@reticlehq/server 3.7.0 → 3.8.1

package/dist/language/flows/replay.js

@@ -1,6 +1,6 @@
-import { REDACTED_FILL, SECRET_NAME_ARG, secretEnvKey, secretValue, } from './fields/flow-secret-field.js';
-import { FlowPredicateSchema, Verified } from '@reticlehq/core';
-import { DANGEROUS_ACTION_CONFIRM_ARG, ReticleCommand, QueryBy, } from '@reticlehq/core';
+import { SECRET_FIELD_ARG, SECRET_NAME_ARG, secretKeyForFill, secretValue, } from './fields/flow-secret-field.js';
+import { EventType, FlowPredicateSchema, MUTATING_METHODS, Verified, isDevToolingUrl, pathOf, } from '@reticlehq/core';
+import { DANGEROUS_ACTION_CONFIRM_ARG, DOCUMENT_ANCHOR_ROLE, ReticleCommand, QueryBy, isGlobalPressCall, } from '@reticlehq/core';
 import { ReticleTool, invokedFlowMissing } from '@reticlehq/core';
 import { formatStepAddress } from 'open-verification';
 import { refFor } from './flow-anchor.js';
@@ -44,11 +44,13 @@ export function queryRefs(result) {
 export function replayActionArgs(value, confirmDangerous = false, field) {
     const args = { ...asRecord(value) };
     delete args[DANGEROUS_ACTION_CONFIRM_ARG];
+    const key = field === undefined ? undefined : secretKeyForFill(args, field);
     delete args[SECRET_NAME_ARG];
+    delete args[SECRET_FIELD_ARG];
     if (confirmDangerous)
         args[DANGEROUS_ACTION_CONFIRM_ARG] = true;
-    if (REDACTED_FILL === args['value'] && field !== undefined) {
-        const supplied = secretValue(secretEnvKey(field), process.env);
+    if (key !== undefined) {
+        const supplied = secretValue(key, process.env);
         if (supplied !== undefined && supplied.length > 0)
             args['value'] = supplied;
     }
@@ -82,14 +84,26 @@ function sourceFromResult(res) {
  * 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;
+export { pathOf };
+/**
+ * Did the app send a write request in this window? A step that did is saved `writes: true`, so a
+ * replay does not repeat it unasked. The dev server's own traffic is not the app's.
+ */
+export function wroteIn(events) {
+    return events.some((event) => {
+        if (EventType.NET_REQUEST !== event.type)
+            return false;
+        const method = asString(event.data['method'])?.toUpperCase() ?? '';
+        return MUTATING_METHODS.includes(method) && !isDevToolingUrl(asString(event.data['url']));
+    });
+}
+/** `wroteIn` over a session's window, best-effort: the record must never fail the drive it records. */
+export function wroteSince(session, since) {
     try {
-        return new URL(url).pathname;
+        return wroteIn(session.eventsSince(since));
     }
     catch {
-        return undefined;
+        return false;
     }
 }
 /** What a saved flow could not keep, and the fix. See RecordedStep.unkeptExpect. */
@@ -106,7 +120,9 @@ export function captureAct(recordings, args, res,
 /** Where this step ran, so the ambient tape can be cut into journeys. See RecordedStep.route. */
 route, 
 /** The session that acted: only recordings it started take the step. */
-session) {
+session, 
+/** The act's window sent a write request; see `wroteIn`. */
+wrote = false) {
     // NO `active()` gate. `RecordingStore.capture` opens the AMBIENT tape on its first step, and that
     // branch was unreachable from here: this returned early whenever nothing was open, and the only
     // thing that opened anything was `reticle_record { action: "start" }`. So the comment on `capture`
@@ -116,6 +132,10 @@ session) {
     // 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.
+    // A click on Reticle's own panel (the HUD exposed) is not a step of the app's journey: saved, the
+    // app's flow pressed Run Harness on replay, a paid drive, under an intent that never named it.
+    if (true === asRecord(res)['reticleUi'])
+        return;
     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
@@ -132,6 +152,8 @@ session) {
     const intent = asString(args['intent'])?.trim();
     if (intent !== undefined && intent.length > 0)
         step.intent = intent;
+    if (wrote)
+        step.writes = true;
     recordings.capture(step, route, session);
 }
 /**
@@ -140,9 +162,11 @@ session) {
  * 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, session) {
+export function captureVerdictedAct(recordings, args, res, route, verified, session, 
+/** The act's window sent a write request; see `wroteIn`. */
+wrote = false) {
     const { until: _until, predicate: _predicate, ...unproved } = args;
-    captureAct(recordings, Verified.YES === verified ? args : unproved, res, route, session);
+    captureAct(recordings, Verified.YES === verified ? args : unproved, res, route, session, wrote);
 }
 /** Fold a PASSING standalone assertion into the step it proved. See RecordingStore.attachExpect. */
 export function captureAssertion(recordings, raw, session) {
@@ -205,9 +229,31 @@ function explicitTimeoutMs(args) {
  * perfectly stable anchor.
  */
 function compileAnchorArgs(r, ref, action, actArgs) {
+    const compiled = anchorArgs(r, ref, action, actArgs);
+    // The SDK says the target holds a secret (a password input, whatever its label). Carried beside
+    // the anchor so the saved flow redacts the fill by what the field IS, not by what it is called.
+    if (true === r['secret'])
+        compiled.args[SECRET_FIELD_ARG] = true;
+    return compiled;
+}
+function anchorArgs(r, ref, action, actArgs) {
+    // A document-key press with no ref ran live against no element (act-target resolves it to the
+    // document), so there is nothing to anchor and nothing missing. It used to fall through to the
+    // ref-bound branch with an empty ref, which saved as the degraded placeholder and drifted on every
+    // replay with "add a data-testid", on a step that has no element to add one to (#1559).
+    if (0 === ref.length && isGlobalPressCall({ action, args: actArgs })) {
+        return {
+            args: { by: QueryBy.ROLE, value: DOCUMENT_ANCHOR_ROLE, action, args: actArgs },
+            stable: true,
+        };
+    }
     const testid = asString(r['testid']);
     const source = sourceFromResult(r);
-    if (testid !== undefined) {
+    // Several elements carry this test id, so a replay would take the first: anchor on role and name
+    // when the element has them, else keep the test id and say how many share it.
+    const testidOf = 'number' === typeof r['testidOf'] && 1 < r['testidOf'] ? r['testidOf'] : undefined;
+    const named = asString(r['role']) !== undefined && asString(r['name']) !== undefined;
+    if (testid !== undefined && !(testidOf !== undefined && named)) {
         // The testid anchors the step; source rides along purely so a failure can name a file. Carrying
         // both was the point of separating anchor from provenance at capture time.
         const testidArgs = {
@@ -218,6 +264,8 @@ function compileAnchorArgs(r, ref, action, actArgs) {
         };
         if (source !== undefined)
             testidArgs['source'] = source;
+        if (testidOf !== undefined)
+            testidArgs['of'] = testidOf;
         return { args: testidArgs, stable: true };
     }
     // Role + NAME before component: a component/source anchor names the JSX site, so every row's copy
@@ -264,7 +312,10 @@ export function compileSequenceStep(args, res) {
         ? asRecord(res)['steps']
         : [];
     let stable = inputSteps.length > 0;
-    const subSteps = inputSteps.map((raw, i) => {
+    const subSteps = inputSteps.flatMap((raw, i) => {
+        // A step on Reticle's own panel is not a step of the app's journey, as for a single act.
+        if (true === asRecord(resolved[i])['reticleUi'])
+            return [];
         const step = asRecord(raw);
         const compiled = compileAnchorArgs(asRecord(resolved[i]), asString(step['ref']) ?? '', asString(step['action']) ?? '', replayActionArgs(step['args']));
         if (!compiled.stable)
@@ -273,7 +324,7 @@ export function compileSequenceStep(args, res) {
         // one batch, but what each step CLAIMED is per step -- folding them together would let one
         // signal answer for every click in the journey.
         const expect = enforceableExpect(step['expect']);
-        return expect === undefined ? compiled.args : { ...compiled.args, expect };
+        return [expect === undefined ? compiled.args : { ...compiled.args, expect }];
     });
     const timeoutMs = explicitTimeoutMs(args);
     return {
@@ -294,6 +345,9 @@ export function compileSequenceStep(args, res) {
  * the first of them.
  */
 async function resolveRef(session, step) {
+    // Dispatched the way it ran live: at the document, with no ref. See compileAnchorArgs.
+    if (isDocumentPress(step))
+        return { ref: '' };
     const by = asString(step.by);
     const value = asString(step.value);
     if (by === QueryBy.TESTID && value !== undefined) {
@@ -354,6 +408,19 @@ async function resolveRef(session, step) {
     }
     return { ref, note: 'replayed by stale ref (not portable across sessions)' };
 }
+/**
+ * A compiled step that presses a document key at no element (#1559).
+ *
+ * Both halves are required. The anchor alone is not enough, because a hand-edited `role: document`
+ * on a click would then dispatch that click at nothing; and the press alone is not enough, because a
+ * recorded Escape aimed at a named element keeps that element.
+ */
+export function isDocumentPress(step) {
+    return (QueryBy.ROLE === step['by'] &&
+        DOCUMENT_ANCHOR_ROLE === step['value'] &&
+        undefined === step['name'] &&
+        isGlobalPressCall({ action: step['action'], args: step['args'] }));
+}
 /** Re-execute every step of a compiled program in order, stopping at the first failure. */
 export async function replayProgram(session, program, confirmDangerous = false, 
 /**

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

@@ -19,7 +19,7 @@ import { withFileLock } from '../../../memory/project/file-lock.js';
  */
 const AssertionTiersFileSchema = z.object({
     version: z.literal(1),
-    flows: z.record(z.object({
+    flows: z.record(z.string(), z.object({
         steps: z.array(z.object({ step: z.number(), expect: z.unknown().optional() })),
         /** Source files this flow covered when it last passed — lets the gate scope DELETION findings to
          * the files that actually changed, instead of flagging every intentionally-removed flow. */

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

@@ -33,6 +33,15 @@ interface Coverage {
 }
 /** The gate's outcome when the project has recorded no flows at all — not a pass, and not a failure. */
 export declare const NO_FLOWS = "no_flows";
+/**
+ * How to get a first flow, in calls that work on every tool surface (#1547).
+ *
+ * `reticle_record` and `reticle_flow_save` are not on the default surface, so naming them bare sent
+ * an agent looking for tools it did not have, and it stopped. A journey driven with
+ * `reticle_act_and_wait` and an `until` is saved as a flow when the session ends, so that leads;
+ * recording by hand goes through `reticle_run`, which every surface advertises.
+ */
+export declare const RECORD_A_FLOW: string;
 /** The gate's flow-coverage line. `pct` and `outcome` are mutually exclusive by construction. */
 interface FlowCoverageReport {
     covered: number;

package/dist/language/flows/suite/coverage.js

@@ -6,6 +6,17 @@
  */
 /** The gate's outcome when the project has recorded no flows at all — not a pass, and not a failure. */
 export const NO_FLOWS = 'no_flows';
+/**
+ * How to get a first flow, in calls that work on every tool surface (#1547).
+ *
+ * `reticle_record` and `reticle_flow_save` are not on the default surface, so naming them bare sent
+ * an agent looking for tools it did not have, and it stopped. A journey driven with
+ * `reticle_act_and_wait` and an `until` is saved as a flow when the session ends, so that leads;
+ * recording by hand goes through `reticle_run`, which every surface advertises.
+ */
+export const RECORD_A_FLOW = 'Drive a journey with reticle_act_and_wait and an `until`: it is saved as a flow when the session ends. ' +
+    'Or record one by hand with reticle_run { tool: "reticle_record", args: { action: "start" } }, then ' +
+    'reticle_run { tool: "reticle_flow_save", args: { flowName } }.';
 /**
  * What to do about it, since the empty state is otherwise indistinguishable from success.
  *
@@ -13,7 +24,7 @@ export const NO_FLOWS = 'no_flows';
  * that errors is a second dead end on top of the first (see suggested-commands-exist.test.ts). Same
  * wording as the empty-suite verdict, which is the same situation reached from `reticle verify`.
  */
-const NO_FLOWS_NOTE = 'no flows recorded — nothing was checked. Record one with reticle_record { action: "start" }, then reticle_flow_save.';
+const NO_FLOWS_NOTE = `no flows recorded — nothing was checked. ${RECORD_A_FLOW}`;
 /**
  * Report flow coverage so that an EMPTY suite cannot be read as a passing one.
  *

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

@@ -1,3 +1,17 @@
+/**
+ * Which flows a suite run replays, resolved against the store.
+ *
+ * Shared by the MCP tool and the `reticle verify` command so the two cannot disagree about what a
+ * selection means.
+ *
+ * Lives beside the flow store rather than under `suite/` on purpose: it needs `flowsForSession`, and
+ * from `suite/` that import made `suite` and `flows` need EACH OTHER -- a mutual pair, which the
+ * reach guard forbids growing because two directories that need each other cannot be read, moved or
+ * tested apart. Here it adds no edge at all: `flows` reaching itself is nothing, and `cli -> flows`
+ * already existed. The pure rule lives in core (`selectFlows`); this is the part that has to read
+ * the files, because a label lives in one and `list` returns only names.
+ */
+import { type FlowFile } from '@reticlehq/core';
 import type { ProjectTarget } from '../../memory/project/session-root.js';
 import type { ToolDeps } from '../../surface/tools/tool-kit.js';
 /**
@@ -14,6 +28,8 @@ export declare function resolveSuiteSelection(deps: ToolDeps, target: ProjectTar
     run: string[];
     quarantined: string[];
     unmatched: string[];
+    /** Flows held back by `skipWrites`: replaying them would send their write requests again. */
+    writing?: string[];
     /** Flows in a dependency cycle — none of them ran. */
     cycles?: string[];
     /** A flow whose prerequisite is not in this run, so it did not run either. */
@@ -30,3 +46,12 @@ export declare function resolveSuiteSelection(deps: ToolDeps, target: ProjectTar
      */
     knownRoutes: string[];
 }>;
+/** The flows a replay would change real data with: a step sent, or expects, a write request. */
+export declare function writingFlows(flows: readonly FlowFile[]): string[];
+/** How the refusal of an unknown flow name opens: the error table recognizes it by these words. */
+export declare const UNKNOWN_FLOW_OPENING = "No saved flow is named";
+/**
+ * The refusal for flow names no saved flow carries, or `undefined` when every name is known. Names
+ * the flows that do exist, so the typo can be fixed in the next call.
+ */
+export declare function unknownFlowRefusal(wanted: readonly string[], known: readonly string[]): Error | undefined;

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

@@ -13,6 +13,7 @@
  */
 import { FLOW_FILE_VERSION, orderFlows, selectFlows } from '@reticlehq/core';
 import { flowsForSession } from './flow-store-for-session.js';
+import { readyForReplay, replayability } from './flow-replayable.js';
 /**
  * Resolve what a suite run should replay, and what it is holding back.
  *
@@ -55,23 +56,29 @@ export async function resolveSuiteSelection(deps, target, args) {
         ...(0 === wantedLabels.length ? {} : { labels: wantedLabels }),
     });
     /*
-     * A name the caller asked for that no file matches is still ATTEMPTED.
-     *
-     * Replay already answers a missing flow with the real reason, and that is a better answer than
-     * quietly running one fewer flow than was asked for. `unmatched` therefore reports labels, where
-     * a typo has no other way of surfacing -- ask for `@smoek` and, without this, a suite of zero
-     * flows reports a clean pass.
+     * A name no saved flow carries is refused before anything runs. It used to be ATTEMPTED, so a
+     * typo became a failed check and a failed run on the dashboard, with "check the element state" as
+     * the advice. `unmatched` still reports labels, where a typo has no other way of surfacing -- ask
+     * for `@smoek` and, without it, a suite of zero flows reports a clean pass.
      */
-    const missingNames = wantedNames.filter((name) => !names.includes(name));
+    const unknown = unknownFlowRefusal(wantedNames, names);
+    if (unknown !== undefined)
+        throw unknown;
     /*
      * Ordered AFTER selection, so a prerequisite filtered out by a label is reported rather than
      * silently pulled back in. A flow whose `login` was excluded does not run: failing it here would
      * produce a failure about the wrong thing, and quietly adding `login` back would run a flow the
      * caller did not ask for.
      */
-    const ordered = orderFlows(chosen.run);
+    /*
+     * A certify run must not change real data. A flow whose step sent a write request when it was
+     * recorded (or whose expect names one) is held back and named, never replayed, when asked.
+     */
+    const writing = true === args['skipWrites'] ? writingFlows(chosen.run) : [];
+    const ordered = orderFlows(chosen.run.filter((flow) => !writing.includes(flow.name)));
     return {
-        run: [...ordered.run.map((flow) => flow.name), ...missingNames],
+        run: ordered.run.map((flow) => flow.name),
+        ...(0 === writing.length ? {} : { writing }),
         quarantined: chosen.quarantined,
         unmatched: chosen.unmatched.filter((entry) => !wantedNames.includes(entry)),
         ...(0 === ordered.cycles.length ? {} : { cycles: ordered.cycles }),
@@ -83,3 +90,28 @@ export async function resolveSuiteSelection(deps, target, args) {
         ],
     };
 }
+/** The flows a replay would change real data with: a step sent, or expects, a write request. */
+export function writingFlows(flows) {
+    return flows
+        .filter((flow) => true === replayability(readyForReplay(flow)).writes)
+        .map((flow) => flow.name);
+}
+/** How the refusal of an unknown flow name opens: the error table recognizes it by these words. */
+export const UNKNOWN_FLOW_OPENING = 'No saved flow is named';
+/** How many saved flow names a refusal lists before it says how many more there are. */
+const KNOWN_SHOWN = 10;
+/**
+ * The refusal for flow names no saved flow carries, or `undefined` when every name is known. Names
+ * the flows that do exist, so the typo can be fixed in the next call.
+ */
+export function unknownFlowRefusal(wanted, known) {
+    const missing = wanted.filter((name) => !known.includes(name));
+    if (0 === missing.length)
+        return undefined;
+    const asked = missing.map((name) => `"${name}"`).join(', ');
+    const more = known.length - KNOWN_SHOWN;
+    const saved = 0 === known.length
+        ? 'No flows are saved for this project yet: drive the journey once and it is saved.'
+        : `Saved flows: ${known.slice(0, KNOWN_SHOWN).join(', ')}${more > 0 ? `, and ${String(more)} more (reticle_flow {action:"list"})` : ''}.`;
+    return new Error(`${UNKNOWN_FLOW_OPENING} ${asked}, so nothing ran. ${saved}`);
+}

package/dist/machine/git-tracks.d.ts

@@ -0,0 +1,6 @@
+/**
+ * True when git answers that it does not ignore `path`, so a checkout gets the file from git. False
+ * when git ignores it, and when git cannot answer. Asked once for each path in this process. `path`
+ * need not exist yet.
+ */
+export declare function gitTracks(path: string): boolean;

package/dist/machine/git-tracks.js

@@ -0,0 +1,36 @@
+/**
+ * Whether git gives a checkout a path, or ignores it. One `git check-ignore` for each path.
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { dirname } from 'node:path';
+/** Exit status of `git check-ignore` for a path that git does not ignore. */
+const CHECK_IGNORE_NOT_IGNORED = 1;
+const GIT_TIMEOUT_MS = 2_000;
+const tracked = new Map();
+/**
+ * True when git answers that it does not ignore `path`, so a checkout gets the file from git. False
+ * when git ignores it, and when git cannot answer. Asked once for each path in this process. `path`
+ * need not exist yet.
+ */
+export function gitTracks(path) {
+    const known = tracked.get(path);
+    if (known !== undefined)
+        return known;
+    const result = spawnSync('git', ['check-ignore', '-q', path], {
+        cwd: existingAncestor(path),
+        stdio: 'ignore',
+        timeout: GIT_TIMEOUT_MS,
+        windowsHide: true,
+    });
+    const answer = CHECK_IGNORE_NOT_IGNORED === result.status;
+    tracked.set(path, answer);
+    return answer;
+}
+/** `path`, or the nearest directory above it that exists: git needs a real working directory. */
+function existingAncestor(path) {
+    let dir = dirname(path);
+    while (!existsSync(dir) && dirname(dir) !== dir)
+        dir = dirname(dir);
+    return dir;
+}

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

@@ -0,0 +1,25 @@
+import type { ProjectCloud } from './cloud-config.js';
+export declare const BackgroundSyncState: {
+    readonly ON: "on";
+    readonly OPTED_OUT: "opted-out";
+    readonly UNLINKED: "unlinked";
+    readonly SIGNED_OUT: "signed-out";
+    /** The platform refused the credential (401/403). Stays stopped until the sign-in changes. */
+    readonly REFUSED: "refused";
+};
+export type BackgroundSyncState = (typeof BackgroundSyncState)[keyof typeof BackgroundSyncState];
+export interface BackgroundSyncGate {
+    state: BackgroundSyncState;
+    /** In words a person can act on. */
+    why: string;
+    /** Who is sending, when it is ON: a new value after a new sign-in or a new key. */
+    credential?: string;
+}
+/** May the daemon send this root's work now? Reads the disk, never the network. */
+export declare function backgroundSyncGate(input: {
+    reticleRoot: string;
+    cloud: ProjectCloud;
+    env: NodeJS.ProcessEnv;
+    /** The signed-in session's token for that address, or undefined. */
+    signedIn: (url: string) => string | undefined;
+}): BackgroundSyncGate;

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

@@ -0,0 +1,79 @@
+/**
+ * Whether the daemon's background sync may send a project's work.
+ *
+ * The daemon sends without anybody asking, so it sends only when every one of these holds:
+ *
+ * - Nobody switched it off: `RETICLE_BACKGROUND_SYNC=0` on the machine, `"backgroundSync": false`
+ *   in the project's `.reticle.json`.
+ * - The project is LINKED, by its own `.reticle/cloud.json`. The address comes from that link and
+ *   nowhere else. An environment address is never used: a repository's `.env` that named the
+ *   hosted service once sent another app's runs to the wrong workspace.
+ * - Somebody is signed in to that address, and this machine holds a key for the link. `reticle
+ *   logout` stops it on the next tick; `reticle login` starts it again. OR the link's key is
+ *   `RETICLE_API_KEY` from the environment, which is how CI runs: a committed `cloud.json`, a key
+ *   kept as a secret, and nobody to sign in. The address still comes from the link, and
+ *   `resolveProjectCloud` uses the environment's key only when it is for that address.
+ *
+ * `reticle sync` stays the explicit way to send now, and none of this applies to it.
+ */
+import { dirname } from 'node:path';
+import { ReticleEnv, apiKeyFrom } from '@reticlehq/core';
+import { projectSetting } from '../intent/record-request.js';
+export const BackgroundSyncState = {
+    ON: 'on',
+    OPTED_OUT: 'opted-out',
+    UNLINKED: 'unlinked',
+    SIGNED_OUT: 'signed-out',
+    /** The platform refused the credential (401/403). Stays stopped until the sign-in changes. */
+    REFUSED: 'refused',
+};
+const OFF_VALUES = new Set(['0', 'false', 'off', 'no']);
+const BACKGROUND_SYNC_SETTING = 'backgroundSync';
+/** May the daemon send this root's work now? Reads the disk, never the network. */
+export function backgroundSyncGate(input) {
+    const { reticleRoot, cloud, env, signedIn } = input;
+    if (OFF_VALUES.has((env[ReticleEnv.BACKGROUND_SYNC] ?? '').toLowerCase())) {
+        return {
+            state: BackgroundSyncState.OPTED_OUT,
+            why: `off on this machine (${ReticleEnv.BACKGROUND_SYNC})`,
+        };
+    }
+    if (false === projectSetting(dirname(reticleRoot), BACKGROUND_SYNC_SETTING)) {
+        return {
+            state: BackgroundSyncState.OPTED_OUT,
+            why: `off in this project ("${BACKGROUND_SYNC_SETTING}": false in .reticle.json)`,
+        };
+    }
+    // `link` is set only from the project's own link file; an environment key leaves it unset.
+    if (cloud.link === undefined) {
+        return {
+            state: BackgroundSyncState.UNLINKED,
+            why: 'this project is not linked: run `reticle connect`',
+        };
+    }
+    if (null === cloud.config) {
+        return {
+            state: BackgroundSyncState.SIGNED_OUT,
+            why: cloud.reason ?? 'no key for this link: run `reticle connect`',
+        };
+    }
+    if (cloud.config.apiKey === apiKeyFrom(env)) {
+        return {
+            state: BackgroundSyncState.ON,
+            why: `sends to ${cloud.config.url} with ${ReticleEnv.API_KEY}`,
+            credential: cloud.config.apiKey,
+        };
+    }
+    const token = signedIn(cloud.config.url);
+    if (token === undefined) {
+        return {
+            state: BackgroundSyncState.SIGNED_OUT,
+            why: `nobody is signed in to ${cloud.config.url}: run \`reticle connect --url ${cloud.config.url}\``,
+        };
+    }
+    return {
+        state: BackgroundSyncState.ON,
+        why: `sends to ${cloud.config.url}`,
+        credential: `${cloud.config.apiKey}\u0000${token}`,
+    };
+}

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

@@ -1,4 +1,4 @@
-import type { FileSystemPort } from '../project/fs/fs-port.js';
+import { type FileSystemPort } from '../project/fs/fs-port.js';
 import { type CloudConfig } 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. */
@@ -31,6 +31,17 @@ interface SyncPolicy {
      * a project that keeps its runs local has not agreed to send pictures of its pages either.
      */
     screenshots: boolean;
+    /**
+     * Push the frames filmed between steps (about one a second while Reticle drives a tab), which the
+     * dashboard plays as the run's video. Follows `screenshots` when the link does not say.
+     */
+    video: boolean;
+    /**
+     * Upload the episode log (every tool call and its whole result). Never a default and never
+     * inherited from another switch: only `"episodes": true` here, and even then only to a workspace
+     * that consented to share its data. See `episodesMaySync`.
+     */
+    episodes?: boolean;
 }
 /** Where a verification actually executes. Reserved for the hosted-runner path; default local. */
 export declare const VerifyMode: {