@reticlehq/server 3.5.0 → 3.7.0

package/dist/memory/cloud/cloud-config.d.ts

@@ -26,6 +26,11 @@ interface SyncPolicy {
      * the bug happen again, and a defect nobody else can reproduce is a defect nobody else can fix.
      */
     capsules: boolean;
+    /**
+     * Push each run's step screenshots after the run. Follows `runs` when the link does not say:
+     * a project that keeps its runs local has not agreed to send pictures of its pages either.
+     */
+    screenshots: boolean;
 }
 /** Where a verification actually executes. Reserved for the hosted-runner path; default local. */
 export declare const VerifyMode: {
@@ -40,8 +45,12 @@ export interface ProjectCloud {
     verify: VerifyMode;
     /** The cloud project id this project is linked to (for display/logging); null when env-fallback. */
     projectId: string | null;
+    /** The link as one key, cloud + workspace + project (`credentialSlot`); absent when env-fallback. */
+    link?: string;
     /** Why `config` is null, in words a person can act on. Absent when attached. */
     reason?: string;
+    /** Attached, but not with the key the caller exported: said, never silent. */
+    note?: string;
 }
 /** Look up the API key for a cloud project id in the user credentials map. */
 /**
@@ -77,7 +86,19 @@ export declare function resolveProjectCloud(fs: FileSystemPort, reticleRoot: str
  * three lines somewhere they belong. The harness reads it so a machine that has run `reticle link`
  * needs no exported key — see `withLinkedCredential`.
  */
-export declare const linkedCloudPort: (fs: FileSystemPort, reticleRoot: string, homeDir: string, env: NodeJS.ProcessEnv) => () => Promise<CloudConfig | null>;
+export declare const linkedCloudPort: (fs: FileSystemPort, reticleRoot: string, homeDir: string, env: NodeJS.ProcessEnv) => (root?: string) => Promise<CloudConfig | null>;
+/**
+ * The API key a tab's own project resolves to, so a credential is only ever used for its own tabs.
+ * A tab whose project cannot be resolved has no key.
+ */
+export declare const sessionApiKeyPort: (fs: FileSystemPort, homeDir: string, env: NodeJS.ProcessEnv, rootOf: (id: string) => string) => (sessionId: string) => Promise<string | undefined>;
+/** The platform and key a tab's own project resolves to, or undefined when it is not linked. */
+export declare const sessionCloudPort: (fs: FileSystemPort, homeDir: string, env: NodeJS.ProcessEnv, rootOf: (id: string) => string) => (sessionId: string) => Promise<CloudConfig | undefined>;
+/**
+ * The credential for pushing RUNS, or null when this project opted out with `sync.runs: false`.
+ * `reticle verify` used the port above and pushed its run and progress regardless of the opt-out.
+ */
+export declare const linkedRunsCloudPort: (fs: FileSystemPort, reticleRoot: string, homeDir: string, env: NodeJS.ProcessEnv) => () => Promise<CloudConfig | null>;
 /**
  * The environment with this project's resolved credential written into it, for the readers that
  * take an env record (the panel's model config and harness switch). Handed `process.env` alone,

package/dist/memory/cloud/cloud-config.js

@@ -17,7 +17,13 @@ import { resolveCloudConfig } from './cloud-sync.js';
 export const CLOUD_LINK_FILE = ReticleDir.CLOUD_LINK_FILE;
 /** `~/.reticle/credentials.json` — the user's per-cloud-project API keys (the only secret). */
 export const CREDENTIALS_FILE = 'credentials.json';
-const DEFAULT_SYNC_POLICY = { runs: true, memory: true, flows: true, capsules: true };
+const DEFAULT_SYNC_POLICY = {
+    runs: true,
+    memory: true,
+    flows: true,
+    capsules: true,
+    screenshots: true,
+};
 /** Where a verification actually executes. Reserved for the hosted-runner path; default local. */
 export const VerifyMode = { LOCAL: 'local', SERVER: 'server' };
 const asBool = (v, fallback) => ('boolean' === typeof v ? v : fallback);
@@ -51,6 +57,7 @@ function parseLink(raw) {
             memory: asBool(sync.memory, DEFAULT_SYNC_POLICY.memory),
             flows: asBool(sync.flows, DEFAULT_SYNC_POLICY.flows),
             capsules: asBool(sync.capsules, DEFAULT_SYNC_POLICY.capsules),
+            screenshots: asBool(sync.screenshots, asBool(sync.runs, DEFAULT_SYNC_POLICY.screenshots)),
         },
         verify: o.verify === VerifyMode.SERVER ? VerifyMode.SERVER : VerifyMode.LOCAL,
     };
