@reticlehq/server 3.1.0 → 3.2.0

package/dist/language/flows/flow-result.d.ts

@@ -1,4 +1,5 @@
 import { FlowErrorCode } from '@reticlehq/core';
+import { type ProjectId } from '@reticlehq/core';
 /** Discriminated result so callers never branch on free strings. */
 export type FlowResult<T> = {
     ok: true;
@@ -14,5 +15,21 @@ export type FlowResult<T> = {
  * An unsafe or absent value collapses to `undefined` — the flat, global store — so a malformed id
  * can never escape `.reticle/flows/`. The store defends the disk boundary itself rather than
  * trusting whatever arrived in a session's HELLO.
+ *
+ * Held to one SEGMENT, not to a flow name. A project id becomes a DIRECTORY; a flow name is an
+ * ADDRESS, and since composites began naming sub-journeys as `onboarding/signup` its pattern has
+ * allowed separators. Validating a directory name with the address guard let a page choose how deep
+ * under `.reticle/` Reticle wrote — not an escape, since neither pattern admits `..` or a leading
+ * separator, but the page naming directories all the same.
+ *
+ * A FILTER, not a mint. It answers "is this id safe on disk", never "is this id a project" — a
+ * session id passes `SAFE_SEGMENT_PATTERN` just as cleanly, so minting the brand here would launder
+ * the exact confusion `ProjectId` exists to catch. The brand arrives already attached, from HELLO
+ * or from `.reticle.json`; see `ProjectId` in core.
+ *
+ * The narrowing said it out loud and nobody was listening: `isValidFlowName` narrows its argument to
+ * `FlowName`, for a value that is a project. The sibling guards for session and run ids have used
+ * the segment pattern since that widening, and `id-guards-are-not-flow-names.test.ts` exists to
+ * hold the distinction — this is the fourth id joined into a path, and the one that file missed.
  */
-export declare const safeProjectId: (projectId?: string) => string | undefined;
+export declare const safeProjectId: (projectId?: ProjectId) => ProjectId | undefined;

package/dist/language/flows/flow-result.js

@@ -1,10 +1,26 @@
 import { FlowErrorCode } from '@reticlehq/core';
-import { isValidFlowName } from '../../memory/project/dir/reticle-dir.js';
+import { SAFE_SEGMENT_PATTERN } from '@reticlehq/core';
 /**
  * A project id that is safe to put in a path, or nothing.
  *
  * An unsafe or absent value collapses to `undefined` — the flat, global store — so a malformed id
  * can never escape `.reticle/flows/`. The store defends the disk boundary itself rather than
  * trusting whatever arrived in a session's HELLO.
+ *
+ * Held to one SEGMENT, not to a flow name. A project id becomes a DIRECTORY; a flow name is an
+ * ADDRESS, and since composites began naming sub-journeys as `onboarding/signup` its pattern has
+ * allowed separators. Validating a directory name with the address guard let a page choose how deep
+ * under `.reticle/` Reticle wrote — not an escape, since neither pattern admits `..` or a leading
+ * separator, but the page naming directories all the same.
+ *
+ * A FILTER, not a mint. It answers "is this id safe on disk", never "is this id a project" — a
+ * session id passes `SAFE_SEGMENT_PATTERN` just as cleanly, so minting the brand here would launder
+ * the exact confusion `ProjectId` exists to catch. The brand arrives already attached, from HELLO
+ * or from `.reticle.json`; see `ProjectId` in core.
+ *
+ * The narrowing said it out loud and nobody was listening: `isValidFlowName` narrows its argument to
+ * `FlowName`, for a value that is a project. The sibling guards for session and run ids have used
+ * the segment pattern since that widening, and `id-guards-are-not-flow-names.test.ts` exists to
+ * hold the distinction — this is the fourth id joined into a path, and the one that file missed.
  */
-export const safeProjectId = (projectId) => projectId !== undefined && isValidFlowName(projectId) ? projectId : undefined;
+export const safeProjectId = (projectId) => projectId !== undefined && SAFE_SEGMENT_PATTERN.test(projectId) ? projectId : undefined;

package/dist/language/flows/flow-store-for-session.d.ts

@@ -24,8 +24,9 @@
  * returned unchanged.
  */
 import { FlowStore } from './flows.js';
+import type { ProjectId } from '@reticlehq/core';
 import type { ToolDeps } from '../../surface/tools/tool-kit.js';
-export declare function flowsForSession(deps: ToolDeps, projectId: string | undefined): {
+export declare function flowsForSession(deps: ToolDeps, projectId: ProjectId | undefined): {
     flows: FlowStore;
     root: string;
 };

package/dist/language/flows/flow-tools.js

@@ -20,6 +20,7 @@ import { recordingBacktrackWarning } from './recording/recording-backtrack.js';
 import { isValidFlowName, flowPath } from '../../memory/project/dir/reticle-dir.js';
 import {} from './flows.js';
 import { flowsForSession } from './flow-store-for-session.js';
+import { rootForProjectId } from '../../memory/project/session-root.js';
 import { resolveSuiteSelection } from './suite-selection.js';
 import { replayNamedFlow, flowErrorMessage, latestRecordedFlow, sessionProjectId, } from './flow-replay-run.js';
 import { persistAndSyncVerificationRun, } from '../../judgement/runs/verification-sync.js';
@@ -34,7 +35,10 @@ import { replayAndLearn } from './flow-learning.js';
  */
 async function syncSavedFlowToCloud(deps, flow, projectId) {
     // Per-project cloud: sync a saved flow only when cloud is attached AND flow sync is enabled.
-    const cloud = await resolveProjectCloud(deps.fs, deps.reticleRoot, homedir(), process.env);
+    // The link file of the project this flow belongs to — the flow itself was already saved through
+    // `flowsForSession`, and reading the credential from a different tree is how one project's work
+    // reaches another project's dashboard.
+    const cloud = await resolveProjectCloud(deps.fs, rootForProjectId(deps, projectId), homedir(), process.env);
     if (null === cloud.config || !cloud.policy.flows)
         return; // not attached / flows disabled → local only
     const result = await syncFlowToCloud(flow, cloud.config, projectId, cloudFetch);
@@ -573,7 +577,7 @@ export const FLOW_TOOLS = [
                 ...(selected.unsatisfied === undefined ? {} : { unsatisfied: selected.unsatisfied }),
             };
             // verify:server — hand the whole suite to the hosted runner; it records the verification itself.
-            const cloud = await resolveProjectCloud(deps.fs, deps.reticleRoot, homedir(), process.env);
+            const cloud = await resolveProjectCloud(deps.fs, rootForProjectId(deps, projectId), homedir(), process.env);
             const server = await runServerVerify(deps, cloud, sessionId, requested);
             if (server !== null)
                 return server;
@@ -637,7 +641,7 @@ export const FLOW_TOOLS = [
                         : leaseFailureReplay(requested[i] ?? '', o.error),
                     durationMs: o.ok && o.value !== undefined ? o.value.durationMs : 0,
                 }));
-                const flaky = await recordSuiteFlakes(deps.fs, deps.reticleRoot, parallelRuns);
+                const flaky = await recordSuiteFlakes(deps.fs, rootForProjectId(deps, projectId), parallelRuns);
                 await persistAndSyncVerificationRun(deps, timed, projectId);
                 const verdict = buildSuiteVerdict(parallelRuns, selected.knownRoutes, SuiteIsolation.PER_FLOW_LEASE);
                 return {
@@ -673,7 +677,7 @@ export const FLOW_TOOLS = [
             // `reticle flow` on the command line, so an AGENT running this tool a hundred times learned
             // nothing about which flows are intermittent. Same product, same ledger, two surfaces, and the
             // one an agent uses was the blind half.
-            const flaky = await recordSuiteFlakes(deps.fs, deps.reticleRoot, runs);
+            const flaky = await recordSuiteFlakes(deps.fs, rootForProjectId(deps, projectId), runs);
             // Emit the consolidated run artifact (Runs tab) + best-effort cloud push. Never blocks the verdict.
             await persistAndSyncVerificationRun(deps, timed, projectId);
             const verdict = buildSuiteVerdict(runs, selected.knownRoutes, SuiteIsolation.SHARED_SESSION);

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

@@ -1,3 +1,4 @@
+import { type ProjectId } from '@reticlehq/core';
 export { REDACTED_FILL } from './fields/flow-secret-field.js';
 import { type FlowResult } from './flow-result.js';
 export type { FlowResult } from './flow-result.js';
@@ -63,15 +64,15 @@ export declare class FlowStore {
      * Optionally fold structured annotations (per-step expect, dynamic[], success) onto
      * the flow before writing. Omitting `annotations` reproduces the same bytes.
      */
-    save(program: CompiledProgram, annotations?: FlowAnnotations, projectId?: string): Promise<FlowResult<SaveSummary>>;
+    save(program: CompiledProgram, annotations?: FlowAnnotations, projectId?: ProjectId): Promise<FlowResult<SaveSummary>>;
     /**
      * Persist an already-anchored FlowFile captured in-page (no recompilation). The
      * browser resolved every semantic anchor at capture time; here we only validate the name +
      * re-run FlowFileSchema before writing. save is left untouched.
      */
-    saveFlow(flow: FlowFile, projectId?: string): Promise<FlowResult<SaveSummary>>;
+    saveFlow(flow: FlowFile, projectId?: ProjectId): Promise<FlowResult<SaveSummary>>;
     /** Write back only what a replay LEARNED. See `#changeInPlace` for why it is not `saveFlow`. */
-    recordLearned(name: string, learned: NonNullable<FlowFile['learned']>, projectId?: string): Promise<FlowResult<{
+    recordLearned(name: string, learned: NonNullable<FlowFile['learned']>, projectId?: ProjectId): Promise<FlowResult<{
         name: string;
     }>>;
     /**
@@ -83,7 +84,7 @@ export declare class FlowStore {
      * it with proposals that already cleared HEAL_CONFIDENCE_MIN. A change whose `from` no longer
      * matches the step's anchor is skipped — idempotent and defensive, never throwing.
      */
-    heal(name: string, changes: HealChange[], projectId?: string): Promise<FlowResult<{
+    heal(name: string, changes: HealChange[], projectId?: ProjectId): Promise<FlowResult<{
         name: string;
         changed: HealChange[];
     }>>;
@@ -97,17 +98,17 @@ export declare class FlowStore {
      * the caller as a reportable error, never be silently filtered away. Callers that build a path from a
      * name must validate first; `flowPath` takes a branded FlowName precisely so the compiler insists.
      */
-    list(projectId?: string): Promise<string[]>;
+    list(projectId?: ProjectId): Promise<string[]>;
     /**
      * Read + zod-validate a flow by name. With a `projectId`, prefers the per-project copy and falls
      * back to a legacy flat (untagged) flow of the same name — so pre-existing flows keep loading.
      */
-    load(name: string, projectId?: string): Promise<FlowResult<FlowFile>>;
+    load(name: string, projectId?: ProjectId): Promise<FlowResult<FlowFile>>;
     /**
      * Delete a flow's file so a renamed/obsolete flow stops lingering in the replay list. Resolves the
      * same path `load` would (per-project copy, else legacy flat, else a subdir scan for the no-pid
      * caller), then removes it. NOT_FOUND when nothing resolves — deleting an absent flow is an error,
      * not a silent no-op, so a typo doesn't read as success.
      */
-    remove(name: string, projectId?: string): Promise<FlowResult<void>>;
+    remove(name: string, projectId?: ProjectId): Promise<FlowResult<void>>;
 }

package/dist/language/flows/flows.js

@@ -1,4 +1,4 @@
-import { asFlowName } from '@reticlehq/core';
+import { asFlowName, asProjectId } from '@reticlehq/core';
 import { REDACTED_FILL } from './fields/flow-secret-field.js';
 export { REDACTED_FILL } from './fields/flow-secret-field.js';
 import { safeProjectId } from './flow-result.js';
@@ -408,8 +408,11 @@ export class FlowStore {
         catch {
             return legacy.sort();
         }
+        // Every subdirectory of `.reticle/flows/` is a project's, by construction: this class is the
+        // only thing that creates one, and it creates it from a projectId that already passed
+        // `safeProjectId`. Reading the name back is the third provenance boundary, not a cast.
         const subdirs = entries.filter((e) => !e.endsWith(FLOW_SUFFIX));
-        const nested = (await Promise.all(subdirs.map((d) => this.#namesIn(flowDir(this.#root, d))))).flat();
+        const nested = (await Promise.all(subdirs.map((d) => this.#namesIn(flowDir(this.#root, asProjectId(d)))))).flat();
         return [...new Set([...legacy, ...nested])].sort();
     }
     /** The path a flow actually lives at: nested (per-project) if present, else legacy flat, else null. */
@@ -441,8 +444,9 @@ export class FlowStore {
         catch {
             return null;
         }
+        // Same provenance as `#namesIn`'s scan above: a subdir of `.reticle/flows/` is a projectId.
         for (const dir of entries.filter((e) => !e.endsWith(FLOW_SUFFIX))) {
-            const nested = flowPath(this.#root, name, dir);
+            const nested = flowPath(this.#root, name, asProjectId(dir));
             if (await this.#fs.exists(nested))
                 return nested;
         }

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/replay.js

@@ -93,7 +93,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.

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

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;

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 };
 }

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;