@reticlehq/server 3.3.0 → 3.4.0

package/dist/language/flows/replay.js

@@ -1,5 +1,5 @@
 import { REDACTED_FILL, secretEnvKey } from './fields/flow-secret-field.js';
-import { FlowPredicateSchema } from '@reticlehq/core';
+import { FlowPredicateSchema, Verified } from '@reticlehq/core';
 import { DANGEROUS_ACTION_CONFIRM_ARG, ReticleCommand, QueryBy, } from '@reticlehq/core';
 import { ReticleTool } from '@reticlehq/core';
 import { formatStepAddress } from 'open-verification';
@@ -71,6 +71,22 @@ function sourceFromResult(res) {
         out['column'] = source['column'];
     return out;
 }
+/**
+ * The pathname of a session's live url, or undefined when it has none yet.
+ *
+ * Pathname rather than the whole url, because that is what `startPath` is compared against and what
+ * a hash-routed app makes meaningless in the document location — see routeOfEvent.
+ */
+export function pathOf(url) {
+    if (url === undefined)
+        return undefined;
+    try {
+        return new URL(url).pathname;
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * Capture an act into every in-flight recording, or do nothing when none is running.
  *
@@ -87,20 +103,40 @@ route) {
     // — "recording is a property of the system rather than a rule an agent has to remember" — was true
     // about the intent and false about the code, and every drive nobody wrapped by hand was discarded.
     //
-    // That is the whole supply of regression tests this product could have had for free: the corpus
-    // measures 3 of 33 flows mutation-testable and 6 of 112 steps declaring a consequence, and a drive
-    // that is never recorded cannot contribute to either.
+    // That is the whole supply of regression tests this product could have had for free: few saved
+    // flows are mutation-testable and few steps declare a consequence, and a drive 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 — 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.
+    // story failing at its last step. See enforceableExpect below.
     const expect = enforceableExpect(args['until'] ?? args['predicate']);
     if (expect !== undefined)
         step.expect = expect;
+    if (route !== undefined)
+        step.page = route;
+    const intent = asString(args['intent'])?.trim();
+    if (intent !== undefined && intent.length > 0)
+        step.intent = intent;
     recordings.capture(step, route);
 }
+/**
+ * Capture an act_and_wait once its verdict is known, keeping `until` as the step's expectation only
+ * on a yes. Recorded before the verdict, a step kept an `until` that came back `no` or `no-fault` —
+ * a regression test asserting something never once observed to hold because of the action. The
+ * action itself is always recorded: it happened, and replay needs it to reach the next step.
+ */
+export function captureVerdictedAct(recordings, args, res, route, verified) {
+    const { until: _until, predicate: _predicate, ...unproved } = args;
+    captureAct(recordings, Verified.YES === verified ? args : unproved, res, route);
+}
+/** Fold a PASSING standalone assertion into the step it proved. See RecordingStore.attachExpect. */
+export function captureAssertion(recordings, raw) {
+    const expect = enforceableExpect(raw);
+    if (expect !== undefined)
+        recordings.attachExpect(expect);
+}
 /**
  * A declared predicate, as a recorded expectation — or nothing.
  *

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

@@ -172,9 +172,12 @@ export const VERIFY_CHANGE_TOOLS = [
             const extra = await inspectAfterReplay(deps, args, cursor);
             if (extra.contradictions.length > 0) {
                 const kinds = extra.contradictions.map((c) => c.kind).join(', ');
+                const earned = attributedFailures(affected, unknownProvenance).length > 0;
                 return {
-                    verified: Verified.NO,
-                    because: `every covering flow passed, but channels disagreed during the replay (${kinds}) — a green suite over a failed write is the false green worth looking at${provenanceNote}`,
+                    verified: earned ? Verified.NO : Verified.UNKNOWN,
+                    because: earned
+                        ? `every covering flow passed, but channels disagreed during the replay (${kinds}) — a green suite over a failed write is the false green worth looking at${provenanceNote}`
+                        : `channels disagreed during the replay (${kinds}), but Reticle cannot tell which sources any of the flows that ran 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,

package/dist/launch-chromium.d.ts

@@ -0,0 +1,80 @@
+/**
+ * The ONE place a Reticle-owned Chromium is launched — the pooled lease browser
+ * (`playwright-launcher`) and the drive browser (`real-input`) both come through here.
+ *
+ * Why it is more than `chromium.launch`: on a fresh machine the `playwright` package is present
+ * (npx pulled it in with the server) but its browser build is not, because that is a separate
+ * ~150 MiB download nobody told the user about. Every lease, `reticle verify`, `open` and `drive`
+ * then refused with "Chromium is not installed for Playwright. Run: npx playwright@… install
+ * chromium" — the first run stopped on a human step a machine could do. Most machines already have
+ * a Chrome or an Edge, and Playwright drives either through `channel`, so that is tried before any
+ * download; only a machine with neither gets the pinned install, run for them and announced.
+ *
+ * Announcements go to STDERR, never stdout: `reticle mcp` speaks JSON-RPC on stdout and one stray
+ * line there corrupts the client's stream.
+ */
+import { type ChromiumLaunchOptions } from './chromium-launch-options.js';
+import { type ChromiumProbe } from './command/cli/doctor/browser/chromium-hint.js';
+/** The installed-browser channels Playwright can drive in place of its own build. */
+export declare const ChromiumChannel: {
+    readonly CHROME: "chrome";
+    readonly MSEDGE: "msedge";
+};
+export type ChromiumChannel = (typeof ChromiumChannel)[keyof typeof ChromiumChannel];
+export declare const CHANNEL_LABEL: Record<ChromiumChannel, string>;
+/** Candidate executable paths for a channel on this platform; empty where it is not installable. */
+export declare function channelExecutableCandidates(channel: ChromiumChannel, platform: NodeJS.Platform, env: NodeJS.ProcessEnv): string[];
+/** The first installed Chrome/Edge on this machine, or undefined. Looks only; installs nothing. */
+export declare function findInstalledChannel(deps: Pick<ChromiumTargetDeps, 'exists' | 'platform' | 'env'>): ChromiumChannel | undefined;
+/** Everything the resolver touches, injected so it runs against a fake machine in tests. */
+export interface ChromiumTargetDeps {
+    /** Where the bundled playwright expects its Chromium build. */
+    executablePath: () => string;
+    exists: (path: string) => boolean;
+    platform: NodeJS.Platform;
+    env: NodeJS.ProcessEnv;
+    /** Run the pinned Chromium install; resolves true when it succeeded. */
+    install: () => Promise<boolean>;
+    /** A progress line for a human — stderr in production. */
+    announce: (line: string) => void;
+}
+/** Which browser to launch: the bundled build (no channel), an installed channel, or none at all. */
+export type ChromiumTarget = {
+    found: true;
+    channel?: ChromiumChannel;
+} | {
+    found: false;
+};
+/**
+ * Decide which browser a launch will use, installing the pinned Chromium only as the last resort.
+ * Order: bundled build on disk → installed Chrome → installed Edge → install, then bundled.
+ */
+export declare function resolveChromiumTarget(deps: ChromiumTargetDeps): Promise<ChromiumTarget>;
+/** The subset of Playwright's `BrowserType` this file needs, so tests can pass a fake. */
+export interface LaunchableChromium<B> {
+    executablePath: () => string;
+    launch: (options: ChromiumLaunchOptions) => Promise<B>;
+}
+/**
+ * A progress writer that says each distinct line once. The Chrome/Edge fallback line was written on
+ * every launch, and the pool launches per context, so one daemon repeated the same notice into the
+ * terminal of whoever started it.
+ */
+export declare function announceOnce(write: (line: string) => void): (line: string) => void;
+/**
+ * Launch a Chromium with the shared options, on whichever browser this machine can offer. When none
+ * can be found or installed, launch anyway: Playwright's own error is what `chromiumLaunchHint`
+ * turns into the pinned install command, so the user still gets the one line that fixes it.
+ */
+export declare function launchChromium<B>(chromium: LaunchableChromium<B>, headless: boolean, deps?: ChromiumTargetDeps): Promise<B>;
+/**
+ * The lease preflight's probe: "can a launch succeed?", which now includes the Chrome/Edge fallback
+ * and the automatic install. Without this the preflight would refuse a lease on a machine the
+ * launcher itself could serve. Falls back to the plain probe so a real refusal keeps its evidence.
+ */
+export declare function probeLaunchableChromium(): Promise<ChromiumProbe>;
+/**
+ * `doctor`'s probe: the plain Chromium probe, plus the installed browser that stands in when the
+ * bundled build is missing. Never installs — a diagnostic that downloads 150 MiB is not one.
+ */
+export declare function probeChromiumWithFallback(): Promise<ChromiumProbe>;

package/dist/launch-chromium.js

@@ -0,0 +1,218 @@
+/**
+ * The ONE place a Reticle-owned Chromium is launched — the pooled lease browser
+ * (`playwright-launcher`) and the drive browser (`real-input`) both come through here.
+ *
+ * Why it is more than `chromium.launch`: on a fresh machine the `playwright` package is present
+ * (npx pulled it in with the server) but its browser build is not, because that is a separate
+ * ~150 MiB download nobody told the user about. Every lease, `reticle verify`, `open` and `drive`
+ * then refused with "Chromium is not installed for Playwright. Run: npx playwright@… install
+ * chromium" — the first run stopped on a human step a machine could do. Most machines already have
+ * a Chrome or an Edge, and Playwright drives either through `channel`, so that is tried before any
+ * download; only a machine with neither gets the pinned install, run for them and announced.
+ *
+ * Announcements go to STDERR, never stdout: `reticle mcp` speaks JSON-RPC on stdout and one stray
+ * line there corrupts the client's stream.
+ */
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { chromiumLaunchOptions } from './chromium-launch-options.js';
+import { bundledPlaywrightVersion, chromiumInstallCommand, probeChromium, } from './command/cli/doctor/browser/chromium-hint.js';
+/** The installed-browser channels Playwright can drive in place of its own build. */
+export const ChromiumChannel = {
+    CHROME: 'chrome',
+    MSEDGE: 'msedge',
+};
+/** Tried in this order: Chrome is the likelier install and the closer match to Playwright's build. */
+const CHANNEL_ORDER = [ChromiumChannel.CHROME, ChromiumChannel.MSEDGE];
+export const CHANNEL_LABEL = {
+    [ChromiumChannel.CHROME]: 'Google Chrome',
+    [ChromiumChannel.MSEDGE]: 'Microsoft Edge',
+};
+/**
+ * Where each channel's executable lives, per platform — the same locations Playwright's own
+ * registry checks when it launches a channel, so "we found it" and "Playwright can launch it" agree.
+ * Windows is relative to each install root below.
+ */
+const CHANNEL_PATHS = {
+    [ChromiumChannel.CHROME]: {
+        darwin: '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+        linux: '/opt/google/chrome/chrome',
+        win32: '\\Google\\Chrome\\Application\\chrome.exe',
+    },
+    [ChromiumChannel.MSEDGE]: {
+        darwin: '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
+        linux: '/opt/microsoft/msedge/msedge',
+        win32: '\\Microsoft\\Edge\\Application\\msedge.exe',
+    },
+};
+const WINDOWS_INSTALL_ROOTS = ['LOCALAPPDATA', 'PROGRAMFILES', 'PROGRAMFILES(X86)'];
+/** Candidate executable paths for a channel on this platform; empty where it is not installable. */
+export function channelExecutableCandidates(channel, platform, env) {
+    const paths = CHANNEL_PATHS[channel];
+    if ('darwin' === platform)
+        return [paths.darwin];
+    if ('linux' === platform)
+        return [paths.linux];
+    if ('win32' === platform) {
+        return WINDOWS_INSTALL_ROOTS.flatMap((key) => {
+            const root = env[key];
+            return root === undefined || 0 === root.length ? [] : [`${root}${paths.win32}`];
+        });
+    }
+    return [];
+}
+/** The first installed Chrome/Edge on this machine, or undefined. Looks only; installs nothing. */
+export function findInstalledChannel(deps) {
+    return CHANNEL_ORDER.find((channel) => channelExecutableCandidates(channel, deps.platform, deps.env).some((p) => deps.exists(p)));
+}
+const usingChannelLine = (channel) => `[reticle] Playwright's Chromium is not installed; using the installed ${CHANNEL_LABEL[channel]} instead.\n`;
+const installingLine = (command) => `[reticle] No Chromium, Chrome or Edge found; installing Playwright's Chromium (${command}) — a one-time download…\n`;
+const INSTALL_FAILED_LINE = '[reticle] The Chromium install did not complete.\n';
+/**
+ * Decide which browser a launch will use, installing the pinned Chromium only as the last resort.
+ * Order: bundled build on disk → installed Chrome → installed Edge → install, then bundled.
+ */
+export async function resolveChromiumTarget(deps) {
+    let bundled;
+    try {
+        bundled = deps.executablePath();
+    }
+    catch {
+        // A playwright that cannot name its executable is not evidence the browser is missing. Launch
+        // as before and let Playwright's own error (translated by chromiumLaunchHint) say what is wrong,
+        // rather than download ~150 MiB on a guess.
+        return { found: true };
+    }
+    if (deps.exists(bundled))
+        return { found: true };
+    const channel = findInstalledChannel(deps);
+    if (channel !== undefined) {
+        deps.announce(usingChannelLine(channel));
+        return { found: true, channel };
+    }
+    deps.announce(installingLine(chromiumInstallCommand(bundledPlaywrightVersion())));
+    const ok = await deps.install();
+    if (ok && deps.exists(bundled))
+        return { found: true };
+    deps.announce(INSTALL_FAILED_LINE);
+    return { found: false };
+}
+/**
+ * The bundled playwright's own CLI, or undefined when playwright cannot be resolved from here.
+ *
+ * Run directly rather than through the `npx playwright@<version>` the hint prints. They install the
+ * same revision, but `npx` runs in the user's project and inherits everything wrong with it: in the
+ * sandbox this was written against, an `overrides` block in the app's package.json made npm refuse
+ * with EOVERRIDE before playwright ever ran. The bundled CLI is the same version by construction
+ * and needs no registry round trip to find itself.
+ */
+function bundledPlaywrightCli() {
+    try {
+        const pkg = createRequire(import.meta.url).resolve('playwright/package.json');
+        return join(dirname(pkg), PLAYWRIGHT_CLI);
+    }
+    catch {
+        return undefined;
+    }
+}
+const PLAYWRIGHT_CLI = 'cli.js';
+const INSTALL_ARGS = ['install', 'chromium'];
+/**
+ * Run the pinned install with its progress on stderr. Memoized per process: the pool can race
+ * several launches on the first acquire, and two concurrent installs into one browsers root would
+ * fight over the same directory. A failed install clears the memo so a later launch can retry.
+ */
+let installing;
+function installPinnedChromium() {
+    if (installing === undefined) {
+        const cli = bundledPlaywrightCli();
+        installing = new Promise((resolve) => {
+            if (cli === undefined) {
+                resolve(false);
+                return;
+            }
+            // stdout goes to fd 2 for the JSON-RPC reason in this file's header.
+            const child = spawn(process.execPath, [cli, ...INSTALL_ARGS], { stdio: ['ignore', 2, 2] });
+            child.on('error', () => resolve(false));
+            child.on('exit', (code) => resolve(0 === code));
+        }).then((ok) => {
+            if (!ok)
+                installing = undefined;
+            return ok;
+        });
+    }
+    return installing;
+}
+/**
+ * A progress writer that says each distinct line once. The Chrome/Edge fallback line was written on
+ * every launch, and the pool launches per context, so one daemon repeated the same notice into the
+ * terminal of whoever started it.
+ */
+export function announceOnce(write) {
+    const said = new Set();
+    return (line) => {
+        if (said.has(line))
+            return;
+        said.add(line);
+        write(line);
+    };
+}
+/** Once per PROCESS, so it is shared by every launch rather than made per call. */
+// ponytail: an install retried after a failure is not re-announced; the install itself still runs.
+const announceToStderr = announceOnce((line) => {
+    process.stderr.write(line);
+});
+function defaultDeps(chromium) {
+    return {
+        executablePath: () => chromium.executablePath(),
+        exists: existsSync,
+        platform: process.platform,
+        env: process.env,
+        install: installPinnedChromium,
+        announce: announceToStderr,
+    };
+}
+/**
+ * Launch a Chromium with the shared options, on whichever browser this machine can offer. When none
+ * can be found or installed, launch anyway: Playwright's own error is what `chromiumLaunchHint`
+ * turns into the pinned install command, so the user still gets the one line that fixes it.
+ */
+export async function launchChromium(chromium, headless, deps = defaultDeps(chromium)) {
+    const target = await resolveChromiumTarget(deps);
+    const channel = target.found ? target.channel : undefined;
+    return chromium.launch(chromiumLaunchOptions(headless, channel));
+}
+/**
+ * The lease preflight's probe: "can a launch succeed?", which now includes the Chrome/Edge fallback
+ * and the automatic install. Without this the preflight would refuse a lease on a machine the
+ * launcher itself could serve. Falls back to the plain probe so a real refusal keeps its evidence.
+ */
+export async function probeLaunchableChromium() {
+    try {
+        const { chromium } = await import('playwright');
+        const target = await resolveChromiumTarget(defaultDeps(chromium));
+        if (target.found)
+            return { exists: true };
+    }
+    catch {
+        // No playwright at all — probeChromium below says so, with where it looked.
+    }
+    return probeChromium();
+}
+/**
+ * `doctor`'s probe: the plain Chromium probe, plus the installed browser that stands in when the
+ * bundled build is missing. Never installs — a diagnostic that downloads 150 MiB is not one.
+ */
+export async function probeChromiumWithFallback() {
+    const probe = await probeChromium();
+    if (probe.exists)
+        return probe;
+    const channel = findInstalledChannel({
+        exists: existsSync,
+        platform: process.platform,
+        env: process.env,
+    });
+    return channel === undefined ? probe : { ...probe, fallback: CHANNEL_LABEL[channel] };
+}

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

@@ -40,6 +40,8 @@ export interface ProjectCloud {
     verify: VerifyMode;
     /** The cloud project id this project is linked to (for display/logging); null when env-fallback. */
     projectId: string | null;
+    /** Why `config` is null, in words a person can act on. Absent when attached. */
+    reason?: string;
 }
 /** Look up the API key for a cloud project id in the user credentials map. */
 /**
@@ -63,8 +65,8 @@ export interface ProjectCloud {
 export declare const credentialSlot: (url: string, projectId: string, orgId?: string) => string;
 /**
  * Resolve the cloud picture for a project rooted at `reticleRoot`. Reads the project's link file + the
- * user credential store; if the project isn't linked (no cloud.json), falls back to the global env creds
- * so the single-project / CI flow is unchanged. `homeDir` is injected (testable; `os.homedir()` at call).
+ * user credential store, else the env key; if the project isn't linked (no cloud.json), the env creds
+ * are the whole story (the single-project / CI flow). `homeDir` is injected (testable; `os.homedir()` at call).
  */
 export declare function resolveProjectCloud(fs: FileSystemPort, reticleRoot: string, homeDir: string, env: NodeJS.ProcessEnv): Promise<ProjectCloud>;
 /**
@@ -76,4 +78,11 @@ export declare function resolveProjectCloud(fs: FileSystemPort, reticleRoot: str
  * needs no exported key — see `withLinkedCredential`.
  */
 export declare const linkedCloudPort: (fs: FileSystemPort, reticleRoot: string, homeDir: string, env: NodeJS.ProcessEnv) => () => Promise<CloudConfig | null>;
+/**
+ * The environment with this project's resolved credential written into it, for the readers that
+ * take an env record (the panel's model config and harness switch). Handed `process.env` alone,
+ * they never saw a key `reticle link` had stored. Resolved per call, so a link made mid-session
+ * takes effect without a restart.
+ */
+export declare const platformEnvPort: (fs: FileSystemPort, reticleRoot: string, homeDir: string, env: NodeJS.ProcessEnv) => () => Promise<NodeJS.ProcessEnv>;
 export {};

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

@@ -10,7 +10,7 @@
  * user-level credential. "Cloud attached" = a valid link file AND a key for its project id (or env creds).
  */
 import { join } from 'node:path';
-import { ReticleDir } from '@reticlehq/core';
+import { DEFAULT_PLATFORM_URL, ReticleDir, ReticleEnv } from '@reticlehq/core';
 import { resolveCloudConfig } from './cloud-sync.js';
 /** `<reticleRoot>/cloud.json` — the project's cloud binding + sync policy (non-secret). */
 /** Re-exported so the existing importers keep working; the string itself lives in core. */
@@ -121,18 +121,22 @@ function credentialFor(raw, projectId, url, orgId) {
 const normalizeCloudUrl = (url) => url.replace(/\/+$/, '');
 /**
  * Resolve the cloud picture for a project rooted at `reticleRoot`. Reads the project's link file + the
- * user credential store; if the project isn't linked (no cloud.json), falls back to the global env creds
- * so the single-project / CI flow is unchanged. `homeDir` is injected (testable; `os.homedir()` at call).
+ * user credential store, else the env key; if the project isn't linked (no cloud.json), the env creds
+ * are the whole story (the single-project / CI flow). `homeDir` is injected (testable; `os.homedir()` at call).
  */
 export async function resolveProjectCloud(fs, reticleRoot, homeDir, env) {
     const link = parseLink(await readJson(fs, join(reticleRoot, CLOUD_LINK_FILE)));
     if (null === link) {
         // No per-project link → the env vars are the whole story (legacy single-project / CI behaviour).
+        const config = resolveCloudConfig(env);
         return {
-            config: resolveCloudConfig(env),
+            config,
             policy: DEFAULT_SYNC_POLICY,
             verify: VerifyMode.LOCAL,
             projectId: null,
+            ...(null === config
+                ? { reason: 'cloud not attached here: run `reticle link`, or set RETICLE_API_KEY' }
+                : {}),
         };
     }
     const policy = {
@@ -141,9 +145,33 @@ export async function resolveProjectCloud(fs, reticleRoot, homeDir, env) {
         flows: link.sync.flows ?? DEFAULT_SYNC_POLICY.flows,
         capsules: link.sync.capsules ?? DEFAULT_SYNC_POLICY.capsules,
     };
-    const key = credentialFor(await readJson(fs, join(homeDir, ReticleDir.ROOT, CREDENTIALS_FILE)), link.projectId, link.url, link.orgId);
-    const config = key !== null ? { url: link.url.replace(/\/+$/, ''), apiKey: key } : null;
-    return { config, policy, verify: link.verify, projectId: link.projectId };
+    const stored = credentialFor(await readJson(fs, join(homeDir, ReticleDir.ROOT, CREDENTIALS_FILE)), link.projectId, link.url, link.orgId);
+    /*
+     * No stored key, so the environment's — which is the whole of CI: `cloud.json` is committed, a
+     * CI clone is therefore linked, and it has no keystore. Only when the environment's key is FOR
+     * this link's host (its URL, else the hosted default): a key exported for one cloud is not a
+     * credential for a repo linked to another, the same rule `credentialFor` applies to stored keys.
+     */
+    const fromEnv = resolveCloudConfig(env);
+    const key = stored ??
+        (fromEnv !== null && fromEnv.url === normalizeCloudUrl(link.url) ? fromEnv.apiKey : null);
+    const linkedUrl = normalizeCloudUrl(link.url);
+    const config = key !== null ? { url: linkedUrl, apiKey: key } : null;
+    const reason = config !== null
+        ? undefined
+        : fromEnv !== null
+            ? `this repo is linked to ${linkedUrl}, and RETICLE_API_KEY is set for ${fromEnv.url}: ` +
+                `set RETICLE_CLOUD_URL=${linkedUrl} to use that key here, or run \`reticle login\` for it`
+            : `this repo is linked to ${linkedUrl}, and this machine has no key for it: run ` +
+                '`reticle login`, or set RETICLE_API_KEY' +
+                (DEFAULT_PLATFORM_URL === linkedUrl ? '' : ` with RETICLE_CLOUD_URL=${linkedUrl}`);
+    return {
+        config,
+        policy,
+        verify: link.verify,
+        projectId: link.projectId,
+        ...(reason === undefined ? {} : { reason }),
+    };
 }
 /**
  * The linked credential, as a port the tool surface can be handed.
@@ -154,3 +182,15 @@ export async function resolveProjectCloud(fs, reticleRoot, homeDir, env) {
  * needs no exported key — see `withLinkedCredential`.
  */
 export const linkedCloudPort = (fs, reticleRoot, homeDir, env) => async () => (await resolveProjectCloud(fs, reticleRoot, homeDir, env)).config;
+/**
+ * The environment with this project's resolved credential written into it, for the readers that
+ * take an env record (the panel's model config and harness switch). Handed `process.env` alone,
+ * they never saw a key `reticle link` had stored. Resolved per call, so a link made mid-session
+ * takes effect without a restart.
+ */
+export const platformEnvPort = (fs, reticleRoot, homeDir, env) => async () => {
+    const config = (await resolveProjectCloud(fs, reticleRoot, homeDir, env)).config;
+    return null === config
+        ? env
+        : { ...env, [ReticleEnv.API_KEY]: config.apiKey, [ReticleEnv.CLOUD_URL]: config.url };
+};

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

@@ -24,7 +24,10 @@ export interface CloudConfig {
     url: string;
     apiKey: string;
 }
-/** Resolve cloud credentials from the environment, or null when not logged in (sync disabled). */
+/**
+ * Resolve cloud credentials from the environment, or null without a key (sync disabled). The key
+ * alone is enough: the URL defaults to the hosted service, which is what the platform tells CI.
+ */
 export declare function resolveCloudConfig(env: NodeJS.ProcessEnv): CloudConfig | null;
 export declare const CLOUD_VERIFY_TIMEOUT_MS = 120000;
 /**

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

@@ -9,7 +9,7 @@
  * 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';
+import { VERIFY_PROGRESS_MAX_EVENTS, platformCredentialFrom, } from '@reticlehq/core';
 /**
  * Env var names — the presence of BOTH is what "logged in" means for cloud sync.
  *
@@ -27,15 +27,12 @@ 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). */
+/**
+ * Resolve cloud credentials from the environment, or null without a key (sync disabled). The key
+ * alone is enough: the URL defaults to the hosted service, which is what the platform tells CI.
+ */
 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 };
+    return platformCredentialFrom(env) ?? null;
 }
 /**
  * Budget for a cloud call. Node's `fetch` has NO default timeout, so a connection that opens and then

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

@@ -15,7 +15,7 @@
  * 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';
+import { platformCredentialFrom } 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;
@@ -65,12 +65,11 @@ function parse(body, claimUrl) {
 }
 /** 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)
+    const cloud = platformCredentialFrom(env);
+    if (cloud === undefined)
         return undefined;
+    const key = cloud.apiKey;
+    const host = cloud.url;
     const controller = new AbortController();
     const timer = setTimeout(() => {
         controller.abort();

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

@@ -17,18 +17,17 @@
  * that quietly did not save; the next snapshot re-reads the platform, so a lost write shows up as
  * the switch springing back, which is a truthful thing for it to do.
  */
-import { ReticleEnv, apiKeyFrom } from '@reticlehq/core';
+import { platformCredentialFrom } from '@reticlehq/core';
 const CONFIG_PATH = '/v1/model/config';
 /** Same budget as the read beside it: a settings write must never hold anything up. */
 const TIMEOUT_MS = 2_000;
 /** `true` when the platform accepted it. Callers use this for logging, never to block a person. */
 export async function writeHarnessSwitch(env, enabled, 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 false;
-    if (host === undefined || 0 === host.length)
+    const cloud = platformCredentialFrom(env);
+    if (cloud === undefined)
         return false;
+    const key = cloud.apiKey;
+    const host = cloud.url;
     const controller = new AbortController();
     const timer = setTimeout(() => {
         controller.abort();