@reticlehq/server 3.6.0 → 3.7.0

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

@@ -21,12 +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;
 /**
@@ -100,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),
@@ -119,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.
      *
@@ -143,14 +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);
                 // 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;
@@ -180,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,
@@ -195,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
@@ -253,6 +335,7 @@ export function startSyncDaemon(deps) {
             return undefined;
         }
         finally {
+            await refreshUnsynced().catch(() => undefined);
             running = false;
         }
     };
@@ -272,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);
@@ -320,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.js

@@ -12,7 +12,8 @@
  */
 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';
@@ -102,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 = {
@@ -139,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];
@@ -178,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>;

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

@@ -0,0 +1,105 @@
+/**
+ * The step screenshots of each run the platform has accepted, sent once each.
+ *
+ * A run goes up first, through the sync; its screenshots follow, one request per image, to
+ * `POST /v1/runs/:runId/screenshots` — only once the platform holds the run, because the endpoint
+ * answers 404 for a run it does not. What was sent is remembered by `seq:sha256`, like runs by hash,
+ * so a quiet cycle sends nothing.
+ *
+ * An OLDER platform has no such endpoint and answers 404 or 405. That run's screenshots stay on
+ * this machine and are not offered again: the alternative is one refused request per image on every
+ * cycle, forever. A newer platform picks up the next run's. Anything else that failed (the network,
+ * a 5xx) is simply retried next cycle.
+ */
+import { createHash } from 'node:crypto';
+import { RunScreenshotSchema, STEP_SCREENSHOT } from '@reticlehq/core';
+const SCREENSHOTS_PATH = (runId) => `/v1/runs/${encodeURIComponent(runId)}/screenshots`;
+const HTTP_CREATED = 201;
+const HTTP_OK = 200;
+/** An older platform: no route (404), or a route that takes no POST (405). */
+const NOT_THERE = new Set([404, 405]);
+/** Refused for good: too large (413), too many for one run (409). Retrying cannot change it. */
+const REFUSED_FOR_GOOD = new Set([409, 413]);
+/** The screenshots a run artifact lists, read defensively: a malformed entry is skipped. */
+function listed(payload) {
+    const raw = 'object' === typeof payload && null !== payload
+        ? payload['screenshots']
+        : undefined;
+    if (!Array.isArray(raw))
+        return [];
+    return raw.flatMap((entry) => {
+        const parsed = RunScreenshotSchema.safeParse(entry);
+        return parsed.success ? [parsed.data] : [];
+    });
+}
+const keyOf = (shot) => `${String(shot.seq)}:${shot.sha256}`;
+/** The upload body for one screenshot — the shape `ScreenshotUploadSchema` reads. */
+function bodyOf(shot, image) {
+    return {
+        seq: shot.seq,
+        file: shot.file,
+        ...(shot.step === undefined ? {} : { step: shot.step }),
+        tool: shot.tool,
+        ...(shot.checkId === undefined ? {} : { checkId: shot.checkId }),
+        source: shot.source,
+        width: shot.width,
+        height: shot.height,
+        sha256: shot.sha256,
+        jpeg: Buffer.from(image).toString('base64'),
+    };
+}
+/** Send what is owed. Never throws; the record is bounded by the runs still on disk. */
+export async function syncScreenshots(deps) {
+    const onDisk = new Set(deps.runs.map((run) => run.runId));
+    const sent = {};
+    for (const [runId, keys] of Object.entries(deps.state.sentScreenshots ?? {}))
+        if (onDisk.has(runId) && Array.isArray(keys))
+            sent[runId] = keys.filter((k) => 'string' === typeof k);
+    const heldLocal = new Set((deps.state.screenshotsHeldLocal ?? []).filter((id) => onDisk.has(id)));
+    const finish = (count, error) => ({
+        sent: count,
+        state: { sentScreenshots: sent, screenshotsHeldLocal: [...heldLocal] },
+        ...(error === undefined ? {} : { error }),
+    });
+    let count = 0;
+    try {
+        for (const run of deps.runs) {
+            if (heldLocal.has(run.runId) || !deps.accepted(run.runId))
+                continue;
+            const done = new Set(sent[run.runId] ?? []);
+            for (const shot of listed(run.payload)) {
+                if (done.has(keyOf(shot)))
+                    continue;
+                const image = deps.readImage(run.runId, shot.file);
+                // Gone (retention took it) or changed under its name: nothing true is left to send.
+                if (image === undefined || createHash('sha256').update(image).digest('hex') !== shot.sha256)
+                    continue;
+                const markDone = () => {
+                    done.add(keyOf(shot));
+                    sent[run.runId] = [...done];
+                };
+                if (image.byteLength > STEP_SCREENSHOT.MAX_BYTES) {
+                    markDone();
+                    continue;
+                }
+                const res = await deps.post(SCREENSHOTS_PATH(run.runId), JSON.stringify(bodyOf(shot, image)));
+                if (HTTP_CREATED === res.status || HTTP_OK === res.status) {
+                    markDone();
+                    count += 1;
+                }
+                else if (NOT_THERE.has(res.status)) {
+                    heldLocal.add(run.runId);
+                    return finish(count, `screenshots ${String(res.status)}: this platform does not take screenshots yet, so run ${run.runId}'s stay on this machine`);
+                }
+                else if (REFUSED_FOR_GOOD.has(res.status))
+                    markDone();
+                else
+                    return finish(count, `screenshots ${String(res.status)}: ${res.text.slice(0, 200)}`);
+            }
+        }
+    }
+    catch (error) {
+        return finish(count, error instanceof Error ? error.message : String(error));
+    }
+    return finish(count);
+}

