@reticlehq/server 3.2.0 → 3.3.0

package/dist/memory/intent/intent-store.js

@@ -1,115 +1,71 @@
-import { bindIntent, declareIntent, dischargeIntent, emptyIntentFile, openIntents, parseIntentFile, upsertIntent, } from '@reticlehq/core/artifacts';
-import { reticleDirPaths } from '../project/dir/reticle-dir.js';
-import { withFileLock } from '../project/file-lock.js';
+import { IntentState, bindIntent, declareIntent, redeclareIntent, dischargeIntent, isActionLabel, } from '@reticlehq/core/artifacts';
+import { IntentShardStore } from './intent-shard-store.js';
+import { IntentStatus } from './intent-shard.js';
 /**
- * The intent ledger on disk — `.reticle/intent.json`, git-checked and meant to be read in review.
+ * The intent ledger's domain operations: declare, place, bind, discharge.
  *
- * Git-checked deliberately. The one real defence against an agent quietly narrowing what it meant to
- * match what it can already prove is that a human sees the narrowing in a diff, and that only works
- * if the file lives with the code and travels with the PR. It is also why the writes are byte-stable:
- * a ledger that churns on every run is one whose diffs nobody reads.
- *
- * Every operation goes through the same file lock the other stores use, because two sessions driving
- * one project is ordinary and a lost declaration would be silent.
+ * Every operation is a PURE transition from core (`redeclareIntent`, `bindIntent`,
+ * `dischargeIntent`) handed to the ledger's atomic upsert. Storage is `IntentShardStore` —
+ * `.reticle/intent/<subject>/intent.json`, a flow's name being its subject — and this class writes no
+ * file of its own, so there is exactly one place an intent can be.
  */
