@reticlehq/server 2.14.0 → 3.2.0

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

@@ -0,0 +1,247 @@
+import { CaptureLoss, channelsRead, PredicateKind } from '@reticlehq/core';
+import { gapsForAction } from '@reticlehq/engine/evidence/instrumentation-gaps.js';
+import { noteSessionGaps } from '@reticlehq/engine/evidence/gap-ledger.js';
+import { declaresState } from '@reticlehq/engine/question/predicate/predicate-asks.js';
+import { isStateUnwatched } from '@reticlehq/engine/evidence/blind-spots.js';
+import { findContradictions, } from '@reticlehq/engine/disagreement/contradictions.js';
+import { crashedRuleNotes } from '@reticlehq/engine/disagreement/contradiction-folds.js';
+import { declaredExpectations, declaresBodyIndependentChannel, } from '@reticlehq/engine/question/declared.js';
+import { absenceBlindSpotNote, blindSpotsFromState, buildCoverageStatement, restsOnCompleteWindow, Coverage, impeachesCapture, transportGapNote, } from '@reticlehq/engine/evidence/blind-spots.js';
+import { buildHonestyBlock } from '@reticlehq/engine/evidence/honesty.js';
+import { acceptedWriteLabels } from '@reticlehq/engine/evidence/accepted-write.js';
+import { unreadWriteLabels } from '@reticlehq/engine/evidence/unread-outcome.js';
+import { decideVerified } from '@reticlehq/engine/evidence/verified.js';
+import { describeWaitTarget, namedNetIsInFlight } from '@reticlehq/engine/evidence/unsettled.js';
+import { inFlightRequestLabels, repeatedRequestLabels, } from '../act/settle-in-flight.js';
+import { gradeOfPredicate } from './assert-grade.js';
+import { assertSource } from './assert-source.js';
+/**
+ * The honesty verdict for a plain `reticle_assert`.
+ *
+ * This is the single field an agent reads, and it was missing from the most-used verdict path.
+ * `act_and_wait` has always returned it; `reticle_assert` returned a bare `pass: true`.
+ *
+ * Measured on a shipments console: a dispatch answered 202 Accepted, the row rendered "dispatched"
+ * optimistically, an assert taken right after the click returned `pass: true` with no caveat, and the
+ * server reverted the write to "held" 1.2s later. The 202 machinery that exists precisely to report
+ * that as `verified: "unknown"` was never reached, because the tool an agent actually calls did not
+ * consult it. Asserting a moment earlier — while the POST was still open — is the same story with a
+ * different name: `request-never-settled`, also unreported.
+ */
+export async function assertVerdict(session, predicate, pass, 
+/**
+ * What the oracle actually looked at. The only thing this verdict is entitled to point at — see
+ * `assertSource`, which reads the matched element descriptors' own `file:line`.
+ */
+evidence, since, 
+/** Set when the assertion was never evaluated — see engine/src/evidence/verified.ts. */
+inconclusive, 
+/**
+ * Set when the tab went away mid-wait, so the assertion was never OBSERVED. `reticle_assert` and
+ * `reticle_wait_for` reach the same disconnect path as the act tools, and a verdict that blames
+ * the app for a lost connection is no more honest on this route than on that one.
+ */
+observationLost, 
+/**
+ * Set when code changed since the last verdict with nothing declaring what it was for. Decided by
+ * `isChangeUndeclared` at the call site, which is the only place that can reach the intent ledger —
+ * this path takes a session and no `deps`.
+ */
+changeUndeclared) {
+    // Scope caveat, stated because it is a real limitation and not a bug: blind spots are tracked per
+    // SESSION, not per assertion window, so a cross-origin iframe seen once marks every later verdict
+    // in that session partial — including ones about a region it cannot affect. That errs toward
+    // over-warning, which is the correct direction here: the failure this guards against is a green
+    // that implies coverage it never had, and a needless caveat costs the agent a sentence.
+    const spots = blindSpotsFromState(session.blindSpots(), session.runtime);
+    const statement = buildCoverageStatement(spots);
+    const absenceBlindSpot = absenceBlindSpotNote(predicate, spots);
+    // Omitted entirely when coverage is full, so an intact page pays nothing and the field's PRESENCE
+    // is the warning.
+    const coverage = Coverage.PARTIAL === statement.coverage
+        ? {
+            coverage: statement.note ?? Coverage.PARTIAL,
+            coverage_spots: statement.spots.map((sp) => ({ kind: sp.kind, count: sp.count })),
+        }
+        : {};
+    const windowEvents = await session.queryEvents({ since });
+    // Everything before the window, passed as LEARNING material only. A scale error disagrees with a
+    // value the API stated earlier in the session, which an action-scoped window can never contain —
+    // measured live, `observe` over a wide window reported `unit-mismatch` while `assert` on the same
+    // session reported none. Attribution is unchanged: findings still come only from windowEvents.
+    const prior = since > 0 ? (await session.queryEvents({ since: 0 })).filter((e) => e.t < since) : [];
+    // The last act, when it falls inside the window being judged. Without it `duplicate-request` counted
+    // `method + url` across whatever window the caller asked for, so two legitimate separate saves to one
+    // endpoint were reported as a double submit — the instrument accusing the app of something nobody
+    // could show it did. An assert taken over a window that predates the act attributes nothing, and the
+    // rule then stays quiet.
+    const actCursor = session.lastAct.cursor();
+    // The same declaration the act path reads. `reticle_assert` is the other half of the verdict
+    // surface, and an error path declared here deserves the same answer it gets there — a fix that
+    // lived only on the act path would leave the sibling caller broken.
+    const declared = declaredExpectations(predicate);
+    const contradictions = findContradictions(windowEvents, {
+        prior,
+        currentDocumentId: session.currentDocumentId,
+        currentEditEpoch: session.currentEditEpoch,
+        appOrigin: session.url,
+        expectedFailures: declared.netFailures,
+        namedNetUrls: declared.netUrls,
+        renderProved: pass && declared.rendersContent,
+        ...(actCursor !== undefined && actCursor >= since ? { actionSince: actCursor } : {}),
+    });
+    // Only a spot that IMPEACHES the capture downgrades a general verdict. Structural boundaries are
+    // reported as coverage; the narrower absence exception is computed separately above.
+    const impeaching = buildCoverageStatement(spots.filter((sp) => impeachesCapture(sp.kind)));
+    // A gap in the WINDOW, as opposed to a standing limit of the page. Both mean the same thing to the
+    // rule — part of what happened was not seen — so both belong in `blindSpots`, which is the only
+    // input `decideVerified` reads for that.
+    const gap = transportGapNote(windowEvents);
+    /**
+     * The DURABLE half of the same question. `queryEvents` above falls through to the journal once the
+     * ring buffer has evicted, and that ledger refuses writes at its byte ceiling — so a window read
+     * from it after the ceiling was reached is missing whatever the cap turned away. The in-band
+     * marker cannot carry this: it is stamped with a `t`, and any `since` later than that filters it
+     * straight back out, leaving a partial answer that looks exactly like a complete one.
+     *
+     * Called optionally because `Session` is stubbed by cast in a great many suites, and a method
+     * added to it therefore arrives as a runtime `undefined` in files that have nothing to do with
+     * this change — the cost recorded at the top of `fake-session.ts`, four times over.
+     */
+    const ledgerClosed = undefined !== (await session.journalWriteLoss?.());
+    // A consumer rule that crashed belongs here too: the engine ran with fewer rules than it claims,
+    // so part of what happened may simply not have been looked for.
+    const impeachingNotes = [impeaching.note, gap, ...crashedRuleNotes()].filter((n) => n !== undefined);
+    const outcomePending = acceptedWriteLabels(windowEvents);
+    const outcomeUnread = unreadWriteLabels(windowEvents);
+    const stillInFlight = inFlightRequestLabels(windowEvents);
+    const effectiveInconclusive = inconclusive ?? (!pass ? session.preconditionFailure?.() : undefined);
+    /**
+     * Does a green here rest on the window having been COMPLETE?
+     *
+     * Not a refinement of the two losses below — it is what keeps either of them usable. Scarce loss
+     * is recorded for AGE eviction too, so `lostSince(0)` is true on any session past the 60s cutoff,
+     * and assert takes a caller-chosen `since` that is often 0. Impeaching every verdict over a wide
+     * window would make `unknown` the answer to everything, which is the failure this repo has already
+     * paid for once, when `unclean_capture` became the dominant cause of `unknown` in the field. A
+     * POSITIVE assertion that passed FOUND its evidence; things lost elsewhere do not unmake it.
+     */
+    const restsOnComplete = restsOnCompleteWindow(predicate);
+    /**
+     * The buffer evicted scarce evidence from this window.
+     *
+     * assert never consulted the buffer at all, on the reasoning that it "observes an already-open
+     * window" — but eviction happens on push regardless of who opened the window, so
+     * `{ console, absent: true }` returned `yes` over a window whose evidence was gone, which is
+     * absence of evidence read as evidence of absence. The act path needs no `restsOnComplete` guard:
+     * its cursor is the action's own.
+     */
+    const bufferLost = session.lostSince(since) && restsOnComplete;
+    /** The durable ledger refused writes, on a query path that read from it. Same rule, other store. */
+    const ledgerLost = ledgerClosed && restsOnComplete;
+    const decision = decideVerified({
+        pass,
+        // What this claim needs to read, against what the page said it can see -- the protocol's
+        // first clause, and one this implementation could not run until the page started declaring.
+        // Both halves are conditional on purpose: an SDK too old to declare sends nothing, and
+        // treating that silence as an empty set would refuse every claim from every older page.
+        channelsRead: channelsRead(predicate.kind),
+        ...(session.channels === undefined ? {} : { channelsObservable: session.channels }),
+        // So the unread-body remedy can check it applies to THIS page. Threaded rather than
+        // looked up inside decideVerified, which is pure and has no session.
+        ...(session.sdkVersion === undefined ? {} : { sdkVersion: session.sdkVersion }),
+        // Same rule as the act path: the caller named a consequence, so a settlement-only finding must
+        // not override it. A fix that lived on one half of the verdict surface would leave the other
+        // half broken, and this is the tool agents call most.
+        declaredConsequence: predicate.kind !== PredicateKind.SETTLED,
+        ...(declaresBodyIndependentChannel(predicate) ? { independentOfBody: true } : {}),
+        ...(effectiveInconclusive === undefined ? {} : { inconclusive: effectiveInconclusive }),
+        ...(true === observationLost ? { observationLost: true, lastUrl: session.url } : {}),
+        ...(absenceBlindSpot === undefined ? {} : { absenceBlindSpot }),
+        ...(namedNetIsInFlight(predicate, stillInFlight) ? { namedRequestInFlight: true } : {}),
+        honesty: buildHonestyBlock({
+            grade: gradeOfPredicate(predicate),
+            attribution: 'window',
+            truncated: bufferLost,
+            // The durable ledger stopped, and the SAME absence rule applies: a positive assertion that
+            // passed found its evidence, and events missing from the end of a file do not unmake it.
+            ledgerClosed: ledgerLost,
+            coveragePartial: Coverage.PARTIAL === statement.coverage,
+            ...(statement.note === undefined ? {} : { coverageNote: statement.note }),
+            ...(0 === impeachingNotes.length ? {} : { blindSpots: impeachingNotes }),
+            // Which loss, as an enum, beside the prose. Ours before the page's, and the memory one before
+            // the disk one: `verification.uncleanLoss` takes the first, and a window that lost both is
+            // more usefully reported as the eviction, which is the one a caller can still drive around.
+            losses: [
+                ...(bufferLost ? [CaptureLoss.BUFFER_LOSS] : []),
+                ...(ledgerLost ? [CaptureLoss.JOURNAL_LOSS] : []),
+                ...(gap === undefined ? [] : [CaptureLoss.TRANSPORT_GAP]),
+                ...(impeaching.note === undefined ? [] : [CaptureLoss.BLIND_SPOT]),
+            ],
+        }),
+        contradictions,
+        ...(0 === outcomePending.length ? {} : { outcomePending }),
+        ...(outcomeUnread.length > 0 ? { outcomeUnread } : {}),
+        // Same detail the act path supplies: this route reaches UNSETTLED through an absence-derived
+        // contradiction, and "the window closed before the app finished" is no more actionable here.
+        unsettled: {
+            waitedFor: describeWaitTarget(predicate),
+            stillInFlight,
+            repeated: repeatedRequestLabels(windowEvents),
+        },
+    });
+    // The same rule the act path uses, fed by what THIS path knows. An assertion drives nothing, so
+    // only two of the four gates can fire here: a red with no remembered source to point at, and a
+    // state assertion against an app that registers no store.
+    const gaps = gapsForAction({
+        pass,
+        ...(changeUndeclared === undefined ? {} : { changeUndeclared }),
+        source: session.lastAct.source(),
+        stateAsked: declaresState(predicate),
+        stateUnwatched: isStateUnwatched(spots),
+        // What the app DECLARED, so an under-instrumented one is told without having to be asked.
+        hasCapabilities: session.hasCapabilities,
+        // Whether the build TURNED the source stamp off, so a red with no file:line prescribes the
+        // right fix. `false` from the page is the only value that means anything; absent is unknown.
+        ...(false === session.sourceMapping ? { sourceMappingDisabled: true } : {}),
+        domMutated: false,
+        signalsFired: 0,
+    });
+    noteSessionGaps(session, gaps);
+    // The one file:line this verdict is entitled to: its own evidence, or — for a failure with no DOM
+    // clause to point at — the control last driven. Returned so the RESPONSE can echo the same value
+    // the journal keeps; one verdict must never carry two different pointers.
+    const source = assertSource({
+        predicate,
+        evidence,
+        pass,
+        lastActSource: session.lastAct.source(),
+    });
+    return {
+        decision: decision,
+        contradictions,
+        coverage,
+        gaps,
+        verdictEffect: {
+            claim: describeWaitTarget(predicate),
+            verified: decision.verified,
+            ...(source === undefined ? {} : { source }),
+            // The three facts that make a verdict something other than a pass/fail line. All three were
+            // known right here and none of them survived into the durable record, so nothing downstream
+            // could report them however well this moment understood them.
+            //
+            // FALSE, and this is the one value here that is easy to get wrong. This path serves `assert`,
+            // which reads a window that is already open: the claim is made after the action, not before.
+            // Recording it as pre-registered would put the product's own headline property on evidence
+            // that does not have it -- and a claim written afterwards can always be shaped to fit what
+            // happened, which is the whole reason the distinction is worth recording.
+            declaredBeforeActing: false,
+            // The deciding clause, kept. `unknown` alone cannot distinguish an outcome that has not
+            // arrived from a capture that could not be read, and only the first is worth asking about
+            // again -- which is what makes a later answer a CORRECTION rather than a second opinion.
+            reason: decision.verifiedReason,
+            grade: gradeOfPredicate(predicate),
+            couldNotSee: spots.map((spot) => spot.kind),
+        },
+    };
+}

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

