@reticlehq/server 3.6.0 → 3.7.0

package/dist/memory/project/link-directory.d.ts

@@ -0,0 +1,15 @@
+import { type ConfigDiscovery } from '../../command/cli/config/config-discovery.js';
+/**
+ * The declared project that encloses `cwd`, else the one project declared below it, else `cwd`
+ * itself. Several candidates below and none enclosing is a choice the caller must make, so `cwd` is
+ * kept rather than one picked silently.
+ */
+export declare function linkDirectoryFor(cwd: string, discovery: ConfigDiscovery): string;
+/**
+ * The `.reticle` a command run here owns: the project's, when this folder is in or above exactly one
+ * declared project or already holds a `.reticle`. Undefined anywhere else, so a lease opened from a
+ * home directory never plants a `.reticle` in it.
+ */
+export declare function callerArtifactRoot(cwd: string): string | undefined;
+/** `linkDirectoryFor` over this machine's own discovery from `cwd`. */
+export declare function linkDirectoryFrom(cwd: string): string;

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

@@ -0,0 +1,44 @@
+/**
+ * The directory `reticle link` binds: the project a session from here would write its runs into.
+ *
+ * Runs land in the root the artifact resolver picks for the page's project, which comes from the same
+ * config discovery used here. Binding `cwd` instead left a monorepo's `apps/web/.reticle` unlinked
+ * while every run of that app landed in it.
+ */
+import { existsSync } from 'node:fs';
+import { 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. */
+const within = (inner, outer) => inner === outer || inner.startsWith(outer.endsWith(sep) ? outer : `${outer}${sep}`);
+/**
+ * The declared project that encloses `cwd`, else the one project declared below it, else `cwd`
+ * itself. Several candidates below and none enclosing is a choice the caller must make, so `cwd` is
+ * kept rather than one picked silently.
+ */
+export function linkDirectoryFor(cwd, discovery) {
+    const here = resolve(cwd);
+    const enclosing = discovery.found
+        .map((found) => found.directory)
+        .filter((directory) => within(here, directory))
+        .sort((a, b) => b.length - a.length)[0];
+    if (enclosing !== undefined)
+        return enclosing;
+    const below = discovery.found.filter((found) => within(found.directory, here));
+    const only = 1 === below.length ? below[0] : undefined;
+    return only === undefined ? here : only.directory;
+}
+/**
+ * The `.reticle` a command run here owns: the project's, when this folder is in or above exactly one
+ * declared project or already holds a `.reticle`. Undefined anywhere else, so a lease opened from a
+ * home directory never plants a `.reticle` in it.
+ */
+export function callerArtifactRoot(cwd) {
+    const dir = linkDirectoryFrom(cwd);
+    const root = join(dir, ReticleDir.ROOT);
+    return hasProjectConfig(dir) || existsSync(root) ? root : undefined;
+}
+/** `linkDirectoryFor` over this machine's own discovery from `cwd`. */
+export function linkDirectoryFrom(cwd) {
+    return linkDirectoryFor(cwd, discoverProjectConfigs(cwd));
+}

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

@@ -0,0 +1,6 @@
+/** Claim `root` for the session a lease registers. Refuses anything but an absolute `.reticle`. */
+export declare function claimArtifactRoot(leaseId: string, root: string): void;
+/** 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. */
+export declare function dropArtifactRootClaim(leaseId: string): void;

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

@@ -0,0 +1,39 @@
+/**
+ * Which `.reticle` a leased session writes into, when whoever opened the lease said so.
+ *
+ * The resolver can only go on the page's project id and origin, and a page with no project id lands
+ * in `~/.reticle/unmatched/`, which nothing links or syncs. A lease opened by `reticle try`, a chat
+ * drive or `verify` from a linked folder knows better: the run belongs to the folder that asked.
+ *
+ * Keyed by the lease id, which the leased tab carries as `__reticle_session` on its url, so a
+ * 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 { 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))
+        throw new Error(`root must be an absolute path to a ${ReticleDir.ROOT} folder, got ${root}`);
+    claims.set(leaseId, root);
+}
+/** 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)
+        return direct;
+    if (url === undefined)
+        return undefined;
+    try {
+        const lease = new URL(url).searchParams.get(RETICLE_URL_PARAM.SESSION);
+        return null === lease ? undefined : claims.get(lease);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Forget a lease's claim, once the lease is released. */
+export function dropArtifactRootClaim(leaseId) {
+    claims.delete(leaseId);
+}

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

@@ -13,6 +13,8 @@ import type { ToolDeps } from '../../surface/tools/tool-kit.js';
 export interface ProjectTarget {
     projectId: ProjectId | undefined;
     origin?: string | undefined;
+    /** The root whoever leased this session claimed for it (see `root-claims.ts`), which wins. */
+    claimedRoot?: 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;

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

@@ -1,4 +1,5 @@
 import { dirname } from 'node:path';
+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
@@ -57,6 +58,8 @@ export function sessionRoot(deps, sessionId) {
  * cannot disagree about what a resolved root is.
  */
 export function rootForTarget(deps, target) {
+    if (target.claimedRoot !== undefined)
+        return target.claimedRoot;
     return deps.artifactRootFor?.(target.projectId, target.origin).root ?? deps.reticleRoot;
 }
 /**
@@ -111,7 +114,12 @@ export function safeSessionTarget(deps, sessionId) {
 export function sessionTarget(deps, sessionId) {
     try {
         const session = deps.sessions.resolve(sessionId);
-        return { projectId: session.projectId, origin: originOf(session.url) };
+        const claimedRoot = claimedArtifactRoot(session.id, session.url);
+        return {
+            projectId: session.projectId,
+            origin: originOf(session.url),
+            ...(claimedRoot === undefined ? {} : { claimedRoot }),
+        };
     }
     catch (cause) {
         if (sessionId === undefined)

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

@@ -1,4 +1,6 @@
 import type { CloudSyncState } from '../cloud/sync-cycle.js';
+import { type UnsyncedRoot } from '../cloud/unsynced-roots.js';
+import type { FileSystemPort } from './fs/fs-port.js';
 export declare const SyncStatus: {
     readonly ON_PLATFORM: "on-platform";
     readonly PENDING: "pending";
@@ -22,6 +24,8 @@ export interface SyncSummary {
     lastPushAt?: number;
     /** Why the last cycle failed, when it did. */
     lastError?: string;
+    /** The newest run the platform holds in its current form: what "see it in your dashboard" opens. */
+    latestOnPlatform?: string;
 }
 export declare function summarizeSync(input: {
     linked: boolean;
@@ -31,9 +35,51 @@ export declare function summarizeSync(input: {
     }[];
     state: CloudSyncState;
 }): SyncSummary;
+/**
+ * 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 declare function readDashboardUrl(reticleRoot: string): string | undefined;
+/** The platform project this folder is linked to, from the same link file. */
+export declare function readLinkedProjectId(reticleRoot: string): string | undefined;
+/** The refused credential, in words: what a person has to act on. */
+export declare const KEY_REFUSED = "the platform refused this project's API key: it was revoked, or its owner no longer has access to the workspace";
+/**
+ * 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 declare function refusalSaid(body: string): string;
+/** Why the platform refused this project's key at the last sync, or undefined. Never throws. */
+export declare function keyRefusalAtLastSync(reticleRoot: string): string | undefined;
+/** Whether the platform refused this project's key at the last sync. Never throws. */
+export declare function keyRefusedAtLastSync(reticleRoot: string): boolean;
+/** The dashboard's page for one run: the console's `/runs/:runId` route, at the dashboard's origin. */
+export declare const DASHBOARD_RUN_PATH = "/runs/";
+export declare const DASHBOARD_PLAN_PATH = "/plans/";
+export declare function dashboardRunUrl(dashboardUrl: string, runId: string): string;
+/** The line a command prints once its run reached the platform. */
+export declare function seeRunLine(dashboardUrl: string, runId: string): string;
+/**
+ * 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 declare function dashboardPlanUrl({ dashboardUrl, planId, projectId, }: {
+    dashboardUrl: string;
+    planId: string;
+    projectId?: string | undefined;
+}): string;
 /** 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;
+/**
+ * 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 declare function machineUnsyncedRoots(fs: FileSystemPort, home: string, env: NodeJS.ProcessEnv): Promise<UnsyncedRoot[]>;

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

@@ -12,6 +12,12 @@
  */
 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',
@@ -25,10 +31,14 @@ export function summarizeSync(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)
@@ -48,8 +58,113 @@ export function summarizeSync(input) {
         ...(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 = [];
@@ -84,7 +199,26 @@ export function describeSync(summary, now) {
     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)
+    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.
  *
@@ -31,13 +36,18 @@ const 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.',
-    [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.',
+    [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()
@@ -48,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(),
@@ -65,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;
+    }
+}