@reticlehq/server 3.1.0 → 3.3.0

package/dist/memory/project/artifact-root-resolver.js

@@ -0,0 +1,89 @@
+/**
+ * Which `.reticle` a connected session's artifacts belong in — the IO half.
+ *
+ * `resolveArtifactRoot` and `unmatchedRoot` next door are pure on purpose; this is the file that
+ * goes to disk for them: the user-level project registry, config discovery, and the one question
+ * that decides whether the daemon may write into its own working directory at all.
+ *
+ * It lives here rather than in the daemon bootstrap because it is a subject, not wiring — and
+ * because the bootstrap is at its line cap, which is the cohesion signal that rule doing its job.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+import { PROJECT_REGISTRY_FILE, emptyProjectRegistry, parseProjectRegistry, } from '@reticlehq/core/artifacts';
+import { ReticleDir } from '@reticlehq/core';
+import { discoverProjectConfigs, hasProjectConfig, } from '../../command/cli/config/config-discovery.js';
+import { log } from '../../log.js';
+import { ArtifactRootReason, projectCandidatesFrom, resolveArtifactRoot, unmatchedRoot, } from './artifact-root.js';
+/**
+ * Is the daemon's own directory a Reticle project, or is it a guest there?
+ *
+ * Answered ONCE per resolver rather than per session: a directory does not become a project between
+ * two tabs connecting, and this is the IO half `unmatchedRoot` deliberately does not do.
+ */
+function daemonSitsInAProject(daemonRoot) {
+    try {
+        // Either mark counts. `.reticle.json` means somebody ran `init` here; an existing `.reticle/`
+        // means Reticle has been invited into this tree before, including by a version that predates
+        // the config file. A directory with neither has never agreed to hold anybody's session data.
+        return existsSync(daemonRoot) || hasProjectConfig(dirname(daemonRoot));
+    }
+    catch {
+        // Unreadable is not a licence to write. Treat it as somebody else's directory.
+        return false;
+    }
+}
+export function artifactRootResolver(daemonRoot) {
+    const daemonIsProject = daemonSitsInAProject(daemonRoot);
+    return (projectId, origin) => {
+        let registry = emptyProjectRegistry();
+        try {
+            const path = join(homedir(), ReticleDir.ROOT, PROJECT_REGISTRY_FILE);
+            registry = existsSync(path)
+                ? parseProjectRegistry(JSON.parse(readFileSync(path, 'utf8')))
+                : registry;
+        }
+        catch {
+            // A cache that cannot be read is an empty cache, never an error: the daemon still resolves
+            // through discovery, and falls back to its own root exactly as it did before this existed.
+        }
+        let discovery = { found: [], searched: [] };
+        try {
+            discovery = discoverProjectConfigs(process.cwd());
+        }
+        catch {
+            // Same reasoning: a diagnostic search that throws must not take a tool call with it.
+        }
+        const resolved = resolveArtifactRoot({
+            projectId,
+            candidates: projectCandidatesFrom(discovery, registry),
+            daemonRoot,
+        });
+        if (resolved.reason === ArtifactRootReason.MATCHED_PROJECT)
+            return resolved;
+        // Could not name the project. The old code wrote into the daemon's directory anyway and said
+        // nothing, which put `.reticle/` — journals included — into repositories nobody had
+        // instrumented. Evidence still has to live somewhere, so it goes to the user's own
+        // `~/.reticle/unmatched/<projectId>` instead, and the daemon says so rather than leaving
+        // somebody to find the files.
+        const root = unmatchedRoot({
+            daemonRoot,
+            daemonIsProject,
+            home: homedir(),
+            ...(projectId === undefined ? {} : { projectId }),
+            // Only reached when no project id survives the guard. Without it every app that never
+            // stamped one shares a single directory -- and that directory holds the durable half, so one
+            // app's learned expectations become another's.
+            ...(origin === undefined ? {} : { origin }),
+        });
+        if (root !== daemonRoot) {
+            log('artifact_root_unmatched', {
+                projectId: projectId ?? null,
+                reason: resolved.reason,
+                root,
+            });
+        }
+        return { ...resolved, root };
+    };
+}

package/dist/memory/project/artifact-root.d.ts

