@reticlehq/server 3.3.0 → 3.5.0

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();

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

@@ -13,6 +13,12 @@ declare const DERIVED_RECORDS: readonly [{
 }, {
     readonly kind: "intent";
     readonly file: "intent.json";
+}, {
+    readonly kind: "envelopes";
+    readonly file: "envelopes.json";
+}, {
+    readonly kind: "assertion-tiers";
+    readonly file: "assertion-tiers.json";
 }];
 type DerivedKind = (typeof DERIVED_RECORDS)[number]['kind'];
 /** What the machine reads from disk. Injected so a cycle is testable with no filesystem at all. */
@@ -69,11 +75,52 @@ export interface CloudSyncState {
      * fills the gap the server declared and never overrides the server on a question it answered.
      */
     sentRunIds?: string[];
+    /**
+     * The content hash of each run as the server last ACCEPTED it, for the runs still held locally.
+     *
+     * A run is not immutable: a session's live drive run is rewritten after every verdict under the
+     * same id. Sending by id alone delivered its first version and never the rest, so the server held
+     * a tab's first few verdicts and none after. The server upserts a run by id, so a changed run is
+     * simply sent again; this is how the machine tells a changed run from one it already delivered.
+     */
+    sentRunHashes?: Record<string, string>;
+    /**
+     * Runs the server refused, by run id: its reason, and the two things that could change the answer
+     * (a hash of the run file, and of what the platform said it reads). A refused run is not offered
+     * again until one of them changes; re-offering it every cycle got the same refusal and dragged
+     * every flow and capsule along with it.
+     */
+    refusedRuns?: Record<string, RefusedRun>;
+    /**
+     * Hashes of the flow set and the capsule set the platform last answered for. A flow saved or
+     * edited with no new run used to wait for one, because flows only rode along with other data; now
+     * a changed set is sent on its own, and an unchanged one is not sent again.
+     */
+    sentFlowsHash?: string;
+    sentCapsulesHash?: string;
+    /**
+     * A flow or capsule set the platform refused, kept so the refusal stays visible on the cycles that
+     * do not resend it, and so the set is offered again once it changes or the platform reads more.
+     */
+    refusedSets?: Partial<Record<SetPart, RefusedSet>>;
+}
+type SetPart = 'flow' | 'capsule';
+interface RefusedSet {
+    hash: string;
+    acceptsHash: string;
+    count: number;
+    reason: string;
+}
+interface RefusedRun {
+    reason: string;
+    payloadHash: string;
+    acceptsHash: string;
 }
 export interface SyncReport {
     /**
-     * False if the cycle failed or any offered run was rejected. A completed HTTP exchange alone
-     * is not a successful push. Accepted counts and rejection reasons still describe partial success.
+     * False if the cycle failed, the server refused anything, or a run or flow was held back for a
+     * version the platform does not read. A completed HTTP exchange alone is not a successful push.
+     * A record KIND the platform does not know yet is reported in `held` and does not fail it.
      */
     ok: boolean;
     /** Runs the server accepted this cycle. */
@@ -86,8 +133,29 @@ export interface SyncReport {
     flowsSent: number;
     /** Capsules the server accepted. Zero when it reported none, which includes not knowing the field. */
     capsulesSent: number;
-    /** Which derived records had actually moved. Empty on a quiet cycle, which is the normal case. */
+    /** Derived records the server ACCEPTED this cycle. Empty on a quiet cycle, the normal case. */
     derivedSent: DerivedKind[];
+    /**
+     * Everything else the server refused: a flow, a capsule, or a derived record. Each reason is a
+     * complete sentence naming the item, because this is often read from a background daemon's log.
+     */
+    refused: Refusal[];
+    /**
+     * What was deliberately NOT sent, and why: a record kind or a file version this platform does
+     * not read. Sending it would only be refused again on every cycle.
+     */
+    held: string[];
+    /** Runs refused on an earlier cycle and not offered again, because nothing has changed since. */
+    notRetried: Array<{
+        runId: string;
+        reason: string;
+    }>;
+    /** Flow or capsule sets refused on an earlier cycle and not offered again. */
+    setsNotRetried: Array<{
+        part: SetPart;
+        count: number;
+        reason: string;
+    }>;
     /** Decisions collected from the dashboard. */
     pulled: number;
     /** True when the pull page was full — call again now rather than waiting for the next tick. */
@@ -104,6 +172,12 @@ export interface SyncReport {
     /** Set when the cycle could not complete. The local record is untouched either way. */
     error?: string;
 }
+/** One item the server refused that is not a run. */
+export interface Refusal {
+    /** `flow`, `capsule`, or the derived record's kind. */
+    part: string;
+    reason: string;
+}
 interface SyncDeps {
     config: {
         url: string;