@relayflows/sdk 2.0.54 → 2.0.56

package/src/authored-human.ts

@@ -105,13 +105,44 @@ export async function readHumanAnswer(
   runId: string,
   waitId: string,
 ): Promise<HumanAnswer | undefined> {
+  return (await readHumanWait(journal, runId, waitId)).answer;
+}
+
+/**
+ * `readHumanAnswer`, plus every question the run has parked on under
+ * `waitId`. The answer is keyed by the wait id alone, so the executor checks
+ * that the question it is about to answer is the one that was asked.
+ */
+export async function readHumanWait(
+  journal: JournalClient,
+  runId: string,
+  waitId: string,
+): Promise<{ answer?: HumanAnswer; asked: Array<{ question: unknown; to: unknown }> }> {
+  const asked: Array<{ question: unknown; to: unknown }> = [];
   for (const entry of await readWaitEntries(journal, runId)) {
-    if (entry.entry_type === 'wait.completed' && entry.payload?.wait_id === waitId
-      && entry.payload.completionReason === 'human_responded') {
-      return parseHumanAnswer(entry.payload.result, waitId);
+    if (entry.payload?.wait_id !== waitId) continue;
+    if (entry.entry_type === 'wait.human') {
+      asked.push({ question: entry.payload.prompt, to: entry.payload.requested_of });
+    } else if (entry.payload.completionReason === 'human_responded') {
+      return { answer: parseHumanAnswer(entry.payload.result, waitId), asked };
     }
   }
-  return undefined;
+  return { asked };
+}
+
+/**
+ * Every `f.human` wait id the run has parked on, answered or not. A parked
+ * question is not in the step index until its answer is lowered, but it
+ * already holds its serial ordinal.
+ */
+export async function readHumanWaitIds(journal: JournalClient, runId: string): Promise<string[]> {
+  const ids = new Set<string>();
+  for (const entry of await readWaitEntries(journal, runId)) {
+    const waitId = entry.payload?.wait_id;
+    if (entry.entry_type === 'wait.human' && typeof waitId === 'string'
+      && /(?:^|--)human-[1-9][0-9]*$/u.test(waitId)) ids.add(waitId);
+  }
+  return [...ids];
 }
 
 /** Every `wait.human` on the run that no `wait.completed` has closed. */

package/src/authored-mcp.ts

@@ -142,13 +142,18 @@ export async function runMcpEffect(
     childRunId = outcome.run_id;
     if (outcome.status !== 'completed') await completed;
     if (diagnostic !== undefined) {
-      try { await readCompletedStepOutput(journal, outcome.run_id, id, journalSteps, {}, outcome.status); }
+      try {
+        await readCompletedStepOutput(journal, outcome.run_id, id, journalSteps,
+          rootRunId === undefined ? {} : { rootRunId }, outcome.status);
+      }
       catch (error) {
         if (!(error instanceof AuthoredFlowExecutionError) || error.code !== 'step_failed') throw error;
         throw new McpStepError(diagnostic, outcome.run_id);
       }
     }
-    const receipt = await readCompletedStepOutput(journal, outcome.run_id, id, journalSteps, {}, outcome.status) as { output: unknown };
+    // Indexed on the root like every other child, so a resume can see its ordinal.
+    const receipt = await readCompletedStepOutput(journal, outcome.run_id, id, journalSteps,
+      rootRunId === undefined ? {} : { rootRunId }, outcome.status) as { output: unknown };
     return receipt.output;
   } finally {
     clearTimeout(timer);

package/src/authored-node-entry.ts

@@ -53,7 +53,7 @@ try {
     executableSha256: hash(process.execPath), payloadSha256: hash(process.argv[1]!) } });
   const request = await new Promise<{ channelKey: string; metadata: AuthoredRootMetadata; socketPath: string;
     rootRunId: string; dataDir: string; localAgentStream?: string; workerCapacity?: number;
-    agentEnvironment?: unknown }>((resolve, reject) => {
+    journaledSteps?: unknown; agentEnvironment?: unknown }>((resolve, reject) => {
     let buffer = '';
     process.stdin.setEncoding('utf8');
     const onData = (chunk: string): void => {
@@ -90,6 +90,8 @@ try {
   }
   if (request.localAgentStream !== request.metadata.localAgentStream) throw new Error('authored root local agent surface mismatch');
   if (request.workerCapacity !== undefined && !isAgentCapacity(request.workerCapacity)) throw new Error('invalid authored worker capacity');
+  if (request.journaledSteps !== undefined && (!Array.isArray(request.journaledSteps)
+    || !request.journaledSteps.every(step => typeof step === 'string'))) throw new Error('invalid authored journaled steps');
   client = new JournalClient(request.socketPath, { readBudgetMs: FLOW_READ_BUDGET_MS, budgetHandshake: true });
   await client.connect(); await client.hello('flows-authored-node');
   const result = await executeAuthoredFlow(loaded.handle, client,
@@ -102,6 +104,7 @@ try {
       flowGraph: loaded.graph,
       localAgentStream: request.localAgentStream, signal: controller.signal,
       ...(request.workerCapacity === undefined ? {} : { workerCapacity: request.workerCapacity }),
+      ...(request.journaledSteps === undefined ? {} : { journaledSteps: request.journaledSteps as string[] }),
       ...(agentEnvironment === undefined ? {} : { agentEnvironment: { ...process.env, ...agentEnvironment } }),
       onProgress: event => send({ type: 'progress', event }),
       onWait: event => send({ type: 'wait', event }),

package/src/authored-node-runner.ts

@@ -3,9 +3,9 @@ import { FLOW_READ_BUDGET_MS } from './journal-read-policy.js';
 import { spawn, spawnSync } from 'node:child_process';
 import { createHash, createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
 import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
-import { readFileSync, realpathSync } from 'node:fs';
+import { accessSync, constants as fsConstants, readFileSync, realpathSync, statSync } from 'node:fs';
 import { tmpdir } from 'node:os';
-import { isAbsolute, join } from 'node:path';
+import { delimiter, isAbsolute, join } from 'node:path';
 import type { Readable } from 'node:stream';
 import type { AuthoredRootMetadata } from './authored-root.js';
 import type { AuthoredExecutionRuntime, AuthoredFlowExecutionResult, ExecuteAuthoredFlowOptions } from './authored-flow-executor.js';
@@ -35,10 +35,51 @@ const refusal = (): AuthoredFlowExecutionError => new AuthoredFlowExecutionError
   'authored execution requires the embedded Node runner and Node >=22.14 on PATH (or an absolute FLOWS_AUTHORED_NODE); no workflow body was executed',
 );
 interface NodeAuthority { path: string; version: string; executableSha256: string }
+/**
+ * One authored run asks for the Node authority before root admission and
+ * again before spawning the body. Each probe spawns Node and hashes its whole
+ * executable (~100 MB), which a cold sandbox pays on the startup path twice.
+ * Reuse the previous answer only while the same candidate is selected (the
+ * override or the first `node` on PATH, by path and by realpath, so a
+ * retargeted symlink re-probes) and the executable it resolved is unchanged.
+ * The spawned child still hashes the executable it actually runs and the
+ * parent compares that report with this authority, so a binary replaced
+ * after the probe is refused, never trusted.
+ */
+let probedAuthority: { selection: string; fingerprint: string; authority: NodeAuthority } | undefined;
+function executableFingerprint(path: string): string {
+  const stat = statSync(path, { bigint: true });
+  return [stat.dev, stat.ino, stat.size, stat.mtimeNs, stat.ctimeNs].join(':');
+}
+/** The candidate `spawnSync(override ?? 'node')` would run, by path and realpath. */
+function selectedCandidate(override: string | undefined): string | undefined {
+  const directories = (process.env['PATH'] ?? '').split(delimiter);
+  // A relative PATH entry resolves against the working directory; do not
+  // guess which candidate the spawn would pick, just probe every time.
+  if (override === undefined && directories.some(directory => !isAbsolute(directory))) return undefined;
+  const candidates = override !== undefined ? [override] : directories.map(directory => join(directory, 'node'));
+  for (const candidate of candidates) {
+    try {
+      if (!statSync(candidate).isFile()) continue;
+      accessSync(candidate, fsConstants.X_OK);
+      return `${candidate}\0${realpathSync(candidate)}`;
+    } catch { /* Not this candidate. */ }
+  }
+  return undefined;
+}
 function nodeAuthority(): NodeAuthority {
   if (embeddedSource === undefined) throw refusal();
   const override = process.env['FLOWS_AUTHORED_NODE'];
   if (override !== undefined && !isAbsolute(override)) throw refusal();
+  const selection = selectedCandidate(override);
+  if (selection !== undefined && probedAuthority?.selection === selection) {
+    try {
+      if (executableFingerprint(probedAuthority.authority.path) === probedAuthority.fingerprint) {
+        return probedAuthority.authority;
+      }
+    } catch { /* A vanished executable is re-probed, and refused there. */ }
+  }
+  probedAuthority = undefined;
   const probe = spawnSync(override ?? 'node', ['--input-type=module', '--eval', `
 import {createHook} from 'node:async_hooks';
 import {stripTypeScriptTypes,register} from 'node:module';
@@ -56,10 +97,22 @@ process.stdout.write(JSON.stringify({path:process.execPath,version:process.versi
     const [major, minor] = value.version.split('.').map(Number);
     if (major! < 22 || (major === 22 && minor! < 14)) throw refusal();
     const path = realpathSync(value.path);
-    return { path, version: value.version, executableSha256: hash(readFileSync(path)) };
+    const fingerprint = executableFingerprint(path);
+    const authority = { path, version: value.version, executableSha256: hash(readFileSync(path)) };
+    // Reuse only an answer for a candidate that could be identified, and not
+    // one whose file was rewritten while it was being hashed.
+    if (selection !== undefined && executableFingerprint(path) === fingerprint) {
+      probedAuthority = { selection, fingerprint, authority };
+    }
+    return authority;
   } catch { throw refusal(); }
 }
 
+/** Test seam: resolve the authored Node authority exactly as the runner does. */
+export function authoredNodeAuthorityForTest(): Readonly<NodeAuthority> {
+  return nodeAuthority();
+}
+
 /** Called before root admission/resume; declarative commands never reach it. */
 export function assertAuthoredRuntimeAvailable(): void {
   if (process.versions['bun'] === undefined) assertAuthoredPromiseHooks();
@@ -138,6 +191,7 @@ export async function runAuthoredInNode(
               child.stdin!.write(JSON.stringify({ channelKey, metadata, socketPath, rootRunId,
                 dataDir: options.dataDir, localAgentStream: options.localAgentStream,
                 workerCapacity: options.workerCapacity,
+                ...(options.journaledSteps === undefined ? {} : { journaledSteps: options.journaledSteps }),
                 agentEnvironment: options.agentEnvironment }) + '\n');
             } else if (!ready || result) throw new Error('unexpected authored runtime message');
             else if (message.type === 'progress') options.onProgress?.(message.event);

package/src/authored-plugin-effect.ts

@@ -127,13 +127,18 @@ export async function runPluginEffect(
       if (dispatchExpired) await cancelChildRun();
       if (outcome.status !== 'completed') await completed;
       if (diagnostic !== undefined) {
-        try { await readCompletedStepOutput(journal, outcome.run_id, id, journalSteps, {}, outcome.status); }
+        try {
+          await readCompletedStepOutput(journal, outcome.run_id, id, journalSteps,
+            rootRunId === undefined ? {} : { rootRunId }, outcome.status);
+        }
         catch (error) {
           if (!(error instanceof AuthoredFlowExecutionError) || error.code !== 'step_failed') throw error;
           throw new PluginStepError(diagnostic, outcome.run_id);
         }
       }
-      const receipt = await readCompletedStepOutput(journal, outcome.run_id, id, journalSteps, {}, outcome.status) as { output: unknown };
+      // Indexed on the root like every other child, so a resume can see its ordinal.
+      const receipt = await readCompletedStepOutput(journal, outcome.run_id, id, journalSteps,
+        rootRunId === undefined ? {} : { rootRunId }, outcome.status) as { output: unknown };
       return receipt.output;
     }, admissionKey), deadline]);
   } finally {

package/src/authored-preflight.ts

@@ -1,3 +1,4 @@
+import { brokerInstruction } from './communication/broker-spec.js';
 import { dirname, resolve } from 'node:path';
 import { checkAuthoredFlow, readProjectConfig, type ProjectConfig } from './cli/check.js';
 import { probeCliAsync } from './cli/cli-probe.js';
@@ -21,7 +22,7 @@ export function authoredPreflight(path: string, environment?: NodeJS.ProcessEnv)
     if (!resolved.ok) return checkAuthoredFlow(flow, path, config, { environment });
     await Promise.all(resolved.resolutions.map(async resolution => {
       const step = resolved.compiled!.steps.find(step => step.id === resolution.stepId)!;
-      const managed = step.type === 'agent' && communicationInstruction(step.instruction) !== undefined;
+      const managed = step.type === 'agent' && (communicationInstruction(step.instruction) !== undefined || brokerInstruction(step.instruction) !== undefined);
       const key = cliProbeKey(resolution, managed, step.secrets);
       if (probeCache.has(key)) return;
       let probing = pending.get(key);

package/src/authored-root.ts

@@ -19,12 +19,13 @@ import { SPEC_SCHEMA_VERSION } from './spec.js';
 import type { RunLifecycleOptions } from './cli/run.js';
 import { isLeaseLost, withWorkerLease } from './worker-lease.js';
 import { AuthoredFlowExecutionError, AuthoredHumanParked } from './authored-flow-error.js';
-import { readOpenHumanWaits, resumeCommand } from './authored-human.js';
+import { readHumanWaitIds, readOpenHumanWaits, resumeCommand } from './authored-human.js';
 import { helperReceiptWaitId, releaseHelperReceiptWaits } from './helper-park.js';
 import { readSubscriptionPark } from './authored-subscription-park.js';
 import { localAgentCredentialEnvironment } from './local-agent-environment.js';
 import { completedResult, rootKernelStep, rootStepIfPresent } from './authored-root-readback.js';
 import { parallelPromiseIntrinsicsIntact } from './authored-flow-lifecycle.js';
+import { readAuthoredStepIndex } from './authored-step-index.js';
 
 export type DurableAuthoredFlowResult =
   | (AuthoredFlowExecutionResult & { readonly rootRunId: string })
@@ -391,6 +392,14 @@ async function driveRoot(
       // A lost root lease must also stop body reads still inside their budget.
       const releaseReads = journal.scopeReads?.(rootSignal) ?? (() => {});
       try {
+        // A re-dispatched serial body replays an earlier attempt; give it that
+        // attempt's step index so a reordered resume is refused, not re-run.
+        // A first attempt has nothing to replay and reads nothing.
+        const parallel = metadata.identityVersion === 2 && metadata.executionMode === 'parallel';
+        const journaledSteps = parallel || dispatch.attempt <= 1 ? undefined : [
+          ...(await readAuthoredStepIndex(journal, dispatch.run_id)).map(record => record.step),
+          ...await readHumanWaitIds(journal, dispatch.run_id),
+        ];
         const callerSignal = options.lifecycle?.signal;
         const signal = callerSignal === undefined ? rootSignal : AbortSignal.any([callerSignal, rootSignal]);
         if (process.versions['bun'] !== undefined) {
@@ -401,6 +410,7 @@ async function driveRoot(
               agentEnvironment: localAgentCredentialEnvironment(options.agentEnvironment),
             }),
             ...(options.workerCapacity === undefined ? {} : { workerCapacity: options.workerCapacity }),
+            ...(journaledSteps === undefined ? {} : { journaledSteps }),
             ...options.lifecycle, signal,
           });
         }
@@ -416,8 +426,8 @@ async function driveRoot(
             ...(options.agentEnvironment === undefined ? {} : { agentEnvironment: options.agentEnvironment }),
             ...(options.workerCapacity === undefined ? {} : { workerCapacity: options.workerCapacity }),
             rootRunId: dispatch.run_id,
-            executionMode: metadata.identityVersion === 2 && metadata.executionMode === 'parallel'
-              ? 'parallel' : 'serial',
+            executionMode: parallel ? 'parallel' : 'serial',
+            ...(journaledSteps === undefined ? {} : { journaledSteps }),
             extensions: loaded.extensions,
             flowGraph: loaded.graph,
             ...options.lifecycle,

package/src/authored-serial-ordinals.ts

@@ -0,0 +1,76 @@
+import { AuthoredFlowExecutionError } from './authored-flow-error.js';
+
+/**
+ * Serial step ids are `<kind>-<N>`, with ONE ordinal counter shared by every
+ * kind and assigned in call order (authored-flow-executor `nextId`). Inside a
+ * `Promise.all` that call order follows result arrival: each branch's next
+ * call is made when its previous step resolves. A resume replays completed
+ * results from the journal, in whatever order they come back, so two
+ * branches can take each other's ordinals.
+ *
+ * The kernel catches part of that: an admission key is bound to its spec, so
+ * `run-3` re-requested with a different command is `run_admission_conflict`.
+ * It cannot catch a KIND swap. `run-3` and `llm-3` are different admission
+ * keys, so a resumed `f.run` that lands on the ordinal an `llm` already
+ * holds gets a fresh key and runs again, exiting 0. This guard refuses that
+ * from the root's journaled step index before the step is admitted.
+ *
+ * The root driver reads the index, plus the root's `wait.human` ids, once
+ * per re-dispatched attempt (authored-root.ts); a first attempt reads
+ * nothing. The guard adds no journal record of its own. It sees what those
+ * hold — `f.llm`/`f.agent` from admission, an `f.dispatch` from its child's
+ * first step, an `f.human` from its park, other steps from completion — so an
+ * ordinal whose only holder was an `f.run` or effect still in flight at the
+ * crash is invisible to it. Stable per-branch identities (a new identity
+ * version) remove the class.
+ */
+export type SerialOrdinals = ReadonlyMap<number, ReadonlyArray<{ readonly kind: string; readonly step: string }>>;
+
+const SERIAL_ID = /^(.+)-([1-9][0-9]*)$/u;
+
+/**
+ * The ordinals journaled directly under `prefix` (a dispatched child's
+ * `dispatch-N--`, or '' for the root body). A descendant's step claims its
+ * dispatch's ordinal here: `dispatch-3--run-1` holds ordinal 3 for `dispatch`
+ * even before the child's receipt is journaled. Lowered `.gate` steps and
+ * anything not shaped `<kind>-<N>` hold none.
+ */
+export function serialOrdinals(journaledSteps: readonly string[], prefix: string): SerialOrdinals {
+  const ordinals = new Map<number, Array<{ kind: string; step: string }>>();
+  for (const step of journaledSteps) {
+    if (!step.startsWith(prefix)) continue;
+    const local = step.slice(prefix.length);
+    const descendant = local.indexOf('--');
+    const match = SERIAL_ID.exec(descendant < 0 ? local : local.slice(0, descendant));
+    if (match === null || (descendant >= 0 && match[1] !== 'dispatch')) continue;
+    const ordinal = Number(match[2]);
+    if (!Number.isSafeInteger(ordinal)) continue;
+    const holders = ordinals.get(ordinal) ?? [];
+    holders.push({ kind: match[1]!, step });
+    ordinals.set(ordinal, holders);
+  }
+  return ordinals;
+}
+
+/** Refuse `<kind>-<ordinal>` when the journal holds that ordinal under another kind. */
+export function assertSerialOrdinal(ordinals: SerialOrdinals, kind: string, ordinal: number): void {
+  const journaled = ordinals.get(ordinal)?.find(holder => holder.kind !== kind);
+  if (journaled === undefined) return;
+  throw serialReplayOrderMismatch(
+    `ordinal ${ordinal} is journaled as ${kindName(journaled.kind)} step "${journaled.step}", `
+      + `but this resume reached it with ${kindName(kind)}`,
+  );
+}
+
+export function serialReplayOrderMismatch(detail: string): AuthoredFlowExecutionError {
+  return new AuthoredFlowExecutionError(
+    'serial_replay_order_mismatch',
+    `serial replay order mismatch: ${detail}. Concurrent branches resolved in a different order `
+      + 'than the journaled run, so the step was refused instead of executed.',
+  );
+}
+
+/** Helper ids embed the root run id (`slack-<root>-N`); name the provider only. */
+function kindName(kind: string): string {
+  return kind.replace(/-[0-9A-HJKMNP-TV-Z]{26}$/u, '');
+}

package/src/authored-worker-step.ts

@@ -1,3 +1,5 @@
+import { authoredBroker } from './authored-broker.js';
+import { brokerInstruction, brokerOptionsError } from './communication/broker-spec.js';
 import { dirname, resolve, isAbsolute, relative, sep } from 'node:path';
 import type { AuthoredBudget } from './authored-budget.js';
 import { parseBudget } from './budget.js';
@@ -159,14 +161,24 @@ export function authoredWorkerRunner(
       onCompleted === undefined ? context : { ...context, onCompleted }, execution.report.status);
     };
     const admissionKey = authoredChildAdmissionKey(rootRunId, id);
+    const cleanup = step.type === 'agent' && brokerInstruction(step.instruction)?.operation === 'release';
     const admit = async () => budget === undefined
       ? consume(await journal.runStart(spec, undefined, admissionKey))
-      : budget.execute(journal, spec, consume, admissionKey);
+      : budget.execute(journal, spec, consume, admissionKey, false, cleanup);
     return slotScopes === undefined ? admit() : slotScopes[step.type === 'llm' ? 'llm' : 'agent'].run(admit);
   }
 
+  const broker = authoredBroker(definition, rootRunId, localAgentStream, async step => {
+    const output = await run(step);
+    if (typeof output === 'object' && output !== null && AGENT_TIMEOUT in output) {
+      return { completionReason: 'timeout', summary: String(output[AGENT_TIMEOUT]), artifacts: [] };
+    }
+    return output;
+  });
   return {
     slots,
+    message: broker.message,
+    release: broker.release,
     /** Refuse every agent/LLM call still waiting for a worker slot (body teardown). */
     stop(reason: unknown): void {
       if (ownsSlots) {
@@ -177,9 +189,12 @@ export function authoredWorkerRunner(
         slotScopes?.llm.close(reason);
       }
     },
-    async agent(id: string, options: AgentOptions, verification?: NamedGate): Promise<AgentResult> {
+    async agent(id: string, options: AgentOptions, verification?: NamedGate, name = id): Promise<AgentResult> {
       const secrets = validateStepSecrets((options as AgentOptions & { secrets?: unknown }).secrets,
         agentEnvironment ?? process.env);
+      if (options.transport === 'broker') return broker.agent(id, name, options, verification, secrets);
+      const brokerProblem = brokerOptionsError(options);
+      if (brokerProblem) throw new AuthoredFlowExecutionError('agent_cli_unresolved', brokerProblem);
       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.');

package/src/budget-preflight.ts

@@ -1,3 +1,4 @@
+import { brokerInstruction } from './communication/broker-spec.js';
 import type { CompiledFlowSpec } from './compile.js';
 import type { PreflightWarning } from './preflight.js';
 import { hasPricing } from './model-pricing.js';
@@ -34,10 +35,17 @@ export function budgetDiagnostics(
   flow: CompiledFlowSpec,
   resolved: ReadonlyMap<string, BudgetStepResolution> = new Map(),
 ): PreflightWarning[] {
-  if (flow.budget?.pricing !== 'frozen' || flow.budget.maxDollars === undefined) return [];
+  const dollarBudget = flow.budget?.pricing === 'frozen' && flow.budget.maxDollars !== undefined;
   const warnings: PreflightWarning[] = [];
   for (const step of flow.steps) {
     if (step.type === 'deterministic') continue;
+    const broker = step.type === 'agent' ? brokerInstruction(step.instruction) : undefined;
+    if (broker) {
+      if (broker.operation !== 'release') warnings.push({ severity: 'warning', kind: 'budget_unmetered', stepId: step.id,
+        message: `Step "${step.id}" uses a broker session that reports no token or dollar usage. Token and dollar ceilings cannot bound its spend; timeout bounds its duration.` });
+      continue;
+    }
+    if (!dollarBudget) continue;
     const resolution = resolved.get(step.id);
     const model = resolution?.model
       ?? step.model ?? (step.type === 'agent' && step.agent !== undefined

package/src/bundle-transport.ts

@@ -11,6 +11,10 @@ export class BundleFailure extends Error {
   constructor(readonly kind: BundleFailureKind, message: string) { super(message); }
 }
 export interface DigestReference { name: string; digest: string }
+/** Bare cloud names exclude file extensions and directory separators. */
+export function isFlowName(value: string): boolean {
+  return /^[A-Za-z0-9][A-Za-z0-9_-]{0,99}$/u.test(value);
+}
 export function parseDigestReference(value: string): DigestReference | undefined {
   // Match the safe single-component name grammar used by sealBundle.
   const match = /^([A-Za-z0-9][A-Za-z0-9._-]*)@sha256:([0-9a-f]{64})$/.exec(value);

package/src/cached-flow-runtime.ts

@@ -0,0 +1,32 @@
+import { createRequire } from 'node:module';
+import { mkdir, readFile, realpath, symlink } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/** Cached single-file flows use the CLI's installed authoring runtime. */
+export async function prepareCachedFlowRuntime(directory: string): Promise<void> {
+  const require = createRequire(import.meta.url);
+  const packages = [
+    ['@relayflows/surface', require.resolve('@relayflows/surface/runtime')],
+    ['@relayflows/sdk', fileURLToPath(import.meta.url)],
+  ] as const;
+  for (const [name, entry] of packages) {
+    let root = dirname(entry);
+    for (;;) {
+      const manifest = await readFile(join(root, 'package.json'), 'utf8').catch(() => '{}');
+      if ((JSON.parse(manifest) as { name?: string }).name === name) break;
+      const parent = dirname(root);
+      if (parent === root) throw new Error(`Cannot locate installed ${name}.`);
+      root = parent;
+    }
+    const target = join(directory, 'node_modules', name);
+    await mkdir(dirname(target), { recursive: true });
+    try { await symlink(root, target, 'dir'); }
+    catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;
+      if (await realpath(target) !== await realpath(root)) {
+        throw new Error(`Cached runtime at ${target} differs from this CLI. Remove that link and retry.`);
+      }
+    }
+  }
+}

package/src/cli/check.ts

@@ -1,3 +1,5 @@
+import { checkBrokerEnvironment } from '../communication/broker-preflight.js';
+import { brokerInstruction } from '../communication/broker-spec.js';
 import { validateSpecWithDaemon, type DaemonValidation, type DaemonValidationMode, type DaemonValidationDeps } from '../daemon-spec-validation.js';
 import { communicationInstruction } from '../communication/spec.js';
 import { rememberResolvedCliIdentities } from '../resolved-cli-identity.js';
@@ -246,6 +248,14 @@ export function checkAuthoredFlow(
           effectiveProbeCache,
         )
       : undefined;
+    if (flow?.steps.some(step => step.type === 'agent' && brokerInstruction(step.instruction)?.operation === 'spawn')) {
+      try { checkBrokerEnvironment(); }
+      catch (error) {
+        result.ok = false;
+        result.diagnostics.push({ severity: 'refusal', kind: 'probe_failed',
+          message: error instanceof Error ? error.message : 'Broker environment could not be checked.' });
+      }
+    }
     if (flow?.steps.some(step => step.type === 'agent' && communicationInstruction(step.instruction))) {
       try { if (options?.communicationChecked !== true) checkCommunicationEnvironment(flow); }
       catch (error) {
@@ -520,7 +530,7 @@ function bindResolvedCliPaths(
       const resolution = byStep.get(step.id);
       if (resolution === undefined) return step;
       const directory = resolution.source === 'project' ? configDirectory : flowDirectory;
-      const managed = step.type === 'agent' && communicationInstruction(step.instruction) !== undefined;
+      const managed = step.type === 'agent' && (communicationInstruction(step.instruction) !== undefined || brokerInstruction(step.instruction) !== undefined);
       const outcome = probeCache.get(cliProbeKey(resolution, managed, step.secrets));
       const executable = outcome !== undefined && 'result' in outcome
         ? outcome.result.executable

package/src/cli/cloud-deploy.ts

@@ -98,7 +98,7 @@ export function parseCloudDeployArgs(args: readonly string[]): CloudDeployArgs |
     value = arg;
   }
   if (value === undefined) return undefined;
-  if (flow === undefined && (repo === undefined || on.length === 0)) return undefined;
+  if (flow === undefined && on.length > 0 && repo === undefined) return undefined;
   return { command: 'cloud-deploy', value, flow, repo, on, approver, name, agents, draft, noConnect, json, plugins };
 }
 
@@ -119,7 +119,7 @@ export async function runCloudDeployCli(args: CloudDeployArgs, io: CliIo): Promi
   // by deployToCloud, not here.
   let harnesses: readonly string[] = agents instanceof CloudFlowError ? [] : agents ?? [];
   try {
-    if (args.approver === undefined) {
+    if (args.on.length > 0 && args.approver === undefined) {
       throw new CloudFlowError('invalid_input',
         '--approver <handle> is required: every launched run receives it as input.approver for f.human.');
     }
@@ -128,7 +128,7 @@ export async function runCloudDeployCli(args: CloudDeployArgs, io: CliIo): Promi
     if (agents === undefined) harnesses = (await flowRequirementsForPath(args.value))?.harnesses ?? [];
     const deployment = await deployToCloud({
       path: args.value,
-      repository: parseRepository(args.repo!),
+      ...(args.repo === undefined ? {} : { repository: parseRepository(args.repo) }),
       sources: args.on.map(parseTriggerSource),
       approver: args.approver,
       draft: args.draft,
@@ -144,12 +144,12 @@ export async function runCloudDeployCli(args: CloudDeployArgs, io: CliIo): Promi
     io.stdout(`${deployment.status === 'draft' ? 'SAVED' : 'DEPLOYED'} ${deployment.agentId} ${deployment.status}`
       + (deployment.version === undefined ? '' : ` · ${describeVersionChange(deployment.version)}`));
     io.stdout(`  flow: ${deployment.name} (${args.value}, sha256 ${deployment.sourceSha256.slice(0, 12)})`);
-    io.stdout(`  repository: ${describeRepository(deployment.repository)}`);
+    if (deployment.repository) io.stdout(`  repository: ${describeRepository(deployment.repository)}`);
     for (const source of deployment.sources) io.stdout(`  on: ${describeSource(source)}`);
     const requires = describeFlowRequirements(deployment.requirements);
     if (requires) io.stdout(`  requires: ${requires}`);
     for (const provider of deployment.connected) io.stdout(`  connected: ${provider}`);
-    io.stdout(deployment.status === 'draft'
+    io.stdout(deployment.sources.length === 0 ? `Run locally: flows run ${deployment.name}` : deployment.status === 'draft'
       ? 'Saved without activating; activate it from the Cloud dashboard, or redeploy without --draft.'
       : 'Each matching ticket launches a run of this source in a fresh branch; list with: flows deployments');
     return 0;

package/src/cli/cloud-mirror-session.ts

@@ -1,26 +1,5 @@
-// The Cloud half of `flows run` / `flows resume`: also put this local run on
-// the Cloud dashboard.
-//
-// Opt-in, and deliberately the only opt-in thing on this path.
-//
-// A local run is already watchable by default: `observer-session.ts` beside
-// this one projects the run into its own channel and prints a read-only link,
-// off a workspace key, for free. That is the right default — it is a step
-// projection, it costs nothing, and a run that never joins a workspace is not
-// a defect (RFC-0001 settled decision 7).
-//
-// The dashboard is the richer, hosted view of the same run: the flow source,
-// every step's transcript, the run graph, the logs, and the run sitting in the
-// same history as the hosted ones. It is also the one that *stores* all of
-// that. So it is asked for — `--cloud-mirror`, or `FLOWS_CLOUD_MIRROR=1` for a
-// shell — and never turned on by a login happening to be present. Mirroring
-// someone's local runs because they once signed in is not a default anyone
-// consented to.
-//
-// Best-effort once it is on, like the observer: a registration failure is one
-// labeled stderr line, and nothing here can change a run's exit code or its
-// journal. But it is a *louder* line than it used to be, because the run asked
-// for this and did not get it.
+// Signed-in local runs project their journal onto the Cloud dashboard.
+// Reporting is best-effort and never changes the durable run outcome.
 
 import { readFile } from 'node:fs/promises';
 import type { CliIo } from '../cli.js';
@@ -59,7 +38,7 @@ export interface CloudMirrorSession {
    */
   receipt(): Promise<CloudMirrorReceipt | undefined>;
   /** A journaled entry; the first one names the run for a declarative flow. */
-  onJournalEntry(entry: { run_id: string }): void;
+  onJournalEntry(entry: { run_id: string; entry_type?: string; step_id?: string | null }): void;
   /** Step transitions, pushed as lifecycle events the run page's stream shows. */
   onProgress(event: ProgressEvent): void;
   /** Publish the final report and the terminal status. Never rejects. */
@@ -82,7 +61,7 @@ export interface CloudMirrorRequest {
   /** Lines the CLI has printed for this run, uploaded as the run's `runner.log`. */
   log: () => readonly string[];
   /** How the dashboard was asked for, so a refusal can name the right switch. */
-  requested: 'flag' | 'env';
+  requested: 'flag' | 'env' | 'login';
 }
 
 /**
@@ -147,7 +126,14 @@ export function createCloudMirrorSession(
       void open(run.runId);
     },
     onJournalEntry(entry) {
-      void open(entry.run_id);
+      const opened = open(entry.run_id);
+      if (entry.step_id && (entry.entry_type === 'step.attempt.started' || entry.entry_type === 'step.completed')) {
+        void opened.then(mirror => mirror?.event({
+          eventType: entry.entry_type === 'step.completed' ? 'relayflow.step.completed' : 'relayflow.step.started',
+          stepName: entry.step_id!,
+          payload: { journalRunId: entry.run_id },
+        }));
+      }
     },
     async receipt() {
       if (opening === undefined) return undefined;
@@ -194,6 +180,7 @@ export function mirrorSourceFromPath(
   path: string,
   inputArgument: string | undefined,
   dataDir: string,
+  named?: { flowId: string; flowVersionId: string; source: string },
 ): (runId: string) => Promise<MirrorRunSource> {
   const fromJournal = mirrorSourceFromJournal(dataDir);
   return async (runId) => {
@@ -203,9 +190,10 @@ export function mirrorSourceFromPath(
     // the dashboard, so fall back to what the journal recorded — the same
     // source a resume mirrors.
     if (parseDigestReference(path)) return fromJournal(runId);
-    const workflow = await readFile(path, 'utf8');
+    const workflow = named?.source ?? await readFile(path, 'utf8');
     if (!isAuthoredFlowPath(path)) return { workflow, fileType: 'yaml' };
-    return { workflow, fileType: 'ts', inputs: parseDirectInput(inputArgument) };
+    return { workflow, fileType: 'ts', inputs: parseDirectInput(inputArgument),
+      ...(named === undefined ? {} : { flowId: named.flowId, flowVersionId: named.flowVersionId }) };
   };
 }
 
@@ -305,7 +293,13 @@ function completionReport(report: RunReport): Record<string, unknown> {
  * missing-login case is the common one and names the two commands that fix
  * it: sign in, or stop asking.
  */
-function mirrorRefusal(error: unknown, requested: 'flag' | 'env'): string {
+function mirrorRefusal(error: unknown, requested: 'flag' | 'env' | 'login'): string {
+  if (requested === 'login') {
+    if (error instanceof CloudFlowError && error.reason === 'auth_missing') {
+      return 'Not signed in; this run stays local. Sign in with `agent-relay cloud login` to report runs.';
+    }
+    return `Local run reporting unavailable: ${error instanceof Error ? error.message : String(error)}; the run itself is unaffected.`;
+  }
   const asked = requested === 'flag' ? '--cloud-mirror' : `${MIRROR_ENV}=1`;
   if (error instanceof CloudFlowError && error.code === 'configuration') {
     return error.reason === 'auth_missing'