@reticlehq/server 3.1.0 → 3.3.0

package/dist/language/flows/learned-sources.js

@@ -0,0 +1,84 @@
+/**
+ * Learn a flow step's source file from the element its anchor resolved to on a replay.
+ *
+ * A step recorded before the build stamped the app names no file, so a scoped re-verify cannot say
+ * which edits it covers. Every replay already asks the page for each anchor's element, and that
+ * element carries its stamp now: this records the answer at the one place every resolution passes
+ * through (the session's QUERY), rather than threading it through each step runner.
+ */
+import { ReticleCommand, asRecord, asString } from '@reticlehq/core';
+import { anchorQueryArgs } from './flow-step-runners.js';
+/** `src/Pay.tsx:12:4` or `src/Pay.tsx:12` → `{file, line}`; anything else is not a location. */
+export function parseCompactSource(value) {
+    const match = /^(.+?):(\d+)(?::\d+)?$/.exec(value);
+    const file = match?.[1];
+    const line = match?.[2];
+    if (file === undefined || line === undefined)
+        return undefined;
+    return { file, line: Number(line) };
+}
+function keyOf(args) {
+    if (args === undefined)
+        return undefined;
+    const by = asString(args['by']);
+    const value = asString(args['value']);
+    if (by === undefined || value === undefined)
+        return undefined;
+    return JSON.stringify([by, value, asString(args['name']) ?? null]);
+}
+/** The one element a query found, when exactly one was found and it carries a stamp. */
+function soleSource(result) {
+    const elements = asRecord(result)?.['elements'];
+    if (!Array.isArray(elements) || elements.length !== 1)
+        return undefined;
+    const source = asString(asRecord(elements[0])?.['source']);
+    return source === undefined ? undefined : parseCompactSource(source);
+}
+/** Wrap a replay session so every anchor QUERY that resolves to one stamped element is remembered. */
+export function recordingSources(inner) {
+    const sources = new Map();
+    const session = new Proxy(inner, {
+        // Bound to the target, never the proxy: a real Session keeps `#private` state, and a method
+        // called with the proxy as `this` throws reading it.
+        get(target, prop) {
+            if (prop !== 'command') {
+                const value = Reflect.get(target, prop, target);
+                return 'function' === typeof value ? value.bind(target) : value;
+            }
+            return async (name, args) => {
+                const result = await target.command(name, args);
+                const key = name === ReticleCommand.QUERY ? keyOf(args) : undefined;
+                const source = result.ok ? soleSource(result.result) : undefined;
+                if (key !== undefined && source !== undefined)
+                    sources.set(key, source);
+                return result;
+            };
+        },
+    });
+    return { session, sources };
+}
+function learnSteps(steps, sources) {
+    let changed = false;
+    const next = steps.map((step) => {
+        const nested = step.steps === undefined ? undefined : learnSteps(step.steps, sources);
+        const learned = step.source === undefined
+            ? sources.get(keyOf(anchorQueryArgs(step.anchor) ?? undefined) ?? '')
+            : undefined;
+        if (learned === undefined && nested?.changed !== true)
+            return step;
+        changed = true;
+        return {
+            ...step,
+            ...(learned === undefined ? {} : { source: learned }),
+            ...(nested === undefined ? {} : { steps: nested.steps }),
+        };
+    });
+    return { steps: next, changed };
+}
+/** The flow with every sourceless step given the file its anchor resolved to; undefined if none was. */
+export function withLearnedSources(flow, sources) {
+    if (0 === sources.size)
+        return undefined;
+    const { steps, changed } = learnSteps(flow.steps, sources);
+    return changed ? { ...flow, steps } : undefined;
+}

package/dist/language/flows/narrow-write.d.ts

