@relayflows/sdk 2.0.55 → 2.0.57

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,16 +35,29 @@ 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;
+    }
     const resolution = resolved.get(step.id);
+    const cli = resolution?.cli ?? step.cli ?? (step.type === 'agent' && step.agent !== undefined
+      ? flow.agents?.[step.agent]?.cli : undefined);
+    if (cli !== undefined && resolveAdapterKind(cli) === 'devin') {
+      warnings.push({ severity: 'warning', kind: 'budget_unmetered', stepId: step.id,
+        message: `Step "${step.id}" uses Devin print mode, which reports no token or dollar usage. Token and dollar ceilings cannot bound its spend; timeout bounds its duration.` });
+      continue;
+    }
+    if (!dollarBudget) continue;
     const model = resolution?.model
       ?? step.model ?? (step.type === 'agent' && step.agent !== undefined
         ? flow.agents?.[step.agent]?.model : undefined);
     if (hasPricing(model)) continue;
-    const cli = resolution?.cli ?? step.cli;
     const reason = model !== undefined
       ? `model "${model}" has no frozen price`
       : cli !== undefined && resolveAdapterKind(cli) === 'codex'

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/cli-probe.ts

@@ -1,12 +1,14 @@
 import { accessSync, constants, realpathSync } from 'node:fs';
 import { basename, isAbsolute, resolve } from 'node:path';
 import { execFile, spawnSync } from 'node:child_process';
+import { redactText } from '../agent-transcript.js';
 import { agentEnvironment, brokerEnvironment } from '../communication/environment.js';
 import { adapterIdentification, authenticationProbe, classifyModelProbeFailure, cliAdapterKind,
   displayInvocation, modelReadinessProbe, type CliInvocation } from '../cli-adapter.js';
 import { MODEL_ENV } from '../worker-cli.js';
 import { CliProbeError, type CliProbeResult } from '../preflight.js';
 import { pinCliAlias, pinCliAliasSync } from './pinned-cli-alias.js';
