@reticlehq/server 3.2.0 → 3.3.0

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[];

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

@@ -0,0 +1,88 @@
+import { ReticleDir } from '@reticlehq/core';
+/**
+ * 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 const Durability = {
+    MEMORY: 'memory',
+    EVIDENCE: 'evidence',
+};
+/**
+ * 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 const Sharing = {
+    COMMIT: 'commit',
+    LOCAL: 'local',
+};
+const localDir = { durability: Durability.EVIDENCE, sharing: Sharing.LOCAL, isDirectory: true };
+const localFile = { durability: Durability.MEMORY, sharing: Sharing.LOCAL, isDirectory: false };
+const sharedDir = { durability: Durability.MEMORY, sharing: Sharing.COMMIT, isDirectory: true };
+const sharedFile = { durability: Durability.MEMORY, sharing: Sharing.COMMIT, isDirectory: false };
+/**
+ * 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 const WORKSPACE_TIERS = {
+    [ReticleDir.SESSIONS_SUBDIR]: localDir,
+    [ReticleDir.RUNS_SUBDIR]: localDir,
+    [ReticleDir.VISUAL_SUBDIR]: localDir,
+    // Write-only: a local copy of what was already sent. The outbox is the record.
+    [ReticleDir.FEEDBACK_SUBDIR]: localDir,
+    [ReticleDir.PROJECT_FILE]: localFile,
+    [ReticleDir.AMBIENT_FILE]: localFile,
+    [ReticleDir.ENVELOPES_FILE]: localFile,
+    [ReticleDir.FLAKE_FILE]: localFile,
+    [ReticleDir.TIERS_FILE]: localFile,
+    // The user's own record of what Reticle did for them, on THIS machine.
+    [ReticleDir.IMPACT_FILE]: localFile,
+    // 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]: localFile,
+    // Triage pulled back from the dashboard — a cache of somebody's decisions, re-pullable at will.
+    [ReticleDir.ISSUES_FILE]: localFile,
+    [ReticleDir.CONTRACT_FILE]: sharedFile,
+    [ReticleDir.FLOWS_SUBDIR]: sharedDir,
+    [ReticleDir.BASELINES_SUBDIR]: sharedDir,
+    [ReticleDir.CAPSULES_SUBDIR]: sharedDir,
+    [ReticleDir.INTENT_FILE]: sharedFile,
+    // The sharded form of the same ledger, and shared for the same reason.
+    [ReticleDir.INTENT_SUBDIR]: sharedDir,
+    [ReticleDir.CLOUD_LINK_FILE]: sharedFile,
+    // A hook is a decision the whole team shares, exactly like a package script: one that exists only
+    // on the machine that wrote it is a rule nobody else is following. It names COMMANDS and never a
+    // credential, so it is safe to commit — the same reasoning that puts `cloud.json` here while its
+    // API key stays in ~/.reticle.
+    [ReticleDir.HOOKS_FILE]: sharedFile,
+    // What a drive types into each labelled field. Committed for two reasons: a replay must send
+    // exactly what the recording sent or it is not a replay, and a value a model wrote once should be
+    // reviewable and editable by the team rather than regenerated differently on every machine.
+    [ReticleDir.FILL_VALUES_FILE]: sharedFile,
+};
+function namesWhere(match) {
+    return Object.entries(WORKSPACE_TIERS)
+        .filter(([, tier]) => match(tier))
+        .map(([name]) => name);
+}
+/** Machine-local directories, without the trailing slash the ignore file wants. */
+export const LOCAL_DIRS = namesWhere((tier) => Sharing.LOCAL === tier.sharing && tier.isDirectory);
+/** Machine-local files. */
+export const LOCAL_FILES = namesWhere((tier) => Sharing.LOCAL === tier.sharing && !tier.isDirectory);
+/** The directories retention sweeps, ignored or not. The byte budget and the count bounds read this. */
+export const EVIDENCE_DIRS = namesWhere((tier) => Durability.EVIDENCE === tier.durability && tier.isDirectory);

