@reticlehq/server 3.1.0 → 3.3.0

package/dist/memory/journal/drive-flow.js

@@ -1,4 +1,5 @@
-import { REPLAY_PROGRAM_VERSION, asFlowName } from '@reticlehq/core';
+import { PredicateKind, REPLAY_PROGRAM_VERSION, asFlowName } from '@reticlehq/core';
+import { clauseOfKind } from '@reticlehq/core';
 /**
  * What a session drove, saved as a replayable flow — without anybody asking for it.
  *
@@ -36,21 +37,29 @@ function provedSlug(steps) {
         const expect = step.expect;
         if (expect === undefined)
             continue;
-        if (expect.signal !== undefined)
-            return segment(expect.signal, 32);
-        if (expect.net !== undefined) {
-            const method = segment(expect.net.method ?? '', 6);
-            const where = segment(expect.net.urlContains ?? '', 24);
+        // A predicate names its kind, so the slug reads the tree rather than probing a struct. The
+        // signal wins over the request for the same reason it always did: it is the app saying what it
+        // did, which is the strongest thing a name can carry.
+        const signal = clauseOfKind(expect, PredicateKind.SIGNAL);
+        if (signal?.name !== undefined)
+            return segment(signal.name, 32);
+        const netClause = clauseOfKind(expect, PredicateKind.NET);
+        if (netClause !== undefined) {
+            const method = segment(netClause.method ?? '', 6);
+            const where = segment(netClause.urlContains ?? '', 24);
             const joined = [method, where].filter((part) => '' !== part).join('-');
             if ('' !== joined)
                 return joined;
         }
-        if (expect.state !== undefined)
-            return segment(expect.state.path, 32);
-        if (expect.route?.pathname !== undefined)
-            return segment(expect.route.pathname, 24);
-        if (expect.text?.contains !== undefined)
-            return segment(expect.text.contains, 24);
+        const state = clauseOfKind(expect, PredicateKind.STATE);
+        if (state !== undefined)
+            return segment(state.path, 32);
+        const route = clauseOfKind(expect, PredicateKind.ROUTE);
+        if (route?.pathname !== undefined)
+            return segment(route.pathname, 24);
+        const text = clauseOfKind(expect, PredicateKind.TEXT);
+        if (text?.contains !== undefined)
+            return segment(text.contains, 24);
     }
     return '';
 }

package/dist/memory/journal/envelope-store.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { writeFileAtomic } from '../project/fs/write-atomic.js';
 import { dirname } from 'node:path';
 import { reticleDirPaths } from '../project/dir/reticle-dir.js';
 import { RouteEnvelopeSchema } from './envelope.js';
@@ -54,8 +55,6 @@ export class EnvelopeStore {
             routes[route] = envelope;
         const body = `${JSON.stringify({ version: ENVELOPE_FILE_VERSION, routes }, null, 2)}\n`;
         // Atomic publish: write a temp sibling then rename, so a crash never leaves a half-written baseline.
-        const tmp = `${this.#path}.tmp`;
-        await this.#fs.writeFile(tmp, body);
-        await this.#fs.rename(tmp, this.#path);
+        await writeFileAtomic(this.#fs, this.#path, body);
     }
 }

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

@@ -1,4 +1,13 @@
-import type { ReticleEvent } from '@reticlehq/core';
+import type { JournalWriteLoss, ReticleEvent } from '@reticlehq/core';
+import type { JournalReader } from './journal-recorder.js';
+/** The slice of the ring buffer a journal-backed query reads. `RingBuffer` satisfies it structurally. */
+export interface QueryBuffer {
+    since(cursor: number): ReticleEvent[];
+    bufferHealth(): {
+        total: number;
+        dropped: number;
+    };
+}
 /** Filter bounds for a journal-backed event query. All optional; omitted = unbounded on that axis. */
 export interface EventQueryOptions {
     /** Lower time bound (inclusive), elapsed ms — the act cursor semantics of `eventsSince`. */
@@ -28,5 +37,30 @@ export interface EventQueryOptions {
  * Overlapping seqs need no rule — appends are ordered, so the newest write already wins the dedupe.
  */
 export declare function mergeEventsBySeq(journal: readonly ReticleEvent[], buffer: readonly ReticleEvent[]): ReticleEvent[];
+/**
+ * The events a query answers with: the ring buffer's, merged with the durable journal's **only when
+ * the buffer has evicted** (so a healthy session pays no disk cost), then filtered by
+ * since/until/actionId. This is how "what did action N cause" is answered after the buffer has
+ * dropped the evidence — the substrate's whole point.
+ */
+export declare function readQueryEvents(reader: JournalReader | undefined, buffer: QueryBuffer, options: EventQueryOptions): Promise<ReticleEvent[]>;
+/**
+ * What the durable ledger could not WRITE, when a query would read from it.
+ *
+ * The event ledger stops at a byte ceiling, so a journal-backed window can be missing exactly the
+ * evidence that would have refuted an absence claim. The in-band `truncated` record cannot carry
+ * this on its own: it is stamped with the `t` of the last refused event, and `filterEvents` above
+ * bounds on `t` — so a window opened after the ceiling was reached holds no marker, no events, and
+ * nothing to distinguish it from a window in which nothing happened.
+ *
+ * Reported ONLY while the buffer has evicted, which is the same condition `readQueryEvents` uses to
+ * fall through to disk. While the buffer still holds the window, the ledger's state says nothing
+ * about that window's completeness, and saying it anyway would impeach healthy verdicts for the
+ * rest of every session that ever hit its cap. Live ring data is never discarded over this.
+ *
+ * A reader with no opinion answers `undefined`, which means NOT MEASURED. It must never be read as
+ * "nothing was lost" — see `JournalReader.readWriteLoss`.
+ */
+export declare function readJournalWriteLoss(reader: JournalReader | undefined, buffer: QueryBuffer): Promise<JournalWriteLoss | undefined>;
 /** Apply since/until/actionId bounds to an event list. */
 export declare function filterEvents(events: readonly ReticleEvent[], options: EventQueryOptions): ReticleEvent[];

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

@@ -44,6 +44,52 @@ export function mergeEventsBySeq(journal, buffer) {
         return a.t - b.t;
     });
 }
