@reticlehq/server 2.14.0 → 3.2.0

package/dist/memory/journal/on-disk/ambient-file.js

@@ -0,0 +1,15 @@
+import { z } from 'zod';
+/**
+ * The shape of the file the learned ambient map is kept in.
+ *
+ * Only the storing of the map lives here. What counts as background churn is a judgement about what
+ * happened on the page, and that reasoning sits with the rules that decide a verdict, in
+ * `events/ambient.ts`.
+ *
+ * Example of a valid file: `{ "version": 1, "regions": { "#chat-feed": 43 } }` — the chat feed has
+ * changed on its own forty-three times, with no action to explain it.
+ */
+export const AmbientFileSchema = z.object({
+    version: z.literal(1),
+    regions: z.record(z.number()),
+});

package/dist/memory/journal/on-disk/retention.d.ts

@@ -0,0 +1,141 @@
+import type { FileSystemPort } from '../../project/fs/fs-port.js';
+/** Keep at most this many session journals on disk; older ones are pruned by recency. */
+export declare const DEFAULT_SESSION_RETENTION = 20;
+/**
+ * Keep at most this many overlay diffs. Small on purpose: a diff is looked at in the minute after
+ * the comparison that produced it, or never.
+ */
+export declare const DEFAULT_DIFF_RETENTION = 10;
+/**
+ * Keep at most this many local feedback copies. The outbox is the record; these are a convenience
+ * for the one case where delivery was refused and somebody has to file the report by hand.
+ */
+export declare const DEFAULT_FEEDBACK_RETENTION = 20;
+/**
+ * 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 user's `.reticle/sessions` reached 8 GB 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 declare const DEFAULT_EVIDENCE_BUDGET_BYTES: number;
+/**
+ * One candidate entry inside a `.reticle/`, classified by the top-level directory it lives under.
+ *
+ * `under` is what decides the tier, and it is compared against `TRANSIENT_DIRS` — the same list the
+ * workspace gitignore writes, guarded there as an exhaustive partition of what `.reticle/` holds.
+ * Anything else is MEMORY: flows, capsules, baselines, the contract, the intent ledger. Those are
+ * small, durable and the reason the directory exists, so they are never evicted, never counted, and
+ * must keep being written however full the disk is.
+ */
+export interface TierEntry {
+    /** Absolute path, and what is removed. */
+    path: string;
+    /** The `.reticle/` top-level entry this lives under. */
+    under: string;
+    sizeBytes: number;
+    mtimeMs: number;
+}
+/**
+ * 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 declare function selectOverBudget(entries: readonly TierEntry[], budgetBytes: number, live?: ReadonlySet<string>): string[];
+interface DatedDir {
+    name: string;
+    mtimeMs: number;
+}
+/**
+ * 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).
+ */
+export declare function selectPrunable(dirs: readonly DatedDir[], retention: number): string[];
+/** What a sweep is allowed to delete. Every field optional: omitting one keeps the old behaviour. */
+export interface RetentionOptions {
+    /** How many session directories survive the count bound. */
+    retention?: number;
+    /** The TOTAL the evidence tier may occupy. */
+    budgetBytes?: number;
+    /**
+     * The ids of sessions that are STILL OPEN. Neither bound may evict one.
+     *
+     * Without this both bounds could delete the journal of the session currently being written, and
+     * the long-running session was the FIRST candidate rather than the last: a directory's mtime is
+     * stamped when it is created and never moves again — appending to a file inside it advances the
+     * file's mtime, not the directory's — so an hour-long drive looks older than every short session
+     * that started after it. The journal then latched its directory as ensured, every later append
+     * failed ENOENT into a swallowed catch, and reads kept answering from the in-memory cache, so the
+     * session reported healthy with nothing reaching disk.
+     */
+    live?: ReadonlySet<string> | undefined;
+}
+/**
+ * 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 and at the end of every session.
+ *
+ * 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 declare function pruneSessions(fs: FileSystemPort, root: string, options?: RetentionOptions): Promise<void>;
+/**
+ * Bound `.reticle/visual/` — the largest thing in the workspace, and the only one with no delete
+ * path at all.
+ *
+ * Only the overlay DIFFS are pruned. Nothing reads a diff back: it is written, its path is handed
+ * to the caller, and a human opens it immediately or not at all — it is derived from a baseline and
+ * a screenshot, both of which outlive it. A BASELINE is the reference that makes a comparison mean
+ * anything, so deleting one to save disk turns the next run's verdict into `baseline-missing`, which
+ * is worse than a large directory.
+ *
+ * Walks one level into the per-runtime subdirectories (`visual/electron/`), because a desktop run's
+ * diffs are the same kind of garbage in a different folder. Best-effort throughout, like
+ * `pruneSessions`: this is maintenance, and maintenance must never be the reason a daemon fails.
+ */
+export declare function pruneVisualDiffs(fs: FileSystemPort, root: string, retention?: number): Promise<void>;
+/**
+ * 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 declare function pruneEvidenceBudget(fs: FileSystemPort, root: string, budgetBytes?: number, live?: ReadonlySet<string>): Promise<void>;
+/**
+ * Bound `.reticle/feedback/` — local copies of reports that were already sent.
+ *
+ * Nothing reads the directory back: no readdir, no consumer. It exists so a report refused delivery
+ * is not lost and the receipt can hand somebody a path. That makes the recent ones useful and the
+ * rest dead weight. The outbox remains the record.
+ *
+ * Capped from here rather than from the writer, which lives in an area this file does not own. A
+ * retention rule is the same rule whether the directory holds journals, diffs or reports.
+ */
+export declare function pruneFeedback(fs: FileSystemPort, root: string, retention?: number): Promise<void>;
+export {};

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

