@reticlehq/server 3.2.0 → 3.4.0

package/dist/index.js

@@ -4,14 +4,14 @@ import { fetchPlatformConfig } from './features/harness/platform-config.js';
 import { join } from 'node:path';
 import { existsSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { linkedCloudPort } from './memory/cloud/cloud-config.js';
+import { linkedCloudPort, platformEnvPort } from './memory/cloud/cloud-config.js';
 import { attachCloudSync } from './memory/cloud/sync-daemon.js';
 import { wireHooks } from './hooks/hook-commands.js';
 import { PROJECT_REGISTRY_FILE, parseProjectRegistry, projectCandidates, } from '@reticlehq/core/artifacts';
 import { discoverProjectConfigs } from './command/cli/config/config-discovery.js';
 import { artifactRootResolver } from './memory/project/artifact-root-resolver.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 { AGENT_STOPPED_NOTICE, RETICLE_DEFAULT_PORT, bridgeWsUrl, ReticleCommand, ReticleDir, ReticleEnv, LOOPBACK_HOST, ReplayStatus, EventType, } from '@reticlehq/core';
 import { originOf } from './portal/session/session-manager.js';
 import { setBrowserMode, BrowserMode } from './telemetry/browser-mode.js';
 import { replayAndLearn } from './language/flows/flow-learning.js';
@@ -25,6 +25,7 @@ import { SERVER_VERSION } from './command/version/identity/server-version.js';
 import { BaselineStore } from './memory/project/baselines.js';
 import { RecordingStore } from './language/flows/recording/tape/recordings.js';
 import { initImpact } from './memory/impact/impact-recorder.js';
+import { flowAuthor } from './language/flows/flow-author.js';
 import { FlowStore } from './language/flows/flows.js';
 import { buildFlowChips } from './language/flows/flow-scope.js';
 import { ProjectStore } from './memory/project/project-store.js';
@@ -42,7 +43,7 @@ import { LEASE_ACQUIRE_TOOL } from './surface/tools/lease-tools.js';
 import { runTool } from './surface/tools/invoke-tool.js';
 import { SessionReaper, endAllSessions, MCP_DISCONNECT_SUMMARY, } from './portal/session/session-reaper.js';
 import { wireSessionScope } from './portal/session/no-session-watch.js';
-import { buildIdlePredicate } from './command/daemon/lifetime/daemon-usefulness.js';
+import { buildIdlePredicate, noteSetupHold } from './command/daemon/lifetime/daemon-usefulness.js';
 import { resolveToolSurface } from './surface/tools/tool-surface.js';
 import { statusPayload } from './status-payload.js';
 import { CdpRealInputProvider, LaunchedRealInputProvider } from './portal/input/real-input.js';
@@ -51,19 +52,16 @@ import { BrowserPool } from './portal/pool/browser-pool.js';
 import { AGENT_ALREADY_DRIVING_ELSEWHERE, shouldGreetWithLeaseNotice, } from './portal/session/lease-visibility.js';
 import { playwrightLauncher, resolveMaxContexts } from './portal/pool/playwright-launcher.js';
 import { LeaseReaper } from './portal/pool/lease-reaper.js';
-import { readJournalEnabled, readProjectId } from './command/cli/ports/resolve/cli-port.js';
-import { hasProjectConnectedBefore } from './memory/recall/prior/connection-memory.js';
+import { findProjectConfig, projectIdsAt, readJournalEnabled, readProjectId, } from './command/cli/ports/resolve/cli-port.js';
+import { hasAnyProjectConnectedBefore } from './memory/recall/prior/connection-memory.js';
 import { reticleStateHome } from './command/daemon/daemon.js';
-import { probeChromium } from './command/cli/doctor/browser/chromium-hint.js';
-import { makeJournalAttach } from './memory/journal/attach-journal.js';
-import { makeSessionEnd, recordDriveRun } from './memory/journal/session-end.js';
-import { attachDriveRunFlush } from './memory/journal/drive-run-flush.js';
+import { probeLaunchableChromium } from './launch-chromium.js';
+import { attachJournal } from './wire-journal.js';
 import { reportOnboardingStep } from './telemetry/onboarding-funnel.js';
 import { AMBIENT_RECORDING } from './language/flows/recording/tape/recordings.js';
-import { AmbientStore } from './memory/journal/ambient-store.js';
-import { ensureWorkspaceGitignore } from './memory/journal/on-disk/workspace-gitignore.js';
-import { pruneFeedback, pruneSessions, pruneVisualDiffs, } from './memory/journal/on-disk/retention.js';
+import { readRetainPolicy } from './memory/journal/on-disk/retain-policy.js';
 import { log } from './log.js';
+import { readReaderBundle, zeroInstallScript as zeroInstallScriptFor, } from './portal/pool/zero-install.js';
 /** A human-facing one-liner for a panel replay verdict — ✓ passed / ⚠ drifted / ✗ errored. */
 function replayVerdictLine(result) {
     if (result.status === ReplayStatus.OK)
@@ -83,10 +81,19 @@ export { buildSessionRecommendation } from './portal/session/presence/session-re
 export { TOOLS } from './surface/tools/tools.js';
 export { createToolInvoker, UNKNOWN_TOOL_ERROR } from './surface/tools/tool-invoker.js';
 export { runTool, SESSION_BOUND_TOOLS, SESSION_EXEMPT_TOOLS } from './surface/tools/invoke-tool.js';
+/**
+ * The port-presence check the CLI commands (`drive`, `verify`, `status`, `doctor`, `kill`) all share,
+ * re-exported so a consumer embedding `start()` in its own process can refuse a taken port the same
+ * honest way instead of letting a raw `EADDRINUSE` stack out — the gap `@reticlehq/test`'s
+ * `bootSession()` had (reticlehq/reticle#1141): it called `start()` directly with no pre-flight probe.
+ */
+export { probePresence, describePresence, PortPresence, } from './command/daemon/binding/port-presence.js';
+export { probeDaemon } from './surface/mcp/proxy/proxy-daemon-probe.js';
+export { fetchStatus } from './command/daemon/binding/daemon-status-probe.js';
 export { BaselineStore, normalizeLines, diffLines } from './memory/project/baselines.js';
 export { RecordingStore } from './language/flows/recording/tape/recordings.js';
 export { FlowStore, recordedStepToFlowStep } from './language/flows/flows.js';
-export { assertSuccess, successToPredicate, dynamicTestids, successLabel, } from './language/flows/flow-success.js';
+export { assertSuccess, dynamicTestids, successLabel, successToPredicate, } from './language/flows/flow-success.js';
 export { classifyFlowAssertions, FlowAssertionGrade } from './language/flows/flow-classify.js';
 export { buildDomainModel } from './judgement/domain/domain-model.js';
 export { ProjectStore } from './memory/project/project-store.js';
@@ -108,12 +115,29 @@ export { resolveBridgeSecurity } from './portal/bridge/bridge-security.js';
  * Build the shared browser pool (one headless Chromium, N capped isolated leased contexts). Lazy —
  * no Chromium launches until the first lease — so creating it is free even when never used.
  */
-function createBrowserPool(headless) {
+/** Where the zero-install reader connects: this daemon's own bridge, with its pairing token. */
+function readerConnect(port, token) {
+    return { url: bridgeWsUrl(port), ...(token === undefined ? {} : { token }) };
+}
+function createBrowserPool(headless, reader) {
     const maxContexts = resolveMaxContexts(process.env[ReticleEnv.MAX_CONTEXTS], cpus().length);
     const genSessionId = () => `lease-${'function' === typeof globalThis.crypto?.randomUUID
         ? globalThis.crypto.randomUUID()
         : String(Date.now())}`;
-    return new BrowserPool(playwrightLauncher({ headless }), { maxContexts, genSessionId });
+    // Built on first use and kept: the page that needs it is one whose app never connected.
+    let script;
+    const zeroInstallScript = () => {
+        if (script === undefined) {
+            const bundle = readReaderBundle();
+            script = bundle === undefined ? null : zeroInstallScriptFor(bundle, reader);
+        }
+        return script ?? undefined;
+    };
+    return new BrowserPool(playwrightLauncher({ headless }), {
+        maxContexts,
+        genSessionId,
+        zeroInstallScript,
+    });
 }
 /**
  * Route CDP-authoritative network detail onto the driven session's journal.
@@ -153,82 +177,6 @@ function makeNetworkDetailRouter(bridge, driveUrl) {
         }
     };
 }
-/**
- * Wire journal capture, ambient seeding and the journal-tail flush onto a bridge.
- *
- * Both entry points need all three, and both used to hand-roll them. `startDaemon` only ever wired the
- * first, so on the path every user actually takes (`reticle serve` / `reticle mcp`) the journal tail was
- * dropped at session end and the learned ambient map was never persisted OR seeded — meaning ambient
- * learning could not converge across sessions and the last events of every session were lost. The two
- * call sites had already drifted once before, which is why this is one function rather than a
- * copy-paste both are asked to keep in step.
- */
-function attachJournal(bridge, deps) {
-    const journalAttach = makeJournalAttach(deps);
-    const ambientStore = new AmbientStore(deps.fs, deps.reticleRoot);
-    // Built once, not per session: the resolver walks config discovery and the user-level registry,
-    // and neither changes between two tabs connecting a second apart.
-    const resolveArtifactRoot = artifactRootResolver(deps.reticleRoot);
-    bridge.attachSessionCreate((session) => {
-        // Stamp the project's own `.reticle` before ANY counter fires for this session. Without it every
-        // verdict is recorded against wherever the daemon was started, which is how one app's evidence
-        // reached a different account's production dashboard.
-        // The origin is passed for the case where the page never stamped a project id: it is the only
-        // distinguishing fact left, and without it every such app shares one bucket.
-        session.artifactRoot = resolveArtifactRoot(session.projectId, originOf(session.url)).root;
-        // Here rather than on the start path, which was neither the moment we were about to write into a
-        // repository nor the root we were about to write into: it created `.reticle/` — holding nothing
-        // but the ignore file — wherever the daemon was launched, coming back every boot after the user
-        // deleted it, while the journals this ignore protects landed in another tree, uncovered.
-        if (deps.enabled)
-            void ensureWorkspaceGitignore(deps.fs, session.artifactRoot);
-        journalAttach(session);
-        // Seed the learned ambient map so a fresh session starts knowing which regions churn, instead of
-        // re-learning from zero. Best-effort + async: a late seed still helps, a failure is silent.
-        if (deps.enabled) {
-            void ambientStore
-                .load()
-                .then((counts) => session.seedAmbient(counts))
-                .catch(() => undefined);
-        }
-    });
-    // Teardown: flush the journal tail to disk + persist what this session learned.
-    bridge.attachSessionEnd(makeSessionEnd({
-        ...deps,
-        // Retention runs from teardown, and it must not delete the journal of a session that is still
-        // being written. The registry is the only thing that knows which those are.
-        liveSessionIds: () => new Set(bridge.sessions.all().map((s) => s.id)),
-    }));
-    /*
-     * And the same write, DURING the session rather than only at the end of it.
-     *
-     * Teardown was the only writer of a run artifact, so every verdict produced while a tab stayed
-     * open was invisible to cloud sync — which can only push artifacts that exist. Reported as "sync
-     * is not happening" and diagnosed as the agent forgetting to sync; there is no sync command to
-     * forget. The evidence simply was not on disk yet.
-     *
-     * Safe to call repeatedly because the run id is derived from the session, so this rewrites one
-     * artifact rather than accumulating them — a property `recordDriveRun` already had, for the
-     * unrelated reason that a reconnecting tab must not publish two overlapping rows.
-     */
-    if (deps.enabled) {
-        attachDriveRunFlush({
-            resolve: (sessionId) => bridge.sessions.get(sessionId),
-            write: (session) => recordDriveRun(deps, session),
-        });
-    }
-    if (deps.enabled) {
-        // Empty in the ordinary case (nothing has connected yet), but this path also runs on a daemon
-        // that is already serving sessions.
-        void pruneSessions(deps.fs, deps.reticleRoot, {
-            live: new Set(bridge.sessions.all().map((s) => s.id)),
-        });
-        // The largest thing in the workspace, and until now the only one with no delete path at all.
-        void pruneVisualDiffs(deps.fs, deps.reticleRoot);
-        // Write-only local copies of reports the outbox already carries.
-        void pruneFeedback(deps.fs, deps.reticleRoot);
-    }
-}
 /**
  * Resolve the drive/real-input provider from options — shared by start and startDaemon so the
  * precedence (driveUrl launch+own → CDP attach → none) and the storageState/injectConnect plumbing
@@ -325,6 +273,8 @@ function knownProjectRoots() {
     }
     return [...roots];
 }
+/** This project's platform credential (stored, else the env key), as the env the platform readers take. */
+const platformEnvFor = (root) => platformEnvPort(createNodeFileSystem(), root ?? join(process.cwd(), ReticleDir.ROOT), homedir(), process.env);
 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
@@ -335,7 +285,7 @@ export async function start(options = {}) {
         // The daemon owns both sides of this seam, so it is the layer that may join them: the cache
         // lives in cloud memory, the platform read lives in the harness feature, and neither is allowed
         // to reach for the other.
-        config: harnessConfigSource(() => fetchPlatformConfig(process.env)),
+        config: harnessConfigSource(async () => fetchPlatformConfig(await platformEnvFor(options.reticleRoot)())),
     });
     const uninstallHooks = wireHooks(options.reticleRoot ?? join(process.cwd(), ReticleDir.ROOT), readProjectId(process.cwd()));
     const security = await resolveBridgeSecurityWithAutoToken(options);
@@ -364,21 +314,26 @@ export async function start(options = {}) {
         const fs = createNodeFileSystem();
         const reticleRoot = options.reticleRoot ?? join(process.cwd(), ReticleDir.ROOT);
         const now = options.now ?? (() => Date.now());
-        const journalEnabled = readJournalEnabled(process.cwd(), process.env[ReticleEnv.JOURNAL]);
+        const retain = readRetainPolicy(findProjectConfig(process.cwd()));
+        // `retain.sessions: 0` says keep no journals. Honoured at CAPTURE as well as at the sweep —
+        // writing a directory in order to delete it on the way out is work nobody asked for.
+        const journalEnabled = readJournalEnabled(process.cwd(), process.env[ReticleEnv.JOURNAL]) && 0 < retain.sessions;
         const flows = new FlowStore(fs, reticleRoot, { now });
         attachJournal(bridge, {
             fs,
             reticleRoot,
             enabled: journalEnabled,
+            retain,
             // Bound HERE, where the recorder is already in hand: teardown gets the tape, not the recorder.
             takeAmbientTape: () => recordings.stop(AMBIENT_RECORDING),
             reportStep: reportOnboardingStep,
             flows,
+            author: flowAuthor,
         });
         const project = new ProjectStore(fs, reticleRoot, { now });
         attachRouteLearning(bridge, projectStoreResolver(fs, project, reticleRoot, now));
         const annotations = new AnnotationStore();
-        pool = createBrowserPool(options.headless ?? true);
+        pool = createBrowserPool(options.headless ?? true, readerConnect(port, security.token));
         leaseReaper = new LeaseReaper(pool);
         leaseReaper.start();
         /*
@@ -410,16 +365,23 @@ export async function start(options = {}) {
             project,
             fs,
             reticleRoot,
+            linkedCloud: linkedCloudPort(fs, reticleRoot, homedir(), process.env),
             artifactRootFor: artifactRootResolver(reticleRoot),
             now,
             bridgePort: port,
-            browserProbe: probeChromium,
+            browserProbe: probeLaunchableChromium,
             // The daemon's OWN project, so a tool can tell "this session is mine" from "this session
             // belongs to a sibling app under the same daemon". contract_save refuses on the second.
             ...(activeProjectId === undefined ? {} : { projectId: activeProjectId }),
         };
         const profile = resolveToolSurface(options.toolProfile);
-        const server = createMcpServer(realInput !== undefined ? { ...deps, realInput } : deps, profile, hasProjectConnectedBefore(reticleStateHome(), port, activeProjectId));
+        const server = createMcpServer(realInput !== undefined ? { ...deps, realInput } : deps, profile, 
+        // A session live RIGHT NOW is stronger evidence than the durable memory, which can be empty or
+        // stale for a project the plugin wired without writing `.reticle.json` (see connection-memory.ts's
+        // KNOWN LIMIT). Without this OR, that project's `initialize` led with the first-install steps
+        // while a real session was already connected — see #1138.
+        bridge.sessions.count() > 0 ||
+            hasAnyProjectConnectedBefore(reticleStateHome(), port, projectIdsAt(process.cwd())));
         // When the agent (the MCP client) disconnects cleanly, end every active session at once so the
         // HUD doesn't linger. (If the agent instead KILLS this process, the WS dies and the browser
         // self-ends via SESSION_LIFECYCLE.BRIDGE_LOST_MS — see transport.ts.)
@@ -462,7 +424,7 @@ export async function startDaemon(options = {}) {
         // The daemon owns both sides of this seam, so it is the layer that may join them: the cache
         // lives in cloud memory, the platform read lives in the harness feature, and neither is allowed
         // to reach for the other.
-        config: harnessConfigSource(() => fetchPlatformConfig(process.env)),
+        config: harnessConfigSource(async () => fetchPlatformConfig(await platformEnvFor(options.reticleRoot)())),
     });
     const security = await resolveBridgeSecurityWithAutoToken(options);
     const shared = createSharedServer(security.token === undefined ? {} : { token: security.token });
@@ -478,7 +440,12 @@ export async function startDaemon(options = {}) {
     // answers WHY rather than just "sessionCount: 0".
     // `verifyPort` rides along so a later `serve --http` can tell whether this daemon already honours
     // the requested `--http-port` instead of silently ignoring the flag (#687).
-    shared.attachStatus(() => statusPayload(bridge.sessions.count(), bridge.sessions.list(), bridge.sessions.noSessionHint(), verifyHttp?.port, bridge.sessions.noSessionLead()));
+    shared.attachStatus((held) => {
+        // `init` holds the daemon it is waiting on, so the idle rule cannot shut it down mid-wait.
+        if (held)
+            noteSetupHold(Date.now());
+        return statusPayload(bridge.sessions.count(), bridge.sessions.list(), bridge.sessions.noSessionHint(), verifyHttp?.port, bridge.sessions.noSessionLead());
+    });
     // Agent-independent presence: the daemon outlives any single agent, so when the LAST agent's MCP
     // connection drops (it stopped, or is waiting on the human), end every session and push a clear
     // "go to your terminal" notice to the panel — the human is on the browser and must not lose a typed
@@ -497,7 +464,9 @@ export async function startDaemon(options = {}) {
     const fs = createNodeFileSystem();
     const reticleRoot = options.reticleRoot ?? join(process.cwd(), ReticleDir.ROOT);
     const now = options.now ?? (() => Date.now());
-    const journalEnabled = readJournalEnabled(process.cwd(), process.env[ReticleEnv.JOURNAL]);
+    const retain = readRetainPolicy(findProjectConfig(process.cwd()));
+    // See the sibling path: `retain.sessions: 0` stops the capture too, not only the sweep.
+    const journalEnabled = readJournalEnabled(process.cwd(), process.env[ReticleEnv.JOURNAL]) && 0 < retain.sessions;
     const flows = new FlowStore(fs, reticleRoot, { now });
     // Built here rather than inside `deps` below, so teardown can save what a drive recorded. Both
     // paths pass the same pair — `daemon-parity.test.ts` is what keeps them from drifting apart.
@@ -514,15 +483,17 @@ export async function startDaemon(options = {}) {
         fs,
         reticleRoot,
         enabled: journalEnabled,
+        retain,
         takeAmbientTape: () => recordings.stop(AMBIENT_RECORDING),
         reportStep: reportOnboardingStep,
         flows,
+        author: flowAuthor,
         onRunPersisted: () => syncNudge.run?.(),
     });
     const project = new ProjectStore(fs, reticleRoot, { now });
     attachRouteLearning(bridge, projectStoreResolver(fs, project, reticleRoot, now));
     const annotations = new AnnotationStore();
-    const pool = createBrowserPool(options.headless ?? true);
+    const pool = createBrowserPool(options.headless ?? true, readerConnect(port, security.token));
     const leaseReaper = new LeaseReaper(pool);
     leaseReaper.start();
     /*
@@ -556,7 +527,7 @@ export async function startDaemon(options = {}) {
     // console and the panel cannot disagree about a setting they both offer. Nothing is awaited and a
     // failure is not surfaced: the next snapshot re-reads the platform, so a lost write shows up as
     // the switch springing back, which is the truthful outcome.
-    bridge.attachHarnessRequest((enabled) => void writeHarnessSwitch(process.env, enabled));
+    bridge.attachHarnessRequest((enabled) => void platformEnvFor(reticleRoot)().then((env) => writeHarnessSwitch(env, enabled)));
     // Scope auto-selection to the active project (from .reticle.json) so a stray tab from another app is
     // never picked when the agent omits a sessionId. Explicit per-call scope/sessionId still overrides.
     // Scope + the no-session diagnosis: "no browser session connected" is the error that ends most
@@ -588,7 +559,7 @@ export async function startDaemon(options = {}) {
         artifactRootFor: artifactRootResolver(reticleRoot),
         now,
         bridgePort: port,
-        browserProbe: probeChromium,
+        browserProbe: probeLaunchableChromium,
         // A finished verification should not sit behind a one-minute timer — see ToolDeps.onRunPersisted.
         onRunPersisted: () => cloudSync.nudge(),
     };
@@ -596,7 +567,10 @@ export async function startDaemon(options = {}) {
     const effectiveDeps = realInput !== undefined ? { ...deps, realInput } : deps;
     // Read per attach, not once: a project that gets wired while this daemon is alive should stop
     // being told to wire itself on the next agent that connects.
-    shared.attachMcp(() => createMcpServer(effectiveDeps, profile, hasProjectConnectedBefore(reticleStateHome(), port, readProjectId(process.cwd()))));
+    shared.attachMcp(() => createMcpServer(effectiveDeps, profile, 
+    // See the sibling call in `start`: a live session outweighs empty/stale durable memory (#1138).
+    bridge.sessions.count() > 0 ||
+        hasAnyProjectConnectedBefore(reticleStateHome(), port, projectIdsAt(process.cwd()))));
     // `reticle drive <url>` when this daemon already owns the port: it asks HERE instead of trying to
     // bind a port we are holding, and gets the same pooled context an agent's reticle_lease returns —
     // through runTool, so it is counted and reported like any other call rather than being a second,
@@ -698,7 +672,7 @@ export async function startDaemon(options = {}) {
             if (vh !== undefined)
                 await new Promise((resolve) => vh.server.close(() => resolve()));
             leaseReaper.stop();
-            cloudSync.stop();
+            await cloudSync.flush(); // not stop(): the last run written is the one nobody has yet
             await loopbackAlias.close?.();
             await pool.shutdown();
             await owned?.dispose();

package/dist/judgement/capsule/capsule-store.d.ts

@@ -29,6 +29,18 @@ declare const CapsuleSchema: z.ZodObject<{
     observed: z.ZodString;
     /** Minimal steps to reproduce (prefix-trimmed). */
     steps: z.ZodArray<z.ZodType<FlowStep, z.ZodTypeDef, FlowStep>, "many">;
+    /**
+     * How many times this exact failure has been captured, and when it last was.
+     *
+     * A repeat is not a new capsule -- it is the same one, again. "This failed 37 times, most
+     * recently at T" is strictly MORE than 37 files each holding one timestamp, so folding the
+     * duplicates in adds information rather than discarding it.
+     *
+     * Optional, because a capsule written before these existed has neither and must not be read as
+     * though it were seen once when nobody counted.
+     */
+    seen: z.ZodOptional<z.ZodNumber>;
+    lastSeenAt: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
     expected: string;
     origin: string;
@@ -38,6 +50,8 @@ declare const CapsuleSchema: z.ZodObject<{
     createdAt: number;
     observed: string;
     flow?: string | undefined;
+    seen?: number | undefined;
+    lastSeenAt?: number | undefined;
 }, {
     expected: string;
     origin: string;
@@ -47,6 +61,8 @@ declare const CapsuleSchema: z.ZodObject<{
     createdAt: number;
     observed: string;
     flow?: string | undefined;
+    seen?: number | undefined;
+    lastSeenAt?: number | undefined;
 }>;
 export type Capsule = z.infer<typeof CapsuleSchema>;
 /** Capsule ids are filenames — refuse anything that could escape the capsules directory. */
@@ -63,8 +79,21 @@ export declare class CapsuleStore {
     /** Every readable capsule, newest-first — what `reticle capsules` prints. */
     all(): Promise<Capsule[]>;
 }
-/** Deterministic, path-safe capsule id: time-ordered so `list` sorts newest-first for free. */
-export declare function capsuleId(now: number, label: string): string;
+/**
+ * What makes two captures the SAME failure.
+ *
+ * Everything that describes the failure, and nothing that describes the capture: `createdAt` is
+ * excluded because it is precisely what turned every retry of a broken step into a new file, and
+ * `id` because it is derived from this. `flow` is included -- the same assertion failing in two
+ * different journeys is two findings, not one.
+ */
+export declare function capsuleFingerprint(capsule: Omit<Capsule, 'id' | 'createdAt' | 'seen' | 'lastSeenAt'>): string;
+/**
+ * Deterministic, path-safe capsule id: time-ordered so `list` sorts newest-first for free, with the
+ * fingerprint on the END so a duplicate can be found by listing the directory rather than reading
+ * every file in it.
+ */
+export declare function capsuleId(now: number, label: string, fingerprint: string): string;
 /** The minimal reproduction: the steps up to and including the one that failed (prefix trim). */
 export declare function minimalSteps(steps: readonly FlowStep[], failedIndex: number): FlowStep[];
 export {};

package/dist/judgement/capsule/capsule-store.js

@@ -1,4 +1,6 @@
 import { join } from 'node:path';
+import { fnv1a } from '@reticlehq/core';
+import { writeFileAtomic } from '../../memory/project/fs/write-atomic.js';
 import { z } from 'zod';
 import { FlowStepSchema } from '@reticlehq/core';
 import { reticleDirPaths } from '../../memory/project/dir/reticle-dir.js';
@@ -30,6 +32,18 @@ const CapsuleSchema = z.object({
     observed: z.string(),
     /** Minimal steps to reproduce (prefix-trimmed). */
     steps: z.array(FlowStepSchema),
+    /**
+     * How many times this exact failure has been captured, and when it last was.
+     *
+     * A repeat is not a new capsule -- it is the same one, again. "This failed 37 times, most
+     * recently at T" is strictly MORE than 37 files each holding one timestamp, so folding the
+     * duplicates in adds information rather than discarding it.
+     *
+     * Optional, because a capsule written before these existed has neither and must not be read as
+     * though it were seen once when nobody counted.
+     */
+    seen: z.number().int().positive().optional(),
+    lastSeenAt: z.number().optional(),
 });
 /** Capsule ids are filenames — refuse anything that could escape the capsules directory. */
 export function isValidCapsuleId(id) {
@@ -51,9 +65,26 @@ export class CapsuleStore {
             return false;
         try {
             await this.#fs.mkdir(this.#dir);
-            const tmp = `${this.#pathFor(capsule.id)}.tmp`;
-            await this.#fs.writeFile(tmp, `${JSON.stringify(capsule, null, 2)}\n`);
-            await this.#fs.rename(tmp, this.#pathFor(capsule.id));
+            /*
+             * A capture of a failure already on disk folds into it rather than adding a file. Found by
+             * LISTING: the fingerprint is the id's suffix, so this costs one directory read instead of
+             * one read per capsule. An id written before fingerprints existed simply never matches, which
+             * is the correct outcome -- it is left exactly as it was.
+             *
+             * `createdAt` keeps the FIRST sighting. A repeat is the same failure happening again, not a
+             * new one, and the interesting pair is when it started and when it last happened.
+             */
+            const fingerprint = capsuleFingerprint(capsule);
+            const existingId = (await this.list()).find((id) => id.endsWith(`-${fingerprint}`));
+            const previous = existingId === undefined ? undefined : await this.read(existingId);
+            const folded = previous === undefined
+                ? { ...capsule, seen: 1, lastSeenAt: capsule.createdAt }
+                : {
+                    ...previous,
+                    seen: (previous.seen ?? 1) + 1,
+                    lastSeenAt: capsule.createdAt,
+                };
+            await writeFileAtomic(this.#fs, this.#pathFor(folded.id), `${JSON.stringify(folded, null, 2)}\n`);
             return true;
         }
         catch {
@@ -100,10 +131,31 @@ export class CapsuleStore {
         return out;
     }
 }
-/** Deterministic, path-safe capsule id: time-ordered so `list` sorts newest-first for free. */
-export function capsuleId(now, label) {
+/**
+ * What makes two captures the SAME failure.
+ *
+ * Everything that describes the failure, and nothing that describes the capture: `createdAt` is
+ * excluded because it is precisely what turned every retry of a broken step into a new file, and
+ * `id` because it is derived from this. `flow` is included -- the same assertion failing in two
+ * different journeys is two findings, not one.
+ */
+export function capsuleFingerprint(capsule) {
+    return fnv1a(JSON.stringify([
+        capsule.flow ?? '',
+        capsule.origin,
+        capsule.expected,
+        capsule.observed,
+        capsule.steps,
+    ]));
+}
+/**
+ * Deterministic, path-safe capsule id: time-ordered so `list` sorts newest-first for free, with the
+ * fingerprint on the END so a duplicate can be found by listing the directory rather than reading
+ * every file in it.
+ */
+export function capsuleId(now, label, fingerprint) {
     const safe = label.replace(/[^a-zA-Z0-9._-]/g, '-').slice(0, 40);
-    return `${String(now)}-${safe.length > 0 ? safe : 'capsule'}`;
+    return `${String(now)}-${safe.length > 0 ? safe : 'capsule'}-${fingerprint}`;
 }
 /** The minimal reproduction: the steps up to and including the one that failed (prefix trim). */
 export function minimalSteps(steps, failedIndex) {

package/dist/judgement/capsule/capsule.js

@@ -1,4 +1,5 @@
 import { ConsequenceKind, EventType } from '@reticlehq/core';
+import { isDocumentInitiated } from '@reticlehq/engine/question/predicate/predicate-eval.js';
 import { causalSummary } from './causal-summary.js';
 import { firstDivergence } from './divergence.js';
 /**
@@ -34,6 +35,10 @@ export function blastRadius(expected, observed) {
                 continue;
             if (declaredUrls.some((fragment) => url.includes(fragment)))
                 continue;
+            // A subresource the document fetched is the page loading, not a request the action sent: one
+            // navigation is a couple of hundred of them. IPC and beacons carry an initiator too, and stay.
+            if (isDocumentInitiated(event))
+                continue;
             const method = event.data['method'];
             add(`net ${'string' === typeof method ? method : 'request'} ${url}`);
             continue;

package/dist/judgement/capsule/causal-summary.d.ts

@@ -63,6 +63,18 @@ export interface CausalSummary {
     elided?: Partial<Record<CappedList, number>>;
     route?: string;
     signals: string[];
+    /**
+     * Form fields whose value moved in this window, by NAME.
+     *
+     * Names only, never values: a form is where somebody types their password, and the observer that
+     * reports this already refuses to carry one. The names are what an assertion is written against,
+     * and a field moving when nothing should have touched it (or not moving when something should)
+     * is the silently-cleared-field class — which until this channel existed left no trace at all,
+     * because React sets the input PROPERTY and MutationObserver watches attributes.
+     *
+     * Present only when a field moved, so a page with no form pays nothing.
+     */
+    fieldsChanged?: string[];
     layoutShift?: number;
     longTasks: number;
     /**
@@ -114,6 +126,6 @@ interface SummaryContext {
  */
 export declare const MAX_SUMMARY_ENTRIES = 20;
 /** The lists that are capped, named so `elided` can say which one lost entries. */
-type CappedList = 'statePathsChanged' | 'storageKeysChanged' | 'stateDiffs' | 'storageDiffs' | 'signals';
+type CappedList = 'statePathsChanged' | 'storageKeysChanged' | 'stateDiffs' | 'storageDiffs' | 'signals' | 'fieldsChanged';
 export declare function causalSummary(events: readonly ReticleEvent[], context?: SummaryContext): CausalSummary;
 export {};

package/dist/judgement/capsule/causal-summary.js

@@ -69,6 +69,7 @@ export function causalSummary(events, context = {}) {
     const storageDiffs = [];
     let route;
     const signals = [];
+    const fieldsChanged = [];
     let layoutShift;
     let longTasks = 0;
     for (const event of events) {
@@ -131,6 +132,9 @@ export function causalSummary(events, context = {}) {
             case EventType.SIGNAL:
                 pushUnique(signals, data['name']);
                 break;
+            case EventType.FIELD_CHANGE:
+                pushUnique(fieldsChanged, data['field']);
+                break;
             case EventType.PERF:
                 if (data['metric'] === PerfMetric.CLS && 'number' === typeof data['value']) {
                     layoutShift = Math.max(layoutShift ?? 0, data['value']);
@@ -163,6 +167,9 @@ export function causalSummary(events, context = {}) {
         storageDiffs: cap(storageDiffs, 'storageDiffs', elided),
         ...(route === undefined ? {} : { route }),
         signals: cap(signals, 'signals', elided),
+        ...(0 === fieldsChanged.length
+            ? {}
+            : { fieldsChanged: cap(fieldsChanged, 'fieldsChanged', elided) }),
         ...(0 === Object.keys(elided).length ? {} : { elided }),
         ...(layoutShift === undefined ? {} : { layoutShift }),
         longTasks,