@reticlehq/server 3.1.0 → 3.2.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/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. */
@@ -17,6 +17,8 @@ export interface ReticleDirPaths {
     impact: string;
     /**.../.reticle/intent.json (what changes were supposed to make true — git-checked) */
     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,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;
 /** 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) => {
             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;
+                const length = size - start;
                 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, start);
+                // 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)
+                    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: start + bytesRead };
+                return {
+                    text: got.subarray(newline + 1).toString('utf8'),
+                    size,
+                    from: start + newline + 1,
+                };
             }
             finally {
                 await fh.close();

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 {};

package/dist/memory/project/learned-routes.js

@@ -26,20 +26,35 @@ export function routesFromEvents(events) {
         return route === undefined ? [] : [route];
     });
 }
-/** Persist initial and subsequent routes for existing and future browser sessions. */
-export function attachRouteLearning(bridge, project) {
+/**
+ * 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 function attachRouteLearning(bridge, storeFor) {
     const attached = new WeakSet();
-    const pending = new Set();
+    // Keyed by STORE rather than by root path: `storeFor` already answers one store per root, so this
+    // cannot disagree with it about which roots are distinct.
+    const pending = new Map();
     let flushTimer;
     const flush = () => {
         flushTimer = undefined;
-        const routes = [...pending];
+        const batches = [...pending];
         pending.clear();
-        if (routes.length > 0)
-            void project.recordRoutes(routes).catch(() => undefined);
+        for (const [store, routes] of batches) {
+            if (routes.size > 0)
+                void store.recordRoutes([...routes]).catch(() => undefined);
+        }
     };
-    const queue = (route) => {
-        pending.add(route);
+    const queue = (store, route) => {
+        const routes = pending.get(store) ?? new Set();
+        routes.add(route);
+        pending.set(store, routes);
         if (flushTimer !== undefined)
             clearTimeout(flushTimer);
         flushTimer = setTimeout(flush, ROUTE_PERSIST_DEBOUNCE_MS);
@@ -48,13 +63,14 @@ export function attachRouteLearning(bridge, project) {
         if (attached.has(session))
             return;
         attached.add(session);
+        const store = storeFor(session.artifactRoot);
         const initial = routeFromUrl(session.url);
         if (initial !== undefined)
-            queue(initial);
+            queue(store, initial);
         session.onEvent((event) => {
             const route = routeFromEvent(event);
             if (route !== undefined)
-                queue(route);
+                queue(store, route);
         });
     };
     for (const session of bridge.sessions.all())

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

@@ -0,0 +1,30 @@
+/**
+ * The project memory store for ONE artifact root.
+ *
+ * `deps.project` is bound to the daemon's own root at construction, which is right only when the
+ * daemon happens to have been started inside the app it is driving — and a user-scoped MCP
+ * registration, the common case, starts it wherever the editor's cwd is. So every run record, every
+ * learned route and every observability high-water mark was written into that directory: a
+ * `.reticle/` appearing in a backend nobody instrumented, and a driven project whose own memory
+ * stayed empty. The cloud half of `recordReplayRun` had already been moved onto the session's root
+ * and its local half left behind, which is how a replay outcome could reach the dashboard and not
+ * the project it belonged to.
+ *
+ * Reads and writes both go through here, deliberately: a write that resolves to the app while a
+ * read still answers from the daemon's directory is worse than either alone — the record lands and
+ * is then invisible to the tool that exists to report it.
+ *
+ * Rebinding is cheap (a filesystem port, a root and a clock) and the single-project case allocates
+ * nothing: when the resolved root IS the daemon's, `deps.project` comes back unchanged.
+ */
+import { ProjectStore } from './project-store.js';
+import type { FileSystemPort } from './fs/fs-port.js';
+import type { ToolDeps } from '../../surface/tools/tool-kit.js';
+export declare function projectForRoot(deps: ToolDeps, root: string): ProjectStore;
+/**
+ * The same question asked by the daemon rather than by a tool: one store per artifact root, so a
+ * session's learned routes land in the app that was driven and not in whatever directory the daemon
+ * was launched from. The daemon's own store is seeded in, so the single-project case allocates
+ * nothing and keeps the instance every other caller already holds.
+ */
+export declare function projectStoreResolver(fs: FileSystemPort, daemonStore: ProjectStore, daemonRoot: string, now: () => number): (root: string | undefined) => ProjectStore;