@@ -135,7 +142,7 @@ export async function resolveProjectCloud(fs, reticleRoot, homeDir, env) {
             verify: VerifyMode.LOCAL,
             projectId: null,
             ...(null === config
-                ? { reason: 'cloud not attached here: run `reticle link`, or set RETICLE_API_KEY' }
+                ? { reason: 'cloud not attached here: run `reticle connect`, or set RETICLE_API_KEY' }
                 : {}),
         };
     }
@@ -144,6 +151,7 @@ export async function resolveProjectCloud(fs, reticleRoot, homeDir, env) {
         memory: link.sync.memory ?? DEFAULT_SYNC_POLICY.memory,
         flows: link.sync.flows ?? DEFAULT_SYNC_POLICY.flows,
         capsules: link.sync.capsules ?? DEFAULT_SYNC_POLICY.capsules,
+        screenshots: link.sync.screenshots ?? DEFAULT_SYNC_POLICY.screenshots,
     };
     const stored = credentialFor(await readJson(fs, join(homeDir, ReticleDir.ROOT, CREDENTIALS_FILE)), link.projectId, link.url, link.orgId);
     /*
@@ -161,16 +169,22 @@ export async function resolveProjectCloud(fs, reticleRoot, homeDir, env) {
         ? undefined
         : fromEnv !== null
             ? `this repo is linked to ${linkedUrl}, and RETICLE_API_KEY is set for ${fromEnv.url}: ` +
-                `set RETICLE_CLOUD_URL=${linkedUrl} to use that key here, or run \`reticle login\` for it`
+                `set RETICLE_CLOUD_URL=${linkedUrl} to use that key here, or run \`reticle connect\` for it`
             : `this repo is linked to ${linkedUrl}, and this machine has no key for it: run ` +
-                '`reticle login`, or set RETICLE_API_KEY' +
+                '`reticle connect`, or set RETICLE_API_KEY' +
                 (DEFAULT_PLATFORM_URL === linkedUrl ? '' : ` with RETICLE_CLOUD_URL=${linkedUrl}`);
+    const note = stored !== null && fromEnv !== null && fromEnv.apiKey !== stored
+        ? `RETICLE_API_KEY is set, but this repo uses the key \`reticle connect\` stored for it: ` +
+            'a stored key wins over the environment, so the exported key was not used'
+        : undefined;
     return {
         config,
         policy,
         verify: link.verify,
         projectId: link.projectId,
+        link: credentialSlot(link.url, link.projectId, link.orgId),
         ...(reason === undefined ? {} : { reason }),
+        ...(note === undefined ? {} : { note }),
     };
 }
 /**
@@ -181,7 +195,22 @@ export async function resolveProjectCloud(fs, reticleRoot, homeDir, env) {
  * three lines somewhere they belong. The harness reads it so a machine that has run `reticle link`
  * needs no exported key — see `withLinkedCredential`.
  */
