@reticlehq/server 2.14.0 → 3.2.0

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

@@ -0,0 +1,359 @@
+/**
+ * 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 { VERIFY_PROGRESS_MAX_EVENTS, apiKeyFrom, } from '@reticlehq/core';
+/**
+ * Env var names — the presence of BOTH is what "logged in" means for cloud sync.
+ *
+ * `KEY` names the CURRENT spelling only. The previous one is still honoured, through `apiKeyFrom`
+ * below, which is the one place that knows there are two.
+ */
+export const CloudEnv = {
+    URL: 'RETICLE_CLOUD_URL',
+    KEY: 'RETICLE_API_KEY',
+};
+/** Paths the OSS server pushes to (match the cloud app's contract). */
+const CLOUD_FLOWS_PATH = '/v1/flows';
+const CLOUD_RUNS_PATH = '/v1/runs';
+const CLOUD_PROJECT_RUNS_PATH = '/v1/project/runs';
+const CLOUD_PROJECT_REGRESSION_PATH = '/v1/project/regression';
+const CLOUD_VERIFICATIONS_PATH = '/v1/verifications';
+const CLOUD_PROGRESS_PATH = '/v1/connect/progress';
+/** Resolve cloud credentials from the environment, or null when not logged in (sync disabled). */
+export function resolveCloudConfig(env) {
+    const url = env[CloudEnv.URL];
+    const apiKey = apiKeyFrom(env);
+    if (typeof url !== 'string' || 0 === url.length)
+        return null;
+    if (apiKey === undefined)
+        return null;
+    return { url: url.replace(/\/+$/, ''), apiKey };
+}
+/**
+ * Budget for a cloud call. Node's `fetch` has NO default timeout, so a connection that opens and then
+ * stalls never settles — and the caller `await`s it forever. In `reticle_flow_verify` that is an MCP
+ * tool call that never returns, and in `reticle cloud …` a terminal that prints nothing.
+ *
+ * One shared budget covers every call here: they are all small JSON request/response pairs against the
+ * same API, so there is nothing to tune per site. The ONE exception is the hosted verification submit,
+ * which blocks while a real browser runs the suite server-side — a normal response there is minutes,
+ * not seconds, so it gets its own (still bounded) budget rather than dragging the common one up.
+ */
+const CLOUD_FETCH_TIMEOUT_MS = 30_000;
+export const CLOUD_VERIFY_TIMEOUT_MS = 120_000;
+/** Names Node gives an abort: `AbortSignal.timeout` raises TimeoutError, an explicit abort AbortError. */
+const TIMEOUT_ERROR_NAMES = new Set(['TimeoutError', 'AbortError']);
+/**
+ * A header value `fetch` can actually send. Anything above U+00FF is not a valid ByteString.
+ *
+ * The one that happens in practice is an ellipsis. A dashboard masks a key as `rk_live_…` so it is
+ * never shown in full, somebody copies what they can SEE into `.env`, and the request dies deep
+ * inside undici with "Cannot convert argument to a ByteString because the character at index 15 has
+ * a value of 8230" — a byte offset into a header the user never wrote, naming no variable, no file
+ * and no fix.
+ */
+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\`)`,
+};
+/**
+ * Refuse a request whose headers cannot be encoded, before it is sent.
+ *
+ * Before dialling on purpose: a credential that cannot be encoded cannot succeed, so the round trip
+ * buys only a slower and less specific failure.
+ */
+function assertSendableHeaders(headers) {
+    for (const [name, value] of Object.entries(headers)) {
+        if (!UNSENDABLE_HEADER_CHAR.test(value))
+            continue;
+        const source = CREDENTIAL_SOURCE[name];
+        throw new Error(`the ${name} header carries a character that cannot be sent, which means the value is truncated — ` +
+            `a credential displayed masked as \`rk_live_…\` keeps that ellipsis when it is copied. ` +
+            `Paste the full value${source === undefined ? '' : ` into ${source}`}.`);
+    }
+}
+/**
+ * The fetch every cloud call goes through. Adds the abort signal, and turns the abort into a message
+ * that says what happened and what to do — a bare `AbortError` reaching a user or an agent is a riddle,
+ * and the agent-facing half of this product is judged on whether its errors are actionable.
+ */
+export async function cloudFetch(url, init, timeoutMs = CLOUD_FETCH_TIMEOUT_MS) {
+    assertSendableHeaders(init.headers);
+    try {
+        return await fetch(url, { ...init, signal: AbortSignal.timeout(timeoutMs) });
+    }
+    catch (err) {
+        if (err instanceof Error && TIMEOUT_ERROR_NAMES.has(err.name)) {
+            throw new Error(`Reticle request timed out after ${Math.round(timeoutMs / 1000)}s: ${init.method} ${url}. ` +
+                `The server accepted the connection but never answered. Check the network and ${CloudEnv.URL}, then retry — ` +
+                `verification works locally without cloud.`);
+        }
+        throw err;
+    }
+}
+export const SyncOutcome = {
+    SYNCED: 'synced',
+    SKIPPED: 'skipped',
+    FAILED: 'failed',
+};
+/**
+ * Push one flow to the cloud. `projectId` scopes it to this app. Returns a structured outcome; never
+ * throws — a failure is reported, not propagated, so the local save is authoritative.
+ */
+export async function syncFlowToCloud(flow, config, projectId, fetchImpl) {
+    if (null === config)
+        return { outcome: SyncOutcome.SKIPPED };
+    try {
+        const res = await fetchImpl(`${config.url}${CLOUD_FLOWS_PATH}`, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                authorization: `Bearer ${config.apiKey}`,
+            },
+            body: JSON.stringify(projectId === undefined ? { flow } : { flow, projectId }),
+        });
+        return res.ok
+            ? { outcome: SyncOutcome.SYNCED, status: res.status }
+            : { outcome: SyncOutcome.FAILED, status: res.status };
+    }
+    catch (err) {
+        return { outcome: SyncOutcome.FAILED, error: err instanceof Error ? err.message : String(err) };
+    }
+}
+/**
+ * Push one verification-run artifact to the cloud. This is what makes "runs recorded on the dashboard"
+ * real once a user shifts to the server: after `reticle verify` produces a run, it lands in the team's
+ * hosted history with its verdict. Same opt-in creds as flow sync — absent → no-op (stays local). The
+ * cloud's `POST /v1/runs` ingests the RAW artifact (validated by the same `@reticlehq/core` schema that
+ * built it), so the body is the run itself, not a wrapper. Best-effort: never throws, never blocks exit.
+ */
+export async function syncRunToCloud(run, config, fetchImpl) {
+    if (null === config)
+        return { outcome: SyncOutcome.SKIPPED };
+    try {
+        const res = await fetchImpl(`${config.url}${CLOUD_RUNS_PATH}`, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                authorization: `Bearer ${config.apiKey}`,
+            },
+            body: JSON.stringify(run),
+        });
+        return res.ok
+            ? { outcome: SyncOutcome.SYNCED, status: res.status }
+            : { outcome: SyncOutcome.FAILED, status: res.status };
+    }
+    catch (err) {
+        return { outcome: SyncOutcome.FAILED, error: err instanceof Error ? err.message : String(err) };
+    }
+}
+/**
+ * Push one project-memory RunRecord (a flow replay/verify outcome) to the cloud so the team's server-side
+ * regression history stays current: "did this development break a previously-passing flow?" is answered
+ * from these. Same opt-in creds as the others — absent → no-op (project.json stays the local source of
+ * truth). `projectId` scopes an org's multiple suites. Best-effort: never throws, never blocks the tool.
+ */
+export async function syncRunRecordToCloud(record, projectId, config, fetchImpl) {
+    if (null === config)
+        return { outcome: SyncOutcome.SKIPPED };
+    try {
+        const res = await fetchImpl(`${config.url}${CLOUD_PROJECT_RUNS_PATH}`, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                authorization: `Bearer ${config.apiKey}`,
+            },
+            body: JSON.stringify({
+                flowName: record.name,
+                status: record.status,
+                kind: record.kind,
+                summary: record.summary,
+                at: record.at,
+                ...(projectId === undefined ? {} : { projectId }),
+            }),
+        });
+        return res.ok
+            ? { outcome: SyncOutcome.SYNCED, status: res.status }
+            : { outcome: SyncOutcome.FAILED, status: res.status };
+    }
+    catch (err) {
+        return { outcome: SyncOutcome.FAILED, error: err instanceof Error ? err.message : String(err) };
+    }
+}
+/**
+ * Read the team's server-side regression report back down to the agent. This is the half that makes the
+ * system "agent-friendly across context loss": a fresh agent (new session, CI box, teammate's machine)
+ * whose local .reticle/project.json is empty can still ask the ONE tool it knows — reticle_project — and
+ * get the durable cloud memory of what's broken vs before. Returns the raw report (shape owned by the
+ * cloud), or null when not logged in / unreachable — so the caller degrades to local-only, never fails.
+ */
+export async function fetchProjectRegressionFromCloud(config, projectId, fetchImpl) {
+    if (null === config)
+        return null;
+    try {
+        const query = projectId === undefined ? '' : `?projectId=${encodeURIComponent(projectId)}`;
+        const res = await fetchImpl(`${config.url}${CLOUD_PROJECT_REGRESSION_PATH}${query}`, {
+            method: 'GET',
+            headers: { authorization: `Bearer ${config.apiKey}` },
+        });
+        return res.ok ? await res.json() : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The hosted runner's report, validated at the boundary (the full shape is owned by the cloud app). */
+const ServerVerificationSchema = z.object({
+    verificationId: z.string(),
+    verdict: z.string().nullable(),
+    flows: z.array(z.object({ name: z.string(), status: z.string() })),
+    summary: z.string(),
+});
+/**
+ * Delegate a verification to the hosted runner: submit the preview URL + flow names to `POST
+ * /v1/verifications` and read back the report. This is the `verify: 'server'` half of the per-project
+ * config — the WORK runs on the server (real browser pool, later), not the local machine. The server
+ * records the verification itself, so there is no separate run-push. Returns null when not attached or the
+ * submit fails, so the caller falls back to a local replay. Never throws.
+ */
+export async function submitServerVerification(body, config, fetchImpl) {
+    if (null === config)
+        return null;
+    try {
+        const res = await fetchImpl(`${config.url}${CLOUD_VERIFICATIONS_PATH}`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', authorization: `Bearer ${config.apiKey}` },
+            body: JSON.stringify(body),
+        });
+        if (!res.ok)
+            return null;
+        const parsed = ServerVerificationSchema.safeParse(await res.json());
+        return parsed.success ? parsed.data : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Narrate a run in flight to the dashboard.
+ *
+ * ## Why this exists
+ *
+ * Everything else here syncs a FINISHED artifact. That is the right shape for evidence and the wrong
+ * shape for the minutes a verification is actually running: a browser launches, flows replay one at
+ * a time, and until the run ends the dashboard has nothing to show but a spinner. A run that is
+ * working and a run that has died are indistinguishable for the whole of its duration, and somebody
+ * watching sat on exactly that ambiguity for fifteen minutes.
+ *
+ * ## Why it is batched
+ *
+ * One request per flow is one request per flow. A fifty-flow suite would open a hundred connections
+ * to say things that are only interesting in aggregate, so events accumulate and go out on a timer.
+ * Two seconds is well under the time a person waits before deciding a page is broken, and well over
+ * the time a fast flow takes — so a burst of quick replays becomes one request, not twenty.
+ *
+ * ## Why it can never matter
+ *
+ * Opt-in like every other cloud call (no credentials → no-op, nothing leaves the machine), and
+ * best-effort at every layer: a failed flush is dropped, never retried and never surfaced. This is
+ * narration. The run artifact is the record, it syncs separately, and nothing here is graded or
+ * allowed to influence a verdict or an exit code.
+ */
+export async function syncProgressToCloud(runId, events, config, fetchImpl) {
+    if (null === config)
+        return { outcome: SyncOutcome.SKIPPED };
+    if (0 === events.length)
+        return { outcome: SyncOutcome.SKIPPED };
+    try {
+        const res = await fetchImpl(`${config.url}${CLOUD_PROGRESS_PATH}`, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                authorization: `Bearer ${config.apiKey}`,
+            },
+            // Bounded on the way OUT as well as in the schema: a receiver that rejects an oversized batch
+            // would drop the whole window, and the newest events are the ones somebody is waiting on.
+            body: JSON.stringify({ runId, events: events.slice(-VERIFY_PROGRESS_MAX_EVENTS) }),
+        });
+        return res.ok
+            ? { outcome: SyncOutcome.SYNCED, status: res.status }
+            : { outcome: SyncOutcome.FAILED, status: res.status };
+    }
+    catch (err) {
+        return { outcome: SyncOutcome.FAILED, error: err instanceof Error ? err.message : String(err) };
+    }
+}
+/** How long events accumulate before a flush. See the batching note above. */
+export const PROGRESS_FLUSH_MS = 2_000;
+/**
+ * A listener that buffers progress and ships it on a timer.
+ *
+ * Returned with its own `flush` and `stop` so the caller can push the last events out when the run
+ * ends — otherwise the most interesting event of all, the one saying it finished, waits for a timer
+ * that is about to be cleared.
+ *
+ * The timer is `unref`'d where the runtime supports it: a narration timer must never be the reason a
+ * CLI process stays alive after its work is done.
+ */
+export function createProgressReporter(runId, config, fetchImpl, flushMs = PROGRESS_FLUSH_MS) {
+    /*
+     * The WHOLE window, re-sent each flush — not the events since the last one.
+     *
+     * The receiver REPLACES the row it keeps for a project rather than appending, because one row per
+     * project is what stops narration accumulating into a second, ungraded history of the run. A
+     * client that sent deltas against that would destroy its own story: each flush would overwrite the
+     * row with only the handful of events since the previous one, and a finished run would be
+     * represented by whatever its last two seconds happened to contain.
+     *
+     * Found by running a real verification and watching the dashboard freeze on flow 2 of 3.
+     *
+     * Re-sending is cheap and idempotent: the window is bounded, the events are tiny, and a replace is
+     * the same operation however many times it arrives. `dirty` keeps an unchanged window off the
+     * wire, so a run that has gone quiet stops posting rather than resending forever.
+     */
+    /* Named `accumulated`, not `window`: this is Node, and shadowing the global reads badly. */
+    const accumulated = [];
+    let dirty = false;
+    let timer = null;
+    const flush = async () => {
+        if (!dirty || 0 === accumulated.length)
+            return;
+        // Cleared BEFORE the await so a slow flush does not let the next tick send the same window
+        // again; a genuinely new event during the send re-sets it and the next tick picks it up.
+        dirty = false;
+        await syncProgressToCloud(runId, [...accumulated], config, fetchImpl).catch(() => undefined);
+    };
+    const start = () => {
+        if (null !== timer || null === config)
+            return;
+        timer = setInterval(() => void flush(), flushMs);
+        timer.unref?.();
+    };
+    return {
+        onProgress: (event) => {
+            if (null === config)
+                return; // not logged in: nothing is buffered and nothing is sent
+            // Bounded, keeping the NEWEST: they are the ones somebody is waiting on.
+            if (accumulated.length >= VERIFY_PROGRESS_MAX_EVENTS)
+                accumulated.shift();
+            accumulated.push(event);
+            dirty = true;
+            start();
+        },
+        flush,
+        stop: () => {
+            if (null !== timer)
+                clearInterval(timer);
+            timer = null;
+        },
+    };
+}

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

@@ -0,0 +1,10 @@
+/** Narrowed to what this file stores: the caller's own type is richer and irrelevant here. */
+export interface HarnessConfigView {
+    provider: string;
+    harnessEnabled: boolean;
+    harnessEntitled: boolean;
+}
+export interface ConfigSource {
+    read(): HarnessConfigView | undefined;
+}
+export declare function harnessConfigSource(load: () => Promise<HarnessConfigView | undefined>, now?: () => number): ConfigSource;

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

@@ -0,0 +1,58 @@
+/**
+ * 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.
+ */
+/** How long a cached answer is trusted. A person who just changed it expects the panel to notice. */
+const FRESH_MS = 30 * 1_000;
+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;
+    const refresh = () => {
+        if (inFlight)
+            return;
+        inFlight = true;
+        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();
+        })
+            .catch(() => {
+            fetchedAt = now();
+        })
+            .finally(() => {
+            inFlight = false;
+        });
+    };
+    // Asked at construction, not first read: the daemon pushes a snapshot the instant a session
+    // attaches, and on a page nobody drives that is the only push there will ever be.
+    refresh();
+    return {
+        read() {
+            if (fetchedAt === undefined || FRESH_MS <= now() - fetchedAt)
+                refresh();
+            return cached;
+        },
+    };
+}

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

