@reticlehq/server 3.4.0 → 3.6.0

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

@@ -18,6 +18,7 @@
  * guard refuses — correctly, and for the same reason it refused the tool surface reaching the other
  * way. Whoever wires the daemon owns both sides and can hand one to the other.
  */
+import { writeHarnessSwitch } from './harness-switch.js';
 /** How long a cached answer is trusted. A person who just changed it expects the panel to notice. */
 const FRESH_MS = 30 * 1_000;
 export function harnessConfigSource(load, now = () => Date.now()) {
@@ -26,23 +27,47 @@ export function harnessConfigSource(load, now = () => Date.now()) {
     // conflating them made a source with an injected clock never take its first read.
     let fetchedAt;
     let inFlight = false;
+    let queuedRefresh = false;
+    let revision = 0;
+    /** Set for a background poll, so an unchanged answer does not repaint every HUD. */
+    let quiet = false;
+    const listeners = new Set();
+    const notify = () => {
+        for (const listener of listeners)
+            listener();
+    };
     const refresh = () => {
         if (inFlight)
             return;
         inFlight = true;
+        const startedAtRevision = revision;
         void load()
             .then((cfg) => {
             // A failed read keeps the LAST good answer rather than blanking the control mid-session:
             // one dropped request is not evidence that somebody changed their mind.
-            if (cfg !== undefined)
-                cached = cfg;
-            fetchedAt = now();
+            const before = JSON.stringify(cached);
+            if (startedAtRevision === revision) {
+                if (cfg !== undefined)
+                    cached = cfg;
+                fetchedAt = now();
+            }
+            // A poll that learned nothing new repaints nothing; anything else is said at once.
+            if (!quiet || before !== JSON.stringify(cached))
+                notify();
+            quiet = false;
         })
             .catch(() => {
-            fetchedAt = now();
+            if (startedAtRevision === revision)
+                fetchedAt = now();
+            quiet = false;
+            notify();
         })
             .finally(() => {
             inFlight = false;
+            if (queuedRefresh) {
+                queuedRefresh = false;
+                refresh();
+            }
         });
     };
     // Asked at construction, not first read: the daemon pushes a snapshot the instant a session
@@ -54,5 +79,75 @@ export function harnessConfigSource(load, now = () => Date.now()) {
                 refresh();
             return cached;
         },
+        applyWrite(enabled) {
+            revision += 1;
+            if (cached !== undefined)
+                cached = { ...cached, harnessEnabled: enabled };
+            fetchedAt = now();
+            notify();
+            if (cached === undefined) {
+                if (inFlight)
+                    queuedRefresh = true;
+                else
+                    refresh();
+            }
+        },
+        recheck() {
+            notify(); // Roll back an optimistic HUD switch immediately, even if the GET is slow.
+            if (inFlight)
+                queuedRefresh = true;
+            else
+                refresh();
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        poll() {
+            if (inFlight)
+                return;
+            quiet = true;
+            refresh();
+        },
     };
 }
+/**
+ * One live config source per project root, created on first ask; `onChange` hears every update.
+ *
+ * The platform read arrives as `load`, so this cache never reaches for the harness feature that
+ * performs it: the daemon, which owns both, joins them. It sat inline in `start` and `startDaemon`.
+ */
+export function harnessConfigsByRoot(load, onChange) {
+    const sources = new Map();
+    return (root) => {
+        let source = sources.get(root);
+        if (source === undefined) {
+            source = harnessConfigSource(() => load(root));
+            if (onChange !== undefined) {
+                source.subscribe(() => onChange(root));
+                // The switch can be flipped anywhere: the console, another tab, the API. A HUD that only
+                // learned of it on its next tool call showed Harness ON over a drive that had stopped.
+                const live = source;
+                setInterval(() => live.poll(), FRESH_MS).unref();
+            }
+            sources.set(root, source);
+        }
+        return source;
+    };
+}
+/**
+ * The HUD's harness switch, written to the platform with this project's credential. Nothing is
+ * awaited: an accepted write updates the cache at once, and a refused or failed one re-reads the
+ * platform so the switch springs back to the truth rather than staying where the user left it.
+ */
+export function applyHarnessSwitch(configs, root, enabled, envFor) {
+    void envFor()
+        .then((env) => writeHarnessSwitch(env, enabled))
+        .then((saved) => {
+        if (saved)
+            configs(root).applyWrite(enabled);
+        else
+            configs(root).recheck();
+    })
+        .catch(() => configs(root).recheck());
+}

package/dist/memory/cloud/hud-notices-source.d.ts

@@ -0,0 +1,21 @@
+import { type HudNoticeEntry } from '@reticlehq/core/hud';
+/**
+ * The largest body the daemon will read or keep. The real file is a few hundred bytes; anything near
+ * this is not a notices file, and the cache on disk must not grow with whatever the network sends.
+ */
+export declare const MAX_NOTICES_BODY_BYTES: number;
+export type NoticesLoad = (url: string, etag: string | undefined) => Promise<{
+    status: number;
+    etag?: string | undefined;
+    body?: string | undefined;
+}>;
+export interface NoticesSource {
+    /** The entries this daemon knows, unfiltered. Never throws, never waits. */
+    read(): HudNoticeEntry[];
+}
+export declare function hudNoticesSource(opts: {
+    cacheFile: string;
+    now?: () => number;
+    load?: NoticesLoad;
+    url?: string;
+}): NoticesSource;

package/dist/memory/cloud/hud-notices-source.js

@@ -0,0 +1,128 @@
+/**
+ * The HUD rail's notices, as the daemon keeps them.
+ *
+ * Read synchronously (the snapshot is rebuilt many times a session), served from a disk cache that
+ * survives restarts, and revalidated in the background with the stored ETag, so an unchanged file
+ * costs a 304 and no body. A failed or garbled refresh keeps the last good copy: the rail is
+ * marketing, and nothing about it may block or break a session. See core `hud-notices.ts`.
+ */
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { ReticleEnv } from '@reticlehq/core';
+import { HUD_NOTICES_URL, NOTICES_FILE_VERSION, parseHudNotices, } from '@reticlehq/core/hud';
+/** How long a copy is trusted before it is revalidated. Notices change over days, not minutes. */
+const FRESH_MS = 6 * 60 * 60 * 1_000;
+const TIMEOUT_MS = 5_000;
+/**
+ * The largest body the daemon will read or keep. The real file is a few hundred bytes; anything near
+ * this is not a notices file, and the cache on disk must not grow with whatever the network sends.
+ */
+export const MAX_NOTICES_BODY_BYTES = 64 * 1_024;
+/** Overrides the notices URL: self-hosting, staging, tests. */
+const NOTICES_URL_ENV = 'RETICLE_HUD_NOTICES_URL';
+/**
+ * The same opt-outs telemetry honours. The notices file carries nothing about anybody, but it is a
+ * request to reticle.sh, and somebody who switched Reticle's outbound calls off asked for none.
+ */
+function outboundOff(env) {
+    const telemetry = (env[ReticleEnv.TELEMETRY] ?? '').toLowerCase();
+    const dnt = env[ReticleEnv.DO_NOT_TRACK];
+    return (['0', 'false', 'off'].includes(telemetry) ||
+        ('string' === typeof dnt && dnt !== '' && dnt !== '0'));
+}
+const defaultLoad = async (url, etag) => {
+    const res = await fetch(url, {
+        headers: etag === undefined ? {} : { 'if-none-match': etag },
+        signal: AbortSignal.timeout(TIMEOUT_MS),
+    });
+    return {
+        status: res.status,
+        etag: res.headers.get('etag') ?? undefined,
+        body: 304 === res.status ? undefined : await res.text(),
+    };
+};
+function readCache(path) {
+    try {
+        const raw = JSON.parse(readFileSync(path, 'utf8'));
+        if ('object' !== typeof raw || null === raw)
+            return undefined;
+        const record = raw;
+        const fetchedAt = record['fetchedAt'];
+        const etag = record['etag'];
+        return {
+            fetchedAt: 'number' === typeof fetchedAt ? fetchedAt : 0,
+            ...('string' === typeof etag ? { etag } : {}),
+            file: record['file'],
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+function writeCache(path, cached) {
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, JSON.stringify(cached));
+    }
+    catch {
+        /* a cache that cannot be written is a fetch next time, not an error */
+    }
+}
+export function hudNoticesSource(opts) {
+    const now = opts.now ?? (() => Date.now());
+    const load = opts.load ?? defaultLoad;
+    const url = opts.url ?? process.env[NOTICES_URL_ENV] ?? HUD_NOTICES_URL;
+    let cached = readCache(opts.cacheFile);
+    let entries = cached === undefined ? [] : parseHudNotices(cached.file);
+    let inFlight = false;
+    let askedAt;
+    const refresh = () => {
+        inFlight = true;
+        askedAt = now();
+        void load(url, cached?.etag)
+            .then((answer) => {
+            if (304 === answer.status && cached !== undefined) {
+                cached = { ...cached, fetchedAt: now() };
+                writeCache(opts.cacheFile, cached);
+                return;
+            }
+            if (200 !== answer.status || answer.body === undefined)
+                return;
+            if (MAX_NOTICES_BODY_BYTES < Buffer.byteLength(answer.body))
+                return;
+            let file;
+            try {
+                file = JSON.parse(answer.body);
+            }
+            catch {
+                return;
+            }
+            // An unreadable file keeps the last good notices rather than emptying the rail.
+            const parsed = parseHudNotices(file);
+            if (0 === parsed.length && 0 < entries.length)
+                return;
+            entries = parsed;
+            // The cache holds what VALIDATED, rebuilt from the schema's output, never the body itself:
+            // unknown fields and rejected entries in a network answer do not reach the disk.
+            cached = {
+                etag: answer.etag,
+                fetchedAt: now(),
+                file: { version: NOTICES_FILE_VERSION, notices: parsed },
+            };
+            writeCache(opts.cacheFile, cached);
+        })
+            .catch(() => undefined)
+            .finally(() => {
+            inFlight = false;
+        });
+    };
+    return {
+        read() {
+            const last = Math.max(cached?.fetchedAt ?? 0, askedAt ?? Number.NEGATIVE_INFINITY);
+            const stale = cached === undefined && askedAt === undefined ? true : FRESH_MS <= now() - last;
+            if (!inFlight && stale && !outboundOff(process.env))
+                refresh();
+            return entries;
+        },
+    };
+}

package/dist/memory/cloud/memory-scope.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Which project a shared-memory read is about, on the wire and in the response.
+ *
+ * `GET /v1/memory` used to be asked with the API key and `?subject`, and nothing else. The key covers
+ * a whole workspace, and a workspace can hold more than one repo: a `cloud.json` naming project B was
+ * read with a key that also reaches project A, so B's agent could be handed A's "established
+ * knowledge" and never know it. Two repos, one key, and the wrong one's facts arrive looking exactly
+ * like the right one's.
+ *
+ * The link file has always known the answer — `resolveProjectCloud` returns it as `projectId`, and
+ * every reader simply did not pass it on.
+ *
+ * ## Why the envelope, and not the entries
+ *
+ * Sending `projectId` is the fix, and it only works once the platform filters on it. Against a server
+ * that does not know the parameter yet, the client would go on being handed the whole workspace and
+ * would report it as this project's knowledge — the same lie, now with a parameter in the URL that
+ * makes it look handled. So the response is checked here too, and WHERE it is checked is the lesson:
+ * the platform puts the project id on the response ENVELOPE — `{ projectId, entries }` — and not on
+ * each entry. An entry-level filter therefore matched nothing, kept everything, and read as a fix
+ * while being none. `scopeOfMemoryResponse` reads the envelope and refuses the whole response when
+ * it names another project, or names none.
+ *
+ * The entry-level filter stays as a second pass. It is redundant against the platform's real shape,
+ * and it is the right answer against a server that labels entries instead — cheap to keep, and
+ * nothing here rests on it.
+ *
+ * ## Every reader, and that word is load-bearing
+ *
+ * Three callers read this endpoint: the `reticle_memory` tool, flow replay's automatic consultation,
+ * and `reticle memory` at a terminal. The first cut gave the first two an entry-level filter and the
+ * third the parameter alone, while a comment claimed all three were covered — and none of the three
+ * was, because the project id arrives on the envelope. They now share `scopedMemoryEntries`, so a
+ * fourth reader cannot get a different answer than the other three.
+ *
+ * Lives beside `cloud-sync.ts` rather than in `recall/` because that is where the other platform path
+ * constants live, and because both readers already reach this directory: a home under `recall/` would
+ * make `flows` reach a directory it never needed.
+ */
+/**
+ * The wire names, spelled once.
+ *
+ * `PROJECT_ID` is a request parameter AND a response field. They are the same word on purpose — the
+ * server echoes back what it was asked about — and one constant keeps a rename from moving only one
+ * of the two, which would silently restore the unfiltered read. `SUBJECT` is a request parameter only
+ * and is named for the same reason: it is a spelling the platform owns, not ours.
+ */
+export declare const MemoryScopeField: {
+    readonly PROJECT_ID: "projectId";
+    readonly SUBJECT: "subject";
+};
+/**
+ * What a read is asked about: the linked project, and optionally one subject within it.
+ *
+ * `projectId` takes `null` as well as `undefined`, because that is the shape `resolveProjectCloud`
+ * already answers with — "the link declared none" is one fact, and making every caller spell the
+ * conversion is how a reader starts wondering whether the two spellings mean different things.
+ */
+export interface MemoryReadScope {
+    /** The cloud project the link file names. Absent, `null` and empty all mean "no project to name". */
+    projectId: string | null | undefined;
+    subject?: string | undefined;
+}
+/**
+ * The URL for one memory read.
+ *
+ * Encoded with `encodeURIComponent` rather than `URLSearchParams`, which spells a space `+`. Both are
+ * valid in a query string and the server may accept either — but this is a URL a test asserts against
+ * and a person reads in a log, and one spelling is easier to reason about than two.
+ */
+export declare function memoryReadUrl(baseUrl: string, scope: MemoryReadScope): string;
+/**
+ * Drop the entries that state they belong to another project.
+ *
+ * The field is read defensively because the wire is somebody else's server: a number, an object or an
+ * absent key all mean "this entry does not say", and only a non-empty string that disagrees is enough
+ * to refuse one. See the note above for why silence is kept rather than dropped.
+ */
+export declare function keepOwnProject(entries: readonly unknown[], projectId: string | null | undefined): unknown[];
+/**
+ * Whether a memory response can be read as THIS project's knowledge.
+ *
+ * The platform puts the project id on the response ENVELOPE, not on each entry (see the module note).
+ * Reading it there is the only check that works against the real shape: an entry-level filter sees no
+ * project field at all and keeps everything, so a server that ignores the request parameter — or
+ * resolves the key to a different project — hands back a whole workspace under this project's
+ * heading with nothing to distinguish it.
+ */
+export declare const MemoryResponseScope: {
+    /** The envelope names the project this read asked about. Its entries may be read. */
+    readonly OWN: "own";
+    /** The envelope names a DIFFERENT project. Nothing in it belongs to this one. */
+    readonly OTHER: "other";
+    /**
+     * The envelope does not say which project it is about — an older server, or a shape we do not
+     * know. Unverifiable, which is NOT the same as empty and must not be shown as though it were.
+     */
+    readonly UNSCOPED: "unscoped";
+    /**
+     * This read named no project to begin with, so there is nothing for the envelope to contradict.
+     * The env-credential path with no `cloud.json`: CI, and a single-project setup that never linked.
+     */
+    readonly NOT_ASKED: "not-asked";
+};
+export type MemoryResponseScope = (typeof MemoryResponseScope)[keyof typeof MemoryResponseScope];
+/** The two verdicts that permit reading the entries. Named so no caller re-derives the pair. */
+export declare const isReadableMemoryScope: (scope: MemoryResponseScope) => boolean;
+/**
+ * What the envelope says about which project this response is about.
+ *
+ * A missing or non-string field is `UNSCOPED` rather than a mismatch: the wire is somebody else's
+ * server, and "this response never said" is a different fact from "this response named a rival".
+ * Both refuse; only the message a reader shows differs.
+ */
+export declare function scopeOfMemoryResponse(body: unknown, projectId: string | null | undefined): MemoryResponseScope;
+/**
+ * The entries a reader may treat as this project's, or `undefined` when the response cannot be read
+ * that way at all.
+ *
+ * `undefined` is the point of the return type. Three callers need three different sentences and none
+ * of them is a list: the tool reports `UNVERIFIED`, the CLI refuses out loud, and replay attaches
+ * nothing. "This project knows nothing" and "the server answered about something else" are different
+ * facts, and only the first is safe to act on.
+ */
+export declare function scopedMemoryEntries(body: unknown, projectId: string | null | undefined): unknown[] | undefined;
+/**
+ * The same filter, for a caller that prints the server's envelope rather than reading a list.
+ *
+ * `reticle memory` writes the response to stdout as JSON, so filtering has to preserve every other
+ * field the server sent and replace only `entries`. A body whose `entries` is not an array is handed
+ * back as it arrived: at that point the envelope has already been accepted, and guessing further is
+ * how a diagnostic command starts dropping the thing it was asked to print.
+ *
+ * It REFUSES on its own, answering `undefined` for a body it cannot show to be this project's. It
+ * used to hand the body back and leave the check to a JSDoc line telling callers to run
+ * `scopeOfMemoryResponse` first — which is the exact failure this module documents, written one
+ * function below the lesson. A reader that hands a body back cannot refuse it: the day somebody
+ * calls this first, a sibling project's knowledge goes to stdout with nothing to stop it. The
+ * `undefined` is what makes the unsafe call unexpressible rather than merely discouraged — a caller
+ * cannot print what it was not handed.
+ *
+ * The caller therefore checks for `undefined` and refuses out loud, instead of asking twice.
+ */
+export declare function scopeMemoryResponse(body: unknown, projectId: string | null | undefined): unknown;

package/dist/memory/cloud/memory-scope.js

@@ -0,0 +1,205 @@
+/**
+ * Which project a shared-memory read is about, on the wire and in the response.
+ *
+ * `GET /v1/memory` used to be asked with the API key and `?subject`, and nothing else. The key covers
+ * a whole workspace, and a workspace can hold more than one repo: a `cloud.json` naming project B was
+ * read with a key that also reaches project A, so B's agent could be handed A's "established
+ * knowledge" and never know it. Two repos, one key, and the wrong one's facts arrive looking exactly
+ * like the right one's.
+ *
+ * The link file has always known the answer — `resolveProjectCloud` returns it as `projectId`, and
+ * every reader simply did not pass it on.
+ *
+ * ## Why the envelope, and not the entries
+ *
+ * Sending `projectId` is the fix, and it only works once the platform filters on it. Against a server
+ * that does not know the parameter yet, the client would go on being handed the whole workspace and
+ * would report it as this project's knowledge — the same lie, now with a parameter in the URL that
+ * makes it look handled. So the response is checked here too, and WHERE it is checked is the lesson:
+ * the platform puts the project id on the response ENVELOPE — `{ projectId, entries }` — and not on
+ * each entry. An entry-level filter therefore matched nothing, kept everything, and read as a fix
+ * while being none. `scopeOfMemoryResponse` reads the envelope and refuses the whole response when
+ * it names another project, or names none.
+ *
+ * The entry-level filter stays as a second pass. It is redundant against the platform's real shape,
+ * and it is the right answer against a server that labels entries instead — cheap to keep, and
+ * nothing here rests on it.
+ *
+ * ## Every reader, and that word is load-bearing
+ *
+ * Three callers read this endpoint: the `reticle_memory` tool, flow replay's automatic consultation,
+ * and `reticle memory` at a terminal. The first cut gave the first two an entry-level filter and the
+ * third the parameter alone, while a comment claimed all three were covered — and none of the three
+ * was, because the project id arrives on the envelope. They now share `scopedMemoryEntries`, so a
+ * fourth reader cannot get a different answer than the other three.
+ *
+ * Lives beside `cloud-sync.ts` rather than in `recall/` because that is where the other platform path
+ * constants live, and because both readers already reach this directory: a home under `recall/` would
+ * make `flows` reach a directory it never needed.
+ */
+/**
+ * The path this module builds, spelled once, for the same reason as the names below.
+ *
+ * Here rather than in `cloud-sync.ts`'s group of `CLOUD_*_PATH` constants: that group describes the
+ * calls THAT file makes, and cloud-sync has no memory reader at all. Adding this one there would make
+ * the group a registry of every endpoint in the package rather than a description of one file's calls.
+ */
+const CLOUD_MEMORY_PATH = '/v1/memory';
+/**
+ * The wire names, spelled once.
+ *
+ * `PROJECT_ID` is a request parameter AND a response field. They are the same word on purpose — the
+ * server echoes back what it was asked about — and one constant keeps a rename from moving only one
+ * of the two, which would silently restore the unfiltered read. `SUBJECT` is a request parameter only
+ * and is named for the same reason: it is a spelling the platform owns, not ours.
+ */
+export const MemoryScopeField = {
+    PROJECT_ID: 'projectId',
+    SUBJECT: 'subject',
+};
+/**
+ * The project id to name, or `undefined` when there is none.
+ *
+ * `null`, `undefined` and `''` all say the same thing and all arrive in practice: `resolveProjectCloud`
+ * answers `null` when the link declares nothing, an absent argument is `undefined`, and a truncated
+ * config gives `''`. One helper, so the URL builder and the response filter cannot disagree about
+ * which of them counts as unscoped — a disagreement that would send `?projectId=` and come back
+ * empty, which reads as "this project knows nothing" rather than as a bug.
+ *
+ * Returns the id rather than a boolean so callers get the narrowing with it. A `boolean` predicate
+ * would leave `string | null | undefined` as-is and force a `String(...)` at the call site, which is
+ * a cast dressed up as a conversion.
+ */
+const projectToName = (projectId) => 'string' === typeof projectId && projectId.length > 0 ? projectId : undefined;
+/**
+ * The URL for one memory read.
+ *
+ * Encoded with `encodeURIComponent` rather than `URLSearchParams`, which spells a space `+`. Both are
+ * valid in a query string and the server may accept either — but this is a URL a test asserts against
+ * and a person reads in a log, and one spelling is easier to reason about than two.
+ */
+export function memoryReadUrl(baseUrl, scope) {
+    const parts = [];
+    if (scope.subject !== undefined) {
+        parts.push(`${MemoryScopeField.SUBJECT}=${encodeURIComponent(scope.subject)}`);
+    }
+    const projectId = projectToName(scope.projectId);
+    if (projectId !== undefined) {
+        parts.push(`${MemoryScopeField.PROJECT_ID}=${encodeURIComponent(projectId)}`);
+    }
+    const url = `${baseUrl}${CLOUD_MEMORY_PATH}`;
+    return 0 === parts.length ? url : `${url}?${parts.join('&')}`;
+}
+/**
+ * Drop the entries that state they belong to another project.
+ *
+ * The field is read defensively because the wire is somebody else's server: a number, an object or an
+ * absent key all mean "this entry does not say", and only a non-empty string that disagrees is enough
+ * to refuse one. See the note above for why silence is kept rather than dropped.
+ */
+export function keepOwnProject(entries, projectId) {
+    const mine = projectToName(projectId);
+    if (mine === undefined)
+        return [...entries];
+    return entries.filter((entry) => {
+        if (null === entry || 'object' !== typeof entry)
+            return true;
+        const stated = entry[MemoryScopeField.PROJECT_ID];
+        if ('string' !== typeof stated || 0 === stated.length)
+            return true;
+        return stated === mine;
+    });
+}
+/**
+ * Whether a memory response can be read as THIS project's knowledge.
+ *
+ * The platform puts the project id on the response ENVELOPE, not on each entry (see the module note).
+ * Reading it there is the only check that works against the real shape: an entry-level filter sees no
+ * project field at all and keeps everything, so a server that ignores the request parameter — or
+ * resolves the key to a different project — hands back a whole workspace under this project's
+ * heading with nothing to distinguish it.
+ */
+export const MemoryResponseScope = {
+    /** The envelope names the project this read asked about. Its entries may be read. */
+    OWN: 'own',
+    /** The envelope names a DIFFERENT project. Nothing in it belongs to this one. */
+    OTHER: 'other',
+    /**
+     * The envelope does not say which project it is about — an older server, or a shape we do not
+     * know. Unverifiable, which is NOT the same as empty and must not be shown as though it were.
+     */
+    UNSCOPED: 'unscoped',
+    /**
+     * This read named no project to begin with, so there is nothing for the envelope to contradict.
+     * The env-credential path with no `cloud.json`: CI, and a single-project setup that never linked.
+     */
+    NOT_ASKED: 'not-asked',
+};
+/** The two verdicts that permit reading the entries. Named so no caller re-derives the pair. */
+export const isReadableMemoryScope = (scope) => MemoryResponseScope.OWN === scope || MemoryResponseScope.NOT_ASKED === scope;
+/**
+ * What the envelope says about which project this response is about.
+ *
+ * A missing or non-string field is `UNSCOPED` rather than a mismatch: the wire is somebody else's
+ * server, and "this response never said" is a different fact from "this response named a rival".
+ * Both refuse; only the message a reader shows differs.
+ */
+export function scopeOfMemoryResponse(body, projectId) {
+    const mine = projectToName(projectId);
+    if (mine === undefined)
+        return MemoryResponseScope.NOT_ASKED;
+    if (null === body || 'object' !== typeof body)
+        return MemoryResponseScope.UNSCOPED;
+    const stated = body[MemoryScopeField.PROJECT_ID];
+    if ('string' !== typeof stated || 0 === stated.length)
+        return MemoryResponseScope.UNSCOPED;
+    return stated === mine ? MemoryResponseScope.OWN : MemoryResponseScope.OTHER;
+}
+/**
+ * The entries a reader may treat as this project's, or `undefined` when the response cannot be read
+ * that way at all.
+ *
+ * `undefined` is the point of the return type. Three callers need three different sentences and none
+ * of them is a list: the tool reports `UNVERIFIED`, the CLI refuses out loud, and replay attaches
+ * nothing. "This project knows nothing" and "the server answered about something else" are different
+ * facts, and only the first is safe to act on.
+ */
+export function scopedMemoryEntries(body, projectId) {
+    if (!isReadableMemoryScope(scopeOfMemoryResponse(body, projectId)))
+        return undefined;
+    if (null === body || 'object' !== typeof body)
+        return undefined;
+    const entries = body['entries'];
+    if (!Array.isArray(entries))
+        return undefined;
+    return keepOwnProject(entries, projectId);
+}
+/**
+ * The same filter, for a caller that prints the server's envelope rather than reading a list.
+ *
+ * `reticle memory` writes the response to stdout as JSON, so filtering has to preserve every other
+ * field the server sent and replace only `entries`. A body whose `entries` is not an array is handed
+ * back as it arrived: at that point the envelope has already been accepted, and guessing further is
+ * how a diagnostic command starts dropping the thing it was asked to print.
+ *
+ * It REFUSES on its own, answering `undefined` for a body it cannot show to be this project's. It
+ * used to hand the body back and leave the check to a JSDoc line telling callers to run
+ * `scopeOfMemoryResponse` first — which is the exact failure this module documents, written one
+ * function below the lesson. A reader that hands a body back cannot refuse it: the day somebody
+ * calls this first, a sibling project's knowledge goes to stdout with nothing to stop it. The
+ * `undefined` is what makes the unsafe call unexpressible rather than merely discouraged — a caller
+ * cannot print what it was not handed.
+ *
+ * The caller therefore checks for `undefined` and refuses out loud, instead of asking twice.
+ */
+export function scopeMemoryResponse(body, projectId) {
+    if (!isReadableMemoryScope(scopeOfMemoryResponse(body, projectId)))
+        return undefined;
+    if (null === body || 'object' !== typeof body)
+        return undefined;
+    const envelope = body;
+    const entries = envelope['entries'];
+    if (!Array.isArray(entries))
+        return body;
+    return { ...envelope, entries: keepOwnProject(entries, projectId) };
+}