-const JSON_INDENT = 2;
 export class IntentStore {
-    #fs;
-    #root;
+    #ledger;
     #clock;
     constructor(fs, root, clock) {
-        this.#fs = fs;
-        this.#root = root;
+        this.#ledger = new IntentShardStore(fs, root, clock);
         this.#clock = clock;
     }
-    #path() {
-        return reticleDirPaths(this.#root).intent;
-    }
-    /**
-     * Load the ledger, failing soft to empty.
-     *
-     * This is a git-checked file an agent can write and a human can hand-merge, so a malformed one is
-     * genuinely reachable — a conflict marker left in place is the obvious case. Throwing here would
-     * take down the verdict that was only asking what was still open, which trades a small problem for
-     * a large one.
-     */
-    async #load() {
-        try {
-            const raw = await this.#fs.readFile(this.#path());
-            return parseIntentFile(JSON.parse(raw));
-        }
-        catch {
-            return emptyIntentFile();
-        }
-    }
-    /** Byte-stable: 2-space indent, one trailing newline. An unchanged ledger produces no diff. */
-    async #save(file) {
-        await this.#fs.mkdir(reticleDirPaths(this.#root).root);
-        await this.#fs.writeFile(this.#path(), `${JSON.stringify(file, null, JSON_INDENT)}\n`);
-    }
     /** Every intent, in declaration order. */
     async read() {
-        return Object.values((await this.#load()).intents);
+        return this.#ledger.all();
     }
     /** Everything not yet proved — what an agent asking "am I done?" still owes. */
     async open() {
-        return openIntents(await this.#load());
+        // Stale is not owed: it is kept as history, not as work.
+        return (await this.#ledger.all()).filter((record) => IntentState.PROVED !== record.state && IntentStatus.STALE !== record.status);
     }
     /**
      * Declare one or more intents.
      *
      * Batched because the marginal cost of the whole mechanism has to stay at one call per feature; an
-     * agent that must make five calls to declare five things will make none.
+     * agent that must make five calls to declare five things will make none. Saying an intent again
+     * does not unsay it: see `redeclareIntent` for what survives.
      */
     async declare(entries) {
-        if (0 === entries.length)
-            return [];
-        return withFileLock(this.#path(), async () => {
-            let file = await this.#load();
-            const now = this.#clock.now();
-            const declared = [];
-            for (const entry of entries) {
-                const intent = declareIntent({ ...entry, now });
-                file = upsertIntent(file, intent);
-                const stored = file.intents[intent.id];
-                if (stored !== undefined)
-                    declared.push(stored);
-            }
-            await this.#save(file);
-            return declared;
-        });
+        const now = this.#clock.now();
+        const declared = [];
+        for (const entry of entries) {
+            // A step label is a log line, not a rule: every route that declares comes through here.
+            if (isActionLabel(entry.statement))
+                continue;
+            const stored = await this.#ledger.upsert(entry.id, (existing) => redeclareIntent(existing, declareIntent({ ...entry, now })));
+            if (stored !== undefined)
+                declared.push(stored);
+        }
+        return declared;
     }
     /**
      * File a record under where it turned out to be about.
      *
-     * Separate from `declare` because the two happen at different MOMENTS and know different things.
-     * An inline intent is declared BEFORE the action — deliberately, so a verdict can see it open —
-     * and at that instant the agent is still on the page it is leaving. The route that describes what
-     * the intent is ABOUT only exists after the consequence lands.
-     *
-     * Write-once: an existing surface is never overwritten. A record placed by an agent that named its
-     * own subject must not be re-filed by a later run that happened to be somewhere else.
+     * Separate from `declare` because an inline intent is declared BEFORE the action, and the route
+     * that describes it only exists after the consequence lands. Write-once: an existing surface is
+     * never overwritten. A flow named here moves the record into that flow's directory.
      */
     async place(id, surface) {
-        return withFileLock(this.#path(), async () => {
-            const file = await this.#load();
-            const existing = file.intents[id];
+        let placed = false;
+        await this.#ledger.upsert(id, (existing) => {
             if (existing === undefined || existing.surface !== undefined)
-                return false;
-            await this.#save(upsertIntent(file, { ...existing, surface }));
-            return true;
+                return undefined;
+            placed = true;
+            return { ...existing, surface };
         });
+        return placed;
     }
     /** Attach the predicate that would prove an intent. False when the id names nothing. */
     async bind(id, binding) {
-        return withFileLock(this.#path(), async () => {
-            const file = await this.#load();
-            const existing = file.intents[id];
-            if (existing === undefined)
-                return false;
-            await this.#save(upsertIntent(file, bindIntent(existing, binding)));
-            return true;
-        });
+        const stored = await this.#ledger.upsert(id, (existing) => existing === undefined ? undefined : bindIntent(existing, binding));
+        return stored !== undefined;
     }
     /**
      * Record that a verdict proved an intent.
@@ -118,16 +74,16 @@ export class IntentStore {
      * and must never be the reason one fails to return.
      */
     async discharge(id, proof) {
-        return withFileLock(this.#path(), async () => {
-            const file = await this.#load();
-            const existing = file.intents[id];
+        let proved = false;
+        await this.#ledger.upsert(id, (existing) => {
             if (existing === undefined)
-                return false;
-            const proved = dischargeIntent(existing, proof);
-            if (proved === existing)
-                return false;
-            await this.#save(upsertIntent(file, proved));
-            return true;
+                return undefined;
+            const next = dischargeIntent(existing, proof);
+            if (next === existing)
+                return undefined;
+            proved = true;
+            return next;
         });
+        return proved;
     }
 }

package/dist/memory/intent/intent-tools.js

@@ -4,8 +4,10 @@ import { IntentShardStore } from './intent-shard-store.js';
 import { IntentStatus } from './intent-shard.js';
 import { ReticleTool } from '@reticlehq/core';
 import { sessionIdShape } from '../../surface/tools/tool-kit.js';
+import { PredicateSchema } from '@reticlehq/engine/question/predicate/predicate.js';
 import { sessionRoot } from '../project/session-root.js';
 import { asString } from '@reticlehq/core';