package/dist/memory/journal/route-template.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The key an envelope's statistics accumulate under.
+ *
+ * The envelope map was keyed on the raw `pathname`. On any app whose URLs carry ids — most of them —
+ * `/orders/1001` and `/orders/1002` are different keys, so every visit mints a fresh envelope
+ * holding one sample.
+ *
+ * The cost is not the file size. `deviation-report` skips any envelope below
+ * `MIN_ENVELOPE_SAMPLES`, so on such an app no envelope ever qualifies, every report answers
+ * "envelope too new", and the deviation feature never turns on at all — silently, permanently, with
+ * nothing anywhere saying why. The unbounded file and the dead feature are one defect.
+ *
+ * CONSERVATIVE on purpose. Over-collapsing is the worse error: merging two genuinely different
+ * routes builds a baseline from two different pages, and a confident comparison against the wrong
+ * population is more expensive than no comparison. So a segment is an id only when it could not
+ * plausibly be a route NAME.
+ *
+ * This is the statistics key alone. The observed path is untouched, because a report has to be able
+ * to say "/orders/1001 was slow" — the template tells you where to look, the path tells you what to
+ * open.
+ */
+export declare function routeTemplate(pathname: string): string;

package/dist/memory/journal/route-template.js

@@ -0,0 +1,44 @@
+/**
+ * The key an envelope's statistics accumulate under.
+ *
+ * The envelope map was keyed on the raw `pathname`. On any app whose URLs carry ids — most of them —
+ * `/orders/1001` and `/orders/1002` are different keys, so every visit mints a fresh envelope
+ * holding one sample.
+ *
+ * The cost is not the file size. `deviation-report` skips any envelope below
+ * `MIN_ENVELOPE_SAMPLES`, so on such an app no envelope ever qualifies, every report answers
+ * "envelope too new", and the deviation feature never turns on at all — silently, permanently, with
+ * nothing anywhere saying why. The unbounded file and the dead feature are one defect.
+ *
+ * CONSERVATIVE on purpose. Over-collapsing is the worse error: merging two genuinely different
+ * routes builds a baseline from two different pages, and a confident comparison against the wrong
+ * population is more expensive than no comparison. So a segment is an id only when it could not
+ * plausibly be a route NAME.
+ *
+ * This is the statistics key alone. The observed path is untouched, because a report has to be able
+ * to say "/orders/1001 was slow" — the template tells you where to look, the path tells you what to
+ * open.
+ */
+/** Stands in for any id segment. Not a valid path segment itself, so it cannot collide with one. */
+const ID = ':id';
+/** 8+ hex characters: a token, a hash, a short uuid. Below that it is as likely to be a word. */
+const LONG_HEX = /^[0-9a-f]{8,}$/i;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const ALL_DIGITS = /^\d+$/;
+/**
+ * A year collapses too, and that is a deliberate trade rather than an oversight: `/reports/2024`
+ * and `/reports/2025` are the same page with different data, which is exactly what one envelope
+ * should describe. Distinguishing a year from an id needs to know the app, and guessing would
+ * reintroduce the split this exists to remove.
+ */
+function isIdSegment(segment) {
+    return ALL_DIGITS.test(segment) || UUID.test(segment) || LONG_HEX.test(segment);
+}
+export function routeTemplate(pathname) {
+    if (0 === pathname.length)
+        return pathname;
+    return pathname
+        .split('/')
+        .map((segment) => (isIdSegment(segment) ? ID : segment))
+        .join('/');
+}

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

@@ -3,6 +3,7 @@ import { type OnboardingStep } from '@reticlehq/core/telemetry';
 import type { AmbientCounts } from '@reticlehq/engine/window/ambient.js';
 import { type ProjectId, type JournalAction } from '@reticlehq/core';
 import type { FileSystemPort } from '../project/fs/fs-port.js';