package/dist/memory/cloud/unsynced-roots.d.ts

@@ -0,0 +1,47 @@
+export interface UnsyncedRoot {
+    root: string;
+    /** Runs on disk the platform has not accepted. */
+    runs: number;
+    /** Flows on disk nothing will send: see `unsentFlowCount`. */
+    flows: number;
+    /** Whether this folder holds a link. False is the case nothing will ever send. */
+    linked: boolean;
+    /**
+     * The project it belongs to: the linked one, else the id its `.reticle.json` names. A machine
+     * reports every folder to each workspace it is linked to; this is how a board keeps only its own.
+     */
+    projectId?: string;
+}
+/**
+ * Run files in `root` the platform never accepted. Ids only — a run file is named by its id — so
+ * this costs a directory listing, never a payload read. Never throws.
+ */
+export declare function unsentRunCount(root: string): number;
+/**
+ * Flows in `root` that will not reach the platform: all of them when nothing sends them (the root is
+ * not linked, has no key for its host, or has flow sync switched off), else the ones the platform
+ * refused. A flow waiting on a root that does send them is not counted: a save wakes the next cycle.
+ * Never throws.
+ */
+export declare function unsentFlowCount(root: string, sendsFlows: boolean): number;
+/**
+ * Every root here with runs or flows the platform does not have. Roots are deduped; order is kept.
+ * `sendsFlows` defaults to `isLinked`: a linked root sends its flows unless flow sync is off.
+ */
+export declare function unsyncedRoots(roots: readonly string[], isLinked: (root: string) => Promise<boolean>, sendsFlows?: (root: string) => Promise<boolean>): Promise<UnsyncedRoot[]>;
+/**
+ * The buckets under `~/.reticle/unmatched/` — evidence no project claimed, which nothing sends. After
+ * the first warning nothing named them again: not `status`, not `connect`, not the dashboard's
+ * unsent list. Never throws.
+ */
+export declare function unmatchedRoots(home: string): string[];
+/** The project a `.reticle` folder belongs to: where a person runs the command that sends it. */
+export declare function projectFolderOf(root: string): string;
+/** One line a person can act on: where the runs are, and the command that sends them. */
+export declare function describeUnsynced(entry: UnsyncedRoot, from: string): string;
+/**
+ * The unsent folders as a command's few lines: every unclaimed bucket in one (they all need the same
+ * thing, and `reticle connect` printed ninety near-identical lines of them before "Connected"), the
+ * rest one by one up to a handful, then a count and where the full list is.
+ */
+export declare function describeUnsyncedBriefly(entries: readonly UnsyncedRoot[], from: string): string[];

package/dist/memory/cloud/unsynced-roots.js

