@relayflows/sdk 2.0.55 → 2.0.56

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'

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): /, ''),
       }],
     },
   };

package/src/cli.ts

@@ -1,4 +1,7 @@
 #!/usr/bin/env node
+import { resolveNamedFlow, type NamedFlowSource } from './cloud-flow-source.js';
+import { isFlowName } from './bundle-transport.js';
+import { CloudFlowError } from './cloud-http.js';
 import { unavailableValidation, validationAnnotation, type DaemonValidationMode } from './daemon-spec-validation.js';
 import { foldUnprovableEffects, type FoldOptions } from './cli/diagnostic-fold.js';
 import { startDetachedRun, emitDetachedHandle } from './cli/detached-run.js';
@@ -134,6 +137,7 @@ const USAGE = [
   'flows plugin update [--json] [--yes] [--to <ref>] [<name>]',
   'flows build [--out <dir>] <flow.yaml|flow.ts>',
   'flows build --verify <bundle-dir>',
+  'flows deploy <flow.ts> [--name <name>] [--json]',
   'flows deploy <flow.ts> --repo <owner/name|gitlab:group/project> --on <provider>[:key=value,...] [--on ...] --approver <handle> [--agents claude[,codex]] [--name <name>] [--draft] [--plugin <ref>] [--no-connect] [--json]',
   'flows deploy <flow.ts> --flow <name|listener-id> [--plugin <ref>] [--no-connect] [--json]',
   'flows deployments [--json]',
@@ -152,6 +156,7 @@ const USAGE = [
   '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 run <name> [--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>',
   'flows resume [--allow-human-influenced] [--json] [--no-spawn] [--no-observer-link] [--cloud-mirror] [--detach] [--data-dir <dir>] [--local-agent [--agent-capacity <n>]] <run-id>',
   'flows answer --cloud [--json] [--note <text>] [--source <path>] <run-id> <yes|no>',
@@ -259,7 +264,7 @@ export async function runCli(
     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');
+        + '~/.agentworkforce/relay/workspaces.json for an Observer link, or sign in with agent-relay cloud login for the Cloud dashboard');
     }
   }
 
@@ -379,6 +384,27 @@ export async function runCli(
     }, io) as CliExitCode);
   }
 
+  let named: NamedFlowSource | undefined;
+  if (parsed.command === 'run') {
+    try {
+      named = await resolveNamedFlow(parsed.value);
+      if (!named && parsed.input !== undefined && !isAuthoredFlowPath(parsed.value)) {
+        throw new CloudFlowError('invalid_input', '--input requires an authored .flow.ts or a saved flow name.');
+      }
+      if (named) {
+        if (parsed.reuseFromRunId !== undefined) throw new CloudFlowError('invalid_input', '--reuse-from is not supported for authored named flows.');
+        parsed.value = named.path;
+        parsed.input ??= '{}';
+      }
+    } catch (error) {
+      const code = error instanceof CloudFlowError ? error.refusal?.code ?? error.code : 'flow_resolution_failed';
+      const message = error instanceof Error ? error.message : String(error);
+      if (parsed.json) io.stdout(JSON.stringify({ ok: false, code, message }));
+      else io.stderr(`${code}: ${message}`);
+      return 2;
+    }
+  }
+
   // Attach-or-spawn runs inside `runFlow`/`resumeFlow`/`runDirectFlow`, at the
   // single `connect()` seam immediately before journal-client.ts is used --
   // not here. Hoisting it above the dispatch would start a daemon as a side
@@ -388,21 +414,13 @@ export async function runCli(
     onObserverUrl: url => options.detachedReceipt?.observerUrl(url),
   });
   const runnerLog: string[] = [];
-  // Opt-in, unlike the observer link beside it. The observer is the default
-  // way to watch a local run: it is free, it needs only a workspace key, and
-  // it carries a step projection. The dashboard is the richer, hosted view —
-  // it stores the flow source, every step's transcript and this invocation's
-  // own output — so a local run joins it because someone asked, never because
-  // a login happened to be lying around.
-  const mirror = !(parsed.cloudMirror || cloudMirrorRequested(process.env))
-    ? undefined
-    : createCloudMirrorSession({
+  const mirror = createCloudMirrorSession({
       source: parsed.command === 'run'
-        ? mirrorSourceFromPath(parsed.value, parsed.input, parsed.dataDir)
+        ? mirrorSourceFromPath(parsed.value, parsed.input, parsed.dataDir, named)
         : mirrorSourceFromJournal(parsed.dataDir),
       dataDir: parsed.dataDir,
       log: () => runnerLog,
-      requested: parsed.cloudMirror ? 'flag' : 'env',
+      requested: parsed.cloudMirror ? 'flag' : cloudMirrorRequested(process.env) ? 'env' : 'login',
     }, io);
   // Everything this invocation prints, kept in order, so the mirror can upload
   // it as the run's `runner.log` — the object the dashboard's log pane reads,
@@ -888,7 +906,7 @@ function parseArgs(args: readonly string[]): ParsedArgs | 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;
+  if (command === 'run' && input !== undefined && !isAuthoredFlowPath(positionals[0]!) && !isFlowName(positionals[0]!)) return undefined;
   return command === 'check'
     ? { command, json, watch, explainWarnings, value: positionals[0]!,
         daemonValidation: daemonValidation ?? (process.env['FLOWS_NO_DAEMON_CHECK'] === '1' ? 'off'