@reticlehq/server 3.5.0 → 3.6.0

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

@@ -1,4 +1,4 @@
-import { join } from 'node:path';
+import { isAbsolute, join, relative, sep } from 'node:path';
 import { SAFE_SEGMENT_PATTERN, ReticleDir, fnv1a, projectCandidates, } from '@reticlehq/core';
 /**
  * Which `.reticle/` a session's artifacts belong in.
@@ -51,6 +51,10 @@ export function resolveArtifactRoot(query) {
         return { root: daemonRoot, reason: ArtifactRootReason.NO_MATCH };
     }
     if (matches.length > 1) {
+        const served = checkoutContaining(matches, query.servingDirectory);
+        if (served !== undefined) {
+            return { root: join(served, ReticleDir.ROOT), reason: ArtifactRootReason.MATCHED_PROJECT };
+        }
         return {
             root: daemonRoot,
             reason: ArtifactRootReason.AMBIGUOUS,
@@ -66,6 +70,24 @@ export function resolveArtifactRoot(query) {
     }
     return { root: join(directory, ReticleDir.ROOT), reason: ArtifactRootReason.MATCHED_PROJECT };
 }
+/**
+ * The checkout the serving directory sits in, or undefined when it is in none of them.
+ *
+ * Deepest wins, because a worktree can live INSIDE the primary checkout (`.claude/worktrees/x`) and
+ * then sits under both; the deeper one is the one the server actually runs in. `relative` rather
+ * than a string prefix, so `/wt/pr-77` is not read as inside `/wt/pr-7`, and on every platform.
+ */
+function checkoutContaining(matches, servingDirectory) {
+    if (servingDirectory === undefined || 0 === servingDirectory.length)
+        return undefined;
+    const inside = matches
+        .map((candidate) => candidate.directory)
+        .filter((directory) => {
+        const rel = relative(directory, servingDirectory);
+        return '' === rel || ('..' !== rel && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
+    });
+    return inside.sort((a, b) => b.length - a.length)[0];
+}
 /**
  * One entry per directory.
  *
@@ -92,11 +114,21 @@ function dedupeByDirectory(matches) {
  * is a cache of something `init` saw once. Order only decides which duplicate survives dedupe, and
  * the one confirmed a moment ago is the better survivor.
  */
-export function projectCandidatesFrom(discovery, registry) {
+export function projectCandidatesFrom(discovery, registry, devServers = []) {
     const discovered = discovery.found.flatMap((config) => config.projectId === undefined || 0 === config.projectId.length
         ? []
         : [{ projectId: config.projectId, directory: config.directory }]);
-    return [...discovered, ...projectCandidates(registry)];
+    const known = [...discovered, ...projectCandidates(registry)];
+    // A dev server's own announcement of its project id and root, ONLY for an id nothing above names.
+    // It is the one source that knows an app wired by the build plugin alone (no `.reticle.json`, never
+    // `init`-ed), whose runs otherwise went to `unmatched/`, which nothing syncs. It fills gaps and never
+    // competes: `init` at a monorepo root names the root while the dev server names the app's subfolder,
+    // and counting both refused a project that resolved fine before.
+    const named = new Set(known.map((candidate) => candidate.projectId));
+    const announced = devServers.flatMap((server) => server.projectId === undefined || 0 === server.projectId.length || named.has(server.projectId)
+        ? []
+        : [{ projectId: server.projectId, directory: server.root }]);
+    return [...known, ...announced];
 }
 /** Where evidence goes when no project could be named and the daemon is a guest in this tree. */
 export const UNMATCHED_SUBDIR = 'unmatched';
@@ -132,23 +164,70 @@ const ORIGIN_BUCKET_PREFIX = 'origin-';
  * 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.
+ *     app), and the session is asking about THAT project. Its root is the right answer, and it is
+ *     the case the old fallback was written for.
+ *   - otherwise — a guest in the tree, or a daemon in its own checkout serving a DIFFERENT project.
+ *     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.
  *
+ * ## The second case in that list used to be missing, and it is not an edge case
+ *
+ * `daemonIsProject` answers "is the daemon sitting in SOME Reticle project". The guard below read it
+ * as "this session's project", and those are different questions whenever the two ids differ. Run
+ * the daemon in repo A, then connect an app from a git worktree B of that same repo: B has its own
+ * `projectId` in its own `.reticle.json`, and discovery cannot see it — it walks out from A's
+ * `process.cwd()` and never crosses into a sibling checkout — so this function is reached with a
+ * NAMED project and the daemon's root came back anyway. B's intents, flows and runs were written
+ * into A's checkout, and the returned path said A, so nothing looked wrong.
+ *
+ * A real identity always wins. The daemon's root is only the answer when it is that identity's own
+ * root, or when no identity was named at all.
+ *
  * `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.
+ * to one safe segment — the same guard session ids and flow names already pass. `daemonProjectId`
+ * is read from the daemon's own `.reticle.json` and gets the same treatment, because equality
+ * against a guarded value is only as strong as the weaker side.
  */
 export function unmatchedRoot(query) {
-    if (query.daemonIsProject)
+    if (query.daemonIsProject && isTheDaemonsOwnProject(query.daemonProjectId, query.projectId))
         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));
 }
+/**
+ * May the daemon write this session's artifacts into its own `.reticle/`?
+ *
+ * Two ways to qualify, and the difference between them is the whole bug: belonging to the directory
+ * is not the same as owning it.
+ *
+ *   - Nobody named a project (a pre-2.0 SDK sends no projectId). There is no identity to disagree
+ *     with, and the daemon's own root is the only thing on offer.
+ *   - The named project IS the daemon's own, and the daemon can prove it — `.reticle.json` sits in
+ *     its directory and declares the same id. Both sides go through the same segment guard, because
+ *     an equality between a guarded value and an unguarded one is only as strong as the loose side.
+ *
+ * A NAMED project the daemon cannot match declines, including when it has a `.reticle/` but no
+ * readable id. Declining costs the session its home directory and buys the guarantee that one
+ * checkout never receives another's ledger; the alternative is a wrong answer that reports success.
+ *
+ * The two ids are REQUIRED parameters rather than one object, and that is load-bearing. Taking a
+ * partial object let a caller omit a field and still compile — and an omitted `projectId` reads as
+ * "nobody named a project", which answers `true` and puts the session straight back into the daemon's
+ * checkout. That is the original defect, reachable by a typo rather than by a decision.
+ */
+function isTheDaemonsOwnProject(daemonProjectId, projectId) {
+    if (projectId === undefined || 0 === projectId.length)
+        return true;
+    if (daemonProjectId === undefined || 0 === daemonProjectId.length)
+        return false;
+    return (daemonProjectId === projectId &&
+        SAFE_SEGMENT_PATTERN.test(daemonProjectId) &&
+        !daemonProjectId.includes('..'));
+}
 /** 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)

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

@@ -17,8 +17,6 @@ export interface ReticleDirPaths {
     impact: string;
     /**.../.reticle/intent.json — the LEGACY single ledger, read until the first write migrates it into .reticle/intent/ */
     intent: string;
-    /**.../.reticle/fill-values.json (what a drive types into each labelled field — git-checked) */
-    fillValues: string;
     /**.../.reticle/visual (PNG baselines + diffs) */
     visual: string;
     /**.../.reticle/runs (verification-run artifacts) */
@@ -37,6 +35,10 @@ export interface ReticleDirPaths {
     coverage: string;
     /**.../.reticle/assertion-tiers.json (last-passing assertion tiers; anti-reward-hacking baseline) */
     tiers: string;
+    /**.../.reticle/request.json (the user's latest request, relayed by the agent, classified) */
+    request: string;
+    /** .reticle/plans/ — every Harness drive plan made here, and how it went. */
+    plans: string;
 }
 export declare function reticleDirPaths(root: string): ReticleDirPaths;
 /** The verification-run artifact path for `runId`.reticle/runs/<runId>.json). */

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

@@ -10,7 +10,6 @@ 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),
@@ -20,6 +19,9 @@ export function reticleDirPaths(root) {
         flake: join(root, ReticleDir.FLAKE_FILE),
         coverage: join(root, ReticleDir.COVERAGE_FILE),
         tiers: join(root, ReticleDir.TIERS_FILE),
+        // Beside `intent/`, not in it: `intent/` is committed, and this is the user's own words.
+        request: join(root, ReticleDir.REQUEST_FILE),
+        plans: join(root, ReticleDir.PLANS_SUBDIR),
     };
 }
 /** The verification-run artifact path for `runId`.reticle/runs/<runId>.json). */

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

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { describeSync, overallStatus, readSyncSummary } from './sync-status.js';
 import { sessionRoot } from './session-root.js';
 import { projectForRoot } from './project-for-root.js';
 import { ProjectReadError, RunStatus } from '@reticlehq/core';
@@ -94,6 +95,7 @@ export const PROJECT_TOOLS = [
         description: 'Read cross-run history from .reticle/project.json — the memory of how past runs behaved. With { name } it also returns the last run for that flow plus a diff-vs-last summary (status change, regressed flag, consoleErrors/driftSteps deltas) so you can answer "did it behave like last time?". `diff` is the lightweight status/console/drift delta vs the previous run of that NAME; `runDiff` is the per-flow duration/status delta between the two most-recent full verification artifacts ("step 3: 412ms -> 987ms (+140%), +2 requests"). When logged in to Reticle, also returns `cloud`: the team\'s server-side regression report (broken/changed flows vs before) — the durable memory a fresh or context-lost agent can rely on even when local history is empty. Returns { runs, learned?, lastRun?, diff?, runDiff?, cloud? } or { error, reason, cloud? }.',
         inputSchema: {
             name: z.string().optional().describe('Filter runs by this name. Omit to return all runs.'),
+            push: z.boolean().optional().describe('Sync with the platform now, before answering.'),
             limit: countSchema
                 .optional()
                 .describe('Most-recent N runs to return. Defaults to 25 — the full history is unbounded and grows with every run (measured at ~20KB / ~5,000 tokens on a modest project), which is a large slice of an agent context for data it mostly does not read. `totalRuns` always reports the true count, so a cap is never silent.'),
@@ -110,14 +112,31 @@ export const PROJECT_TOOLS = [
             cloud: z.unknown().optional(),
         },
         handler: async (deps, args) => {
-            const cloud = await cloudRegression(deps, asString(args['sessionId']));
-            const withCloud = (obj) => cloud === undefined ? obj : { ...obj, cloud };
+            // A push asked for is done first, so the status below describes what it achieved.
+            if (true === args['push'])
+                await deps.syncNow?.().catch(() => undefined);
+            const root = sessionRoot(deps, asString(args['sessionId']));
+            const linked = (await deps.linkedCloud?.().catch(() => null)) ?? null;
+            const summary = readSyncSummary(root, null !== linked);
+            const sync = {
+                ...summary,
+                status: overallStatus(summary),
+                said: describeSync(summary, deps.now()),
+            };
+            const regression = await cloudRegression(deps, asString(args['sessionId']));
+            // Where this project's work stands with the platform rides in `cloud` beside the team's
+            // regression report: the two answers to "what does the platform know about this project".
+            const cloud = {
+                ...('object' === typeof regression && null !== regression ? regression : {}),
+                sync,
+            };
+            const withCloud = (obj) => ({ ...obj, cloud });
             const project = projectForRoot(deps, sessionRoot(deps, asString(args['sessionId'])));
             const read = await project.read();
             if (!read.ok) {
                 return withCloud({
                     error: read.reason === ProjectReadError.MISSING
-                        ? 'no .reticle/project.json yet — run a flow (reticle_flow_replay) or reticle_run_record first'
+                        ? 'no .reticle/project.json yet — the first verified run writes it: drive one step with reticle_act_and_wait and an `until`'
                         : '.reticle/project.json is malformed — it will self-heal on the next recorded run',
                     reason: read.reason,
                 });

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

@@ -1,5 +1,21 @@
 import type { ProjectId } from '@reticlehq/core';
 import type { ToolDeps } from '../../surface/tools/tool-kit.js';
+/**
+ * Which project a call is about, and the page origin it came through.
+ *
+ * The projectId alone is not an address: every git worktree carries the same committed
+ * `.reticle.json`, so a daemon serving several worktrees sees one id for all of them. The origin
+ * names the dev server that served the page, and the resolver uses it to pick the checkout that
+ * server runs in. Carried as one value so no caller can resolve with half of it -- a flow saved
+ * through the worktree and replayed through the id alone would land in one tree and be read from
+ * another.
+ */
+export interface ProjectTarget {
+    projectId: ProjectId | undefined;
+    origin?: string | undefined;
+}
+/** The target for a caller that genuinely holds no session -- the id is all there is. */
+export declare function projectOnly(projectId: ProjectId | undefined): ProjectTarget;
 /**
  * The `.reticle` directory a tool call's artifacts belong in.
  *
@@ -24,7 +40,7 @@ export declare function sessionRoot(deps: ToolDeps, sessionId: string | undefine
  * place and the id from another. `sessionRoot` is now this function plus a lookup, so the two
  * cannot disagree about what a resolved root is.
  */
-export declare function rootForProjectId(deps: ToolDeps, projectId: ProjectId | undefined): string;
+export declare function rootForTarget(deps: ToolDeps, target: ProjectTarget): string;
 /**
  * The PROJECT directory -- one level above `.reticle` -- for a caller that runs a tool in a tree
  * rather than writing a file into one. `git diff` is the case: it was being run in the daemon's
@@ -50,3 +66,10 @@ export declare function projectDirFor(deps: ToolDeps, sessionId: string | undefi
  * there is no answer either.
  */
 export declare function sessionProjectId(deps: ToolDeps, sessionId: string | undefined): ProjectId | undefined;
+/**
+ * `sessionTarget` for the paths that degrade instead of refusing: replay and learning resolve a
+ * missing session to the global store, and keep doing so -- with the origin when there is one.
+ */
+export declare function safeSessionTarget(deps: ToolDeps, sessionId: string | undefined): ProjectTarget;
+/** `sessionProjectId` plus the origin the session's page was served from. Same refusals. */
+export declare function sessionTarget(deps: ToolDeps, sessionId: string | undefined): ProjectTarget;

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

@@ -1,4 +1,23 @@
 import { dirname } from 'node:path';
+/**
+ * The scheme://host:port a session's page was served from. Local rather than the session manager's
+ * copy because `memory/project` does not reach `portal/session`, and five lines are cheaper than a
+ * new dependency between the two.
+ */
+function originOf(url) {
+    if (url === undefined)
+        return undefined;
+    try {
+        return new URL(url).origin;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The target for a caller that genuinely holds no session -- the id is all there is. */
+export function projectOnly(projectId) {
+    return { projectId };
+}
 /**
  * The `.reticle` directory a tool call's artifacts belong in.
  *
@@ -26,7 +45,7 @@ export function sessionRoot(deps, sessionId) {
     // nothing its answer could change, so that one case skips the lookup and costs what it always
     // did. Every embedder of this engine, and every older construction of ToolDeps, is on it.
     const nothingToRefuse = deps.artifactRootFor === undefined && sessionId === undefined;
-    return rootForProjectId(deps, nothingToRefuse ? undefined : sessionProjectId(deps, sessionId));
+    return rootForTarget(deps, nothingToRefuse ? projectOnly(undefined) : sessionTarget(deps, sessionId));
 }
 /**
  * The same answer for a caller that already holds the projectId rather than a sessionId.
@@ -37,8 +56,8 @@ export function sessionRoot(deps, sessionId) {
  * place and the id from another. `sessionRoot` is now this function plus a lookup, so the two
  * cannot disagree about what a resolved root is.
  */
-export function rootForProjectId(deps, projectId) {
-    return deps.artifactRootFor?.(projectId).root ?? deps.reticleRoot;
+export function rootForTarget(deps, target) {
+    return deps.artifactRootFor?.(target.projectId, target.origin).root ?? deps.reticleRoot;
 }
 /**
  * The PROJECT directory -- one level above `.reticle` -- for a caller that runs a tool in a tree
@@ -74,12 +93,29 @@ export function projectDirFor(deps, sessionId) {
  * from this file so they cannot disagree again.
  */
 export function sessionProjectId(deps, sessionId) {
+    return sessionTarget(deps, sessionId).projectId;
+}
+/**
+ * `sessionTarget` for the paths that degrade instead of refusing: replay and learning resolve a
+ * missing session to the global store, and keep doing so -- with the origin when there is one.
+ */
+export function safeSessionTarget(deps, sessionId) {
+    try {
+        return sessionTarget(deps, sessionId);
+    }
+    catch {
+        return projectOnly(undefined);
+    }
+}
+/** `sessionProjectId` plus the origin the session's page was served from. Same refusals. */
+export function sessionTarget(deps, sessionId) {
     try {
-        return deps.sessions.resolve(sessionId).projectId;
+        const session = deps.sessions.resolve(sessionId);
+        return { projectId: session.projectId, origin: originOf(session.url) };
     }
     catch (cause) {
         if (sessionId === undefined)
-            return undefined;
+            return projectOnly(undefined);
         throw unresolvedTargetRefusal(sessionId, cause);
     }
 }

package/dist/memory/project/sync-status.d.ts

@@ -0,0 +1,39 @@
+import type { CloudSyncState } from '../cloud/sync-cycle.js';
+export declare const SyncStatus: {
+    readonly ON_PLATFORM: "on-platform";
+    readonly PENDING: "pending";
+    readonly REFUSED: "refused";
+    readonly LOCAL_ONLY: "local-only";
+};
+export type SyncStatus = (typeof SyncStatus)[keyof typeof SyncStatus];
+export interface SyncSummary {
+    linked: boolean;
+    /** Runs on this machine. */
+    runs: number;
+    onPlatform: number;
+    pending: number;
+    /** The runs the platform refused in their current form, with its reason. */
+    refused: {
+        runId: string;
+        reason: string;
+    }[];
+    /** Refusals beyond the ones named. */
+    refusedMore: number;
+    lastPushAt?: number;
+    /** Why the last cycle failed, when it did. */
+    lastError?: string;
+}
+export declare function summarizeSync(input: {
+    linked: boolean;
+    runs: readonly {
+        runId: string;
+        payload: unknown;
+    }[];
+    state: CloudSyncState;
+}): SyncSummary;
+/** This project's summary, read from its `.reticle`. Never throws: an unreadable record is empty. */
+export declare function readSyncSummary(reticleRoot: string, linked: boolean): SyncSummary;
+/** One status for the whole project: the worst thing true of it. */
+export declare function overallStatus(summary: SyncSummary): SyncStatus;
+/** The summary in one sentence an agent can repeat to a person. */
+export declare function describeSync(summary: SyncSummary, now: number): string;

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

@@ -0,0 +1,90 @@
+/**
+ * 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';
+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 = [];
+    if (linked) {
+        for (const run of runs) {
+            const hash = hashPayload(run.payload);
+            const refusal = state.refusedRuns?.[run.runId];
+            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 }),
+    };
+}
+/** 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)` : ''}`);
+    if (summary.lastError !== undefined)
+        parts.push(`the last push failed: ${summary.lastError}`);
+    return `${parts.join('; ')} (${ago}).`;
+}

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

@@ -30,6 +30,8 @@ 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 memory` from the same terminal returns a `{ projectId, entries }` body.',
 };
 export const MEMORY_TOOLS = [
     {

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

@@ -13,6 +13,7 @@
  */
 import { cloudFetch } from '../cloud/cloud-sync.js';
 import { resolveProjectCloud } from '../cloud/cloud-config.js';
+import { isReadableMemoryScope, 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. */
 const MCP_AGENT_ID = 'reticle-mcp';
 /** Why a lookup returned nothing. Each one is a different thing for the agent to do next. */
@@ -23,6 +24,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) => {
@@ -58,9 +78,15 @@ export async function readProjectMemory(fs, root, home, env, opts) {
         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}`,
@@ -75,10 +101,23 @@ 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 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 = entries.map(asKnown).filter((k) => k !== null);
         return {
             ok: true,

package/dist/portal/bridge/bridge.d.ts

@@ -110,7 +110,9 @@ export declare class Bridge {
      * Register a handler for the panel's harness switch. Optional for the same reason as the above: a
      * bridge built without one ignores the request rather than refusing it.
      */
-    attachHarnessRequest(handler: (enabled: boolean) => void): void;
+    attachHarnessRequest(handler: (enabled: boolean, session: Session) => void): void;
+    /** Register a handler for the panel's Sign in. Optional, like the above: without one it is ignored. */
+    attachSigninRequest(handler: () => void): void;
     /** Register a handler to run when a session connects. Additive — every handler runs. */
     attachSessionCreate(handler: (session: Session) => void): void;
     close(): Promise<void>;