+import { type PruneWorkspaceOptions } from './on-disk/startup-maintenance.js';
 /**
  * Session teardown: the durable half of ending a session. Two things must happen when a tab disconnects,
  * and neither did before — the journal batches events and only writes at its flush threshold, so the tail
@@ -44,8 +45,10 @@ export interface SessionEndTarget {
 interface SessionEndDeps {
     fs: FileSystemPort;
     reticleRoot: string;
-    /** Journaling/persistence off (opt-out) → teardown is a no-op. */
+    /** Journaling/persistence off (opt-out) → teardown is a no-op. Retention still runs. */
     enabled: boolean;
+    /** What this project is willing to keep — the `retain` block of its `.reticle.json`. */
+    retain?: PruneWorkspaceOptions;
     /**
      * The one clock in this file, injected — the run artifact stamps `createdAt` from it.
      *

package/dist/memory/journal/session-end.js

@@ -1,8 +1,10 @@
 import { driveFlowsFrom } from './drive-flow.js';
+import { journalActionsPath, sessionDirPath } from '../project/dir/reticle-dir.js';
+import { asSessionId } from '@reticlehq/core';
 import { OnboardingPhase, OnboardingStepStatus, } from '@reticlehq/core/telemetry';
 import { AmbientStore } from './ambient-store.js';
 import { subjectOf } from '@reticlehq/core';
-import { pruneSessions } from './on-disk/retention.js';
+import { pruneWorkspace } from './on-disk/startup-maintenance.js';
 import { buildVerificationRun } from '../../judgement/runs/artifact/build-verification-run.js';
 import { driveRunFrom, driveRunId } from '../../judgement/runs/drive-run.js';
 import { RunStore } from '../../judgement/runs/artifact/run-store.js';
@@ -13,8 +15,28 @@ import { RunStore } from '../../judgement/runs/artifact/run-store.js';
  */
 export function makeSessionEnd(deps) {
     return async (session) => {
-        if (!deps.enabled)
+        /*
+         * Retention is maintenance of a directory, not a part of journalling, so it runs either way.
+         *
+         * Teardown used to return here, and this is the one setting under which that mattered most:
+         * somebody switches journalling off BECAUSE `.reticle/` got too big, and switching it off was
+         * what stopped anything ever deleting what was already there. It also stopped the sweep of
+         * visual diffs, feedback copies and run artifacts, none of which need the journal to be written
+         * at all. The daemon's own start-path sweep was gated on the same flag, so there was no second
+         * site still running — both are ungated now.
+         */
+        const sweep = async () => {
+            try {
+                await pruneWorkspace(deps.fs, session.artifactRoot ?? deps.reticleRoot, deps.liveSessionIds?.() ?? new Set(), deps.retain ?? {});
+            }
+            catch {
+                // retention is best-effort maintenance; never surface at teardown
+            }
+        };
+        if (!deps.enabled) {
+            await sweep();
             return;
+        }
         try {
             await session.flushJournal();
         }
@@ -101,13 +123,31 @@ export function makeSessionEnd(deps) {
             // The root this session actually journalled into. Pruning the daemon's tree instead meant a
             // per-project workspace was never swept at all, so the one place journals really accumulate
             // was the one place retention never ran.
-            await pruneSessions(deps.fs, session.artifactRoot ?? deps.reticleRoot, {
-                live: deps.liveSessionIds?.(),
-            });
+            /*
+             * A session nobody ever drove keeps no journal.
+             *
+             * The observers run from the moment the SDK attaches, so an idle tab on a busy page
+             * accumulates megabytes without a single tool call. The cost is not the disk: those
+             * directories occupy retention SLOTS, so a journal that could answer a verdict question is
+             * evicted by one that was never asked one.
+             *
+             * Decided at the END and never by gating CAPTURE. Whether a tool call will happen is not
+             * knowable while the events that would answer it are being recorded, and gating capture on it
+             * would leave the first assertion of a session with nothing to read.
+             */
+            await dropUndrivenJournal(deps.fs, session.artifactRoot ?? deps.reticleRoot, asSessionId(session.id));
         }
         catch {
-            // retention is best-effort maintenance; never surface at teardown
+            // teardown must never throw: the tab is already gone
         }
+        // EVERY tier, not just sessions. Visual diffs and feedback copies were pruned only at daemon
+        // start, against the DAEMON's root — which for a globally registered daemon is `$HOME` and not
+        // the project at all, so the two tiers that only ever grow in a project workspace were the two
+        // never swept there. Same defect as the one this line already fixed for sessions, one move
+        // behind. The byte budget rides along for the same reason: it was wired at daemon start too.
+        //
+        // Outside the try above, so a failure anywhere in teardown still leaves the directory swept.
+        await sweep();
     };
 }
 /**
@@ -177,3 +217,21 @@ async function saveDrivenFlow(deps, session) {
         ...(outcome.unprovenSteps === undefined ? {} : { reason: 'no_declared_consequence' }),
     });
 }
+/**
+ * Remove this session's journal when it served no tool call.
+ *
+ * "Served no tool call" is read off the actions ledger, which is written one line per call: absent
+ * or empty means nothing was ever driven here. Best-effort like every other maintenance step —
+ * a session that cannot be tidied is not a session that failed.
+ */
+async function dropUndrivenJournal(fs, root, sessionId) {
+    try {
+        const actions = await fs.readFile(journalActionsPath(root, sessionId)).catch(() => '');
+        if (actions.trim().length > 0)
+            return;
+        await fs.rm(sessionDirPath(root, sessionId));
+    }
+    catch {
+        // tidying is never the reason a teardown fails
+    }
+}

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