@@ -0,0 +1,291 @@
+import { basename, join } from 'node:path';
+import { ReticleDir } from '@reticlehq/core';
+import { reticleDirPaths, visualDir } from '../../project/dir/reticle-dir.js';
+import { TRANSIENT_DIRS } from './workspace-gitignore.js';
+/** Keep at most this many session journals on disk; older ones are pruned by recency. */
+export const DEFAULT_SESSION_RETENTION = 20;
+/**
+ * Keep at most this many overlay diffs. Small on purpose: a diff is looked at in the minute after
+ * the comparison that produced it, or never.
+ */
+export const DEFAULT_DIFF_RETENTION = 10;
+/**
+ * Keep at most this many local feedback copies. The outbox is the record; these are a convenience
+ * for the one case where delivery was refused and somebody has to file the report by hand.
+ */
+export const DEFAULT_FEEDBACK_RETENTION = 20;
+const DIFF_SUFFIX = '.diff.png';
+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 user's `.reticle/sessions` reached 8 GB 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) => TRANSIENT_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;
+}
+/** Where refused feedback reports are copied. Named here because the writer lives in another area. */
+const FEEDBACK_SUBDIR = 'feedback';
+/**
+ * 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).
+ */
+export function selectPrunable(dirs, retention) {
+    if (dirs.length <= retention)
+        return [];
+    return [...dirs]
+        .sort((a, b) => a.mtimeMs - b.mtimeMs)
+        .slice(0, dirs.length - retention)
+        .map((d) => d.name);
+}
+/**
+ * Keep the `retention` most-recent entries of `dir`, remove the rest by mtime.
+ *
+ * The one rule behind all three callers below — journals, overlay diffs, feedback copies. Never
+ * throws: retention is maintenance, and maintenance must never be the reason a daemon fails to come
+ * up or a session dies. A missing directory, an unstattable entry and a failed remove are all just
+ * "nothing to do here".
+ *
+ * @param keep an entry this returns false for is not a candidate and is never counted, so a
+ * directory holding two kinds of file can have one of them capped.
+ */
+async function pruneByRecency(fs, dir, retention, keep = () => true) {
+    let names;
+    try {
+        names = await fs.readdir(dir);
+    }
+    catch {
+        return; // nothing written here yet
+    }
+    const dated = [];
+    for (const name of names) {
+        if (!keep(name))
+            continue;
+        try {
+            const { mtimeMs } = await fs.stat(join(dir, name));
+            dated.push({ name, mtimeMs });
+        }
+        catch {
+            /* unstattable entry — skip */
+        }
+    }
+    for (const name of selectPrunable(dated, retention)) {
+        try {
+            await fs.rm(join(dir, name));
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+}
+/**
+ * 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 and at the end of every session.
+ *
+ * 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, 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));
+    // The tier total is swept from here because this is the one sweep that runs on BOTH the daemon's
+    // start path and the end of every session, and the end of a session is when the bytes arrive.
+    await pruneEvidenceBudget(fs, root, options.budgetBytes ?? DEFAULT_EVIDENCE_BUDGET_BYTES, live);
+}
+/**
+ * Bound `.reticle/visual/` — the largest thing in the workspace, and the only one with no delete
+ * path at all.
+ *
+ * Only the overlay DIFFS are pruned. Nothing reads a diff back: it is written, its path is handed
+ * to the caller, and a human opens it immediately or not at all — it is derived from a baseline and
+ * a screenshot, both of which outlive it. A BASELINE is the reference that makes a comparison mean
+ * anything, so deleting one to save disk turns the next run's verdict into `baseline-missing`, which
+ * is worse than a large directory.
+ *
+ * Walks one level into the per-runtime subdirectories (`visual/electron/`), because a desktop run's
+ * diffs are the same kind of garbage in a different folder. Best-effort throughout, like
+ * `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_SUFFIX))
+                dirs.push(join(top, entry));
+        }
+    }
+    catch {
+        return [];
+    }
+    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 TRANSIENT_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 */
+    }
+}
+/**
+ * Bound `.reticle/feedback/` — local copies of reports that were already sent.
+ *
+ * Nothing reads the directory back: no readdir, no consumer. It exists so a report refused delivery
+ * is not lost and the receipt can hand somebody a path. That makes the recent ones useful and the
+ * rest dead weight. The outbox remains the record.
+ *
+ * Capped from here rather than from the writer, which lives in an area this file does not own. A
+ * 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);
+}

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

@@ -0,0 +1,21 @@
+import type { FileSystemPort } from '../../project/fs/fs-port.js';
+/**
+ * Local directories, without the trailing slash the ignore file wants.
+ *
+ * Exported because this is also the EVIDENCE tier: the per-session churn that retention is allowed
+ * to delete. Read from here rather than restated next to the byte budget — the partition of what
+ * `.reticle/` holds already exists, is guarded as exhaustive, and a second copy of it would be the
+ * list that silently disagrees.
+ */
+export declare const TRANSIENT_DIRS: readonly string[];
+/** 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.
+ *
+ * Never overwrites — once the file exists it belongs to whoever edited it last, and silently
+ * reverting somebody's change to a file we placed in their repository is worse than not having
+ * written it. Best-effort throughout: this runs on the daemon's start path, and a workspace that
+ * cannot be written must not stop a daemon coming up. Nothing about verification depends on it.
+ */
+export declare function ensureWorkspaceGitignore(fs: FileSystemPort, root: string): Promise<void>;

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

