@reticlehq/server 3.2.0 → 3.4.0

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

@@ -1,4 +1,5 @@
-import { REPLAY_PROGRAM_VERSION, asFlowName } from '@reticlehq/core';
+import { ActionType, PredicateKind, QueryBy, REPLAY_PROGRAM_VERSION, asFlowName, defaultIsSensitiveKey, } from '@reticlehq/core';
+import { clauseOfKind } from '@reticlehq/core';
 /**
  * What a session drove, saved as a replayable flow — without anybody asking for it.
  *
@@ -29,67 +30,62 @@ const segment = (value, max) => value
  * DOM-shaped claims are the weakest. Naming a flow after the strongest thing it proves is the same
  * judgement the honesty grade makes, reused where a human reads it.
  *
- * Returns '' when a step claims nothing nameable, and the caller keeps the old session-only name.
+ * Returns '' when a step claims nothing nameable.
  */
 function provedSlug(steps) {
     for (const step of 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 '';
 }
+/** Every auto-saved flow's name starts here, which is what lets a merge tell them from hand-named ones. */
+export const DRIVE_FLOW_PREFIX = 'drive-';
 /**
- * A stable name for what this session drove — led by what it proved.
+ * A readable name for a journey, led by WHY it was driven.
  *
- * Two properties, and the name used to have only the second. It has to be STABLE: teardown fires on
- * every socket close and a reconnecting tab keeps its id, so a name that moves leaves one journey
- * scattered across several files, each a partial copy of the others. And it has to be READABLE,
- * because `presenter-controls.ts` renders it straight into the replay button's `textContent` — so
- * the label a person actually sees was `drive-sdc991872-6d66-4adf-8780-f931c62905f9`, twice, for two
- * different journeys. A session id is a fact about the socket, not about the feature.
+ * The agent's own `intent` on the action is the best name there is — it is the sentence a person
+ * would use — so it leads when one was declared. Without one, what the journey proved names it (the
+ * strongest claim first), and the route follows so two journeys stay apart.
  *
- * So the claim leads, the route follows, and a SHORT session discriminator trails: two sessions that
- * prove the same thing on the same route stay separate files rather than overwriting each other,
- * which is the one thing the full id was buying that the claim cannot.
+ * No session id. It used to trail every name so two sessions never overwrote each other, which also
+ * made every session's drive of the same journey its own file. Two DIFFERENT journeys that land on
+ * one name are now told apart at save by their shape, and two copies of the SAME journey merge —
+ * see FlowStore.saveJourney.
  */
-export function driveFlowName(sessionId, route, steps = []) {
-    const safe = sessionId.replace(/[^a-zA-Z0-9-]/g, '-').slice(0, 40);
-    const proved = provedSlug(steps);
-    // The route is part of the name, so two journeys in one session do not overwrite each other —
-    // and so a re-drive of the same journey rewrites its own flow rather than adding a near-duplicate.
-    const leg = (route ?? '')
-        .replace(/[^a-zA-Z0-9]+/g, '-')
-        .replace(/^-|-$/g, '')
-        .slice(0, 24);
-    // Minted here, not at the call site. This function is where a drive's flow name comes into
-    // existence, and every character it can emit has just been forced through the safe-segment
-    // replacements above — so this IS the validated boundary the brand is meant to be created at.
-    // Returning `string` pushed a cast onto each caller, which is the hole `flowPath`'s parameter
-    // type was added to close.
-    // Nothing nameable was proved, so keep the name this function has always produced.
-    if ('' === proved) {
-        return asFlowName(0 === leg.length ? `drive-${safe}` : `drive-${safe}-${leg}`);
-    }
-    // Enough of the session to keep two of them apart, and little enough to read past.
-    const discriminator = safe.replace(/-/g, '').slice(0, 8);
-    const parts = ['drive', proved, ...(0 === leg.length ? [] : [leg]), discriminator];
-    return asFlowName(parts.join('-'));
+export function driveFlowName(route, steps = []) {
+    const intent = steps.find((step) => step.intent !== undefined)?.intent;
+    const leg = segment(route ?? '', 24);
+    const why = intent === undefined ? '' : segment(intent, 48);
+    const lead = '' !== why ? why : provedSlug(steps);
+    // Minted here: every character has just been forced through `segment`, so this IS the validated
+    // boundary the brand is meant to be created at.
+    const parts = [lead, ...('' !== why || 0 === leg.length ? [] : [leg])].filter((p) => '' !== p);
+    return asFlowName(`${DRIVE_FLOW_PREFIX}${0 === parts.length ? 'journey' : parts.join('-')}`);
 }
 /**
  * Turn this session's ambient tape into a flow, when it is worth one.
@@ -116,18 +112,39 @@ export function driveFlowName(sessionId, route, steps = []) {
  */
 function segmentsByRoute(steps) {
     const out = [];
+    let signedIn = false;
     for (const step of steps) {
         const last = out.at(-1);
-        if (last !== undefined && last.route === step.route) {
+        const previous = last?.steps.at(-1);
+        // The same journey when the route is unchanged, or when the previous ACTION moved the app here
+        // — cart → shipping → payment is one flow, and cutting it left three fragments that each
+        // proved a page and none proved the journey. Not after a sign-in: that is the cut this exists
+        // for, and a login that navigates onward must still not open the next flow.
+        const caused = previous !== undefined && step.route !== undefined && previous.endPage === step.route;
+        if (last !== undefined && (last.route === step.route || (caused && !signedIn))) {
             last.steps.push(step);
+            signedIn ||= typesASecret(step);
             continue;
         }
+        signedIn = typesASecret(step);
         out.push({ ...(step.route === undefined ? {} : { route: step.route }), steps: [step] });
     }
     return out;
 }
+/**
+ * A fill into a field the network channel would redact — the sign-in a journey must not carry.
+ * Read off the recorder's anchor args: a testid names the field by `value`, a role by `name`.
+ */
+function typesASecret(step) {
+    const action = step.args['action'];
+    if (ActionType.FILL !== action && ActionType.TYPE !== action)
+        return false;
+    const by = step.args['by'];
+    const field = QueryBy.TESTID === by ? step.args['value'] : step.args['name'];
+    return 'string' === typeof field && defaultIsSensitiveKey(field);
+}
 /** A flow per journey, so two journeys in one session are two regression tests rather than one. */
-export function driveFlowsFrom(sessionId, tape) {
+export function driveFlowsFrom(tape) {
     if (tape === undefined || 0 === tape.steps.length)
         return { programs: [], outcome: {} };
     const programs = [];
@@ -139,7 +156,7 @@ export function driveFlowsFrom(sessionId, tape) {
         }
         const startPath = segment.route ?? tape.startPath;
         programs.push({
-            name: driveFlowName(sessionId, startPath, segment.steps),
+            name: driveFlowName(startPath, segment.steps),
             version: REPLAY_PROGRAM_VERSION,
             // The route is recorder-internal and has no business on disk — `startPath` is where the
             // on-disk flow says the same thing, in the field replay actually reads.

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-recorder.d.ts

@@ -53,6 +53,27 @@ export interface JournalReader {
      * 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). */

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

@@ -16,9 +16,10 @@ export declare const DEFAULT_FEEDBACK_RETENTION = 20;
  * 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.
+ * 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
@@ -40,11 +41,11 @@ 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.
+ * `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. */
@@ -73,8 +74,6 @@ export declare function selectPrunable(dirs: readonly DatedDir[], retention: num
 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.
      *
@@ -94,6 +93,11 @@ export interface RetentionOptions {
  * 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.
  *
+ * 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.

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

@@ -1,7 +1,7 @@
 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';
+import { EVIDENCE_DIRS } from './workspace-tiers.js';
 /** Keep at most this many session journals on disk; older ones are pruned by recency. */
 export const DEFAULT_SESSION_RETENTION = 20;
 /**
@@ -21,9 +21,10 @@ const PNG_SUFFIX = '.png';
  * 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.
+ * 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
@@ -60,7 +61,7 @@ function isOpenSession(entry, live) {
  * `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));
+    const evidence = entries.filter((entry) => EVIDENCE_DIRS.includes(entry.under));
     // Live sessions still COUNT — their bytes are on disk and the budget is about the disk. They are
     // only excluded from the eviction list, so a session over budget on its own is left alone rather
     // than deleted under its own writer.
@@ -78,8 +79,6 @@ export function selectOverBudget(entries, budgetBytes, live = NO_LIVE_SESSIONS)
     }
     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).
@@ -138,6 +137,11 @@ async function pruneByRecency(fs, dir, retention, keep = () => true) {
  * 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.
  *
+ * 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.
@@ -148,9 +152,6 @@ 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
@@ -224,7 +225,7 @@ async function sizeOf(fs, path) {
  */
 async function collectEvidence(fs, root) {
     const entries = [];
-    for (const under of TRANSIENT_DIRS) {
+    for (const under of EVIDENCE_DIRS) {
         const isVisual = ReticleDir.VISUAL_SUBDIR === under;
         const dirs = isVisual ? await visualDirs(fs, root) : [join(root, under)];
         for (const dir of dirs) {
@@ -287,5 +288,5 @@ export async function pruneEvidenceBudget(fs, root, budgetBytes = DEFAULT_EVIDEN
  * retention rule is the same rule whether the directory holds journals, diffs or reports.
  */
 export async function pruneFeedback(fs, root, retention = DEFAULT_FEEDBACK_RETENTION) {
-    await pruneByRecency(fs, join(root, FEEDBACK_SUBDIR), retention);
+    await pruneByRecency(fs, join(root, ReticleDir.FEEDBACK_SUBDIR), retention);
 }

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

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

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

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

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

@@ -1,15 +1,4 @@
 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.
  *

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

@@ -1,60 +1,21 @@
 import { join } from 'node:path';
 import { ReticleDir } from '@reticlehq/core';
+import { LOCAL_DIRS, LOCAL_FILES } from './workspace-tiers.js';
 /**
  * The `.reticle/` entries that are LOCAL state, and must never be committed by accident.
  *
- * Split from the durable half deliberately, and the split is the whole design: `contract.json`,
- * `flows/`, `intent.json` and `capsules/` are meant to be checked in — a flow that cannot be shared
- * is not a regression check anybody else can run — while everything below is per-machine churn.
+ * Read from the tier table rather than restated here: which half a name belongs to is one decision,
+ * and a second copy of it is the list that silently disagrees. This file asks the table exactly one
+ * of its two questions — `sharing` — and has no opinion at all about what retention may delete.
  *
  * The reason this matters beyond tidiness: a session journal carries URLs, request and response
  * bodies, and DOM text from the app under test. `.reticle/` is created by the daemon rather than by
  * the user, so it arrives untracked and unexplained, and one `git add -A` puts an app's traffic into
  * a shared repository. Reticle created the directory; the ignore for it is Reticle's to write.
  */
-/**
- * The local feedback copies — `.reticle/feedback/`.
- *
- * Named here rather than imported: the directory is spelled inline where it is written, in files
- * another agent owns, and the ignore for a directory Reticle creates is Reticle's to write whether
- * or not that name has been hoisted yet.
- */
-const FEEDBACK_SUBDIR = 'feedback';
-/**
- * Local directories, without the trailing slash the ignore file wants.
- *
- * 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,
+    ...LOCAL_DIRS.map((dir) => `${dir}/`),
+    ...LOCAL_FILES,
     '*.log',
     '*.tmp',
 ];

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

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