@reticlehq/server 3.7.0 → 3.8.1

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

@@ -24,19 +24,26 @@ import { PROJECT_REGISTRY_FILE, emptyProjectRegistry, parseProjectRegistry, } fr
 import { DevServerEntrySchema, ReticleDir, ReticleEnv, devServerRegistryPort, } from '@reticlehq/core';
 import { discoverProjectConfigs, hasProjectConfig, } from '../../command/cli/config/config-discovery.js';
 import { log } from '../../log.js';
-import { ArtifactRootReason, projectCandidatesFrom, resolveArtifactRoot, unmatchedRoot, } from './artifact-root.js';
+import { isUnmatchedRoot } from './dir/reticle-dir.js';
+import { checkoutAt, hasLinkedWorktrees } from '../../command/cli/config/checkout.js';
+import { ArtifactRootReason, projectCandidatesFrom, rebaseIntoCheckout, resolveArtifactRoot, unmatchedRoot, } from './artifact-root.js';
 /**
- * Is the daemon's own directory a Reticle project, or is it a guest there?
+ * May the daemon write into this `.reticle` root? This is the one answer for every writer.
  *
- * Answered ONCE per resolver rather than per session: a directory does not become a project between
- * two tabs connecting, and this is the IO half `unmatchedRoot` deliberately does not do.
+ * The resolver asks it ONCE for the daemon's own root: a directory does not become a project
+ * between two tabs connecting, and this is the IO half `unmatchedRoot` deliberately does not do.
+ * A writer that holds a root for the daemon's life (the impact ledger) asks it on each write, so
+ * that it starts to write into the project when `init` wires it.
  */
