@relayflows/sdk 2.0.49 → 2.0.51

package/src/authored-worker-step.ts

@@ -20,6 +20,7 @@ import { alsoRecord, recordAuthoredChild } from './authored-step-index.js';
 import type { StepFailedDetails } from './failure-kinds.js';
 import { LOCAL_AGENT_WORKSPACE } from './local-agent-pins.js';
 import { authoredWorkerSlots, type AuthoredWorkerSlots } from './worker-slots.js';
+import { validateStepSecrets } from './step-secrets.js';
 
 const AGENT_TIMEOUT = Symbol('declared agent timeout');
 const WORKSPACE_PERMISSION_ANNOTATION = /:\s*(readonly|readwrite)\s*$/i;
@@ -177,6 +178,8 @@ export function authoredWorkerRunner(
       }
     },
     async agent(id: string, options: AgentOptions, verification?: NamedGate): Promise<AgentResult> {
+      const secrets = validateStepSecrets((options as AgentOptions & { secrets?: unknown }).secrets,
+        agentEnvironment ?? process.env);
       if (options.workspace !== undefined && localAgentStream !== undefined) {
         throw new AuthoredFlowExecutionError('unsupported_workspace_permission',
           'The local agent worker accepts stream-only steps. Remove workspace or attach a worker that holds its revision pins.');
@@ -277,6 +280,7 @@ export function authoredWorkerRunner(
         : snapshotJsonValue(permissions, 'f.agent options.permissions') as unknown as PermissionsSpec;
       const output = await run({
         id, type: 'agent', instruction: options.task,
+        ...(secrets.length ? { secrets } : {}),
         ...(timeoutMs === undefined ? {} : { timeoutMs }),
         ...(permissionsSnapshot === undefined ? {} : { permissions: permissionsSnapshot }),
         ...(localAgentStream === undefined ? {} : { surfaces: {
@@ -323,11 +327,14 @@ export function authoredWorkerRunner(
       }
       const snapshot = options === undefined ? undefined : snapshotJsonValue(options, 'f.llm options');
       if (snapshot !== undefined && (typeof snapshot !== 'object' || snapshot === null || Array.isArray(snapshot)
-        || Object.keys(snapshot).some(key => !['output', 'cli', 'model'].includes(key)))) {
-        throw new AuthoredFlowExecutionError('llm_cli_unresolved', 'f.llm options accepts only output, cli, and model.');
+        || Object.keys(snapshot).some(key => !['output', 'cli', 'model', 'secrets'].includes(key)))) {
+        throw new AuthoredFlowExecutionError('llm_cli_unresolved', 'f.llm options accepts only output, cli, model, and secrets.');
       }
+      const secrets = validateStepSecrets((snapshot as { secrets?: unknown } | undefined)?.secrets,
+        agentEnvironment ?? process.env);
       const output = await run({
         id, type: 'llm', prompt, ...snapshot as unknown as LlmOptions,
+        ...(secrets.length ? { secrets } : {}),
         ...(verification === undefined ? {} : { verification }),
       });
       if (options === undefined && typeof output !== 'string') {
@@ -358,6 +365,7 @@ export function authoredDeterministicRunner(
   function lower<T>(
     id: string, command: string, terminal: boolean, leaseMs: number | undefined,
     verification: NamedGate | undefined, onNonZero: 'record' | undefined,
+    secrets: string[] | undefined,
     read: (outcome: import('./protocol.js').RunOutcome) => Promise<T>,
   ): Promise<T> {
     const spec = toKernelSpec(compileSpec({
@@ -365,6 +373,7 @@ export function authoredDeterministicRunner(
       name: `${name}/${id}`,
       steps: [{
         id, type: 'deterministic', command,
+        ...(secrets?.length ? { secrets } : {}),
         ...(leaseMs === undefined ? {} : { lease_ms: leaseMs }),
         ...(onNonZero === undefined ? {} : { onNonZero }),
         ...(verification === undefined ? {} : { verification }),
@@ -380,12 +389,14 @@ export function authoredDeterministicRunner(
     if (terminal) return journal.runStart(spec, undefined, admissionKey).then(consume);
     return budget.execute(journal, spec, consume, admissionKey);
   }
-  const lowerRun = (id: string, command: string, terminal = false, leaseMs?: number, verification?: NamedGate): Promise<string> =>
-    lower(id, command, terminal, leaseMs, verification, undefined,
+  const lowerRun = (id: string, command: string, terminal = false, leaseMs?: number, verification?: NamedGate,
+    secrets?: string[]): Promise<string> =>
+    lower(id, command, terminal, leaseMs, verification, undefined, secrets,
       outcome => readSuccessfulOutput(journal, outcome, id, journalSteps, context));
   /** `f.run(..., { onNonZero: 'record' })`: the exit code is the result, not a throw. */
-  lowerRun.recording = (id: string, command: string, leaseMs?: number, verification?: NamedGate): Promise<RecordedRunOutcome> =>
-    lower(id, command, false, leaseMs, verification, 'record',
+  lowerRun.recording = (id: string, command: string, leaseMs?: number, verification?: NamedGate,
+    secrets?: string[]): Promise<RecordedRunOutcome> =>
+    lower(id, command, false, leaseMs, verification, 'record', secrets,
       outcome => readRecordedOutcome(journal, outcome, id, journalSteps, context));
   return lowerRun;
 }

package/src/cli/check.ts

@@ -492,8 +492,8 @@ function findConfig(start: string): string | undefined {
 function systemProbes(flowDirectory: string, config: ProjectConfig, environment?: NodeJS.ProcessEnv): PreflightProbes {
   return {
     helper: helperReady,
-    cli: (cli, source, model, execution) => probeCli(cli,
-      source === 'project' ? config.directory : flowDirectory, model, execution, environment),
+    cli: (cli, source, model, execution, secrets) => probeCli(cli,
+      source === 'project' ? config.directory : flowDirectory, model, execution, environment, secrets),
     executor: (trigger) => config.executors.includes(trigger.executor),
     // A deterministic step runs in the daemon's working directory — the
     // directory `flows run` was invoked from, or Cloud's code mount — not in
@@ -521,7 +521,7 @@ function bindResolvedCliPaths(
       if (resolution === undefined) return step;
       const directory = resolution.source === 'project' ? configDirectory : flowDirectory;
       const managed = step.type === 'agent' && communicationInstruction(step.instruction) !== undefined;
-      const outcome = probeCache.get(cliProbeKey(resolution, managed));
+      const outcome = probeCache.get(cliProbeKey(resolution, managed, step.secrets));
       const executable = outcome !== undefined && 'result' in outcome
         ? outcome.result.executable
         : undefined;

package/src/cli/cli-probe.ts

@@ -7,6 +7,7 @@ import { adapterIdentification, authenticationProbe, classifyModelProbeFailure,
 import { MODEL_ENV } from '../worker-cli.js';
 import { CliProbeError, type CliProbeResult } from '../preflight.js';
 import { pinCliAlias, pinCliAliasSync } from './pinned-cli-alias.js';
+import { agentProbeEnvironment } from '../step-secrets.js';
 
 interface ProbeRequest {
   argv0?: string;
@@ -30,7 +31,8 @@ export async function probeCliAsync(...args: Parameters<typeof probeSequence>):
 }
 
 export function resolveExecutable(command: string, directory: string, environment: NodeJS.ProcessEnv = process.env): string | undefined {
-  return driveSync(executableSequence(command, directory, environment));
+  return driveSync(executableSequence(command, directory,
+    agentProbeEnvironment(environment, 'relayflows-wrapper-v1')));
 }
 
 function driveSync<T>(sequence: Generator<ProbeRequest, T, ProbeOutput>): T {
@@ -94,23 +96,24 @@ function* probeSequence(
   model?: string,
   execution?: 'managed',
   sourceEnvironment: NodeJS.ProcessEnv = process.env,
+  grants?: string[],
 ): Generator<ProbeRequest, CliProbeResult, ProbeOutput> {
-  const executable = yield* executableSequence(cli, directory, sourceEnvironment);
+  const kind = cliAdapterKind(cli);
+  const environment = execution === 'managed'
+    ? { ...brokerEnvironment(sourceEnvironment), ...agentEnvironment(cli, sourceEnvironment, grants) }
+    : agentProbeEnvironment(sourceEnvironment, kind, grants);
+  const executable = yield* executableSequence(cli, directory, environment);
   if (executable === undefined) return { exists: false, authenticated: false };
   // The declaration selects the adapter; the canonical executable selects
   // the bytes. Package-manager links commonly name `claude` or `codex` while
   // targeting a generic `cli.js`, whose basename must not rewrite the adapter
   // contract after resolution.
-  const kind = cliAdapterKind(cli);
   // Relay owns interactive CLI launch/injection. Its generic PTY path is not
   // the headless wrapper protocol; do not demand that protocol from Gemini,
   // Cursor, OpenCode, or other interactive tools. Never invent an auth pass.
   if (execution === 'managed' && kind === 'relayflows-wrapper-v1') {
     return { exists: true, supported: true, authenticated: 'unverified', executable };
   }
-  const environment = execution === 'managed'
-    ? { ...brokerEnvironment(sourceEnvironment), ...agentEnvironment(cli, sourceEnvironment) }
-    : sourceEnvironment;
   const probe = (invocation: CliInvocation): ProbeRequest => ({
     executable,
     argv0: basename(cli),

package/src/cli/cloud-run.ts

@@ -9,8 +9,9 @@ import type { CliIo } from '../cli.js';
 
 /** Presentation only: the central CLI parser owns argv; the SDK owns the lifecycle. */
 export async function runCloudCli(
-  { value: path, json, wait, input, syncCode, noConnect = false }: {
+  { value: path, json, wait, input, syncCode, noConnect = false, budgetMinutes }: {
     value: string; json: boolean; wait: boolean; input: string | undefined; syncCode: boolean; noConnect?: boolean;
+    budgetMinutes?: number;
   },
   io: CliIo,
   /**
@@ -27,7 +28,11 @@ export async function runCloudCli(
   let submitting = false;
   let harnesses: readonly string[] = [];
   try {
-    const options: RunInCloudOptions = { signal, onSubmit: () => { submitting = true; } };
+    const options: RunInCloudOptions = {
+      signal,
+      onSubmit: () => { submitting = true; },
+      ...(budgetMinutes === undefined ? {} : { runBudgetMinutes: budgetMinutes }),
+    };
     if (isAuthoredFlowPath(path)) {
       // Same parse as a local direct run, so a file-or-inline argument means
       // the same thing on both sides of `--cloud`.

package/src/cli-commands.ts

@@ -300,7 +300,7 @@ export const CLI_VERBS = [
   },
   {
     name: 'run',
-    description: 'Run a flow locally, or submit it to Cloud with --cloud',
+    description: 'Run locally with an Observer link (workspace key) or --cloud-mirror (Cloud dashboard), or submit with --cloud',
     args: [{ name: 'flow', description: 'flow.yaml, flow.ts, spec.json, or <flow>@sha256:<digest>', required: true }],
     options: [
       ...LOCAL_EXECUTION_OPTIONS,
@@ -309,6 +309,10 @@ export const CLI_VERBS = [
       { flags: '--reuse-from <run-id>', description: 'Reuse memoized step outputs from an earlier run' },
       { flags: '--cloud', description: 'Submit to Agent Relay Cloud instead of running locally' },
       { flags: '--wait', description: 'With --cloud, poll until the hosted run reaches a terminal state' },
+      {
+        flags: '--budget-minutes <n>',
+        description: 'With --cloud, set this admission’s run budget (30-180 minutes); a resume does not inherit it',
+      },
       {
         flags: '--sync-code',
         description: 'With --cloud, upload the working directory as the run’s tree; pull results back with `flows sync`',

package/src/cli.ts

@@ -48,6 +48,7 @@ import { runCloudLogsFollow, runCloudStatusWatch } from './cli/cloud-live.js';
 import { transcriptTailSource } from './transcript-tail.js';
 import { checkTypeScriptFlow } from './cli/check-typescript.js';
 import { runCloudCli } from './cli/cloud-run.js';
+import { isCloudRunBudgetMinutes } from './cloud-run.js';
 import { runCloudSyncCli } from './cli/cloud-sync.js';
 import { parseCloudDeployArgs, runCloudDeployCli, runCloudDeploymentsCli, runCloudUndeployCli, type CloudDeployArgs } from './cli/cloud-deploy.js';
 import { runCloudRollbackCli, runCloudVersionsCli } from './cli/cloud-versions.js';
@@ -100,7 +101,7 @@ export type ParsedArgs =
   | BuildArgs
   | DeployArgs
   | { command: 'serve-webhook'; dataDir: string; port: number; admitted?: readonly string[] }
-  | { command: 'cloud-run'; value: string; json: boolean; wait: boolean; input: string | undefined; syncCode: boolean; noConnect: boolean }
+  | { command: 'cloud-run'; value: string; json: boolean; wait: boolean; input: string | undefined; syncCode: boolean; noConnect: boolean; budgetMinutes: number | undefined }
   | { command: 'sync'; runId: string; json: boolean; root: string; dryRun: boolean }
   | CloudDeployArgs
   | { command: 'deployments'; json: boolean }
@@ -147,8 +148,8 @@ const USAGE = [
   'flows check [--against-daemon|--no-daemon-check] [--watch] [--json] [--explain-warnings] <flow.ts|flow.yaml|spec.json>',
   'flows serve-webhook --data-dir <dir> --port <p> [--allow <name>[,<name>]]',
   'flows run [--json] [--no-spawn] [--no-observer-link] [--cloud-mirror] [--detach] [--data-dir <dir>] [--local-agent [--agent-capacity <n>]] [--reuse-from <run-id>] <flow.yaml|spec.json>',
-  'flows run --cloud [--json] [--wait] [--sync-code] [--no-connect] <flow.yaml|spec.json>',
-  'flows run --cloud [--json] [--wait] [--sync-code] [--no-connect] <flow.ts> --input <inline-json-or-file>',
+  'flows run --cloud [--json] [--wait] [--sync-code] [--no-connect] [--budget-minutes <n>] <flow.yaml|spec.json>',
+  'flows run --cloud [--json] [--wait] [--sync-code] [--no-connect] [--budget-minutes <n>] <flow.ts> --input <inline-json-or-file>',
   'flows sync [--json] [--dry-run] [--dir <path>] <run-id>',
   'flows run [--json] [--no-spawn] [--no-observer-link] [--cloud-mirror] [--detach] [--data-dir <dir>] [--local-agent [--agent-capacity <n>]] <flow.ts> --input <inline-json-or-file>',
   'flows tick start --schedule-id <id> --interval-ms <ms> [--epoch-ms <ms>] [--max-catch-up <n>] [--poll-interval-ms <ms>] [--data-dir <dir>] <spec.json>',
@@ -253,6 +254,15 @@ export async function runCli(
     return 2;
   }
 
+  if (parsed.command === 'run' && !parsed.json && !parsed.noObserverLink
+    && !(parsed.cloudMirror || cloudMirrorRequested(process.env))) {
+    const link = resolveObserverLinkEnv(process.env);
+    if (!link.suppressed && link.workspaceKey === undefined) {
+      io.stderr('Observer unavailable: no workspace key configured; set RELAYCAST_WORKSPACE_KEY or configure '
+        + '~/.agentworkforce/relay/workspaces.json for an Observer link, or pass --cloud-mirror for the Cloud dashboard');
+    }
+  }
+
   if ((parsed.command === 'run' || parsed.command === 'resume') && parsed.detach) {
     const result = await startDetachedRun(args, {
       ...parsed, ...(options.selfCommand === undefined ? {} : { selfCommand: options.selfCommand }),
@@ -536,9 +546,9 @@ async function checkAuthoredFlowComposed(path: string): Promise<{ report: CheckR
 
 /**
  * Resolve the pending observer-mint into a URL (or nothing), and route any
- * mint warning to stderr under a `[observer]` label. Silent-skip (`undefined`
- * input) prints nothing at all, so a workspace with no observer configured
- * produces no observer output on stderr or stdout.
+ * mint warning to stderr under a `[observer]` label. An `undefined` input
+ * prints nothing here; any missing-key hint was already emitted while the
+ * observer session was configured.
  */
 async function observerUrlFrom(
   mint: Promise<{ observerUrl?: string; warning?: string }> | undefined,
@@ -729,6 +739,7 @@ function parseArgs(args: readonly string[]): ParsedArgs | undefined {
   let wait = false;
   let syncCode = false;
   let noConnect = false;
+  let budgetMinutes: number | undefined;
   let localAgent = false;
   let detach = false;
   let agentCapacity: number | undefined;
@@ -754,6 +765,13 @@ function parseArgs(args: readonly string[]): ParsedArgs | undefined {
       else noConnect = true;
       continue;
     }
+    if (argument === '--budget-minutes') {
+      const value = args[++index];
+      if (command !== 'run' || budgetMinutes !== undefined || value === undefined || !/^[0-9]+$/.test(value)) return undefined;
+      budgetMinutes = Number(value);
+      if (!isCloudRunBudgetMinutes(budgetMinutes)) return undefined;
+      continue;
+    }
     if (argument === '--detach') {
       if (command === 'check' || detach) return undefined;
       detach = true;
@@ -865,9 +883,9 @@ function parseArgs(args: readonly string[]): ParsedArgs | undefined {
     if (detach || allowHumanInfluenced || sawDataDir || !spawn || localAgent || noObserverLink || cloudMirror
       || reuseFromRunId !== undefined) return undefined;
     if (sawInput && !isAuthoredFlowPath(positionals[0]!)) return undefined;
-    return { command: 'cloud-run', value: positionals[0]!, json, wait, input, syncCode, noConnect };
+    return { command: 'cloud-run', value: positionals[0]!, json, wait, input, syncCode, noConnect, budgetMinutes };
   }
-  if (wait || syncCode || noConnect) return undefined;
+  if (wait || syncCode || noConnect || budgetMinutes !== undefined) return undefined;
   if (reuseFromRunId !== undefined && isAuthoredFlowPath(positionals[0]!)) return undefined;
 
   if (command === 'run' && input !== undefined && !isAuthoredFlowPath(positionals[0]!)) return undefined;

package/src/cloud-http.ts

@@ -290,7 +290,7 @@ export function isCloudRecord(value: unknown): value is Record<string, unknown>
   return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 
-function transportError(error: unknown): CloudFlowError {
+export function transportError(error: unknown): CloudFlowError {
   const cause = error instanceof Error ? error.cause : undefined;
   const code = isCloudRecord(cause) ? cause.code : undefined;
   const transient = (error instanceof Error && error.name === 'TimeoutError')

package/src/cloud-run.ts

@@ -14,12 +14,23 @@ import {
   type CloudConnectionOptions,
 } from './cloud-http.js';
 import { cloudRunState, isCloudRunActive, type CloudRunState } from './cloud-run-record.js';
-import { packWorkingTree, prepareCloudSync, uploadCloudCode } from './cloud-sync.js';
+import { canUseCodeCache, packWorkingTree, prepareCloudSync, sha256PackedTree, uploadCloudCode } from './cloud-sync.js';
 
 export type CloudFlowSource = FlowSpec | { path: string };
+export const MIN_CLOUD_RUN_BUDGET_MINUTES = 30;
+export const MAX_CLOUD_RUN_BUDGET_MINUTES = 180;
+
+export function isCloudRunBudgetMinutes(value: number): boolean {
+  return Number.isSafeInteger(value)
+    && value >= MIN_CLOUD_RUN_BUDGET_MINUTES
+    && value <= MAX_CLOUD_RUN_BUDGET_MINUTES;
+}
+
 export interface RunInCloudOptions extends CloudConnectionOptions {
   /** Existing Cloud workspace to run in; provisioning/authorization remains server-side. */
   workspaceId?: string;
+  /** Hosted run deadline in minutes. Applies to this admission only, not a later resume. */
+  runBudgetMinutes?: number;
   /** Exact JSON input. Required at runtime for authored .flow.ts; refused for declarative source. */
   input?: JsonValue;
   /**
@@ -54,7 +65,7 @@ export interface CloudRunReceipt {
   specHash: string;
   /** Authenticated run API resource; this is not a public sharing URL. */
   apiUrl: string;
-  /** Present when a working tree was synced: what was uploaded, by count and size. */
+  /** Present when a working tree was synced: its file count and uncompressed size. */
   synced?: { files: number; bytes: number; skippedLinks: string[] };
 }
 export interface CloudAuthoredAuthority {
@@ -108,6 +119,31 @@ function snapshotEnvSecrets(value: unknown): Record<string, string> | undefined
   return Object.keys(copy).length === 0 ? undefined : copy;
 }
 
+/**
+ * A Cloud refusal is Cloud's own text. Should any of it ever quote an
+ * envSecrets value — the message, or a field such as `expected`/`received` —
+ * keep only a safe refusal code and drop the rest, so the value never reaches
+ * an error message, a log line or a caller's error report.
+ */
+function withheldIfQuotingSecret(error: unknown, envSecrets: Record<string, string> | undefined): unknown {
+  if (envSecrets === undefined || !(error instanceof CloudFlowError) || error.refusal === undefined) return error;
+  const values = Object.values(envSecrets).filter(value => value.length > 0);
+  const quotes = (text: string): boolean => values.some(value => text.includes(value));
+  if (!quotes(error.message) && !refusalStrings(error.refusal).some(quotes)) return error;
+  const code = quotes(error.refusal.code) ? 'withheld' : error.refusal.code;
+  return new CloudFlowError(error.code,
+    `Cloud refused (${code}); its message was withheld because it quoted an envSecrets value.`,
+    error.status, { code, error: 'withheld: quoted an envSecrets value' });
+}
+
+/** Every string anywhere in a refusal, so a field added later is checked too. */
+function refusalStrings(value: unknown): string[] {
+  if (typeof value === 'string') return [value];
+  if (Array.isArray(value)) return value.flatMap(refusalStrings);
+  if (value !== null && typeof value === 'object') return Object.values(value).flatMap(refusalStrings);
+  return [];
+}
+
 /**
  * Submit a declarative flow to Cloud's pinned v2 runtime. Compilation only
  * happens here; Cloud owns provisioning and the Rust engine owns execution.
@@ -252,6 +288,10 @@ export async function runInCloud(
 ): Promise<CloudRunReceipt> {
   // Validate locally first: resolving the connection may refresh a stored
   // login, which posts the refresh token and rotates the credential file.
+  if (options.runBudgetMinutes !== undefined && !isCloudRunBudgetMinutes(options.runBudgetMinutes)) {
+    throw new CloudFlowError('configuration',
+      `runBudgetMinutes must be an integer from ${MIN_CLOUD_RUN_BUDGET_MINUTES} to ${MAX_CLOUD_RUN_BUDGET_MINUTES}.`);
+  }
   const envSecrets = snapshotEnvSecrets(options.envSecrets);
   const submission = await prepareCloudSubmission(flow, options);
   const { baseUrl } = await resolveCloudConnection(options);
@@ -260,31 +300,44 @@ export async function runInCloud(
   // under it, so the run request below names code Cloud already holds. A
   // refused backend or failed upload therefore never leaves a launched run
   // pointing at a tree that is not there.
-  let synced: { runId: string; codeKey: string; files: number; bytes: number; skippedLinks: string[] } | undefined;
+  let synced: { runId: string; codeKey: string; codeCacheHit: boolean; files: number; bytes: number; skippedLinks: string[] } | undefined;
   if (options.syncCode !== undefined) {
-    const prepared = await prepareCloudSync(options);
     options.signal?.throwIfAborted();
     const packed = await packWorkingTree(options.syncCode.root);
+    let prepared: Awaited<ReturnType<typeof prepareCloudSync>>;
     try {
       options.signal?.throwIfAborted();
-      await uploadCloudCode(prepared, packed, options);
+      const digest = canUseCodeCache(packed) ? await sha256PackedTree(packed) : undefined;
+      prepared = await prepareCloudSync(options, digest);
+      options.signal?.throwIfAborted();
+      if (!prepared.codeCacheHit) await uploadCloudCode(prepared, packed, options);
     } finally {
       packed.dispose();
     }
-    synced = { runId: prepared.runId, codeKey: prepared.codeKey, files: packed.files.length, bytes: packed.bytes,
+    synced = { runId: prepared.runId, codeKey: prepared.codeKey, codeCacheHit: prepared.codeCacheHit === true,
+      files: packed.files.length, bytes: packed.bytes,
       skippedLinks: packed.skippedLinks };
   }
   options.signal?.throwIfAborted();
   options.onSubmit?.();
   let result: unknown;
   try {
-    result = await cloudFetch('/api/v1/workflows/run', options, { method: 'POST', detail: true, body: JSON.stringify({
+    // A cache hit is copied into the run prefix after admission. The R2 copy
+    // may outlast the normal 30s request budget; explicit caller limits win.
+    const submitOptions = synced?.codeCacheHit
+      ? { ...options, requestTimeoutMs: options.requestTimeoutMs ?? 300_000 }
+      : options;
+    result = await cloudFetch('/api/v1/workflows/run', submitOptions, { method: 'POST', detail: true, body: JSON.stringify({
       ...cloudSubmissionBody(submission),
       ...(options.workspaceId === undefined ? {} : { workspaceId: options.workspaceId }),
+      ...(options.runBudgetMinutes === undefined ? {} : { relayflowV2RunBudgetMinutes: options.runBudgetMinutes }),
       ...(synced === undefined ? {} : { runId: synced.runId, s3CodeKey: synced.codeKey }),
       ...(envSecrets === undefined ? {} : { envSecrets }),
     }) });
-  } catch (error) {
+  } catch (caught) {
+    // Withhold first: every error thrown from here, including the rewrite
+    // below, carries only a refusal that quotes no envSecrets value.
+    const error = withheldIfQuotingSecret(caught, envSecrets);
     // Cloud accepts exactly one authored Surface (the one its sandbox runs).
     // A CLI on another release is refused with this code; say which side is
     // which instead of leaving the user with a bare 400 (flows#461).

package/src/cloud-signal.ts

@@ -0,0 +1,110 @@
+import { setTimeout as delay } from 'node:timers/promises';
+import { CloudFlowError, cloudFetch, cloudRunId, isCloudRecord, resolveCloudConnection,
+  transportError, type CloudConnectionOptions } from './cloud-http.js';
+
+const SIGNAL_NAME = /^[A-Za-z0-9_-]{1,80}$/u;
+const MAX_BYTES = 4 * 1024;
+const HELD_GET_MS = 25_000;
+const HOSTED_SIGNAL_READ_TOKEN_ENV = 'RELAYFLOW_V2_SIGNAL_READ_TOKEN';
+
+function signalPath(runId: string, name: string): string {
+  cloudRunId(runId);
+  if (!SIGNAL_NAME.test(name)) {
+    throw new CloudFlowError('invalid_input', 'Signal name must contain only letters, digits, underscores, or hyphens (1–80 characters).');
+  }
+  return `/api/v1/workflows/runs/${runId}/signals/${name}`;
+}
+
+/** Store a run-scoped completion. Retrying the same JSON payload is safe. */
+export async function postCloudSignal(
+  runId: string, name: string, payload: unknown, options: CloudConnectionOptions = {},
+): Promise<{ accepted: true; duplicate: boolean }> {
+  const path = signalPath(runId, name);
+  if (payload === undefined) throw new CloudFlowError('invalid_input', 'Signal payload must be present.');
+  let body: string;
+  try { body = JSON.stringify({ payload }); }
+  catch { throw new CloudFlowError('invalid_input', 'Signal payload must be JSON serializable.'); }
+  // JSON.stringify omits a function, symbol, or toJSON() result of undefined.
+  // This envelope has only one field, so {} means the payload was lost.
+  if (body === '{}') throw new CloudFlowError('invalid_input', 'Signal payload must be JSON serializable.');
+  if (new TextEncoder().encode(body).byteLength > MAX_BYTES) {
+    throw new CloudFlowError('invalid_input', 'Signal payload exceeds 4 KiB.');
+  }
+  const result = await cloudFetch(path, options, { method: 'POST', body, detail: true });
+  if (!isCloudRecord(result) || result.accepted !== true || typeof result.duplicate !== 'boolean') {
+    throw new CloudFlowError('invalid_response', 'Cloud returned an invalid signal receipt.');
+  }
+  return { accepted: true, duplicate: result.duplicate };
+}
+
+/**
+ * Wait on Cloud's held GET. A normally held 204 re-arms immediately. A fast
+ * 204 backs off so a proxy or broken server cannot turn this into a hot loop.
+ */
+export async function waitForCloudSignal(
+  runId: string, name: string, options: CloudConnectionOptions = {},
+): Promise<unknown> {
+  const path = signalPath(runId, name);
+  const requestTimeout = options.requestTimeoutMs ?? 30_000;
+  if (!Number.isSafeInteger(requestTimeout) || requestTimeout <= HELD_GET_MS) {
+    throw new CloudFlowError('invalid_input', 'Signal requestTimeoutMs must exceed 25 seconds.');
+  }
+  let fast204BackoffMs = 250;
+  for (;;) {
+    options.signal?.throwIfAborted();
+    let connection: { baseUrl: string; token: string };
+    try {
+      connection = await resolveCloudConnection(options);
+    } catch (error) {
+      // The hosted run's read-only credential is only a fallback for waits.
+      // Explicit Cloud credentials and stored logins retain precedence, and
+      // postCloudSignal never sees this token.
+      const hostedToken = process.env[HOSTED_SIGNAL_READ_TOKEN_ENV];
+      if (!(error instanceof CloudFlowError) || error.code !== 'configuration'
+        || error.reason !== 'auth_missing' || options.token !== undefined
+        || process.env['FLOWS_CLOUD_TOKEN'] !== undefined || hostedToken === undefined) throw error;
+      connection = await resolveCloudConnection({ ...options, token: hostedToken });
+    }
+    const { baseUrl, token } = connection;
+    const deadline = AbortSignal.timeout(requestTimeout);
+    const requestStartedAt = performance.now();
+    let response: Response;
+    try {
+      response = await fetch(`${baseUrl}${path}?waitMs=${HELD_GET_MS}`, {
+        method: 'GET',
+        headers: { authorization: `Bearer ${token}` },
+        signal: options.signal ? AbortSignal.any([options.signal, deadline]) : deadline,
+        redirect: 'error',
+      });
+    } catch (error) {
+      options.signal?.throwIfAborted();
+      throw transportError(deadline.aborted ? deadline.reason : error);
+    }
+    if (response.status === 204) {
+      if (performance.now() - requestStartedAt < 1_000) {
+        try {
+          await delay(fast204BackoffMs, undefined, { signal: options.signal });
+        } catch (error) {
+          options.signal?.throwIfAborted();
+          throw error;
+        }
+        fast204BackoffMs = Math.min(fast204BackoffMs * 2, 5_000);
+      } else {
+        fast204BackoffMs = 250;
+      }
+      continue;
+    }
+    if (!response.ok) throw new CloudFlowError('http_error', `Cloud signal wait failed with HTTP ${response.status}.`, response.status);
+    let body: unknown;
+    try { body = await response.json(); }
+    catch (error) {
+      options.signal?.throwIfAborted();
+      if (!(error instanceof SyntaxError)) throw transportError(deadline.aborted ? deadline.reason : error);
+      throw new CloudFlowError('invalid_response', 'Cloud returned an invalid signal.');
+    }
+    if (!isCloudRecord(body) || !Object.hasOwn(body, 'payload') || typeof body.acceptedAt !== 'number') {
+      throw new CloudFlowError('invalid_response', 'Cloud returned an invalid signal.');
+    }
+    return body.payload;
+  }
+}

package/src/cloud-sync.ts

@@ -1,11 +1,12 @@
 import { spawnSync } from 'node:child_process';
-import { createReadStream, createWriteStream, existsSync, lstatSync, mkdtempSync, readdirSync, readlinkSync, rmSync } from 'node:fs';
-import { readFile } from 'node:fs/promises';
+import { createReadStream, createWriteStream, existsSync, lstatSync, mkdtempSync, readdirSync, readlinkSync, rmSync, statSync } from 'node:fs';
+import { open, readFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { Readable } from 'node:stream';
 import { pipeline } from 'node:stream/promises';
 import { createGzip } from 'node:zlib';
+import { createHash } from 'node:crypto';
 import {
   CloudFlowError, cloudFetch, cloudRequest, cloudRunId, isCloudRecord, type CloudConnectionOptions,
 } from './cloud-http.js';
@@ -25,6 +26,8 @@ import {
 
 /** Uncompressed bytes. Matches the sandbox's extraction budget with headroom. */
 export const MAX_SYNC_BYTES = 256 * 1024 * 1024;
+/** Above this compressed size, use the unchanged legacy upload path. */
+export const MAX_CACHED_CODE_BYTES = 64 * 1024 * 1024;
 const ALWAYS_SKIPPED = new Set(['.git', 'node_modules']);
 const CODE_KEY = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u;
 
@@ -33,11 +36,14 @@ export interface PreparedCloudSync {
   codeKey: string;
   /** Run-scoped upload credential from `prepare`; falls back to the session token. */
   uploadToken?: string;
+  /** Cloud confirmed the immutable archive already exists in this workspace. */
+  codeCacheHit?: boolean;
 }
 
 /** `POST /api/v1/workflows/prepare`, refusing every non-Cloud-API storage backend. */
-export async function prepareCloudSync(options: CloudConnectionOptions): Promise<PreparedCloudSync> {
-  const receipt = await cloudFetch('/api/v1/workflows/prepare', options, { method: 'POST' });
+export async function prepareCloudSync(options: CloudConnectionOptions, codeSha256?: string): Promise<PreparedCloudSync> {
+  const receipt = await cloudFetch('/api/v1/workflows/prepare', options,
+    { method: 'POST', ...(codeSha256 ? { body: JSON.stringify({ codeSha256 }) } : {}) });
   if (!isCloudRecord(receipt)) throw new CloudFlowError('invalid_response', 'Cloud prepare returned a non-object.');
   const storage = isCloudRecord(receipt.workflowStorage) ? receipt.workflowStorage : undefined;
   const credentials = isCloudRecord(receipt.s3Credentials) ? receipt.s3Credentials : undefined;
@@ -49,6 +55,15 @@ export async function prepareCloudSync(options: CloudConnectionOptions): Promise
   }
   const codeKey = typeof receipt.s3CodeKey === 'string' ? receipt.s3CodeKey : '';
   if (!CODE_KEY.test(codeKey)) throw new CloudFlowError('invalid_response', 'Cloud prepare returned an unusable code key.');
+  const codeCache = isCloudRecord(receipt.codeCache) ? receipt.codeCache : undefined;
+  let codeCacheHit: boolean | undefined;
+  if (codeSha256 && (codeCache !== undefined || codeKey.startsWith('code-sha256-'))) {
+    if (!codeCache || codeCache.sha256 !== codeSha256 || typeof codeCache.hit !== 'boolean'
+      || codeKey !== `code-sha256-${codeSha256}.tar.gz`) {
+      throw new CloudFlowError('invalid_response', 'Cloud prepare returned an inconsistent code cache receipt.');
+    }
+    codeCacheHit = codeCache.hit;
+  }
   const uploadToken = credentials?.cloudApiAccessToken;
   if (uploadToken !== undefined && typeof uploadToken !== 'string') {
     throw new CloudFlowError('invalid_response', 'Cloud prepare returned an unusable storage credential.');
@@ -56,9 +71,17 @@ export async function prepareCloudSync(options: CloudConnectionOptions): Promise
   return {
     runId: cloudRunId(receipt.runId), codeKey,
     ...(uploadToken === undefined ? {} : { uploadToken }),
+    ...(codeCacheHit === undefined ? {} : { codeCacheHit }),
   };
 }
 
+/** Hash the deterministic compressed archive without loading it into memory. */
+export async function sha256PackedTree(packed: PackedTree): Promise<string> {
+  const hash = createHash('sha256');
+  for await (const chunk of createReadStream(packed.archivePath)) hash.update(chunk);
+  return hash.digest('hex');
+}
+
 export interface PackedTree {
   /** The gzip'd ustar, spooled to a temporary file; `dispose()` removes it. */
   archivePath: string;
@@ -125,6 +148,14 @@ export async function packWorkingTree(root: string): Promise<PackedTree> {
   }
   try {
     await pipeline(Readable.from(flatten(entries())), createGzip({ level: 6 }), createWriteStream(archivePath));
+    // zlib's OS byte can vary by platform while the tar contents are equal.
+    // 255 means unknown OS and does not affect decompression.
+    const archive = await open(archivePath, 'r+');
+    try {
+      await archive.write(Buffer.from([255]), 0, 1, 9);
+    } finally {
+      await archive.close();
+    }
   } catch (error) {
     dispose();
     throw error;
@@ -132,6 +163,10 @@ export async function packWorkingTree(root: string): Promise<PackedTree> {
   return { archivePath, files: members, bytes, skippedLinks, dispose };
 }
 
+export function canUseCodeCache(packed: PackedTree): boolean {
+  return statSync(packed.archivePath).size <= MAX_CACHED_CODE_BYTES;
+}
+
 /** Yield file streams chunk by chunk so `Readable.from` never buffers a whole file. */
 async function* flatten(source: AsyncGenerator<Buffer | NodeJS.ReadableStream>): AsyncGenerator<Buffer> {
   for await (const part of source) {