@reticlehq/server 3.2.0 → 3.4.0

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

@@ -0,0 +1,90 @@
+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,
+    // What THIS machine's drives covered, and the best each level reached — the gate's ratchet.
+    [ReticleDir.COVERAGE_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.
      *
@@ -76,8 +79,16 @@ interface SessionEndDeps {
      * this handler follows.
      */
     flows?: {
-        save: (program: DriveProgram, annotations?: undefined, projectId?: ProjectId) => Promise<unknown>;
+        saveJourney: (program: DriveProgram, projectId: ProjectId | undefined, prefix: string) => Promise<unknown>;
     };
+    /**
+     * The flow store for a session's own `.reticle`. Drive flows used to go to `flows` above — the
+     * daemon's launch directory — while replay reads the session's project, so a daemon started
+     * anywhere else saved flows nothing could replay. Absent, `flows` is used.
+     */
+    flowsAt?: (root: string) => NonNullable<SessionEndDeps['flows']>;
+    /** Who is driving — stamped on each saved flow. Injected: teardown does not reach into MCP. */
+    author?: () => DriveProgram['author'];
     /**
      * Called when a run artifact is written, so cloud sync can cycle instead of waiting for its timer.
      *

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

@@ -1,8 +1,17 @@
-import { driveFlowsFrom } from './drive-flow.js';
+import { DRIVE_FLOW_PREFIX, driveFlowsFrom, } from './drive-flow.js';
+import { log } from '../../log.js';
+/** What a session's teardown writes to the daemon log when a by-product fails to save. */
+const SESSION_END_LOG = {
+    FLOW_SAVE_FAILED: 'reticle_drive_flow_save_failed',
+    RUN_RECORD_FAILED: 'reticle_drive_run_record_failed',
+};
+const errorMessage = (error) => error instanceof Error ? error.message : String(error);
+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 +22,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();
         }
@@ -56,24 +85,27 @@ export function makeSessionEnd(deps) {
         // would buy under a minute of latency for a mutable handle held across two wiring sites.
         // A DRIVE IS A REGRESSION TEST, and it used to need somebody to remember to say so.
         //
-        // `record{start}` + `flow_save` is the agent-facing route and agents do not take it: the corpus
-        // measures 3 of 33 flows mutation-testable and 6 of 112 steps declaring a consequence, while the
-        // engine catches 84 of the 86 bugs it structurally can. The ceiling is how many flows EXIST that
-        // could go red, so a drive that is never saved is a regression test paid for and thrown away.
+        // `record{start}` + `flow_save` is the agent-facing route and agents do not take it: few saved
+        // flows are mutation-testable and few steps declare a consequence, while the engine catches
+        // nearly every bug it structurally can. The ceiling is how many flows EXIST that could go red,
+        // so a drive that is never saved is a regression test paid for and thrown away.
         //
         // Saved only when the tape declared a consequence — see drive-flow.ts for why the alternative is
         // a false-green factory running once per session.
         try {
             await saveDrivenFlow(deps, session);
         }
-        catch {
-            // a flow is a by-product of the session; failing to write one never fails the teardown
+        catch (error) {
+            // A flow is a by-product of the session; failing to write one never fails the teardown. It is
+            // logged, because a drive that leaves no flow and no reason is otherwise undiagnosable.
+            log(SESSION_END_LOG.FLOW_SAVE_FAILED, { error: errorMessage(error) });
         }
         try {
             await recordDriveRun(deps, session);
         }
-        catch {
-            // an artifact is a report ABOUT the session; failing to write one never fails the teardown
+        catch (error) {
+            // An artifact is a report ABOUT the session; failing to write one never fails the teardown.
+            log(SESSION_END_LOG.RUN_RECORD_FAILED, { error: errorMessage(error) });
         }
         try {
             // Bound the journal on disk HERE, not only at daemon start.
@@ -101,13 +133,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();
     };
 }
 /**
@@ -156,13 +206,15 @@ export async function recordDriveRun(deps, session) {
 /** Persist what this session drove as a replayable flow, when it declared anything provable. */
 async function saveDrivenFlow(deps, session) {
     const takeTape = deps.takeAmbientTape;
-    const flows = deps.flows;
+    const flows = deps.flowsAt?.(session.artifactRoot ?? deps.reticleRoot) ?? deps.flows;
     if (takeTape === undefined || flows === undefined)
         return;
     // One flow per journey the session contained, not one flow per session — see drive-flow.ts.
-    const { programs, outcome } = driveFlowsFrom(session.id, takeTape());
+    const { programs, outcome } = driveFlowsFrom(takeTape());
+    const author = deps.author?.();
     for (const program of programs) {
-        await flows.save(program, undefined, session.projectId);
+        // Folded into any saved copy of the same journey, so each session does not add a near-copy.
+        await flows.saveJourney(author === undefined ? program : { ...program, author }, session.projectId, DRIVE_FLOW_PREFIX);
     }
     // The funnel step that makes the SECOND run cheap.
     //
@@ -177,3 +229,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;
@@ -33,6 +33,8 @@ export interface ReticleDirPaths {
     capsules: string;
     /**.../.reticle/flake.json (per-flow flake ledger) */
     flake: string;
+    /**.../.reticle/coverage.json (app-wide coverage ledger, all six levels) */
+    coverage: string;
     /**.../.reticle/assertion-tiers.json (last-passing assertion tiers; anti-reward-hacking baseline) */
     tiers: string;
 }

package/dist/memory/project/dir/reticle-dir.js

@@ -18,6 +18,7 @@ export function reticleDirPaths(root) {
         ambient: join(root, ReticleDir.AMBIENT_FILE),
         capsules: join(root, ReticleDir.CAPSULES_SUBDIR),
         flake: join(root, ReticleDir.FLAKE_FILE),
+        coverage: join(root, ReticleDir.COVERAGE_FILE),
         tiers: join(root, ReticleDir.TIERS_FILE),
     };
 }

package/dist/memory/project/fs/fs-port.js

@@ -1,11 +1,46 @@
 import { access, appendFile, mkdir, open, readdir, readFile, realpath, rename, rm, stat, writeFile, } from 'node:fs/promises';
 /** The JSONL record terminator, as a byte — the only boundary a capped tail read can align to. */
 const NEWLINE_BYTE = 0x0a;
+/**
+ * The largest single `read(2)` this port will ask for: 2^31 - 1, the int32 ceiling.
+ *
+ * Past it `fs.read` does not throw — it ABORTS the process on a V8 assertion
+ * (`node::fs::Read ... Assertion failed: args[3]->IsInt32()`, where args[3] is the length). That is
+ * not catchable, so one oversized journal takes the daemon down and with it every session on the
+ * machine, including unrelated ones. Reported from the field exactly that way.
+ *
+ * Reachable in practice because `Buffer.allocUnsafe` happily allocates well past this, so a
+ * `size - start` over 2 GiB allocates fine and then kills node at the syscall. A `.reticle/sessions`
+ * has been observed in the multi-gigabyte range, so "no journal is ever that big" is not a bound
+ * anybody is enforcing.
+ *
+ * Clamping rather than throwing is deliberate: a caller reading a tail wants the newest records, and
+ * returning the last 2 GiB of them is a better answer than an error. The boundary realignment below
+ * already handles a window that opens mid-record, which is exactly what a clamp produces.
+ */
+const MAX_SINGLE_READ_BYTES = 2_147_483_647;
+/**
+ * Refuse an offset that cannot survive the arithmetic below.
+ *
+ * `length = size - start`, so a non-integer or negative offset produces a non-integer or negative
+ * length, and those fail in two different ways one layer apart: `Buffer.allocUnsafe` throws a
+ * RangeError for a fractional length, while an oversized one reaches `fs.read` and aborts the
+ * process. Checking here means the caller gets one predictable rejection instead of either.
+ */
+function requireByteCount(label, value) {
+    if (value === undefined)
+        return;
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new RangeError(`${label} must be a non-negative safe integer, got ${String(value)} — a fractional or negative byte count cannot reach a read syscall safely`);
+    }
+}
 /** Production adapter — the single import site of node:fs/promises in the server. */
 export function createNodeFileSystem() {
     return {
         readFile: (path) => readFile(path, 'utf8'),
         readFileFrom: async (path, byteOffset, maxBytes) => {
+            requireByteCount('byteOffset', byteOffset);
+            requireByteCount('maxBytes', maxBytes);
             const fh = await open(path, 'r');
             try {
                 const { size } = await fh.stat();
@@ -18,14 +53,18 @@ export function createNodeFileSystem() {
                 // One byte BEFORE that cut, so a cut landing exactly on a record boundary is recognised as
                 // one instead of sacrificing the record after it.
                 const start = capped ? cut - 1 : byteOffset;
-                const length = size - start;
+                // Clamped to the int32 ceiling: past it `fs.read` aborts the process rather than throwing.
+                // Keep the NEWEST bytes, matching what every caller of a tail read is asking for.
+                const want = size - start;
+                const length = Math.min(want, MAX_SINGLE_READ_BYTES);
+                const readFrom = start + (want - length);
                 const buf = Buffer.allocUnsafe(length);
-                const { bytesRead } = await fh.read(buf, 0, length, start);
+                const { bytesRead } = await fh.read(buf, 0, length, readFrom);
                 // ONLY what the read returned. `allocUnsafe` hands back whatever was last in that heap
                 // block, and `fstat` runs one syscall ahead of `read` — so a file truncated in between, or
                 // any short read, would otherwise decode that memory and hand it back as journal text.
                 const got = buf.subarray(0, bytesRead);
-                if (!capped)
+                if (!capped && readFrom === start)
                     return { text: got.toString('utf8'), size, from: start };
                 // The ceiling moved the start, so the window may open inside a record whose head was never
                 // read. Drop up to the first boundary in BYTES, before decoding: `\n` is one byte and
@@ -35,11 +74,11 @@ export function createNodeFileSystem() {
                 // No boundary in the whole window: there is no record here that can be read, and half of
                 // one is worse than none. `from` still says how far the read reached.
                 if (-1 === newline)
-                    return { text: '', size, from: start + bytesRead };
+                    return { text: '', size, from: readFrom + bytesRead };
                 return {
                     text: got.subarray(newline + 1).toString('utf8'),
                     size,
-                    from: start + newline + 1,
+                    from: readFrom + newline + 1,
                 };
             }
             finally {

package/dist/memory/project/fs/write-atomic.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Write a file so a reader never sees a half-written one, and two writers never see each other's.
+ *
+ * Write to a temporary sibling, then rename. The rename is what makes it atomic: on a POSIX
+ * filesystem it either replaces the destination entirely or does not happen, so a reader gets the
+ * old file or the new one and never a truncated middle.
+ *
+ * TWO properties, and the second is the one that was missing. Five stores in this package built
+ * this by hand and named the temp file after the DESTINATION — `${path}.tmp` — which is shared by
+ * every process writing that path. Two daemons on one repository then write the same temp file:
+ * one truncates the other mid-write and renames the remains into place, and the survivor is a file
+ * neither of them produced. Two other stores already pid-suffixed theirs, so the fix was known and
+ * had simply never been carried to the rest.
+ *
+ * Running parallel agent sessions against one checkout is the ordinary way to reach this, not an
+ * exotic one.
+ *
+ * The temp file stays BESIDE its destination rather than in the system temp directory, because a
+ * rename across devices is not atomic and `/tmp` is routinely a different device.
+ *
+ * One helper rather than five corrected copies: the sixth store gets this for free and cannot get
+ * it wrong, which is the only version of this fix that stays fixed.
+ */
+import type { FileSystemPort } from './fs-port.js';
+export declare function tempNameFor(path: string, pid?: number, seq?: number): string;
+export declare function writeFileAtomic(fs: FileSystemPort, path: string, contents: string): Promise<void>;

package/dist/memory/project/fs/write-atomic.js

@@ -0,0 +1,48 @@
+/**
+ * Unique per WRITE, not per process.
+ *
+ * The pid separates two daemons. It does not separate two concurrent writes inside ONE daemon —
+ * `Promise.all` over two store saves, or two scheduled flushes of the same ledger — and those share
+ * a pid, so a pid-only name puts them straight back on the same temp file. The first version of
+ * this helper had exactly that hole and its own concurrency test found it.
+ *
+ * A counter rather than `Math.random()`: rule 7 keeps the clock and the random source out of pure
+ * logic, and a monotonic counter is deterministic, collision-free within a process, and needs
+ * neither.
+ */
+let writeSeq = 0;
+export function tempNameFor(path, pid = process.pid, seq) {
+    writeSeq += 1;
+    return `${path}.${String(pid)}.${String(seq ?? writeSeq)}.tmp`;
+}
+/**
+ * What Windows answers, for a moment, when another writer is still replacing the destination.
+ * POSIX never refuses such a rename; Windows does, and the save has to wait it out rather than
+ * fail. Seen on Windows CI with two writers on one path.
+ */
+const TRANSIENT_RENAME = new Set(['EPERM', 'EBUSY', 'EACCES']);
+const RENAME_ATTEMPTS = 6;
+const RENAME_BACKOFF_MS = 15;
+function isTransientRename(error) {
+    const code = error?.code;
+    return 'string' === typeof code && TRANSIENT_RENAME.has(code);
+}
+export async function writeFileAtomic(fs, path, contents) {
+    const tmp = tempNameFor(path);
+    await fs.writeFile(tmp, contents);
+    for (let attempt = 1;; attempt += 1) {
+        try {
+            await fs.rename(tmp, path);
+            return;
+        }
+        catch (error) {
+            if (attempt < RENAME_ATTEMPTS && isTransientRename(error)) {
+                await new Promise((resolve) => setTimeout(resolve, RENAME_BACKOFF_MS * attempt));
+                continue;
+            }
+            // The write failed; its temp file must not outlive it.
+            await fs.rm(tmp).catch(() => undefined);
+            throw error;
+        }
+    }
+}

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

@@ -38,7 +38,9 @@ function numericDelta(before, after) {
  * "what's broken vs before" from the cloud. Absent creds / unreachable → undefined (agent stays local).
  */
 async function cloudRegression(deps, sessionId) {
-    const config = resolveCloudConfig(process.env);
+    // The same resolver every caller uses (stored key for a linked repo, else the exported one);
+    // the environment alone only for an embedder that wires no linked-credential port.
+    const config = await (deps.linkedCloud?.() ?? Promise.resolve(resolveCloudConfig(process.env)));
     if (null === config)
         return undefined;
     let projectId;

package/dist/memory/recall/prior/connection-memory.d.ts

@@ -63,3 +63,9 @@ export declare function hasAnyAppConnectedBefore(stateDir: string, port: number,
  * diagnosis, which is why it now shares this function instead of keeping a second copy of the rule.
  */
 export declare function hasProjectConnectedBefore(stateDir: string, port: number, projectId: string | undefined): boolean;
+/**
+ * Has any of these projects connected before: the first-move question for a directory that speaks
+ * for more than one app (a monorepo root), or for none by name (an app wired by the plugin alone).
+ * The ids come from `projectIdsAt`; each is still asked the narrow question.
+ */
+export declare function hasAnyProjectConnectedBefore(stateDir: string, port: number, projectIds: readonly string[]): boolean;

package/dist/memory/recall/prior/connection-memory.js

@@ -112,3 +112,11 @@ export function hasProjectConnectedBefore(stateDir, port, projectId) {
         return false;
     return hasAnyAppConnectedBefore(stateDir, port, projectId);
 }
+/**
+ * Has any of these projects connected before: the first-move question for a directory that speaks
+ * for more than one app (a monorepo root), or for none by name (an app wired by the plugin alone).
+ * The ids come from `projectIdsAt`; each is still asked the narrow question.
+ */
+export function hasAnyProjectConnectedBefore(stateDir, port, projectIds) {
+    return projectIds.some((id) => hasProjectConnectedBefore(stateDir, port, id));
+}

package/dist/memory/recall/registered-projects.d.ts

@@ -1,5 +1,5 @@
 /** One project this machine has paired before, in the shape the no-session facts already carry. */
-export interface RegisteredProject {
+interface RegisteredProject {
     directory: string;
     projectId?: string;
 }
@@ -52,3 +52,4 @@ export declare function isUnscopedRoot(directory: string, home: string): boolean
  * reporting it as such would tell a correctly-scoped daemon to go and look somewhere else.
  */
 export declare function registeredElsewhere(home: string, directory: string): RegisteredProject[];
+export {};