-export const linkedCloudPort = (fs, reticleRoot, homeDir, env) => async () => (await resolveProjectCloud(fs, reticleRoot, homeDir, env)).config;
+export const linkedCloudPort = (fs, reticleRoot, homeDir, env) => async (root) => (await resolveProjectCloud(fs, root ?? reticleRoot, homeDir, env)).config;
+/**
+ * The API key a tab's own project resolves to, so a credential is only ever used for its own tabs.
+ * A tab whose project cannot be resolved has no key.
+ */
+export const sessionApiKeyPort = (fs, homeDir, env, rootOf) => async (sessionId) => (await sessionCloudPort(fs, homeDir, env, rootOf)(sessionId))?.apiKey;
+/** The platform and key a tab's own project resolves to, or undefined when it is not linked. */
+export const sessionCloudPort = (fs, homeDir, env, rootOf) => async (sessionId) => (await resolveProjectCloud(fs, rootOf(sessionId), homeDir, env)).config ?? undefined;
+/**
+ * The credential for pushing RUNS, or null when this project opted out with `sync.runs: false`.
+ * `reticle verify` used the port above and pushed its run and progress regardless of the opt-out.
+ */
+export const linkedRunsCloudPort = (fs, reticleRoot, homeDir, env) => async () => {
+    const cloud = await resolveProjectCloud(fs, reticleRoot, homeDir, env);
+    return cloud.policy.runs ? cloud.config : null;
+};
 /**
  * The environment with this project's resolved credential written into it, for the readers that
  * take an env record (the panel's model config and harness switch). Handed `process.env` alone,

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

@@ -1,13 +1,3 @@
-/**
- * Optional cloud sync for saved flows. "Logged in" here means the two cloud env vars are set (written by
- * `reticle login` later; settable by hand today): the hosted URL and an API key from the Reticle
- * dashboard. When present, a freshly-saved flow is pushed to `POST /v1/flows` so the team's regression
- * suite lives in the cloud — surviving refactors and runnable in CI. When absent, sync is a no-op and
- * everything stays 100% local (the "no phone-home" default: nothing leaves the machine unless you opt in).
- *
- * Sync is best-effort: a network failure NEVER fails the local save. The flow is already on disk; the
- * cloud copy is an enhancement, so a push error is logged and swallowed.
- */
 import { z } from 'zod';
 import { type FlowFile, type ReticleVerificationRun, type RunRecord, type VerifyProgressEvent } from '@reticlehq/core';
 /**
@@ -40,6 +30,19 @@ export declare function cloudFetch(url: string, init: {
     headers: Record<string, string>;
     body?: string;
 }, timeoutMs?: number): Promise<Response>;
+/**
+ * One sync request, status and body, under the same timeout every cloud call has. The sync daemon
+ * and `reticle sync` each called a bare `fetch`: one accepted-but-silent connection left the daemon's
+ * cycle running forever, and the dashboard stopped updating with nothing logged.
+ */
+export declare function syncRequest(url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body?: string;
+}, timeoutMs?: number): Promise<{
+    status: number;
+    text: string;
+}>;
 export declare const SyncOutcome: {
     readonly SYNCED: "synced";
     readonly SKIPPED: "skipped";
@@ -123,20 +126,20 @@ declare const ServerVerificationSchema: z.ZodObject<{
     }>, "many">;
     summary: z.ZodString;
 }, "strip", z.ZodTypeAny, {
-    verificationId: string;
-    verdict: string | null;
     flows: {
         status: string;
         name: string;
     }[];
-    summary: string;
-}, {
     verificationId: string;
     verdict: string | null;
+    summary: string;
+}, {
     flows: {
         status: string;
         name: string;
     }[];
+    verificationId: string;
+    verdict: string | null;
     summary: string;
 }>;
 export type ServerVerification = z.infer<typeof ServerVerificationSchema>;

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

@@ -8,8 +8,9 @@
  * Sync is best-effort: a network failure NEVER fails the local save. The flow is already on disk; the
  * cloud copy is an enhancement, so a push error is logged and swallowed.
  */
+import { shareableRun } from '@reticlehq/core/artifacts';
 import { z } from 'zod';
-import { VERIFY_PROGRESS_MAX_EVENTS, platformCredentialFrom, } from '@reticlehq/core';
+import { VERIFY_PROGRESS_MAX_EVENTS, platformCredentialFrom, flowJsonReplacer, } from '@reticlehq/core';
 /**
  * Env var names — the presence of BOTH is what "logged in" means for cloud sync.
  *
@@ -60,7 +61,7 @@ const TIMEOUT_ERROR_NAMES = new Set(['TimeoutError', 'AbortError']);
 const UNSENDABLE_HEADER_CHAR = /[^ -ÿ]/;
 /** Which knob holds the credential behind a header, so the error can name the thing to go and edit. */
 const CREDENTIAL_SOURCE = {
-    authorization: `${CloudEnv.KEY} (or the session from \`reticle login\`)`,
+    authorization: `${CloudEnv.KEY} (or the session from \`reticle connect\`)`,
 };
 /**
  * Refuse a request whose headers cannot be encoded, before it is sent.
@@ -97,6 +98,15 @@ export async function cloudFetch(url, init, timeoutMs = CLOUD_FETCH_TIMEOUT_MS)
         throw err;
     }
 }
+/**
+ * One sync request, status and body, under the same timeout every cloud call has. The sync daemon
+ * and `reticle sync` each called a bare `fetch`: one accepted-but-silent connection left the daemon's
+ * cycle running forever, and the dashboard stopped updating with nothing logged.
+ */
+export async function syncRequest(url, init, timeoutMs = CLOUD_FETCH_TIMEOUT_MS) {
+    const res = await cloudFetch(url, init, timeoutMs);
+    return { status: res.status, text: await res.text() };
+}
 export const SyncOutcome = {
     SYNCED: 'synced',
     SKIPPED: 'skipped',
@@ -116,7 +126,7 @@ export async function syncFlowToCloud(flow, config, projectId, fetchImpl) {
                 'content-type': 'application/json',
                 authorization: `Bearer ${config.apiKey}`,
             },
-            body: JSON.stringify(projectId === undefined ? { flow } : { flow, projectId }),
+            body: JSON.stringify(projectId === undefined ? { flow } : { flow, projectId }, flowJsonReplacer),
         });
         return res.ok
             ? { outcome: SyncOutcome.SYNCED, status: res.status }