@@ -1,4 +1,4 @@
-import { type ProjectCandidate, type ProjectRegistry } from '@reticlehq/core';
+import { type ProjectCandidate, type ProjectId, type ProjectRegistry } from '@reticlehq/core';
 import type { ConfigDiscovery } from '../../command/cli/config/config-discovery.js';
 /**
  * Which `.reticle/` a session's artifacts belong in.
@@ -38,7 +38,7 @@ export declare const ArtifactRootReason: {
 export type ArtifactRootReason = (typeof ArtifactRootReason)[keyof typeof ArtifactRootReason];
 interface ArtifactRootQuery {
     /** The connected session's HELLO projectId, when it sent one. */
-    projectId: string | undefined;
+    projectId: ProjectId | undefined;
     /** Every project this machine knows about. Supplied, not gathered here — this stays pure. */
     candidates: readonly ProjectCandidate[];
     /** Where artifacts go when the project cannot be identified. Already a `.reticle` path. */
@@ -69,4 +69,41 @@ export declare function resolveArtifactRoot(query: ArtifactRootQuery): ArtifactR
  * the one confirmed a moment ago is the better survivor.
  */
 export declare function projectCandidatesFrom(discovery: ConfigDiscovery, registry: ProjectRegistry): ProjectCandidate[];
+/** Where evidence goes when no project could be named and the daemon is a guest in this tree. */
+export declare const UNMATCHED_SUBDIR = "unmatched";
+/**
+ * The fallback root for a session whose project could not be resolved.
+ *
+ * Falling back to the daemon's own root was unconditional and silent, and that is how Reticle came
+ * to create `.reticle/` — session journals included, carrying URLs, request and response bodies and
+ * page text — in a user's BACKEND directory. Their editor starts the daemon there; the directory
+ * was never instrumented and never agreed to hold anybody's session data. They deleted it, and the
+ * next session wrote it again.
+ *
+ * Two cases, and only one of them was ever the intended behaviour:
+ *
+ *   - the daemon is sitting IN a Reticle project (a developer who ran `reticle serve` in their own
+ *     app). Its root is the right answer, and it is the case the old fallback was written for.
+ *   - the daemon is a guest — no `.reticle.json`, no `.reticle/` already there. Then the evidence
+ *     goes to the user's own `~/.reticle/unmatched/<projectId>`, which is Reticle's to write.
+ *
+ * It is never dropped. A verdict with nowhere to live is a worse failure than one in an unexpected
+ * place, and the caller says out loud where it went.
+ *
+ * `projectId` arrives in HELLO from the page, so it is untrusted input on a path join and is held
+ * to one safe segment — the same guard session ids and flow names already pass.
+ */
+export declare function unmatchedRoot(query: {
+    daemonRoot: string;
+    /** Whether the daemon's own directory is a Reticle project — an IO question, answered by the caller. */
+    daemonIsProject: boolean;
+    /** The user's home directory. Passed in rather than read, so this stays pure. */
+    home: string;
+    projectId?: ProjectId | undefined;
+    /**
+     * Where the session was served from, when it is known. Used ONLY when no project id survives the
+     * segment guard — a real id always wins, because it is an identity and this is a stand-in.
+     */
+    origin?: string | undefined;
+}): string;
 export {};

package/dist/memory/project/artifact-root.js

@@ -1,5 +1,5 @@
 import { join } from 'node:path';
