@relayflows/sdk 2.0.22 → 2.0.23

package/src/cli/run.ts

@@ -1,3 +1,5 @@
+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 { prepareDigestRun } from './run-digest.js';
@@ -13,7 +15,7 @@ import { ensureDaemon, type EnsureDaemonOptions } from '../daemon-lifecycle.js';
 import { isAuthoredFlowPath } from '../direct-input.js';
 import { daemonRefusal } from './daemon-refusal.js';
 import type { RunFailureKind, RunWarningKind, StepFailedDetails } from '../failure-kinds.js';
-import { inspectionHint, stepFailureDetails } from './step-failure.js';
+import { inspectionHint, renderInspection, renderStepEvidence, stepFailureDetails } from './step-failure.js';
 import { JournalClient, JournalProtocolError } from '../journal-client.js';
 import { attachLocalAgent } from '../local-agent.js';
 import { LlmWorker } from '../llm-worker.js';
@@ -49,6 +51,8 @@ export interface RunReport {
   command: RunCommand;
   path?: string;
   runId?: string;
+  /** Authored root to resume/collect when runId identifies a failed child. */
+  rootRunId?: string;
   socketPath?: string;
   status?: RunStatus;
   completionReason?: RunCompletionReason;
@@ -129,16 +133,26 @@ async function executeCheckedFlow(
   // Carry the preflight's diagnostics as a RunReport from here on, so the
   // attach step has one accumulator to append to (see `connect`).
   const base = fromCheckReport('run', checked.report);
+  if (options.localAgent) {
+    try { checkCommunicationEnvironment(checked.flow!); }
+    catch (error) { return { exitCode: 2, report: { ...base, diagnostics: [...base.diagnostics,
+      { severity: 'refusal', kind: 'probe_failed', message: error instanceof Error ? error.message : 'Communication environment could not be checked.' }] } }; }
+  }
   const client = new JournalClient(socketPath);
   const connected = await connect(client, 'run', dataDir, base, options);
   if (connected !== undefined) return connected;
 
+  let communicationWorkers: Awaited<ReturnType<typeof import('../communication/local.js').attachCommunicationWorkers>> | undefined;
   let localAgent: Awaited<ReturnType<typeof attachLocalAgent>> | undefined;
   try {
     const spec = toKernelSpec(checked.flow!);
     // Use the checked CLI/model and declared surfaces unchanged. The worker
     // advertises its existing pins; the daemon still owns surface matching.
     if (options.localAgent) localAgent = await attachLocalAgent(client, dataDir, options.onPtyReady);
+    if (options.localAgent && spec.steps.some(step => step.type === 'agent' && communicationInstruction(step.instruction))) {
+      const { attachCommunicationWorkers } = await import('../communication/local.js');
+      communicationWorkers = await attachCommunicationWorkers(spec, socketPath, dataDir);
+    }
     const outcome = await client.runStart(spec, options.reuseFromRunId);
     const execution = await classifyOutcome(client, 'run', outcome, base, socketPath, { ...options, dataDir });
     if (options.reuseFromRunId !== undefined) {
@@ -146,6 +160,8 @@ async function executeCheckedFlow(
     }
     return execution;
   } catch (error) {
+    if (error instanceof CommunicationEnvironmentError) return { exitCode: 2, report: { ...base,
+      diagnostics: [...base.diagnostics, { severity: 'refusal', kind: 'probe_failed', message: error.message }] } };
     if (error instanceof JournalProtocolError && (
       error.code === 'reuse_spec_mismatch' || error.code === 'reuse_run_not_found'
       || error.code === 'reuse_journal_read_failed'
@@ -155,9 +171,9 @@ async function executeCheckedFlow(
         diagnostics: [...base.diagnostics, { severity: failed ? 'failure' : 'refusal',
           kind: error.code, message: error.message }] } };
     }
-    return protocolFailure('run', base, socketPath, localAgent?.failure ?? error);
+    return protocolFailure('run', base, socketPath, communicationWorkers?.failure ?? localAgent?.failure ?? error);
   } finally {
-    try { await localAgent?.close(); } finally { client.close(); }
+    try { await communicationWorkers?.close(); } finally { try { await localAgent?.close(); } finally { client.close(); } }
   }
 }
 
@@ -172,6 +188,7 @@ export async function resumeFlow(
   const connected = await connect(client, 'resume', dataDir, base, options);
   if (connected !== undefined) return connected;
 
+  let communicationWorkers: Awaited<ReturnType<typeof import('../communication/local.js').attachCommunicationWorkers>> | undefined;
   let authoredAgent: Awaited<ReturnType<typeof attachLocalAgent>> | undefined;
   let authoredLlm: LlmWorker | undefined;
   let authoredLlmClient: JournalClient | undefined;
@@ -206,12 +223,23 @@ export async function resumeFlow(
     // slack effect resume plus every other provider from N's codegen. The
     // second call the earlier rebase left is a stale reference from before
     // the helper fanout renamed the API.
+    if (options.localAgent) {
+      authoredAgent = await attachLocalAgent(client, dataDir, options.onPtyReady);
+      const entries = (await client.journalRead(runId, 1)).entries as Array<{ entry_type: string; payload?: { spec?: import('../spec.js').KernelRunSpec } }>;
+      const spec = entries.find(entry => entry.entry_type === 'run.spawned')?.payload?.spec;
+      if (spec?.steps.some(step => step.type === 'agent' && communicationInstruction(step.instruction))) {
+        const { attachCommunicationWorkers } = await import('../communication/local.js');
+        communicationWorkers = await attachCommunicationWorkers(spec, socketPath, dataDir);
+      }
+    }
     let outcome = await client.runResume(runId, options.allowHumanInfluenced);
     if (await resumeHelperEffect(client, runId, dataDir)) {
       outcome = await client.runResume(runId, options.allowHumanInfluenced);
     }
     return await classifyOutcome(client, 'resume', outcome, base, socketPath, { ...options, dataDir });
   } catch (error) {
+    if (error instanceof CommunicationEnvironmentError) return { exitCode: 2, report: { ...base, runId, socketPath,
+      diagnostics: [...base.diagnostics, { severity: 'refusal', kind: 'probe_failed', message: error.message }] } };
     if (error instanceof JournalProtocolError && error.code === 'human_influenced_run') {
       return { exitCode: 2, report: { ...base, runId, socketPath,
         diagnostics: [{ severity: 'refusal', kind: 'human_influenced_run', message: error.message.replace(/^human_influenced_run: /, '') }] } };
@@ -255,6 +283,7 @@ export async function resumeFlow(
     };
   } finally {
     try {
+      await communicationWorkers?.close();
       await authoredLlm?.close();
       authoredLlmClient?.close();
       await authoredAgent?.close();
@@ -287,16 +316,23 @@ export function authoredStepFailure(
   // The failing step runs as its own kernel run, so the error's run id is the
   // one whose journal holds the evidence. The resume target is the fallback.
   const runId = error.runId ?? fallbackRunId;
+  const rootRunId = error.rootRunId ?? fallbackRunId;
   return {
     exitCode: 1,
     report: {
       ...fromBase(command, base),
       ok: false,
       ...(runId === undefined ? {} : { runId }),
+      ...(rootRunId === undefined ? {} : { rootRunId }),
       socketPath,
       status: 'failed',
       completionReason: 'step_failed',
       diagnostics: [...base.diagnostics, {
+        // The structured evidence the failing step left in its own journal.
+        // `RunDiagnostic extends StepFailedDetails`, so `--json` gains the
+        // fields it already declares instead of leaving them to be re-parsed
+        // out of the rendered message.
+        ...error.details,
         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.
@@ -522,7 +558,9 @@ export async function classifyOutcome(
   let unclassifiedPolls = 0;
   while (current.status === 'parked') {
     const inspection = await inspectOutOfBandStep(client, current.run_id);
-    if (inspection?.parkedStep !== undefined) {
+    // A runnable sibling may only be waiting for capacity held by a live
+    // attempt. Keep driving until that lease releases before declaring a park.
+    if (inspection?.parkedStep !== undefined && (inspection.needsHuman || inspection.runningStep === undefined)) {
       parkedStep = inspection.parkedStep;
       needsHuman = inspection.needsHuman;
       break;
@@ -603,8 +641,7 @@ export async function classifyOutcome(
       // must still end with somewhere to go rather than with a dead end.
       const where = inspectionHint(current.run_id, details?.stepId, options.dataDir);
       Object.assign(diagnostic, where);
-      diagnostic.message += `\nInspect: ${where.hint}`
-        + (where.journalPath === undefined ? '' : `\nJournal: ${where.journalPath}`);
+      diagnostic.message += renderInspection(where);
     }
     return {
       exitCode: 1,
@@ -793,25 +830,6 @@ function errorMessage(error: unknown): string {
   return error instanceof Error ? error.message : 'unknown protocol error';
 }
 
-/**
- * The evidence half of a `step_failed` diagnostic; `inspectionHint` adds the
- * rest. Each field is printed only when the journal actually carried it — an
- * agent step has no exit code to report, and inventing `exit=undefined` (which
- * is what the deterministic-only version printed for one) is worse than
- * silence on that field.
- */
-function renderStepEvidence(details: StepFailedDetails): string {
-  return ` Step ${JSON.stringify(details.stepId)}`
-    + (details.stepType === undefined ? '' : ` (${details.stepType})`)
-    + ` completionReason: ${details.completionReason}`
-    + (details.exitCode === undefined ? '' : ` exit=${details.exitCode}`)
-    + '.'
-    + (details.detail === undefined ? '' : `\nDetail: ${details.detail}`)
-    + (details.stdoutTail ? `\nStdout (last 1,024 bytes):\n${details.stdoutTail}` : '')
-    + (details.stderrTail ? `\nStderr (last 1,024 bytes):\n${details.stderrTail}` : '')
-    + (details.transcriptPath === undefined ? '' : `\nTranscript: ${details.transcriptPath}`);
-}
-
 function throwIfCanceled(signal: AbortSignal | undefined, stepId: string): void {
   if (signal?.aborted === true) throw new Error(`waiting for running step "${stepId}" was canceled`);
 }

package/src/cli/status.ts

@@ -22,6 +22,15 @@ export interface StatusArgs {
   dataDir?: string;
   tail?: number;
   runId?: string;
+  /**
+   * `--cloud`: read the run from the Cloud API instead of a local journal.
+   *
+   * Parsed here because the verb is one verb — a reader should not have to
+   * know that a hosted run is a different command — but never *handled* here:
+   * `runCli` routes a `--cloud` invocation to `cli/cloud-read.ts`, so this
+   * module keeps its property of opening one file and no socket.
+   */
+  cloud?: true;
 }
 
 export const DEFAULT_TAIL_LINES = 20;
@@ -53,6 +62,7 @@ export interface StatusOptions {
 
 export function parseStatusArgs(args: readonly string[]): StatusArgs | undefined {
   let json = false;
+  let cloud = false;
   let dataDir: string | undefined;
   let tail: number | undefined;
   const positionals: string[] = [];
@@ -61,6 +71,9 @@ export function parseStatusArgs(args: readonly string[]): StatusArgs | undefined
     if (argument === '--json') {
       if (json) return undefined;
       json = true;
+    } else if (argument === '--cloud') {
+      if (cloud) return undefined;
+      cloud = true;
     } else if (argument === '--data-dir' || argument === '--tail') {
       const value = args[++index];
       if (value === undefined || value.length === 0 || value.startsWith('-')) return undefined;
@@ -78,8 +91,15 @@ export function parseStatusArgs(args: readonly string[]): StatusArgs | undefined
     }
   }
   if (positionals.length > 1) return undefined;
+  // `--data-dir` and `--tail` name things on this filesystem: a data directory
+  // to read a journal out of, and per-attempt tail files beside it. A hosted
+  // run has neither, so pairing them with `--cloud` is not a narrower request
+  // but a contradiction, and is refused as an invocation rather than silently
+  // ignored. A hosted run id is mandatory: there is no ambient one.
+  if (cloud && (dataDir !== undefined || tail !== undefined || positionals.length === 0)) return undefined;
   return {
     command: 'status', json,
+    ...(cloud ? { cloud: true as const } : {}),
     ...(dataDir === undefined ? {} : { dataDir }),
     ...(tail === undefined ? {} : { tail }),
     ...(positionals[0] === undefined ? {} : { runId: positionals[0] }),

package/src/cli/step-failure.ts

@@ -34,18 +34,33 @@ export async function stepFailureDetails(
   const snapshot = await client.runGet(runId);
   let fromSeq = 1;
   const failures = new Map<string, StepFailedDetails>();
+  // `runGet`'s `StepSnapshot` carries only `type`, `state` and an optional
+  // lease deadline — neither the attempt number nor the attempt budget. Both
+  // are journal facts: the envelope's `attempt` counts the attempt, and
+  // `step.attempt.started` records the `max_iterations` the kernel is
+  // enforcing (relayflowd-core/src/entry.rs `AttemptStartedPayload`). They are
+  // collected on the same walk and reported only when the journal held them.
+  const budgets = new Map<string, number>();
   while (true) {
     const { entries } = await client.journalRead(runId, fromSeq, 100);
     if (entries.length === 0) break;
     for (const raw of entries) {
       const entry = record(raw);
       const seq = entry?.['seq'];
-      if (typeof seq !== 'number' || !Number.isSafeInteger(seq) || seq < fromSeq) {
+      if (entry === undefined || typeof seq !== 'number' || !Number.isSafeInteger(seq) || seq < fromSeq) {
         throw new Error('invalid journal sequence in step failure inspection');
       }
       fromSeq = seq + 1;
-      const stepId = entry?.['step_id'];
-      if (entry?.['entry_type'] !== 'step.completed' || typeof stepId !== 'string') continue;
+      const stepId = entry['step_id'];
+      if (typeof stepId !== 'string') continue;
+      if (entry['entry_type'] === 'step.attempt.started') {
+        const maxIterations = record(entry['payload'])?.['max_iterations'];
+        if (typeof maxIterations === 'number' && Number.isSafeInteger(maxIterations) && maxIterations > 0) {
+          budgets.set(stepId, maxIterations);
+        }
+        continue;
+      }
+      if (entry['entry_type'] !== 'step.completed') continue;
       // A later completion supersedes an earlier failed attempt.
       failures.delete(stepId);
       const payload = record(entry['payload']);
@@ -59,10 +74,14 @@ export async function stepFailureDetails(
       if (payload['disposition'] !== 'step_done'
         || typeof completionReason !== 'string' || completionReason === 'success') continue;
       const stepType = snapshot.steps[stepId]?.type;
+      const attempt = entry['attempt'];
+      const maxIterations = budgets.get(stepId);
       failures.set(stepId, {
         stepId,
         completionReason,
         ...(stepType === undefined ? {} : { stepType }),
+        ...(typeof attempt === 'number' && Number.isSafeInteger(attempt) && attempt > 0 ? { attempt } : {}),
+        ...(maxIterations === undefined ? {} : { maxIterations }),
         ...evidence(payload),
       });
     }
@@ -70,6 +89,52 @@ export async function stepFailureDetails(
   return [...failures.values()].at(-1);
 }
 
+/**
+ * The evidence half of a `step_failed` diagnostic; `renderInspection` adds the
+ * rest. Each field is printed only when the journal actually carried it — an
+ * agent step has no exit code to report, and inventing `exit=undefined` (which
+ * is what the deterministic-only version printed for one) is worse than
+ * silence on that field.
+ *
+ * `attempt=N/M` is here for `retries_exhausted`, which is the kernel's terminal
+ * reason for "the attempt budget was consumed" (kernel/DESIGN.md) and is
+ * accurate kernel vocabulary that reads in English as though retries happened.
+ * A deterministic step gets the default budget of one, so a single failed
+ * attempt with no retry at all terminates as `retries_exhausted`. The
+ * vocabulary does not change (AGENTS.md rule 7); printing the facts beside it
+ * stops it being misread. Unknown values are omitted rather than defaulted —
+ * an absent budget must not be reported as one attempt.
+ *
+ * Lives next to `StepFailedDetails`'s extractor rather than in `cli/run.ts` so
+ * the authored `f.run` path can render the same grammar without importing the
+ * run lifecycle (which would be a cycle).
+ */
+export function renderStepEvidence(details: StepFailedDetails): string {
+  return ` Step ${JSON.stringify(details.stepId)}`
+    + (details.stepType === undefined ? '' : ` (${details.stepType})`)
+    + ` completionReason: ${details.completionReason}`
+    + renderAttempt(details)
+    + (details.exitCode === undefined ? '' : ` exit=${details.exitCode}`)
+    + '.'
+    + (details.detail === undefined ? '' : `\nDetail: ${details.detail}`)
+    + (details.stdoutTail ? `\nStdout (last 1,024 bytes):\n${details.stdoutTail}` : '')
+    + (details.stderrTail ? `\nStderr (last 1,024 bytes):\n${details.stderrTail}` : '')
+    + (details.transcriptPath === undefined ? '' : `\nTranscript: ${details.transcriptPath}`);
+}
+
+function renderAttempt(details: StepFailedDetails): string {
+  if (details.attempt === undefined) return '';
+  return ` attempt=${details.attempt}`
+    + (details.maxIterations === undefined ? '' : `/${details.maxIterations}`);
+}
+
+/** The `Inspect:`/`Journal:` tail every `step_failed` message ends with. */
+export function renderInspection(where: { hint?: string; journalPath?: string }): string {
+  if (where.hint === undefined) return '';
+  return `\nInspect: ${where.hint}`
+    + (where.journalPath === undefined ? '' : `\nJournal: ${where.journalPath}`);
+}
+
 /**
  * Where to look, derived from the run id and data dir ALONE.
  *

package/src/cli-commands.ts

@@ -1,4 +1,5 @@
 import { DEFAULT_DATA_DIR } from './daemon-connection.js';
+import { DEFAULT_RUN_LIMIT } from './cli/cloud-read.js';
 import type { ParsedArgs } from './cli.js';
 
 /**
@@ -181,6 +182,17 @@ export const CLI_VERBS = [
     ],
     variants: ['hn-monitor'],
   },
+  {
+    name: 'logs',
+    description: 'Read a hosted run’s runner log, or one agent step’s transcript, from Cloud',
+    args: [{ name: 'run-id', description: 'Hosted run id, as `flows runs` lists it', required: true }],
+    options: [
+      { flags: '--step <name>', description: 'Show that agent step’s transcript instead of the runner log' },
+      { flags: '--raw', description: 'Print the transcript JSONL unrendered (still redacted)' },
+      JSON_OPTION,
+    ],
+    variants: ['logs'],
+  },
   {
     name: 'observer',
     description: 'Mint a read-only observer link without running a flow',
@@ -231,6 +243,15 @@ export const CLI_VERBS = [
     ],
     variants: ['run', 'cloud-run'],
   },
+  {
+    name: 'runs',
+    description: 'List the hosted runs this Cloud credential can read, newest first',
+    options: [
+      { flags: '--limit <n>', description: 'How many runs to show', defaultValue: DEFAULT_RUN_LIMIT },
+      JSON_OPTION,
+    ],
+    variants: ['runs'],
+  },
   {
     name: 'schedule',
     description: 'Register a flow to run in Cloud on a cron or interval, or on the one it declares',
@@ -267,12 +288,13 @@ export const CLI_VERBS = [
   },
   {
     name: 'status',
-    description: 'Show a run’s steps, attempts, leases and last verdicts from its journal; offline, no daemon',
+    description: 'Show a run’s steps, attempts, leases and last verdicts from its journal, or from Cloud with --cloud',
     args: [{ name: 'run-id', description: 'Run to inspect; defaults to RELAYFLOW_RUN_ID inside a step', required: false }],
     options: [
       JSON_OPTION,
       DATA_DIR_OPTION,
       { flags: '--tail <n>', description: 'Lines of each agent attempt’s transcript tail to show' },
+      { flags: '--cloud', description: 'Read the run from Cloud instead of a local journal; needs the run id' },
     ],
     variants: ['status'],
   },

package/src/cli.ts

@@ -25,6 +25,10 @@ import { parseWebhookArgs, runServeWebhook } from './cli/serve-webhook.js';
 import { runDirectFlow } from './cli/direct-run.js';
 import { parseReplayArgs, replayJournal, type ReplayArgs } from './cli/replay.js';
 import { parseStatusArgs, runStatus, type StatusArgs } from './cli/status.js';
+import {
+  parseLogsArgs, parseRunsArgs, runCloudLogsCli, runCloudRunsCli, runCloudStatusCli,
+  type LogsArgs, type RunsArgs,
+} from './cli/cloud-read.js';
 import { transcriptTailSource } from './transcript-tail.js';
 import { checkTypeScriptFlow } from './cli/check-typescript.js';
 import { runCloudCli } from './cli/cloud-run.js';
@@ -77,6 +81,8 @@ export type ParsedArgs =
   | { command: 'run'; bucket: string | undefined; reuseFromRunId: string | undefined; localAgent: boolean; dataDir: string; input: string | undefined; json: boolean; spawn: boolean; noObserverLink: boolean; allowHumanInfluenced: boolean; value: string }
   | { command: 'resume'; localAgent: boolean; dataDir: string; json: boolean; spawn: boolean; noObserverLink: boolean; allowHumanInfluenced: boolean; value: string }
   | { command: 'answer'; dataDir: string; json: boolean; spawn: boolean; note: string | undefined; by: string | undefined; runId: string; waitId: string; answer: boolean }
+  | RunsArgs
+  | LogsArgs
   | { command: 'observer'; dataDir: string }
   | { command: 'hn-monitor'; sub: 'start'; dataDir: string; specPath: string; pollIntervalMs: number | undefined }
   | { command: 'tick'; sub: 'start'; dataDir: string; specPath: string; scheduleId: string;
@@ -108,6 +114,9 @@ const USAGE = [
   'flows answer [--json] [--no-spawn] [--data-dir <dir>] [--note <text>] [--by <identity>] <run-id> <wait-id> <yes|no>',
   'flows replay [--allow-human-influenced] [--json] [--data-dir <dir>] <run-id> [--at <step-id>]',
   'flows status [--json] [--data-dir <dir>] [--tail <n>] [<run-id>]',
+  'flows status --cloud [--json] <run-id>',
+  'flows runs [--limit <n>] [--json]',
+  'flows logs [--step <name>] [--raw] [--json] <run-id>',
   'flows observer [--data-dir <dir>]',
   'flows hn-monitor start [--data-dir <dir>] [--poll-interval-ms <n>] <spec.json>',
 ].join('\n');
@@ -201,7 +210,15 @@ export async function runCli(
   if (parsed.command === 'replay') return replayJournal(parsed, io);
   // Daemon-free like `check`: reads one journal file and nothing else, so it
   // works inside a step of a run whose daemon is gone (kernel/DAEMON-LIFECYCLE.md §4).
-  if (parsed.command === 'status') return runStatus(parsed, io, { tails: transcriptTailSource() });
+  if (parsed.command === 'status') {
+    // One verb, two sources. `--cloud` never reaches `runStatus`, so the
+    // offline reader stays offline (cli/status.ts).
+    return parsed.cloud === true
+      ? runCloudStatusCli(parsed, io)
+      : runStatus(parsed, io, { tails: transcriptTailSource() });
+  }
+  if (parsed.command === 'runs') return runCloudRunsCli(parsed, io);
+  if (parsed.command === 'logs') return runCloudLogsCli(parsed, io);
   if (parsed.command === 'answer') {
     const execution = await answerFlow(parsed.runId, parsed.waitId, parsed.answer, parsed.dataDir, {
       ...(parsed.note === undefined ? {} : { note: parsed.note }),
@@ -506,6 +523,8 @@ function parseArgs(args: readonly string[]): ParsedArgs | undefined {
   if (command === 'add') return args.length === 2 ? { command: 'add', value: args[1]! } : undefined;
   if (command === 'replay') return parseReplayArgs(args.slice(1));
   if (command === 'status') return parseStatusArgs(args.slice(1));
+  if (command === 'runs') return parseRunsArgs(args.slice(1));
+  if (command === 'logs') return parseLogsArgs(args.slice(1));
   if (command === 'build') return parseBuildArgs(args.slice(1));
   if (command === 'deploy') {
     // The positional decides the form: an authored source deploys a hosted

package/src/cloud-http.ts

@@ -21,7 +21,26 @@ export interface CloudRefusal {
   received?: { packageName?: string; version?: string };
 }
 
+/**
+ * Narrows a `configuration` failure to the thing that was wrong.
+ *
+ * `configuration` has always covered every local misconfiguration, and its
+ * message says which. A caller that must answer with a *code* — the read
+ * verbs print `REFUSED [cloud_auth_missing]` and name `agent-relay cloud
+ * login` — cannot get that from prose without matching on it. Optional and
+ * additive: every existing `catch` on `code === 'configuration'` is unchanged.
+ */
+export type CloudConfigurationReason =
+  | 'auth_missing'
+  | 'auth_expired'
+  | 'url_invalid'
+  | 'url_mismatch'
+  | 'timeout_invalid';
+
 export class CloudFlowError extends Error {
+  /** Set only for `configuration`; see {@link CloudConfigurationReason}. */
+  reason?: CloudConfigurationReason;
+
   constructor(
     readonly code: 'configuration' | 'unsupported_source' | 'invalid_input' | 'invalid_response' | 'http_error'
       | 'transport_error' | 'transient_error' | 'unsupported_storage_backend' | 'sync_too_large' | 'sync_unsupported'
@@ -35,6 +54,13 @@ export class CloudFlowError extends Error {
   }
 }
 
+/** A `configuration` refusal that also carries its {@link CloudConfigurationReason}. */
+function configurationError(reason: CloudConfigurationReason, message: string): CloudFlowError {
+  const error = new CloudFlowError('configuration', message);
+  error.reason = reason;
+  return error;
+}
+
 /**
  * The `agent-relay cloud login` credential store. Read only when neither the
  * `token` option nor `FLOWS_CLOUD_TOKEN` is set, so an explicit credential
@@ -79,7 +105,7 @@ export function cloudConnection(options: CloudConnectionOptions): { baseUrl: str
     if (login !== undefined) {
       const expiresAt = login.accessTokenExpiresAt === undefined ? Number.NaN : Date.parse(login.accessTokenExpiresAt);
       if (Number.isFinite(expiresAt) && expiresAt <= Date.now()) {
-        throw new CloudFlowError('configuration',
+        throw configurationError('auth_expired',
           'The agent-relay cloud login has expired. Run `agent-relay cloud login` again, or set FLOWS_CLOUD_TOKEN.');
       }
       rawToken = login.accessToken;
@@ -88,7 +114,7 @@ export function cloudConnection(options: CloudConnectionOptions): { baseUrl: str
   }
   const token = rawToken?.trim();
   if (!token || /[\r\n]/u.test(rawToken!) || /^(?:rk|ot)_live_/u.test(token)) {
-    throw new CloudFlowError('configuration',
+    throw configurationError('auth_missing',
       'Set FLOWS_CLOUD_TOKEN to a scoped Cloud API token (workflow:invoke:write and workflow:runs:read), '
       + 'or sign in with `agent-relay cloud login`.');
   }
@@ -96,11 +122,11 @@ export function cloudConnection(options: CloudConnectionOptions): { baseUrl: str
   try {
     url = new URL(options.apiUrl ?? process.env['FLOWS_CLOUD_URL'] ?? loginApiUrl ?? 'https://agentrelay.com/cloud');
   } catch {
-    throw new CloudFlowError('configuration', 'FLOWS_CLOUD_URL must be an absolute Cloud application base URL.');
+    throw configurationError('url_invalid', 'FLOWS_CLOUD_URL must be an absolute Cloud application base URL.');
   }
   if (url.protocol !== 'https:'
     || url.username || url.password || url.search || url.hash || !/^\/[A-Za-z0-9/_-]*$/u.test(url.pathname)) {
-    throw new CloudFlowError('configuration', 'Cloud URL must use HTTPS and a plain base path.');
+    throw configurationError('url_invalid', 'Cloud URL must use HTTPS and a plain base path.');
   }
   const baseUrl = `${url.origin}${url.pathname.replace(/\/+$/u, '')}`;
   // A login-store token is bound to the deployment that issued it. An explicit
@@ -113,7 +139,7 @@ export function cloudConnection(options: CloudConnectionOptions): { baseUrl: str
       issued = `${login.origin}${login.pathname.replace(/\/+$/u, '')}`;
     } catch { issued = undefined; }
     if (issued !== baseUrl) {
-      throw new CloudFlowError('configuration',
+      throw configurationError('url_mismatch',
         `The agent-relay cloud login was issued for ${loginApiUrl}, not ${baseUrl}. `
         + 'Set FLOWS_CLOUD_TOKEN for that deployment, or unset FLOWS_CLOUD_URL to use the login.');
     }
@@ -159,7 +185,7 @@ export async function cloudFetch(
   const { baseUrl, token } = cloudConnection(options);
   const timeout = options.requestTimeoutMs ?? 30_000;
   if (!Number.isSafeInteger(timeout) || timeout < 1 || timeout > 2_147_483_647) {
-    throw new CloudFlowError('configuration', 'requestTimeoutMs must be a positive 32-bit integer.');
+    throw configurationError('timeout_invalid', 'requestTimeoutMs must be a positive 32-bit integer.');
   }
   const bearer = init.bearerToken ?? token;
   if (/[\r\n]/u.test(bearer) || !bearer.trim()) {