@reticlehq/server 2.12.0 → 2.13.0

package/dist/cli.js

@@ -5,19 +5,24 @@ import { realpathSync } from 'node:fs';
 import { join } from 'node:path';
 import { stateDirProblem } from './daemon/state-dir.js';
 import { statusNextAction } from './cli/status-next-action.js';
-import { hasConnectedBefore } from './session/connection-memory.js';
+import { readDevServers } from './daemon/dev-servers.js';
+import { hasConnectedBefore, hasProjectConnectedBefore } from './session/connection-memory.js';
 import { attachStatusFields } from './mcp/attach-memory.js';
 import { reticleStateHome } from './daemon/daemon.js';
 import { handleMcp } from './cli/mcp-command.js';
-import { resolveDaemonForProject } from './daemon/daemon-resolve.js';
+import { daemonSpawnArgs, daemonStartOptions } from './cli/daemon-start-options.js';
+import { daemonsServingProjectElsewhere, resolveDaemonForProject, splitBrainNote, wrongDaemonNote, } from './daemon/daemon-resolve.js';
 import { handleWatch, handleCapsules, handleGate, loadNamedFlows, resolveChangedFiles, } from './cli/cli-flow-commands.js';
-import { RETICLE_DEFAULT_PORT, ReticleDir, ReticleEnv } from '@reticlehq/core';
+import { RETICLE_DEFAULT_PORT, ReticleDir, ReticleEnv, devServersForProject, } from '@reticlehq/core';
 import { loadDotEnv } from './telemetry/dev-repo.js';
+import { licenseKeyFromEnvFiles } from './license/license-env.js';
+import { LICENSE_KEY_ENV } from './license/license.js';
 import { createNodeFileSystem } from './project/fs-port.js';
 import { affectedSavedFlows } from './flows/flow-sources.js';
 import { availableUpdate } from './update/update-nudge.js';
 import { handleUpdate, handleRollback } from './cli/cli-update-commands.js';
-import { startDaemon } from './index.js';
+import { startDaemon, RETICLE_VERIFY_DEFAULT_PORT } from './index.js';
+import { verifyEndpointMismatch } from './status-payload.js';
 import { isCloudCommand, runCloudCommand } from './cli/cloud-cli.js';
 import { SERVER_VERSION } from './version/server-version.js';
 import { log } from './log.js';
@@ -34,12 +39,12 @@ import { handleVerify } from './cli/cli-verify.js';
 import { runKill } from './cli/cli-kill.js';
 import { summarizeHunt } from './hunt/hunt-report.js';
 import { runInit } from './init/run.js';
-import { confirmInstall, nodeConfirmDeps } from './init/confirm.js';
+import { continueAfterInit } from './setup/init-runtime.js';
 import { handleDoctor } from './cli/cli-doctor.js';
 import { buildNodeIo } from './init/node-io.js';
 import { describeLicense } from './license/license.js';
 import { isLikelyDevServerPort, devServerPortWarning, readProjectPort, readProjectId, } from './cli/cli-port.js';
-import { DAEMON_INNER_COMMAND, PORT_FLAG, DRIVE_FLAG, HEADED_FLAG, HTTP_FLAG, HTTP_PORT_FLAG, HTTP_TOKEN_FLAG, parseCliArgs, CLI_USAGE, } from './cli/cli-parse.js';
+import { DAEMON_INNER_COMMAND, PORT_FLAG, parseCliArgs, CLI_USAGE } from './cli/cli-parse.js';
 import { handleFeedback, handleIdentify, handleTelemetry } from './telemetry/feedback-cli.js';
 import { installDaemonTelemetry } from './telemetry/daemon-telemetry.js';
 import { reportCliRun } from './telemetry/cli-telemetry.js';
@@ -55,14 +60,13 @@ function handleInit(parsed) {
         dryRun: parsed.dryRun,
         install: parsed.install,
         ...(parsed.app === undefined ? {} : { app: parsed.app }),
+        captureBodies: true === parsed.captureBodies,
         // The outcome is reported by confirmInstall instead, once it knows whether an app connected —
         // `init` writing files was never the same thing as `init` working (#269).
         deferOutcome: true,
+        continuesToRuntime: true !== parsed.filesOnly && true !== parsed.dryRun,
     }, io);