@@ -0,0 +1,166 @@
+/**
+ * `.reticle` folders whose runs never reached the platform, and why.
+ *
+ * The daemon skipped every root without a link and said nothing: one repo held 31 runs nobody sent
+ * while the log repeated `reticle_cloud_unlinked` about a different folder. Counted here, from run
+ * ids on disk against the ids the platform accepted, so `reticle sync`, `doctor`, the HUD and the
+ * platform report can each name the folder and the one command that fixes it.
+ */
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { basename, dirname, join, relative, sep } from 'node:path';
+import { ReticleDir } from '@reticlehq/core';
+import { DRIVE_RECORD_SUFFIX, UNMATCHED_SUBDIR, isUnmatchedRoot, } from '../project/dir/reticle-dir.js';
+import { diskSource, readCloudState } from './sync-disk.js';
+/** The project's own config, beside its `.reticle` folder. */
+const PROJECT_CONFIG = '.reticle.json';
+/** `projectId` out of a JSON file, or undefined. Never throws. */
+function projectIdIn(path) {
+    try {
+        const id = JSON.parse(readFileSync(path, 'utf8'))?.['projectId'];
+        return 'string' === typeof id && 0 < id.length ? id : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The project a `.reticle` folder belongs to, as the platform keys it. */
+function projectOfRoot(root) {
+    return (projectIdIn(join(root, ReticleDir.CLOUD_LINK_FILE)) ??
+        projectIdIn(join(projectFolderOf(root), PROJECT_CONFIG)));
+}
+const RUN_SUFFIX = '.json';
+/** The folder the command is run from, named when it is the one the person is already in. */
+const HERE = 'this folder';
+/**
+ * Run files in `root` the platform never accepted. Ids only — a run file is named by its id — so
+ * this costs a directory listing, never a payload read. Never throws.
+ */
+export function unsentRunCount(root) {
+    try {
+        const dir = join(root, ReticleDir.RUNS_SUBDIR);
+        if (!existsSync(dir))
+            return 0;
+        const state = readCloudState(root);
+        const sent = new Set([...Object.keys(state.sentRunHashes ?? {}), ...(state.sentRunIds ?? [])]);
+        // Made before the folder was linked here: held for `--move-history`, so not waiting for a sync.
+        const linkedAt = state.linkedAt;
+        const heldBack = (file) => {
+            if (linkedAt === undefined)
+                return false;
+            try {
+                const at = JSON.parse(readFileSync(join(dir, file), 'utf8'))
+                    .createdAt;
+                return !('number' === typeof at && at >= linkedAt);
+            }
+            catch {
+                return false;
+            }
+        };
+        return readdirSync(dir)
+            .filter((file) => file.endsWith(RUN_SUFFIX) && !file.endsWith(DRIVE_RECORD_SUFFIX))
+            .filter((file) => !sent.has(file.slice(0, -RUN_SUFFIX.length)) && !heldBack(file)).length;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Flows in `root` that will not reach the platform: all of them when nothing sends them (the root is
+ * not linked, has no key for its host, or has flow sync switched off), else the ones the platform
+ * refused. A flow waiting on a root that does send them is not counted: a save wakes the next cycle.
+ * Never throws.
+ */
+export function unsentFlowCount(root, sendsFlows) {
+    try {
+        if (!sendsFlows)
+            return diskSource(root).flows().length;
+        return readCloudState(root).refusedSets?.flow?.count ?? 0;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Every root here with runs or flows the platform does not have. Roots are deduped; order is kept.
+ * `sendsFlows` defaults to `isLinked`: a linked root sends its flows unless flow sync is off.
+ */
+export async function unsyncedRoots(roots, isLinked, sendsFlows = isLinked) {
+    const out = [];
+    for (const root of new Set(roots)) {
+        const runs = unsentRunCount(root);
+        const linked = await isLinked(root).catch(() => false);
+        const flows = unsentFlowCount(root, linked && (await sendsFlows(root).catch(() => false)));
+        if (0 === runs && 0 === flows)
+            continue;
+        const projectId = projectOfRoot(root);
+        out.push({ root, runs, flows, linked, ...(projectId === undefined ? {} : { projectId }) });
+    }
+    return out;
+}
+/**
+ * The buckets under `~/.reticle/unmatched/` — evidence no project claimed, which nothing sends. After
+ * the first warning nothing named them again: not `status`, not `connect`, not the dashboard's
+ * unsent list. Never throws.
+ */
+export function unmatchedRoots(home) {
+    const dir = join(home, ReticleDir.ROOT, UNMATCHED_SUBDIR);
+    try {
+        return readdirSync(dir, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => join(dir, entry.name));
+    }
+    catch {
+        return [];
+    }
+}
+/** The project a `.reticle` folder belongs to: where a person runs the command that sends it. */
+export function projectFolderOf(root) {
+    return ReticleDir.ROOT === basename(root) ? dirname(root) : root;
+}
+/** One line a person can act on: where the runs are, and the command that sends them. */
+export function describeUnsynced(entry, from) {
+    // Forward slashes on every platform, as the platform report writes `~/...`: one spelling of a
+    // folder whether it is read in a Windows terminal, the HUD or the dashboard.
+    const folder = projectFolderOf(entry.root);
+    const where = 0 === relative(from, folder).length ? HERE : relative(from, folder).split(sep).join('/');
+    const what = [
+        ...(0 < entry.runs ? [`${String(entry.runs)} run(s)`] : []),
+        ...(0 < entry.flows ? [`${String(entry.flows)} flow(s)`] : []),
+    ].join(' and ');
+    if (isUnmatchedRoot(entry.root)) {
+        return (`${what} in ${entry.root.split(sep).join('/')} are not on your dashboard: no project claimed ` +
+            'them — the checkout that made them shares its project id with another, or has none. They stay ' +
+            'on this machine; serve the app from the checkout that owns the id, or give this one its own, so new work reaches it');
+    }
+    // `connect`, not `link`: it signs in first when it has to, so it is the one command that works.
+    if (!entry.linked)
+        return `${what} in ${where} are not on your dashboard: run \`reticle connect\` there`;
+    // A linked root counts flows only when flow sync is off or the platform refused them.
+    return 0 < entry.flows
+        ? `${what} in ${where} are not on your dashboard: \`reticle config --flows on\` there if flow ` +
+            'sync is off; `reticle sync` names any the platform refused'
+        : `${what} in ${where} are waiting to be sent: run \`reticle sync\` there`;
+}
+/** Folders named one by one before the rest are counted. */
+const FOLDERS_SHOWN = 5;
+/**
+ * The unsent folders as a command's few lines: every unclaimed bucket in one (they all need the same
+ * thing, and `reticle connect` printed ninety near-identical lines of them before "Connected"), the
+ * rest one by one up to a handful, then a count and where the full list is.
+ */
+export function describeUnsyncedBriefly(entries, from) {
+    const unclaimed = entries.filter((entry) => isUnmatchedRoot(entry.root));
+    const claimed = entries.filter((entry) => !isUnmatchedRoot(entry.root));
+    if (entries.length <= FOLDERS_SHOWN)
+        return entries.map((entry) => describeUnsynced(entry, from));
+    const runs = unclaimed.reduce((sum, entry) => sum + entry.runs, 0);
+    const lines = claimed.slice(0, FOLDERS_SHOWN).map((entry) => describeUnsynced(entry, from));
+    if (0 < unclaimed.length)
+        lines.unshift(`${String(runs)} run(s) in ${String(unclaimed.length)} folders under ~/${ReticleDir.ROOT}/${UNMATCHED_SUBDIR} ` +
+            'are not on your dashboard: no project claimed them, so they stay on this machine');
+    const more = claimed.length - FOLDERS_SHOWN;
+    if (0 < more || 0 < unclaimed.length)
+        lines.push(`${0 < more ? `${String(more)} more folder(s) hold work not on your dashboard. ` : ''}` +
+            '`reticle doctor` lists every one');
+    return lines;
+}

package/dist/memory/impact/account-watch.d.ts

@@ -9,11 +9,26 @@
  * ponytail: stat polling (`fs.watchFile`), not `fs.watch`. It works on a file that does not exist
  * yet — the usual state of `cloud.json` before a link — and costs one stat per file per interval.
  */
+import type { ImpactSnapshot } from '@reticlehq/core';
 /** How often each watched file is stat'ed. A second reads as live to somebody switching windows. */
 export declare const ACCOUNT_WATCH_INTERVAL_MS = 1000;
+/** How often `onTick` re-reads what has no file to watch; the platform config is polled as often. */
+export declare const HUD_REFRESH_MS = 30000;
 export interface AccountFilesWatch {
     /** Start watching one file. Watching the same path twice is a no-op. */
     watch(path: string): void;
     close(): void;
 }
-export declare function watchAccountFiles(onChange: () => void, intervalMs?: number): AccountFilesWatch;
+export declare function watchAccountFiles(onChange: () => void, intervalMs?: number, 
+/** The rest of the platform's side of the HUD, which has no file to watch: run every 30s. */
+onTick?: () => void): AccountFilesWatch;
+/**
+ * Push a tab its impact snapshot, or, with `ifChanged`, only when it moved since this last pushed it.
+ *
+ * The daemon re-reads every tab on a timer so the platform's side of the HUD (sync status, runs on
+ * the dashboard, days left) reaches an idle tab without a tool call; resending an unchanged snapshot
+ * on every tick would repaint every HUD for nothing.
+ */
+export declare function pushIfMoved(tab: {
+    pushImpact(read: () => ImpactSnapshot | undefined, immediate: boolean): void;
+}, read: () => ImpactSnapshot | undefined, ifChanged: boolean): void;