@reticlehq/server 2.10.0 → 2.12.0

package/dist/honesty/observability.d.ts

@@ -0,0 +1,37 @@
+import type { InstrumentationGap } from '@reticlehq/core';
+/**
+ * Of the controls this session drove, how many could Reticle fully observe?
+ *
+ * The first honest denominator this product has ever had. `reticle_verify{action:"coverage"}`
+ * already answers "which controls did you not drive"; this answers the question underneath it —
+ * *of the ones you did drive, how many could the app actually answer for?* A high untouched-count is
+ * work remaining for the agent. A low observability is work remaining in the APP, and no amount of
+ * driving closes it.
+ *
+ * ## Two things it deliberately refuses to do
+ *
+ * **It does not report a percentage for an empty run.** 0/0 rendered as 100% is the most flattering
+ * possible reading of no evidence at all, and a coverage number that starts perfect is one nobody
+ * believes the first time it drops.
+ *
+ * **It does not count app-level gaps against a control.** An unregistered store or an unsignalled
+ * route is missing from the application, not from a button. Attributing it to whichever control
+ * happened to be driven would put the number on the wrong thing and make it move for reasons the
+ * agent cannot act on. Those gaps are reported alongside, not divided into.
+ */
+export interface Observability {
+    /** Distinct controls driven this session. */
+    driven: number;
+    /** How many of them Reticle could fully observe. */
+    observable: number;
+    /** Rounded percentage. OMITTED when nothing was driven — see above. */
+    percent?: number;
+}
+export declare function observabilityOf(drivenRefs: Iterable<string>, gaps: readonly InstrumentationGap[]): Observability;
+export interface CoverageRegression {
+    was: number;
+    now: number;
+}
+export declare function coverageRegressed(best: {
+    percent: number;
+} | undefined, current: Observability): CoverageRegression | undefined;

package/dist/honesty/observability.js

@@ -0,0 +1,40 @@
+export function observabilityOf(
+// Iterable, not an array: the session holds these as a Set, and making the caller spread it would
+// be a conversion that exists only to satisfy a signature.
+drivenRefs, gaps) {
+    const driven = new Set(drivenRefs);
+    const impaired = new Set();
+    for (const gap of gaps) {
+        // App-level gaps carry no ref, and a gap on a control this session never drove is about some
+        // earlier route — neither belongs in a ratio over what WAS driven.
+        if (gap.ref !== undefined && driven.has(gap.ref))
+            impaired.add(gap.ref);
+    }
+    const observable = driven.size - impaired.size;
+    if (0 === driven.size)
+        return { driven: 0, observable: 0 };
+    return { driven: driven.size, observable, percent: Math.round((observable / driven.size) * 100) };
+}
+/**
+ * The floor under the number, shipped with it rather than after it.
+ *
+ * A coverage figure with no downgrade check is a figure that gets gamed, and we would be the ones
+ * teaching agents to game it: the cheapest way to stop a gap firing is to stop asserting the thing
+ * that revealed it. The same reasoning already runs for flow assertions in `assertion-tiers-store`,
+ * where a flow that passes more weakly than it used to is a finding rather than a pass.
+ *
+ * Returns undefined — not a false — when there is nothing honest to compare. A first run has no
+ * best to fall from, and a run that drove almost nothing is evidence of a short session rather than
+ * of a regression.
+ */
+/** Below this, a run is too small for its ratio to mean anything. */
+const MIN_DRIVEN_TO_COMPARE = 3;
+export function coverageRegressed(best, current) {
+    if (best === undefined)
+        return undefined;
+    if (current.percent === undefined)
+        return undefined;
+    if (current.driven < MIN_DRIVEN_TO_COMPARE)
+        return undefined;
+    return current.percent < best.percent ? { was: best.percent, now: current.percent } : undefined;
+}