@@ -0,0 +1,2 @@
+import type { ToolDef } from './tool-kit.js';
+export declare const BROWSER_TOOLS: ToolDef[];

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

@@ -0,0 +1,115 @@
+import { carryReticleIdentity } from './lease-tools.js';
+import { z } from 'zod';
+import { navigateResult } from './act/navigation/navigate-result.js';
+import { awaitArrival, idsAtTarget, ARRIVAL_TIMEOUT_MS, } from './act/navigation/navigate-arrival.js';
+import { reloadResult } from './act/navigation/reload-result.js';
+import { waitForReconnect, RELOAD_RECONNECT_TIMEOUT_MS, } from '../../portal/session/session-reconnect.js';
+import { ReticleCommand } from '@reticlehq/core';
+import { ReticleTool } from '@reticlehq/core';
+import { asNumber, asString } from '@reticlehq/core';
+import { sessionIdShape, commandOrThrow } from './tool-kit.js';
+import { timeoutMsSchema } from './args/numeric-bounds.js';
+export const BROWSER_TOOLS = [
+    {
+        name: ReticleTool.NAVIGATE,
+        example: { url: '/settings' },
+        description: 'Navigate the connected browser tab to a URL, or reload it in place with { reload: true } (add { hard: true } to bypass the cache). `ok` means the navigation was DISPATCHED — the SDK is torn down by the navigation, so the page itself cannot report on it. The daemon then waits up to `timeout_ms` (default 5000) for the SDK to reconnect: `confirmed:true` with a new `sessionId` means the page arrived and you can act immediately. `confirmed:false` means it did not arrive within that window (reported as `waitedMs`) — the page may be slow, uninstrumented, or not there. A slow SPA can take 30-60s to reattach: raise `timeout_ms` rather than polling reticle_sessions.',
+        inputSchema: {
+            url: z.string().optional().describe('The URL to navigate to. Omit when using reload.'),
+            reload: z
+                .boolean()
+                .optional()
+                .describe('Reload the current page instead of navigating (replaces the former standalone refresh tool).'),
+            hard: z
+                .boolean()
+                .optional()
+                .describe('With reload:true, bypass the browser cache (Cmd+Shift+R). Default: false.'),
+            timeout_ms: timeoutMsSchema
+                .optional()
+                .describe('How long to wait for the page to come back (the SDK reconnecting at the new URL, or under the same id on a reload) before answering confirmed:false. Default 5000. 0 looks once without waiting. An SPA reattaching under HMR has been measured at 30-60s — say so here instead of polling reticle_sessions.'),
+            ...sessionIdShape,
+        },
+        outputSchema: {
+            ok: z.boolean(),
+            url: z.string().optional(),
+            reason: z.string().optional(),
+            // Present on a dispatched navigation: nothing here can see the new document, so arrival is
+            // reported as unconfirmed rather than implied by `ok`. See navigate-result.ts.
+            confirmed: z.boolean().optional(),
+            /** The session the SDK reconnected as, when arrival was confirmed — it is a NEW id. */
+            sessionId: z.string().optional(),
+            /**
+             * On confirmed:false — the budget (ms) that expired without the page coming back. Says which
+             * of "Reticle stopped waiting" and "the page never came back" you are looking at.
+             */
+            waitedMs: z.number().optional(),
+            note: z.string().optional(),
+        },
+        handler: async (deps, args) => {
+            // reload:true is the absorbed reticle_refresh — same command, one fewer advertised tool.
+            if (true === args['reload']) {
+                // The reload branch has its own default, sized for a cold dev-server rebuild; the caller's
+                // budget overrides it for the same reason it overrides the arrival wait below.
+                const timeoutMs = asNumber(args['timeout_ms']) ?? RELOAD_RECONNECT_TIMEOUT_MS;
+                const before = deps.sessions.resolve(asString(args['sessionId']));
+                // The verdict floor moves HERE, before the page goes away. A reload destroys the document,
+                // so every request that failed under the old one belongs to a page that no longer exists —
+                // and a later assert defaulting its window to "the last thing that happened" must not reach
+                // back past this point. Reported from the field as an assertion whose clauses all passed
+                // coming back `contradicted` by hundreds of 500s against resources that were already gone.
+                before.lastAct.markNavigated(before.elapsed());
+                await commandOrThrow(deps, asString(args['sessionId']), ReticleCommand.REFRESH, {
+                    hard: true === args['hard'],
+                });
+                // WAIT for the page to come back, rather than telling the agent to. The id survives the
+                // reload, but the seconds between dispatch and the new HELLO are seconds in which every call
+                // lands in the old, disconnected session — measured as reticle_run failing 5 of 5 on a page
+                // that was healthy immediately afterwards. Returns on the first poll in the common case.
+                const back = await waitForReconnect({
+                    current: () => deps.sessions.get(before.id),
+                    previous: before,
+                    timeoutMs,
+                    now: deps.now,
+                    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+                });
+                // Not a bare `{ ok: true }`. The URL branch below already discloses that `ok` means
+                // DISPATCHED — the reload branch had identical semantics and said nothing, on the path most
+                // likely to need it. See reload-result.
+                return reloadResult(back, timeoutMs);
+            }
+            const requested = asString(args['url']);
+            if (requested === undefined || 0 === requested.length)
+                return { ok: false, reason: 'url required' };
+            // Record navigate as an action. Its window is usually empty (the page unloads and the SDK
+            // reconnects), but the action record itself — "navigated to X" — is the causal fact worth keeping.
+            const session = deps.sessions.resolve(asString(args['sessionId']));
+            // A leased tab is addressed by a URL param, so navigating away from it used to strand the
+            // lease — see carryReticleIdentity. A tab that claims no identity is untouched.
+            const url = carryReticleIdentity(session.url, requested);
+            // Sampled BEFORE dispatch, because that is the only moment it can be known. A session already
+            // sitting on the target is not evidence that THIS navigation arrived — and the arrival scan,
+            // which reads whatever is at the target afterwards, cannot tell the two apart on its own.
+            const priorIds = idsAtTarget(deps.sessions, url);
+            session.beginAction(ReticleTool.NAVIGATE, { url });
+            // Same floor as the reload path above, for the same reason: going to a new URL replaces the
+            // document just as thoroughly. `beginAction` attributes events to this action; it does not move
+            // the window a later assert judges over, and those are two different jobs.
+            session.lastAct.markNavigated(session.elapsed());
+            try {
+                const result = (await commandOrThrow(deps, asString(args['sessionId']), ReticleCommand.NAVIGATE, { url }));
+                // `ok` is the browser accepting the instruction, not the page arriving — see navigate-result.
+                // The daemon is the only party that CAN see arrival (the SDK reconnects to it), so it looks,
+                // for as long as the caller said to, instead of telling the agent to go poll
+                // reticle_sessions itself. A refusal skips the wait: there is nothing to wait FOR.
+                const timeoutMs = asNumber(args['timeout_ms']) ?? ARRIVAL_TIMEOUT_MS;
+                const arrival = true === result.ok
+                    ? await awaitArrival(deps.sessions, url, { navigatedId: session.id, priorIds }, timeoutMs)
+                    : null;
+                return navigateResult(result, arrival, timeoutMs);
+            }
+            finally {
+                session.finishAction();
+            }
+        },
+    },
+];

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

