@reticlehq/server 3.5.0 → 3.7.0

package/dist/memory/project/sync-status.js

@@ -0,0 +1,224 @@
+/**
+ * Where this project's work stands with the Reticle platform, run by run.
+ *
+ * Read from the sync cycle's own record (`.reticle/cloud-state.json`): the content hash of every run
+ * the platform ACCEPTED, and the reason for every run it REFUSED. A run whose current content matches
+ * an accepted hash is on the platform; one whose current content was refused is refused, with the
+ * platform's own sentence; anything else is waiting for the next cycle. On a machine that is not
+ * linked, everything is local only.
+ *
+ * Nothing here talks to the network. It answers "did my work go up?" from what the machine already
+ * knows, so it can ride on every verdict without costing a request.
+ */
+import { diskSource, readCloudState } from '../cloud/sync-disk.js';
+import { hashPayload } from '../cloud/sync-hash.js';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { ReticleDir } from '@reticlehq/core';
+import { resolveProjectCloud } from '../cloud/cloud-config.js';
+import { unmatchedRoots, unsyncedRoots } from '../cloud/unsynced-roots.js';
+import { knownProjectCandidates } from './artifact-root-resolver.js';
+export const SyncStatus = {
+    ON_PLATFORM: 'on-platform',
+    PENDING: 'pending',
+    REFUSED: 'refused',
+    LOCAL_ONLY: 'local-only',
+};
+/** How many refusals a summary names before it only counts them. */
+const MAX_NAMED_REFUSALS = 3;
+export function summarizeSync(input) {
+    const { linked, runs, state } = input;
+    let onPlatform = 0;
+    let pending = 0;
+    const refused = [];
+    let latest;
+    if (linked) {
+        for (const run of runs) {
+            const hash = hashPayload(run.payload);
+            const refusal = state.refusedRuns?.[run.runId];
+            const at = createdAtOf(run.payload);
+            if (state.sentRunHashes?.[run.runId] === hash && (latest === undefined || at > latest.at))
+                latest = { runId: run.runId, at };
+            if (state.sentRunHashes?.[run.runId] === hash)
+                onPlatform += 1;
+            else if (refusal !== undefined && refusal.payloadHash === hash)
+                refused.push({ runId: run.runId, reason: refusal.reason });
+            else
+                pending += 1;
+        }
+    }
+    return {
+        linked,
+        runs: runs.length,
+        onPlatform,
+        pending,
+        refused: refused.slice(0, MAX_NAMED_REFUSALS),
+        refusedMore: Math.max(0, refused.length - MAX_NAMED_REFUSALS),
+        ...(state.lastPushAt === undefined ? {} : { lastPushAt: state.lastPushAt }),
+        ...(state.lastError === undefined || 0 === state.lastError.length
+            ? {}
+            : { lastError: state.lastError }),
+        ...(latest === undefined ? {} : { latestOnPlatform: latest.runId }),
+    };
+}
+/** A run artifact's `createdAt`, or 0 when it has none. */
+function createdAtOf(payload) {
+    const at = 'object' === typeof payload && null !== payload
+        ? payload['createdAt']
+        : undefined;
+    return 'number' === typeof at ? at : 0;
+}
+/**
+ * Where this project's dashboard lives, if `reticle link` recorded one.
+ *
+ * Read from the link file rather than derived from the API url, because the API origin and the
+ * console origin are different hosts in every deployment that is not a laptop. Synchronous and
+ * best-effort, like every other read in this file: a missing or malformed link file means no link
+ * in the HUD, never a failed tool call.
+ */
+export function readDashboardUrl(reticleRoot) {
+    return linkField(reticleRoot, 'dashboardUrl');
+}
+/** The platform project this folder is linked to, from the same link file. */
+export function readLinkedProjectId(reticleRoot) {
+    return linkField(reticleRoot, 'projectId');
+}
+function linkField(reticleRoot, field) {
+    try {
+        const raw = JSON.parse(readFileSync(join(reticleRoot, ReticleDir.CLOUD_LINK_FILE), 'utf8'));
+        if ('object' !== typeof raw || null === raw)
+            return undefined;
+        const value = raw[field];
+        return 'string' === typeof value && value.length > 0 ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** How the sync loop records a refused credential in its state. */
+const REFUSED_SYNC = /^status 40[13]\b/;
+/** What precedes the answer's body in that record: `status 401: `. */
+const REFUSED_PREFIX = /^status \d+: /;
+/** The refused credential, in words: what a person has to act on. */
+export const KEY_REFUSED = "the platform refused this project's API key: it was revoked, or its owner no longer has access to the workspace";
+/** The refusals the platform explains in its own words (its `error.code`). */
+const EXPLAINED_REFUSALS = new Set([
+    'removed_from_workspace',
+    'key_lost_access',
+]);
+/**
+ * Why a credential was refused: the platform's own sentence when it names the reason ("You were
+ * removed from Acme.", a key whose owner lost the project), else ours. Reads an answer body.
+ */
+export function refusalSaid(body) {
+    try {
+        const error = JSON.parse(body)
+            ?.error;
+        if ('string' === typeof error?.code &&
+            EXPLAINED_REFUSALS.has(error.code) &&
+            'string' === typeof error.message &&
+            0 < error.message.length)
+            return error.message;
+    }
+    catch {
+        // Not the platform's JSON: our own sentence stands.
+    }
+    return KEY_REFUSED;
+}
+/** Why the platform refused this project's key at the last sync, or undefined. Never throws. */
+export function keyRefusalAtLastSync(reticleRoot) {
+    return keyRefusalIn(readCloudState(reticleRoot).lastError);
+}
+/** The refusal a recorded sync error carries, in words, or undefined when it is another failure. */
+function keyRefusalIn(error) {
+    if ('string' !== typeof error || !REFUSED_SYNC.test(error))
+        return undefined;
+    return refusalSaid(error.replace(REFUSED_PREFIX, ''));
+}
+/** Whether the platform refused this project's key at the last sync. Never throws. */
+export function keyRefusedAtLastSync(reticleRoot) {
+    return keyRefusalAtLastSync(reticleRoot) !== undefined;
+}
+/** The dashboard's page for one run: the console's `/runs/:runId` route, at the dashboard's origin. */
+export const DASHBOARD_RUN_PATH = '/runs/';
+export const DASHBOARD_PLAN_PATH = '/plans/';
+export function dashboardRunUrl(dashboardUrl, runId) {
+    return `${dashboardOrigin(dashboardUrl)}${DASHBOARD_RUN_PATH}${encodeURIComponent(runId)}`;
+}
+function dashboardOrigin(dashboardUrl) {
+    try {
+        return new URL(dashboardUrl).origin;
+    }
+    catch {
+        return dashboardUrl.replace(/\/+$/, ''); // not a url: use it as given
+    }
+}
+/** The line a command prints once its run reached the platform. */
+export function seeRunLine(dashboardUrl, runId) {
+    return `See it in your dashboard: ${dashboardRunUrl(dashboardUrl, runId)}`;
+}
+/**
+ * A saved Harness plan's page on the dashboard, beside its runs, under its project: opened under
+ * another project's sticky scope the page answered "We could not find that plan" to its owner.
+ */
+export function dashboardPlanUrl({ dashboardUrl, planId, projectId, }) {
+    const page = `${dashboardOrigin(dashboardUrl)}${DASHBOARD_PLAN_PATH}${encodeURIComponent(planId)}`;
+    return projectId === undefined ? page : `${page}?project=${encodeURIComponent(projectId)}`;
+}
+/** This project's summary, read from its `.reticle`. Never throws: an unreadable record is empty. */
+export function readSyncSummary(reticleRoot, linked) {
+    let runs = [];
+    try {
+        runs = diskSource(reticleRoot).runs();
+    }
+    catch {
+        runs = [];
+    }
+    return summarizeSync({ linked, runs, state: readCloudState(reticleRoot) });
+}
+/** One status for the whole project: the worst thing true of it. */
+export function overallStatus(summary) {
+    if (!summary.linked)
+        return SyncStatus.LOCAL_ONLY;
+    if (0 < summary.refused.length)
+        return SyncStatus.REFUSED;
+    if (0 < summary.pending || summary.lastError !== undefined)
+        return SyncStatus.PENDING;
+    return SyncStatus.ON_PLATFORM;
+}
+/** The summary in one sentence an agent can repeat to a person. */
+export function describeSync(summary, now) {
+    if (!summary.linked)
+        return `${String(summary.runs)} run(s) exist only on this machine; nothing is synced until the project is linked (npx @reticlehq/server connect).`;
+    const ago = summary.lastPushAt === undefined
+        ? 'nothing pushed yet'
+        : `last push ${String(Math.max(0, Math.round((now - summary.lastPushAt) / 1000)))}s ago`;
+    const parts = [`${String(summary.onPlatform)} of ${String(summary.runs)} run(s) on the platform`];
+    if (0 < summary.pending)
+        parts.push(`${String(summary.pending)} waiting for the next push`);
+    const named = summary.refused.map((r) => `${r.runId}: ${r.reason}`);
+    if (0 < named.length)
+        parts.push(`refused by the platform: ${named.join('; ')}${0 < summary.refusedMore ? ` (+${String(summary.refusedMore)} more)` : ''}`);
+    const refusal = keyRefusalIn(summary.lastError);
+    if (refusal !== undefined)
+        parts.push(`the last push was refused: ${refusal}`);
+    else if (summary.lastError !== undefined)
+        parts.push(`the last push failed: ${summary.lastError}`);
+    return `${parts.join('; ')} (${ago}).`;
+}
+/**
+ * Every project folder this machine knows with runs or flows the platform never got, linked by its OWN link
+ * file or not. `reticle sync` and `doctor` print these; a daemon tracks the same through its cycle.
+ */
+export async function machineUnsyncedRoots(fs, home, env) {
+    const roots = [
+        ...knownProjectCandidates().map((c) => join(c.directory, ReticleDir.ROOT)),
+        // And what no project claimed: nothing sends it, and nothing named it after the first warning.
+        ...unmatchedRoots(home),
+    ];
+    const cloudOf = (root) => resolveProjectCloud(fs, root, home, env);
+    return unsyncedRoots(roots, async (root) => {
+        const cloud = await cloudOf(root);
+        return null !== cloud.config && null !== cloud.projectId;
+    }, async (root) => (await cloudOf(root)).policy.flows);
+}

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

@@ -17,7 +17,12 @@ import { sessionIdShape } from '../../surface/tools/tool-kit.js';
 import { asNumber, asString } from '@reticlehq/core';
 import { sessionRoot } from '../project/session-root.js';
 import { MemoryUnavailable, readProjectMemory } from './project-memory.js';
+import { MemoryAction, addMemoryStatement, fetchPlatformFlow, pushFlow, setAsideStatement, } from './platform-memory.js';
+import { flowsForSession } from '../../language/flows/flow-store-for-session.js';
+import { safeSessionTarget } from '../project/session-root.js';
 import { homedir } from 'node:os';
+const NEEDS_NAME = 'needs `name`: the flow’s name';
+const NEEDS_STATEMENT = 'needs `subject` and `statement`';
 /**
  * Enough to orient on, not enough to flood a context.
  *
@@ -30,12 +35,19 @@ const ADVICE = {
     [MemoryUnavailable.NOT_LINKED]: 'this project is not linked to a Reticle workspace, so there is no shared memory to read. Run `npx @reticlehq/server login` in the project to link it.',
     [MemoryUnavailable.DISABLED]: 'this project is linked but memory sync is turned off in .reticle/cloud.json, so nothing is being shared. Enable `sync.memory` to use it.',
     [MemoryUnavailable.UNREACHABLE]: 'the workspace could not be reached, or refused the key. Nothing is wrong with this project — try again, or check the link with `reticle status`.',
+    [MemoryUnavailable.UNVERIFIED]: 'the server answered, but the answer could not be shown to be about THIS project, so none of it is being reported. This is not an empty corpus: do NOT conclude this project knows nothing. Check the link with `reticle status`, and retry once the workspace is reachable.',
+    [MemoryUnavailable.UNREADABLE]: 'the workspace answered about THIS project, but the body was a shape this build cannot read entries out of. Retrying will not change it — this is not an empty corpus and not a link problem. Check the workspace version, and that `reticle runs memory` from the same terminal returns a `{ projectId, entries }` body.',
 };
 export const MEMORY_TOOLS = [
     {
         name: ReticleTool.MEMORY,
-        description: 'Ask what THIS PROJECT already knows — the shared memory its team has built up, written by every engineer who verified something and readable by every agent since. Use it BEFORE re-deriving how a feature is supposed to behave: a colleague may already have proved it, and a statement marked `proved` was established by a real verdict rather than written down. With { subject } it narrows to one area (a flow name, or a route like "checkout"); without, it returns across the project. Each entry carries the flow and the source file it is about, so a claim can be checked. The read is recorded as an agent consultation, which is what the dashboard\'s per-flow fetch counts are built from. Returns { subject, known, total } or { error, reason, advice } when this project is not linked to a workspace.',
+        description: 'Ask what THIS PROJECT already knows — the shared memory its team has built up, written by every engineer who verified something and readable by every agent since. Use it BEFORE re-deriving how a feature is supposed to behave: a colleague may already have proved it, and a statement marked `proved` was established by a real verdict rather than written down. With { subject } it narrows to one area (a flow name, or a route like "checkout"); without, it returns across the project. Each entry carries the flow and the source file it is about, so a claim can be checked. The read is recorded as an agent consultation, which is what the dashboard\'s per-flow fetch counts are built from. Returns { subject, known, total } or { error, reason, advice } when this project is not linked to a workspace. ' +
+            'Other actions, each answered by the platform: "flow" { name } reads one saved flow from the platform (a teammate\'s too); "add" { subject, statement } writes a statement (lands as proposed); "push-flow" { name } uploads this machine\'s saved flow, replacing the platform copy; "set-aside" { id } marks a statement stale so nobody relies on it (it is kept, not deleted).',
         inputSchema: {
+            action: z.enum(Object.values(MemoryAction)).optional(),
+            name: z.string().optional().describe('flow / push-flow: the flow name.'),
+            statement: z.string().optional().describe('add: what is true, in prose.'),
+            id: z.string().optional().describe('set-aside: the statement id.'),
             subject: z
                 .string()
                 .optional()
@@ -46,6 +58,10 @@ export const MEMORY_TOOLS = [
             ...sessionIdShape,
         },
         outputSchema: {
+            flow: z.unknown().optional(),
+            added: z.unknown().optional(),
+            pushed: z.string().optional(),
+            setAside: z.string().optional(),
             subject: z.string().nullable().optional(),
             known: z.array(z.unknown()).optional(),
             total: z.number().optional(),
@@ -63,8 +79,37 @@ export const MEMORY_TOOLS = [
              * has now been fixed three times in this codebase; routing through sessionRoot is what stops
              * a fourth.
              */
-            const root = sessionRoot(deps, asString(args['sessionId']));
+            const sid = asString(args['sessionId']);
+            const root = sessionRoot(deps, sid);
             const subject = asString(args['subject']);
+            const action = asString(args['action']) ?? MemoryAction.READ;
+            const name = asString(args['name']);
+            if (MemoryAction.SET_ASIDE === action) {
+                const id = asString(args['id']);
+                if (id === undefined || 0 === id.trim().length)
+                    return { error: `${action} needs \`id\`: the statement id from a read` };
+                return setAsideStatement(deps.fs, root, id);
+            }
+            if (MemoryAction.FLOW === action) {
+                if (name === undefined)
+                    return { error: `${action} ${NEEDS_NAME}` };
+                return fetchPlatformFlow(deps.fs, root, name);
+            }
+            if (MemoryAction.PUSH_FLOW === action) {
+                if (name === undefined)
+                    return { error: `${action} ${NEEDS_NAME}` };
+                const target = safeSessionTarget(deps, sid);
+                const saved = await flowsForSession(deps, target).flows.load(name, target.projectId);
+                if (!saved.ok)
+                    return { error: `no saved flow named "${name}" on this machine`, reason: saved.code };
+                return pushFlow(deps.fs, root, saved.value, target.projectId);
+            }
+            if (MemoryAction.ADD === action) {
+                const statement = asString(args['statement']);
+                if (subject === undefined || statement === undefined || 0 === statement.trim().length)
+                    return { error: `${action} ${NEEDS_STATEMENT}` };
+                return addMemoryStatement(deps.fs, root, { subject, statement });
+            }
             const result = await readProjectMemory(deps.fs, root, homedir(), process.env, {
                 subject,
                 limit: asNumber(args['limit']) ?? DEFAULT_LIMIT,

package/dist/memory/recall/platform-memory.d.ts

@@ -0,0 +1,34 @@
+import type { FileSystemPort } from '../project/fs/fs-port.js';
+import type { FlowFile } from '@reticlehq/core';
+/** What `reticle_memory` can be asked to do. `read` is the default and needs no `action`. */
+export declare const MemoryAction: {
+    readonly READ: "read";
+    readonly FLOW: "flow";
+    readonly ADD: "add";
+    readonly SET_ASIDE: "set-aside";
+    readonly PUSH_FLOW: "push-flow";
+};
+export type MemoryAction = (typeof MemoryAction)[keyof typeof MemoryAction];
+/** Why the platform would not set a statement aside, each from its own answer. */
+export declare const SetAsideRefused: {
+    readonly NO_SUCH_STATEMENT: "no-such-statement";
+    readonly NOT_ALLOWED: "not-allowed";
+    readonly REFUSED: "refused";
+};
+export type PlatformAnswer = Record<string, unknown>;
+/** One saved flow from the platform: a teammate's, or this project's as the platform holds it. */
+export declare function fetchPlatformFlow(fs: FileSystemPort, root: string, name: string): Promise<PlatformAnswer>;
+/** Add one statement to the project's memory. It lands as a proposal; only a passing check proves it. */
+export declare function addMemoryStatement(fs: FileSystemPort, root: string, entry: {
+    subject: string;
+    statement: string;
+    flowName?: string | undefined;
+}): Promise<PlatformAnswer>;
+/** Put this machine's saved flow on the platform now, replacing the platform's copy of that name. */
+export declare function pushFlow(fs: FileSystemPort, root: string, flow: FlowFile, projectId: string | undefined): Promise<PlatformAnswer>;
+/**
+ * Set one statement aside: the platform keeps it, marked stale, and stops offering it as known. The
+ * one change a project key may make to a statement; proving one takes a passing check, and new
+ * words on a settled one are the team's to agree.
+ */
+export declare function setAsideStatement(fs: FileSystemPort, root: string, intentId: string): Promise<PlatformAnswer>;

package/dist/memory/recall/platform-memory.js

@@ -0,0 +1,139 @@
+/**
+ * The agent's writes to the platform, and its read of one flow, beside `readProjectMemory`.
+ *
+ * Every call here is answered by the platform before the tool answers, so an agent is told whether
+ * the platform has it rather than trusting a later sync cycle to carry it. Each reads the link of the
+ * project being driven (its `.reticle`, not the daemon's) and names that project on the wire.
+ */
+import { homedir } from 'node:os';
+import { cloudFetch, syncFlowToCloud, SyncOutcome } from '../cloud/cloud-sync.js';
+import { resolveProjectCloud } from '../cloud/cloud-config.js';
+import { MemoryUnavailable } from './project-memory.js';
+/** What `reticle_memory` can be asked to do. `read` is the default and needs no `action`. */
+export const MemoryAction = {
+    READ: 'read',
+    FLOW: 'flow',
+    ADD: 'add',
+    SET_ASIDE: 'set-aside',
+    PUSH_FLOW: 'push-flow',
+};
+/** Why the platform would not set a statement aside, each from its own answer. */
+export const SetAsideRefused = {
+    NO_SUCH_STATEMENT: 'no-such-statement',
+    NOT_ALLOWED: 'not-allowed',
+    REFUSED: 'refused',
+};
+/** The status a statement set aside takes on the platform: kept, but no longer relied on. */
+const STALE = 'stale';
+const MEMORY_PATH = '/v1/memory';
+const FLOWS_PATH = '/v1/flows';
+const NOT_FOUND = 'not-found';
+const HTTP_NOT_FOUND = 404;
+const HTTP_FORBIDDEN = 403;
+const HTTP_BAD_REQUEST = 400;
+const unavailable = (reason, error) => ({ error, reason });
+const UNREACHABLE = unavailable(MemoryUnavailable.UNREACHABLE, 'the platform could not be reached, or refused this project’s key');
+/** The link, or the reason there is none. Writes honour `sync.memory` / `sync.flows` like the sync. */
+async function linked(fs, root, allowed) {
+    const cloud = await resolveProjectCloud(fs, root, homedir(), process.env);
+    const { config } = cloud;
+    if (null === config)
+        return {
+            ok: false,
+            answer: unavailable(MemoryUnavailable.NOT_LINKED, 'this project is not linked to the platform'),
+        };
+    if (!allowed(cloud))
+        return {
+            ok: false,
+            answer: unavailable(MemoryUnavailable.DISABLED, 'this kind of sync is off in .reticle/cloud.json'),
+        };
+    return { ok: true, cloud: { ...cloud, config } };
+}
+const headers = (apiKey) => ({
+    'content-type': 'application/json',
+    authorization: `Bearer ${apiKey}`,
+});
+const projectQuery = (projectId) => null === projectId ? '' : `?projectId=${encodeURIComponent(projectId)}`;
+/** One saved flow from the platform: a teammate's, or this project's as the platform holds it. */
+export async function fetchPlatformFlow(fs, root, name) {
+    const link = await linked(fs, root, (c) => c.policy.flows);
+    if (!link.ok)
+        return link.answer;
+    const { config, projectId } = link.cloud;
+    try {
+        const res = await cloudFetch(`${config.url}${FLOWS_PATH}/${encodeURIComponent(name)}${projectQuery(projectId)}`, { method: 'GET', headers: headers(config.apiKey) });
+        if (HTTP_NOT_FOUND === res.status)
+            return unavailable(NOT_FOUND, `the platform holds no flow named "${name}" for this project`);
+        if (200 !== res.status)
+            return UNREACHABLE;
+        const flow = await res.json();
+        return { flow };
+    }
+    catch {
+        return UNREACHABLE;
+    }
+}
+/** Add one statement to the project's memory. It lands as a proposal; only a passing check proves it. */
+export async function addMemoryStatement(fs, root, entry) {
+    const link = await linked(fs, root, (c) => c.policy.memory);
+    if (!link.ok)
+        return link.answer;
+    const { config, projectId } = link.cloud;
+    try {
+        const res = await cloudFetch(`${config.url}${MEMORY_PATH}`, {
+            method: 'POST',
+            headers: headers(config.apiKey),
+            body: JSON.stringify({
+                subject: entry.subject,
+                statement: entry.statement,
+                ...(entry.flowName === undefined ? {} : { flowName: entry.flowName }),
+                ...(null === projectId ? {} : { projectId }),
+            }),
+        });
+        if (res.status >= 300)
+            return UNREACHABLE;
+        const added = await res.json();
+        return { added };
+    }
+    catch {
+        return UNREACHABLE;
+    }
+}
+/** Put this machine's saved flow on the platform now, replacing the platform's copy of that name. */
+export async function pushFlow(fs, root, flow, projectId) {
+    const link = await linked(fs, root, (c) => c.policy.flows);
+    if (!link.ok)
+        return link.answer;
+    const result = await syncFlowToCloud(flow, link.cloud.config, projectId, cloudFetch);
+    return SyncOutcome.SYNCED === result.outcome ? { pushed: flow.name } : UNREACHABLE;
+}
+/**
+ * Set one statement aside: the platform keeps it, marked stale, and stops offering it as known. The
+ * one change a project key may make to a statement; proving one takes a passing check, and new
+ * words on a settled one are the team's to agree.
+ */
+export async function setAsideStatement(fs, root, intentId) {
+    const link = await linked(fs, root, (c) => c.policy.memory);
+    if (!link.ok)
+        return link.answer;
+    const { config } = link.cloud;
+    try {
+        const res = await cloudFetch(`${config.url}${MEMORY_PATH}/${encodeURIComponent(intentId)}`, {
+            method: 'PATCH',
+            headers: headers(config.apiKey),
+            body: JSON.stringify({ status: STALE }),
+        });
+        if (HTTP_NOT_FOUND === res.status)
+            return unavailable(SetAsideRefused.NO_SUCH_STATEMENT, `the platform holds no statement "${intentId}" in this project. Read reticle_memory again for the current ids.`);
+        if (HTTP_FORBIDDEN === res.status)
+            return unavailable(SetAsideRefused.NOT_ALLOWED, 'the platform refused: the teammate who made this project’s key may not change flows or memory. Ask the user to set it aside on the dashboard (Memory), and meanwhile do not rely on it.');
+        if (HTTP_BAD_REQUEST === res.status)
+            return unavailable(SetAsideRefused.REFUSED, 'the platform refused the change: with a project key a statement can only be set aside.');
+        if (res.status >= 300)
+            return UNREACHABLE;
+        return { setAside: intentId };
+    }
+    catch {
+        return UNREACHABLE;
+    }
+}

package/dist/memory/recall/project-memory.d.ts

@@ -7,6 +7,25 @@ export declare const MemoryUnavailable: {
     readonly DISABLED: "memory-sync-disabled";
     /** The server was reached and said no, or could not be reached at all. */
     readonly UNREACHABLE: "unreachable";
+    /**
+     * The server answered, and the answer could not be shown to be about THIS project: its envelope
+     * named another one, or named none at all.
+     *
+     * Its own reason rather than an empty list, because the two are opposite facts about the corpus.
+     * "This project knows nothing" is something an agent can act on; "we cannot tell whose knowledge
+     * this is" is something it must not, and an empty list reports the first while meaning the second.
+     */
+    readonly UNVERIFIED: "unverified";
+    /**
+     * The server answered about THIS project, and the body is a shape this build cannot read entries
+     * out of — no `entries` field, or one that is not a list.
+     *
+     * Apart from `UNREACHABLE` on purpose. That reason's advice is "try again, or check the link", and
+     * neither applies: the workspace WAS reached, its answer IS this project's, and the shape will be
+     * the same on the second attempt. Sending an agent to retry it costs a round trip and teaches it
+     * to distrust a link that is fine, which is what a reason is for.
+     */
+    readonly UNREADABLE: "unreadable";
 };
 export type MemoryUnavailable = (typeof MemoryUnavailable)[keyof typeof MemoryUnavailable];
 export interface KnownThing {

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

@@ -12,8 +12,13 @@
  * question the fetch counters exist to answer and could not while nothing was reading.
  */
 import { cloudFetch } from '../cloud/cloud-sync.js';
+import { callingClientName } from '../../hooks/coding-agents.js';
 import { resolveProjectCloud } from '../cloud/cloud-config.js';
-/** Named so a read from the tool surface is distinguishable from the CLI's and from replay's. */
+import { isReadableMemoryScope, MemoryReadHeader, memoryReadUrl, scopedMemoryEntries, scopeOfMemoryResponse, } from '../cloud/memory-scope.js';
+/**
+ * Named so a read from the tool surface is distinguishable from the CLI's and from replay's. The
+ * reader is the MCP client that made the call when one can be named; this only when none can.
+ */
 const MCP_AGENT_ID = 'reticle-mcp';
 /** Why a lookup returned nothing. Each one is a different thing for the agent to do next. */
 export const MemoryUnavailable = {
@@ -23,6 +28,25 @@ export const MemoryUnavailable = {
     DISABLED: 'memory-sync-disabled',
     /** The server was reached and said no, or could not be reached at all. */
     UNREACHABLE: 'unreachable',
+    /**
+     * The server answered, and the answer could not be shown to be about THIS project: its envelope
+     * named another one, or named none at all.
+     *
+     * Its own reason rather than an empty list, because the two are opposite facts about the corpus.
+     * "This project knows nothing" is something an agent can act on; "we cannot tell whose knowledge
+     * this is" is something it must not, and an empty list reports the first while meaning the second.
+     */
+    UNVERIFIED: 'unverified',
+    /**
+     * The server answered about THIS project, and the body is a shape this build cannot read entries
+     * out of — no `entries` field, or one that is not a list.
+     *
+     * Apart from `UNREACHABLE` on purpose. That reason's advice is "try again, or check the link", and
+     * neither applies: the workspace WAS reached, its answer IS this project's, and the shape will be
+     * the same on the second attempt. Sending an agent to retry it costs a round trip and teaches it
+     * to distrust a link that is fine, which is what a reason is for.
+     */
+    UNREADABLE: 'unreadable',
 };
 /** Defensive: the wire is somebody else's server, so every field is checked before it is trusted. */
 const asKnown = (raw) => {
@@ -48,25 +72,55 @@ const asKnown = (raw) => {
  * twice returns the same order — an unstable list reads as the corpus churning when it has not.
  */
 const PROVED = 'proved';
-export const rankKnown = (things) => [
-    ...things.filter((t) => PROVED === t.status),
-    ...things.filter((t) => PROVED !== t.status),
+const AGREED = 'agreed';
+/** Set aside on the dashboard or by `reticle_memory {set-aside}`: nobody stands by it any more. */
+const SET_ASIDE = 'stale';
+/** Then agreed, then what a person wrote (no flow behind it), then flow intents. */
+const RANKS = [
+    (t) => PROVED === t.status,
+    (t) => AGREED === t.status,
+    (t) => null === t.flowName,
+    () => true,
 ];
+export const rankKnown = (things) => things
+    .map((thing, at) => ({ thing, at, rank: RANKS.findIndex((fits) => fits(thing)) }))
+    .sort((a, b) => a.rank - b.rank || a.at - b.at)
+    .map((r) => r.thing);
+/**
+ * What a read can show: each statement once (a persona's intent saved on six pages pushed a
+ * person's own fact past the cap) and nothing set aside (it ranked second seconds after).
+ */
+const liveAndDistinct = (things) => {
+    const seen = new Set();
+    return rankKnown(things.filter((t) => SET_ASIDE !== t.status)).filter((t) => {
+        const key = t.statement.trim();
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+};
 export async function readProjectMemory(fs, root, home, env, opts) {
     const cloud = await resolveProjectCloud(fs, root, home, env);
     if (null === cloud.config)
         return { ok: false, reason: MemoryUnavailable.NOT_LINKED };
     if (!cloud.policy.memory)
         return { ok: false, reason: MemoryUnavailable.DISABLED };
-    const query = opts.subject === undefined ? '' : `?subject=${encodeURIComponent(opts.subject)}`;
+    // Scoped to the LINKED project, not to whatever the key happens to cover. A workspace can hold
+    // more than one repo, and a read that named no project could be answered with another one's
+    // established knowledge — indistinguishable from this project's, and acted on. See memory-scope.
+    const url = memoryReadUrl(cloud.config.url, {
+        projectId: cloud.projectId,
+        subject: opts.subject,
+    });
     try {
-        const res = await cloudFetch(`${cloud.config.url}/v1/memory${query}`, {
+        const res = await cloudFetch(url, {
             method: 'GET',
             headers: {
                 authorization: `Bearer ${cloud.config.apiKey}`,
                 // What makes this read COUNT as an agent consulting the corpus rather than a human
                 // browsing — the distinction the dashboard's "times an agent consulted it" rests on.
-                'x-reticle-agent': MCP_AGENT_ID,
+                [MemoryReadHeader.AGENT]: callingClientName() ?? MCP_AGENT_ID,
             },
         });
         if (200 !== res.status)
@@ -75,18 +129,31 @@ export async function readProjectMemory(fs, root, home, env, opts) {
         // property yields the function, and every downstream field is undefined — a silent "the project
         // knows nothing" that is indistinguishable from the honest empty case. It cost a live drive to
         // find once already.
-        const body = (await res.json());
-        const entries = body?.entries;
-        if (!Array.isArray(entries))
-            return { ok: false, reason: MemoryUnavailable.UNREACHABLE };
-        const known = entries.map(asKnown).filter((k) => k !== null);
+        const body = await res.json();
+        // The envelope first, and it decides everything. The platform names the project on the response
+        // and NOT on each entry, so an entry-level filter alone keeps a whole sibling workspace while
+        // looking like it did something — see `memory-scope.ts`. A response that names another project,
+        // or names none, is UNVERIFIED: not empty, and not this project's.
+        const entries = scopedMemoryEntries(body, cloud.projectId);
+        if (entries === undefined) {
+            return {
+                ok: false,
+                reason: isReadableMemoryScope(scopeOfMemoryResponse(body, cloud.projectId))
+                    ? MemoryUnavailable.UNREADABLE // scoped fine, but no readable `entries` — a shape we do not know
+                    : MemoryUnavailable.UNVERIFIED,
+            };
+        }
+        // The entry-level pass is redundant against the envelope check above and kept for a server that
+        // labels entries instead. `total` is counted AFTER it, so a truncated list still tells the truth
+        // about how many of THIS project's statements there were.
+        const known = liveAndDistinct(entries.map(asKnown).filter((k) => k !== null));
         return {
             ok: true,
             subject: opts.subject ?? null,
             // Capped for the agent's context, but `total` always reports the truth so the cap is never
             // silent — a truncated list that looks complete is how an agent concludes a project knows
             // less than it does.
-            known: rankKnown(known).slice(0, opts.limit),
+            known: known.slice(0, opts.limit),
             total: known.length,
         };
     }