@reticlehq/server 3.1.0 → 3.3.0

package/dist/memory/journal/on-disk/retention.js

@@ -1,5 +1,7 @@
-import { join } from 'node:path';
+import { basename, join } from 'node:path';
+import { ReticleDir } from '@reticlehq/core';
 import { reticleDirPaths, visualDir } from '../../project/dir/reticle-dir.js';
+import { EVIDENCE_DIRS } from './workspace-tiers.js';
 /** Keep at most this many session journals on disk; older ones are pruned by recency. */
 export const DEFAULT_SESSION_RETENTION = 20;
 /**
@@ -13,8 +15,70 @@ export const DEFAULT_DIFF_RETENTION = 10;
  */
 export const DEFAULT_FEEDBACK_RETENTION = 20;
 const DIFF_SUFFIX = '.diff.png';
-/** Where refused feedback reports are copied. Named here because the writer lives in another area. */
-const FEEDBACK_SUBDIR = 'feedback';
+const PNG_SUFFIX = '.png';
+/**
+ * The TOTAL the evidence tier of one `.reticle/` may occupy, across sessions, runs, overlay diffs
+ * and feedback copies together.
+ *
+ * Every bound above this line counts things, and a count cannot see a size: twenty session
+ * directories is twenty UNBOUNDED directories. A workspace in the field grew to multiple gigabytes
+ * with all three counts being honoured the whole time, because one drive against a chatty app
+ * appends response bodies and DOM text for as long as the drive lasts, and nothing was looking at
+ * the total.
+ *
+ * Why this number and not one an order of magnitude either side. An ordinary session journal is
+ * hundreds of kilobytes to a few megabytes; a long drive against an app with large JSON responses
+ * runs to tens. Twenty of the ordinary ones fit inside this budget outright, which is the working
+ * set somebody plausibly wants — the evidence a person reads is from the drive they are looking at
+ * and the two before it, and nobody has ever opened the twentieth. A tenth of this (~50 MB) is
+ * smaller than a single bad session, so the budget would evict the newest evidence while it was
+ * still being written and the count bound could never be reached; ten times it (~5 GB) is not a
+ * bound a laptop notices, and 5 GB of untouched journals is the same abandoned-Reticle report with
+ * a different number in it. This is roughly one node_modules: large enough to be invisible in a
+ * project checkout, small enough that it can never be the reason a disk fills.
+ *
+ * Both bounds stay, and they are independent on purpose. The count is the cheap guard — it needs one
+ * stat per entry and it keeps the directory listing readable. The budget is the guard that holds
+ * when the counts are all satisfied and the bytes are not, which is the only situation anybody has
+ * actually been hurt by. Either one alone leaves the other's failure unguarded.
+ */
+export const DEFAULT_EVIDENCE_BUDGET_BYTES = 512 * 1024 * 1024;
+/** No session is open. The default everywhere, so an existing caller keeps its old behaviour. */
+const NO_LIVE_SESSIONS = new Set();
+/**
+ * Is this entry the journal directory of a session that is STILL BEING WRITTEN?
+ *
+ * A session directory is named for its session id, so the id IS the basename. Scoped to the
+ * sessions tier on purpose: a run artifact or a diff that happens to share a session's name is not
+ * a journal, and nothing is holding it open.
+ */
+function isOpenSession(entry, live) {
+    return ReticleDir.SESSIONS_SUBDIR === entry.under && live.has(basename(entry.path));
+}
+/**
+ * Pure: the paths to remove so the EVIDENCE tier fits in `budgetBytes`. Oldest first, memory-tier
+ * entries never selected and never counted. No IO — the call site stats and removes, exactly as
+ * `selectPrunable` and `pruneByRecency` already split it.
+ */
+export function selectOverBudget(entries, budgetBytes, live = NO_LIVE_SESSIONS) {
+    const evidence = entries.filter((entry) => EVIDENCE_DIRS.includes(entry.under));
+    // Live sessions still COUNT — their bytes are on disk and the budget is about the disk. They are
+    // only excluded from the eviction list, so a session over budget on its own is left alone rather
+    // than deleted under its own writer.
+    let total = evidence.reduce((sum, entry) => sum + entry.sizeBytes, 0);
+    if (total <= budgetBytes)
+        return [];
+    const doomed = [];
+    for (const entry of [...evidence].sort((a, b) => a.mtimeMs - b.mtimeMs)) {
+        if (isOpenSession(entry, live))
+            continue;
+        if (total <= budgetBytes)
+            break;
+        doomed.push(entry.path);
+        total -= entry.sizeBytes;
+    }
+    return doomed;
+}
 /**
  * Pure: given session dirs with their mtimes, the names to remove so only the `retention` most-recent
  * remain. Oldest-first. Exported for testing (no IO).
@@ -71,10 +135,23 @@ async function pruneByRecency(fs, dir, retention, keep = () => true) {
  * Bound the journal on disk: keep the `retention` most-recent session directories under
  * `.reticle/sessions/`, remove the rest by mtime. Never throws — retention is best-effort maintenance,
  * so a stat/rm failure on one dir (or a missing sessions/ dir) is swallowed, never crashing a session.
- * Mirrors RunStore's amortized pruning; run on daemon start.
+ * Mirrors RunStore's amortized pruning; run on daemon start and at the end of every session.
+ *
+ * The COUNT bound only. This used to sweep the tier total as well, from when it was the single
+ * sweep both call sites used; `pruneWorkspace` is that single place now and runs the budget last,
+ * on purpose, so the leftover call here was a second walk of every evidence entry on every teardown
+ * — and it ran FIRST, sizing everything the counts were about to delete anyway.
+ *
+ * An open session is excluded from BOTH bounds — see `RetentionOptions.live`.
+ *
+ * ponytail: excluded via `keep`, so an open session is not COUNTED toward the retention cap either.
+ * The directory can therefore hold `retention` + (concurrently open sessions) entries, which is a
+ * handful. Count them separately only if somebody runs enough parallel sessions for it to matter.
  */