@@ -0,0 +1,2 @@
+import type { ToolDef } from './tool-kit.js';
+export declare const CONTRACT_TOOLS: ToolDef[];

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

@@ -0,0 +1,112 @@
+import { z } from 'zod';
+import { sessionRoot } from '../../memory/project/session-root.js';
+import { CapabilitiesSchema, ContractReadError, FROM_DISK_ARG, ReticleCommand, } from '@reticlehq/core';
+import { ReticleTool } from '@reticlehq/core';
+import { capabilityAbsences } from './gaps/capability-absences.js';
+import { asString } from '@reticlehq/core';
+import { sessionIdShape, commandOrThrow } from './tool-kit.js';
+import { reticleDirPaths, readContract, writeContract } from '../../memory/project/dir/reticle-dir.js';
+/**
+ * The capability-contract tools. `reticle_capabilities` reads the live session, or the
+ * git-checked `.reticle/contract.json` when `{ fromDisk:true }`; `reticle_contract_save` persists the
+ * live registry to that file (pretty-printed, stable key order — diffable in PRs).
+ */
+/**
+ * Refuse to persist one project's surface into another project's repo.
+ *
+ * `writeContract` writes to the DAEMON's `.reticle/`, which is the directory the daemon was started
+ * in — not the session's project. A daemon started above several apps therefore saves app A's
+ * testids into app B's checkout, reports `saved: true`, and hands back a path that looks right. A
+ * contract is git-checked and diffable, so that is a change somebody commits.
+ *
+ * Refuse rather than redirect: a session advertises a projectId, not a project DIRECTORY, so there
+ * is no honest way to work out where the correct `.reticle/` lives. Naming both ids and stopping is
+ * the whole of what can be said truthfully.
+ *
+ * Silence is not a mismatch. An unstamped build carries no projectId, and a daemon above an
+ * uninitialised directory has none either; neither is evidence of two projects.
+ */
+function assertSameProject(deps, sessionId) {
+    const mine = deps.projectId;
+    const theirs = deps.sessions.resolve(sessionId).projectId;
+    if (mine === undefined || theirs === undefined || mine === theirs)
+        return;
+    throw new Error(`refusing to save: this session belongs to project '${theirs}', but this daemon writes to ` +
+        `project '${mine}' (.reticle/ in the directory it was started in). Saving would put one ` +
+        "app's testable surface into another app's git-checked contract. Run a daemon from " +
+        `'${theirs}'s own directory and save there.`);
+}
+export const CONTRACT_TOOLS = [
+    {
+        name: ReticleTool.CAPABILITIES,
+        description: 'The app-advertised testable surface (reticle.describe): testids, signals, stores, and named flows. Call this first to learn what to assert on without reading source. Pass { fromDisk:true } to read the git-checked .reticle/contract.json instead of the live session (a fresh agent can learn the surface with no browser attached).',
+        // Every core tool carries one, so an agent reading the surface never has to guess the shape.
+        // `fromDisk` is the example deliberately: it is the call that works with nothing attached, which
+        // is the state a fresh agent is actually in when it first reads this list.
+        example: { [FROM_DISK_ARG]: true },
+        inputSchema: { [FROM_DISK_ARG]: z.boolean().optional(), ...sessionIdShape },
+        outputSchema: {
+            testids: z.array(z.string()),
+            signals: z.array(z.string()),
+            stores: z.array(z.string()),
+            flows: z.array(z.object({ name: z.string(), steps: z.array(z.string()) })),
+            source: z
+                .string()
+                .describe('live = real-time from the browser; disk = last saved contract.json'),
+            // fromDisk carries when the contract was generated; both paths carry the app's declared governance
+            // (owner/safety/scope) when present. Undeclared, they were stripped on a validating profile — a
+            // governance-gated app lost its policy block, and disk reads lost their freshness stamp.
+            generatedAt: z.number().optional(),
+            governance: z.unknown().optional(),
+            // Only on a live read, and only when the page declared something switched off. A disk read has
+            // no session to ask, and an empty list on every healthy call is a line agents learn to skip.
+            cannot: z
+                .array(z.object({ capability: z.string(), meaning: z.string(), remedy: z.string() }))
+                .optional()
+                .describe('what this session cannot observe, why it matters, and how to change it'),
+        },
+        handler: async (deps, args) => {
+            if (true === args[FROM_DISK_ARG]) {
+                const r = await readContract(deps.fs, sessionRoot(deps, asString(args['sessionId'])));
+                if (!r.ok)
+                    throw new Error(r.reason === ContractReadError.MISSING
+                        ? 'no .reticle/contract.json on disk — run reticle_contract_save first (or omit fromDisk to read the live session)'
+                        : '.reticle/contract.json is malformed — fix or regenerate it with reticle_contract_save');
+                return { ...r.capabilities, source: 'disk', generatedAt: r.generatedAt };
+            }
+            const caps = await commandOrThrow(deps, asString(args['sessionId']), ReticleCommand.CAPABILITIES, {});
+            // The surface above says what the app OFFERS. This says what the instrumentation cannot watch,
+            // so a plan is not built around evidence this session was never going to have.
+            const cannot = capabilityAbsences(deps.sessions.resolve(asString(args['sessionId'])));
+            return {
+                ...caps,
+                source: 'live',
+                ...(0 === cannot.length ? {} : { cannot }),
+            };
+        },
+    },
+    {
+        name: ReticleTool.CONTRACT_SAVE,
+        description: "Persist the app's live capability registry (reticle.describe) to .reticle/contract.json — git-checked, diffable, readable by a fresh agent via reticle_capabilities({ fromDisk:true }). Returns { path, counts }.",
+        inputSchema: { ...sessionIdShape },
+        outputSchema: {
+            saved: z.boolean(),
+            path: z.string(),
+            testidCount: z.number(),
+            signalCount: z.number(),
+        },
+        handler: async (deps, args) => {
+            const res = await commandOrThrow(deps, asString(args['sessionId']), ReticleCommand.CAPABILITIES, {});
+            const caps = CapabilitiesSchema.parse(res);
+            assertSameProject(deps, asString(args['sessionId']));
+            const root = sessionRoot(deps, asString(args['sessionId']));
+            await writeContract(deps.fs, root, caps, deps.now);
+            return {
+                saved: true,
+                path: reticleDirPaths(root).contract,
+                testidCount: caps.testids.length,
+                signalCount: caps.signals.length,
+            };
+        },
+    },
+];

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

@@ -0,0 +1,18 @@
+import type { ToolDef } from './tool-kit.js';
+interface Control {
+    ref: string;
+    label: string;
+}
+/** Parse the interactive snapshot into {ref,label} controls, preserving document order. */
+export declare function parseControls(tree: string): Control[];
+/**
+ * Build the coverage tool over the dispatchable tool table.
+ *
+ * The table arrives as a thunk rather than an import: `tools.ts` assembles it FROM this module, so
+ * importing it back would close a cycle whose failure mode is a load-order-dependent crash rather
+ * than an error anyone sees while writing it. The thunk is called inside the handler, long after the
+ * table exists. It carries the merged names — the ones `reticle_run` will actually accept — because
+ * a tool that merged into a parent is not something an agent can call or a maintainer can cut.
+ */
+export declare function buildCoverageTools(toolNames: () => readonly string[]): ToolDef[];
+export {};