@@ -143,7 +153,8 @@ export async function syncRunToCloud(run, config, fetchImpl) {
                 'content-type': 'application/json',
                 authorization: `Bearer ${config.apiKey}`,
             },
-            body: JSON.stringify(run),
+            // The prompt context leaves the machine only when the project opted in.
+            body: JSON.stringify(shareableRun(run)),
         });
         return res.ok
             ? { outcome: SyncOutcome.SYNCED, status: res.status }

package/dist/memory/cloud/harness-config.d.ts

@@ -1,3 +1,24 @@
+/**
+ * The harness switch, cached for a HUD that reads it inline.
+ *
+ * `fetchPlatformConfig` already asks the platform and parses the answer; this adds the one thing the
+ * impact snapshot needs and the drive path does not — a SYNCHRONOUS read. The snapshot is rebuilt
+ * dozens of times a session, the answer changes about as often as somebody opens a settings page,
+ * and a panel that awaited the network on every repaint would be a panel that stutters.
+ *
+ * Deliberately its own cache rather than a shared abstraction with the notices source:
+ * two callers with the same caching problem is not yet a pattern, and the day one of them needs a
+ * different staleness rule the shared version becomes the awkward one.
+ *
+ * Every failure answers `undefined`, which the HUD must read as "we have not heard" and render as NO
+ * control — never as "off". Showing a switch that cannot be honoured is worse than showing none.
+ *
+ * The loader arrives as a PORT rather than an import. Reading the platform lives in
+ * `features/harness`, and a cloud-memory file reaching into a feature is the reach the directory
+ * guard refuses — correctly, and for the same reason it refused the tool surface reaching the other
+ * way. Whoever wires the daemon owns both sides and can hand one to the other.
+ */
+import type { CreditKind } from '@reticlehq/core';
 /** Narrowed to what this file stores: the caller's own type is richer and irrelevant here. */
 export interface HarnessConfigView {
     provider: string;
@@ -5,8 +26,61 @@ export interface HarnessConfigView {
     harnessEntitled: boolean;
     /** Whether the platform holds a key for `provider`. Entitlement is not readiness — see the offer. */
     providerReady: boolean;
+    credits?: {
+        used: number;
+        limit: number;
+        kind?: CreditKind | undefined;
+        endsAt?: number;
+    };
+    /** The platform's coverage gate, when it sent one: the HUD prefers it to the local score. */
+    gate?: {
+        unlocked: boolean;
+        percent?: number;
+        reason?: string;
+        prompt?: string;
+    };
+    plan?: {
+        kind: CreditKind;
+        daysLeft?: number;
+        seats?: number;
+    };
+    harnessRuns?: number;
+    memoryEntries?: number;
 }
+/**
+ * The answer as the HUD is pushed it: the grant's end date becomes whole days left, counted on the
+ * daemon's clock (the HUD has none worth trusting for this). No end date, no days. Pure.
+ */
+export declare function configForHud(config: HarnessConfigView, now: number): Omit<HarnessConfigView, 'credits'> & {
+    credits?: {
+        used: number;
+        limit: number;
+        kind?: CreditKind | undefined;
+        daysLeft?: number;
+    };
+};
 export interface ConfigSource {
     read(): HarnessConfigView | undefined;
 }
-export declare function harnessConfigSource(load: () => Promise<HarnessConfigView | undefined>, now?: () => number): ConfigSource;
+export interface MutableConfigSource extends ConfigSource {
+    applyWrite(enabled: boolean): void;
+    recheck(): void;
+    subscribe(listener: () => void): () => void;
+    /** Re-read in the background, telling listeners only when the answer changed. */
+    poll(): void;
+}
+export declare function harnessConfigSource(load: () => Promise<HarnessConfigView | undefined>, now?: () => number): MutableConfigSource;
+export type ConfigsByRoot = (root: string) => MutableConfigSource;
+/**
+ * One live config source per project root, created on first ask; `onChange` hears every update.
+ *
+ * The platform read arrives as `load`, so this cache never reaches for the harness feature that
+ * performs it: the daemon, which owns both, joins them. It sat inline in `start` and `startDaemon`.
+ */
+export declare function harnessConfigsByRoot(load: (root: string) => Promise<HarnessConfigView | undefined>, onChange?: (root: string) => void): ConfigsByRoot;
+/**
+ * The HUD's harness switch, written to the platform with this project's credential. Nothing is
+ * awaited: an accepted write updates the cache at once, and a refused or failed one re-reads the
+ * platform so the switch springs back to the truth rather than staying where the user left it.
+ */
+export declare function applyHarnessSwitch(configs: ConfigsByRoot, root: string, enabled: boolean, envFor: () => Promise<Record<string, string | undefined>>): void;

package/dist/memory/cloud/harness-config.js

@@ -1,48 +1,69 @@
-/**
- * The harness switch, cached for a HUD that reads it inline.
- *
- * `fetchPlatformConfig` already asks the platform and parses the answer; this adds the one thing the
- * impact snapshot needs and the drive path does not — a SYNCHRONOUS read. The snapshot is rebuilt
- * dozens of times a session, the answer changes about as often as somebody opens a settings page,
- * and a panel that awaited the network on every repaint would be a panel that stutters.
- *
- * Deliberately the same shape as `harnessOfferSource` next door rather than a shared abstraction:
- * two callers with the same caching problem is not yet a pattern, and the day one of them needs a
- * different staleness rule the shared version becomes the awkward one.
- *
- * Every failure answers `undefined`, which the HUD must read as "we have not heard" and render as NO
- * control — never as "off". Showing a switch that cannot be honoured is worse than showing none.
- *
- * The loader arrives as a PORT rather than an import. Reading the platform lives in
- * `features/harness`, and a cloud-memory file reaching into a feature is the reach the directory
- * guard refuses — correctly, and for the same reason it refused the tool surface reaching the other
- * way. Whoever wires the daemon owns both sides and can hand one to the other.
- */
+import { writeHarnessSwitch } from './harness-switch.js';
 /** How long a cached answer is trusted. A person who just changed it expects the panel to notice. */
 const FRESH_MS = 30 * 1_000;
+const DAY_MS = 24 * 60 * 60 * 1_000;
+/**
+ * The answer as the HUD is pushed it: the grant's end date becomes whole days left, counted on the
+ * daemon's clock (the HUD has none worth trusting for this). No end date, no days. Pure.
+ */
+export function configForHud(config, now) {
+    if (config.credits === undefined)
+        return config;
+    const { endsAt, ...credits } = config.credits;
+    return {
+        ...config,
+        credits: endsAt === undefined
+            ? credits
+            : { ...credits, daysLeft: Math.max(0, Math.ceil((endsAt - now) / DAY_MS)) },
+    };
+}
 export function harnessConfigSource(load, now = () => Date.now()) {
     let cached;
     // `undefined` rather than 0: "never asked" is a different state from "asked at the epoch", and
     // conflating them made a source with an injected clock never take its first read.
     let fetchedAt;
     let inFlight = false;
+    let queuedRefresh = false;
+    let revision = 0;
+    /** Set for a background poll, so an unchanged answer does not repaint every HUD. */
+    let quiet = false;
+    const listeners = new Set();
+    const notify = () => {
+        for (const listener of listeners)
+            listener();
+    };
     const refresh = () => {
         if (inFlight)
             return;
         inFlight = true;
+        const startedAtRevision = revision;
         void load()
             .then((cfg) => {
             // A failed read keeps the LAST good answer rather than blanking the control mid-session:
             // one dropped request is not evidence that somebody changed their mind.
-            if (cfg !== undefined)
-                cached = cfg;
-            fetchedAt = now();
+            const before = JSON.stringify(cached);
+            if (startedAtRevision === revision) {
+                if (cfg !== undefined)
+                    cached = cfg;
+                fetchedAt = now();
+            }
+            // A poll that learned nothing new repaints nothing; anything else is said at once.
+            if (!quiet || before !== JSON.stringify(cached))
+                notify();
+            quiet = false;
         })
             .catch(() => {
-            fetchedAt = now();
+            if (startedAtRevision === revision)
+                fetchedAt = now();
+            quiet = false;
+            notify();
         })
             .finally(() => {
             inFlight = false;
+            if (queuedRefresh) {
+                queuedRefresh = false;
+                refresh();
+            }
         });
     };
     // Asked at construction, not first read: the daemon pushes a snapshot the instant a session
@@ -54,5 +75,75 @@ export function harnessConfigSource(load, now = () => Date.now()) {
                 refresh();
             return cached;
         },
+        applyWrite(enabled) {
+            revision += 1;
+            if (cached !== undefined)
+                cached = { ...cached, harnessEnabled: enabled };
+            fetchedAt = now();
+            notify();
+            if (cached === undefined) {
+                if (inFlight)
+                    queuedRefresh = true;
+                else
+                    refresh();
+            }
+        },
+        recheck() {
+            notify(); // Roll back an optimistic HUD switch immediately, even if the GET is slow.
+            if (inFlight)
+                queuedRefresh = true;
+            else
+                refresh();
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        poll() {
+            if (inFlight)
+                return;
+            quiet = true;
+            refresh();
+        },
+    };
+}
+/**
+ * One live config source per project root, created on first ask; `onChange` hears every update.
+ *
+ * The platform read arrives as `load`, so this cache never reaches for the harness feature that
+ * performs it: the daemon, which owns both, joins them. It sat inline in `start` and `startDaemon`.
+ */
+export function harnessConfigsByRoot(load, onChange) {
+    const sources = new Map();
+    return (root) => {
+        let source = sources.get(root);
+        if (source === undefined) {
+            source = harnessConfigSource(() => load(root));
+            if (onChange !== undefined) {
+                source.subscribe(() => onChange(root));
+                // The switch can be flipped anywhere: the console, another tab, the API. A HUD that only
+                // learned of it on its next tool call showed Harness ON over a drive that had stopped.
+                const live = source;
+                setInterval(() => live.poll(), FRESH_MS).unref();
+            }
+            sources.set(root, source);
+        }
+        return source;
     };
 }
+/**
+ * The HUD's harness switch, written to the platform with this project's credential. Nothing is
+ * awaited: an accepted write updates the cache at once, and a refused or failed one re-reads the
+ * platform so the switch springs back to the truth rather than staying where the user left it.
+ */
+export function applyHarnessSwitch(configs, root, enabled, envFor) {
+    void envFor()
+        .then((env) => writeHarnessSwitch(env, enabled))
+        .then((saved) => {
+        if (saved)
+            configs(root).applyWrite(enabled);
+        else
+            configs(root).recheck();
+    })
+        .catch(() => configs(root).recheck());
+}

package/dist/memory/cloud/hud-notices-source.d.ts

@@ -0,0 +1,21 @@
+import { type HudNoticeEntry } from '@reticlehq/core/hud';
+/**
+ * The largest body the daemon will read or keep. The real file is a few hundred bytes; anything near
+ * this is not a notices file, and the cache on disk must not grow with whatever the network sends.
+ */
+export declare const MAX_NOTICES_BODY_BYTES: number;
+export type NoticesLoad = (url: string, etag: string | undefined) => Promise<{
+    status: number;
+    etag?: string | undefined;
+    body?: string | undefined;
+}>;
+export interface NoticesSource {
+    /** The entries this daemon knows, unfiltered. Never throws, never waits. */
+    read(): HudNoticeEntry[];
+}
+export declare function hudNoticesSource(opts: {
+    cacheFile: string;
+    now?: () => number;
+    load?: NoticesLoad;
+    url?: string;
+}): NoticesSource;

package/dist/memory/cloud/hud-notices-source.js

@@ -0,0 +1,128 @@
+/**
+ * The HUD rail's notices, as the daemon keeps them.
+ *
+ * Read synchronously (the snapshot is rebuilt many times a session), served from a disk cache that
+ * survives restarts, and revalidated in the background with the stored ETag, so an unchanged file
+ * costs a 304 and no body. A failed or garbled refresh keeps the last good copy: the rail is
+ * marketing, and nothing about it may block or break a session. See core `hud-notices.ts`.
+ */
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { ReticleEnv } from '@reticlehq/core';
+import { HUD_NOTICES_URL, NOTICES_FILE_VERSION, parseHudNotices, } from '@reticlehq/core/hud';
+/** How long a copy is trusted before it is revalidated. Notices change over days, not minutes. */
+const FRESH_MS = 6 * 60 * 60 * 1_000;
+const TIMEOUT_MS = 5_000;
+/**
+ * The largest body the daemon will read or keep. The real file is a few hundred bytes; anything near
+ * this is not a notices file, and the cache on disk must not grow with whatever the network sends.
+ */
+export const MAX_NOTICES_BODY_BYTES = 64 * 1_024;
+/** Overrides the notices URL: self-hosting, staging, tests. */
+const NOTICES_URL_ENV = 'RETICLE_HUD_NOTICES_URL';
+/**
+ * The same opt-outs telemetry honours. The notices file carries nothing about anybody, but it is a
+ * request to reticle.sh, and somebody who switched Reticle's outbound calls off asked for none.
+ */
+function outboundOff(env) {
+    const telemetry = (env[ReticleEnv.TELEMETRY] ?? '').toLowerCase();
+    const dnt = env[ReticleEnv.DO_NOT_TRACK];
+    return (['0', 'false', 'off'].includes(telemetry) ||
+        ('string' === typeof dnt && dnt !== '' && dnt !== '0'));
+}
+const defaultLoad = async (url, etag) => {
+    const res = await fetch(url, {
+        headers: etag === undefined ? {} : { 'if-none-match': etag },
+        signal: AbortSignal.timeout(TIMEOUT_MS),
+    });
+    return {
+        status: res.status,
+        etag: res.headers.get('etag') ?? undefined,
+        body: 304 === res.status ? undefined : await res.text(),
+    };
+};
+function readCache(path) {
+    try {
+        const raw = JSON.parse(readFileSync(path, 'utf8'));
+        if ('object' !== typeof raw || null === raw)
+            return undefined;
+        const record = raw;
+        const fetchedAt = record['fetchedAt'];
+        const etag = record['etag'];
+        return {
+            fetchedAt: 'number' === typeof fetchedAt ? fetchedAt : 0,
+            ...('string' === typeof etag ? { etag } : {}),
+            file: record['file'],
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+function writeCache(path, cached) {
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, JSON.stringify(cached));
+    }
+    catch {
+        /* a cache that cannot be written is a fetch next time, not an error */
+    }
+}
+export function hudNoticesSource(opts) {
+    const now = opts.now ?? (() => Date.now());
+    const load = opts.load ?? defaultLoad;
+    const url = opts.url ?? process.env[NOTICES_URL_ENV] ?? HUD_NOTICES_URL;
+    let cached = readCache(opts.cacheFile);
+    let entries = cached === undefined ? [] : parseHudNotices(cached.file);
+    let inFlight = false;
+    let askedAt;
+    const refresh = () => {
+        inFlight = true;
+        askedAt = now();
+        void load(url, cached?.etag)
+            .then((answer) => {
+            if (304 === answer.status && cached !== undefined) {
+                cached = { ...cached, fetchedAt: now() };
+                writeCache(opts.cacheFile, cached);
+                return;
+            }
+            if (200 !== answer.status || answer.body === undefined)
+                return;
+            if (MAX_NOTICES_BODY_BYTES < Buffer.byteLength(answer.body))
+                return;
+            let file;
+            try {
+                file = JSON.parse(answer.body);
+            }
+            catch {
+                return;
+            }
+            // An unreadable file keeps the last good notices rather than emptying the rail.
+            const parsed = parseHudNotices(file);
+            if (0 === parsed.length && 0 < entries.length)
+                return;
+            entries = parsed;
+            // The cache holds what VALIDATED, rebuilt from the schema's output, never the body itself:
+            // unknown fields and rejected entries in a network answer do not reach the disk.
+            cached = {
+                etag: answer.etag,
+                fetchedAt: now(),
+                file: { version: NOTICES_FILE_VERSION, notices: parsed },
+            };
+            writeCache(opts.cacheFile, cached);
+        })
+            .catch(() => undefined)
+            .finally(() => {
+            inFlight = false;
+        });
+    };
+    return {
+        read() {
+            const last = Math.max(cached?.fetchedAt ?? 0, askedAt ?? Number.NEGATIVE_INFINITY);
+            const stale = cached === undefined && askedAt === undefined ? true : FRESH_MS <= now() - last;
+            if (!inFlight && stale && !outboundOff(process.env))
+                refresh();
+            return entries;
+        },
+    };
+}