@@ -1,6 +1,6 @@
 import { type JournalAction, type JournalWriteLoss, type ReticleEvent } from '@reticlehq/core';
 import type { FileSystemPort } from '../project/fs/fs-port.js';
-import type { JournalReadLoss } from './journal-recorder.js';
+import type { JournalLedgerSize, JournalReadLoss } from './journal-recorder.js';
 /**
  * The two ceilings a durable read is held to.
  *
@@ -115,6 +115,13 @@ export declare class SessionJournal {
      * file, as opposed to what a bounded read declined to hand back.
      */
     readWriteLoss(): Promise<JournalWriteLoss | undefined>;
+    /**
+     * The ledger's size against its ceiling, once the size is known.
+     *
+     * `undefined` before the first append, because `#eventBytes` is seeded from `stat` at that point
+     * and a zero reported before it is measured would be a claim rather than a reading.
+     */
+    ledger(): JournalLedgerSize | undefined;
     appendAction(action: JournalAction): Promise<void>;
     readEvents(): Promise<ReticleEvent[]>;
     /**

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

@@ -281,6 +281,16 @@ export class SessionJournal {
     async readWriteLoss() {
         return this.#closureReport();
     }
+    /**
+     * The ledger's size against its ceiling, once the size is known.
+     *
+     * `undefined` before the first append, because `#eventBytes` is seeded from `stat` at that point
+     * and a zero reported before it is measured would be a claim rather than a reading.
+     */
+    ledger() {
+        const bytes = this.#eventBytes;
+        return bytes === undefined ? undefined : { bytes, capBytes: this.#eventBytesCap };
+    }
     /**
      * Close the ledger for good, and declare the loss twice — durably, then in-band.
      *

package/dist/memory/project/baselines.d.ts

@@ -1,4 +1,4 @@
-export interface Baseline {
+interface Baseline {
     name: string;
     lines: string[];
     route: string;

package/dist/memory/project/dir/reticle-dir.d.ts

@@ -15,7 +15,7 @@ export interface ReticleDirPaths {
     project: string;
     /**.../.reticle/impact.json (what Reticle has done for this user, local only) */
     impact: string;
-    /**.../.reticle/intent.json (what changes were supposed to make true — git-checked) */
+    /**.../.reticle/intent.json — the LEGACY single ledger, read until the first write migrates it into .reticle/intent/ */
     intent: string;
     /**.../.reticle/fill-values.json (what a drive types into each labelled field — git-checked) */
     fillValues: string;