-import { ReticleDir, projectCandidates, } from '@reticlehq/core';
+import { SAFE_SEGMENT_PATTERN, ReticleDir, fnv1a, projectCandidates, } from '@reticlehq/core';
 /**
  * Which `.reticle/` a session's artifacts belong in.
  *
@@ -98,3 +98,60 @@ export function projectCandidatesFrom(discovery, registry) {
         : [{ projectId: config.projectId, directory: config.directory }]);
     return [...discovered, ...projectCandidates(registry)];
 }
+/** Where evidence goes when no project could be named and the daemon is a guest in this tree. */
+export const UNMATCHED_SUBDIR = 'unmatched';
+/** What a project with NO identity at all is called on disk. Never blank, so the path is always real. */
+const UNNAMED_PROJECT = 'unnamed';
+/**
+ * The bucket for a project that could not name itself but was served from somewhere.
+ *
+ * `unnamed` used to take every one of these, which made it not a project's directory but the union
+ * of every project that ever failed to identify itself — sharing one `project.json`, one
+ * `envelopes.json`, one `flake.json` and one `assertion-tiers.json`. Those are the durable half:
+ * learned routes, per-route expectations, a quarantine ledger and an anti-downgrade floor. One
+ * app's floor silently becoming another app's floor is a wrong answer, not untidy disk.
+ *
+ * And it is the ORDINARY path, not an edge: a page that never stamped an id is an app instrumented
+ * without a build plugin, a page loaded before the plugin ran, or any tree where the daemon is a
+ * guest.
+ *
+ * The origin is the next-best identity available at that moment. It does not pretend to be a
+ * project id — two apps served on one port at different times still share a bucket — but that is a
+ * far smaller wrong than every unidentified app in the world sharing one.
+ */
+const ORIGIN_BUCKET_PREFIX = 'origin-';
+/**
+ * The fallback root for a session whose project could not be resolved.
+ *
+ * Falling back to the daemon's own root was unconditional and silent, and that is how Reticle came
+ * to create `.reticle/` — session journals included, carrying URLs, request and response bodies and
+ * page text — in a user's BACKEND directory. Their editor starts the daemon there; the directory
+ * was never instrumented and never agreed to hold anybody's session data. They deleted it, and the
+ * next session wrote it again.
+ *
+ * Two cases, and only one of them was ever the intended behaviour:
+ *
+ *   - the daemon is sitting IN a Reticle project (a developer who ran `reticle serve` in their own
+ *     app). Its root is the right answer, and it is the case the old fallback was written for.
+ *   - the daemon is a guest — no `.reticle.json`, no `.reticle/` already there. Then the evidence
+ *     goes to the user's own `~/.reticle/unmatched/<projectId>`, which is Reticle's to write.
+ *
+ * It is never dropped. A verdict with nowhere to live is a worse failure than one in an unexpected
+ * place, and the caller says out loud where it went.
+ *
+ * `projectId` arrives in HELLO from the page, so it is untrusted input on a path join and is held
+ * to one safe segment — the same guard session ids and flow names already pass.
+ */
+export function unmatchedRoot(query) {
+    if (query.daemonIsProject)
+        return query.daemonRoot;
+    const id = query.projectId ?? '';
+    const named = SAFE_SEGMENT_PATTERN.test(id) && !id.includes('..');
+    return join(query.home, ReticleDir.ROOT, UNMATCHED_SUBDIR, named ? id : unnamedSegment(query.origin));
+}
+/** Hashed, not spelled: an origin carries a host and a port, and neither belongs in a path segment. */
+function unnamedSegment(origin) {
+    if (origin === undefined || 0 === origin.trim().length)
+        return UNNAMED_PROJECT;
+    return `${ORIGIN_BUCKET_PREFIX}${fnv1a(origin.trim())}`;
+}

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/fill-value-store.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The values a drive types into this project's fields, kept so they are paid for once.
+ *
+ * A generated field value is not a model's opinion to be re-asked every run. It is a FIXTURE: the
+ * same label on the same app wants the same value tomorrow, a replay must send exactly what the
+ * recording sent or it is not a replay, and a human who dislikes "Acme Corp" should be able to open
+ * a file and write something else rather than argue with a model about it. So it lives beside the
+ * flows it belongs to, in git, in the project's own directory.
+ *
+ * Read once at the start of a drive and written once at the end: a drive that fills twenty fields
+ * must not write the file twenty times, and nothing else in the process is competing for it.
+ *
+ * Every failure is silent and answers "no values". A drive must never fail over a fixtures file,
+ * and the fallback -- the label heuristic -- is what every drive used before this existed.
+ */
+import type { FileSystemPort } from '../fs/fs-port.js';
+/** What a drive holds while it runs: a read-through map plus whatever it learned. */
+export interface FillValueStore {
+    get(label: string): string | undefined;
+    set(label: string, value: string): void;
+    /** Persist, if anything was learned. Silent on failure, like every read here. */
+    flush(): Promise<void>;
+}
+/**
+ * A store that remembers within one drive and writes nothing.
+ *
+ * Used when there is no project directory to write to. A drive must never fail over its fixtures
+ * file, and that includes failing to FIND one: the values still de-duplicate inside the run, they
+ * are simply not carried into the next one.
+ */
+export declare function memoryFillValues(): FillValueStore;
+export declare function openFillValues(fs: FileSystemPort, root: string | undefined): Promise<FillValueStore>;

