@reticlehq/server 3.5.0 → 3.7.0

package/dist/memory/cloud/sync-cycle.js

@@ -30,19 +30,21 @@
  * Every dependency is injected — the clock, the fetch, the reads and writes — because this is the
  * one piece of Reticle that talks to a network AND to a disk, and it must be provable without either.
  */
-import { FlowErrorCode, ReticleDir, SYNC_BATCH_LIMITS } from '@reticlehq/core';
+import { FlowErrorCode, ReticleDir, SYNC_BATCH_LIMITS, flowJsonReplacer } from '@reticlehq/core';
 import { hashPayload } from './sync-hash.js';
+import { syncScreenshots } from './sync-screenshots.js';
 /** The server's own doors. Kept beside the code that calls them, like the other cloud paths. */
 const SYNC_PATH = '/v1/sync';
 const SYNC_STATUS_PATH = '/v1/sync/status';
 const SYNC_PULL_PATH = '/v1/sync/pull';
+const FLOWS_PATH = '/v1/flows';
 /**
  * The derived records that ride along with runs, and the file each one lives in.
  *
- * A list rather than three hand-written blocks so adding a fourth is one line and cannot be
- * half-done — the bundle, the hashing and the reporting all walk this.
+ * One list, so adding a record is one line and cannot be half-done: the bundle, the hashing, the
+ * reporting and the disk source (`sync-disk.ts`) all read it.
  */