package/dist/honesty/tool-hit-rate.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Which tools this session called, and how reachable each one was.
+ *
+ * The generalisation of the capture ledger: it recorded a short list of read tools to answer one
+ * feature's disproof, and the question that followed is the same question asked of the whole table —
+ * most of the surface has never been observed being called at all, and a decision about what to cut
+ * or consolidate is about to be made. This is the instrument for that decision, and nothing else.
+ *
+ * ## Why the count alone is not enough
+ *
+ * A tool that goes uncalled because nobody was told it exists and a tool that goes uncalled because
+ * nobody wants it look identical in a call count. They are opposite conclusions. So every count is
+ * reported beside the tool's REACHABILITY — advertised on the default surface, advertised only on
+ * the extended one, or reachable solely by naming it to `reticle_run` — and the interesting cell is
+ * the one where an agent found a run-only tool anyway.
+ *
+ * ## The tiers are derived, never restated
+ *
+ * `tierOfTool` reads `CORE_TOOL_NAMES` and `EXTENDED_TOOL_NAMES` directly. A tool promoted or
+ * demoted between surfaces changes tier here with nothing edited. A local copy of either list would
+ * go stale on the first move and would then be wrong about the exact axis this exists to measure —
+ * and it would be wrong silently, in a report used to justify deleting things.
+ *
+ * ## What these numbers do NOT establish
+ *
+ *  - **One session is not a hit rate.** This is evidence about ONE run by ONE agent against ONE app.
+ *    A hit rate is a distribution over many sessions; a single session quoted as one is an anecdote
+ *    with a denominator drawn on it.
+ *  - **Never-called is not useless.** A tool one team reaches for once a month in an emergency and a
+ *    tool nobody has ever called are the same zero here. Frequency alone cannot separate them, so a
+ *    cut decided on frequency alone will delete the wrong things.
+ *  - **Absent is not zero.** A session with no ledger reports `observed: false`. It has not
+ *    established that no tools were called; it has established that nothing was watching.
+ *  - The tools that ran BEFORE this instrument existed in the process, or against a session this
+ *    daemon adopted after the fact, are simply missing rather than counted low.
+ */
+/** How an agent could have reached a tool. Derived from the surface sets — see above. */
+export declare const ToolTier: {
+    /** Advertised directly on the surface every user gets. */
+    readonly DEFAULT: "default";
+    /** Advertised only when the full schema-carrying surface is switched on. */
+    readonly EXTENDED: "extended";
+    /** Advertised nowhere: reachable only by naming it to `reticle_run`. */
+    readonly RUN_ONLY: "run-only";
+};
+export type ToolTier = (typeof ToolTier)[keyof typeof ToolTier];
+/** Which surface would have put this tool in front of an agent, read off that surface's own set. */
+export declare function tierOfTool(tool: string): ToolTier;
+/** How many tools fell in each tier on one side of the called/never-called split. */
+export interface TierCounts {
+    default: number;
+    extended: number;
+    runOnly: number;
+}
+export interface ToolHitRate {
+    /** False when this session carries no ledger — "not watched", never "nothing was called". */
+    observed: boolean;
+    /** The four-plus-two cells: every tier, called and never-called. Omitted when not observed. */
+    cells?: {
+        called: TierCounts;
+        neverCalled: TierCounts;
+    };
+    /** Each tool called this session, most-called first. */
+    called?: readonly {
+        tool: string;
+        tier: ToolTier;
+        calls: number;
+    }[];
+    /** Each tool in the table this session never called, by name. */
+    neverCalled?: readonly {
+        tool: string;
+        tier: ToolTier;
+    }[];
+}
+/**
+ * Cross one session's per-tool counts with the tool table.
+ *
+ * `allTools` is the DISPATCHABLE table — the names `reticle_run` will accept — passed in rather than
+ * imported, because the table is assembled in the module that owns this tool and importing it back
+ * would close a cycle. A tool counted but absent from the table still appears, so a name the table
+ * lost is visible rather than dropped.
+ */
+export declare function foldToolHitRate(input: {
+    calls: ReadonlyMap<string, number> | undefined;
+    allTools: readonly string[];
+}): ToolHitRate;

package/dist/honesty/tool-hit-rate.js