package/dist/memory/project/dir/fill-value-store.js

@@ -0,0 +1,88 @@
+/**
+ * The values a drive types into this project's fields, kept so they are paid for once.
+ *
+ * A generated field value is not a model's opinion to be re-asked every run. It is a FIXTURE: the
+ * same label on the same app wants the same value tomorrow, a replay must send exactly what the
+ * recording sent or it is not a replay, and a human who dislikes "Acme Corp" should be able to open
+ * a file and write something else rather than argue with a model about it. So it lives beside the
+ * flows it belongs to, in git, in the project's own directory.
+ *
+ * Read once at the start of a drive and written once at the end: a drive that fills twenty fields
+ * must not write the file twenty times, and nothing else in the process is competing for it.
+ *
+ * Every failure is silent and answers "no values". A drive must never fail over a fixtures file,
+ * and the fallback -- the label heuristic -- is what every drive used before this existed.
+ */
+import { ReticleDir } from '@reticlehq/core';
+import { join } from 'node:path';
+/** Stamped so a later format change can tell an old file from a broken one. */
+const VERSION = 1;
+/** A label is a UI string and can be anything; a value that is not a string is not usable. */
+function parse(text) {
+    try {
+        const raw = JSON.parse(text);
+        if ('object' !== typeof raw || null === raw)
+            return {};
+        const values = raw.values;
+        if ('object' !== typeof values || null === values)
+            return {};
+        const out = {};
+        for (const [label, value] of Object.entries(values))
+            if ('string' === typeof value && 0 < value.length)
+                out[label] = value;
+        return out;
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * A store that remembers within one drive and writes nothing.
+ *
+ * Used when there is no project directory to write to. A drive must never fail over its fixtures
+ * file, and that includes failing to FIND one: the values still de-duplicate inside the run, they
+ * are simply not carried into the next one.
+ */
+export function memoryFillValues() {
+    const values = new Map();
+    return {
+        get: (label) => values.get(label),
+        set: (label, value) => void values.set(label, value),
+        flush: () => Promise.resolve(),
+    };
+}
+export async function openFillValues(fs, root) {
+    if (root === undefined || 0 === root.length)
+        return memoryFillValues();
+    const path = join(root, ReticleDir.FILL_VALUES_FILE);
+    let values = {};
+    try {
+        if (await fs.exists(path))
+            values = parse(await fs.readFile(path));
+    }
+    catch {
+        /* an unreadable fixtures file is the same as an absent one */
+    }
+    let learned = false;
+    return {
+        get: (label) => values[label],
+        set: (label, value) => {
+            if (values[label] === value)
+                return;
+            values[label] = value;
+            learned = true;
+        },
+        async flush() {
+            if (!learned)
+                return;
+            try {
+                await fs.mkdir(root);
+                const file = { version: VERSION, values };
+                await fs.writeFile(path, `${JSON.stringify(file, null, 2)}\n`);
+            }
+            catch {
+                /* the drive already happened; losing the cache costs a regeneration, not a result */
+            }
+        },
+    };
+}

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

@@ -1,4 +1,4 @@
-import { type FlowName, type SessionId } from '@reticlehq/core';
+import { type ProjectId, type FlowName, type SessionId } from '@reticlehq/core';
 import { ContractReadError, type CapabilitiesContract, type RunId } from '@reticlehq/core';
 import type { FileSystemPort } from '../fs/fs-port.js';
 /** Resolved absolute paths inside a `.reticle/` root. Pure: join only, no IO, no cwd. */
@@ -15,8 +15,10 @@ 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;
     /**.../.reticle/visual (PNG baselines + diffs) */
     visual: string;
     /**.../.reticle/runs (verification-run artifacts) */
@@ -43,6 +45,14 @@ export declare function sessionDirPath(root: string, sessionId: SessionId): stri
 export declare function journalEventsPath(root: string, sessionId: SessionId): string;
 /** The append-only action ledger path for a session (.reticle/sessions/<id>/actions.jsonl). */
 export declare function journalActionsPath(root: string, sessionId: SessionId): string;
+/**
+ * The event ledger's closure report for a session (.reticle/sessions/<id>/events.closed.json).
+ *
+ * A sidecar rather than a header inside `events.jsonl`, because the ledger is append-only and
+ * readers track a byte offset into it: a header would have to be rewritten in place, which shrinks
+ * or shifts the file and silently invalidates every cursor pointing at it.
+ */
+export declare function journalClosedPath(root: string, sessionId: SessionId): string;
 /**
  * A sessionId must be a single safe path segment before it is joined into a disk path (rejects
  * '../', slashes, absolute, dotfiles). Session labels are user/tab-supplied, so this guard runs
@@ -82,9 +92,9 @@ export declare function visualDiffPath(root: string, name: string, runtime?: str
  * apps' flows of the same name; without one it's the flat legacy path (`.reticle/flows/<name>.json`),
  * which is also where pre-existing (untagged) flows stay. Callers pass ONLY a validated projectId.
  */
-export declare function flowPath(root: string, name: FlowName, projectId?: string): string;
+export declare function flowPath(root: string, name: FlowName, projectId?: ProjectId): string;
 /** The directory a flow write targets: the per-project subdir, or the flat flows root for global. */
-export declare function flowDir(root: string, projectId?: string): string;
+export declare function flowDir(root: string, projectId?: ProjectId): string;
 /**
  * The directory that must exist before a flow of this name can be written.
  *
@@ -96,7 +106,7 @@ export declare function flowDir(root: string, projectId?: string): string;
  * Derived from the resolved path rather than by splitting the name, so it cannot disagree with
  * `flowPath` about where the file actually goes.
  */
-export declare function flowParentDir(root: string, name: FlowName, projectId?: string): string;
+export declare function flowParentDir(root: string, name: FlowName, projectId?: ProjectId): string;
 /**
  * A flow name may be NAMESPACED — `onboarding/signup` — and still never escapes `.reticle/`.
  *

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

@@ -10,6 +10,7 @@ export function reticleDirPaths(root) {
         project: join(root, ReticleDir.PROJECT_FILE),
         impact: join(root, ReticleDir.IMPACT_FILE),
         intent: join(root, ReticleDir.INTENT_FILE),
+        fillValues: join(root, ReticleDir.FILL_VALUES_FILE),
         visual: join(root, ReticleDir.VISUAL_SUBDIR),
         runs: join(root, ReticleDir.RUNS_SUBDIR),
         sessions: join(root, ReticleDir.SESSIONS_SUBDIR),
@@ -36,6 +37,16 @@ export function journalEventsPath(root, sessionId) {
 export function journalActionsPath(root, sessionId) {
     return join(sessionDirPath(root, sessionId), ReticleDir.JOURNAL_ACTIONS_FILE);
 }
+/**
+ * The event ledger's closure report for a session (.reticle/sessions/<id>/events.closed.json).
+ *
+ * A sidecar rather than a header inside `events.jsonl`, because the ledger is append-only and
+ * readers track a byte offset into it: a header would have to be rewritten in place, which shrinks
+ * or shifts the file and silently invalidates every cursor pointing at it.
+ */
+export function journalClosedPath(root, sessionId) {
+    return join(sessionDirPath(root, sessionId), ReticleDir.JOURNAL_EVENTS_CLOSED_FILE);
+}
 /**
  * A sessionId must be a single safe path segment before it is joined into a disk path (rejects
  * '../', slashes, absolute, dotfiles). Session labels are user/tab-supplied, so this guard runs

package/dist/memory/project/fs/fs-port.d.ts

@@ -12,10 +12,31 @@ export interface FileSystemPort {
      * that lands on a `\n` boundary (the journal's line terminator, 1 ASCII byte) so the returned tail
      * starts on a valid UTF-8 char boundary. Optional — a FileSystemPort that omits it makes readers fall
      * back to a whole-file read.
+     *
+     * `maxBytes` caps what ONE call materialises as a single string. It is not a performance knob: V8
+     * cannot build a string longer than 0x1fffffe8 characters, and `Buffer.prototype.toString` THROWS
+     * past that rather than returning a shorter one — so a tail bigger than the ceiling is not a slow
+     * read, it is a failed one. When the cap bites, the NEWEST bytes are kept (a journal tail is read
+     * to answer about what just happened).
+     *
+     * Two guarantees make the returned text safe to account for in bytes, and an implementation owes
+     * both:
+     *
+     *   - `from` is where the text ACTUALLY starts. It equals `byteOffset` when nothing was skipped,
+     *     and a caller can compare the two to see that a cap bit. (Omitted by a port that does not
+     *     implement the cap — read that as `byteOffset`, since such a port never skips.)
+     *   - When the cap moves the start, `from` lands just past a `\n`, so the text begins at a record
+     *     boundary and never with the replacement char of a character the window cut in half. A
+     *     window holding no `\n` at all returns empty text with `from` at the end of what was read.
+     *
+     * `size` is the file's length as `fstat` reported it, which is NOT where the returned text ends:
+     * a truncation between the stat and the read, or any short read, returns less. Advance a cursor
+     * by what arrived, never by `size`.
      */
-    readFileFrom?(path: string, byteOffset: number): Promise<{
+    readFileFrom?(path: string, byteOffset: number, maxBytes?: number): Promise<{
         text: string;
         size: number;
+        from?: number;
     }>;
     writeFile(path: string, data: string): Promise<void>;
     /** Append UTF-8 text, creating the file if absent — for the append-only JSONL journal. */

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

@@ -1,18 +1,85 @@
 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) => {
+        readFileFrom: async (path, byteOffset, maxBytes) => {
+            requireByteCount('byteOffset', byteOffset);
+            requireByteCount('maxBytes', maxBytes);
             const fh = await open(path, 'r');
             try {
                 const { size } = await fh.stat();
                 if (byteOffset >= size)
-                    return { text: '', size };
-                const length = size - byteOffset;
+                    return { text: '', size, from: byteOffset };
+                // Keep the newest bytes when the tail is over the caller's ceiling. Clamped into the file
+                // rather than trusted: a ceiling of zero would otherwise size a negative buffer.
+                const cut = maxBytes === undefined ? byteOffset : Math.max(byteOffset, size - Math.max(maxBytes, 0));
+                const capped = cut > byteOffset;
+                // 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;
+                // 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);
-                await fh.read(buf, 0, length, byteOffset);
-                return { text: buf.toString('utf8'), size };
+                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 && 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
+                // cannot occur inside a multi-byte sequence, so everything past it is intact UTF-8 and a
+                // whole number of records.
+                const newline = got.indexOf(NEWLINE_BYTE);
+                // 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: readFrom + bytesRead };
+                return {
+                    text: got.subarray(newline + 1).toString('utf8'),
+                    size,
+                    from: readFrom + newline + 1,
+                };
             }
             finally {
                 await fh.close();

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/learned-routes.d.ts

@@ -1,6 +1,11 @@
 import { type ReticleEvent } from '@reticlehq/core';
 interface RouteLearningSession {
     url: string;
+    /**
+     * The `.reticle` this session's artifacts belong in, stamped on session-create. Undefined only
+     * for a caller that does not stamp one, which resolves to the daemon's own root.
+     */
+    artifactRoot?: string | undefined;
     onEvent(handler: (event: ReticleEvent) => void): () => void;
 }
 interface RouteLearningBridge {
@@ -19,6 +24,15 @@ export declare function routeFromEvent(event: ReticleEvent): string | undefined;
 /** Read the same route shape from a session's absolute URL. */
 export declare function routeFromUrl(value: string): string | undefined;
 export declare function routesFromEvents(events: readonly ReticleEvent[]): string[];
-/** Persist initial and subsequent routes for existing and future browser sessions. */
-export declare function attachRouteLearning(bridge: RouteLearningBridge, project: RouteLearningStore): void;
+/**
+ * Persist initial and subsequent routes for existing and future browser sessions.
+ *
+ * `storeFor` resolves the store for ONE session's artifact root, rather than the daemon being handed
+ * a single store bound to its own `process.cwd()`. That binding was right only when the daemon
+ * happened to be started inside the app it was driving — and a user-scoped MCP registration, the
+ * common case, starts it wherever the editor's cwd is. The routes of every app then landed in that
+ * directory, which is how a `.reticle/` kept reappearing in a backend nobody had instrumented,
+ * while the driven project's own memory never filled.
+ */
+export declare function attachRouteLearning(bridge: RouteLearningBridge, storeFor: (root: string | undefined) => RouteLearningStore): void;
 export {};