@reticlehq/server 3.1.0 → 3.2.0

package/dist/memory/cloud/harness-offer.js

@@ -0,0 +1,146 @@
+/**
+ * Whether this workspace has taken the three months of free harness, read by the thing that would
+ * advertise it.
+ *
+ * The HUD can only advertise honestly if it knows, and only the platform knows. This is the read —
+ * filed beside the other reads of the linked account rather than with the harness itself, because
+ * nothing that DRIVES needs it; the thing that needs it is the snapshot the HUD paints from. Same
+ * shape as the harness's own `platform-config.ts` and for the same reasons: it is INFORMATION, not a
+ * credential, so every failure answers `undefined`, which every caller must treat as "say nothing"
+ * rather than as "not claimed". An offline laptop must not start advertising something the person
+ * already owns.
+ *
+ * It is also SYNCHRONOUS at the point of use. The impact snapshot is built inline, dozens of times a
+ * session, and the answer changes about once per workspace lifetime, so a cache that refreshes in
+ * the background is the whole design: readers get what we last heard, and a stale answer is only
+ * ever stale in the safe direction — the card the person is looking at is the one they can act on.
+ */
+import { ReticleEnv, apiKeyFrom } from '@reticlehq/core';
+const OFFER_PATH = '/v1/harness/offer';
+/** Same budget as the model-config read: a drive must never wait on an advert. */
+const TIMEOUT_MS = 2_000;
+/**
+ * How long a cached answer is trusted.
+ *
+ * A claim happens once. The only transition worth catching quickly is the one the person just made
+ * in another tab, and ten minutes is well inside the time it takes them to come back and look.
+ */
+const FRESH_MS = 10 * 60 * 1_000;
+/**
+ * Parse the platform's answer.
+ *
+ * The platform reports `null` for "never claimed" on the fields it has no value for; the wire
+ * contract says ABSENT. They are the same fact and the translation belongs here, at the edge,
+ * rather than in a HUD that would then need to know about two spellings of nothing.
+ */
+function parse(body, claimUrl) {
+    try {
+        const parsed = JSON.parse(body);
+        if ('object' !== typeof parsed || null === parsed)
+            return undefined;
+        const record = parsed;
+        const claimed = record['claimed'];
+        if ('boolean' !== typeof claimed)
+            return undefined;
+        const offer = { claimed };
+        const expiresAt = record['expiresAt'];
+        if ('number' === typeof expiresAt)
+            offer.expiresAt = expiresAt;
+        const days = record['daysRemaining'];
+        if ('number' === typeof days)
+            offer.daysRemaining = days;
+        // The one field that cannot be inferred from the others: a LAPSED claim reports `claimed:false`
+        // and `daysRemaining:0`, which is indistinguishable from never having claimed unless the
+        // platform's own answer about offerability is carried through.
+        const eligible = record['eligible'];
+        if ('boolean' === typeof eligible)
+            offer.eligible = eligible;
+        if (claimUrl !== undefined && 0 < claimUrl.length)
+            offer.claimUrl = claimUrl;
+        return offer;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Ask the platform where this workspace stands. `undefined` means "no answer", never "not claimed". */
+export async function fetchHarnessOffer(env, claimUrl, doFetch = (url, init) => fetch(url, init), timeoutMs = TIMEOUT_MS) {
+    const key = apiKeyFrom(env);
+    const host = env[ReticleEnv.CLOUD_URL];
+    if (key === undefined || 0 === key.length)
+        return undefined;
+    if (host === undefined || 0 === host.length)
+        return undefined;
+    const controller = new AbortController();
+    const timer = setTimeout(() => {
+        controller.abort();
+    }, timeoutMs);
+    try {
+        const res = await doFetch(`${host.replace(/\/+$/, '')}${OFFER_PATH}`, {
+            method: 'GET',
+            headers: { authorization: `Bearer ${key}` },
+            signal: controller.signal,
+        });
+        if (!res.ok)
+            return undefined;
+        return parse(await res.text(), claimUrl);
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * A self-refreshing cache over the read above.
+ *
+ * Deliberately NOT a timer. A daemon that lives for days would otherwise hold an interval whose only
+ * job is to re-ask a question nobody is asking, and it would have to be torn down in a place that
+ * already has nine teardowns. Refreshing on a stale READ means the work only happens while somebody
+ * is actually looking, and the first read of a process — which is always stale — starts the fetch
+ * that the second read answers from.
+ */
+export function harnessOfferSource(env, claimUrl, now = () => Date.now(), load = (claim) => fetchHarnessOffer(env, claim)) {
+    let cached;
+    // `undefined` rather than 0: "never asked" is a different state from "asked at the epoch", and
+    // conflating them made a source with an injected clock never take its first read.
+    let fetchedAt;
+    let inFlight = false;
+    const refresh = () => {
+        if (inFlight)
+            return;
+        inFlight = true;
+        void load(claimUrl())
+            .then((offer) => {
+            // A failed read keeps the LAST good answer rather than blanking the card mid-session: one
+            // dropped request is not evidence that the offer changed.
+            if (offer !== undefined)
+                cached = offer;
+            fetchedAt = now();
+        })
+            .catch(() => {
+            fetchedAt = now();
+        })
+            .finally(() => {
+            inFlight = false;
+        });
+    };
+    /*
+     * Asked once at construction, not first read.
+     *
+     * Measured in a browser: a daemon pushes the impact snapshot the INSTANT a session attaches, and
+     * on a page nobody drives that is the only push there will ever be. Refreshing on the first read
+     * meant that push always carried "we have not heard", the answer landed a moment later with
+     * nobody to tell, and the HUD showed nothing for the whole session. Starting the fetch when the
+     * daemon starts puts the answer in place before any page can connect.
+     */
+    refresh();
+    return {
+        read() {
+            if (fetchedAt === undefined || FRESH_MS <= now() - fetchedAt)
+                refresh();
+            return cached;
+        },
+    };
+}

package/dist/memory/cloud/harness-switch.d.ts

@@ -0,0 +1,11 @@
+export type SwitchFetch = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body: string;
+    signal?: AbortSignal;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+}>;
+/** `true` when the platform accepted it. Callers use this for logging, never to block a person. */
+export declare function writeHarnessSwitch(env: Record<string, string | undefined>, enabled: boolean, doFetch?: SwitchFetch, timeoutMs?: number): Promise<boolean>;

package/dist/memory/cloud/harness-switch.js

@@ -0,0 +1,53 @@
+/**
+ * Write the harness switch back to the platform.
+ *
+ * The panel does not keep this state — it emits an intent and this puts it where the dashboard can
+ * see it, so the two surfaces cannot disagree. Only the switch is sent: somebody who chose a
+ * provider in the console must not have it reset by a panel that never rendered one. The platform's
+ * PUT is what guarantees that, not the verb -- it merges the fields it is given and leaves the rest,
+ * which its own spec pins ("leaves the fields it was not sent alone").
+ *
+ * It says PUT because that is what the platform registers. It said PATCH for one release, against a
+ * route that has only ever served GET and PUT, so every write 404'd. Nothing reported it: the call
+ * is fire-and-forget and failure here is deliberately silent, so the switch simply sprang back on
+ * the next snapshot and looked like a UI that would not stick.
+ *
+ * Failure is SILENT by design, and that deserves saying plainly rather than being discovered. A
+ * dev-only overlay that threw a dialog because a settings write timed out would be worse than one
+ * that quietly did not save; the next snapshot re-reads the platform, so a lost write shows up as
+ * the switch springing back, which is a truthful thing for it to do.
+ */
+import { ReticleEnv, apiKeyFrom } from '@reticlehq/core';
+const CONFIG_PATH = '/v1/model/config';
+/** Same budget as the read beside it: a settings write must never hold anything up. */
+const TIMEOUT_MS = 2_000;
+/** `true` when the platform accepted it. Callers use this for logging, never to block a person. */
+export async function writeHarnessSwitch(env, enabled, doFetch = (url, init) => fetch(url, init), timeoutMs = TIMEOUT_MS) {
+    const key = apiKeyFrom(env);
+    const host = env[ReticleEnv.CLOUD_URL];
+    if (key === undefined || 0 === key.length)
+        return false;
+    if (host === undefined || 0 === host.length)
+        return false;
+    const controller = new AbortController();
+    const timer = setTimeout(() => {
+        controller.abort();
+    }, timeoutMs);
+    try {
+        // No projectId in the body: the key IS project-scoped, and the platform refuses to let a key
+        // name somebody else's project. Sending one would be asking for a privilege we do not have.
+        const res = await doFetch(`${host.replace(/\/+$/, '')}${CONFIG_PATH}`, {
+            method: 'PUT',
+            headers: { authorization: `Bearer ${key}`, 'content-type': 'application/json' },
+            body: JSON.stringify({ harnessEnabled: enabled }),
+            signal: controller.signal,
+        });
+        return res.ok;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/memory/cloud/sync-daemon.d.ts

@@ -1,5 +1,6 @@
 import { type SyncReport } from './sync-cycle.js';
-import type { ProjectCloud } from './cloud-config.js';
+import { type ProjectCloud } from './cloud-config.js';
+import type { FileSystemPort } from '../project/fs/fs-port.js';
 interface SyncDaemonDeps {
     reticleRoot: string;
     /** Resolved per tick, not once: a repo linked while the daemon is alive starts syncing itself. */
@@ -29,7 +30,7 @@ interface SyncDaemonDeps {
         text: string;
     }>;
 }
-interface SyncDaemon {
+export interface SyncDaemon {
     /** Run one cycle now, whatever the timer is doing. Returns undefined when not linked. */
     syncNow: () => Promise<SyncReport | undefined>;
     /**
@@ -50,4 +51,23 @@ interface SyncDaemon {
  * nothing until one appears, which is what lets `reticle link` take effect without a restart.
  */
 export declare function startSyncDaemon(deps: SyncDaemonDeps): SyncDaemon;
+/**
+ * Start cloud sync for a daemon and hand back the two hooks the daemon wires to it.
+ *
+ * The wiring lived in `index.ts`, which sits exactly on the thousand-line cap — so the next thing
+ * anyone needed there could not be added without a split, and this is the block that most obviously
+ * did not belong in a bootstrap file. Four calls that are all one concern: what to sync, where else
+ * to look, how a landed run wakes it, and what the panel's button does.
+ *
+ * Returns the daemon itself: the caller still owns when to nudge, when to sync now, and when to
+ * stop. Only the CONSTRUCTION moved, which is the part that was four interdependent arguments about
+ * resolving a credential — and the part a bootstrap file has no business spelling out.
+ */
+export declare function attachCloudSync(deps: {
+    fs: FileSystemPort;
+    reticleRoot: string;
+    homeDir: string;
+    env: NodeJS.ProcessEnv;
+    otherRoots: () => readonly string[];
+}): SyncDaemon;
 export {};

package/dist/memory/cloud/sync-daemon.js

@@ -25,6 +25,7 @@ import { log } from '../../log.js';
 import { emitSyncHook } from '../../hooks/hook-emit.js';
 import { describeSync, runSyncCycle } from './sync-cycle.js';
 import { diskSink, diskSource, readCloudState } from './sync-disk.js';
+import { resolveProjectCloud } from './cloud-config.js';
 /** How often the daemon cycles. See the note above on why this is a constant and not a curve. */
 const DAEMON_SYNC_INTERVAL_MS = 60_000;
 /**
@@ -271,3 +272,26 @@ export function startSyncDaemon(deps) {
         },
     };
 }
+/**
+ * Start cloud sync for a daemon and hand back the two hooks the daemon wires to it.
+ *
+ * The wiring lived in `index.ts`, which sits exactly on the thousand-line cap — so the next thing
+ * anyone needed there could not be added without a split, and this is the block that most obviously
+ * did not belong in a bootstrap file. Four calls that are all one concern: what to sync, where else
+ * to look, how a landed run wakes it, and what the panel's button does.
+ *
+ * Returns the daemon itself: the caller still owns when to nudge, when to sync now, and when to
+ * stop. Only the CONSTRUCTION moved, which is the part that was four interdependent arguments about
+ * resolving a credential — and the part a bootstrap file has no business spelling out.
+ */
+export function attachCloudSync(deps) {
+    return startSyncDaemon({
+        reticleRoot: deps.reticleRoot,
+        cloud: () => resolveProjectCloud(deps.fs, deps.reticleRoot, deps.homeDir, deps.env),
+        // Every OTHER linked repo on this machine, not just the directory the daemon was started in.
+        // One daemon serves many projects, and pushing only its own root left the rest silently
+        // reporting nothing — indistinguishable, on the dashboard, from nobody having verified anything.
+        otherRoots: () => Promise.resolve(deps.otherRoots()),
+        cloudFor: (root) => resolveProjectCloud(deps.fs, root, deps.homeDir, deps.env),
+    });
+}

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

@@ -1,4 +1,5 @@
 import { type ImpactCounts, type ImpactDefect, type ImpactSnapshot } from '@reticlehq/core';
+import type { ConfigSource } from '../cloud/harness-config.js';
 import { ImpactStore, type ImpactFoldMeta } from './impact-store.js';
 /**
  * Wire the DEFAULT root — the daemon's own. Idempotent; the first one wins.
@@ -8,6 +9,13 @@ import { ImpactStore, type ImpactFoldMeta } from './impact-store.js';
  * project passes one, and this is the fallback for calls that do not.
  */
 export declare function initImpact(opts: {
+    /**
+     * The harness-config source, supplied by whoever wired the daemon.
+     *
+     * Passed in rather than built here: reading the platform lives in `features/harness`, and this
+     * directory may not reach for it. The daemon owns both sides.
+     */
+    config?: ConfigSource;
     reticleRoot: string | undefined;
     projectName?: string;
     now?: () => number;

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

@@ -50,10 +50,11 @@ export function initImpact(opts) {
         return storeFor(undefined);
     if (defaultRoot === undefined) {
         defaultRoot = opts.reticleRoot;
-        const { projectName, now } = opts;
+        const { projectName, now, config } = opts;
         storeOpts = {
             ...(projectName === undefined ? {} : { projectName }),
             ...(now === undefined ? {} : { now }),
+            ...(config === undefined ? {} : { config }),
         };
     }
     return storeFor(opts.reticleRoot);

package/dist/memory/impact/impact-store.d.ts

@@ -1,3 +1,5 @@
+import { type OfferSource } from '../cloud/harness-offer.js';
+import type { ConfigSource } from '../cloud/harness-config.js';
 import { type ImpactCounts, type ImpactDefect, type AccountState, type ImpactScope, type ImpactSnapshot } from '@reticlehq/core';
 /** Read a scope, tolerating absence and corruption: a broken file starts over rather than throwing. */
 export declare function readScope(path: string, now: number): ImpactScope;
@@ -37,6 +39,9 @@ export declare class ImpactStore {
         globalRoot?: string;
         /** Reads whether this machine is signed in. Injected so the store stays testable and pure-ish. */
         account?: () => AccountState;
+        /** Where the workspace stands with the free harness offer. Injected so no test touches a network. */
+        offer?: OfferSource;
+        config?: ConfigSource;
     });
     /** Notified after every fold, so the HUD can be pushed a fresh snapshot. */
     onChange(fn: () => void): void;

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

@@ -2,6 +2,7 @@ import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { homedir } from 'node:os';
 import { readAccountState } from '../cloud/account-state.js';
+import { harnessOfferSource } from '../cloud/harness-offer.js';
 import { ReticleDir, IMPACT_DAILY_BUCKETS, IMPACT_DEFECT_LIMIT, IMPACT_SCHEMA_VERSION, ImpactScopeSchema, addImpactCounts, emptyImpactCounts, emptyImpactRecords, estimateImpactSavings, } from '@reticlehq/core';
 /**
  * Where Reticle keeps the record of what it has done for you.
@@ -174,6 +175,9 @@ export class ImpactStore {
     #timer;
     #onChange;
     #account;
+    /** Where this workspace stands with the free harness offer. Cached; see harness-offer.ts. */
+    #offer;
+    #config;
     constructor(opts) {
         this.#paths = impactPaths(opts.reticleRoot, opts.globalRoot ?? homedir());
         // Resolved per snapshot, not cached: a user who runs `reticle login` in another terminal must
@@ -182,6 +186,12 @@ export class ImpactStore {
         this.#now = opts.now ?? (() => Date.now());
         this.#projectName = opts.projectName;
         this.#dashboardUrl = readDashboardUrl(opts.reticleRoot);
+        // The claim happens in the console, so the link this project was linked to IS the claim link —
+        // built here rather than in the HUD, which has no way to know where this project points.
+        this.#offer = opts.offer ?? harnessOfferSource(process.env, () => this.#dashboardUrl);
+        // No default: the loader lives in `features/harness` and this file may not reach for it.
+        // A store built without one simply reports no harness config, which the HUD renders as no row.
+        this.#config = opts.config ?? { read: () => undefined };
         const now = this.#now();
         this.#project = readScope(this.#paths.project, now);
         this.#global = readScope(this.#paths.global, now);
@@ -211,6 +221,15 @@ export class ImpactStore {
         if (this.#dashboardUrl !== undefined)
             snap.dashboardUrl = this.#dashboardUrl;
         snap.account = this.#account();
+        const offer = this.#offer.read();
+        // Absent means "we have not heard", which the HUD renders as nothing at all. Never defaulted to
+        // `{claimed:false}`: that would advertise the offer to everyone who is offline.
+        if (offer !== undefined)
+            snap.harnessOffer = offer;
+        // Absent stays absent: the HUD reads that as "we have not heard" and renders no control.
+        const cfg = this.#config.read();
+        if (cfg !== undefined)
+            snap.harnessConfig = cfg;
         return snap;
     }
     /** Write now (process exit, tests). */

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

@@ -20,11 +20,11 @@
  * is a separate decision somebody can take once they believe the migration.
  */
 import { parseIntentFile } from '@reticlehq/core/artifacts';
+import { ReticleDir } from '@reticlehq/core';
 import { reticleDirPaths } from '../project/dir/reticle-dir.js';
 import { withFileLock } from '../project/file-lock.js';
 import { subjectFor } from './intent-subject.js';
 import { emptyShard, indexFrom, IntentShardSchema, IntentStatus, recordFromIntent, serialise, shardsFrom, readJsonFile, } from './intent-shard.js';
-const INTENT_DIR = 'intent';
 const INDEX_FILE = 'index.json';
 const SHARD_SUFFIX = '.json';
 export class IntentShardStore {
@@ -37,7 +37,7 @@ export class IntentShardStore {
         this.#clock = clock;
     }
     #dir() {
-        return `${reticleDirPaths(this.#root).root}/${INTENT_DIR}`;
+        return `${reticleDirPaths(this.#root).root}/${ReticleDir.INTENT_SUBDIR}`;
     }
     #indexPath() {
         return `${this.#dir()}/${INDEX_FILE}`;

package/dist/memory/intent/intent-shard.d.ts

@@ -94,7 +94,7 @@ declare const IntentRecordSchema: z.ZodObject<{
     /** When it was last touched, so a stale-looking record can be told from an untouched one. */
     updatedAt: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
-    status: "proved" | "stale" | "proposed" | "agreed";
+    status: "proved" | "proposed" | "agreed" | "stale";
     state: "proved" | "declared" | "bound";
     id: string;
     subject: string;
@@ -119,7 +119,7 @@ declare const IntentRecordSchema: z.ZodObject<{
         statement: string;
     }[] | undefined;
 }, {
-    status: "proved" | "stale" | "proposed" | "agreed";
+    status: "proved" | "proposed" | "agreed" | "stale";
     state: "proved" | "declared" | "bound";
     id: string;
     subject: string;
@@ -201,7 +201,7 @@ export declare const IntentShardSchema: z.ZodObject<{
         /** When it was last touched, so a stale-looking record can be told from an untouched one. */
         updatedAt: z.ZodOptional<z.ZodNumber>;
     }, "strip", z.ZodTypeAny, {
-        status: "proved" | "stale" | "proposed" | "agreed";
+        status: "proved" | "proposed" | "agreed" | "stale";
         state: "proved" | "declared" | "bound";
         id: string;
         subject: string;
@@ -226,7 +226,7 @@ export declare const IntentShardSchema: z.ZodObject<{
             statement: string;
         }[] | undefined;
     }, {
-        status: "proved" | "stale" | "proposed" | "agreed";
+        status: "proved" | "proposed" | "agreed" | "stale";
         state: "proved" | "declared" | "bound";
         id: string;
         subject: string;
@@ -255,7 +255,7 @@ export declare const IntentShardSchema: z.ZodObject<{
     version: 1;
     subject: string;
     intents: Record<string, {
-        status: "proved" | "stale" | "proposed" | "agreed";
+        status: "proved" | "proposed" | "agreed" | "stale";
         state: "proved" | "declared" | "bound";
         id: string;
         subject: string;
@@ -284,7 +284,7 @@ export declare const IntentShardSchema: z.ZodObject<{
     version: 1;
     subject: string;
     intents: Record<string, {
-        status: "proved" | "stale" | "proposed" | "agreed";
+        status: "proved" | "proposed" | "agreed" | "stale";
         state: "proved" | "declared" | "bound";
         id: string;
         subject: string;
@@ -319,12 +319,12 @@ declare const IntentIndexEntrySchema: z.ZodObject<{
     statement: z.ZodString;
     status: z.ZodEnum<["proposed", "agreed", "proved", "stale"]>;
 }, "strip", z.ZodTypeAny, {
-    status: "proved" | "stale" | "proposed" | "agreed";
+    status: "proved" | "proposed" | "agreed" | "stale";
     id: string;
     subject: string;
     statement: string;
 }, {
-    status: "proved" | "stale" | "proposed" | "agreed";
+    status: "proved" | "proposed" | "agreed" | "stale";
     id: string;
     subject: string;
     statement: string;
@@ -338,19 +338,19 @@ export declare const IntentIndexSchema: z.ZodObject<{
         statement: z.ZodString;
         status: z.ZodEnum<["proposed", "agreed", "proved", "stale"]>;
     }, "strip", z.ZodTypeAny, {
-        status: "proved" | "stale" | "proposed" | "agreed";
+        status: "proved" | "proposed" | "agreed" | "stale";
         id: string;
         subject: string;
         statement: string;
     }, {
-        status: "proved" | "stale" | "proposed" | "agreed";
+        status: "proved" | "proposed" | "agreed" | "stale";
         id: string;
         subject: string;
         statement: string;
     }>, "many">;
 }, "strip", z.ZodTypeAny, {
     entries: {
-        status: "proved" | "stale" | "proposed" | "agreed";
+        status: "proved" | "proposed" | "agreed" | "stale";
         id: string;
         subject: string;
         statement: string;
@@ -358,7 +358,7 @@ export declare const IntentIndexSchema: z.ZodObject<{
     version: 1;
 }, {
     entries: {
-        status: "proved" | "stale" | "proposed" | "agreed";
+        status: "proved" | "proposed" | "agreed" | "stale";
         id: string;
         subject: string;
         statement: string;

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

@@ -3,6 +3,17 @@ import { JournalRecorder, type JournalReader } from './journal-recorder.js';
 /** The minimal Session surface the journal attachment needs (Session satisfies it structurally). */
 export interface JournalTarget {
     readonly id: string;
+    /**
+     * The `.reticle` this session's artifacts belong in, stamped on session-create before this runs.
+     *
+     * The journal used to go to the daemon's own root — wherever the agent was launched — while the
+     * run artifact written at teardown already used this one. The journal is the worse half to
+     * misroute: it carries URLs, request and response bodies and DOM text from the app under test, so
+     * a daemon started in a backend wrote that app's traffic into a repository nobody instrumented,
+     * and the `.reticle/.gitignore` meant to keep journals out of a shared repo was being written into
+     * the OTHER tree. Undefined only when no project could be resolved, which keeps the old fallback.
+     */
+    readonly artifactRoot?: string | undefined;
     /** Milliseconds since the session connected — the recorder's injected clock. */
     elapsed(): number;
     setJournal(recorder: JournalRecorder, reader?: JournalReader): void;

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

@@ -19,7 +19,7 @@ export function makeJournalAttach(deps) {
             log('journal_skipped_unsafe_session_id', { sessionId: session.id });
             return;
         }
-        const journal = new SessionJournal(deps.fs, deps.reticleRoot, session.id);
+        const journal = new SessionJournal(deps.fs, session.artifactRoot ?? deps.reticleRoot, session.id);
         // Same SessionJournal is both the write sink and the read fall-through for queries after eviction.
         session.setJournal(new JournalRecorder(journal, { now: () => session.elapsed() }), journal);
     };

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

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

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

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