@reticlehq/server 2.8.0 → 2.9.0

package/dist/cli.js

@@ -1,8 +1,11 @@
 #!/usr/bin/env node
 import { pathToFileURL } from 'node:url';
+import { openFailureNote } from './cli/open-note.js';
 import { realpathSync } from 'node:fs';
 import { join } from 'node:path';
 import { stateDirProblem } from './daemon/state-dir.js';
+import { statusNextAction } from './cli/status-next-action.js';
+import { hasConnectedBefore } from './session/connection-memory.js';
 import { reticleStateHome } from './daemon/daemon.js';
 import { handleWatch, handleCapsules, handleGate, loadNamedFlows, resolveChangedFiles, } from './cli/cli-flow-commands.js';
 import { RETICLE_DEFAULT_PORT, ReticleDir, ReticleEnv } from '@reticlehq/core';
@@ -11,7 +14,7 @@ import { createNodeFileSystem } from './project/fs-port.js';
 import { affectedSavedFlows } from './flows/flow-sources.js';
 import { availableUpdate } from './update/update-nudge.js';
 import { handleUpdate, handleRollback } from './cli/cli-update-commands.js';
-import { start, startDaemon } from './index.js';
+import { startDaemon } from './index.js';
 import { isCloudCommand, runCloudCommand } from './cli/cloud-cli.js';
 import { SERVER_VERSION } from './version/server-version.js';
 import { log } from './log.js';