+/**
+ * Does a query read the durable journal at all, or is the buffer still authoritative?
+ *
+ * One expression, three callers, because the two public functions below are only honest while this
+ * is true. Kept here rather than on `Session` so the rule sits beside the merge and filter rules it
+ * governs; two copies of it would drift into a verdict that impeached itself over a file it never
+ * opened.
+ */
+function readsJournal(reader, buffer) {
+    return reader !== undefined && buffer.bufferHealth().dropped > 0;
+}
+/**
+ * The events a query answers with: the ring buffer's, merged with the durable journal's **only when
+ * the buffer has evicted** (so a healthy session pays no disk cost), then filtered by
+ * since/until/actionId. This is how "what did action N cause" is answered after the buffer has
+ * dropped the evidence — the substrate's whole point.
+ */
+export async function readQueryEvents(reader, buffer, options) {
+    if (!readsJournal(reader, buffer)) {
+        return filterEvents(buffer.since(options.since ?? 0), options);
+    }
+    const durable = (await reader?.readEvents()) ?? [];
+    return filterEvents(mergeEventsBySeq(durable, buffer.since(0)), options);
+}
+/**
+ * What the durable ledger could not WRITE, when a query would read from it.
+ *
+ * The event ledger stops at a byte ceiling, so a journal-backed window can be missing exactly the
+ * evidence that would have refuted an absence claim. The in-band `truncated` record cannot carry
+ * this on its own: it is stamped with the `t` of the last refused event, and `filterEvents` above
+ * bounds on `t` — so a window opened after the ceiling was reached holds no marker, no events, and
+ * nothing to distinguish it from a window in which nothing happened.
+ *
+ * Reported ONLY while the buffer has evicted, which is the same condition `readQueryEvents` uses to
+ * fall through to disk. While the buffer still holds the window, the ledger's state says nothing
+ * about that window's completeness, and saying it anyway would impeach healthy verdicts for the
+ * rest of every session that ever hit its cap. Live ring data is never discarded over this.
+ *
+ * A reader with no opinion answers `undefined`, which means NOT MEASURED. It must never be read as
+ * "nothing was lost" — see `JournalReader.readWriteLoss`.
+ */
+export async function readJournalWriteLoss(reader, buffer) {
+    if (!readsJournal(reader, buffer))
+        return undefined;
+    return (await reader?.readWriteLoss?.()) ?? undefined;
+}
 /** Apply since/until/actionId bounds to an event list. */
 export function filterEvents(events, options) {
     return events.filter((event) => (options.since === undefined || event.t >= options.since) &&

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,42 @@ 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>;
+    /**
+     * How big the event ledger is right now, and the ceiling it is measured against.
+     *
+     * Synchronous and cached: the size is already tracked for the cap, so reporting it costs a field
+     * read. Optional on the same reasoning as `readActions` -- a partial double declares no size,
+     * and a caller reads that as "not measured" rather than "empty".
+     *
+     * It is reported at all because nothing reported it. A repeating uncaught error wrote one
+     * session's ledger without limit, and neither the daemon nor
+     * `doctor` nor any health counter said a word; the user found out when the disk was full (#986).
+     * The cap that now bounds this is only half an answer -- a ledger silently approaching it is
+     * still a dev tool writing hard to somebody's repo directory.
+     */
+    ledger?(): JournalLedgerSize | undefined;
+}
+/** The event ledger's size on disk against the ceiling that will refuse it. */
+export interface JournalLedgerSize {
+    /** Bytes of `events.jsonl` on disk. */
+    bytes: number;
+    /** The ceiling that refuses the next batch past it. */
+    capBytes: number;
 }
 interface JournalRecorderOptions {
     /** Injected elapsed-ms clock (never read from Date here — the clock-injection rule). */
@@ -31,7 +93,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/retain-policy.d.ts

@@ -0,0 +1,34 @@
+/**
+ * What a project is willing to keep.
+ *
+ * The only answer `.reticle.json` used to offer a full directory was `journal: false` — turning off
+ * the thing the product is FOR, and, until the sweep was ungated, the one setting under which
+ * nothing was deleted either. The bounds themselves were four constants no user could reach.
+ *
+ * `0` is a real answer and means keep none, which the count bounds already do for free: a sweep that
+ * keeps zero directories deletes all of them. It is not the same as "unset", which is why every
+ * field is read explicitly rather than with `??` over a falsy value.
+ */
+export interface RetainPolicy {
+    /** Session journal directories under `sessions/`. */
+    sessions: number;
+    /** Overlay diffs under `visual/`. Baselines are memory and are never counted here. */
+    visual: number;
+    /** Local copies of reports the outbox already carries. */
+    feedback: number;
+    /** The TOTAL the evidence tier may occupy, in bytes. Stated in the file as `budgetMb`. */
+    budgetBytes: number;
+}
+export declare const DEFAULT_RETAIN: RetainPolicy;
+/**
+ * Read the `retain` block out of an already-parsed `.reticle.json`.
+ *
+ * Takes the record rather than a path: the config search belongs to the caller that already does it
+ * once at startup, and reaching for it from here would point the retention domain at the
+ * command-line surface for a single lookup.
+ *
+ * Never throws, and falls back PER FIELD. A project that mistypes one bound keeps the other three —
+ * the alternative silently reverts every bound the user did set, which is the same class of quiet
+ * disagreement the whole partition of `.reticle/` exists to prevent.
+ */
+export declare function readRetainPolicy(config: Record<string, unknown> | undefined): RetainPolicy;

package/dist/memory/journal/on-disk/retain-policy.js

@@ -0,0 +1,44 @@
+import { DEFAULT_DIFF_RETENTION, DEFAULT_EVIDENCE_BUDGET_BYTES, DEFAULT_FEEDBACK_RETENTION, DEFAULT_SESSION_RETENTION, } from './retention.js';
+/** The key a project writes in `.reticle.json`. */
+const RETAIN_KEY = 'retain';
+const BYTES_PER_MB = 1024 * 1024;
+export const DEFAULT_RETAIN = {
+    sessions: DEFAULT_SESSION_RETENTION,
+    visual: DEFAULT_DIFF_RETENTION,
+    feedback: DEFAULT_FEEDBACK_RETENTION,
+    budgetBytes: DEFAULT_EVIDENCE_BUDGET_BYTES,
+};
+/**
+ * A count a sweep can act on, or `undefined` for anything else.
+ *
+ * Negative and fractional are refused rather than coerced. "Keep -1 sessions" and "keep 1.5" are
+ * both a user saying something they did not mean, and a sweep that guesses at what they meant is
+ * deleting files on a guess.
+ */
+function count(value) {
+    return 'number' === typeof value && Number.isInteger(value) && value >= 0 ? value : undefined;
+}
+/**
+ * Read the `retain` block out of an already-parsed `.reticle.json`.
+ *
+ * Takes the record rather than a path: the config search belongs to the caller that already does it
+ * once at startup, and reaching for it from here would point the retention domain at the
+ * command-line surface for a single lookup.
+ *
+ * Never throws, and falls back PER FIELD. A project that mistypes one bound keeps the other three —
+ * the alternative silently reverts every bound the user did set, which is the same class of quiet
+ * disagreement the whole partition of `.reticle/` exists to prevent.
+ */
+export function readRetainPolicy(config) {
+    const raw = config?.[RETAIN_KEY];
+    if ('object' !== typeof raw || null === raw || Array.isArray(raw))
+        return DEFAULT_RETAIN;
+    const retain = raw;
+    const mb = count(retain['budgetMb']);
+    return {
+        sessions: count(retain['sessions']) ?? DEFAULT_RETAIN.sessions,
+        visual: count(retain['visual']) ?? DEFAULT_RETAIN.visual,
+        feedback: count(retain['feedback']) ?? DEFAULT_RETAIN.feedback,
+        budgetBytes: mb === undefined ? DEFAULT_RETAIN.budgetBytes : mb * BYTES_PER_MB,
+    };
+}

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

@@ -11,6 +11,56 @@ 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 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 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 looked up in the workspace tier table's `durability`
+ * axis — never in the gitignore's, which answers a different question. Anything not EVIDENCE 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 +70,41 @@ 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 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.
+ *
+ * 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 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 +120,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.
  *