@@ -0,0 +1,90 @@
+import { CORE_TOOL_NAMES, EXTENDED_TOOL_NAMES } from '../tools/tool-surface.js';
+/**
+ * Which tools this session called, and how reachable each one was.
+ *
+ * The generalisation of the capture ledger: it recorded a short list of read tools to answer one
+ * feature's disproof, and the question that followed is the same question asked of the whole table —
+ * most of the surface has never been observed being called at all, and a decision about what to cut
+ * or consolidate is about to be made. This is the instrument for that decision, and nothing else.
+ *
+ * ## Why the count alone is not enough
+ *
+ * A tool that goes uncalled because nobody was told it exists and a tool that goes uncalled because
+ * nobody wants it look identical in a call count. They are opposite conclusions. So every count is
+ * reported beside the tool's REACHABILITY — advertised on the default surface, advertised only on
+ * the extended one, or reachable solely by naming it to `reticle_run` — and the interesting cell is
+ * the one where an agent found a run-only tool anyway.
+ *
+ * ## The tiers are derived, never restated
+ *
+ * `tierOfTool` reads `CORE_TOOL_NAMES` and `EXTENDED_TOOL_NAMES` directly. A tool promoted or
+ * demoted between surfaces changes tier here with nothing edited. A local copy of either list would
+ * go stale on the first move and would then be wrong about the exact axis this exists to measure —
+ * and it would be wrong silently, in a report used to justify deleting things.
+ *
+ * ## What these numbers do NOT establish
+ *
+ *  - **One session is not a hit rate.** This is evidence about ONE run by ONE agent against ONE app.
+ *    A hit rate is a distribution over many sessions; a single session quoted as one is an anecdote
+ *    with a denominator drawn on it.
+ *  - **Never-called is not useless.** A tool one team reaches for once a month in an emergency and a
+ *    tool nobody has ever called are the same zero here. Frequency alone cannot separate them, so a
+ *    cut decided on frequency alone will delete the wrong things.
+ *  - **Absent is not zero.** A session with no ledger reports `observed: false`. It has not
+ *    established that no tools were called; it has established that nothing was watching.
+ *  - The tools that ran BEFORE this instrument existed in the process, or against a session this
+ *    daemon adopted after the fact, are simply missing rather than counted low.
+ */
+/** How an agent could have reached a tool. Derived from the surface sets — see above. */
+export const ToolTier = {
+    /** Advertised directly on the surface every user gets. */
+    DEFAULT: 'default',
+    /** Advertised only when the full schema-carrying surface is switched on. */
+    EXTENDED: 'extended',
+    /** Advertised nowhere: reachable only by naming it to `reticle_run`. */
+    RUN_ONLY: 'run-only',
+};
+/** Which surface would have put this tool in front of an agent, read off that surface's own set. */
+export function tierOfTool(tool) {
+    if (CORE_TOOL_NAMES.has(tool))
+        return ToolTier.DEFAULT;
+    if (EXTENDED_TOOL_NAMES.has(tool))
+        return ToolTier.EXTENDED;
+    return ToolTier.RUN_ONLY;
+}
+function tally(tools) {
+    return {
+        default: tools.filter((tier) => ToolTier.DEFAULT === tier).length,
+        extended: tools.filter((tier) => ToolTier.EXTENDED === tier).length,
+        runOnly: tools.filter((tier) => ToolTier.RUN_ONLY === tier).length,
+    };
+}
+/**
+ * Cross one session's per-tool counts with the tool table.
+ *
+ * `allTools` is the DISPATCHABLE table — the names `reticle_run` will accept — passed in rather than
+ * imported, because the table is assembled in the module that owns this tool and importing it back
+ * would close a cycle. A tool counted but absent from the table still appears, so a name the table
+ * lost is visible rather than dropped.
+ */
+export function foldToolHitRate(input) {
+    const { calls } = input;
+    if (calls === undefined)
+        return { observed: false };
+    const called = [...calls]
+        .map(([tool, count]) => ({ tool, tier: tierOfTool(tool), calls: count }))
+        .sort((a, b) => b.calls - a.calls || a.tool.localeCompare(b.tool));
+    const neverCalled = input.allTools
+        .filter((tool) => !calls.has(tool))
+        .map((tool) => ({ tool, tier: tierOfTool(tool) }))
+        .sort((a, b) => a.tool.localeCompare(b.tool));
+    return {
+        observed: true,
+        cells: {
+            called: tally(called.map((entry) => entry.tier)),
+            neverCalled: tally(neverCalled.map((entry) => entry.tier)),
+        },
+        called,
+        neverCalled,
+    };
+}