+import { prepareDevinRuntime } from '../devin-runtime.js';
 import { agentProbeEnvironment } from '../step-secrets.js';
 
 interface ProbeRequest {
@@ -40,15 +42,18 @@ function driveSync<T>(sequence: Generator<ProbeRequest, T, ProbeOutput>): T {
   while (!next.done) {
     const request = next.value;
     const pinned = pinCliAliasSync(request.executable, request.argv0 ?? basename(request.executable));
+    let prepared: ReturnType<typeof prepareProbe> | undefined;
     const result = (() => {
       try {
-        return spawnSync(pinned.executable, request.invocation.args, {
-          ...probeOptions(request),
+        prepared = prepareProbe(request);
+        return spawnSync(pinned.executable, prepared.args, {
+          ...probeOptions({ ...request, environment: prepared.env }),
           // Preserve the old synchronous probe contract: provider CLIs must not
           // inherit a readable stdin that can block auth/identify probes.
           stdio: ['ignore', 'pipe', 'pipe'],
         });
       } finally {
+        prepared?.close();
         pinned.release();
       }
     })();
@@ -69,9 +74,12 @@ function probeOptions({ argv0, directory, invocation, environment }: ProbeReques
 
 async function runProbeAsync(request: ProbeRequest): Promise<ProbeOutput> {
   const pinned = await pinCliAlias(request.executable, request.argv0 ?? basename(request.executable));
+  let prepared: ReturnType<typeof prepareProbe> | undefined;
   try {
+    prepared = prepareProbe(request);
+    const current = prepared;
     return await new Promise((resolve, reject) => {
-      const child = execFile(pinned.executable, request.invocation.args, probeOptions(request),
+      const child = execFile(pinned.executable, current.args, probeOptions({ ...request, environment: current.env }),
         (error, stdout, stderr) => {
           // Numeric exit codes are probe results; launch, timeout, signal and buffer
           // errors are failures to collect a fact, just as in the synchronous driver.
@@ -86,6 +94,7 @@ async function runProbeAsync(request: ProbeRequest): Promise<ProbeOutput> {
       child.stdin?.end();
     });
   } finally {
+    prepared?.close();
     await pinned.release();
   }
 }
@@ -133,12 +142,16 @@ function* probeSequence(
   const auth = authenticationProbe(kind);
   const authCommand = displayInvocation(cli, auth);
   if (model === undefined) {
+    const authProbe = yield probe(auth);
+    const authenticated = authProbe.status === 0;
     return {
       exists: true,
       supported: true,
-      authenticated: (yield probe(auth)).status === 0,
+      authenticated,
       executable,
       authCommand,
+      ...(authenticated ? {} : { authExitCode: authProbe.status,
+        authFailureDetail: redactProbeOutput(`${authProbe.stderr}${authProbe.stdout}`, sourceEnvironment).trim().slice(0, 500) }),
     };
   }
 
@@ -168,7 +181,7 @@ function* probeSequence(
   // because Claude Code prints the provider's API error there and its own
   // catalog warnings on stderr.
   const failure = classifyModelProbeFailure(kind, `${scopedProbe.stdout}\n${scopedProbe.stderr}`);
-  const modelDetail = redactProbeOutput(scopedProbe.stdout.trim() || scopedProbe.stderr.trim()).slice(0, 500);
+  const modelDetail = redactProbeOutput(scopedProbe.stdout.trim() || scopedProbe.stderr.trim(), sourceEnvironment).slice(0, 500);
   return {
     exists: true,
     supported: true,
@@ -187,7 +200,7 @@ function* probeSequence(
       : {
         authExitCode: authProbe.status,
         authFailureDetail: redactProbeOutput(
-          `${authProbe.stderr}${authProbe.stdout}`,
+          `${authProbe.stderr}${authProbe.stdout}`, sourceEnvironment,
         ).trim().slice(0, 500),
       }),
   };
@@ -201,11 +214,42 @@ function* probeSequence(
  * say WHY a probe failed, which survives redaction; leaking an identity into a
  * refusal message that gets pasted into issues does not.
  */
-function redactProbeOutput(text: string): string {
-  return text
-    .replace(/[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g, '<redacted-email>')
-    .replace(/\b(sk|pk|oat|rt)[-_][A-Za-z0-9._-]{8,}/gi, '<redacted-token>')
-    .replace(/\b[A-Fa-f0-9]{32,}\b/g, '<redacted-hex>');
+function redactProbeOutput(text: string, environment: NodeJS.ProcessEnv): string {
+  const key = environment.DEVIN_API_KEY?.trim();
+  const normalized = { ...environment, ...(key === undefined ? {} : { DEVIN_API_KEY: key }) };
+  // Preserve the shared redactor's known-value, header and cookie handling.
+  const redacted = redactText(text, normalized);
+  // One byte per diagnostic character bounds auxiliary memory even when a
+  // one-character credential matches the entire probe buffer. No span lists.
+  const covered = new Uint8Array(redacted.length);
+  const replacements = ['', '<redacted-email>', '<redacted-token>', '<redacted-hex>', '[redacted:DEVIN_API_KEY]'];
+  for (const [pattern, tag] of [
+    [/(?<![A-Za-z0-9._%+-])[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g, 1],
+    [/\b(sk|pk|oat|rt)[-_][A-Za-z0-9._-]{8,}/gi, 2],
+    [/\b[A-Fa-f0-9]{32,}\b/g, 3],
+  ] as const) {
+    for (const match of redacted.matchAll(pattern)) covered.fill(tag, match.index, match.index + match[0].length);
+  }
+  // Mark short credentials AFTER the shapes, on the same text: replacing
+  // either first can split the other and leak a suffix. Connected marks are
+  // redacted together; a known credential's marker takes precedence.
+  if (key && key.length < 8) {
+    for (let start = redacted.indexOf(key); start !== -1; start = redacted.indexOf(key, start + 1)) {
+      covered.fill(4, start, start + key.length);
+    }
+  }
+  let result = ''; let cursor = 0;
+  for (let start = 0; start < covered.length;) {
+    if (covered[start] === 0) { start++; continue; }
+    let tag = covered[start]!; let end = start + 1;
+    while (end < covered.length && covered[end] !== 0) {
+      if (covered[end] === 4) tag = 4;
+      end++;
+    }
+    result += redacted.slice(cursor, start) + replacements[tag];
+    cursor = end; start = end;
+  }
+  return result + redacted.slice(cursor);
 }
 
 function* executableSequence(command: string, directory: string, environment: NodeJS.ProcessEnv): Generator<ProbeRequest, string | undefined, ProbeOutput> {
@@ -245,3 +289,13 @@ function classifySpawnFailure(
   }
   return signal === null ? undefined : new CliProbeError(`signal:${signal}`);
 }
+
+function prepareProbe(request: ProbeRequest) {
+  if (cliAdapterKind(request.argv0 ?? request.executable) === 'devin'
+      && request.environment.DEVIN_API_KEY !== undefined && !request.environment.DEVIN_API_KEY.trim()) {
+    throw new CliProbeError('devin_api_key_empty');
+  }
+  return cliAdapterKind(request.argv0 ?? request.executable) === 'devin'
+    ? prepareDevinRuntime(request.environment, request.invocation)
+    : { args: request.invocation.args, env: request.environment, close() {} };
+}

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'

package/src/cli/direct-run.ts

@@ -221,7 +221,8 @@ export async function runDirectFlow(
     // diagnostic carried up from `classifyOutcome` already names the step, its
     // exit code and its output tail; this branch is what lets it reach the
     // terminal. `resumeFlow` takes the same branch, through the same helper.
-    if (error instanceof AuthoredFlowExecutionError && (error.code === 'step_failed' || error.code === 'gate_failed')) {
+    if (error instanceof AuthoredFlowExecutionError && (error.code === 'step_failed' || error.code === 'gate_failed'
+      || error.code === 'serial_replay_order_mismatch')) {
       return authoredStepFailure('run', base, socketPath, error);
     }
     if (error instanceof AuthoredFlowExecutionError && error.code === 'result_unreadable') {

package/src/cli/run.ts

@@ -7,6 +7,7 @@ import { communicationInstruction } from '../communication/spec.js';
 import { checkCommunicationEnvironment, CommunicationEnvironmentError } from '../communication/preflight.js';
 import { parseHumanRecipient } from '../human-to.js';
 import { parseDigestReference } from '../bundle-transport.js';
+import { resolveNamedFlow } from '../cloud-flow-source.js';
 import { prepareDigestRun } from './run-digest.js';
 import { attachReuseSummary } from './reuse.js';
 import { resumeHelperEffect } from '../authored-helper-effect.js';
@@ -47,6 +48,7 @@ import { DEFAULT_LOCAL_AGENT_CAPACITY } from '../worker-slots.js';
 import { localAgentEnvironment } from '../local-agent-environment.js';
 import {
   checkFlow,
+  inputFailureReport,
   type CheckReport,
 } from './check.js';
 
@@ -182,6 +184,17 @@ export async function runFlow(
   dataDir: string,
   options: RunLifecycleOptions = {},
 ): Promise<RunExecution> {
+  try {
+    const named = await resolveNamedFlow(path);
+    if (named) {
+      const { runDirectFlow } = await import('./direct-run.js');
+      return runDirectFlow(named.path, '{}', dataDir, options);
+    }
+  } catch (error) {
+    return { exitCode: 2, report: fromCheckReport('run', inputFailureReport({
+      kind: 'input_unreadable', message: error instanceof Error ? error.message : String(error),
+    }, path)) };
+  }
   const agentEnvironment = localAgentEnvironment();
   const prepared = parseDigestReference(path) ? await prepareDigestRun(path, options.bucket) : undefined;
   if (prepared && 'exitCode' in prepared) return prepared;
@@ -432,7 +445,8 @@ export async function resumeFlow(
     // leaving it on `protocolFailure` meant `flows run` printed the evidence
     // while `flows resume` still printed `protocol_error` and
     // `RUN <id> unknown` for the identical failure.
-    if (error instanceof AuthoredFlowExecutionError && (error.code === 'step_failed' || error.code === 'gate_failed')) {
+    if (error instanceof AuthoredFlowExecutionError && (error.code === 'step_failed' || error.code === 'gate_failed'
+      || error.code === 'serial_replay_order_mismatch')) {
       return authoredStepFailure('resume', base, socketPath, error, runId);
     }
     if (error instanceof AuthoredFlowExecutionError && error.code === 'result_unreadable') {
@@ -632,10 +646,11 @@ export function authoredStepFailure(
         severity: 'failure',
         // A predicate gate that judged false is a run failure with its own
         // name, so the report says which kind of check the body did not pass.
-        kind: error.code === 'gate_failed' ? 'gate_failed' : 'step_failed',
+        // A refused out-of-order replay names itself the same way.
+        kind: error.code === 'gate_failed' || error.code === 'serial_replay_order_mismatch' ? error.code : 'step_failed',
         // The `step_failed: ` prefix `AuthoredFlowExecutionError` adds is
         // redundant once the diagnostic is labelled `[step_failed]`.
-        message: error.message.replace(/^(?:step_failed|gate_failed): /, ''),
+        message: error.message.replace(/^(?:step_failed|gate_failed|serial_replay_order_mismatch): /, ''),
       }],
     },
   };