-export async function pruneSessions(fs, root, retention = DEFAULT_SESSION_RETENTION) {
-    await pruneByRecency(fs, reticleDirPaths(root).sessions, retention);
+export async function pruneSessions(fs, root, options = {}) {
+    const live = options.live ?? NO_LIVE_SESSIONS;
+    const retention = options.retention ?? DEFAULT_SESSION_RETENTION;
+    await pruneByRecency(fs, reticleDirPaths(root).sessions, retention, (name) => !live.has(name));
 }
 /**
  * Bound `.reticle/visual/` — the largest thing in the workspace, and the only one with no delete
@@ -91,20 +168,113 @@ export async function pruneSessions(fs, root, retention = DEFAULT_SESSION_RETENT
  * `pruneSessions`: this is maintenance, and maintenance must never be the reason a daemon fails.
  */
 export async function pruneVisualDiffs(fs, root, retention = DEFAULT_DIFF_RETENTION) {
+    for (const dir of await visualDirs(fs, root)) {
+        await pruneByRecency(fs, dir, retention, isDiff);
+    }
+}
+/** `visual/` plus its per-runtime subdirectories. Empty when nothing has been captured yet. */
+async function visualDirs(fs, root) {
     const top = visualDir(root);
     const dirs = [top];
     try {
         // A per-runtime subdirectory is anything here that is not itself a PNG.
         for (const entry of await fs.readdir(top)) {
-            if (!entry.endsWith('.png'))
+            if (!entry.endsWith(PNG_SUFFIX))
                 dirs.push(join(top, entry));
         }
     }
     catch {
-        return; // no visual dir yet
+        return [];
     }
-    for (const dir of dirs) {
-        await pruneByRecency(fs, dir, retention, (name) => name.endsWith(DIFF_SUFFIX));
+    return dirs;
+}
+const isDiff = (name) => name.endsWith(DIFF_SUFFIX);
+/**
+ * Bytes under `path`, summed recursively. A session journal is a DIRECTORY, and `stat` on one
+ * reports the dirent, not the megabytes of JSONL inside it.
+ *
+ * readdir-first because the port exposes no `isDirectory`: a readdir that fails is a file, and its
+ * own stat answers. Never throws — an unreadable entry contributes nothing, which can only make the
+ * sweep evict less than it should, never more.
+ */
+async function sizeOf(fs, path) {
+    let names;
+    try {
+        names = await fs.readdir(path);
+    }
+    catch {
+        try {
+            return (await fs.stat(path)).size;
+        }
+        catch {
+            return 0;
+        }
+    }
+    let total = 0;
+    for (const name of names)
+        total += await sizeOf(fs, join(path, name));
+    return total;
+}
+/**
+ * Every evidence entry in this `.reticle/`, sized and dated. The IO half of the byte budget.
+ *
+ * `visual/` is the one evidence directory holding something that is not evidence — the PNG
+ * BASELINES a comparison means anything against — so the same `.diff.png` filter `pruneVisualDiffs`
+ * applies is applied here. The tier list is the coarse rule; that filter is the finer one, and
+ * deleting a baseline to save disk turns the next run's verdict into `baseline-missing`.
+ */
+async function collectEvidence(fs, root) {
+    const entries = [];
+    for (const under of EVIDENCE_DIRS) {
+        const isVisual = ReticleDir.VISUAL_SUBDIR === under;
+        const dirs = isVisual ? await visualDirs(fs, root) : [join(root, under)];
+        for (const dir of dirs) {
+            let names;
+            try {
+                names = await fs.readdir(dir);
+            }
+            catch {
+                continue; // nothing written here yet
+            }
+            for (const name of names) {
+                if (isVisual && !isDiff(name))
+                    continue;
+                const path = join(dir, name);
+                try {
+                    const { mtimeMs } = await fs.stat(path);
+                    entries.push({ path, under, sizeBytes: await sizeOf(fs, path), mtimeMs });
+                }
+                catch {
+                    /* unreadable entry — skip */
+                }
+            }
+        }
+    }
+    return entries;
+}
+/**
+ * Hold the evidence tier of one `.reticle/` under a TOTAL byte budget, evicting oldest-first.
+ *
+ * The memory tier is not read, not counted and not touched: the maintainer's constraint is a cap
+ * that never stops memory and flows being created, so a full disk costs somebody their session
+ * journals and never their flows.
+ *
+ * Never throws, like everything else here. Retention is maintenance, and maintenance must never be
+ * the reason a daemon fails to come up or a session dies.
+ */
+export async function pruneEvidenceBudget(fs, root, budgetBytes = DEFAULT_EVIDENCE_BUDGET_BYTES, live = NO_LIVE_SESSIONS) {
+    try {
+        for (const path of selectOverBudget(await collectEvidence(fs, root), budgetBytes, live)) {
+            try {
+                await fs.rm(path);
+            }
+            catch {
+                /* best-effort */
+            }
+        }
+    }
+    catch {
+        /* maintenance never fails a daemon */
     }
 }
 /**
@@ -118,5 +288,5 @@ export async function pruneVisualDiffs(fs, root, retention = DEFAULT_DIFF_RETENT
  * retention rule is the same rule whether the directory holds journals, diffs or reports.
  */
 export async function pruneFeedback(fs, root, retention = DEFAULT_FEEDBACK_RETENTION) {
-    await pruneByRecency(fs, join(root, FEEDBACK_SUBDIR), retention);
+    await pruneByRecency(fs, join(root, ReticleDir.FEEDBACK_SUBDIR), retention);
 }

package/dist/memory/journal/on-disk/startup-maintenance.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Everything Reticle prunes in ONE `.reticle/` workspace, in one place.
+ *
+ * Called from two moments and both matter: daemon start (the daemon's own tree) and session end
+ * (the tree that SESSION wrote into). Those are usually different directories — a globally
+ * registered daemon stands in `$HOME` — and the per-project one is where the bytes actually
+ * accumulate, so sweeping only the first swept the wrong tree for the common case.
+ *
+ * The four bounds were inlined at the call site and one of them was simply missing:
+ * `pruneEvidenceBudget` had been written, tested, and never called by anything. The three COUNT
+ * bounds were wired and the BYTE bound was not, which is the combination the budget's own header
+ * warns about -- "twenty session directories is twenty UNBOUNDED directories", beside a field
+ * report of a multi-gigabyte `.reticle/sessions` with all three counts honoured throughout.
+ *
+ * Counts and bytes answer different questions and neither substitutes for the other. A count says
+ * how MANY sessions are kept; it says nothing about how large one is allowed to get. A chatty app
+ * writes one enormous journal and never trips a count.
+ *
+ * Gathered into a function rather than left as four statements so that "what maintenance runs at
+ * startup" has one answer that can be TESTED. Inlined, the only way to check the budget was wired
+ * was to grep the call site for its name -- and a grep passes on a comment that quotes the code,
+ * which has already happened in this repository.
+ *
+ * Order: counts first, budget last. The counts are cheap and bounded; the budget walks and sizes
+ * what the counts leave behind, so running it second means it sizes less.
+ *
+ * NEVER THROWS. Maintenance must not be the reason a daemon fails to come up, and each prune below
+ * already swallows its own errors -- this only has to avoid adding a new way to fail.
+ */
+import type { FileSystemPort } from '../../project/fs/fs-port.js';
+import { type RetainPolicy } from './retain-policy.js';
+/**
+ * What this sweep is allowed to keep. Every field optional, defaulting to the built-in bound.
+ *
+ * Partial rather than a whole `RetainPolicy` for two reasons that happen to agree: a test states
+ * only the bound it is exercising instead of writing half a gigabyte to disk, and a project's
+ * `.reticle.json` states only the bounds it cares about. Same reason the clock is injected
+ * everywhere else here — a bound that can only be exercised by producing the real quantity is a
+ * bound nothing exercises.
+ */
+export type PruneWorkspaceOptions = Partial<RetainPolicy>;
+export declare function pruneWorkspace(fs: FileSystemPort, root: string, live: ReadonlySet<string>, options?: PruneWorkspaceOptions): Promise<void>;

package/dist/memory/journal/on-disk/startup-maintenance.js

@@ -0,0 +1,14 @@
+import { pruneEvidenceBudget, pruneFeedback, pruneSessions, pruneVisualDiffs, } from './retention.js';
+import { DEFAULT_RETAIN } from './retain-policy.js';
+export async function pruneWorkspace(fs, root, live, options = {}) {
+    const retain = { ...DEFAULT_RETAIN, ...options };
+    // Empty in the ordinary case (nothing has connected yet); this path also runs on a daemon that is
+    // already serving sessions, which is why `live` is threaded rather than assumed empty.
+    await pruneSessions(fs, root, { live, retention: retain.sessions });
+    // The largest thing in the workspace, and for a long time the only one with no delete path.
+    await pruneVisualDiffs(fs, root, retain.visual);
+    // Write-only local copies of reports the outbox already carries.
+    await pruneFeedback(fs, root, retain.feedback);
+    // LAST, and the one that was missing: the only bound that limits SIZE rather than count.
+    await pruneEvidenceBudget(fs, root, retain.budgetBytes, live);
+}

package/dist/memory/journal/on-disk/workspace-gitignore.d.ts

@@ -1,6 +1,4 @@
 import type { FileSystemPort } from '../../project/fs/fs-port.js';
-/** Every name Reticle treats as machine-local, however it is spelled in the ignore file. */
-export declare const TRANSIENT_NAMES: readonly string[];
 /**
  * Write `.reticle/.gitignore` if it is not already there.
  *

package/dist/memory/journal/on-disk/workspace-gitignore.js

@@ -1,53 +1,21 @@
 import { join } from 'node:path';
 import { ReticleDir } from '@reticlehq/core';
+import { LOCAL_DIRS, LOCAL_FILES } from './workspace-tiers.js';
 /**
  * The `.reticle/` entries that are LOCAL state, and must never be committed by accident.
  *
- * Split from the durable half deliberately, and the split is the whole design: `contract.json`,
- * `flows/`, `intent.json` and `capsules/` are meant to be checked in — a flow that cannot be shared
- * is not a regression check anybody else can run — while everything below is per-machine churn.
+ * Read from the tier table rather than restated here: which half a name belongs to is one decision,
+ * and a second copy of it is the list that silently disagrees. This file asks the table exactly one
+ * of its two questions — `sharing` — and has no opinion at all about what retention may delete.
  *
  * The reason this matters beyond tidiness: a session journal carries URLs, request and response
  * bodies, and DOM text from the app under test. `.reticle/` is created by the daemon rather than by
  * the user, so it arrives untracked and unexplained, and one `git add -A` puts an app's traffic into
  * a shared repository. Reticle created the directory; the ignore for it is Reticle's to write.
  */
-/**
- * The local feedback copies — `.reticle/feedback/`.
- *
- * Named here rather than imported: the directory is spelled inline where it is written, in files
- * another agent owns, and the ignore for a directory Reticle creates is Reticle's to write whether
- * or not that name has been hoisted yet.
- */
-const FEEDBACK_SUBDIR = 'feedback';
-/** Local directories, without the trailing slash the ignore file wants. */
-const TRANSIENT_DIRS = [
-    ReticleDir.SESSIONS_SUBDIR,
-    ReticleDir.RUNS_SUBDIR,
-    ReticleDir.VISUAL_SUBDIR,
-    // Write-only: a local copy of what was already sent. The outbox is the record.
-    FEEDBACK_SUBDIR,
-];
-/** Local files. Exported with the directories as `TRANSIENT_NAMES`, which the partition guard reads. */
-const TRANSIENT_FILES = [
-    ReticleDir.PROJECT_FILE,
-    ReticleDir.AMBIENT_FILE,
-    ReticleDir.ENVELOPES_FILE,
-    ReticleDir.FLAKE_FILE,
-    ReticleDir.TIERS_FILE,
-    // The user's own record of what Reticle did for them, on THIS machine.
-    ReticleDir.IMPACT_FILE,
-    // This machine's conversation with the server. Its own doc comment says why committing it is
-    // harmful: one machine's pull cursor makes every other machine skip what it has not seen.
-    ReticleDir.CLOUD_STATE_FILE,
-    // Triage pulled back from the dashboard — a cache of somebody's decisions, re-pullable at will.
-    ReticleDir.ISSUES_FILE,
-];
-/** Every name Reticle treats as machine-local, however it is spelled in the ignore file. */
-export const TRANSIENT_NAMES = [...TRANSIENT_DIRS, ...TRANSIENT_FILES];
 const TRANSIENT = [
-    ...TRANSIENT_DIRS.map((dir) => `${dir}/`),
-    ...TRANSIENT_FILES,
+    ...LOCAL_DIRS.map((dir) => `${dir}/`),
+    ...LOCAL_FILES,
     '*.log',
     '*.tmp',
 ];

package/dist/memory/journal/on-disk/workspace-tiers.d.ts

@@ -0,0 +1,52 @@
+/**
+ * May retention delete this to reclaim disk?
+ *
+ * MEMORY is why `.reticle/` exists — what a flow replays from, what a deviation is measured
+ * against. It is small, it is never evicted, and it must keep being written however full the disk
+ * is. EVIDENCE is what one drive left behind: journals, run artifacts, pixel diffs. It is large, it
+ * ages out, and losing the oldest of it costs nothing anybody can name.
+ */
+export declare const Durability: {
+    readonly MEMORY: "memory";
+    readonly EVIDENCE: "evidence";
+};
+export type Durability = (typeof Durability)[keyof typeof Durability];
+/**
+ * Does this belong in the repository, or only on the machine that wrote it?
+ *
+ * COMMIT is the shareable half: a flow nobody else can replay is not a regression check. LOCAL is
+ * per-machine churn, and journals carry URLs, request and response bodies and page text from the
+ * app under test, so keeping them out of a shared repository is worth doing on its own account.
+ */
+export declare const Sharing: {
+    readonly COMMIT: "commit";
+    readonly LOCAL: "local";
+};
+export type Sharing = (typeof Sharing)[keyof typeof Sharing];
+/** What one `.reticle/` entry is, on both axes at once. */
+export interface WorkspaceTier {
+    readonly durability: Durability;
+    readonly sharing: Sharing;
+    /** A directory is ignored as `name/` and swept entry by entry; a file is neither. */
+    readonly isDirectory: boolean;
+}
+/**
+ * Every top-level name `.reticle/` can hold, classified on both axes.
+ *
+ * One list used to answer both questions with one answer, and they are not the same question.
+ * `capsules/` is committed — a fail-to-pass capsule a teammate cannot replay is not a regression
+ * check — AND it is evidence a drive left behind, which grows without bound. That cell did not
+ * exist, so the byte budget, which read the gitignore's list, structurally could not see capsules
+ * however large they got. Splitting the axes is what makes that sayable; it does not by itself say
+ * it, and `capsules/` stays MEMORY here until the budget is measured against it.
+ *
+ * Declaration order is the order the ignore file lists them, so the file a user already has on disk
+ * and the one written today are the same file.
+ */
+export declare const WORKSPACE_TIERS: Readonly<Record<string, WorkspaceTier>>;
+/** Machine-local directories, without the trailing slash the ignore file wants. */
+export declare const LOCAL_DIRS: readonly string[];
+/** Machine-local files. */
+export declare const LOCAL_FILES: readonly string[];
+/** The directories retention sweeps, ignored or not. The byte budget and the count bounds read this. */
+export declare const EVIDENCE_DIRS: readonly string[];

package/dist/memory/journal/on-disk/workspace-tiers.js

@@ -0,0 +1,88 @@
+import { ReticleDir } from '@reticlehq/core';
+/**
+ * May retention delete this to reclaim disk?
+ *
+ * MEMORY is why `.reticle/` exists — what a flow replays from, what a deviation is measured
+ * against. It is small, it is never evicted, and it must keep being written however full the disk
+ * is. EVIDENCE is what one drive left behind: journals, run artifacts, pixel diffs. It is large, it
+ * ages out, and losing the oldest of it costs nothing anybody can name.
+ */
+export const Durability = {
+    MEMORY: 'memory',
+    EVIDENCE: 'evidence',
+};
+/**
+ * Does this belong in the repository, or only on the machine that wrote it?
+ *
+ * COMMIT is the shareable half: a flow nobody else can replay is not a regression check. LOCAL is
+ * per-machine churn, and journals carry URLs, request and response bodies and page text from the
+ * app under test, so keeping them out of a shared repository is worth doing on its own account.
+ */
+export const Sharing = {
+    COMMIT: 'commit',
+    LOCAL: 'local',
+};
+const localDir = { durability: Durability.EVIDENCE, sharing: Sharing.LOCAL, isDirectory: true };
+const localFile = { durability: Durability.MEMORY, sharing: Sharing.LOCAL, isDirectory: false };
+const sharedDir = { durability: Durability.MEMORY, sharing: Sharing.COMMIT, isDirectory: true };
+const sharedFile = { durability: Durability.MEMORY, sharing: Sharing.COMMIT, isDirectory: false };
+/**
+ * Every top-level name `.reticle/` can hold, classified on both axes.
+ *
+ * One list used to answer both questions with one answer, and they are not the same question.
+ * `capsules/` is committed — a fail-to-pass capsule a teammate cannot replay is not a regression
+ * check — AND it is evidence a drive left behind, which grows without bound. That cell did not
+ * exist, so the byte budget, which read the gitignore's list, structurally could not see capsules
+ * however large they got. Splitting the axes is what makes that sayable; it does not by itself say
+ * it, and `capsules/` stays MEMORY here until the budget is measured against it.
+ *
+ * Declaration order is the order the ignore file lists them, so the file a user already has on disk
+ * and the one written today are the same file.
+ */
+export const WORKSPACE_TIERS = {
+    [ReticleDir.SESSIONS_SUBDIR]: localDir,
+    [ReticleDir.RUNS_SUBDIR]: localDir,
+    [ReticleDir.VISUAL_SUBDIR]: localDir,
+    // Write-only: a local copy of what was already sent. The outbox is the record.
+    [ReticleDir.FEEDBACK_SUBDIR]: localDir,
+    [ReticleDir.PROJECT_FILE]: localFile,
+    [ReticleDir.AMBIENT_FILE]: localFile,
+    [ReticleDir.ENVELOPES_FILE]: localFile,
+    [ReticleDir.FLAKE_FILE]: localFile,
+    [ReticleDir.TIERS_FILE]: localFile,
+    // The user's own record of what Reticle did for them, on THIS machine.
+    [ReticleDir.IMPACT_FILE]: localFile,
+    // This machine's conversation with the server. Its own doc comment says why committing it is
+    // harmful: one machine's pull cursor makes every other machine skip what it has not seen.
+    [ReticleDir.CLOUD_STATE_FILE]: localFile,
+    // Triage pulled back from the dashboard — a cache of somebody's decisions, re-pullable at will.
+    [ReticleDir.ISSUES_FILE]: localFile,
+    [ReticleDir.CONTRACT_FILE]: sharedFile,
+    [ReticleDir.FLOWS_SUBDIR]: sharedDir,
+    [ReticleDir.BASELINES_SUBDIR]: sharedDir,
+    [ReticleDir.CAPSULES_SUBDIR]: sharedDir,
+    [ReticleDir.INTENT_FILE]: sharedFile,
+    // The sharded form of the same ledger, and shared for the same reason.
+    [ReticleDir.INTENT_SUBDIR]: sharedDir,
+    [ReticleDir.CLOUD_LINK_FILE]: sharedFile,
+    // A hook is a decision the whole team shares, exactly like a package script: one that exists only
+    // on the machine that wrote it is a rule nobody else is following. It names COMMANDS and never a
+    // credential, so it is safe to commit — the same reasoning that puts `cloud.json` here while its
+    // API key stays in ~/.reticle.
+    [ReticleDir.HOOKS_FILE]: sharedFile,
+    // What a drive types into each labelled field. Committed for two reasons: a replay must send
+    // exactly what the recording sent or it is not a replay, and a value a model wrote once should be
+    // reviewable and editable by the team rather than regenerated differently on every machine.
+    [ReticleDir.FILL_VALUES_FILE]: sharedFile,
+};
+function namesWhere(match) {
+    return Object.entries(WORKSPACE_TIERS)
+        .filter(([, tier]) => match(tier))
+        .map(([name]) => name);
+}
+/** Machine-local directories, without the trailing slash the ignore file wants. */
+export const LOCAL_DIRS = namesWhere((tier) => Sharing.LOCAL === tier.sharing && tier.isDirectory);
+/** Machine-local files. */
+export const LOCAL_FILES = namesWhere((tier) => Sharing.LOCAL === tier.sharing && !tier.isDirectory);
+/** The directories retention sweeps, ignored or not. The byte budget and the count bounds read this. */
+export const EVIDENCE_DIRS = namesWhere((tier) => Durability.EVIDENCE === tier.durability && tier.isDirectory);

package/dist/memory/journal/route-template.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The key an envelope's statistics accumulate under.
+ *
+ * The envelope map was keyed on the raw `pathname`. On any app whose URLs carry ids — most of them —
+ * `/orders/1001` and `/orders/1002` are different keys, so every visit mints a fresh envelope
+ * holding one sample.
+ *
+ * The cost is not the file size. `deviation-report` skips any envelope below
+ * `MIN_ENVELOPE_SAMPLES`, so on such an app no envelope ever qualifies, every report answers
+ * "envelope too new", and the deviation feature never turns on at all — silently, permanently, with
+ * nothing anywhere saying why. The unbounded file and the dead feature are one defect.
+ *
+ * CONSERVATIVE on purpose. Over-collapsing is the worse error: merging two genuinely different
+ * routes builds a baseline from two different pages, and a confident comparison against the wrong
+ * population is more expensive than no comparison. So a segment is an id only when it could not
+ * plausibly be a route NAME.
+ *
+ * This is the statistics key alone. The observed path is untouched, because a report has to be able
+ * to say "/orders/1001 was slow" — the template tells you where to look, the path tells you what to
+ * open.
+ */
+export declare function routeTemplate(pathname: string): string;

package/dist/memory/journal/route-template.js

@@ -0,0 +1,44 @@
+/**
+ * The key an envelope's statistics accumulate under.
+ *
+ * The envelope map was keyed on the raw `pathname`. On any app whose URLs carry ids — most of them —
+ * `/orders/1001` and `/orders/1002` are different keys, so every visit mints a fresh envelope
+ * holding one sample.
+ *
+ * The cost is not the file size. `deviation-report` skips any envelope below
+ * `MIN_ENVELOPE_SAMPLES`, so on such an app no envelope ever qualifies, every report answers
+ * "envelope too new", and the deviation feature never turns on at all — silently, permanently, with
+ * nothing anywhere saying why. The unbounded file and the dead feature are one defect.
+ *
+ * CONSERVATIVE on purpose. Over-collapsing is the worse error: merging two genuinely different
+ * routes builds a baseline from two different pages, and a confident comparison against the wrong
+ * population is more expensive than no comparison. So a segment is an id only when it could not
+ * plausibly be a route NAME.
+ *
+ * This is the statistics key alone. The observed path is untouched, because a report has to be able
+ * to say "/orders/1001 was slow" — the template tells you where to look, the path tells you what to
+ * open.
+ */
+/** Stands in for any id segment. Not a valid path segment itself, so it cannot collide with one. */
+const ID = ':id';
+/** 8+ hex characters: a token, a hash, a short uuid. Below that it is as likely to be a word. */
+const LONG_HEX = /^[0-9a-f]{8,}$/i;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const ALL_DIGITS = /^\d+$/;
+/**
+ * A year collapses too, and that is a deliberate trade rather than an oversight: `/reports/2024`
+ * and `/reports/2025` are the same page with different data, which is exactly what one envelope
+ * should describe. Distinguishing a year from an id needs to know the app, and guessing would
+ * reintroduce the split this exists to remove.
+ */
+function isIdSegment(segment) {
+    return ALL_DIGITS.test(segment) || UUID.test(segment) || LONG_HEX.test(segment);
+}
+export function routeTemplate(pathname) {
+    if (0 === pathname.length)
+        return pathname;
+    return pathname
+        .split('/')
+        .map((segment) => (isIdSegment(segment) ? ID : segment))
+        .join('/');
+}

package/dist/memory/journal/self-observation.d.ts

@@ -0,0 +1,3 @@
+import { type ReticleEvent } from '@reticlehq/core';
+/** True when this event is the page fetching Reticle's own code rather than doing anything. */
+export declare function isSelfObservation(event: ReticleEvent): boolean;

package/dist/memory/journal/self-observation.js

@@ -0,0 +1,67 @@
+import { EventType, urlForMatch } from '@reticlehq/core';
+/**
+ * A request the page made for Reticle's OWN code, which the journal declines to keep.
+ *
+ * Measured over this repo's twenty recorded sessions: `net.request` is 64.6% of every journal byte
+ * and `net.detail` a further 17.6%, and the bulk of that is the browser fetching the SDK's module
+ * graph over and over as the dev server hot-reloads. Those bytes are Reticle watching itself arrive.
+ * They can never be evidence about the app under test, because the app did not ask for them — the
+ * instrumentation did, and it did so before the app had done anything worth verifying.
+ *
+ * The DOM side has drawn this line for a long time (`isReticleUi`), and the transport side draws it
+ * on the bridge socket's own path. This is the same line on the network channel.
+ *
+ * Identity, not resemblance. A request qualifies only when its PATH names our npm scope, which is
+ * the one thing about a URL that nobody else can be: `@reticlehq` is a registry scope we own, so a
+ * path segment under it is a file from one of our packages however it is being served — from
+ * `node_modules`, from a CDN, or through Vite's dep optimizer, which flattens the scope to
+ * `@reticlehq_browser.js`. A user's own file is never addressed that way.
+ *
+ * What this deliberately does NOT do is guess from shape. `/core/dist/index.js` and
+ * `/adapters/realm/browser/dist/index.js` are what this repo's own linked checkout serves, and
+ * matching those would collapse most of the bytes measured above — but they are ordinary paths that
+ * somebody else's app is entitled to serve, and a filter that drops a user's request to save our own
+ * bytes is the trade this project has already measured the cost of. So a source-linked checkout of
+ * Reticle itself keeps journaling its own SDK, and that is the correct side to be wrong on.
+ *
+ * Only the query string can carry a scope-shaped string that is really app data (a search for
+ * `@reticlehq/browser`), so the decision is taken on `pathname` alone.
+ */
+/** The npm scope directory, as it appears when the package is served from a tree. */
+const SCOPE_PATH = '/@reticlehq/';
+/**
+ * The same scope after Vite's dependency optimizer flattens `@scope/name` to one filename. Anchored
+ * at a segment boundary so it cannot match in the middle of somebody's filename.
+ */
+const SCOPE_FLATTENED = '/@reticlehq_';
+/**
+ * Every event kind that carries a request URL — all of them, on purpose.
+ *
+ * `reconcileNet` pairs a NET_PENDING with its NET_REQUEST by id and reports an unpaired pending as a
+ * HUNG request. Dropping one half of a pair would therefore manufacture a finding out of a request
+ * that completed perfectly. The rule is a pure function of the URL, so both halves of a pair always
+ * get the same answer and no pair can be split.
+ */
+const NET_TYPES = new Set([
+    EventType.NET_REQUEST,
+    EventType.NET_PENDING,
+    EventType.NET_DETAIL,
+    EventType.NET_STREAM,
+]);
+/** A base for parsing relative URLs. Never dereferenced — only the path is read. */
+const RELATIVE_BASE = 'http://reticle.invalid';
+function pathOf(url) {
+    try {
+        return new URL(url, RELATIVE_BASE).pathname;
+    }
+    catch {
+        return url;
+    }
+}
+/** True when this event is the page fetching Reticle's own code rather than doing anything. */
+export function isSelfObservation(event) {
+    if (!NET_TYPES.has(event.type))
+        return false;
+    const path = pathOf(urlForMatch(event.data));
+    return path.includes(SCOPE_PATH) || path.includes(SCOPE_FLATTENED);
+}