-const DERIVED_RECORDS = [
+export const DERIVED_RECORDS = [
     { kind: 'impact', file: ReticleDir.IMPACT_FILE },
     { kind: 'flake', file: ReticleDir.FLAKE_FILE },
     { kind: 'intent', file: ReticleDir.INTENT_FILE },
@@ -50,6 +52,10 @@ const DERIVED_RECORDS = [
     // cannot tell a server a page that drifted from one that always behaved that way.
     { kind: 'envelopes', file: ReticleDir.ENVELOPES_FILE },
     { kind: 'assertion-tiers', file: ReticleDir.TIERS_FILE },
+    // Reticle Coverage: what the platform's Overview shows as controls proved and routes reached.
+    { kind: 'coverage', file: ReticleDir.COVERAGE_FILE },
+    // The notes a human pinned in the HUD, pending and resolved: the review trail a team reads.
+    { kind: 'notes', file: ReticleDir.NOTES_FILE },
 ];
 const asJson = (text) => {
     try {
@@ -75,6 +81,8 @@ const flowName = (flow, index) => {
 const FLOW_VERSION_FIX = 'update the platform or remove `compare` from the flow';
 const RUN_VERSION_FIX = 'update the platform';
 /** The server's per-part answer: accepted count and rejection list, each read defensively. */
+/** A 200 that never confirmed the runs it was sent. Kept queued, and said, rather than dropped. */
+export const MSG_RUNS_UNCONFIRMED = 'sync 200 without a runs result: the server did not confirm the runs it was sent, so they stay queued';
 function partResult(body, part) {
     const raw = isRecord(body[part]) ? body[part] : {};
     const accepted = 'number' === typeof raw['accepted'] ? raw['accepted'] : 0;
@@ -125,7 +133,29 @@ function batchRuns(runs) {
  * Run one cycle. Never throws: the local record is already safe on disk, and a sync that can take
  * down the thing it is backing up is worse than no sync.
  */
-export async function runSyncCycle(deps) {
+/** The command that moves a folder's earlier runs to the link it has now. */
+export const MOVE_HISTORY_COMMAND = 'reticle sync --move-history';
+/**
+ * The record this cycle keeps, for this link. Re-linked to another cloud, workspace or project, it
+ * starts afresh from now: what the old link was sent says nothing about the new one, and the runs
+ * made under the old link are that workspace's (a person's email can be in their steps), so they go
+ * only when the person moves them. A first link, or a record from before links were kept, is
+ * adopted as it is.
+ */
+function stateForLink(deps) {
+    const { state, link } = deps;
+    if (link === undefined)
+        return state;
+    if (state.link === undefined || state.link === link) {
+        const { linkedAt, ...rest } = state;
+        return true === deps.moveHistory || linkedAt === undefined
+            ? { ...rest, link }
+            : { ...rest, link, linkedAt };
+    }
+    return { link, ...(true === deps.moveHistory ? {} : { linkedAt: deps.now() }) };
+}
+export async function runSyncCycle(given) {
+    const deps = { ...given, state: stateForLink(given) };
     const empty = {
         ok: false,
         runsSent: 0,
@@ -231,7 +261,14 @@ export async function runSyncCycle(deps) {
             notRetried.push({ runId: run.runId, reason: prior.reason });
             return false;
         });
+        // Made before this folder was linked here: the previous link's, kept until the person moves it.
+        const linkedAt = deps.state.linkedAt;
+        const earlier = unsent.filter((run) => linkedAt !== undefined && !((numberAt(run.payload, 'createdAt') ?? 0) >= linkedAt));
+        if (0 < earlier.length)
+            heldBack.push(`${String(earlier.length)} run${1 === earlier.length ? '' : 's'} made before this folder was linked to this workspace stay${1 === earlier.length ? 's' : ''} on this machine (recorded under its previous link): run \`${MOVE_HISTORY_COMMAND}\` to send ${1 === earlier.length ? 'it' : 'them'} here`);
         const sendable = unsent.filter((run) => {
+            if (earlier.includes(run))
+                return false;
             const version = numberAt(run.payload, 'schemaVersion');
             if (runVersions === undefined || version === undefined || runVersions.includes(version))
                 return true;
@@ -242,25 +279,51 @@ export async function runSyncCycle(deps) {
         const derivedOffered = [];
         const unsupported = [];
         const bundle = {};
+        // A folder re-linked elsewhere keeps what it derived under the old link (its counts, defects,
+        // notes) here with the runs: those records add up the whole history and cannot be split by time.
+        // ponytail: held until `--move-history`; a per-link reset of the counters would let new ones go.
+        const derivedHeld = [];
         for (const { kind } of DERIVED_RECORDS) {
             const payload = deps.source.derived(kind);
             if (payload === undefined)
                 continue;
+            if (linkedAt !== undefined) {
+                derivedHeld.push(kind);
+                continue;
+            }
             if (!acceptedKinds.has(kind)) {
                 unsupported.push(kind);
                 continue;
             }
-            // The one comparison the whole protocol rests on. Same hash, do not send it.
-            if (hashPayload(payload) === hashes[kind])
+            // The one comparison the whole protocol rests on. Same hash, do not send it: the platform's,
+            // or the one it accepted from here while it still holds the record (a null means it does not).
+            const hash = hashPayload(payload);
+            if (hash === hashes[kind])
+                continue;
+            if ('string' === typeof hashes[kind] && hash === deps.state.sentDerivedHashes?.[kind])
                 continue;
             bundle[kind] = payload;
             derivedOffered.push(kind);
         }
         if (unsupported.length > 0)
             heldBack.push(`this platform does not accept ${unsupported.join(', ')} yet`);
+        if (0 < derivedHeld.length)
+            heldBack.push(`the ${derivedHeld.join(', ')} record${1 === derivedHeld.length ? '' : 's'} made under this folder's previous link stay${1 === derivedHeld.length ? 's' : ''} on this machine: run \`${MOVE_HISTORY_COMMAND}\` to send ${1 === derivedHeld.length ? 'it' : 'them'} here`);
         // Flows and capsules are upserted by name/id, so the whole set goes whenever it differs from the
-        // set the platform last answered for, and rides along with anything else being sent.
-        const flows = deps.source.flows().filter((flow, index) => {
+        // set the platform last answered for — and only then. Riding along with every run push re-sent
+        // ~1.3 MB per push on a real repo, and a POST that size timed out and failed the run with it.
+        // Made before this folder was linked here, like the runs: the previous link's, kept until moved.
+        // A flow carries the steps of whoever drove it, so it is that workspace's as much as a run is.
+        // One read for both halves: the disk source rebuilds every flow per read, so a second read's
+        // objects are never `includes` of the first's, and every held-back flow went out anyway.
+        const flowsAll = deps.source.flows();
+        const madeBefore = (flow) => linkedAt !== undefined && !((numberAt(flow, 'createdAt') ?? 0) >= linkedAt);
+        const flowsBefore = flowsAll.filter(madeBefore);
+        if (0 < flowsBefore.length)
+            heldBack.push(`${String(flowsBefore.length)} flow${1 === flowsBefore.length ? '' : 's'} made before this folder was linked to this workspace stay${1 === flowsBefore.length ? 's' : ''} on this machine: run \`${MOVE_HISTORY_COMMAND}\` to send ${1 === flowsBefore.length ? 'it' : 'them'} here`);
+        const flows = flowsAll.filter((flow, index) => {
+            if (madeBefore(flow))
+                return false;
             const version = numberAt(flow, 'version');
             if (flowVersions === undefined || version === undefined || flowVersions.includes(version))
                 return true;
@@ -290,10 +353,9 @@ export async function runSyncCycle(deps) {
         };
         const flowsChanged = due('flow', flowsHash, flows.length, deps.state.sentFlowsHash);
         const capsulesChanged = due('capsule', capsulesHash, capsulesAll.length, deps.state.sentCapsulesHash);
-        const ridesAlong = sendable.length > 0 || derivedOffered.length > 0 || flowsChanged || capsulesChanged;
-        if (ridesAlong && flows.length > 0)
+        if (flowsChanged)
             bundle['flows'] = flows;
-        const capsules = ridesAlong ? capsulesAll : [];
+        const capsules = capsulesChanged ? capsulesAll : [];
         if (capsules.length > 0)
             bundle['capsules'] = capsules;
         let runsSent = 0;
@@ -315,12 +377,23 @@ export async function runSyncCycle(deps) {
             const body = 0 === i ? { ...bundle } : {};
             if (batch.length > 0)
                 body['runs'] = batch.map((r) => r.payload);
-            const pushed = await call(SYNC_PATH, { method: 'POST', body: JSON.stringify(body) });
+            // The flows ride here too: a default flag stays out of them, as on disk.
+            const pushed = await call(SYNC_PATH, {
+                method: 'POST',
+                body: JSON.stringify(body, flowJsonReplacer),
+            });
             if (200 !== pushed.status) {
                 pushError = `sync ${String(pushed.status)}: ${pushed.text.slice(0, 200)}`;
                 break;
             }
             const answer = isRecord(pushed.json) ? pushed.json : {};
+            // Runs were sent and the answer says nothing about them: a proxy's 200 page, an empty body.
+            // Delivered means the server said so. Recording them as sent here dropped them for good while
+            // the cycle reported ok; they stay queued, and the reason is the cycle's error.
+            if (batch.length > 0 && !isRecord(answer['runs'])) {
+                pushError = MSG_RUNS_UNCONFIRMED;
+                break;
+            }
             const runs = partResult(answer, 'runs');
             runsSent += runs.accepted;
             // Accepted means the server has it. A rejected run was refused by index, so it is exactly as
@@ -375,18 +448,40 @@ export async function runSyncCycle(deps) {
             const state = isRecord(answer['state']) ? answer['state'] : {};
             for (const kind of derivedOffered) {
                 const verdict = state[kind];
-                if ('accepted' === verdict)
+                if ('accepted' === verdict) {
                     derivedSent.push(kind);
+                    nextState.sentDerivedHashes = {
+                        ...nextState.sentDerivedHashes,
+                        [kind]: hashPayload(bundle[kind]),
+                    };
+                }
                 else if ('string' === typeof verdict)
                     refused.push({ part: kind, reason: `${kind}: ${verdict}` });
             }
         }
+        // A flow the platform took from here and that is gone from disk is deleted there by name: it
+        // does not infer a deletion from a missing name, since another clone may still hold the flow.
+        const onDisk = new Set(deps.source.flows().map(flowName));
+        const kept = [];
+        for (const name of deps.projectId === undefined ? [] : (deps.state.sentFlowNames ?? [])) {
+            if (onDisk.has(name)) {
+                kept.push(name);
+                continue;
+            }
+            const gone = await call(`${FLOWS_PATH}/${encodeURIComponent(name)}?projectId=${encodeURIComponent(deps.projectId ?? '')}`, { method: 'DELETE' });
+            if (2 !== Math.floor(gone.status / 100) && 404 !== gone.status)
+                kept.push(name);
+        }
+        if (deps.projectId !== undefined)
+            nextState.sentFlowNames = kept;
         if (requests > 0 && pushError === undefined) {
             nextState.lastPushAt = deps.now();
             // The platform answered for these sets, refusals included (reported above, and not re-offered
             // until the set changes — the same rule as a refused run).
-            if (ridesAlong && flows.length > 0)
+            if (flowsChanged)
                 nextState.sentFlowsHash = flowsHash;
+            if (flowsChanged && deps.projectId !== undefined)
+                nextState.sentFlowNames = [...new Set([...kept, ...flows.map(flowName)])];
             if (capsules.length > 0)
                 nextState.sentCapsulesHash = capsulesHash;
         }
@@ -416,6 +511,22 @@ export async function runSyncCycle(deps) {
          */
         nextState.sentRunIds = allRuns.map((r) => r.runId).filter((id) => known.has(id));
         nextState.sentRunHashes = heldHashes(allRuns, recorded);
+        // 2b. The step screenshots of every run the platform now holds, once each.
+        let screenshotsSent = 0;
+        const readImage = deps.source.screenshot;
+        if (readImage !== undefined) {
+            const shots = await syncScreenshots({
+                runs: allRuns,
+                accepted: (runId) => known.has(runId),
+                readImage,
+                state: deps.state,
+                post: (path, body) => call(path, { method: 'POST', body }),
+            });
+            screenshotsSent = shots.sent;
+            Object.assign(nextState, shots.state);
+            if (shots.error !== undefined)
+                heldBack.push(shots.error);
+        }
         // 3. COLLECT — always, even when there was nothing to send.
         const query = nextState.cursor === undefined ? '' : `?since=${encodeURIComponent(nextState.cursor)}`;
         const pull = await call(`${SYNC_PULL_PATH}${query}`);
@@ -464,6 +575,7 @@ export async function runSyncCycle(deps) {
                 0 === setsNotRetried.length &&
                 !heldArtifacts,
             runsSent,
+            ...(0 === screenshotsSent ? {} : { screenshotsSent }),
             runsRejected,
             flowsSent,
             capsulesSent,
@@ -537,6 +649,8 @@ export function describeSync(report) {
         sent.push(`${String(report.flowsSent)} flow(s)`);
     if (report.capsulesSent > 0)
         sent.push(`${String(report.capsulesSent)} capsule(s)`);
+    if ((report.screenshotsSent ?? 0) > 0)
+        sent.push(`${String(report.screenshotsSent)} screenshot(s)`);
     if (report.derivedSent.length > 0)
         sent.push(report.derivedSent.join(', '));
     /*

package/dist/memory/cloud/sync-daemon.d.ts

@@ -1,5 +1,6 @@
 import { type SyncReport } from './sync-cycle.js';
 import { type ProjectCloud } from './cloud-config.js';
+import { type UnsyncedRoot } from './unsynced-roots.js';
 import type { FileSystemPort } from '../project/fs/fs-port.js';
 interface SyncDaemonDeps {
     reticleRoot: string;
@@ -20,6 +21,11 @@ interface SyncDaemonDeps {
     cloudFor?: (root: string) => Promise<ProjectCloud>;
     now?: () => number;
     intervalMs?: number;
+    /**
+     * Call `onChange` when this root's link file changes; returns how to stop. A re-link was read only
+     * on the next idle tick, so a daemon kept syncing to the old link for up to a minute.
+     */
+    watchLink?: (onChange: () => void) => () => void;
     /** Injected for the test; the real one is `fetch`. */
     request?: (url: string, init: {
         method: string;
@@ -58,6 +64,11 @@ export interface SyncDaemon {
      * time — the artifact is still on disk and the next daemon for this project sends it.
      */
     flush: () => Promise<void>;
+    /**
+     * Every root this daemon knows with runs the platform does not have, as of the last cycle — linked
+     * or not. An unlinked one is the case nothing will ever send, and it used to be skipped silently.
+     */
+    unsyncedRoots: () => readonly UnsyncedRoot[];
 }
 /**
  * Start the loop. Safe to call for an UNLINKED project: it resolves the link on every tick and does

package/dist/memory/cloud/sync-daemon.js

@@ -21,11 +21,21 @@
  * laptop on a train would otherwise fill the log with the same line four hundred times and teach
  * everyone to ignore it.
  */
+import { reticleDirPaths } from '../project/dir/reticle-dir.js';
+import { syncRequest } from './cloud-sync.js';
 import { log } from '../../log.js';
+import { homedir } from 'node:os';
 import { emitSyncHook } from '../../hooks/hook-emit.js';
+import { MemoryReadHeader, MemoryReadPurpose, memoryReadUrl, scopedMemoryEntries, } from './memory-scope.js';
+import { IntentShardStore } from '../intent/intent-shard-store.js';
+import { applySettledWords, keptWordsInRequest, settledWordsIn, } from '../intent/settled-words.js';
+import { createNodeFileSystem } from '../project/fs/fs-port.js';
+import { flushPendingWrites } from '../../hooks/hook-bus.js';
 import { describeSync, runSyncCycle } from './sync-cycle.js';
 import { diskSink, diskSource, readCloudState } from './sync-disk.js';
-import { resolveProjectCloud } from './cloud-config.js';
+import { CLOUD_LINK_FILE, resolveProjectCloud } from './cloud-config.js';
+import { watch } from 'node:fs';
+import { unmatchedRoots, unsyncedRoots } from './unsynced-roots.js';
 /** How often the daemon cycles. See the note above on why this is a constant and not a curve. */
 const DAEMON_SYNC_INTERVAL_MS = 60_000;
 /**
@@ -69,10 +79,7 @@ const movedAnything = (report) => report.runsSent > 0 ||
     report.capsulesSent > 0 ||
     report.derivedSent.length > 0 ||
     report.pulled > 0;
-const defaultRequest = async (url, init) => {
-    const res = await fetch(url, init);
-    return { status: res.status, text: await res.text() };
-};
+const defaultRequest = (url, init) => syncRequest(url, init);
 /**
  * Start the loop. Safe to call for an UNLINKED project: it resolves the link on every tick and does
  * nothing until one appears, which is what lets `reticle link` take effect without a restart.
@@ -102,18 +109,62 @@ export function startSyncDaemon(deps) {
      * so too. Once per transition, never per tick — a line every minute is a line people stop reading.
      */
     let wasLinked;
+    /** The project the last cycle synced to: a re-link to another one is announced too. */
+    let wasProject;
+    /** The last count logged per root: a root is announced when its count changes, never per tick. */
+    const announced = new Map();
+    let unsynced = [];
+    /** Which roots pushed this cycle, and whether each is linked by its own link file. */
+    let rootsLinked = new Map();
+    /** The linked roots that send flows: a link with `sync.flows` off keeps every flow local. */
+    let rootsSendFlows = new Set();
+    /**
+     * Count what every root still owes, and say once per change where runs sit that nothing sends.
+     * Linked roots are listed too (the platform report and `doctor` read them), but only an unlinked
+     * one earns a log line: a linked root's pending runs are the next cycle's job.
+     */
+    const refreshUnsynced = async () => {
+        const linked = rootsLinked;
+        const sendsFlows = rootsSendFlows;
+        unsynced = await unsyncedRoots(
+        // With what no project claimed, which no cycle pushes: the dashboard's unsent list left it out.
+        [...linked.keys(), ...unmatchedRoots(homedir())], (r) => Promise.resolve(true === linked.get(r)), (r) => Promise.resolve(sendsFlows.has(r)));
+        for (const entry of unsynced) {
+            const held = entry.runs + entry.flows;
+            if (entry.linked || announced.get(entry.root) === held)
+                continue;
+            announced.set(entry.root, held);
+            log('reticle_cloud_unsynced_root', {
+                root: entry.root,
+                runs: entry.runs,
+                flows: entry.flows,
+                linked: entry.linked,
+                fix: "run `reticle connect` in that folder's project: this work is on this machine only",
+            });
+        }
+    };
     /** One root's bundle. The state, source and sink are already per-root; only the caller was not. */
     const pushRoot = async (root, cloud) => {
         if (null === cloud.config)
             return undefined;
         const full = diskSource(root);
+        // The team's decisions come down too: an author's record kept the words a maintainer set aside,
+        // and re-sent them every cycle as a new disagreement.
+        if (cloud.policy.memory)
+            await pullSettledWords(root, cloud.config, cloud.projectId).catch(() => 0);
         return runSyncCycle({
             config: cloud.config,
+            ...(cloud.link === undefined ? {} : { link: cloud.link }),
+            // Flows deleted here are deleted there, for the project they were sent to.
+            ...(cloud.policy.flows && null !== cloud.projectId ? { projectId: cloud.projectId } : {}),
             source: {
                 runs: () => (cloud.policy.runs ? full.runs() : []),
                 flows: () => (cloud.policy.flows ? full.flows() : []),
                 capsules: () => (cloud.policy.capsules ? full.capsules() : []),
                 derived: (kind) => (cloud.policy.memory ? full.derived(kind) : undefined),
+                ...(cloud.policy.screenshots && full.screenshot !== undefined
+                    ? { screenshot: full.screenshot }
+                    : {}),
             },
             sink: diskSink(root),
             state: readCloudState(root),
@@ -121,6 +172,23 @@ export function startSyncDaemon(deps) {
             request,
         });
     };
+    /** Bring the dashboard's memory decisions down to this root's records. Returns how many changed. */
+    const pullSettledWords = async (root, config, projectId) => {
+        const res = await request(memoryReadUrl(config.url, { projectId }), {
+            method: 'GET',
+            // The sync, not an agent: without this every cycle counted as an agent consulting memory.
+            headers: {
+                authorization: `Bearer ${config.apiKey}`,
+                [MemoryReadHeader.PURPOSE]: MemoryReadPurpose.SYNC,
+            },
+        });
+        if (200 !== res.status)
+            return 0;
+        const entries = scopedMemoryEntries(JSON.parse(res.text), projectId) ?? [];
+        const settled = settledWordsIn(entries);
+        await keptWordsInRequest(reticleDirPaths(root).request, settled);
+        return applySettledWords(new IntentShardStore(createNodeFileSystem(), root, { now }), settled);
+    };
     /**
      * Push every other linked root this machine knows about.
      *
@@ -145,10 +213,19 @@ export function startSyncDaemon(deps) {
         for (const root of list) {
             if (root === deps.reticleRoot)
                 continue;
+            rootsLinked.set(root, false);
             try {
                 const cloud = await cloudFor(root);
-                if (null === cloud.config)
+                // Linked HERE, by its own link file. An unlinked root resolves to the environment's key,
+                // which is the right answer for the root this daemon stands in and somebody else's project
+                // for every other one: a daemon started with RETICLE_API_KEY pushed every project this
+                // machine had seen into that one, a status and a pull per root on every cycle.
+                // Never silently: `refreshUnsynced` names this root if it holds runs.
+                if (null === cloud.config || null === cloud.projectId)
                     continue;
+                rootsLinked.set(root, true);
+                if (cloud.policy.flows)
+                    rootsSendFlows.add(root);
                 const report = await pushRoot(root, cloud);
                 if (report === undefined)
                     continue;
@@ -178,11 +255,18 @@ export function startSyncDaemon(deps) {
         if (running)
             return undefined;
         running = true;
+        rootsLinked = new Map();
+        rootsSendFlows = new Set();
         try {
             const cloud = await deps.cloud();
             const linked = null !== cloud.config;
-            if (linked !== wasLinked) {
+            const own = deps.reticleRoot;
+            rootsLinked.set(own, linked);
+            if (linked && cloud.policy.flows)
+                rootsSendFlows.add(own);
+            if (linked !== wasLinked || (linked && cloud.projectId !== wasProject)) {
                 wasLinked = linked;
+                wasProject = cloud.projectId;
                 if (linked)
                     log('reticle_cloud_linked', {
                         projectId: cloud.projectId,
@@ -193,7 +277,7 @@ export function startSyncDaemon(deps) {
                 else
                     log('reticle_cloud_unlinked', {
                         root: deps.reticleRoot,
-                        fix: 'run `reticle link` in this directory, or start the daemon in the linked one — nothing is being synced from here',
+                        fix: 'run `reticle connect` in this directory, or start the daemon in the linked one — nothing is being synced from here',
                     });
             }
             // Every OTHER linked root, first. Their failures are logged and never abort this daemon's own
@@ -251,6 +335,7 @@ export function startSyncDaemon(deps) {
             return undefined;
         }
         finally {
+            await refreshUnsynced().catch(() => undefined);
             running = false;
         }
     };
@@ -270,20 +355,30 @@ export function startSyncDaemon(deps) {
         timer.unref?.();
     };
     schedule(FIRST_CYCLE_DELAY_MS);
+    // A nudge, not an immediate cycle: the link file and its key are written one after the other.
+    const unwatch = deps.watchLink?.(() => schedule(NUDGE_DELAY_MS));
     return {
-        syncNow: cycle,
+        // A sync somebody asked for writes what is held on a timer first: a drive's run waits a few
+        // seconds after its last verdict, and a push straight after `session end` sent "0 of 0".
+        syncNow: async () => {
+            await flushPendingWrites();
+            return cycle();
+        },
+        unsyncedRoots: () => unsynced,
         nudge: () => {
             // A cycle already in flight will not pick this up, so the nudge is still scheduled behind it
             // rather than dropped — otherwise the run that arrived during a slow cycle waits a full tick.
             schedule(NUDGE_DELAY_MS);
         },
         stop: () => {
+            unwatch?.();
             stopped = true;
             if (timer !== undefined)
                 clearTimeout(timer);
             timer = undefined;
         },
         flush: async () => {
+            unwatch?.();
             stopped = true;
             if (timer !== undefined)
                 clearTimeout(timer);
@@ -318,5 +413,22 @@ export function attachCloudSync(deps) {
         // reporting nothing — indistinguishable, on the dashboard, from nobody having verified anything.
         otherRoots: () => Promise.resolve(deps.otherRoots()),
         cloudFor: (root) => resolveProjectCloud(deps.fs, root, deps.homeDir, deps.env),
+        // ponytail: this root only; a sibling root's re-link is still read on the next tick.
+        watchLink: (onChange) => watchLinkFile(deps.reticleRoot, onChange),
     });
 }
+/** Watch a root for its link file changing. A root with no `.reticle` yet is picked up per tick. */
+function watchLinkFile(reticleRoot, onChange) {
+    try {
+        const watcher = watch(reticleRoot, (_event, name) => {
+            if (CLOUD_LINK_FILE === String(name))
+                onChange();
+        });
+        watcher.on('error', () => watcher.close());
+        watcher.unref();
+        return () => watcher.close();
+    }
+    catch {
+        return () => undefined;
+    }
+}

package/dist/memory/cloud/sync-disk.d.ts

@@ -1,4 +1,4 @@
-import type { CloudSyncState, PulledIssues, SyncSink, SyncSource } from './sync-cycle.js';
+import { type CloudSyncState, type PulledIssues, type SyncSink, type SyncSource } from './sync-cycle.js';
 /** What the cycle reads, backed by a real `.reticle` directory. */
 export declare function diskSource(reticleRoot: string): SyncSource;
 /** What the cycle writes back into `.reticle/`. */

package/dist/memory/cloud/sync-disk.js

@@ -10,9 +10,12 @@
  * one unsynced record, not a crashed sync. There is no state here worth defending against a parse
  * error — the file will be rewritten on the next tool call anyway.
  */
+import { shareableRun } from '@reticlehq/core/artifacts';
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync, } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { basename, dirname, join } from 'node:path';
+import { stepShotDir } from '../project/dir/reticle-dir.js';
 import { IntentDir, ReticleDir } from '@reticlehq/core';
+import { DERIVED_RECORDS, } from './sync-cycle.js';
 import { subjectFor } from '../intent/intent-subject.js';
 const JSON_SUFFIX = '.json';
 /** Read + parse, or undefined for absent/unreadable/malformed. Never throws. */
@@ -79,13 +82,7 @@ function readFlows(root) {
         return [];
     }
 }
-const DERIVED_FILE = {
-    impact: ReticleDir.IMPACT_FILE,
-    flake: ReticleDir.FLAKE_FILE,
-    intent: ReticleDir.INTENT_FILE,
-    envelopes: ReticleDir.ENVELOPES_FILE,
-    'assertion-tiers': ReticleDir.TIERS_FILE,
-};
+const DERIVED_FILE = Object.fromEntries(DERIVED_RECORDS.map((record) => [record.kind, record.file]));
 /** The directory the sharded intent store writes into, beside the legacy flat file. */
 const INTENT_SUBDIR = ReticleDir.INTENT_SUBDIR;
 const INTENT_INDEX = IntentDir.INDEX_FILE;
@@ -106,6 +103,8 @@ const INTENT_INDEX = IntentDir.INDEX_FILE;
  * Returns undefined when there is no memory at all, so a project with nothing to say sends nothing
  * rather than an empty envelope the server has to store.
  */
+/** The longest reason the platform keeps for a statement. */
+const MAX_REASON = 2000;
 function readIntent(reticleRoot) {
     const legacy = readJson(join(reticleRoot, ReticleDir.INTENT_FILE));
     const merged = {
@@ -143,7 +142,16 @@ function readIntent(reticleRoot) {
      * answers start disagreeing — and the one with the evidence should be the one that decides.
      * Records that already name a subject keep it: an agent's explicit choice outranks inference.
      */
-    const placed = Object.fromEntries(Object.entries(merged).map(([id, record]) => {
+    const placed = Object.fromEntries(Object.entries(merged).map(([id, given]) => {
+        // The record's `why` is what the platform keeps as `reason`.
+        const why = given.why;
+        // The run that proved it, under the name the platform reads (it does not read `provenBy`).
+        const run = given.provenBy?.runId;
+        const record = {
+            ...given,
+            ...('string' === typeof why && 0 < why.length ? { reason: why.slice(0, MAX_REASON) } : {}),
+            ...('string' === typeof run && 0 < run.length ? { provedBy: run } : {}),
+        };
         const held = record;
         if ('string' === typeof held.subject && held.subject.length > 0)
             return [id, record];
@@ -170,7 +178,8 @@ export function diskSource(reticleRoot) {
         runs: () => readJsonDir(join(reticleRoot, ReticleDir.RUNS_SUBDIR))
             .map((payload) => {
             const id = payload?.runId;
-            return 'string' === typeof id ? { runId: id, payload } : undefined;
+            // The prompt context leaves the machine only when the project opted in.
+            return 'string' === typeof id ? { runId: id, payload: shareableRun(payload) } : undefined;
         })
             // A run artifact with no id cannot be diffed against the server's list, so sending it would
             // mean re-sending it every cycle forever. Dropped rather than uploaded repeatedly.
@@ -181,6 +190,18 @@ export function diskSource(reticleRoot) {
         capsules: () => readJsonDir(join(reticleRoot, ReticleDir.CAPSULES_SUBDIR)),
         // Intent is the only derived record that is no longer one file. See readIntent.
         derived: (kind) => 'intent' === kind ? readIntent(reticleRoot) : readJson(join(reticleRoot, DERIVED_FILE[kind])),
+        // The file name comes from a run artifact on disk, so it is held to one segment of the run's
+        // own directory before it is read.
+        screenshot: (runId, file) => {
+            try {
+                if (basename(file) !== file)
+                    return undefined;
+                return new Uint8Array(readFileSync(join(stepShotDir(reticleRoot, runId), file)));
+            }
+            catch {
+                return undefined;
+            }
+        },
     };
 }
 /** What the cycle writes back into `.reticle/`. */

package/dist/memory/cloud/sync-screenshots.d.ts

@@ -0,0 +1,32 @@
+/** This machine's record of what went up, kept in `.reticle/cloud-state.json`. */
+export interface ScreenshotSyncState {
+    /** Per run, `seq:sha256` of every screenshot the platform holds or refused for good. */
+    sentScreenshots?: Record<string, string[]>;
+    /** Runs whose screenshots an older platform could not take. Kept local, never offered again. */
+    screenshotsHeldLocal?: string[];
+}
+export interface ScreenshotSyncDeps {
+    /** Every run on disk, with the payload the sync just sent. */
+    runs: ReadonlyArray<{
+        runId: string;
+        payload: unknown;
+    }>;
+    /** Whether the platform holds this run now. */
+    accepted: (runId: string) => boolean;
+    /** One image from the run's directory, or undefined when it is gone. */
+    readImage: (runId: string, file: string) => Uint8Array | undefined;
+    state: ScreenshotSyncState;
+    /** POST a JSON body to a path on the platform, with the sync's own credentials. */
+    post: (path: string, body: string) => Promise<{
+        status: number;
+        text: string;
+    }>;
+}
+export interface ScreenshotSyncResult {
+    sent: number;
+    state: ScreenshotSyncState;
+    /** Why this cycle stopped early, when it did. Kept local; the next cycle tries again. */
+    error?: string;
+}
+/** Send what is owed. Never throws; the record is bounded by the runs still on disk. */
+export declare function syncScreenshots(deps: ScreenshotSyncDeps): Promise<ScreenshotSyncResult>;