package/dist/honesty/undeclared-change.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Is this verdict being drawn over code nobody said anything about?
+ *
+ * Declaring intent is opt-in, and nothing has ever noticed that a change landed and nobody said what
+ * it was supposed to make true. That is the moment it matters: a change with no declared intent can
+ * only be verified against itself, which is the definition of a false green.
+ *
+ * ## Why this fires on EVERY verdict, not once per change
+ *
+ * The house rule is that a gap nobody hit is a backlog, and a backlog reported as a finding is how
+ * an agent learns to stop reading findings. This clears that bar on the same test every other
+ * instrumentation gap clears it on: **did the absence make THIS verdict weaker?** An unwatched store
+ * weakens every state assertion made over it, not merely the first, so it is reported on every one.
+ * An undeclared change is the same shape — while nothing says what the edit was for, each verdict
+ * drawn after it is checked against nothing but itself, and that is true of the fifth one exactly as
+ * it was of the first. Reporting it once and then falling silent would leave four verdicts carrying
+ * a weakness they no longer disclose, which is the failure mode this whole surface exists to prevent.
+ *
+ * It is also not a backlog, because it is not a survey of the project: it is answered from what this
+ * session observed (an epoch that moved) about the verdict being returned right now, and it is
+ * closed by one call the agent can make immediately. A finding that stays open only because the
+ * agent has not made that call is a finding about the current verdict, not a chore.
+ *
+ * ## The silences, and why each one is required
+ *
+ *  - **An edit was actually OBSERVED.** The epoch degrades to `NO_EDITS_OBSERVED` outside Vite, and
+ *    that means "no edits observed", never "no edits happened" — a finding built on an absence
+ *    Reticle cannot see would be a fabrication.
+ *  - **The ledger holds nothing undischarged.** An open intent IS the declaration; silence is the
+ *    correct response to it, and declaring one is what turns this off from the next verdict on.
+ *
+ * ## Why "covers the work" is answered as "anything open at all"
+ *
+ * The tempting answer is to match the intent's `surface` against the files that changed. Reticle
+ * cannot do that honestly: it observes that an epoch advanced, not WHAT advanced — the hot-update
+ * channel reports a counter, not a diff — so any file-level matching would be inference dressed as a
+ * fact, and it would fire on an agent that had declared its intent perfectly well. Over-reporting on
+ * a correct agent is the direction of error that trains it to stop reading findings.
+ *
+ * So the question asked is the coarse one, and it is asked honestly: has the agent declared anything
+ * that is still outstanding? If it has, it is working to a stated purpose and this stays quiet.
+ */
+/**
+ * `openIntents` is a thunk rather than a list because reading the ledger touches disk, and the epoch
+ * check answers without it for every page that never reported a hot update — which is most of them.
+ * Once an edit HAS been observed the read happens per verdict, and that is the intended cost: the
+ * ledger is the only thing that can end it, so it has to be re-asked each time.
+ */
+export declare function isChangeUndeclared(
+/** The epoch the session is under now. Undefined when the page never stamped one. */
+currentEpoch: number | undefined, openIntents: () => Promise<readonly unknown[]>): Promise<boolean>;

package/dist/honesty/undeclared-change.js

