@reticlehq/server 2.11.0 → 2.13.0

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,22 @@ 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, a route, or an element located by role / name / testid. 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 {
@@ -113,9 +152,24 @@ export function decideVerified(inputs) {
     // with routeChanges 0, because the text was the nav link already on screen — the real navigation
     // landed 1.8s later. UNKNOWN rather than NO on purpose: the app may well be fine, and reporting a
     // failure we did not observe would be its own false claim.
+    //
+    // `no-fault` rather than `unknown`, once the window settled — the same distinction
+    // `nothing_declared` already draws, gated the same way.
+    //
+    // The two words ask for opposite things. `unknown` means LOOK AGAIN WITH BETTER COVERAGE, so an
+    // agent reading it reasonably concludes the engine could not see, and spends its remaining turns
+    // enabling capture, widening timeouts and re-driving — none of which can help, because the engine
+    // saw the whole window and there was nothing wrong with the evidence. The fault is in the
+    // ASSERTION: it named something that was true before the action, so it cannot tell success from a
+    // no-op. `no-fault` says exactly that, and `because` already carried the remedy that `unknown`
+    // was burying.
+    //
+    // Gated on `true === settled` for the same reason `nothing_declared` is: no-fault claims the whole
+    // window was seen, and a call that returned before the app stopped moving has not earned that.
+    // Unsettled stays `unknown`, which is then the honest word for it.
     if (true === inputs.alreadyTrue) {
         return {
-            verified: Verified.UNKNOWN,
+            verified: true === settled ? Verified.NO_FAULT : Verified.UNKNOWN,
             verifiedReason: VerifiedReason.ALREADY_TRUE,
             because: 'the declared consequence was already true before this action, so it proves nothing about it — assert something the action CHANGES (a signal, a request, a route, or store state)',
         };
@@ -142,7 +196,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 +246,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 +290,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

@@ -6,6 +6,7 @@ import { noteAgentPeer, PEER_VERSION_PARAM, PEER_CONTRACT_PARAM } from './versio
 import { log } from './log.js';
 import { reportMcpConnected } from './telemetry/mcp-connection.js';
 import { isLoopbackHost, isLocalWebOrigin, isLoopbackPeer, requestToken, tokensMatch, } from './bridge/token-auth.js';
+import { LOOPBACK_IDLE_MS } from './loopback-agent.js';
 /**
  * Creates a shared HTTP server that handles both the WebSocket bridge (browser SDK) and the
  * SSE MCP transport (Claude/agent). Does NOT call listen — caller controls that.
@@ -258,6 +259,17 @@ export function createSharedServer(options = {}) {
             });
         });
     }
+    /**
+     * The daemon's half of the keep-alive pact with `loopbackAgent`.
+     *
+     * Node's default is 5 seconds, and the proxy's POST leg is one request per JSON-RPC message. An
+     * agent thinks for longer than 5s between tool calls essentially always, so with the default every
+     * tool call had to open a fresh socket however the client was configured — which on Windows ends
+     * in `ENOBUFS`. This has to stay ABOVE `LOOPBACK_IDLE_MS` so the CLIENT is always the side that
+     * retires an idle socket: if the server closed first, the proxy would keep picking up sockets that
+     * were already gone. It also has to stay below Node's 60s default `headersTimeout`.
+     */
+    httpServer.keepAliveTimeout = LOOPBACK_IDLE_MS + 10_000;
     return {
         httpServer,
         attachMcp,
@@ -330,7 +342,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-recorder.d.ts

@@ -1,18 +1,30 @@
-import { type ImpactCounts, type ImpactSnapshot } from '@reticlehq/core';
+import { type ImpactCounts, type ImpactDefect, type ImpactSnapshot } from '@reticlehq/core';
 import { ImpactStore, type ImpactFoldMeta } from './impact-store.js';
-/** Wire the recorder to a project. Idempotent; the first root wins for the daemon's lifetime. */
+/**
+ * Wire the DEFAULT root — the daemon's own. Idempotent; the first one wins.
+ *
+ * Still idempotent, and still first-wins, because the daemon's own root genuinely does not change
+ * while it runs. What changed is that this is no longer the ONLY root: a call that knows its
+ * project passes one, and this is the fallback for calls that do not.
+ */
 export declare function initImpact(opts: {
     reticleRoot: string | undefined;
     projectName?: string;
     now?: () => number;
 }): ImpactStore | undefined;
-/** The live store, if one has been initialised. */
-export declare function impactStore(): ImpactStore | undefined;
-/** Test seam: drop the singleton so a suite can start from a clean record. */
+/** The live store for a root (default when omitted), if one has been initialised. */
+export declare function impactStore(root?: string): ImpactStore | undefined;
+/** Test seam: drop the stores so a suite can start from a clean record. */
 export declare function resetImpactForTest(): void;
-/** Record one delta, if the recorder is live. Never throws: stats must not break a tool call. */
-export declare function recordImpact(delta: Partial<ImpactCounts>, meta?: ImpactFoldMeta): void;
-export declare function impactSnapshot(): ImpactSnapshot | undefined;
+/**
+ * Record one delta against a project's ledger. Never throws: stats must not break a tool call.
+ *
+ * `root` is the `.reticle` directory this call's evidence belongs to. Omitted means "could not tell
+ * which project", which falls back to the daemon's own root — the old behaviour, kept for the paths
+ * that genuinely have no session to ask.
+ */
+export declare function recordImpact(delta: Partial<ImpactCounts>, meta?: ImpactFoldMeta, root?: string): void;
+export declare function impactSnapshot(root?: string): ImpactSnapshot | undefined;
 /**
  * What one tool call did, as counters.
  *
@@ -21,3 +33,14 @@ export declare function impactSnapshot(): ImpactSnapshot | undefined;
  * the same rule the product states to agents - everything else moves or reads the app.
  */
 export declare function deltaForToolResult(raw: unknown, durationMs: number, refused: boolean): Partial<ImpactCounts>;
+/**
+ * What one FAILED verdict was, in a line.
+ *
+ * Only a verified:"no" produces one. That is the same rule the counters follow and the same rule
+ * the product states to agents: an "unknown" is not a defect, it is Reticle admitting it could not
+ * tell — recording those here would fill the user's short list with the tool's own blind spots.
+ *
+ * Everything is read from the result the tool already returned, so this costs nothing extra and
+ * cannot disagree with the verdict it describes.
+ */
+export declare function defectForToolResult(raw: unknown, at: number): ImpactDefect | undefined;

package/dist/impact/impact-recorder.js

@@ -1,43 +1,90 @@
-import { Verified } from '@reticlehq/core';
+import { Verified, } from '@reticlehq/core';
 import { estimateTokens } from '../session/output-budget.js';
 import { ImpactStore } from './impact-store.js';
 /**
- * The daemon's single impact recorder.
+ * The daemon's impact recorders — ONE PER PROJECT ROOT.
  *
- * One store per daemon, created on the first call that knows the project's `.reticle` root. A
- * module singleton for the same reason the tool counters are: the dispatch chokepoint has to be
- * able to record without every tool threading a store through its arguments, and a second recorder
- * would silently split the user's own history in half.
+ * This was a single module-level store, and "the first root wins for the daemon's lifetime" was
+ * written down as if it were a design decision. It is only correct for a daemon that serves one
+ * project, and this daemon has never been that: `artifactRootFor` exists precisely because one
+ * daemon serves many, and nine modules already route their artifacts by the SESSION's project.
+ *
+ * Measured, not theorised: with a daemon rooted at repo A, two verdicts driven against app B landed
+ * in A's `impact.json` — B's own ledger never moved — and A's cloud link then carried them to a
+ * PRODUCTION dashboard belonging to a different account than B was linked to. The impact ledger is
+ * what the whole dashboard is computed from, so this was the one artifact whose misrouting was
+ * guaranteed to be visible and billed.
+ *
+ * Keyed by root path, so two projects driven through one daemon keep separate ledgers, and the
+ * daemon's own root remains the answer for anything that cannot name a project.
+ */
+/** One store per `.reticle` root. */
+const stores = new Map();
+/** The daemon's own root — used when a call cannot say which project it was for. */
+let defaultRoot;
+/** Held so a per-root store is built with the same clock and project name as the default. */
+let storeOpts = {};
+/** Get-or-create the store for one root. */
+function storeFor(root) {
+    const key = root ?? defaultRoot;
+    if (key === undefined || 0 === key.length)
+        return undefined;
+    let found = stores.get(key);
+    if (found === undefined) {
+        found = new ImpactStore({ ...storeOpts, reticleRoot: key });
+        stores.set(key, found);
+    }
+    return found;
+}
+/**
+ * Wire the DEFAULT root — the daemon's own. Idempotent; the first one wins.
+ *
+ * Still idempotent, and still first-wins, because the daemon's own root genuinely does not change
+ * while it runs. What changed is that this is no longer the ONLY root: a call that knows its
+ * project passes one, and this is the fallback for calls that do not.
  */
-let store;
-/** Wire the recorder to a project. Idempotent; the first root wins for the daemon's lifetime. */
 export function initImpact(opts) {
     // No root, no record. Programmatic callers and test doubles build their own deps and are not
     // obliged to carry one, and a courtesy counter must never be the reason a tool call throws.
     if (opts.reticleRoot === undefined || 0 === opts.reticleRoot.length)
-        return store;
-    store ??= new ImpactStore({ ...opts, reticleRoot: opts.reticleRoot });
-    return store;
+        return storeFor(undefined);
+    if (defaultRoot === undefined) {
+        defaultRoot = opts.reticleRoot;
+        const { projectName, now } = opts;
+        storeOpts = {
+            ...(projectName === undefined ? {} : { projectName }),
+            ...(now === undefined ? {} : { now }),
+        };
+    }
+    return storeFor(opts.reticleRoot);
 }
-/** The live store, if one has been initialised. */
-export function impactStore() {
-    return store;
+/** The live store for a root (default when omitted), if one has been initialised. */
+export function impactStore(root) {
+    return storeFor(root);
 }
-/** Test seam: drop the singleton so a suite can start from a clean record. */
+/** Test seam: drop the stores so a suite can start from a clean record. */
 export function resetImpactForTest() {
-    store = undefined;
+    stores.clear();
+    defaultRoot = undefined;
+    storeOpts = {};
 }
-/** Record one delta, if the recorder is live. Never throws: stats must not break a tool call. */
-export function recordImpact(delta, meta = {}) {
+/**
+ * Record one delta against a project's ledger. Never throws: stats must not break a tool call.
+ *
+ * `root` is the `.reticle` directory this call's evidence belongs to. Omitted means "could not tell
+ * which project", which falls back to the daemon's own root — the old behaviour, kept for the paths
+ * that genuinely have no session to ask.
+ */
+export function recordImpact(delta, meta = {}, root) {
     try {
-        store?.record(delta, meta);
+        storeFor(root)?.record(delta, meta);
     }
     catch {
         // Counting is a courtesy to the user; failing to count is not worth failing their call over.
     }
 }
-export function impactSnapshot() {
-    return store?.snapshot();
+export function impactSnapshot(root) {
+    return storeFor(root)?.snapshot();
 }
 /**
  * What one tool call did, as counters.
@@ -71,6 +118,42 @@ export function deltaForToolResult(raw, durationMs, refused) {
     }
     return delta;
 }
+/**
+ * What one FAILED verdict was, in a line.
+ *
+ * Only a verified:"no" produces one. That is the same rule the counters follow and the same rule
+ * the product states to agents: an "unknown" is not a defect, it is Reticle admitting it could not
+ * tell — recording those here would fill the user's short list with the tool's own blind spots.
+ *
+ * Everything is read from the result the tool already returned, so this costs nothing extra and
+ * cannot disagree with the verdict it describes.
+ */
+export function defectForToolResult(raw, at) {
+    if (!isRecord(raw) || raw['verified'] !== Verified.NO)
+        return undefined;
+    const effect = isRecord(raw['effect']) ? raw['effect'] : undefined;
+    const verdict = isRecord(raw['verdict']) ? raw['verdict'] : undefined;
+    const named = text(effect?.['name']) ?? text(effect?.['testid']) ?? text(effect?.['component']);
+    const why = text(verdict?.['failureReason']) ?? text(raw['because']);
+    const defect = {
+        at,
+        // The control that was acted on, when the result names one — "Sign In did not sign in" is a
+        // sentence somebody can act on; "a verdict failed" is not.
+        title: named === undefined ? (why ?? 'a declared consequence did not hold') : named,
+    };
+    if (named !== undefined && why !== undefined)
+        defect.detail = why;
+    const source = text(raw['source']);
+    if (source !== undefined)
+        defect.source = source;
+    return defect;
+}
+function text(value) {
+    if ('string' !== typeof value)
+        return undefined;
+    const trimmed = value.trim();
+    return 0 === trimmed.length ? undefined : trimmed;
+}
 function isRecord(value) {
     return 'object' === typeof value && null !== value;
 }