@reticlehq/server 3.1.0 → 3.2.0

package/dist/memory/journal/journal-recorder.d.ts

@@ -1,9 +1,35 @@
-import { type JournalAction, type ReticleEvent } from '@reticlehq/core';
+import { type JournalAction, type JournalWriteLoss, type ReticleEvent } from '@reticlehq/core';
 /** Where a recorder persists. `SessionJournal` satisfies this structurally. */
 export interface JournalSink {
     appendEvents(events: readonly ReticleEvent[]): Promise<void>;
     appendAction(action: JournalAction): Promise<void>;
 }
+/**
+ * What a durable read could NOT produce — the report that travels beside the events.
+ *
+ * The journal is append-only and one session's file is never pruned, so a long-lived session's
+ * ledger outgrows what a JavaScript string can hold and the read has to stop somewhere; and what a
+ * reader keeps across many reads has to stop somewhere too. Where it stopped is not a detail: an
+ * agent reading a short answer it cannot tell apart from a complete one is the false green this
+ * whole layer exists to prevent. Absent means nothing was lost.
+ */
+export interface JournalReadLoss {
+    /**
+     * Journal bytes not represented in the answer — skipped past by a read that would have exceeded
+     * its ceiling, plus the bytes of records evicted after parsing. A floor, not a total: the record
+     * straddling a cut is discarded with them and is not counted here.
+     */
+    droppedBytes: number;
+    /** Parsed records evicted from the retained set. Exact, unlike `droppedBytes`. */
+    droppedEvents: number;
+    /**
+     * Latest timestamp of parsed cache evictions, inclusive. Omitted after a byte cut skips
+     * unparsed records: their time range is unknown even when newer bytes survive.
+     */
+    lostThroughT?: number;
+    /** Human-and-agent readable summary. Present so a consumer never has to compose one. */
+    note: string;
+}
 /** Read side of the durable journal — the fall-through source when the ring buffer has evicted. */
 export interface JournalReader {
     readEvents(): Promise<ReticleEvent[]>;
@@ -12,6 +38,21 @@ export interface JournalReader {
      * needs events should be forced to grow a second method to satisfy the type.
      */
     readActions?(): Promise<JournalAction[]>;
+    /**
+     * What the reads so far could not reach. Optional on the same reasoning as `readActions`: a reader
+     * that omits it declares no loss, which is the behaviour every partial double already had.
+     */
+    readLoss?(): JournalReadLoss | undefined;
+    /**
+     * What the WRITER could not put on disk: the ledger's closure report, when its byte ceiling
+     * refused a batch. `undefined` means nothing was refused.
+     *
+     * Optional for the same reason `readActions` is, and absence means NOT MEASURED rather than "no
+     * loss" — a reader that cannot answer must not be made to answer "clean". The separate question
+     * of what a bounded READ declined to hand back belongs to the reader that bounded it; this one is
+     * only ever about writes that never happened.
+     */
+    readWriteLoss?(): Promise<JournalWriteLoss | undefined>;
 }
 interface JournalRecorderOptions {
     /** Injected elapsed-ms clock (never read from Date here — the clock-injection rule). */
@@ -31,7 +72,14 @@ interface JournalRecorderOptions {
 export declare class JournalRecorder {
     #private;
     constructor(sink: JournalSink, options: JournalRecorderOptions);
-    /** Attribute (if an action is active), enqueue for journaling, and return the possibly-stamped event. */
+    /**
+     * Attribute (if an action is active), enqueue for journaling, and return the possibly-stamped event.
+     *
+     * Reticle fetching its own SDK is attributed and returned like anything else but never written to
+     * disk. That is a decision about what is worth KEEPING, so it is taken here, where the journal is
+     * written, and not in a reader: a reader that hid these would leave the bytes on disk and the
+     * cost unpaid, and a second reader would still find them and disagree about what happened.
+     */
     observe(event: ReticleEvent): ReticleEvent;
     /** Open an attribution window. One action is active at a time (the agent drives sequentially). */
     beginAction(actionId: string, tool: string, args: Record<string, unknown>): void;

package/dist/memory/journal/journal-recorder.js

@@ -1,4 +1,17 @@
 import { EventAttribution, JOURNAL_FILE_VERSION, } from '@reticlehq/core';
+import { isSelfObservation } from './self-observation.js';
+import { log } from '../../log.js';
+/**
+ * Logged the FIRST time a journal write is lost, and never again for that recorder.
+ *
+ * The swallow stays — a failed local journal write must never break a live session, and a tool call
+ * is not the place to learn the disk is full. But a loss that says nothing is how a journal wrote
+ * nothing for a whole session while the session reported healthy and reads kept answering from the
+ * in-memory cache. Once per recorder, on the existing daemon-log channel: enough to find in the
+ * daemon log when somebody asks why a journal file is short, quiet enough that a full disk does not
+ * produce one line per batch.
+ */
+const JOURNAL_WRITE_LOST = 'journal_write_lost';
 const DEFAULT_FLUSH_AT = 64;
 /**
  * Owns action-window attribution and batched, order-preserving journaling — the durable half of the
@@ -16,12 +29,20 @@ export class JournalRecorder {
     #pending = [];
     #active;
     #chain = Promise.resolve();
+    #lossReported = false;
     constructor(sink, options) {
         this.#sink = sink;
         this.#now = options.now;
         this.#flushAt = options.flushAt ?? DEFAULT_FLUSH_AT;
     }
-    /** Attribute (if an action is active), enqueue for journaling, and return the possibly-stamped event. */
+    /**
+     * Attribute (if an action is active), enqueue for journaling, and return the possibly-stamped event.
+     *
+     * Reticle fetching its own SDK is attributed and returned like anything else but never written to
+     * disk. That is a decision about what is worth KEEPING, so it is taken here, where the journal is
+     * written, and not in a reader: a reader that hid these would leave the bytes on disk and the
+     * cost unpaid, and a second reader would still find them and disagree about what happened.
+     */
     observe(event) {
         let out = event;
         const active = this.#active;
@@ -33,9 +54,13 @@ export class JournalRecorder {
                 active.seqTo = active.seqTo === undefined ? event.seq : Math.max(active.seqTo, event.seq);
             }
         }
-        this.#pending.push(out);
-        if (this.#pending.length >= this.#flushAt)
-            this.#enqueueFlush();
+        // Attribution above still runs, and the return value is what the live ring buffer stores — the
+        // session keeps seeing this event. What is declined is the DURABLE copy: see isSelfObservation.
+        if (!isSelfObservation(out)) {
+            this.#pending.push(out);
+            if (this.#pending.length >= this.#flushAt)
+                this.#enqueueFlush();
+        }
         return out;
     }
     /** Open an attribution window. One action is active at a time (the agent drives sequentially). */
@@ -63,7 +88,9 @@ export class JournalRecorder {
             at: active.tStart,
         };
         this.#enqueueFlush();
-        this.#chain = this.#chain.then(() => this.#sink.appendAction(action)).catch(() => undefined);
+        this.#chain = this.#chain
+            .then(() => this.#sink.appendAction(action))
+            .catch((error) => this.#reportLoss(error));
     }
     /**
      * Append one action record for a tool that PROVED something without driving the page.
@@ -98,7 +125,9 @@ export class JournalRecorder {
             at,
         };
         this.#enqueueFlush();
-        this.#chain = this.#chain.then(() => this.#sink.appendAction(action)).catch(() => undefined);
+        this.#chain = this.#chain
+            .then(() => this.#sink.appendAction(action))
+            .catch((error) => this.#reportLoss(error));
     }
     /** Persist any buffered events now (call on session end). Awaits the write chain to settle. */
     async flush() {
@@ -110,6 +139,15 @@ export class JournalRecorder {
             return;
         const batch = this.#pending;
         this.#pending = [];
-        this.#chain = this.#chain.then(() => this.#sink.appendEvents(batch)).catch(() => undefined);
+        this.#chain = this.#chain
+            .then(() => this.#sink.appendEvents(batch))
+            .catch((error) => this.#reportLoss(error));
+    }
+    /** Swallow a lost write, but say so once. See JOURNAL_WRITE_LOST. */
+    #reportLoss(error) {
+        if (this.#lossReported)
+            return;
+        this.#lossReported = true;
+        log(JOURNAL_WRITE_LOST, { error: error instanceof Error ? error.message : String(error) });
     }
 }

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

@@ -11,6 +11,55 @@ export declare const DEFAULT_DIFF_RETENTION = 10;
  * 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;
@@ -20,13 +69,38 @@ interface DatedDir {
  * 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.
+ * 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, retention?: number): Promise<void>;
+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.
@@ -42,6 +116,17 @@ export declare function pruneSessions(fs: FileSystemPort, root: string, retentio
  * `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.
  *

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 { 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;
 /**
@@ -13,6 +15,69 @@ export const DEFAULT_DIFF_RETENTION = 10;
  */
 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';
 /**
@@ -71,10 +136,21 @@ 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.
+ *
+ * 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));
+    // 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
@@ -91,20 +167,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 [];
+    }
+    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 */
+            }
+        }
     }
-    for (const dir of dirs) {
-        await pruneByRecency(fs, dir, retention, (name) => name.endsWith(DIFF_SUFFIX));
+    catch {
+        /* maintenance never fails a daemon */
     }
 }
 /**

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

@@ -1,4 +1,13 @@
 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[];
 /**

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

@@ -20,8 +20,15 @@ import { ReticleDir } from '@reticlehq/core';
  * 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 = [
+/**
+ * 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,

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

package/dist/memory/journal/session-end.d.ts

@@ -1,7 +1,7 @@
 import { type DriveProgram, type TapeStep } from './drive-flow.js';
 import { type OnboardingStep } from '@reticlehq/core/telemetry';
 import type { AmbientCounts } from '@reticlehq/engine/window/ambient.js';
-import { type JournalAction } from '@reticlehq/core';
+import { type ProjectId, type JournalAction } from '@reticlehq/core';
 import type { FileSystemPort } from '../project/fs/fs-port.js';
 /**
  * Session teardown: the durable half of ending a session. Two things must happen when a tab disconnects,
@@ -39,7 +39,7 @@ export interface SessionEndTarget {
     readJournalActions?(): Promise<JournalAction[]>;
     /** The project's own `.reticle`, so a run lands in the repo it is about. */
     readonly artifactRoot?: string | undefined;
-    readonly projectId?: string | undefined;
+    readonly projectId?: ProjectId | undefined;
 }
 interface SessionEndDeps {
     fs: FileSystemPort;
@@ -76,7 +76,7 @@ interface SessionEndDeps {
      * this handler follows.
      */
     flows?: {
-        save: (program: DriveProgram, annotations?: undefined, projectId?: string) => Promise<unknown>;
+        save: (program: DriveProgram, annotations?: undefined, projectId?: ProjectId) => Promise<unknown>;
     };
     /**
      * Called when a run artifact is written, so cloud sync can cycle instead of waiting for its timer.
@@ -84,6 +84,16 @@ interface SessionEndDeps {
      * Optional, like everything else here: absent simply means the next scheduled cycle picks it up.
      */
     onRunPersisted?: () => void;
+    /**
+     * The ids of the sessions still OPEN, read at each teardown so retention never deletes a journal
+     * that is still being written. A getter rather than a snapshot: this handler is built once at
+     * wiring and fires for every session for the life of the daemon.
+     *
+     * Injected, like the clock and the reporter — teardown needs the answer, not the registry.
+     * Optional so every existing construction keeps compiling, and absent means "none known", which
+     * is exactly the old behaviour.
+     */
+    liveSessionIds?: () => ReadonlySet<string>;
 }
 /**
  * Build the teardown handler the bridge fires when a session is removed. Flushes the journal first (so no