@@ -0,0 +1,56 @@
+import { NO_EDITS_OBSERVED } from '@reticlehq/core';
+/**
+ * Is this verdict being drawn over code nobody said anything about?
+ *
+ * Declaring intent is opt-in, and nothing has ever noticed that a change landed and nobody said what
+ * it was supposed to make true. That is the moment it matters: a change with no declared intent can
+ * only be verified against itself, which is the definition of a false green.
+ *
+ * ## Why this fires on EVERY verdict, not once per change
+ *
+ * The house rule is that a gap nobody hit is a backlog, and a backlog reported as a finding is how
+ * an agent learns to stop reading findings. This clears that bar on the same test every other
+ * instrumentation gap clears it on: **did the absence make THIS verdict weaker?** An unwatched store
+ * weakens every state assertion made over it, not merely the first, so it is reported on every one.
+ * An undeclared change is the same shape — while nothing says what the edit was for, each verdict
+ * drawn after it is checked against nothing but itself, and that is true of the fifth one exactly as
+ * it was of the first. Reporting it once and then falling silent would leave four verdicts carrying
+ * a weakness they no longer disclose, which is the failure mode this whole surface exists to prevent.
+ *
+ * It is also not a backlog, because it is not a survey of the project: it is answered from what this
+ * session observed (an epoch that moved) about the verdict being returned right now, and it is
+ * closed by one call the agent can make immediately. A finding that stays open only because the
+ * agent has not made that call is a finding about the current verdict, not a chore.
+ *
+ * ## The silences, and why each one is required
+ *
+ *  - **An edit was actually OBSERVED.** The epoch degrades to `NO_EDITS_OBSERVED` outside Vite, and
+ *    that means "no edits observed", never "no edits happened" — a finding built on an absence
+ *    Reticle cannot see would be a fabrication.
+ *  - **The ledger holds nothing undischarged.** An open intent IS the declaration; silence is the
+ *    correct response to it, and declaring one is what turns this off from the next verdict on.
+ *
+ * ## Why "covers the work" is answered as "anything open at all"
+ *
+ * The tempting answer is to match the intent's `surface` against the files that changed. Reticle
+ * cannot do that honestly: it observes that an epoch advanced, not WHAT advanced — the hot-update
+ * channel reports a counter, not a diff — so any file-level matching would be inference dressed as a
+ * fact, and it would fire on an agent that had declared its intent perfectly well. Over-reporting on
+ * a correct agent is the direction of error that trains it to stop reading findings.
+ *
+ * So the question asked is the coarse one, and it is asked honestly: has the agent declared anything
+ * that is still outstanding? If it has, it is working to a stated purpose and this stays quiet.
+ */
+/**
+ * `openIntents` is a thunk rather than a list because reading the ledger touches disk, and the epoch
+ * check answers without it for every page that never reported a hot update — which is most of them.
+ * Once an edit HAS been observed the read happens per verdict, and that is the intended cost: the
+ * ledger is the only thing that can end it, so it has to be re-asked each time.
+ */
+export async function isChangeUndeclared(
+/** The epoch the session is under now. Undefined when the page never stamped one. */
+currentEpoch, openIntents) {
+    if (undefined === currentEpoch || NO_EDITS_OBSERVED === currentEpoch)
+        return false;
+    return 0 === (await openIntents()).length;
+}

package/dist/honesty/verified.d.ts