@@ -1,4 +1,4 @@
-import { type FlowFile } from '@reticlehq/core';
+import { type ProjectId, type FlowFile } from '@reticlehq/core';
 import { type FlowResult } from './flow-result.js';
 /**
  * Change one thing about a saved flow, and write the same file that load resolved.
@@ -21,12 +21,12 @@ import { type FlowResult } from './flow-result.js';
  * every rule the document has ever been subject to.
  */
 export interface NarrowWritePort {
-    load: (name: string, projectId?: string) => Promise<FlowResult<FlowFile>>;
-    resolvePath: (name: string, projectId?: string) => Promise<string | null>;
+    load: (name: string, projectId?: ProjectId) => Promise<FlowResult<FlowFile>>;
+    resolvePath: (name: string, projectId?: ProjectId) => Promise<string | null>;
     write: (path: string, contents: string) => Promise<void>;
     serialize: (flow: FlowFile) => string;
 }
-export declare function changeInPlace<T>(port: NarrowWritePort, name: string, projectId: string | undefined, change: (flow: FlowFile) => {
+export declare function changeInPlace<T>(port: NarrowWritePort, name: string, projectId: ProjectId | undefined, change: (flow: FlowFile) => {
     next: FlowFile;
     value: T;
 }): Promise<FlowResult<T>>;

package/dist/language/flows/recording/recording-backtrack.d.ts

@@ -7,13 +7,6 @@
  * stop/save can warn instead of writing a flow that fails on the next click.
  */
 import { type ReticleEvent } from '@reticlehq/core';
-/**
- * The page a recording step sat on, comparable across path routers and hash routers.
- *
- * A startPath is stored as pathname+hash (`/#/search`); a ROUTE_CHANGE carries them separately.
- * Without this, every hash-router page compares as `/` and a backtrack is invisible.
- */
-export declare function recordingRouteOf(pathname: string, hash?: string): string;
 /**
  * Warn when the journey left a page and came back. Linear A→B→C is silent: that still cannot
  * replay either if a later click needs a previous page, but the reported failure is specifically

package/dist/language/flows/recording/recording-backtrack.js

@@ -17,7 +17,7 @@ function asString(value) {
  * A startPath is stored as pathname+hash (`/#/search`); a ROUTE_CHANGE carries them separately.
  * Without this, every hash-router page compares as `/` and a backtrack is invisible.
  */
-export function recordingRouteOf(pathname, hash = '') {
+function recordingRouteOf(pathname, hash = '') {
     const hashIdx = pathname.indexOf('#/');
     if (hashIdx >= 0) {
         return routePathOf(pathname.slice(0, hashIdx) || '/', pathname.slice(hashIdx));

package/dist/language/flows/recording/replay-halt.d.ts

@@ -12,7 +12,7 @@
  */
 import type { FlowStepResult } from '@reticlehq/core';
 /** Set on a replay that stopped early; omitted entirely otherwise, so a clean pass stays flat. */
-export interface ReplayHalt {
+interface ReplayHalt {
     /** Index of the step that stopped the run. */
     atStep: number;
     /** How many of the flow's steps were never attempted because of it. */
@@ -24,3 +24,4 @@ export interface ReplayHalt {
  * defect restated as its own fix.
  */
 export declare function haltedFrom(results: readonly FlowStepResult[], total: number): ReplayHalt | undefined;
+export {};

package/dist/language/flows/recording/tape/recordings.d.ts

@@ -1,4 +1,4 @@
-import { type FlowExpect } from '@reticlehq/core';
+import { type Predicate } from '@reticlehq/core';
 /** One captured agent action, normalized for replay. */
 export interface RecordedStep {
     /** ReticleTool.ACT | ReticleTool.ACT_SEQUENCE */
@@ -8,7 +8,7 @@ export interface RecordedStep {
     /** false if any ref could not be normalized to a testid (replay only valid in-session). */
     stable: boolean;
     /** Optional post-condition annotation carried into the on-disk flow's expect. */
-    expect?: FlowExpect;
+    expect?: Predicate;
     /**
      * The route this step ran on. RECORDER-INTERNAL: it never reaches the on-disk flow.
      *

package/dist/language/flows/replay.js

@@ -1,9 +1,8 @@
 import { REDACTED_FILL, secretEnvKey } from './fields/flow-secret-field.js';
+import { FlowPredicateSchema } from '@reticlehq/core';
 import { DANGEROUS_ACTION_CONFIRM_ARG, ReticleCommand, QueryBy, } from '@reticlehq/core';
 import { ReticleTool } from '@reticlehq/core';
 import { formatStepAddress } from 'open-verification';
-import { predicateToExpect, enforcedOnReplay } from '../../judgement/outcome/predicate-to-expect.js';
-import { PredicateSchema } from '@reticlehq/engine/question/predicate/predicate.js';
 import { asRecord, asString } from '@reticlehq/core';
 /**
  * The note attached when a testid resolves to multiple live elements (the first match is used).
@@ -93,7 +92,7 @@ route) {
     // that is never recorded cannot contribute to either.
     const step = compileActStep(args, res);
     // Keep the assertion the agent actually made. `act_and_wait { until }` IS the agent saying what
-    // success means — 12 of 14 calls in a day carried one — and dropping it produced a flow graded
+    // success means — the large majority of calls carry one — and dropping it produced a flow graded
     // "assertion-free: it will pass even if the feature is broken", which is the regression-suite
     // story failing at its last step. Only kinds FlowExpect can express survive; see
     // predicate-to-expect.ts.
@@ -105,16 +104,21 @@ route) {
 /**
  * A declared predicate, as a recorded expectation — or nothing.
  *
- * The ONE place this conversion happens, because it is the rule that decides whether a saved flow
- * proves anything, and two copies of it would drift. Only kinds a replay actually CHECKS survive:
- * recording an unenforced assertion grades the flow "asserted" while nothing verifies it, which is a
- * false green inside the feature built to prevent them. See enforcedOnReplay.
+ * It is now the SAME OBJECT. A step's `expect` is a `Predicate`, so what the agent declared in
+ * `until` is what the flow file stores, and there is no conversion left to lose anything in.
+ *
+ * What was here before was a lossy round trip through a flat struct with one slot per kind. An
+ * `allOf[netA, netB]` saved as one of the two with nothing said; anything the struct could not
+ * express was dropped, and a filter then removed the kinds replay would not have checked anyway.
+ * Every one of those was a claim the agent made and the file did not keep.
  */
 function enforceableExpect(raw) {
     if (raw === undefined)
         return undefined;
-    const parsed = PredicateSchema.safeParse(raw);
-    return parsed.success ? enforcedOnReplay(predicateToExpect(parsed.data)) : undefined;
+    // The flow file's own schema, so capture keeps exactly what a load would accept — a predicate
+    // holding a session ref is refused by both, rather than recorded here and rejected on read.
+    const parsed = FlowPredicateSchema.safeParse(raw);
+    return parsed.success ? parsed.data : undefined;
 }
 /**
  * Compile a single reticle_act invocation into a normalized RecordedStep using the action result. Anchor

package/dist/language/flows/stores/annotation-store.d.ts

@@ -1,22 +1,22 @@
-import type { FlowExpect } from '@reticlehq/core';
+import type { Predicate } from '@reticlehq/core';
 export declare class AnnotationStore {
     #private;
     /** Testids whose CONTENT must not be asserted at replay (mark-dynamic). Copy, never the live array. */
     dynamic(name: string): string[];
     /** The flow's golden end-condition (success-state), or undefined. */
-    success(name: string): FlowExpect | undefined;
+    success(name: string): Predicate | undefined;
     /** The flow's declared business goal (intent annotation), or undefined. */
     intent(name: string): string | undefined;
     /** Per-step expect predicates compiled from assert-* annotations, keyed by step index. */
-    stepExpect(name: string): Map<number, FlowExpect>;
+    stepExpect(name: string): Map<number, Predicate>;
     /** Append a dynamic testid (mark-dynamic). De-duped so repeated marks stay idempotent. */
     addDynamic(name: string, testid: string): void;
     /** Set the flow's success expectation (success-state); a later set overwrites. */
-    setSuccess(name: string, expect: FlowExpect): void;
+    setSuccess(name: string, expect: Predicate): void;
     /** Set the flow's declared business goal (intent); a later set overwrites. */
     setIntent(name: string, text: string): void;
     /** Set one step's expect (assert-signal / assert-visible); a later set on the same index wins. */
-    setStepExpect(name: string, index: number, expect: FlowExpect): void;
+    setStepExpect(name: string, index: number, expect: Predicate): void;
     /** Drop a recording's annotations (called after reticle_flow_save folds them onto disk). */
     clear(name: string): void;
 }

package/dist/language/flows/stores/assertion-tiers-store.js

@@ -1,4 +1,5 @@
 import { dirname } from 'node:path';
+import { writeFileAtomic } from '../../../memory/project/fs/write-atomic.js';
 import { z } from 'zod';
 import { reticleDirPaths } from '../../../memory/project/dir/reticle-dir.js';
 import { withFileLock } from '../../../memory/project/file-lock.js';
@@ -77,9 +78,7 @@ export class AssertionTiersStore {
     async save(tiers) {
         await this.#fs.mkdir(dirname(this.#path));
         const body = `${JSON.stringify({ version: ASSERTION_TIERS_VERSION, flows: tiers }, null, 2)}\n`;
-        const tmp = `${this.#path}.tmp`;
-        await this.#fs.writeFile(tmp, body);
-        await this.#fs.rename(tmp, this.#path);
+        await writeFileAtomic(this.#fs, this.#path, body);
     }
     /** Record one flow's assertion shape + covered sources after it PASSED. Never breaks a replay. */
     async recordPassing(name, steps, sources = []) {

package/dist/language/flows/stores/flake-store.js

@@ -1,4 +1,5 @@
 import { dirname } from 'node:path';
+import { writeFileAtomic } from '../../../memory/project/fs/write-atomic.js';
 import { reticleDirPaths } from '../../../memory/project/dir/reticle-dir.js';
 import { FlakeFileSchema, emptyRecord, isFlaky, recordOutcome, } from '../recording/flake.js';
 const FLAKE_FILE_VERSION = 1;
@@ -38,9 +39,7 @@ export class FlakeStore {
     async save(ledger) {
         await this.#fs.mkdir(dirname(this.#path));
         const body = `${JSON.stringify({ version: FLAKE_FILE_VERSION, flows: ledger }, null, 2)}\n`;
-        const tmp = `${this.#path}.tmp`;
-        await this.#fs.writeFile(tmp, body);
-        await this.#fs.rename(tmp, this.#path);
+        await writeFileAtomic(this.#fs, this.#path, body);
     }
     /** Accrue one unchanged-code replay outcome for a flow and persist. */
     async record(flow, passed) {

package/dist/language/flows/suite/coverage.d.ts

@@ -24,7 +24,7 @@ interface CoverageDimension {
     /** Declared-but-never-exercised members — what "everything" is silently missing. */
     uncovered: string[];
 }
-export interface Coverage {
+interface Coverage {
     testids: CoverageDimension;
     signals: CoverageDimension;
     flows: CoverageDimension;

package/dist/language/flows/suite/parallel-suite.d.ts

@@ -9,7 +9,7 @@
  * - one flow throwing never sinks the run — it is captured as that item's outcome, because a suite that
  * aborts on the first crash tells you nothing about the other 199 flows.
  */
-export interface Outcome<T> {
+interface Outcome<T> {
     ok: boolean;
     value?: T;
     error?: string;
@@ -24,3 +24,4 @@ export declare function mapWithConcurrency<I, T>(items: readonly I[], limit: num
  * and never below 1. Explicit `requested` (the tool's `parallel` arg) wins when it is a sane number.
  */
 export declare function resolveConcurrency(flowCount: number, poolCapacity: number, requested?: number): number;
+export {};

package/dist/language/flows/suite-selection.d.ts

@@ -1,3 +1,17 @@
+/**
+ * Which flows a suite run replays, resolved against the store.
+ *
+ * Shared by the MCP tool and the `reticle verify` command so the two cannot disagree about what a
+ * selection means.
+ *
+ * Lives beside the flow store rather than under `suite/` on purpose: it needs `flowsForSession`, and
+ * from `suite/` that import made `suite` and `flows` need EACH OTHER -- a mutual pair, which the
+ * reach guard forbids growing because two directories that need each other cannot be read, moved or
+ * tested apart. Here it adds no edge at all: `flows` reaching itself is nothing, and `cli -> flows`
+ * already existed. The pure rule lives in core (`selectFlows`); this is the part that has to read
+ * the files, because a label lives in one and `list` returns only names.
+ */
+import { type ProjectId } from '@reticlehq/core';
 import type { ToolDeps } from '../../surface/tools/tool-kit.js';
 /**
  * Resolve what a suite run should replay, and what it is holding back.
@@ -9,7 +23,7 @@ import type { ToolDeps } from '../../surface/tools/tool-kit.js';
  * would turn a corrupt file into missing coverage nobody is told about, and replay reports the parse
  * failure far better than a silent omission does.
  */
-export declare function resolveSuiteSelection(deps: ToolDeps, projectId: string | undefined, args: Record<string, unknown>): Promise<{
+export declare function resolveSuiteSelection(deps: ToolDeps, projectId: ProjectId | undefined, args: Record<string, unknown>): Promise<{
     run: string[];
     quarantined: string[];
     unmatched: string[];

package/dist/language/flows/suite-selection.js

@@ -11,7 +11,7 @@
  * already existed. The pure rule lives in core (`selectFlows`); this is the part that has to read
  * the files, because a label lives in one and `list` returns only names.
  */
-import { FLOW_FILE_VERSION, orderFlows, selectFlows } from '@reticlehq/core';
+import { FLOW_FILE_VERSION, orderFlows, selectFlows, } from '@reticlehq/core';
 import { flowsForSession } from './flow-store-for-session.js';
 /**
  * Resolve what a suite run should replay, and what it is holding back.

package/dist/language/flows/verify-change-tools.js

@@ -7,6 +7,7 @@ import { ReticleTool } from '@reticlehq/core';
 import { asNumber, asRecord, asString } from '@reticlehq/core';
 import { workerCountSchema } from '../../surface/tools/args/numeric-bounds.js';
 import { loadNamedFlows, resolveChangedFiles } from '../../command/cli/cli-flow-commands.js';
+import { projectDirFor } from '../../memory/project/session-root.js';
 import { affectedSavedFlows } from './change/flow-sources.js';
 import { FLOW_TOOLS } from './flow-tools.js';
 import { findContradictions } from '@reticlehq/engine/disagreement/contradictions.js';
@@ -62,10 +63,12 @@ export const VERIFY_CHANGE_TOOLS = [
                 ? args['files'].filter((f) => 'string' === typeof f)
                 : [];
             const since = asString(args['since']);
-            // The daemon's cwd is not the project — it is wherever the MCP host started it, which for a
-            // globally-registered server is `/` or `$HOME`. `deps.reticleRoot` is the project directory
-            // this daemon was configured with, and it is the right tree to diff.
-            const changed = await resolveChangedFiles(files, since, deps.reticleRoot);
+            // The tree to diff is the SESSION's project, and it is neither of the two things this line
+            // used to say it was: `deps.reticleRoot` is the daemon's `.reticle` SUBDIRECTORY, and the
+            // daemon's cwd is wherever the MCP host started it — `/` or `$HOME` for a globally-registered
+            // server. Both answer about the wrong repository while reporting a clean "nothing changed",
+            // which reads as a pass. `projectDirFor` is the directory holding the resolved root.
+            const changed = await resolveChangedFiles(files, since, projectDirFor(deps, asString(args['sessionId'])));
             const changedFiles = changed.files;
             // Same root flow_save wrote to. A read that resolved differently would report "no flows
             // covered this change" over flows that exist, which reads as a clean result rather than
@@ -181,6 +184,19 @@ export const VERIFY_CHANGE_TOOLS = [
                     measured: extra.measured,
                 };
             }
+            // The mirror of `earnedNo`: a green from flows that ran only because their sources are unknown
+            // says nothing about these files either. At least one attributed flow has to have passed.
+            if (0 === attributedFailures(affected, unknownProvenance).length) {
+                return {
+                    verified: Verified.UNKNOWN,
+                    because: `the flows that ran passed, but Reticle cannot tell which sources any of them cover (${affected.join(', ')}), so this says nothing about the files you changed. Drive the change directly; the drive is saved as a flow with its sources stamped`,
+                    changedFiles,
+                    flowsRun: affected,
+                    suite,
+                    unknownProvenance,
+                    measured: extra.measured,
+                };
+            }
             return {
                 verified: Verified.YES,
                 because: `all ${String(passed)} flows covering these files passed${provenanceNote}${extra.untouched === undefined ? '' : `, with ${String(extra.untouched.length)} controls left undriven`}`,
@@ -223,6 +239,7 @@ async function inspectAfterReplay(deps, args, cursor) {
             currentDocumentId: session.currentDocumentId,
             currentEditEpoch: session.currentEditEpoch,
             appOrigin: session.url,
+            background: session.background,
             // The replay is the action, and the cursor is where it started.
             actionSince: cursor,
         });

package/dist/memory/cloud/account-state.d.ts

@@ -2,7 +2,7 @@
  * Is this machine signed in to a Reticle workspace?
  *
  * Asked by the HUD, and there are two sources that must not be reimplemented per caller: the session
- * file `reticle login` writes to `~/.reticle/session.json`, and `RETICLE_CLOUD_KEY` for an agent that
+ * file `reticle login` writes to `~/.reticle/session.json`, and `RETICLE_API_KEY` for an agent that
  * was handed a key instead. Everything that gates on login — the defect sync button, the prompt to sign
  * in — resolves through here.
  *

package/dist/memory/cloud/account-state.js

@@ -2,7 +2,7 @@
  * Is this machine signed in to a Reticle workspace?
  *
  * Asked by the HUD, and there are two sources that must not be reimplemented per caller: the session
- * file `reticle login` writes to `~/.reticle/session.json`, and `RETICLE_CLOUD_KEY` for an agent that
+ * file `reticle login` writes to `~/.reticle/session.json`, and `RETICLE_API_KEY` for an agent that
  * was handed a key instead. Everything that gates on login — the defect sync button, the prompt to sign
  * in — resolves through here.
  *
@@ -11,7 +11,7 @@
  */
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { ReticleDir } from '@reticlehq/core';
+import { ReticleDir, apiKeyFrom } from '@reticlehq/core';
 import { CloudEnv } from './cloud-sync.js';
 import { SESSION_FILE } from '../../command/cli/cloud-kit.js';
 /** Signed OUT is the safe answer: it shows the way in, where a wrong "signed in" hides it. */
@@ -57,9 +57,10 @@ function fromSessionFile(home) {
  * acting.
  */
 export function readAccountState(home, env) {
-    const key = env[CloudEnv.KEY];
+    // Through the resolver, so a machine still exporting the key's previous name is still signed in.
+    const key = apiKeyFrom(env);
     const url = env[CloudEnv.URL];
-    if ('string' === typeof key && key.length > 0) {
+    if (key !== undefined) {
         return {
             signedIn: true,
             ...('string' === typeof url && url.length > 0 ? { host: url.replace(/\/+$/, '') } : {}),

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

@@ -67,4 +67,13 @@ export declare const credentialSlot: (url: string, projectId: string, orgId?: st
  * so the single-project / CI flow is unchanged. `homeDir` is injected (testable; `os.homedir()` at call).
  */
 export declare function resolveProjectCloud(fs: FileSystemPort, reticleRoot: string, homeDir: string, env: NodeJS.ProcessEnv): Promise<ProjectCloud>;
+/**
+ * The linked credential, as a port the tool surface can be handed.
+ *
+ * Lives here, beside the resolver it wraps, rather than in the daemon bootstrap: `index.ts` sits
+ * exactly on the thousand-line cap, so a caller that needs this in three lines has to put those
+ * 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 {};

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

@@ -145,3 +145,12 @@ export async function resolveProjectCloud(fs, reticleRoot, homeDir, env) {
     const config = key !== null ? { url: link.url.replace(/\/+$/, ''), apiKey: key } : null;
     return { config, policy, verify: link.verify, projectId: link.projectId };
 }
+/**
+ * The linked credential, as a port the tool surface can be handed.
+ *
+ * Lives here, beside the resolver it wraps, rather than in the daemon bootstrap: `index.ts` sits
+ * exactly on the thousand-line cap, so a caller that needs this in three lines has to put those
+ * 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;

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

@@ -10,10 +10,15 @@
  */
 import { z } from 'zod';
 import { type FlowFile, type ReticleVerificationRun, type RunRecord, type VerifyProgressEvent } from '@reticlehq/core';
-/** Env var names — the presence of BOTH is what "logged in" means for cloud sync. */
+/**
+ * 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 declare const CloudEnv: {
     readonly URL: "RETICLE_CLOUD_URL";
-    readonly KEY: "RETICLE_CLOUD_KEY";
+    readonly KEY: "RETICLE_API_KEY";
 };
 export interface CloudConfig {
     url: string;
@@ -170,8 +175,6 @@ export declare function submitServerVerification(body: {
  * allowed to influence a verdict or an exit code.
  */
 export declare function syncProgressToCloud(runId: string, events: readonly VerifyProgressEvent[], config: CloudConfig | null, fetchImpl: FetchLike): Promise<SyncResult>;
-/** How long events accumulate before a flush. See the batching note above. */
-export declare const PROGRESS_FLUSH_MS = 2000;
 /**
  * A listener that buffers progress and ships it on a timer.
  *

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

@@ -9,11 +9,16 @@
  * cloud copy is an enhancement, so a push error is logged and swallowed.
  */
 import { z } from 'zod';
-import { VERIFY_PROGRESS_MAX_EVENTS, } from '@reticlehq/core';
-/** Env var names — the presence of BOTH is what "logged in" means for cloud sync. */
+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_CLOUD_KEY',
+    KEY: 'RETICLE_API_KEY',
 };
 /** Paths the OSS server pushes to (match the cloud app's contract). */
 const CLOUD_FLOWS_PATH = '/v1/flows';
@@ -25,10 +30,10 @@ 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 = env[CloudEnv.KEY];
+    const apiKey = apiKeyFrom(env);
     if (typeof url !== 'string' || 0 === url.length)
         return null;
-    if (typeof apiKey !== 'string' || 0 === apiKey.length)
+    if (apiKey === undefined)
         return null;
     return { url: url.replace(/\/+$/, ''), apiKey };
 }
@@ -288,7 +293,7 @@ export async function syncProgressToCloud(runId, events, config, fetchImpl) {
     }
 }
 /** How long events accumulate before a flush. See the batching note above. */
-export const PROGRESS_FLUSH_MS = 2_000;
+const PROGRESS_FLUSH_MS = 2_000;
 /**
  * A listener that buffers progress and ships it on a timer.
  *

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

@@ -0,0 +1,12 @@
+/** 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;
+    /** Whether the platform holds a key for `provider`. Entitlement is not readiness — see the offer. */
+    providerReady: 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;
+        },
+    };
+}