@@ -0,0 +1,44 @@
+/**
+ * Whether this workspace has taken the three months of free harness, read by the thing that would
+ * advertise it.
+ *
+ * The HUD can only advertise honestly if it knows, and only the platform knows. This is the read —
+ * filed beside the other reads of the linked account rather than with the harness itself, because
+ * nothing that DRIVES needs it; the thing that needs it is the snapshot the HUD paints from. Same
+ * shape as the harness's own `platform-config.ts` and for the same reasons: it is INFORMATION, not a
+ * credential, so every failure answers `undefined`, which every caller must treat as "say nothing"
+ * rather than as "not claimed". An offline laptop must not start advertising something the person
+ * already owns.
+ *
+ * It is also SYNCHRONOUS at the point of use. The impact snapshot is built inline, dozens of times a
+ * session, and the answer changes about once per workspace lifetime, so a cache that refreshes in
+ * the background is the whole design: readers get what we last heard, and a stale answer is only
+ * ever stale in the safe direction — the card the person is looking at is the one they can act on.
+ */
+import { type HarnessOffer } from '@reticlehq/core';
+/** A GET, narrowed to what this file uses, so a test can answer it without a network. */
+export type OfferFetch = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    signal?: AbortSignal;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    text(): Promise<string>;
+}>;
+/** Ask the platform where this workspace stands. `undefined` means "no answer", never "not claimed". */
+export declare function fetchHarnessOffer(env: Record<string, string | undefined>, claimUrl: string | undefined, doFetch?: OfferFetch, timeoutMs?: number): Promise<HarnessOffer | undefined>;
+/** What the impact snapshot reads: the last answer, with a refresh kicked off when it goes stale. */
+export interface OfferSource {
+    read(): HarnessOffer | undefined;
+}
+/**
+ * A self-refreshing cache over the read above.
+ *
+ * Deliberately NOT a timer. A daemon that lives for days would otherwise hold an interval whose only
+ * job is to re-ask a question nobody is asking, and it would have to be torn down in a place that
+ * already has nine teardowns. Refreshing on a stale READ means the work only happens while somebody
+ * is actually looking, and the first read of a process — which is always stale — starts the fetch
+ * that the second read answers from.
+ */
+export declare function harnessOfferSource(env: Record<string, string | undefined>, claimUrl: () => string | undefined, now?: () => number, load?: (claim: string | undefined) => Promise<HarnessOffer | undefined>): OfferSource;

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