@@ -0,0 +1,93 @@
+import { join } from 'node:path';
+import { ReticleDir } from '@reticlehq/core';
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * Exported because this is also the EVIDENCE tier: the per-session churn that retention is allowed
+ * to delete. Read from here rather than restated next to the byte budget — the partition of what
+ * `.reticle/` holds already exists, is guarded as exhaustive, and a second copy of it would be the
+ * list that silently disagrees.
+ */
+export 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,
+    '*.log',
+    '*.tmp',
+];
+const HEADER = [
+    '# Written by Reticle, and only about the directory Reticle owns.',
+    '#',
+    '# The entries below are per-machine state — session journals, run artifacts, learned envelopes.',
+    '# Journals contain URLs, request and response bodies and page text from the app under test, so',
+    '# they are worth keeping out of a shared repository on their own account.',
+    '#',
+    `# Deliberately NOT ignored: ${ReticleDir.CONTRACT_FILE}, ${ReticleDir.FLOWS_SUBDIR}/, ${ReticleDir.INTENT_FILE} and`,
+    `# ${ReticleDir.CAPSULES_SUBDIR}/. Those are meant to be committed — a saved flow only earns its keep`,
+    '# when a teammate or CI can replay it.',
+    '#',
+    '# Edit freely: Reticle writes this once and never rewrites it.',
+];
+/**
+ * Write `.reticle/.gitignore` if it is not already there.
+ *
+ * Never overwrites — once the file exists it belongs to whoever edited it last, and silently
+ * reverting somebody's change to a file we placed in their repository is worse than not having
+ * written it. Best-effort throughout: this runs on the daemon's start path, and a workspace that
+ * cannot be written must not stop a daemon coming up. Nothing about verification depends on it.
+ */
+export async function ensureWorkspaceGitignore(fs, root) {
+    const path = join(root, '.gitignore');
+    try {
+        if (await fs.exists(path))
+            return;
+        await fs.mkdir(root);
+        await fs.writeFile(path, `${[...HEADER, '', ...TRANSIENT].join('\n')}\n`);
+    }
+    catch {
+        /* a workspace we cannot write is not a reason to fail a session */
+    }
+}

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);
+}