-function daemonSitsInAProject(daemonRoot) {
+export function mayWriteIntoRoot(reticleRoot) {
     try {
         // Either mark counts. `.reticle.json` means somebody ran `init` here; an existing `.reticle/`
         // means Reticle has been invited into this tree before, including by a version that predates
         // the config file. A directory with neither has never agreed to hold anybody's session data.
-        return existsSync(daemonRoot) || hasProjectConfig(dirname(daemonRoot));
+        // An unmatched bucket is in the user's own `~/.reticle`, which is Reticle's to write.
+        return (existsSync(reticleRoot) ||
+            hasProjectConfig(dirname(reticleRoot)) ||
+            isUnmatchedRoot(reticleRoot));
     }
     catch {
         // Unreadable is not a licence to write. Treat it as somebody else's directory.
@@ -46,7 +53,7 @@ function daemonSitsInAProject(daemonRoot) {
 /**
  * The project a candidate list says lives at the daemon's own directory.
  *
- * Not the same question as `daemonSitsInAProject`: that one asks whether the tree invited Reticle in
+ * Not the same question as `mayWriteIntoRoot`: that one asks whether the tree invited Reticle in
  * at all (either mark counts, including a bare `.reticle/` from a version that predates the config
  * file), and this one asks WHICH project it is. The difference is the whole of #1244 — a daemon in
  * repo A serving an app from a git worktree B belongs to A and is being asked about B.
@@ -115,12 +122,14 @@ function announcedDevServers() {
     const servers = [];
     try {
         for (const name of readdirSync(dir)) {
-            if (null === devServerRegistryPort(name))
+            if (null === devServerRegistryPort(name)) {
                 continue;
+            }
             try {
                 const parsed = DevServerEntrySchema.safeParse(JSON.parse(readFileSync(join(dir, name), 'utf8')));
-                if (parsed.success)
+                if (parsed.success) {
                     servers.push({ projectId: parsed.data.projectId, root: parsed.data.root });
+                }
             }
             catch {
                 /* one bad announcement does not hide the others */
@@ -142,8 +151,9 @@ function announcedDevServers() {
  * own project id.
  */
 export function projectDirectoryFor(projectId) {
-    if (projectId === undefined)
+    if (projectId === undefined) {
         return undefined;
+    }
     const directories = new Set(knownProjectCandidates()
         .filter((candidate) => candidate.projectId === projectId)
         .map((candidate) => candidate.directory));
@@ -153,7 +163,7 @@ export function projectDirectoryFor(projectId) {
 }
 export function artifactRootResolver(daemonRoot, deps) {
     const candidates = deps.candidates ?? knownProjectCandidates;
-    const sitsInAProject = deps.daemonIsProject ?? daemonSitsInAProject;
+    const sitsInAProject = deps.daemonIsProject ?? mayWriteIntoRoot;
     const { servingDirectory } = deps;
     const daemonIsProject = sitsInAProject(daemonRoot);
     // Resolved beside it and ONCE, for the same reason: a directory's `.reticle.json` does not change
@@ -164,15 +174,29 @@ export function artifactRootResolver(daemonRoot, deps) {
         : undefined;
     /** Said once per project, reason and folder: one session's calls repeated it 16 times in 3s. */
     const told = new Set();
-    // ponytail: asked once per origin (it shells out); a dev server moved to another folder on the
-    // same port is named stale until the daemon restarts.
-    const servedFrom = new Map();
-    const servingOf = (origin) => {
-        if (!servedFrom.has(origin))
-            servedFrom.set(origin, servingDirectory(origin));
-        return servedFrom.get(origin);
+    const checkout = deps.checkout ?? checkoutAt;
+    const hasWorktrees = deps.hasWorktrees ?? hasLinkedWorktrees;
+    /**
+     * The one folder `directories` stand for in the checkout that served the page, or undefined when
+     * they do not agree. Every worktree of a project declares the same id, and discovery usually knows
+     * only some of them, so the page's own checkout decides and a worktree's work stays on its branch.
+     */
+    const inServingCheckout = (directories, serving) => {
+        const to = serving === undefined ? undefined : checkout(serving);
+        const moved = new Set(directories.map((d) => rebaseIntoCheckout(d, checkout(d), to)));
+        return 1 === moved.size ? [...moved][0] : undefined;
     };
     return (projectId, origin) => {
+        // Asked at most once for each connection, and again for the next one: it can shell out, and a
+        // port that moves to another worktree is a new connection whose work must move with it.
+        let served;
+        const serving = () => {
+            if (origin === undefined) {
+                return undefined;
+            }
+            served ??= { directory: servingDirectory(origin) };
+            return served.directory;
+        };
         const known = candidates();
         let resolved = resolveArtifactRoot({ projectId, candidates: known, daemonRoot });
         // Several checkouts declare this project — every git worktree carries the same committed
@@ -183,11 +207,32 @@ export function artifactRootResolver(daemonRoot, deps) {
                 projectId,
                 candidates: known,
                 daemonRoot,
-                servingDirectory: servingOf(origin),
+                servingDirectory: serving(),
             });
+            // Worktrees nested in the main checkout (`.claude/worktrees/a`) are all candidates, and a page
+            // served from another worktree is inside none of them. It fell back to the daemon's folder.
+            const directory = resolved.reason === ArtifactRootReason.AMBIGUOUS
+                ? inServingCheckout(resolved.candidates ?? [], serving())
+                : undefined;
+            if (directory !== undefined) {
+                resolved = {
+                    root: join(directory, ReticleDir.ROOT),
+                    reason: ArtifactRootReason.MATCHED_PROJECT,
+                };
+            }
+        }
+        if (resolved.reason === ArtifactRootReason.MATCHED_PROJECT) {
+            const project = dirname(resolved.root);
+            const from = origin === undefined ? undefined : checkout(project);
+            // Only a repository that HAS worktrees pays for the serving lookup.
+            if (from === undefined || !hasWorktrees(from.commonDir)) {
+                return resolved;
+            }
+            const moved = inServingCheckout([project], serving());
+            return moved === undefined || moved === project
+                ? resolved
+                : { ...resolved, root: join(moved, ReticleDir.ROOT) };
         }
-        if (resolved.reason === ArtifactRootReason.MATCHED_PROJECT)
-            return resolved;
         // Could not name the project. The old code wrote into the daemon's directory anyway and said
         // nothing, which put `.reticle/` — journals included — into repositories nobody had
         // instrumented. Evidence still has to live somewhere, so it goes to the user's own
@@ -219,7 +264,7 @@ export function artifactRootResolver(daemonRoot, deps) {
         }
         // Named so the agent is told WHICH checkout's work is stranded: a clone serving the app was
         // never named, only the primary checkout's folders.
-        const serving = origin === undefined ? undefined : servingOf(origin);
-        return { ...resolved, root, ...(serving === undefined ? {} : { serving }) };
+        const servedFrom = serving();
+        return { ...resolved, root, ...(servedFrom === undefined ? {} : { serving: servedFrom }) };
     };
 }

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

@@ -1,5 +1,5 @@
 import { UNMATCHED_SUBDIR } from './dir/reticle-dir.js';
-import { type ProjectCandidate, type ProjectId, type ProjectRegistry } from '@reticlehq/core';
+import { type Checkout, type ProjectCandidate, type ProjectId, type ProjectRegistry } from '@reticlehq/core';
 import type { ConfigDiscovery } from '../../command/cli/config/config-discovery.js';
 /**
  * Which `.reticle/` a session's artifacts belong in.
@@ -46,11 +46,16 @@ interface ArtifactRootQuery {
     daemonRoot: string;
     /**
      * The directory the dev server that served this page runs in, when the caller could observe it.
-     * Only consulted to break an AMBIGUOUS tie: every git worktree carries the same committed
+     * Consulted to break an AMBIGUOUS tie: every git worktree carries the same committed
      * `.reticle.json`, so the projectId cannot tell them apart, but the serving process runs inside
-     * exactly one of them.
+     * exactly one of them. A lone match in a different tree from it is a second checkout, refused.
      */
     servingDirectory?: string | undefined;
+    /**
+     * The platform whose path rules apply. Windows paths are not case-sensitive, so `C:\app` and
+     * `c:\app` are one folder there. Defaults to this process's platform; a test names it.
+     */
+    platform?: NodeJS.Platform;
 }
 export interface ArtifactRoot {
     /** Absolute path to the `.reticle` directory. Always present, on every branch. */
@@ -71,6 +76,15 @@ export interface ArtifactRoot {
  * passed in, which is what makes every branch below testable without a fixture tree.
  */
 export declare function resolveArtifactRoot(query: ArtifactRootQuery): ArtifactRoot;
+/**
+ * The same project folder, in the checkout that served the page.
+ *
+ * Every git worktree of a project is the same project, so the config the daemon found names the
+ * main checkout's folder. A page served from worktree `x` belongs in `x`'s copy of that folder, so
+ * its flows and runs travel with `x`'s branch. Unchanged unless both checkouts are known, share one
+ * main checkout, and differ.
+ */
+export declare function rebaseIntoCheckout(directory: string, from: Pick<Checkout, 'root' | 'commonDir'> | undefined, to: Pick<Checkout, 'root' | 'commonDir'> | undefined): string;
 /**
  * Everything this machine knows about where projects live, from both sources.
  *

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

@@ -1,6 +1,6 @@
 import { isAbsolute, join, relative, sep } from 'node:path';
 import { UNMATCHED_SUBDIR } from './dir/reticle-dir.js';
-import { SAFE_SEGMENT_PATTERN, ReticleDir, fnv1a, projectCandidates, } from '@reticlehq/core';
+import { SAFE_SEGMENT_PATTERN, ReticleDir, fnv1a, projectCandidates, samePath, } from '@reticlehq/core';
 /**
  * Which `.reticle/` a session's artifacts belong in.
  *
@@ -47,7 +47,7 @@ export function resolveArtifactRoot(query) {
     if (projectId === undefined || 0 === projectId.length) {
         return { root: daemonRoot, reason: ArtifactRootReason.NO_PROJECT_ID };
     }
-    const matches = dedupeByDirectory(candidates.filter((c) => c.projectId === projectId));
+    const matches = dedupeByDirectory(candidates.filter((c) => c.projectId === projectId), query.platform ?? process.platform);
     if (0 === matches.length) {
         return { root: daemonRoot, reason: ArtifactRootReason.NO_MATCH };
     }
@@ -69,8 +69,40 @@ export function resolveArtifactRoot(query) {
     if (0 === directory.length) {
         return { root: daemonRoot, reason: ArtifactRootReason.NO_MATCH };
     }
+    // The page was served from a tree apart from the one checkout we know: a second checkout of the
+    // same project that the registry no longer names. Writing into the known one moves this app's
+    // evidence into a tree nobody drove, so it is refused like any other pair.
+    const serving = query.servingDirectory;
+    if (serving !== undefined &&
+        0 < serving.length &&
+        !isSameOrInside(directory, serving) &&
+        !isSameOrInside(serving, directory)) {
+        return {
+            root: daemonRoot,
+            reason: ArtifactRootReason.AMBIGUOUS,
+            candidates: [directory, serving],
+        };
+    }
     return { root: join(directory, ReticleDir.ROOT), reason: ArtifactRootReason.MATCHED_PROJECT };
 }
+/**
+ * The same project folder, in the checkout that served the page.
+ *
+ * Every git worktree of a project is the same project, so the config the daemon found names the
+ * main checkout's folder. A page served from worktree `x` belongs in `x`'s copy of that folder, so
+ * its flows and runs travel with `x`'s branch. Unchanged unless both checkouts are known, share one
+ * main checkout, and differ.
+ */
+export function rebaseIntoCheckout(directory, from, to) {
+    if (from === undefined || to === undefined)
+        return directory;
+    if (!samePath(from.commonDir, to.commonDir) || samePath(from.root, to.root))
+        return directory;
+    const rel = relative(from.root, directory);
+    if ('..' === rel || rel.startsWith(`..${sep}`) || isAbsolute(rel))
+        return directory;
+    return join(to.root, rel);
+}
 /**
  * The checkout the serving directory sits in, or undefined when it is in none of them.
  *
@@ -83,12 +115,14 @@ function checkoutContaining(matches, servingDirectory) {
         return undefined;
     const inside = matches
         .map((candidate) => candidate.directory)
-        .filter((directory) => {
-        const rel = relative(directory, servingDirectory);
-        return '' === rel || ('..' !== rel && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
-    });
+        .filter((directory) => isSameOrInside(directory, servingDirectory));
     return inside.sort((a, b) => b.length - a.length)[0];
 }
+/** Is `path` the directory `dir` or somewhere inside it? */
+function isSameOrInside(dir, path) {
+    const rel = relative(dir, path);
+    return '' === rel || ('..' !== rel && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
+}
 /**
  * One entry per directory.
  *
@@ -97,13 +131,17 @@ function checkoutContaining(matches, servingDirectory) {
  * it twice would read as two competing checkouts and make the resolver refuse, which is the one
  * outcome worse than either source alone.
  */
-function dedupeByDirectory(matches) {
+function dedupeByDirectory(matches, platform) {
+    // Windows paths are not case-sensitive: one checkout seen from two shells can differ by case.
+    const keyOf = (directory) => 'win32' === platform ? directory.toLowerCase() : directory;
     const seen = new Set();
     const out = [];
     for (const candidate of matches) {
-        if (seen.has(candidate.directory))
+        const key = keyOf(candidate.directory);
+        if (seen.has(key)) {
             continue;
-        seen.add(candidate.directory);
+        }
+        seen.add(key);
         out.push(candidate);
     }
     return out;

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

@@ -66,3 +66,8 @@ export interface FileSystemPort {
 }
 /** Production adapter — the single import site of node:fs/promises in the server. */
 export declare function createNodeFileSystem(): FileSystemPort;
+/**
+ * A file's text, or undefined when it is missing, a directory or unreadable. Synchronous, for the
+ * few questions asked before any port exists, such as which git checkout a folder is in.
+ */
+export declare function readTextOrUndefined(path: string): string | undefined;

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

@@ -1,3 +1,4 @@
+import { readFileSync } from 'node:fs';
 import { access, appendFile, mkdir, open, readdir, readFile, realpath, rename, rm, stat, writeFile, } from 'node:fs/promises';
 /** The JSONL record terminator, as a byte — the only boundary a capped tail read can align to. */
 const NEWLINE_BYTE = 0x0a;
@@ -119,3 +120,15 @@ export function createNodeFileSystem() {
         isNotFound: (error) => 'ENOENT' === error?.code,
     };
 }
+/**
+ * A file's text, or undefined when it is missing, a directory or unreadable. Synchronous, for the
+ * few questions asked before any port exists, such as which git checkout a folder is in.
+ */
+export function readTextOrUndefined(path) {
+    try {
+        return readFileSync(path, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/memory/project/learned-routes.d.ts

@@ -1,4 +1,4 @@
-import { type ReticleEvent } from '@reticlehq/core';
+import { pathOf as routeFromUrl, type ReticleEvent } from '@reticlehq/core';
 interface RouteLearningSession {
     url: string;
     /**
@@ -21,8 +21,8 @@ interface RouteLearningStore {
 export declare const ROUTE_PERSIST_DEBOUNCE_MS = 50;
 /** Convert a validated route-change payload into a bounded route identity. */
 export declare function routeFromEvent(event: ReticleEvent): string | undefined;
-/** Read the same route shape from a session's absolute URL. */
-export declare function routeFromUrl(value: string): string | undefined;
+/** Read the same route shape from a session's absolute URL: core's `pathOf`, re-exported. */
+export { routeFromUrl };
 export declare function routesFromEvents(events: readonly ReticleEvent[]): string[];
 /**
  * Persist initial and subsequent routes for existing and future browser sessions.
@@ -35,4 +35,3 @@ export declare function routesFromEvents(events: readonly ReticleEvent[]): strin
  * while the driven project's own memory never filled.
  */
 export declare function attachRouteLearning(bridge: RouteLearningBridge, storeFor: (root: string | undefined) => RouteLearningStore): void;
-export {};

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

@@ -1,4 +1,4 @@
-import { EventType } from '@reticlehq/core';
+import { EventType, pathOf as routeFromUrl } from '@reticlehq/core';
 /** Coalesce navigation bursts so one crawl does not lock and rewrite project.json per event. */
 export const ROUTE_PERSIST_DEBOUNCE_MS = 50;
 /** Convert a validated route-change payload into a bounded route identity. */
@@ -10,16 +10,8 @@ export function routeFromEvent(event) {
         return undefined;
     return pathname;
 }
-/** Read the same route shape from a session's absolute URL. */
-export function routeFromUrl(value) {
-    try {
-        const url = new URL(value);
-        return url.pathname;
-    }
-    catch {
-        return undefined;
-    }
-}
+/** Read the same route shape from a session's absolute URL: core's `pathOf`, re-exported. */
+export { routeFromUrl };
 export function routesFromEvents(events) {
     return events.flatMap((event) => {
         const route = routeFromEvent(event);

package/dist/memory/project/link-directory.js

@@ -6,7 +6,7 @@
  * while every run of that app landed in it.
  */
 import { existsSync } from 'node:fs';
-import { join, resolve, sep } from 'node:path';
+import { basename, dirname, join, resolve, sep } from 'node:path';
 import { ReticleDir } from '@reticlehq/core';
 import { discoverProjectConfigs, hasProjectConfig, } from '../../command/cli/config/config-discovery.js';
 /** `inner` is `outer` or sits inside it. */
@@ -17,7 +17,10 @@ const within = (inner, outer) => inner === outer || inner.startsWith(outer.endsW
  * kept rather than one picked silently.
  */
 export function linkDirectoryFor(cwd, discovery) {
-    const here = resolve(cwd);
+    // A `.reticle` is a project's, never a project: the HUD's Link passes the tab's `.reticle`, and on
+    // an app with no `.reticle.json` the link landed in `.reticle/.reticle/cloud.json`.
+    const asked = resolve(cwd);
+    const here = ReticleDir.ROOT === basename(asked) ? dirname(asked) : asked;
     const enclosing = discovery.found
         .map((found) => found.directory)
         .filter((directory) => within(here, directory))

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

@@ -1,5 +1,7 @@
-/** Claim `root` for the session a lease registers. Refuses anything but an absolute `.reticle`. */
+/** Claim `root` for the session a lease registers. Takes a `.reticle` folder or the project folder holding one. */
 export declare function claimArtifactRoot(leaseId: string, root: string): void;
+/** Every root a lease claimed in this process, released or not. Sync reads it to find the work. */
+export declare function claimedArtifactRoots(): string[];
 /** The root claimed for this session, by its id or by the lease marker on its url. */
 export declare function claimedArtifactRoot(sessionId: string, url: string | undefined): string | undefined;
 /** Forget a lease's claim, once the lease is released. */

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

@@ -9,22 +9,56 @@
  * reconnect after a navigation, or an app that names its own session, still finds the claim. Lives
  * until the lease is released.
  */
-import { basename, isAbsolute } from 'node:path';
+import { statSync } from 'node:fs';
+import { basename, isAbsolute, join } from 'node:path';
 import { RETICLE_URL_PARAM, ReticleDir } from '@reticlehq/core';
 const claims = new Map();
-/** Claim `root` for the session a lease registers. Refuses anything but an absolute `.reticle`. */
-export function claimArtifactRoot(leaseId, root) {
-    if (!isAbsolute(root) || ReticleDir.ROOT !== basename(root))
+/** Every root claimed in this process. Kept after release, so sync still sends what the lease wrote. */
+const everClaimed = new Set();
+/**
+ * The `.reticle` folder a caller meant by `root`. Agents pass the project folder, the one they work
+ * in, so a folder that holds a `.reticle` stands for it. Anything else is refused with the path to pass.
+ */
+function resolveArtifactRoot(root) {
+    if (!isAbsolute(root)) {
         throw new Error(`root must be an absolute path to a ${ReticleDir.ROOT} folder, got ${root}`);
-    claims.set(leaseId, root);
+    }
+    if (ReticleDir.ROOT === basename(root)) {
+        return root;
+    }
+    const inside = join(root, ReticleDir.ROOT);
+    if (isDirectory(inside)) {
+        return inside;
+    }
+    throw new Error(`root must be the ${ReticleDir.ROOT} folder, or a project folder that contains one, got ${root}. Pass ${inside}`);
+}
+function isDirectory(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/** Claim `root` for the session a lease registers. Takes a `.reticle` folder or the project folder holding one. */
+export function claimArtifactRoot(leaseId, root) {
+    const resolved = resolveArtifactRoot(root);
+    claims.set(leaseId, resolved);
+    everClaimed.add(resolved);
+}
+/** Every root a lease claimed in this process, released or not. Sync reads it to find the work. */
+export function claimedArtifactRoots() {
+    return [...everClaimed];
 }
 /** The root claimed for this session, by its id or by the lease marker on its url. */
 export function claimedArtifactRoot(sessionId, url) {
     const direct = claims.get(sessionId);
-    if (direct !== undefined)
+    if (direct !== undefined) {
         return direct;
-    if (url === undefined)
+    }
+    if (url === undefined) {
         return undefined;
+    }
     try {
         const lease = new URL(url).searchParams.get(RETICLE_URL_PARAM.SESSION);
         return null === lease ? undefined : claims.get(lease);

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

@@ -1,4 +1,4 @@
-import type { ProjectId } from '@reticlehq/core';
+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.

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

@@ -1,20 +1,6 @@
 import { dirname } from 'node:path';
+import { originOf } from '@reticlehq/core';
 import { claimedArtifactRoot } from './root-claims.js';
-/**
- * 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 };

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

@@ -14,7 +14,7 @@ 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 { CONNECT_COMMAND, 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';
@@ -189,7 +189,7 @@ export function overallStatus(summary) {
 /** 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).`;
+        return `${String(summary.runs)} run(s) exist only on this machine; nothing is synced until the project is linked (${CONNECT_COMMAND}).`;
     const ago = summary.lastPushAt === undefined
         ? 'nothing pushed yet'
         : `last push ${String(Math.max(0, Math.round((now - summary.lastPushAt) / 1000)))}s ago`;
@@ -217,8 +217,7 @@ export async function machineUnsyncedRoots(fs, home, env) {
         ...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);
+    return unsyncedRoots(roots, 
+    // A credential is what sends: a folder with no link file sends with the environment's key.
+    async (root) => null !== (await cloudOf(root)).config, async (root) => (await cloudOf(root)).policy.flows);
 }

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

@@ -17,7 +17,7 @@ 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 { MEMORY_NOT_LINKED_ADVICE, 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';
@@ -32,7 +32,7 @@ const NEEDS_STATEMENT = 'needs `subject` and `statement`';
 const DEFAULT_LIMIT = 10;
 /** What to do next, per reason. A refusal that does not say how to fix it is a dead end. */
 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.NOT_LINKED]: MEMORY_NOT_LINKED_ADVICE,
     [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.',

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

@@ -1,5 +1,5 @@
 import type { FileSystemPort } from '../project/fs/fs-port.js';
-import type { FlowFile } from '@reticlehq/core';
+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";
@@ -16,6 +16,8 @@ export declare const SetAsideRefused: {
     readonly REFUSED: "refused";
 };
 export type PlatformAnswer = Record<string, unknown>;
+/** What an unlinked project is told, on every memory action: the one command, and what it adds. */
+export declare const MEMORY_NOT_LINKED_ADVICE: string;
 /** 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. */

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

@@ -8,6 +8,7 @@
 import { homedir } from 'node:os';
 import { cloudFetch, syncFlowToCloud, SyncOutcome } from '../cloud/cloud-sync.js';
 import { resolveProjectCloud } from '../cloud/cloud-config.js';
+import { CONNECT_COMMAND, DEFAULT_PLATFORM_URL } from '@reticlehq/core';
 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 = {
@@ -32,6 +33,10 @@ const HTTP_NOT_FOUND = 404;
 const HTTP_FORBIDDEN = 403;
 const HTTP_BAD_REQUEST = 400;
 const unavailable = (reason, error) => ({ error, reason });
+/** What an unlinked project is told, on every memory action: the one command, and what it adds. */
+export const MEMORY_NOT_LINKED_ADVICE = `Run \`${CONNECT_COMMAND}\` in the project folder to link it; add \`--url <origin>\` only for a ` +
+    `Reticle platform other than ${DEFAULT_PLATFORM_URL}. Once linked, memory keeps what each run ` +
+    'proved, and every agent and teammate on the project can read it.';
 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) {
@@ -40,7 +45,10 @@ async function linked(fs, root, allowed) {
     if (null === config)
         return {
             ok: false,
-            answer: unavailable(MemoryUnavailable.NOT_LINKED, 'this project is not linked to the platform'),
+            answer: {
+                ...unavailable(MemoryUnavailable.NOT_LINKED, 'this project is not linked to the platform'),
+                advice: MEMORY_NOT_LINKED_ADVICE,
+            },
         };
     if (!allowed(cloud))
         return {