@@ -76,6 +76,21 @@ interface VerifiedInputs {
      * Empty means nothing went unread.
      */
     outcomeUnread?: readonly string[];
+    /**
+     * The declared consequence that held does not depend on the response body — an exact string
+     * rendered, a store path, a signal. See `declaresBodyIndependentChannel`.
+     *
+     * The unread-body clause exists for the case where the body is the ONLY channel that could have
+     * contradicted the screen (a 200 with batch/GraphQL errors inside). When a body-independent
+     * declaration held, that is no longer true, and grading `unknown` costs a real verdict. The unread
+     * labels still ride out in `because`, the way absence-derived contradictions still ride out in
+     * `contradictions`.
+     *
+     * Narrow: it does not soften a 202, an observed contradiction, a dirty capture, or a net-only
+     * declaration. `declaredConsequence` alone is not enough — a `{ kind: "net", status: 200 }` is a
+     * declaration whose remaining channel IS the body.
+     */
+    independentOfBody?: boolean;
     /**
      * What the wait was for and what the window held when it ended — read ONLY by the two clauses that
      * answer UNSETTLED, which is the commonest reason a verdict comes back `unknown` and was also the

package/dist/honesty/verified.js

@@ -31,6 +31,24 @@ export function decideVerified(inputs) {
                 'to repeat',
         };
     }
+    // ABOVE the failure clause, for the third time and the same reason: absence is not evidence.
+    //
+    // Omitting `until` waits for the page to SETTLE. Nobody declared a consequence, so a settle that
+    // times out says "the page was still busy when I stopped looking" — the definition of an
+    // absence-derived finding. The failure clause below took it at face value and returned
+    // `verified: "no"` with `because: 'the declared consequence did not hold'`, naming a consequence
+    // that does not exist. Measured on the hard fixture, whose push updates mean it never goes idle:
+    // a healthy pagination click was graded NO. Any app with polling or a live feed gets accused of a
+    // defect for being alive, which is the false NEGATIVE the ABSENCE_DERIVED doctrine exists to stop.
+    if (false === pass && false === inputs.declaredConsequence) {
+        return {
+            verified: Verified.UNKNOWN,
+            verifiedReason: VerifiedReason.UNSETTLED,
+            because: 'no consequence was declared, so this only waited for the page to go idle and it never ' +
+                'did — that is a statement about when Reticle stopped looking, not about the app. Pass ' +
+                '`until` naming what the action should cause (a signal, a request, a route, or store state)',
+        };
+    }
     // A failed assertion is the most actionable fact there is; it leads — including over
     // `alreadyTrue`, because a condition that held before AND fails now is a real regression.
     if (false === pass) {
@@ -82,6 +100,27 @@ export function decideVerified(inputs) {
         inputs.unsettled !== undefined &&
         !openWrite &&
         contradictions.every((c) => c.kind === ContradictionKind.REQUEST_NEVER_SETTLED);
+    // `signal-without-consequence` gets its own sentence, because the generic one is FALSE for it.
+    //
+    // That sentence says the window "closed before the app finished" and then explains that a poll or
+    // a timer kept the page busy. Nothing kept this page busy — nothing happened at all, which is the
+    // entire finding. Measured on the bench fixture: the correct UNKNOWN arrived wearing an
+    // explanation that told the agent to wait longer or assert something else, when the fact to act on
+    // was that the app announced a consequence it did not deliver. A right verdict with a wrong reason
+    // sends an agent to the wrong place, which costs as much as the wrong verdict did.
+    const signalOnly = contradictions.length > 0 &&
+        contradictions.every((c) => c.kind === ContradictionKind.SIGNAL_WITHOUT_CONSEQUENCE);
+    if (signalOnly) {
+        return {
+            verified: Verified.UNKNOWN,
+            verifiedReason: VerifiedReason.EVIDENCE_INCOMPLETE,
+            because: 'the app fired the signal you waited for and NOTHING else moved — no DOM, no store, no ' +
+                'route, no request — so the only evidence is the app saying so. A signal emitted from the ' +
+                'value the app was ASKED for, rather than the one it committed, looks exactly like this. ' +
+                'Check the consequence directly (reticle_snapshot for what rendered, reticle_state for what ' +
+                'the store holds) before trusting it',
+        };
+    }
     if (contradictions.length > 0 && !settlementOnly) {
         const kinds = contradictions.map((c) => c.kind).join(', ');
         return {
@@ -142,7 +181,21 @@ export function decideVerified(inputs) {
     // Gated on `true === settled` rather than on a caller's say-so. A call that returned before the app
     // stopped moving has not earned this, whatever it declared — which is what stops `no-fault` from
     // becoming the green-forever button an always-available "nothing was wrong" would be.
-    if (honesty.grade === HonestyGrade.NONE) {
+    // Two ways to have proved nothing, and only one of them used to be caught. Grade NONE is the
+    // engine's own reading — no signal, no request, no state change, nothing pinned. An explicit
+    // `declaredConsequence: false` is the CALLER saying it asserted nothing, which `act_and_wait`
+    // reports whenever `until` is omitted (an omitted `until` becomes `{kind:"settled"}` — a
+    // sleep-replacement, not an assertion).
+    //
+    // Grading alone missed the second case, because a click that merely moves the DOM lifts the grade
+    // to PRESENCE and walks past this branch into a full green. Measured live: clicking a submit
+    // button, and an inert text input, with no `until` both returned `verified:"yes"` /
+    // `verifiedReason:"proved"`. The claim it printed — "assertion held at presence grade" — was true
+    // about a grade and false about an assertion, because there was no assertion.
+    //
+    // It compounds: `reticle_context` persists proven claims, so an undeclared green becomes
+    // established fact for the agent that re-enters after a compaction.
+    if (honesty.grade === HonestyGrade.NONE || false === inputs.declaredConsequence) {
         if (true === settled) {
             return {
                 verified: Verified.NO_FAULT,
@@ -178,7 +231,15 @@ export function decideVerified(inputs) {
     //
     // UNKNOWN, not NO: nothing is known to have failed. The remedy is in the sentence, because an
     // agent that cannot act on a caveat will learn to skip it.
-    if (outcomeUnread !== undefined && outcomeUnread.length > 0) {
+    //
+    // Skipped when the caller declared a consequence that does not depend on the body and it held.
+    // The clause was written for the body being the ONLY remaining channel; a unique row on screen, a
+    // store path, or a signal that held is a different channel, and grading unknown there cost a real
+    // verdict (a 201 plus the exact message text, agent went to enable capture instead of finishing).
+    // The unread write still rides out in `because`. A net-only declaration does not skip: then the
+    // body is still the remaining channel.
+    const unreadHeldIndependently = declaredHeld && true === inputs.independentOfBody;
+    if (outcomeUnread !== undefined && outcomeUnread.length > 0 && !unreadHeldIndependently) {
         return {
             verified: Verified.UNKNOWN,
             verifiedReason: VerifiedReason.OUTCOME_UNREAD,
@@ -214,11 +275,14 @@ export function decideVerified(inputs) {
     const notIdle = false === settled
         ? ', though the page never went idle — this rests on the consequence you declared, not on the page going quiet'
         : '';
+    const unreadCaveat = unreadHeldIndependently && outcomeUnread !== undefined && outcomeUnread.length > 0
+        ? `, though a write returned 2xx with a response body that was never recorded (${outcomeUnread.join('; ')}) — a 200 describes the transport, not the result`
+        : '';
     return {
         verified: Verified.YES,
         verifiedReason: VerifiedReason.PROVED,
         because: true === honesty.coverage?.partial
-            ? `assertion held at ${honesty.grade} grade with no channel disagreeing, but coverage was PARTIAL — see \`coverage\` for what went unobserved${notIdle}`
-            : `assertion held at ${honesty.grade} grade over a clean capture with no channel disagreeing${notIdle}`,
+            ? `assertion held at ${honesty.grade} grade with no channel disagreeing, but coverage was PARTIAL — see \`coverage\` for what went unobserved${notIdle}${unreadCaveat}`
+            : `assertion held at ${honesty.grade} grade over a clean capture with no channel disagreeing${notIdle}${unreadCaveat}`,
     };
 }

package/dist/http-server.d.ts

@@ -50,4 +50,3 @@ export interface SharedServer {
 export declare function createSharedServer(options?: {
     token?: string;
 }): SharedServer;
-export declare function driveSchemeRefusal(url: string): string | undefined;

package/dist/http-server.js

@@ -330,7 +330,7 @@ function schemeOf(url) {
         return undefined;
     }
 }
-export function driveSchemeRefusal(url) {
+function driveSchemeRefusal(url) {
     const scheme = schemeOf(url);
     if (scheme !== undefined && DRIVEABLE_SCHEMES.includes(scheme))
         return undefined;

package/dist/hunt/hunt-report.d.ts

@@ -18,8 +18,6 @@
  * Pure functions over already-collected reports — the driving is `reticle_crawl`'s job, and running
  * it across a commit range is a shell loop. This is only the part that must not be done by eye.
  */
-/** The contradiction kinds — cross-channel disagreement, as opposed to a single-channel fault. */
-export declare const CONTRADICTION_KINDS: readonly string[];
 export interface HuntAnomaly {
     kind: string;
     ref?: string;

package/dist/hunt/hunt-report.js

@@ -19,7 +19,7 @@
  * it across a commit range is a shell loop. This is only the part that must not be done by eye.
  */
 /** The contradiction kinds — cross-channel disagreement, as opposed to a single-channel fault. */
-export const CONTRADICTION_KINDS = [
+const CONTRADICTION_KINDS = [
     'ui-advanced-request-failed',
     'signal-contradicted',
     'response-ignored',

package/dist/impact/impact-store.d.ts

@@ -3,11 +3,6 @@ export interface ImpactPaths {
     project: string;
     global: string;
 }
-/**
- * `reticleRoot` is the project's own `.reticle` directory (what every other store here is handed);
- * the global scope always lives beside the daemon's own state in `~/.reticle`.
- */
-export declare function impactPaths(reticleRoot: string): ImpactPaths;
 /** Read a scope, tolerating absence and corruption: a broken file starts over rather than throwing. */
 export declare function readScope(path: string, now: number): ImpactScope;
 /** YYYY-MM-DD in local time - the day boundary a person recognises, not UTC's. */

package/dist/impact/impact-store.js

@@ -18,7 +18,7 @@ const WRITE_DEBOUNCE_MS = 800;
  * `reticleRoot` is the project's own `.reticle` directory (what every other store here is handed);
  * the global scope always lives beside the daemon's own state in `~/.reticle`.
  */
-export function impactPaths(reticleRoot) {
+function impactPaths(reticleRoot) {
     return {
         project: join(reticleRoot, ReticleDir.IMPACT_FILE),
         global: join(homedir(), ReticleDir.ROOT, ReticleDir.IMPACT_FILE),

package/dist/index.d.ts

@@ -117,7 +117,10 @@ export interface StartOptions {
     pairingTokenDir?: string;
     /** injectable clock for contract.json's generatedAt stamp. Defaults to Date.now. */
     now?: () => number;
-    /** 'core' exposes the lean tool surface. Defaults to env RETICLE_TOOL_PROFILE, else 'full'. */
+    /**
+     * Retired profile name (`core`/`full`/…). Old values still map. The live switch is
+     * RETICLE_ADVERTISE_ALL_TOOLS=1; the default is the lean surface.
+     */
     toolProfile?: string;
     /** Start the OEM/CI verify HTTP endpoint alongside the daemon (`reticle serve --http`). */
     httpVerify?: boolean;
@@ -151,7 +154,6 @@ export interface RunningServer {
     close: () => Promise<void>;
 }
 export { resolveBridgeSecurity } from './bridge/bridge-security.js';
-/** Start the Reticle bridge (browser WS endpoint) and, by default, the MCP stdio server. */
 export declare function start(options?: StartOptions): Promise<RunningServer>;
 /**
  * Start the Reticle bridge in daemon mode: a single HTTP server handles both the WebSocket

package/dist/index.js

@@ -1,4 +1,9 @@
 import { join } from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { PROJECT_REGISTRY_FILE, emptyProjectRegistry, parseProjectRegistry } from '@reticlehq/core';
+import { discoverProjectConfigs } from './cli/config-discovery.js';
+import { projectCandidatesFrom, resolveArtifactRoot, } from './project/artifact-root.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { AGENT_STOPPED_NOTICE, RETICLE_DEFAULT_PORT, ReticleCommand, ReticleDir, ReticleEnv, LOOPBACK_HOST, ReplayStatus, EventType, } from '@reticlehq/core';
 import { originOf } from './session/session-manager.js';
@@ -251,6 +256,41 @@ async function resolveRealInput(options, onNavigateError, onNetworkDetail) {
     return {};
 }
 /** Start the Reticle bridge (browser WS endpoint) and, by default, the MCP stdio server. */
+/**
+ * Resolve a session's artifact root, from everything this machine knows about where projects live.
+ *
+ * Built once per daemon and closed over by every tool call. The two sources are read lazily and
+ * cheaply on each call rather than snapshotted at startup: `init` can run in another terminal while
+ * this daemon is up, and a resolution that used a startup snapshot would keep answering with a map
+ * from before the project the agent is now driving existed.
+ */
+function artifactRootResolver(daemonRoot) {
+    return (projectId) => {
+        let registry = emptyProjectRegistry();
+        try {
+            const path = join(homedir(), ReticleDir.ROOT, PROJECT_REGISTRY_FILE);
+            registry = existsSync(path)
+                ? parseProjectRegistry(JSON.parse(readFileSync(path, 'utf8')))
+                : registry;
+        }
+        catch {
+            // A cache that cannot be read is an empty cache, never an error: the daemon still resolves
+            // through discovery, and falls back to its own root exactly as it did before this existed.
+        }
+        let discovery = { found: [], searched: [] };
+        try {
+            discovery = discoverProjectConfigs(process.cwd());
+        }
+        catch {
+            // Same reasoning: a diagnostic search that throws must not take a tool call with it.
+        }
+        return resolveArtifactRoot({
+            projectId,
+            candidates: projectCandidatesFrom(discovery, registry),
+            daemonRoot,
+        });
+    };
+}
 export async function start(options = {}) {
     const port = options.port ?? RETICLE_DEFAULT_PORT;
     // Open the user's impact record before anything can connect. Not inside the MCP branch: a daemon
@@ -302,6 +342,7 @@ export async function start(options = {}) {
             project,
             fs,
             reticleRoot,
+            artifactRootFor: artifactRootResolver(reticleRoot),
             now,
             bridgePort: port,
             browserProbe: probeChromium,