-    void confirmInstall(result, io, nodeConfirmDeps(parsed.port ?? RETICLE_DEFAULT_PORT)).then(() => {
-        if (!result.ok)
-            process.exit(1);
-    });
+    void continueAfterInit(parsed, result, io, cwd);
 }
 function handleServe(parsed) {
     void serveWithHonestExit(parsed);
@@ -84,6 +88,20 @@ async function serveWithHonestExit(parsed) {
         status: fetchStatus,
     });
     if (presence === PortPresence.DAEMON) {
+        // A daemon that is already up was started with ITS flags, not these — `serve` only attaches.
+        // Exiting 0 here regardless is how `--http-port` came to be accepted and ignored (#687): the
+        // running daemon kept serving whatever it was started with, and the flag vanished without a
+        // word. Ask the daemon which verify port it actually serves and refuse when it is not the one
+        // requested — a flag that cannot be honoured must say so, not report success.
+        if (parsed.http) {
+            const mismatch = verifyEndpointMismatch(await fetchStatus(parsed.port), parsed.httpPort ?? RETICLE_VERIFY_DEFAULT_PORT);
+            if (mismatch !== undefined) {
+                log('reticle_daemon_start_refused', { port: parsed.port, reason: mismatch });
+                process.stderr.write(`${mismatch}\n`);
+                process.exit(1);
+                return;
+            }
+        }
         log('reticle_daemon_already_running', { port: parsed.port });
         return;
     }
@@ -103,19 +121,7 @@ async function serveWithHonestExit(parsed) {
         process.exit(1);
         return;
     }
-    const daemonArgs = [DAEMON_INNER_COMMAND, PORT_FLAG, String(parsed.port)];
-    if (parsed.driveUrl !== undefined) {
-        daemonArgs.push(DRIVE_FLAG, parsed.driveUrl);
-        if (!parsed.headless)
-            daemonArgs.push(HEADED_FLAG);
-    }
-    if (parsed.http) {
-        daemonArgs.push(HTTP_FLAG);
-        if (parsed.httpPort !== undefined)
-            daemonArgs.push(HTTP_PORT_FLAG, String(parsed.httpPort));
-        if (parsed.httpToken !== undefined)
-            daemonArgs.push(HTTP_TOKEN_FLAG, parsed.httpToken);
-    }
+    const daemonArgs = daemonSpawnArgs(parsed);
     spawnDaemon(process.execPath, scriptPath, daemonArgs, parsed.port);
     // The child binds asynchronously and, when it cannot, exits 1 long after this process would have
     // reported success. Wait for it to ANSWER — `/status` responding is the only evidence a daemon
@@ -232,7 +238,20 @@ function withNextAction(facts) {
     const next = statusNextAction(facts);
     return next === undefined ? {} : { nextAction: next };
 }