@@ -0,0 +1,146 @@
+/**
+ * Whether this workspace has taken the three months of free harness, read by the thing that would
+ * advertise it.
+ *
+ * The HUD can only advertise honestly if it knows, and only the platform knows. This is the read —
+ * filed beside the other reads of the linked account rather than with the harness itself, because
+ * nothing that DRIVES needs it; the thing that needs it is the snapshot the HUD paints from. Same
+ * shape as the harness's own `platform-config.ts` and for the same reasons: it is INFORMATION, not a
+ * credential, so every failure answers `undefined`, which every caller must treat as "say nothing"
+ * rather than as "not claimed". An offline laptop must not start advertising something the person
+ * already owns.
+ *
+ * It is also SYNCHRONOUS at the point of use. The impact snapshot is built inline, dozens of times a
+ * session, and the answer changes about once per workspace lifetime, so a cache that refreshes in
+ * the background is the whole design: readers get what we last heard, and a stale answer is only
+ * ever stale in the safe direction — the card the person is looking at is the one they can act on.
+ */
+import { ReticleEnv, apiKeyFrom } from '@reticlehq/core';
+const OFFER_PATH = '/v1/harness/offer';
+/** Same budget as the model-config read: a drive must never wait on an advert. */
+const TIMEOUT_MS = 2_000;
+/**
+ * How long a cached answer is trusted.
+ *
+ * A claim happens once. The only transition worth catching quickly is the one the person just made
+ * in another tab, and ten minutes is well inside the time it takes them to come back and look.
+ */
+const FRESH_MS = 10 * 60 * 1_000;
+/**
+ * Parse the platform's answer.
+ *
+ * The platform reports `null` for "never claimed" on the fields it has no value for; the wire
+ * contract says ABSENT. They are the same fact and the translation belongs here, at the edge,
+ * rather than in a HUD that would then need to know about two spellings of nothing.
+ */
+function parse(body, claimUrl) {
+    try {
+        const parsed = JSON.parse(body);
+        if ('object' !== typeof parsed || null === parsed)
+            return undefined;
+        const record = parsed;
+        const claimed = record['claimed'];
+        if ('boolean' !== typeof claimed)
+            return undefined;
+        const offer = { claimed };
+        const expiresAt = record['expiresAt'];
+        if ('number' === typeof expiresAt)
+            offer.expiresAt = expiresAt;
+        const days = record['daysRemaining'];
+        if ('number' === typeof days)
+            offer.daysRemaining = days;
+        // The one field that cannot be inferred from the others: a LAPSED claim reports `claimed:false`
+        // and `daysRemaining:0`, which is indistinguishable from never having claimed unless the
+        // platform's own answer about offerability is carried through.
+        const eligible = record['eligible'];
+        if ('boolean' === typeof eligible)
+            offer.eligible = eligible;
+        if (claimUrl !== undefined && 0 < claimUrl.length)
+            offer.claimUrl = claimUrl;
+        return offer;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Ask the platform where this workspace stands. `undefined` means "no answer", never "not claimed". */
+export async function fetchHarnessOffer(env, claimUrl, doFetch = (url, init) => fetch(url, init), timeoutMs = TIMEOUT_MS) {
+    const key = apiKeyFrom(env);
+    const host = env[ReticleEnv.CLOUD_URL];
+    if (key === undefined || 0 === key.length)
+        return undefined;
+    if (host === undefined || 0 === host.length)
+        return undefined;
+    const controller = new AbortController();
+    const timer = setTimeout(() => {
+        controller.abort();
+    }, timeoutMs);
+    try {
+        const res = await doFetch(`${host.replace(/\/+$/, '')}${OFFER_PATH}`, {
+            method: 'GET',
+            headers: { authorization: `Bearer ${key}` },
+            signal: controller.signal,
+        });
+        if (!res.ok)
+            return undefined;
+        return parse(await res.text(), claimUrl);
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * A self-refreshing cache over the read above.
+ *
+ * Deliberately NOT a timer. A daemon that lives for days would otherwise hold an interval whose only
+ * job is to re-ask a question nobody is asking, and it would have to be torn down in a place that
+ * already has nine teardowns. Refreshing on a stale READ means the work only happens while somebody
+ * is actually looking, and the first read of a process — which is always stale — starts the fetch
+ * that the second read answers from.
+ */
+export function harnessOfferSource(env, claimUrl, now = () => Date.now(), load = (claim) => fetchHarnessOffer(env, claim)) {
+    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;
+    const refresh = () => {
+        if (inFlight)
+            return;
+        inFlight = true;
+        void load(claimUrl())
+            .then((offer) => {
+            // A failed read keeps the LAST good answer rather than blanking the card mid-session: one
+            // dropped request is not evidence that the offer changed.
+            if (offer !== undefined)
+                cached = offer;
+            fetchedAt = now();
+        })
+            .catch(() => {
+            fetchedAt = now();
+        })
+            .finally(() => {
+            inFlight = false;
+        });
+    };
+    /*
+     * Asked once at construction, not first read.
+     *
+     * Measured in a browser: a daemon pushes the impact snapshot the INSTANT a session attaches, and
+     * on a page nobody drives that is the only push there will ever be. Refreshing on the first read
+     * meant that push always carried "we have not heard", the answer landed a moment later with
+     * nobody to tell, and the HUD showed nothing for the whole session. Starting the fetch when the
+     * daemon starts puts the answer in place before any page can connect.
+     */
+    refresh();
+    return {
+        read() {
+            if (fetchedAt === undefined || FRESH_MS <= now() - fetchedAt)
+                refresh();
+            return cached;
+        },
+    };
+}

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

@@ -0,0 +1,11 @@
+export type SwitchFetch = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body: string;
+    signal?: AbortSignal;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+}>;
+/** `true` when the platform accepted it. Callers use this for logging, never to block a person. */
+export declare function writeHarnessSwitch(env: Record<string, string | undefined>, enabled: boolean, doFetch?: SwitchFetch, timeoutMs?: number): Promise<boolean>;