+import { isActionLabel } from '@reticlehq/core/artifacts';
 /**
  * Declare what a change was SUPPOSED to make true, while somebody still knows.
  *
@@ -24,11 +26,13 @@ const INDEX = 'index';
 const SUBJECT = 'subject';
 const GET = 'get';
 const RECORD = 'record';
+/** Why a step label is not stored, in words that say what to write instead. */
+const STEP_LABEL_REFUSAL = 'describes a step that was done, not what must be true. State the rule, e.g. "saving the form shows the new row in the list"';
 const MIGRATE = 'migrate';
 export const INTENT_TOOLS = [
     {
         name: ReticleTool.INTENT,
-        description: 'Record what a change is SUPPOSED to make true, as a durable statement ABOUT THE PRODUCT that a teammate who was not here will understand in six months — name the behaviour, not this run or its step number, and never "renders cleanly", which nothing can check. It is SHARED memory: pooled per project and read back by later agents. Capture it while you still know — then verification does not have to re-derive it from the DOM later. { action:"declare", intents:[{ id, statement, surface? }] } takes prose and needs NO predicate: at declare time there is often no route, no ref and no code yet, and a predicate demanded there is just a mechanism. Declare EARLY (as you build) and batch them — one call per feature is the whole budget. { action:"bind", id, binding } attaches the predicate that would prove it once you know how; an intent with no binding is not a failure, it is the most interesting row in the ledger — something meant that nothing can currently prove. { action:"list" } returns what is still open. Stored in .reticle/intent.json, git-checked so a human sees in review if an intent was later narrowed to match what was easy to prove.',
+        description: 'Record what a change is SUPPOSED to make true, as a durable statement ABOUT THE PRODUCT that a teammate who was not here will understand in six months — name the behaviour, not this run or its step number, and never "renders cleanly", which nothing can check. It is SHARED memory: pooled per project and read back by later agents. Capture it while you still know — then verification does not have to re-derive it from the DOM later. { action:"declare", intents:[{ id, statement, surface? }] } takes prose and needs NO predicate: at declare time there is often no route, no ref and no code yet, and a predicate demanded there is just a mechanism. Declare EARLY (as you build) and batch them — one call per feature is the whole budget. { action:"bind", id, binding } attaches the predicate that would prove it once you know how; an intent with no binding is not a failure, it is the most interesting row in the ledger — something meant that nothing can currently prove. { action:"list" } returns what is still open. Stored in .reticle/intent/<subject>/intent.json (a flow name is its subject), git-checked so a human sees in review if an intent was later narrowed to match what was easy to prove.',
         example: {
             action: DECLARE,
             intents: [
@@ -56,8 +60,8 @@ export const INTENT_TOOLS = [
                 .describe('record only: how settled it is. Defaults to proposed.'),
             intents: z
                 .array(z.object({
-                id: z.string(),
-                statement: z.string(),
+                id: z.string().min(1),
+                statement: z.string().min(1),
                 surface: z
                     .object({
                     route: z.string().optional(),
@@ -69,10 +73,19 @@ export const INTENT_TOOLS = [
                 .optional()
                 .describe('declare only. Batchable — declare every intent for a feature in one call.'),
             id: z.string().optional().describe('bind only: which intent the predicate proves.'),
-            binding: z
-                .unknown()
-                .optional()
-                .describe("bind only: the predicate that would prove it, in reticle_assert's shape."),
+            /*
+             * The predicate schema, not `unknown`.
+             *
+             * The description has always said "in reticle_assert's shape" and the type said "anything",
+             * so a client reading the surface to build this call learned the field's name and nothing
+             * else — the same degradation the recursive `until` predicate suffered when it was converted
+             * without the SDK's own options. This one was not a converter bug: it was declared that way.
+             * Caught by `weakest-client-schemas.test.ts`, which is the first thing that ever looked.
+             *
+             * Accepting the real shape also means a malformed binding is refused at the boundary instead
+             * of being written into the ledger and failing later against a verdict it can never satisfy.
+             */
+            binding: PredicateSchema.optional().describe("bind only: the predicate that would prove it, in reticle_assert's shape."),
             ...sessionIdShape,
         },
         outputSchema: {
@@ -81,6 +94,10 @@ export const INTENT_TOOLS = [
                 .optional()
                 .describe('The intents this call declared, or on `list` everything still open — each { id, statement, state, declaredAt, binding?, surface?, provenBy?, amended? }. `state` is declared (prose only), bound (a predicate exists), or proved (a verdict satisfied it).'),
             bound: z.boolean().optional().describe('bind only: false when the id names no intent.'),
+            refused: z
+                .array(z.object({ id: z.string(), reason: z.string() }))
+                .optional()
+                .describe('declare only: statements not stored, and why.'),
             path: z.string().optional().describe('Where the ledger was written.'),
             entries: z
                 .array(z.unknown())
@@ -130,28 +147,22 @@ export const INTENT_TOOLS = [
                 return { bound: await store.bind(id, args['binding']) };
             }
             if (LIST === action) {
-                /*
-                 * Both files, one answer.
-                 *
-                 * `declare` writes the flat `.reticle/intent.json`; `record` writes the sharded
-                 * `.reticle/intent/`. Listing only the flat one meant a recorded intent could not be found
-                 * again by the agent that had just written it — and the lesson an agent draws from that is
-                 * "the intent does not exist", not "there are two stores".
-                 *
-                 * Merged HERE rather than inside either store: this tool is the one seam that knows both
-                 * exist, and neither store should have to learn the other's layout to stay honest.
-                 */
-                const flat = await store.open();
-                const seen = new Set(flat.map((intent) => intent.id));
-                const fromShards = (await shards.all()).filter((record) => !seen.has(record.id));
-                return { intents: [...flat, ...fromShards] };
+                // One ledger, so one read. This merged two stores while `declare` and `record` wrote two
+                // different files; kept past that, it would add back every PROVED intent to a list that
+                // promises only what is still open.
+                return { intents: await store.open() };
             }
             const raw = args['intents'];
             const entries = Array.isArray(raw)
                 ? raw
                 : [];
             const declared = await store.declare(entries);
-            return { intents: declared, path: root };
+            // Said, not swallowed: an agent that declared something and finds nothing stored would
+            // otherwise conclude the ledger lost it.
+            const refused = entries
+                .filter((entry) => isActionLabel(entry.statement))
+                .map((entry) => ({ id: entry.id, reason: STEP_LABEL_REFUSAL }));
+            return { intents: declared, ...(0 === refused.length ? {} : { refused }), path: root };
         },
     },
 ];

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

@@ -1,4 +1,5 @@
 import { dirname } from 'node:path';
+import { writeFileAtomic } from '../project/fs/write-atomic.js';
 import { reticleDirPaths } from '../project/dir/reticle-dir.js';
 import { AmbientFileSchema } from './on-disk/ambient-file.js';
 import { onlyStableAmbient } from '@reticlehq/engine/window/ambient.js';
@@ -45,8 +46,6 @@ export class AmbientStore {
         // numbering, so persisting it teaches the next session to suppress an element it never saw.
         const regions = onlyStableAmbient(counts);
         const body = `${JSON.stringify({ version: AMBIENT_FILE_VERSION, regions }, null, 2)}\n`;
-        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/deviation-report.js

@@ -1,3 +1,4 @@
+import { routeTemplate } from './route-template.js';
 import { compareSegment, MIN_ENVELOPE_SAMPLES, } from './envelope.js';
 function headlineFor(report) {
     const truncNote = report.truncatedSegments > 0
@@ -31,7 +32,9 @@ export function buildDeviationReport(envelopes, segments, zThreshold) {
             truncated += 1;
             continue;
         }
-        const envelope = envelopes.get(segment.route);
+        // The SAME key the service accumulates under — a lookup on the observed path would miss every
+        // envelope on an app with ids in its URLs, which is the case this templating exists for.
+        const envelope = envelopes.get(routeTemplate(segment.route));
         if (envelope === undefined || envelope.samples < MIN_ENVELOPE_SAMPLES)
             continue;
         judged += 1;

package/dist/memory/journal/deviation-service.js

@@ -1,3 +1,4 @@
+import { routeTemplate } from './route-template.js';
 import { addSegmentToEnvelope, emptyEnvelope } from './envelope.js';
 import { buildDeviationReport } from './deviation-report.js';
 import { withFileLock } from '../project/file-lock.js';
@@ -22,8 +23,15 @@ export async function reportAndAccumulate(store, segments, zThreshold) {
             // Never learn from a truncated sample — its understated counts would poison the baseline.
             if (true === segment.truncated)
                 continue;
-            const current = envelopes.get(segment.route) ?? emptyEnvelope(segment.route);
-            envelopes.set(segment.route, addSegmentToEnvelope(current, segment));
+            /*
+             * Keyed on the route TEMPLATE, not the observed path. Keyed on the path, an app with ids in
+             * its URLs mints one envelope per id, every envelope holds a single sample, and nothing ever
+             * reaches MIN_ENVELOPE_SAMPLES — so the deviation report answers "envelope too new" forever
+             * and the feature never turns on. See route-template.ts.
+             */
+            const key = routeTemplate(segment.route);
+            const current = envelopes.get(key) ?? emptyEnvelope(key);
+            envelopes.set(key, addSegmentToEnvelope(current, segment));
         }
         await store.save(envelopes);
         return report;

package/dist/memory/journal/drive-flow.d.ts

@@ -1,4 +1,4 @@
-import type { FlowExpect, FlowName } from '@reticlehq/core';
+import type { FlowName, Predicate } from '@reticlehq/core';
 /**
  * What this module needs a recorded step to BE, named structurally rather than imported.
  *
@@ -12,7 +12,7 @@ export interface TapeStep {
     tool: string;
     args: Record<string, unknown>;
     stable: boolean;
-    expect?: FlowExpect;
+    expect?: Predicate;
     /** Recorder-internal, and the field journeys are cut on. Never written to the saved flow. */
     route?: string;
 }

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-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.