-function handleStatus(port) {
+/**
+ * What `status` says about a project whose daemons have split in two.
+ *
+ * Both halves in one place because they are one condition asked from two positions, and a command
+ * can be standing on either. Silent — no key at all — when there is nothing to report, so a healthy
+ * run reads exactly as it did.
+ */
+function splitBrainFields(port, projectId) {
+    const home = reticleStateHome();
+    const elsewhere = splitBrainNote(port, daemonsServingProjectElsewhere(projectId, port, home, isAlive, (other) => hasProjectConnectedBefore(home, other, projectId)));
+    const note = elsewhere ?? wrongDaemonNote(port, resolveDaemonForProject(projectId, home, isAlive));
+    return note === undefined ? {} : { splitBrain: note };
+}
+export async function handleStatus(port) {
     const pid = readPid(port);
     // Durable, so it survives the daemon idling out — which is the state `status` is most often run in.
     const projectId = readProjectId(process.cwd());
@@ -245,51 +264,90 @@ function handleStatus(port) {
     // Reticle and never lists its tools looks exactly like an abandoned install from here — same idle
     // daemon, same zero sessions — and the user sees a tool that does nothing. See attach-memory.ts.
     const client = attachStatusFields(reticleStateHome(), port);
-    if (null === pid || !isAlive(pid)) {
-        // `running: false` on its own has been reported about a port that was demonstrably occupied,
-        // because the pid file is not the port. Ask the port before answering.
-        void probePresence(port, { tcpOpen: probeDaemon, status: fetchStatus }).then((presence) => {
-            const running = presenceIsUsable(presence);
-            log('reticle_status', {
-                port,
-                running,
-                presence,
-                ...(presence === PortPresence.FOREIGN ? { reason: describePresence(presence, port) } : {}),
-                // `init` promises this command says why the app has not connected. Without it the answer was
-                // `running: false` and nothing else, which reads as "Reticle is broken" for what is usually
-                // just a daemon that has not been asked to do anything yet.
-                ...withNextAction({ running, sessionCount: 0, previouslyConnected, initialized }),
-                ...client,
-            });
+    // What the dev servers themselves said. The reason this command could previously only guess at
+    // whether the app was running is that it had no way to see one; now the ones carrying Reticle
+    // announce, and the advice below stops contradicting the terminal the reader is looking at.
+    // Scoped to THIS project: the registry is machine-wide, and an unrelated app's dev server must
+    // not make this project look like it is running.
+    const devServerPorts = devServersForProject(readDevServers(reticleStateHome()), {
+        projectId,
+        root: process.cwd(),
+    }).map((d) => d.port);
+    // The failure where every individual check is green and the chain is broken: the agent's proxy and
+    // the app resolved their ports independently and landed on two different daemons. Reported from
+    // BOTH stances, because neither one can see it alone.
+    const split = splitBrainFields(port, projectId);
+    // Doctor and status must answer the same liveness question. A live pid only says that some
+    // process exists; a Reticle daemon is running only when the shared port probe reaches /status.
+    const presence = await probePresence(port, { tcpOpen: probeDaemon, status: fetchStatus });
+    if (!presenceIsUsable(presence)) {
+        log('reticle_status', {
+            port,
+            running: false,
+            presence,
+            ...(presence === PortPresence.FOREIGN ? { reason: describePresence(presence, port) } : {}),
+            // `init` promises this command says why the app has not connected. Without it the answer was
+            // `running: false` and nothing else, which reads as "Reticle is broken" for what is usually
+            // just a daemon that has not been asked to do anything yet.
+            ...withNextAction({
+                running: false,
+                sessionCount: 0,
+                previouslyConnected,
+                initialized,
+                devServerPorts,
+            }),
+            ...client,
+            ...split,
         });
         return;
     }
-    // The daemon is up — ask it for live sessions + health so status is at-a-glance, not just a pid.
-    void fetchStatus(port).then((payload) => {
-        // `status` is the second-most-run command and the one a HUMAN types. The update nudge otherwise
-        // only rides a tool result, which the majority of daemons never produce — so the people most in
-        // need of an upgrade were the ones with no path to hearing about it.
-        const update = availableUpdate();
-        const nudge = update === undefined ? {} : { updateAvailable: update };
-        if (payload === undefined) {
-            log('reticle_status', {
-                port,
+    // The daemon answered the same probe doctor trusts — ask it for live sessions + health.
+    const payload = await fetchStatus(port);
+    // `status` is the second-most-run command and the one a HUMAN types. The update nudge otherwise
+    // only rides a tool result, which the majority of daemons never produce — so the people most in
+    // need of an upgrade were the ones with no path to hearing about it.
+    const update = availableUpdate();
+    const nudge = update === undefined ? {} : { updateAvailable: update };
+    if (payload === undefined) {
+        log('reticle_status', {
+            port,
+            running: true,
+            pid,
+            ...nudge,
+            ...withNextAction({
                 running: true,
-                pid,
-                ...nudge,
-                ...withNextAction({ running: true, sessionCount: 0, previouslyConnected, initialized }),
-                ...client,
-            });
-            return;
-        }
-        const summary = summarizeStatus(payload);
-        // Only when the daemon did NOT already explain itself. It has the whole diagnosis in-process and
-        // puts it on the wire as `why`; printing a second, thinner opinion beside it risks two confident
-        // answers pointing different ways, which is worse than one.
-        const next = summary.why === undefined
-            ? withNextAction({ running: true, ...summary, previouslyConnected, initialized })
-            : {};
-        log('reticle_status', { port, running: true, pid, ...summary, ...next, ...client, ...nudge });
+                sessionCount: 0,
+                previouslyConnected,
+                initialized,
+                devServerPorts,
+            }),
+            ...client,
+            ...split,
+        });
+        return;
+    }
+    const summary = summarizeStatus(payload);
+    // Only when the daemon did NOT already explain itself. It has the whole diagnosis in-process and
+    // puts it on the wire as `why`; printing a second, thinner opinion beside it risks two confident
+    // answers pointing different ways, which is worse than one.
+    const next = summary.why === undefined
+        ? withNextAction({
+            running: true,
+            ...summary,
+            previouslyConnected,
+            initialized,
+            devServerPorts,
+        })
+        : {};
+    log('reticle_status', {
+        port,
+        running: true,
+        pid,
+        ...summary,
+        ...next,
+        ...client,
+        ...split,
+        ...nudge,
     });
 }
 /** Print the running package version (resolved once in server-version.ts). */
@@ -492,25 +550,13 @@ function handleOpen(requestedPort, url) {
     });
 }
 function handleDaemonInner(parsed) {
-    const options = {
-        port: parsed.port,
-        ...(parsed.driveUrl !== undefined
-            ? { driveUrl: parsed.driveUrl, headless: parsed.headless }
-            : {}),
-        ...(parsed.http
-            ? {
-                httpVerify: true,
-                ...(parsed.httpPort !== undefined ? { httpVerifyPort: parsed.httpPort } : {}),
-                ...(parsed.httpToken !== undefined ? { httpVerifyToken: parsed.httpToken } : {}),
-            }
-            : {}),
-    };
+    const options = daemonStartOptions(parsed);
     startDaemon(options)
         .then((server) => {
         log('reticle_daemon_ready', { port: parsed.port, pid: process.pid });
         // Daemon lifecycle telemetry: started, a one-shot project profile, the periodic counter flush,
         // and the rich summary on shutdown. All of it lives in one module — see daemon-telemetry.ts.
-        const daemonTelemetry = installDaemonTelemetry(process.cwd());
+        const daemonTelemetry = installDaemonTelemetry(process.cwd(), undefined, parsed.port);
         // Publish to the discovery registry so a build plugin can find this daemon by projectId — no
         // hand-reconciled port. Written from the child (only it knows its cwd); removePid drops it.
         const registryProjectId = readProjectId(process.cwd());
@@ -607,6 +653,14 @@ function main() {
     // Before anything reads process.env — notably the telemetry gate and the bridge's security
     // options — fold in a project-local `.env`. Values already in the environment always win.
     loadDotEnv(process.cwd());
+    // The licence key specifically is searched for HARDER than the rest of the environment, because
+    // the daemon is spawned without an explicit cwd and inherits the editor's. A key in the app's own
+    // `.env` — or in the repo root when the editor started inside the app — was never read, and the
+    // customer then produced events that said `missing`, which is indistinguishable from having no
+    // licence at all. Only the key is taken; see license-env.ts for why nothing else is.
+    const licenseKey = licenseKeyFromEnvFiles(process.cwd());
+    if (licenseKey !== undefined)
+        process.env[LICENSE_KEY_ENV] = licenseKey;
     const argv = process.argv.slice(2);
     // Every invocation passes through here — the single chokepoint for the "how often is it used / how
     // many distinct machines + projects" metrics. Fire-and-forget: a metric must never delay or fail a run.
@@ -677,7 +731,7 @@ function main() {
             void handleRestart(parsed.port, parsed.force);
             break;
         case 'status':
-            handleStatus(parsed.port);
+            void handleStatus(parsed.port);
             break;
         case 'license':
             handleLicense();

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

@@ -1,7 +1,8 @@
 import type { FileSystemPort } from '../project/fs-port.js';
 import { type CloudConfig } from './cloud-sync.js';
 /** `<reticleRoot>/cloud.json` — the project's cloud binding + sync policy (non-secret). */
-export declare const CLOUD_LINK_FILE = "cloud.json";
+/** Re-exported so the existing importers keep working; the string itself lives in core. */
+export declare const CLOUD_LINK_FILE: "cloud.json";
 /** `~/.reticle/credentials.json` — the user's per-cloud-project API keys (the only secret). */
 export declare const CREDENTIALS_FILE = "credentials.json";
 /** What the daemon mirrors to the cloud for a project. Each surface is independently toggleable. */
@@ -27,6 +28,26 @@ export interface ProjectCloud {
     /** The cloud project id this project is linked to (for display/logging); null when env-fallback. */
     projectId: string | null;
 }
+/** Look up the API key for a cloud project id in the user credentials map. */
+/**
+ * The API key this machine holds for one project ON ONE CLOUD.
+ *
+ * The store used to be keyed by cloud project id ALONE, which collides in the case that is not rare
+ * at all — it is the default. `reticle link` names every project "default", so a repo linked to a
+ * self-hosted install and a repo linked to the hosted service both claim the slot `default`, and
+ * whichever was linked last wins. Measured: two repos on one machine, and the production key was
+ * being sent to a localhost server, which answered 401.
+ *
+ * That is the same class of defect as sending a session token to a host that did not issue it, and
+ * it deserves the same answer: a credential is scoped to the cloud that minted it, and no credential
+ * at all is better than one belonging to somewhere else.
+ *
+ * Two shapes are accepted. `{ key, url }` is what is written now and is checked against the URL
+ * being dialled. A bare string is the legacy shape, has no URL to check, and is still honoured —
+ * refusing it would silently unlink every repo that predates this change, which is a worse outage
+ * than the collision. Re-linking upgrades a repo to the safe shape.
+ */
+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

package/dist/cloud/cloud-config.js

@@ -13,7 +13,8 @@ import { join } from 'node:path';
 import { ReticleDir } from '@reticlehq/core';
 import { resolveCloudConfig } from './cloud-sync.js';
 /** `<reticleRoot>/cloud.json` — the project's cloud binding + sync policy (non-secret). */
-export const CLOUD_LINK_FILE = 'cloud.json';
+/** Re-exported so the existing importers keep working; the string itself lives in core. */
+export const CLOUD_LINK_FILE = ReticleDir.CLOUD_LINK_FILE;
 /** `~/.reticle/credentials.json` — the user's per-cloud-project API keys (the only secret). */
 export const CREDENTIALS_FILE = 'credentials.json';
 const DEFAULT_SYNC_POLICY = { runs: true, memory: true, flows: true };
@@ -43,6 +44,7 @@ function parseLink(raw) {
     const sync = 'object' === typeof o.sync && o.sync !== null ? o.sync : {};
     return {
         projectId: o.projectId,
+        orgId: 'string' === typeof o.orgId && o.orgId.length > 0 ? o.orgId : undefined,
         url: o.url,
         sync: {
             runs: asBool(sync.runs, DEFAULT_SYNC_POLICY.runs),
@@ -53,12 +55,69 @@ function parseLink(raw) {
     };
 }
 /** Look up the API key for a cloud project id in the user credentials map. */
-function credentialFor(raw, projectId) {
+/**
+ * The API key this machine holds for one project ON ONE CLOUD.
+ *
+ * The store used to be keyed by cloud project id ALONE, which collides in the case that is not rare
+ * at all — it is the default. `reticle link` names every project "default", so a repo linked to a
+ * self-hosted install and a repo linked to the hosted service both claim the slot `default`, and
+ * whichever was linked last wins. Measured: two repos on one machine, and the production key was
+ * being sent to a localhost server, which answered 401.
+ *
+ * That is the same class of defect as sending a session token to a host that did not issue it, and
+ * it deserves the same answer: a credential is scoped to the cloud that minted it, and no credential
+ * at all is better than one belonging to somewhere else.
+ *
+ * Two shapes are accepted. `{ key, url }` is what is written now and is checked against the URL
+ * being dialled. A bare string is the legacy shape, has no URL to check, and is still honoured —
+ * refusing it would silently unlink every repo that predates this change, which is a worse outage
+ * than the collision. Re-linking upgrades a repo to the safe shape.
+ */
+export const credentialSlot = (url, projectId, orgId) => orgId === undefined || 0 === orgId.length
+    ? `${normalizeCloudUrl(url)}::${projectId}`
+    : `${normalizeCloudUrl(url)}::org::${orgId}::${projectId}`;
+function credentialFor(raw, projectId, url, orgId) {
     if (typeof raw !== 'object' || null === raw)
         return null;
-    const key = raw[projectId];
-    return 'string' === typeof key && key.length > 0 ? key : null;
+    const store = raw;
+    /*
+     * The ORG slot first, because cloud + project is still not an identity.
+     *
+     * `link` names every project "default", so two ACCOUNTS on one cloud both claimed the slot
+     * `<url>::default` and the last link won. Measured on a laptop: a brand-new workspace ran
+     * `reticle login` and was handed a stored key belonging to a different organisation — valid, so
+     * every validation passed, and every run it pushed would have landed in a stranger's dashboard.
+     * Keying by cloud fixed two clouds colliding; only keying by ORG fixes two tenants colliding.
+     */
+    const orgScoped = orgId === undefined ? undefined : store[credentialSlot(url, projectId, orgId)];
+    if ('string' === typeof orgScoped && orgScoped.length > 0)
+        return orgScoped;
+    /*
+     * Then the cloud+project slot, which is what every repo linked before this change still holds. It
+     * is ambiguous between tenants by construction, which is why it is consulted second and why the
+     * writer above stopped producing it as the only entry.
+     */
+    const composite = store[credentialSlot(url, projectId)];
+    if ('string' === typeof composite && composite.length > 0)
+        return composite;
+    const entry = store[projectId];
+    if ('string' === typeof entry)
+        return entry.length > 0 ? entry : null;
+    if (typeof entry !== 'object' || null === entry)
+        return null;
+    const record = entry;
+    const key = record['key'];
+    const forUrl = record['url'];
+    if ('string' !== typeof key || 0 === key.length)
+        return null;
+    // A credential stamped with a DIFFERENT cloud is not this project's credential, however much the
+    // project ids match. Refuse rather than dial somewhere with somebody else's key.
+    if ('string' === typeof forUrl && normalizeCloudUrl(forUrl) !== normalizeCloudUrl(url))
+        return null;
+    return key;
 }
+/** Trailing slashes are not identity: `https://x/` and `https://x` are one cloud. */
+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
@@ -80,7 +139,7 @@ export async function resolveProjectCloud(fs, reticleRoot, homeDir, env) {
         memory: link.sync.memory ?? DEFAULT_SYNC_POLICY.memory,
         flows: link.sync.flows ?? DEFAULT_SYNC_POLICY.flows,
     };
-    const key = credentialFor(await readJson(fs, join(homeDir, ReticleDir.ROOT, CREDENTIALS_FILE)), link.projectId);
+    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 };
 }

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

@@ -1,6 +1,6 @@
 /**
  * Optional cloud sync for saved flows. "Logged in" here means the two cloud env vars are set (written by
- * `reticle login` later; settable by hand today): the hosted URL and an API key from the Reticle Cloud
+ * `reticle login` later; settable by hand today): the hosted URL and an API key from the Reticle
  * dashboard. When present, a freshly-saved flow is pushed to `POST /v1/flows` so the team's regression
  * suite lives in the cloud — surviving refactors and runnable in CI. When absent, sync is a no-op and
  * everything stays 100% local (the "no phone-home" default: nothing leaves the machine unless you opt in).
@@ -115,21 +115,21 @@ declare const ServerVerificationSchema: z.ZodObject<{
     }>, "many">;
     summary: z.ZodString;
 }, "strip", z.ZodTypeAny, {
+    verdict: string | null;
     flows: {
         status: string;
         name: string;
     }[];
-    verificationId: string;
-    verdict: string | null;
     summary: string;
+    verificationId: string;
 }, {
+    verdict: string | null;
     flows: {
         status: string;
         name: string;
     }[];
-    verificationId: string;
-    verdict: string | null;
     summary: string;
+    verificationId: string;
 }>;
 export type ServerVerification = z.infer<typeof ServerVerificationSchema>;
 /**

package/dist/cloud/cloud-sync.js

@@ -1,6 +1,6 @@
 /**
  * Optional cloud sync for saved flows. "Logged in" here means the two cloud env vars are set (written by
- * `reticle login` later; settable by hand today): the hosted URL and an API key from the Reticle Cloud
+ * `reticle login` later; settable by hand today): the hosted URL and an API key from the Reticle
  * dashboard. When present, a freshly-saved flow is pushed to `POST /v1/flows` so the team's regression
  * suite lives in the cloud — surviving refactors and runnable in CI. When absent, sync is a no-op and
  * everything stays 100% local (the "no phone-home" default: nothing leaves the machine unless you opt in).
@@ -44,18 +44,49 @@ const CLOUD_FETCH_TIMEOUT_MS = 30_000;
 export const CLOUD_VERIFY_TIMEOUT_MS = 120_000;
 /** Names Node gives an abort: `AbortSignal.timeout` raises TimeoutError, an explicit abort AbortError. */
 const TIMEOUT_ERROR_NAMES = new Set(['TimeoutError', 'AbortError']);
+/**
+ * A header value `fetch` can actually send. Anything above U+00FF is not a valid ByteString.
+ *
+ * The one that happens in practice is an ellipsis. A dashboard masks a key as `rk_live_…` so it is
+ * never shown in full, somebody copies what they can SEE into `.env`, and the request dies deep
+ * inside undici with "Cannot convert argument to a ByteString because the character at index 15 has
+ * a value of 8230" — a byte offset into a header the user never wrote, naming no variable, no file
+ * and no fix.
+ */
+const UNSENDABLE_HEADER_CHAR = /[^ -ÿ]/;
+/** Which knob holds the credential behind a header, so the error can name the thing to go and edit. */
+const CREDENTIAL_SOURCE = {
+    authorization: `${CloudEnv.KEY} (or the session from \`reticle login\`)`,
+};
+/**
+ * Refuse a request whose headers cannot be encoded, before it is sent.
+ *
+ * Before dialling on purpose: a credential that cannot be encoded cannot succeed, so the round trip
+ * buys only a slower and less specific failure.
+ */
+function assertSendableHeaders(headers) {
+    for (const [name, value] of Object.entries(headers)) {
+        if (!UNSENDABLE_HEADER_CHAR.test(value))
+            continue;
+        const source = CREDENTIAL_SOURCE[name];
+        throw new Error(`the ${name} header carries a character that cannot be sent, which means the value is truncated — ` +
+            `a credential displayed masked as \`rk_live_…\` keeps that ellipsis when it is copied. ` +
+            `Paste the full value${source === undefined ? '' : ` into ${source}`}.`);
+    }
+}
 /**
  * The fetch every cloud call goes through. Adds the abort signal, and turns the abort into a message
  * that says what happened and what to do — a bare `AbortError` reaching a user or an agent is a riddle,
  * and the agent-facing half of this product is judged on whether its errors are actionable.
  */
 export async function cloudFetch(url, init, timeoutMs = CLOUD_FETCH_TIMEOUT_MS) {
+    assertSendableHeaders(init.headers);
     try {
         return await fetch(url, { ...init, signal: AbortSignal.timeout(timeoutMs) });
     }
     catch (err) {
         if (err instanceof Error && TIMEOUT_ERROR_NAMES.has(err.name)) {
-            throw new Error(`Reticle Cloud request timed out after ${Math.round(timeoutMs / 1000)}s: ${init.method} ${url}. ` +
+            throw new Error(`Reticle request timed out after ${Math.round(timeoutMs / 1000)}s: ${init.method} ${url}. ` +
                 `The server accepted the connection but never answered. Check the network and ${CloudEnv.URL}, then retry — ` +
                 `verification works locally without cloud.`);
         }

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

@@ -0,0 +1,110 @@
+/**
+ * The derived records that ride along with runs, and the file each one lives in.
+ *
+ * A list rather than three hand-written blocks so adding a fourth is one line and cannot be
+ * half-done — the bundle, the hashing and the reporting all walk this.
+ */
+export declare const DERIVED_RECORDS: readonly [{
+    readonly kind: "impact";
+    readonly file: "impact.json";
+}, {
+    readonly kind: "flake";
+    readonly file: "flake.json";
+}, {
+    readonly kind: "intent";
+    readonly file: "intent.json";
+}];
+export type DerivedKind = (typeof DERIVED_RECORDS)[number]['kind'];
+/** What the machine reads from disk. Injected so a cycle is testable with no filesystem at all. */
+export interface SyncSource {
+    /** Every run artifact currently on disk. */
+    runs: () => ReadonlyArray<{
+        runId: string;
+        payload: unknown;
+    }>;
+    /** Every saved flow. Small, upserted by name, so they ride along whenever anything else does. */
+    flows: () => readonly unknown[];
+    /** One derived record, or undefined when the file is absent. */
+    derived: (kind: DerivedKind) => unknown;
+}
+/** What the machine writes back. Separated from reads so a dry run is a source with no sink. */
+export interface SyncSink {
+    /** Persist the triage decisions pulled from the dashboard. */
+    writeIssues: (issues: PulledIssues) => void;
+    /** Persist the cursor and the bookkeeping. */
+    writeState: (state: CloudSyncState) => void;
+}
+/** A decision a human made on the dashboard, as the machine stores it. */
+export interface PulledIssue {
+    status: string;
+    flowName: string | null;
+    title: string;
+    at: number;
+}
+export interface PulledIssues {
+    /** Keyed by the server's fingerprint — stable across runs, which is the point of it. */
+    triage: Record<string, PulledIssue>;
+}
+/** `.reticle/cloud-state.json`. This machine's side of the conversation, never git-checked. */
+export interface CloudSyncState {
+    /** Opaque. Handed back to the server verbatim; the machine must never parse or invent one. */
+    cursor?: string;
+    lastPushAt?: number;
+    lastPullAt?: number;
+    /** The last failure, kept so `reticle sync` can say why it is behind instead of just "0 sent". */
+    lastError?: string;
+}
+export interface SyncReport {
+    ok: boolean;
+    /** Runs the server accepted this cycle. */
+    runsSent: number;
+    /** Runs it refused, with the reason, so a bad artifact is visible rather than silently stuck. */
+    runsRejected: Array<{
+        index: number;
+        reason: string;
+    }>;
+    flowsSent: number;
+    /** Which derived records had actually moved. Empty on a quiet cycle, which is the normal case. */
+    derivedSent: DerivedKind[];
+    /** Decisions collected from the dashboard. */
+    pulled: number;
+    /** True when the pull page was full — call again now rather than waiting for the next tick. */
+    morePending: boolean;
+    /**
+     * The repo holds NO artifacts at all — no runs, no flows, no derived records.
+     *
+     * Distinct from "everything here is already pushed", which is the healthy steady state and looks
+     * identical from the outside. An empty repo usually means the app announces no projectId, so its
+     * runs are pooling into a different root and this binding will never report anything. Tracked so
+     * the summary can tell a user which of the two they are looking at.
+     */
+    localIsEmpty?: boolean;
+    /** Set when the cycle could not complete. The local record is untouched either way. */
+    error?: string;
+}
+export interface SyncDeps {
+    config: {
+        url: string;
+        apiKey: string;
+    };
+    source: SyncSource;
+    sink: SyncSink;
+    state: CloudSyncState;
+    now: () => number;
+    /** Injected so a cycle can be driven against a scripted server with no network. */
+    request: (url: string, init: {
+        method: string;
+        headers: Record<string, string>;
+        body?: string;
+    }) => Promise<{
+        status: number;
+        text: string;
+    }>;
+}
+/**
+ * Run one cycle. Never throws: the local record is already safe on disk, and a sync that can take
+ * down the thing it is backing up is worse than no sync.
+ */
+export declare function runSyncCycle(deps: SyncDeps): Promise<SyncReport>;
+/** One line a human can read, for the CLI and the daemon log. */
+export declare function describeSync(report: SyncReport): string;