@@ -22,7 +25,8 @@ import { installDaemonResilience, installProxyResilience, recordExitReason, Daem
 import { IdleShutdown, resolveIdleShutdownMs, resolveIdleCheckMs } from './daemon/idle-shutdown.js';
 import { DaemonHeartbeat, resolveHeartbeatMs } from './daemon/heartbeat.js';
 import { everServedToolCall } from './daemon/daemon-usefulness.js';
-import { fetchStatus, summarizeStatus, warnOnDaemonSkew, decideOpen, drivePortConflict, openInBrowser, openCommand, } from './cli/cli-launch.js';
+import { fetchStatus, summarizeStatus, warnOnDaemonSkew, decideOpen, openInBrowser, openCommand, } from './cli/cli-launch.js';
+import { handleDrive } from './cli/drive-command.js';
 import { handleVerify } from './cli/cli-verify.js';
 import { runKill } from './cli/cli-kill.js';
 import { summarizeHunt } from './hunt/hunt-report.js';
@@ -220,17 +224,34 @@ async function handleRestart(port, force) {
     // same lie `serve` already stopped telling.
     await serveWithHonestExit({ port, headless: true, http: false });
 }
+/** `{ nextAction }` when there is one, `{}` when a session is connected — so the success case is silent. */
+function withNextAction(facts) {
+    const next = statusNextAction(facts);
+    return next === undefined ? {} : { nextAction: next };
+}
 function handleStatus(port) {
     const pid = readPid(port);
+    // Durable, so it survives the daemon idling out — which is the state `status` is most often run in.
+    const projectId = readProjectId(process.cwd());
+    const previouslyConnected = hasConnectedBefore(reticleStateHome(), port, projectId);
+    // Whether `init` has run HERE. Registering the MCP server does not wire the app, and more than one
+    // path does the first without the second — so this is the commonest reason `status` has nothing to
+    // report, and it was not among the facts this command could state.
+    const initialized = projectId !== undefined;
     if (null === pid || !isAlive(pid)) {
         // `running: false` on its own has been reported about a port that was demonstrably occupied,
         // because the pid file is not the port. Ask the port before answering.
         void probePresence(port, { tcpOpen: probeDaemon, status: fetchStatus }).then((presence) => {
+            const running = presenceIsUsable(presence);
             log('reticle_status', {
                 port,
-                running: presenceIsUsable(presence),
+                running,
                 presence,
                 ...(presence === PortPresence.FOREIGN ? { reason: describePresence(presence, port) } : {}),
+                // `init` promises this command says why the app has not connected. Without it the answer was
+                // `running: false` and nothing else, which reads as "Reticle is broken" for what is usually
+                // just a daemon that has not been asked to do anything yet.
+                ...withNextAction({ running, sessionCount: 0, previouslyConnected, initialized }),
             });
         });
         return;
@@ -243,10 +264,23 @@ function handleStatus(port) {
         const update = availableUpdate();
         const nudge = update === undefined ? {} : { updateAvailable: update };
         if (payload === undefined) {
-            log('reticle_status', { port, running: true, pid, ...nudge });
+            log('reticle_status', {
+                port,
+                running: true,
+                pid,
+                ...nudge,
+                ...withNextAction({ running: true, sessionCount: 0, previouslyConnected, initialized }),
+            });
             return;
         }
-        log('reticle_status', { port, running: true, pid, ...summarizeStatus(payload), ...nudge });
+        const summary = summarizeStatus(payload);
+        // Only when the daemon did NOT already explain itself. It has the whole diagnosis in-process and
+        // puts it on the wire as `why`; printing a second, thinner opinion beside it risks two confident
+        // answers pointing different ways, which is worse than one.
+        const next = summary.why === undefined
+            ? withNextAction({ running: true, ...summary, previouslyConnected, initialized })
+            : {};
+        log('reticle_status', { port, running: true, pid, ...summary, ...next, ...nudge });
     });
 }
 /** Print the running package version (resolved once in server-version.ts). */
@@ -318,13 +352,20 @@ async function handleHunt(dir) {
 }
 /** Ensure a daemon is reachable on `port` (probe the real port; spawn + wait only if nothing's there). */
 function ensureDaemon(port) {
-    return probeDaemon(port).then(async (listening) => {
+    return probePresence(port, { tcpOpen: probeDaemon, status: fetchStatus }).then(async (presence) => {
         // Attaching to whatever already owns the port is the whole point of a daemon — but it means an
         // upgrade does NOT take effect until that daemon dies, and nothing used to say so. Say it here,
         // where both versions are in hand, and keep attaching: killing another agent's daemon on a
         // version bump is worse than a loud warning.
-        if (listening)
+        if (presenceIsUsable(presence))
             return warnOnDaemonSkew(port);
+        // Not free, not a daemon: a stranger holds the port. Spawning here is guaranteed to fail —
+        // the child cannot bind — and `waitForDaemon` would then report READY anyway, because its
+        // probe is the same bare TCP connect and the stranger accepts. That is the "serve reports
+        // success for a daemon that never bound" shape. Refuse instead, with the sentence `doctor`
+        // says.
+        if (PortPresence.FREE !== presence)
+            throw new Error(describePresence(presence, port));
         const scriptPath = process.argv[1];
         if (scriptPath === undefined)
             throw new Error('cannot locate the reticle daemon script');
@@ -410,6 +451,7 @@ function handleOpen(requestedPort, url) {
         const connected = await waitForNewSession(port, sessions.length);
         log('reticle_open', {
             port,
+            ...(port === requestedPort ? {} : { requestedPort }),
             opened: decision.url,
             connected,
             ...(connected
@@ -422,14 +464,7 @@ function handleOpen(requestedPort, url) {
                     // about a browser THIS command never uses, so a missing Chromium reads as the
                     // explanation for a session that is missing for an unrelated reason. Both misdirects
                     // were reported from the field, each costing several calls of app-side wiring hunt.
-                    note: `the URL was handed to the system default browser (this command does not use ` +
-                        `Reticle's own Chromium, so a chromium warning from \`reticle doctor\` is unrelated ` +
-                        `to this). No Reticle session appeared. By far the likeliest cause is that the app ` +
-                        `carries no Reticle SDK, or dials a port other than ${String(port)} — run ` +
-                        `\`reticle init\` in the app's directory and restart its dev server. If the app IS ` +
-                        `wired, give the page a moment and check the browser console: the SDK announces its ` +
-                        `own connect failures there, including the one it refuses to make from a ` +
-                        `non-localhost host without allowNonLocalhost.`,
+                    note: openFailureNote(port, requestedPort),
                 }),
         });
     })
@@ -478,6 +513,12 @@ function handleDaemonInner(parsed) {
             // which is after everything below has run. Without it the exit line says `code: 0` and a
             // reader cannot tell a tidy stop from the bridge disappearing — see #123.
             recordExitReason(reason);
+            // Say so on the wire before anything closes. The proxy on the other end sees a clean stream
+            // end whether we retired on schedule or died under it, and it has no other way to tell —
+            // which is how a designed shutdown came to dominate the metric that means "the agent lost
+            // its tools". Told, the proxy classifies its own drop honestly. First, because the send has
+            // to reach a socket that is still open.
+            server.announceShutdown?.();
             // Awaited before the close/exit chain: `process.exit(0)` kills an in-flight POST, and this is
             // the one event carrying the whole session. A failed send resolves anyway (emit swallows its
             // own errors), so this can delay the exit by at most the send timeout, never prevent it.
@@ -572,8 +613,15 @@ function handleMcp(opts) {
      * disappeared mid-session with nothing said. Respawning here makes the reconnect self-healing.
      */
     const ensure = async () => {
-        if (await probeDaemon(port))
+        // The same question every other surface asks. It used to be a bare TCP connect, so a stranger on
+        // the bridge port answered "a daemon is here" — the proxy connected, the stream ended, and each
+        // client request woke into the identical non-answer. Rejecting here is what puts the proxy
+        // dormant with a reason, instead of pretending the wake succeeded.
+        const presence = await probePresence(port, { tcpOpen: probeDaemon, status: fetchStatus });
+        if (presenceIsUsable(presence))
             return;
+        if (PortPresence.FREE !== presence)
+            throw new Error(describePresence(presence, port));
         const scriptPath = process.argv[1];
         if (scriptPath === undefined) {
             log('reticle_mcp_no_script', {});
@@ -640,59 +688,6 @@ function handleMcp(opts) {
         });
     });
 }
-function handleLegacyDrive(parsed) {
-    void driveWithHonestConflict(parsed);
-}
-/**
- * Refuse the port BEFORE binding it, and name what is holding it.
- *
- * `drive` went straight to `start`, which binds. The listen error surfaces asynchronously on the
- * server object long after `start` has resolved, so the `.catch` on that promise could never see it
- * and the process died with the raw `node:net` EADDRINUSE stack — in the one situation this command
- * is most often run in, since `reticle_sessions` recommends `reticle drive` for a throttled tab and
- * a throttled tab nearly always coexists with the daemon holding the port.
- */
-async function driveWithHonestConflict(parsed) {
-    const presence = await probePresence(parsed.port, { tcpOpen: probeDaemon, status: fetchStatus });
-    const conflict = drivePortConflict(presence, parsed.port, { ourPid: readPid(parsed.port) });
-    if (conflict !== undefined) {
-        log('reticle_drive_port_conflict', { port: parsed.port, presence, reason: conflict });
-        process.stderr.write(`${conflict}\n`);
-        process.exit(1);
-        return;
-    }
-    // The probe cannot close the race: something can take the port between here and the bind, and the
-    // bind reports it on the server, outside every promise this function holds. Catching it at the
-    // process is the only place that sees it at all — and only EADDRINUSE, so a genuine crash still
-    // crashes rather than being dressed up as a port conflict. Who won the race is not knowable from
-    // in here, so the sentence used is the one that is true of any holder.
-    process.on('uncaughtException', (error) => {
-        const code = error?.code;
-        if ('EADDRINUSE' !== code)
-            throw error;
-        const reason = drivePortConflict(PortPresence.FOREIGN, parsed.port);
-        log('reticle_drive_port_conflict', {
-            port: parsed.port,
-            presence: PortPresence.FOREIGN,
-            reason,
-        });
-        process.stderr.write(`${String(reason)}\n`);
-        process.exit(1);
-    });
-    const options = {
-        port: parsed.port,
-        driveUrl: parsed.driveUrl,
-        headless: parsed.headless,
-    };
-    try {
-        await start(options);
-        log('reticle_started', { port: parsed.port });
-    }
-    catch (error) {
-        log('reticle_start_failed', { error: error instanceof Error ? error.message : String(error) });
-        process.exit(1);
-    }
-}
 function main() {
     // Before anything reads process.env — notably the telemetry gate and the bridge's security
     // options — fold in a project-local `.env`. Values already in the environment always win.
@@ -782,7 +777,7 @@ function main() {
             handleOpen(parsed.port, parsed.url);
             break;
         case 'drive':
-            handleLegacyDrive(parsed);
+            handleDrive(parsed);
             break;
         case 'verify':
             handleVerify(parsed);

package/dist/events/contradictions.d.ts

@@ -1,4 +1,5 @@
 import { ContradictionKind, type ReticleEvent } from '@reticlehq/core';
+import { type DeclaredNetFailure } from './declared.js';
 /**
  * The contradiction hunter.
  *
@@ -63,5 +64,36 @@ export interface ContradictionOptions {
      * test, which is weaker but never wrong in the direction of a false accusation.
      */
     mutatedWithin?: number | undefined;
+    /**
+     * Requests the CALLER declared would fail, read off the oracle it wrote before acting.
+     *
+     * `ui-advanced-request-failed` cannot tell "the app swallowed the error and carried on" from "the
+     * app rendered the error, which is the behaviour under test" — both are a moved DOM beside a
+     * failed request. `failureAcknowledged` recovers the first from the app's own state, and an app
+     * that renders its error straight into the DOM without touching a store defeats it.
+     *
+     * The declaration is the missing evidence, and it costs no new API: an agent verifying an error
+     * path already writes `{ net, POST, /api/login, status: 500 }` into the predicate. Measured in the
+     * field: every branch of a login error path (500, 401, 503) passed every declared clause and every
+     * run still returned `verified: "no" / contradicted`, so error handling — empty states, offline
+     * banners, 4xx/5xx messaging, lockouts — was the code least able to reach a green verdict and the
+     * most worth verifying.
+     *
+     * Scoped as narrowly as it can be: it suppresses ONLY the heuristic rule that cannot see the
+     * difference. A success signal fired over the declared failure still contradicts, and a server
+     * fault blamed on the user is still misattributed — see the negative controls in
+     * `contradictions.declared.test.ts`.
+     */
+    expectedFailures?: readonly DeclaredNetFailure[] | undefined;
+    /**
+     * The caller declared an on-screen consequence and it HELD in this window.
+     *
+     * `route-rendered-nothing` infers a blank destination from the absence of DOM events, and a
+     * verdict that names it beside an element match — heading found, with its source file and line —
+     * is a clause its own evidence disproves. Positive evidence outranks the absence it is inferred
+     * from. Undefined/false leaves the rule exactly as it was, which is the case that catches a route
+     * with no view.
+     */
+    renderProved?: boolean | undefined;
 }
 export declare function findContradictions(allEvents: readonly ReticleEvent[], options?: ContradictionOptions): Contradiction[];

package/dist/events/contradictions.js

@@ -4,6 +4,7 @@ import { findBodyFailures } from './body-failures.js';
 import { findEchoMismatches } from './echo-mismatch.js';
 import { findUnitMismatches } from './unit-mismatch.js';
 import { asNumber, asString } from '../tools/tools-helpers.js';
+import { matchesDeclaredFailure } from './declared.js';
 function netCall(e) {
     const status = asNumber(e.data['status']);
     return {
@@ -171,7 +172,7 @@ export function findContradictions(allEvents, options = {}) {
     // Needs body capture; silent without it, which is why the assert path also declares when bodies
     // were never recorded rather than letting an unread payload read as an empty one.
     found.push(...findBodyFailures(events));
-    found.push(...findEchoMismatches(events));
+    found.push(...findEchoMismatches(events, options.actionSince));
     // ── A money value written back at the wrong SCALE ───────────────────────────────────────────
     found.push(...findUnitMismatches(events, options.prior ?? []));
     // ── The action landed on something that does not react ──────────────────────────────────────
@@ -192,6 +193,9 @@ export function findContradictions(allEvents, options = {}) {
         ];
     }
     const failed = settled.filter((c) => false === c.ok);
+    // The failures NOBODY declared — see ContradictionOptions.expectedFailures. Only the heuristic
+    // "the UI moved while a request failed" rule reads this; the sharp rules still read `failed`.
+    const unexpected = failed.filter((c) => !matchesDeclaredFailure(c, options.expectedFailures ?? []));
     const advanced = uiAdvanced(events);
     const signals = events
         .filter((e) => e.type === EventType.SIGNAL)
@@ -215,7 +219,7 @@ export function findContradictions(allEvents, options = {}) {
         e.type === EventType.DOM_REMOVED ||
         e.type === EventType.DOM_TEXT);
     const fetched = events.some((e) => e.type === EventType.NET_REQUEST || e.type === EventType.NET_PENDING);
-    if (routed && !rendered && !fetched) {
+    if (routed && !rendered && !fetched && true !== options.renderProved) {
         found.push({
             kind: ContradictionKind.ROUTE_RENDERED_NOTHING,
             claim: 'the app navigated to a new route',
@@ -259,12 +263,12 @@ export function findContradictions(allEvents, options = {}) {
             detail: failed.map(describe).join('; '),
         });
     }
-    else if (failed.length > 0 && advanced && !misattributed && !failureAcknowledged(events)) {
+    else if (unexpected.length > 0 && advanced && !misattributed && !failureAcknowledged(events)) {
         found.push({
             kind: ContradictionKind.UI_ADVANCED_REQUEST_FAILED,
             claim: 'the UI moved forward (DOM/store/route changed)',
-            counter: `${String(failed.length)} request(s) in the same window failed`,
-            detail: failed.map(describe).join('; '),
+            counter: `${String(unexpected.length)} request(s) in the same window failed`,
+            detail: unexpected.map(describe).join('; '),
         });
     }
     // ── A write succeeded and nothing on the client moved ───────────────────────────────────────

package/dist/events/declared.d.ts

@@ -0,0 +1,45 @@
+/**
+ * What the caller DECLARED before acting — the oracle, read back.
+ *
+ * `act_and_wait` asks the agent to name the expected consequence BEFORE the action, and that
+ * declaration was then thrown away: everything downstream judged the window as if nobody had said
+ * what they were expecting. Two measured consequences, one bug:
+ *
+ *  - An error path can be declared exactly — `{ net, POST, /api/login, status: 500 }` — and the
+ *    contradiction hunter still reported `ui-advanced-request-failed`, because a failed request plus
+ *    a moved DOM is all it can see. The failure was EXPECTED and said so in the predicate, so a
+ *    verdict of "channels disagree" is a statement about a disagreement nobody had.
+ *  - A destination whose content was asserted and FOUND was still reported as
+ *    `route-rendered-nothing`, a clause the element evidence beside it disproves.
+ *
+ * Deliberately conservative about what counts as declared. Only what the caller REQUIRED is read:
+ * the top level and `allOf` chains. An `anyOf` branch may never have held, and a `not` declares the
+ * opposite of a consequence — honouring either would suppress a real finding on the strength of
+ * something that never happened. Pure: a predicate in, a description out.
+ */
+import type { Predicate } from './predicate-eval.js';
+/** A failing call the caller named in advance — matched against the window's real calls. */
+export interface DeclaredNetFailure {
+    method?: string;
+    urlContains?: string;
+    status?: number;
+}
+export interface DeclaredExpectations {
+    /** Requests the caller declared would FAIL, so failing is the expected outcome, not a disagreement. */
+    netFailures: readonly DeclaredNetFailure[];
+    /** The caller required something to be ON SCREEN — an element or text, present rather than absent. */
+    rendersContent: boolean;
+}
+export declare function declaredExpectations(predicate: Predicate | undefined): DeclaredExpectations;
+/**
+ * Does a call the window recorded match a failure the caller declared?
+ *
+ * Every field the caller named must agree — a declaration about `POST /api/login → 500` says nothing
+ * about `POST /api/orders`, and treating it as a blanket amnesty for failed requests would remove
+ * the check rather than inform it. Fields the caller left out are not constraints.
+ */
+export declare function matchesDeclaredFailure(call: {
+    method: string;
+    url: string;
+    status: number | undefined;
+}, declared: readonly DeclaredNetFailure[]): boolean;

package/dist/events/declared.js

@@ -0,0 +1,73 @@
+/**
+ * What the caller DECLARED before acting — the oracle, read back.
+ *
+ * `act_and_wait` asks the agent to name the expected consequence BEFORE the action, and that
+ * declaration was then thrown away: everything downstream judged the window as if nobody had said
+ * what they were expecting. Two measured consequences, one bug:
+ *
+ *  - An error path can be declared exactly — `{ net, POST, /api/login, status: 500 }` — and the
+ *    contradiction hunter still reported `ui-advanced-request-failed`, because a failed request plus
+ *    a moved DOM is all it can see. The failure was EXPECTED and said so in the predicate, so a
+ *    verdict of "channels disagree" is a statement about a disagreement nobody had.
+ *  - A destination whose content was asserted and FOUND was still reported as
+ *    `route-rendered-nothing`, a clause the element evidence beside it disproves.
+ *
+ * Deliberately conservative about what counts as declared. Only what the caller REQUIRED is read:
+ * the top level and `allOf` chains. An `anyOf` branch may never have held, and a `not` declares the
+ * opposite of a consequence — honouring either would suppress a real finding on the strength of
+ * something that never happened. Pure: a predicate in, a description out.
+ */
+import { PredicateKind } from '@reticlehq/core';
+/** Below this, a status is a success or a redirect: not a declared failure. */
+const FAILURE_STATUS_MIN = 400;
+export function declaredExpectations(predicate) {
+    const netFailures = [];
+    let rendersContent = false;
+    const walk = (p) => {
+        switch (p.kind) {
+            case PredicateKind.ALL_OF:
+                for (const child of p.predicates)
+                    walk(child);
+                return;
+            case PredicateKind.NET: {
+                const declaredFailure = false === p.ok || (p.status !== undefined && p.status >= FAILURE_STATUS_MIN);
+                if (!declaredFailure)
+                    return;
+                netFailures.push({
+                    ...(p.method === undefined ? {} : { method: p.method }),
+                    ...(p.urlContains === undefined ? {} : { urlContains: p.urlContains }),
+                    ...(p.status === undefined ? {} : { status: p.status }),
+                });
+                return;
+            }
+            case PredicateKind.ELEMENT:
+            case PredicateKind.TEXT:
+                if (true !== p.absent)
+                    rendersContent = true;
+                return;
+            default:
+                return;
+        }
+    };
+    if (predicate !== undefined)
+        walk(predicate);
+    return { netFailures, rendersContent };
+}
+/**
+ * Does a call the window recorded match a failure the caller declared?
+ *
+ * Every field the caller named must agree — a declaration about `POST /api/login → 500` says nothing
+ * about `POST /api/orders`, and treating it as a blanket amnesty for failed requests would remove
+ * the check rather than inform it. Fields the caller left out are not constraints.
+ */
+export function matchesDeclaredFailure(call, declared) {
+    return declared.some((d) => {
+        if (d.method !== undefined && d.method.toUpperCase() !== call.method.toUpperCase())
+            return false;
+        if (d.urlContains !== undefined && !call.url.includes(d.urlContains))
+            return false;
+        if (d.status !== undefined && d.status !== call.status)
+            return false;
+        return true;
+    });
+}

package/dist/events/echo-mismatch.d.ts

@@ -1,4 +1,10 @@
 import { type ReticleEvent } from '@reticlehq/core';
 import type { Contradiction } from './contradictions.js';
-/** Contradictions for writes whose response echoes a different value than the request asked for. */
-export declare function findEchoMismatches(events: readonly ReticleEvent[]): Contradiction[];
+/**
+ * Contradictions for writes whose response echoes a different value than the request asked for.
+ *
+ * `actionSince` is the attribution floor `findContradictions` already keeps — the event time the
+ * action that opened this window was dispatched. A finding about a request that had already settled
+ * before the agent acted otherwise reads as a verdict on the change it just made.
+ */
+export declare function findEchoMismatches(events: readonly ReticleEvent[], actionSince?: number): Contradiction[];

package/dist/events/echo-mismatch.js

@@ -1,4 +1,4 @@
-import { ContradictionKind, EventType } from '@reticlehq/core';
+import { ContradictionKind, EventType, MUTATING_METHODS } from '@reticlehq/core';
 /**
  * A write that returned OK and quietly did not apply part of what it was asked to.
  *
@@ -18,6 +18,11 @@ import { ContradictionKind, EventType } from '@reticlehq/core';
  * would fire on healthy APIs constantly, and a contradiction kind that cries wolf gets filtered out
  * by the agents reading it, taking the true positives with it. So:
  *
+ *  - only requests that are WRITES are considered. Reported from the field: a lookup that sends its
+ *    key in the body (`POST /get-branding` with `{workspace_id}`) and gets a record back was graded
+ *    as a half-applied write. The gate was on the RESPONSE being a success and never on the REQUEST
+ *    being a write, so every successful call carrying a body read as a save — and the same key name
+ *    legitimately means different things on the two sides of a request/response pair;
  *  - only keys the request actually SENT are considered;
  *  - only scalars, since deep structural diffing is where the false positives live;
  *  - values are compared NORMALISED (trimmed, case-folded, numbers as numbers), so `FR` vs `fr` and
@@ -89,12 +94,33 @@ function scalarsByKey(body, into = new Map(), depth = 0) {
 }
 const OK_MIN = 200;
 const OK_MAX = 300;
-/** Contradictions for writes whose response echoes a different value than the request asked for. */
-export function findEchoMismatches(events) {
+/**
+ * Contradictions for writes whose response echoes a different value than the request asked for.
+ *
+ * `actionSince` is the attribution floor `findContradictions` already keeps — the event time the
+ * action that opened this window was dispatched. A finding about a request that had already settled
+ * before the agent acted otherwise reads as a verdict on the change it just made.
+ */
+export function findEchoMismatches(events, actionSince) {
     const found = [];
     for (const event of events) {
         if (event.type !== EventType.NET_REQUEST)
             continue;
+        // `MUTATING_METHODS` is the one definition of "is this a write" in the codebase — the same list
+        // `contradictions.ts`'s `isMutating` reads. A read has no fields to half-apply.
+        //
+        // KNOWN LIMIT, stated because it is easy to read this fix as bigger than it is: POST is in that
+        // list, so a lookup that POSTs its key and gets a record back — the shape actually reported —
+        // still reaches the comparison below. Method is the only signal available here, and a read-shaped
+        // POST is genuinely indistinguishable from a write by method alone.
+        //
+        // The tempting next step is to skip a pair whose JSON types disagree (a string key sent, a number
+        // echoed). Deliberately not taken: that also silences `{"qty":"5"}` answered with `3`, which is a
+        // real dropped write. A false negative here is a missed bug in someone's app, and that is not a
+        // trade this file makes to quieten a false positive.
+        const method = 'string' === typeof event.data['method'] ? event.data['method'] : '';
+        if (!MUTATING_METHODS.includes(method.toUpperCase()))
+            continue;
         // IPC reports `ok` rather than a status; HTTP reports a status. Either must say success — a write
         // that already failed is a different (and louder) finding than one that half-applied.
         const status = event.data['status'];
@@ -126,12 +152,14 @@ export function findEchoMismatches(events) {
         if (0 === dropped.length)
             continue;
         const url = 'string' === typeof event.data['url'] ? event.data['url'] : '';
-        const method = 'string' === typeof event.data['method'] ? event.data['method'] : '';
+        const attribution = actionSince !== undefined && event.t < actionSince
+            ? ' — this request completed before the action being verified, so the finding is not about that change'
+            : '';
         found.push({
             kind: ContradictionKind.WRITE_FIELD_IGNORED,
             claim: 'the write returned success and the page treated it as saved',
             counter: `its own echo shows ${String(dropped.length)} field(s) NOT applied — ${dropped.join('; ')}`,
-            detail: `${method} ${url} — the server answered OK and returned a different value than it was asked to set, so the write half-applied; the UI has no way to know and will show the value the user typed`,
+            detail: `${method} ${url} — the server answered OK and returned a different value than it was asked to set, so the write half-applied; the UI has no way to know and will show the value the user typed${attribution}`,
         });
     }
     return found;

package/dist/events/event-filters.d.ts

@@ -57,7 +57,7 @@ interface NetCallView {
      */
     oneWay?: boolean;
 }
-export declare function projectNetCall(e: ReticleEvent): NetCallView;
+export declare function projectNetCall(e: ReticleEvent, includeBodies?: boolean): NetCallView;
 /**
  * Compact console-log summary for reticle_console output.
  *

package/dist/events/event-filters.js

@@ -86,7 +86,7 @@ export function reconcileNet(events) {
         .map((e) => ({ ...e, data: { ...e.data, status: 'pending', pending: true } }));
     return [...completed, ...unresolved].sort((a, b) => a.t - b.t);
 }
-export function projectNetCall(e) {
+export function projectNetCall(e, includeBodies = true) {
     const status = e.data['status'];
     const ms = asNumber(e.data['durationMs']);
     const statusText = asString(e.data['statusText']);
@@ -106,11 +106,14 @@ export function projectNetCall(e) {
         view.contentType = contentType;
     if (responseSize !== undefined)
         view.responseSize = responseSize;
-    if (requestBody !== undefined)
+    // Bodies dominate the payload of the most-called read tool, and are only occasionally the part
+    // anyone wanted — `bodies: false` on reticle_network drops them for a body-free listing (#401).
+    if (includeBodies && requestBody !== undefined)
         view.requestBody = requestBody;
-    if (responseBody !== undefined)
+    if (includeBodies && responseBody !== undefined)
         view.responseBody = responseBody;
-    if (true === e.data['requestBodyTruncated'] || true === e.data['responseBodyTruncated']) {
+    if (includeBodies &&
+        (true === e.data['requestBodyTruncated'] || true === e.data['responseBodyTruncated'])) {
         view.bodyTruncated = true;
     }
     if (ms !== undefined)