@relayflows/sdk 2.0.38 → 2.0.40

package/src/authored-worker-step.ts

@@ -2,7 +2,8 @@ import { dirname, resolve, isAbsolute, relative, sep } from 'node:path';
 import type { AuthoredBudget } from './authored-budget.js';
 import { parseBudget } from './budget.js';
 import type { AgentOptions, AgentResult, LlmOptions, NamedGate } from '@relayflows/surface';
-import { compileSpec, toKernelSpec } from './compile.js';
+import { compileSpec, toKernelSpec, parseAgentStepTimeout } from './compile.js';
+import { isTransportRetries } from './validate.js';
 import { authoredPreflight } from './authored-preflight.js';
 import { classifyOutcome, type RunLifecycleOptions, type RunReport } from './cli/run.js';
 import type { PreflightDiagnostic } from './preflight.js';
@@ -18,6 +19,7 @@ import { alsoRecord, recordAuthoredChild } from './authored-step-index.js';
 import type { StepFailedDetails } from './failure-kinds.js';
 import { authoredWorkerSlots, type AuthoredWorkerSlots } from './worker-slots.js';
 
+const AGENT_TIMEOUT = Symbol('declared agent timeout');
 const WORKSPACE_PERMISSION_ANNOTATION = /:\s*(readonly|readwrite)\s*$/i;
 
 /** Agent and LLM calls share the exact declarative preflight and lease wait. */
@@ -117,6 +119,7 @@ export function authoredWorkerRunner(
       const diagnostic = execution.report.diagnostics.at(-1);
       const details = stepDetails(diagnostic);
       const reason = execution.report.completionReason;
+      let indexFailure = '';
       let message = diagnostic?.message
         ?? `flow "${definition.name}" step "${id}" did not complete successfully `
           + `(status: ${execution.report.status ?? 'unknown'})`;
@@ -127,13 +130,21 @@ export function authoredWorkerRunner(
         journalSteps.push(Object.freeze({
           id, runId: outcome.run_id, completionReason: details.completionReason, ...stepEdges?.(id),
         }));
-        message += await alsoRecord(journal, rootRunId, {
+        indexFailure = await alsoRecord(journal, rootRunId, {
           step: id, runId: outcome.run_id, state: 'completed',
           completionReason: details.completionReason,
           ...(details.stepId === undefined ? {} : { kernelStep: details.stepId }),
           ...stepEdges?.(id),
         });
       }
+      message += indexFailure;
+      // Resolve inside consume so budget accounting does not latch a failure.
+      // A failed index append must still fail closed, even for a tolerated timeout.
+      if (indexFailure === '' && reason === 'step_failed' && execution.report.status === 'failed'
+        && spec.steps.length === 1 && step.type === 'agent' && step.timeoutMs !== undefined
+        && details?.stepId === id && details.stepType === 'agent' && details.completionReason === 'timeout') {
+        return { [AGENT_TIMEOUT]: details.stderrTail ?? message };
+      }
       throw new AuthoredFlowExecutionError(
         'step_failed', message,
         isSurfaceCompletionReason(reason) ? reason : undefined,
@@ -217,15 +228,47 @@ export function authoredWorkerRunner(
           `f.agent options.transport must be 'direct' or 'relay' (got ${JSON.stringify(options.transport)}).`,
         );
       }
+      if (options.maxIterations !== undefined
+        && (!Number.isSafeInteger(options.maxIterations) || options.maxIterations < 1)) {
+        throw new AuthoredFlowExecutionError(
+          'agent_cli_unresolved',
+          `f.agent options.maxIterations must be a positive integer (got ${JSON.stringify(options.maxIterations)}).`,
+        );
+      }
+      if (options.transportRetries !== undefined && !isTransportRetries(options.transportRetries)) {
+        throw new AuthoredFlowExecutionError(
+          'agent_cli_unresolved',
+          `f.agent options.transportRetries must be a non-negative integer (got ${JSON.stringify(options.transportRetries)}).`,
+        );
+      }
+      if (options.recoveryMode !== undefined
+        && options.recoveryMode !== 'reset'
+        && options.recoveryMode !== 'inspect'
+        && options.recoveryMode !== 'manual') {
+        throw new AuthoredFlowExecutionError(
+          'agent_cli_unresolved',
+          `f.agent options.recoveryMode must be 'reset', 'inspect', or 'manual' (got ${JSON.stringify(options.recoveryMode)}).`,
+        );
+      }
       const cwdTransport = agentCwdTransportError(declaredCwd, options.transport);
       if (cwdTransport !== undefined) {
         throw new AuthoredFlowExecutionError('agent_cli_unresolved', `f.agent options.${cwdTransport}.`);
       }
+      let timeoutMs: number | undefined;
+      if (options.timeout !== undefined) {
+        try { timeoutMs = parseAgentStepTimeout(options.timeout); }
+        catch (error) { throw new AuthoredFlowExecutionError('agent_cli_unresolved', String(error)); }
+        if (options.transport === 'relay' || (options.maxIterations ?? 1) > 1) {
+          throw new AuthoredFlowExecutionError('agent_cli_unresolved',
+            'f.agent timeout requires direct transport and maxIterations 1.');
+        }
+      }
       const permissions = options.permissions;
       const permissionsSnapshot = permissions === undefined ? undefined
         : snapshotJsonValue(permissions, 'f.agent options.permissions') as unknown as PermissionsSpec;
       const output = await run({
         id, type: 'agent', instruction: options.task,
+        ...(timeoutMs === undefined ? {} : { timeoutMs }),
         ...(permissionsSnapshot === undefined ? {} : { permissions: permissionsSnapshot }),
         ...(localAgentStream === undefined ? {} : { surfaces: { streams: [{ stream: localAgentStream }] } }),
         ...(options.workspace === undefined ? {} : { surfaces: { workspace: [{ surface: options.workspace }] } }),
@@ -233,11 +276,17 @@ export function authoredWorkerRunner(
         ...(options.model === undefined ? {} : { model: options.model }),
         ...(declaredCwd === undefined ? {} : { cwd: declaredCwd }),
         ...(options.transport === undefined ? {} : { transport: options.transport }),
+        ...(options.maxIterations === undefined ? {} : { maxIterations: options.maxIterations }),
+        ...(options.transportRetries === undefined ? {} : { transportRetries: options.transportRetries }),
+        ...(options.recoveryMode === undefined ? {} : { recoveryMode: options.recoveryMode }),
         ...(verification === undefined ? {} : { verification }),
       });
       if (typeof output !== 'object' || output === null || Array.isArray(output)) {
         throw new AuthoredFlowExecutionError('journal_protocol_violation', `step "${id}" produced a non-object output`);
       }
+      if (AGENT_TIMEOUT in output && timeoutMs !== undefined) {
+        return { completionReason: 'timeout', summary: String(output[AGENT_TIMEOUT]), artifacts: [] };
+      }
       const stdout = 'stdout_tail' in output ? output.stdout_tail : undefined;
       // The worker that ran the CLI measured the artifacts and journaled them
       // in the step's output; read that fact back rather than re-scanning a
@@ -245,7 +294,7 @@ export function authoredWorkerRunner(
       const journaled = 'artifacts' in output ? output.artifacts : undefined;
       const artifacts = Array.isArray(journaled) && journaled.every(entry => typeof entry === 'string')
         ? [...journaled] : [];
-      return { summary: typeof stdout === 'string' ? stdout : JSON.stringify(output), artifacts };
+      return { completionReason: 'success', summary: typeof stdout === 'string' ? stdout : JSON.stringify(output), artifacts };
     },
     async llm(id: string, prompt: string, options?: LlmOptions, verification?: NamedGate): Promise<unknown> {
       if (options !== undefined && (typeof options !== 'object' || options === null || options.output === undefined)) {
@@ -343,8 +392,14 @@ function stepDetails(
     ...(found.completionReason === undefined ? {} : { completionReason: found.completionReason }),
     ...(found.attempt === undefined ? {} : { attempt: found.attempt }),
     ...(found.maxIterations === undefined ? {} : { maxIterations: found.maxIterations }),
+    ...(found.transportRetries === undefined ? {} : { transportRetries: found.transportRetries }),
     ...(found.unchargedAttempts === undefined ? {} : { unchargedAttempts: found.unchargedAttempts }),
     ...(found.exitCode === undefined ? {} : { exitCode: found.exitCode }),
+    ...(found.transportPhase === undefined ? {} : { transportPhase: found.transportPhase }),
+    ...(found.transportCause === undefined ? {} : { transportCause: found.transportCause }),
+    ...(found.signal === undefined ? {} : { signal: found.signal }),
+    ...(found.errorCode === undefined ? {} : { errorCode: found.errorCode }),
+    ...(found.retryableTransport === undefined ? {} : { retryableTransport: found.retryableTransport }),
     ...(found.stdoutTail === undefined ? {} : { stdoutTail: found.stdoutTail }),
     ...(found.stderrTail === undefined ? {} : { stderrTail: found.stderrTail }),
     ...(found.detail === undefined ? {} : { detail: found.detail }),

package/src/cli/cloud-deploy.ts

@@ -4,13 +4,17 @@ import {
   type FlowTriggerSource,
 } from '../cloud-deploy.js';
 import { describeFlowRequirements } from '../flow-requirements.js';
+import { describeVersionChange } from '../cloud-versions-wire.js';
+import { runCloudDeployVersionCli } from './cloud-versions.js';
 import { cliConnectPrompt, flowRequirementsForPath, harnessRemedy } from './cloud-connect-cli.js';
 import type { CliIo } from '../cli.js';
 
 export interface CloudDeployArgs {
   command: 'cloud-deploy';
   value: string;
-  repo: string;
+  /** Update form: the flow (name or listener id) this source becomes the next version of. */
+  flow: string | undefined;
+  repo: string | undefined;
   on: string[];
   approver: string | undefined;
   name: string | undefined;
@@ -25,6 +29,11 @@ export interface CloudDeployArgs {
 /**
  * `flows deploy <flow.ts> --repo <owner/name> --on <provider>[:k=v,…] [--on …]
  *   --approver <handle> [--name <n>] [--agents <list>] [--draft] [--no-connect] [--json]`
+ * `flows deploy <flow.ts> --flow <name-or-listener-id> [--plugin <ref>] [--no-connect] [--json]`
+ *
+ * The `--flow` form makes the source the next version of an existing flow and
+ * changes nothing else; listener settings given beside it are refused when run,
+ * by name, rather than silently ignored.
  *
  * Parsed here rather than in `parseDeployArgs` because the two `deploy` forms
  * share nothing but the word: the digest form copies a sealed bundle into a
@@ -32,6 +41,7 @@ export interface CloudDeployArgs {
  */
 export function parseCloudDeployArgs(args: readonly string[]): CloudDeployArgs | undefined {
   let value: string | undefined;
+  let flow: string | undefined;
   let repo: string | undefined;
   let approver: string | undefined;
   let name: string | undefined;
@@ -72,11 +82,12 @@ export function parseCloudDeployArgs(args: readonly string[]): CloudDeployArgs |
       i += 1;
       continue;
     }
-    if (arg === '--repo' || arg === '--approver' || arg === '--name' || arg === '--on') {
+    if (arg === '--repo' || arg === '--approver' || arg === '--name' || arg === '--on' || arg === '--flow') {
       const next = args[i + 1];
       if (next === undefined || next.startsWith('-')) return undefined;
       i += 1;
       if (arg === '--on') { on.push(next); continue; }
+      if (arg === '--flow') { if (flow !== undefined) return undefined; flow = next; continue; }
       if (arg === '--repo') { if (repo !== undefined) return undefined; repo = next; continue; }
       if (arg === '--approver') { if (approver !== undefined) return undefined; approver = next; continue; }
       if (name !== undefined) return undefined;
@@ -86,8 +97,9 @@ export function parseCloudDeployArgs(args: readonly string[]): CloudDeployArgs |
     if (arg.startsWith('-') || value !== undefined) return undefined;
     value = arg;
   }
-  if (value === undefined || repo === undefined || on.length === 0) return undefined;
-  return { command: 'cloud-deploy', value, repo, on, approver, name, agents, draft, noConnect, json, plugins };
+  if (value === undefined) return undefined;
+  if (flow === undefined && (repo === undefined || on.length === 0)) return undefined;
+  return { command: 'cloud-deploy', value, flow, repo, on, approver, name, agents, draft, noConnect, json, plugins };
 }
 
 function describeSource(source: FlowTriggerSource): string {
@@ -96,6 +108,7 @@ function describeSource(source: FlowTriggerSource): string {
 }
 
 export async function runCloudDeployCli(args: CloudDeployArgs, io: CliIo): Promise<0 | 1 | 2> {
+  if (args.flow !== undefined) return runCloudDeployVersionCli({ ...args, flow: args.flow }, io);
   const agents = args.agents === undefined ? undefined : parseAgentHarnessesOr(args.agents);
   // What the source declares, so a harness refusal names the right remedy
   // even when `--agents` was not given; the loader's own failure is reported
@@ -111,7 +124,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),
+      repository: parseRepository(args.repo!),
       sources: args.on.map(parseTriggerSource),
       approver: args.approver,
       draft: args.draft,
@@ -124,7 +137,8 @@ export async function runCloudDeployCli(args: CloudDeployArgs, io: CliIo): Promi
       io.stdout(JSON.stringify({ ok: true, ...deployment }));
       return 0;
     }
-    io.stdout(`${deployment.status === 'draft' ? 'SAVED' : 'DEPLOYED'} ${deployment.agentId} ${deployment.status}`);
+    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: ${deployment.repository.owner}/${deployment.repository.name}`);
     for (const source of deployment.sources) io.stdout(`  on: ${describeSource(source)}`);
@@ -181,7 +195,7 @@ export async function runCloudUndeployCli({ agentId, json }: { agentId: string;
   }
 }
 
-function reportCloudFailure(error: unknown, json: boolean, io: CliIo, harnesses: readonly string[] = []): 1 | 2 {
+export function reportCloudFailure(error: unknown, json: boolean, io: CliIo, harnesses: readonly string[] = []): 1 | 2 {
   const code = error instanceof CloudFlowError ? error.code : 'cloud_deploy_failed';
   let message = error instanceof Error ? error.message : 'Cloud deploy failed.';
   // Cloud names the missing coding-agent credential on activation; say how it is connected.

package/src/cli/cloud-versions.ts

@@ -0,0 +1,103 @@
+import { CloudFlowError } from '../cloud-http.js';
+import {
+  activateCloudFlowVersion, deployVersionToCloud, getCloudListener, resolveCloudFlow,
+} from '../cloud-versions.js';
+import { describeVersionChange } from '../cloud-versions-wire.js';
+import { describeFlowRequirements } from '../flow-requirements.js';
+import { cliConnectPrompt } from './cloud-connect-cli.js';
+import { reportCloudFailure, type CloudDeployArgs } from './cloud-deploy.js';
+import type { CliIo } from '../cli.js';
+
+/**
+ * `flows deploy <flow.ts> --flow <name-or-id>`: the source becomes the next
+ * version of that flow. Listener settings are not part of a version, so a
+ * flag that would change one is refused by name instead of being dropped.
+ */
+export async function runCloudDeployVersionCli(
+  args: CloudDeployArgs & { flow: string }, io: CliIo,
+): Promise<0 | 1 | 2> {
+  try {
+    const settings = [
+      args.repo === undefined ? undefined : '--repo',
+      args.on.length === 0 ? undefined : '--on',
+      args.approver === undefined ? undefined : '--approver',
+      args.name === undefined ? undefined : '--name',
+      args.agents === undefined ? undefined : '--agents',
+      args.draft ? '--draft' : undefined,
+    ].filter((flag): flag is string => flag !== undefined);
+    if (settings.length > 0) {
+      throw new CloudFlowError('invalid_input',
+        `--flow deploys a new version of the flow's source only; ${settings.join(', ')} stay on the listener. `
+        + 'Drop them, or change them in the Cloud dashboard.');
+    }
+    const connect = cliConnectPrompt(io, { noConnect: args.noConnect, json: args.json });
+    const deployment = await deployVersionToCloud({
+      path: args.value,
+      flow: args.flow,
+      ...(connect === undefined ? {} : { connect }),
+      ...(args.plugins.length === 0 ? {} : { plugins: args.plugins }),
+    });
+    if (args.json) {
+      io.stdout(JSON.stringify({ ok: true, ...deployment }));
+      return 0;
+    }
+    io.stdout(`${deployment.status === 'draft' ? 'SAVED' : 'DEPLOYED'} ${deployment.agentId} ${deployment.status}`
+      + ` · ${describeVersionChange(deployment.version)}`);
+    io.stdout(`  flow: ${deployment.name} (${args.value}, sha256 ${deployment.sourceSha256.slice(0, 12)})`);
+    const requires = describeFlowRequirements(deployment.requirements);
+    if (requires) io.stdout(`  requires: ${requires}`);
+    for (const provider of deployment.connected) io.stdout(`  connected: ${provider}`);
+    io.stdout('New runs launch this version; runs already started finish on theirs. History: flows versions '
+      + JSON.stringify(deployment.name));
+    return 0;
+  } catch (error) {
+    return reportCloudFailure(error, args.json, io);
+  }
+}
+
+/** `flows versions <name-or-id>`: newest first, the active one marked. */
+export async function runCloudVersionsCli(
+  { flow, json }: { flow: string; json: boolean }, io: CliIo,
+): Promise<0 | 1 | 2> {
+  try {
+    const listener = await getCloudListener(await resolveCloudFlow(flow));
+    if (json) {
+      io.stdout(JSON.stringify({
+        ok: true, agentId: listener.agentId, name: listener.name,
+        activeVersion: listener.activeVersion?.version ?? null, versions: listener.versions,
+      }));
+      return 0;
+    }
+    if (listener.versions.length === 0) {
+      io.stdout(`${listener.agentId} ${JSON.stringify(listener.name)} has no recorded versions.`);
+      return 0;
+    }
+    io.stdout(`${listener.agentId} ${JSON.stringify(listener.name)} ${listener.status}`);
+    for (const version of listener.versions) {
+      const active = version.version === listener.activeVersion?.version ? ' (active)' : '';
+      io.stdout(`  version ${version.version}${active}  ${version.createdAt}  ${version.origin}  sha256 ${version.sourceSha256.slice(0, 12)}`);
+    }
+    return 0;
+  } catch (error) {
+    return reportCloudFailure(error, json, io);
+  }
+}
+
+/** `flows rollback <name-or-id> <version>`: move the pointer; later versions stay recorded. */
+export async function runCloudRollbackCli(
+  { flow, version, json }: { flow: string; version: string; json: boolean }, io: CliIo,
+): Promise<0 | 1 | 2> {
+  try {
+    // Cloud numbers versions up to nine digits; anything longer cannot exist.
+    if (!/^[1-9][0-9]{0,8}$/u.test(version)) {
+      throw new CloudFlowError('invalid_input', `A version is a positive whole number, got "${version}".`);
+    }
+    const result = await activateCloudFlowVersion(flow, Number(version));
+    io.stdout(json
+      ? JSON.stringify({ ok: true, ...result })
+      : `ACTIVATED ${result.agentId} ${result.status} · ${describeVersionChange(result.version)}`);
+    return 0;
+  } catch (error) {
+    return reportCloudFailure(error, json, io);
+  }
+}

package/src/cli/step-evidence.ts

@@ -17,6 +17,13 @@ export const ATTEMPT_TAIL_BYTES = 256;
  */
 const PRODUCER_TRUNCATED = /…\s*\((?:render bounded|[\d,]+ bytes truncated)\)$/u;
 
+/**
+ * What the worker puts in front of a stderr it cut to its tail (`boundedTail`
+ * in worker.ts and cli-transport-evidence.ts). The same rule applies: equal
+ * surviving tails cannot establish equal failures.
+ */
+const STDERR_TRUNCATED = /^\[(?:worker|transport) stderr: [\d,]+ bytes truncated\]…/u;
+
 /**
  * The evidence fields a step failure reports, as the journal held them.
  *
@@ -29,6 +36,11 @@ const PRODUCER_TRUNCATED = /…\s*\((?:render bounded|[\d,]+ bytes truncated)\)$
  */
 export interface SelectedEvidence {
   exitCode?: number;
+  transportPhase?: string;
+  transportCause?: string;
+  signal?: string;
+  errorCode?: string;
+  retryableTransport?: boolean;
   /** Present only when nonempty. */
   stdoutTail?: string;
   /** Present whenever the journal carried one, including the empty string. */
@@ -57,16 +69,18 @@ export interface SelectedEvidence {
 export function selectEvidence(payload: Record<string, unknown>): SelectedEvidence {
   const detail = record(payload['verification'])?.['detail'];
   const rendered = typeof detail === 'string' ? parsed(detail) : undefined;
+  const trajectory = record(payload['trajectory_tail']);
+  const transport = record(trajectory?.['transport']);
   const candidates = [
     record(payload['output']),
-    record(payload['trajectory_tail']),
+    trajectory,
     rendered,
   ].filter((candidate): candidate is Record<string, unknown> => candidate !== undefined);
   const structured = candidates.find(processShaped) ?? candidates[0];
-  const exitCode = structured?.['exit_code'];
+  const exitCode = structured?.['exit_code'] ?? transport?.['exit_code'];
   const stdout = structured?.['stdout_tail'];
-  const stderr = structured?.['stderr_tail'];
-  const transcript = record(record(payload['trajectory_tail'])?.['transcript']);
+  const stderr = structured?.['stderr_tail'] ?? transport?.['stderr_tail'];
+  const transcript = record(trajectory?.['transcript']);
   const failure = record(transcript?.['failure']);
   const excerpt = failure?.['excerpt'];
   const transcriptPath = record(transcript?.['file'])?.['path'];
@@ -77,6 +91,11 @@ export function selectEvidence(payload: Record<string, unknown>): SelectedEviden
     ? excerpt : undefined;
   return {
     ...(typeof exitCode === 'number' && Number.isSafeInteger(exitCode) ? { exitCode } : {}),
+    ...(typeof transport?.['phase'] === 'string' ? { transportPhase: transport['phase'] } : {}),
+    ...(typeof transport?.['cause'] === 'string' ? { transportCause: transport['cause'] } : {}),
+    ...(typeof transport?.['signal'] === 'string' ? { signal: transport['signal'] } : {}),
+    ...(typeof transport?.['error_code'] === 'string' ? { errorCode: transport['error_code'] } : {}),
+    ...(typeof transport?.['retryable'] === 'boolean' ? { retryableTransport: transport['retryable'] } : {}),
     ...(typeof stdout === 'string' && stdout.length > 0 ? { stdoutTail: stdout } : {}),
     ...(typeof stderr === 'string' ? { stderrTail: stderr } : {}),
     ...(excerptDetail !== undefined ? { detail: excerptDetail }
@@ -117,6 +136,11 @@ export function terminalEvidence(payload: Record<string, unknown>): Partial<Step
   const selected = selectEvidence(payload);
   return {
     ...(selected.exitCode === undefined ? {} : { exitCode: selected.exitCode }),
+    ...(selected.transportPhase === undefined ? {} : { transportPhase: formatStepExcerpt(selected.transportPhase) }),
+    ...(selected.transportCause === undefined ? {} : { transportCause: formatStepExcerpt(selected.transportCause) }),
+    ...(selected.signal === undefined ? {} : { signal: formatStepExcerpt(selected.signal) }),
+    ...(selected.errorCode === undefined ? {} : { errorCode: formatStepExcerpt(selected.errorCode) }),
+    ...(selected.retryableTransport === undefined ? {} : { retryableTransport: selected.retryableTransport }),
     ...(selected.stdoutTail === undefined ? {} : { stdoutTail: formatStepExcerpt(selected.stdoutTail) }),
     ...(selected.stderrTail === undefined ? {} : { stderrTail: formatStepExcerpt(selected.stderrTail) }),
     ...(selected.detail === undefined ? {} : { detail: formatStepExcerpt(selected.detail) }),
@@ -151,6 +175,13 @@ export function attemptFailure(
     completionReason,
     ...(typeof disposition === 'string' && disposition.length > 0 ? { disposition } : {}),
     ...(selected.exitCode === undefined ? {} : { exitCode: selected.exitCode }),
+    // Closed-vocabulary scalars, so a crash that left no stderr still says how
+    // it died (`signal=SIGKILL`) rather than reading as no evidence at all.
+    ...(selected.signal === undefined ? {} : { signal: bound(selected.signal) }),
+    ...(selected.transportCause === undefined ? {} : { transportCause: bound(selected.transportCause) }),
+    ...(selected.transportPhase === undefined ? {} : { transportPhase: bound(selected.transportPhase) }),
+    ...(selected.errorCode === undefined ? {} : { errorCode: bound(selected.errorCode) }),
+    ...(selected.retryableTransport === undefined ? {} : { retryableTransport: selected.retryableTransport }),
     ...(selected.stdoutTail === undefined ? {} : { stdoutTail: bound(selected.stdoutTail) }),
     ...(selected.stderrTail === undefined ? {} : { stderrTail: bound(selected.stderrTail) }),
     ...(selected.detail === undefined ? {} : { detail: bound(selected.detail) }),
@@ -177,15 +208,18 @@ export function failureCause(
   const verification = record(payload['verification']);
   const output = record(payload['output']);
   const trajectory = record(payload['trajectory_tail']);
+  const transport = record(trajectory?.['transport']);
   const failure = record(record(trajectory?.['transcript'])?.['failure']);
   const verificationDetail = text(verification?.['detail']);
   const accounts = [
     verificationDetail,
     text(output?.['stdout_tail']), text(output?.['stderr_tail']),
     text(trajectory?.['stdout_tail']), text(trajectory?.['stderr_tail']),
+    text(transport?.['phase']), text(transport?.['cause']), text(transport?.['signal']),
+    text(transport?.['error_code']), text(transport?.['stderr_tail']),
     text(failure?.['excerpt']),
   ];
-  const exitCodes = [output?.['exit_code'], trajectory?.['exit_code']]
+  const exitCodes = [output?.['exit_code'], trajectory?.['exit_code'], transport?.['exit_code']]
     .filter(value => typeof value === 'number');
   return {
     key: JSON.stringify([
@@ -197,13 +231,15 @@ export function failureCause(
       completionReason === 'verification_failed' || completionReason === 'retries_exhausted'
         ? 'kernel_rejected' : completionReason,
       text(verification?.['gate']), text(verification?.['verdict']), verificationDetail,
-      ...exitCodes, ...accounts, text(failure?.['kind']),
+      ...exitCodes, ...accounts, transport?.['retryable'], text(failure?.['kind']),
     ]),
     // An attempt that journaled nothing about itself cannot agree with
     // another one; it can only fail to disagree.
     recorded: exitCodes.length > 0 || accounts.some(account => account !== undefined),
     producerTruncated: (verificationDetail !== undefined
       && PRODUCER_TRUNCATED.test(verificationDetail))
+      || [output?.['stderr_tail'], trajectory?.['stderr_tail'], transport?.['stderr_tail']]
+        .some(stderr => typeof stderr === 'string' && STDERR_TRUNCATED.test(stderr))
       // The transcript digest's own flag (`boundTranscriptDigest`,
       // agent-transcript.ts): the worker already cut this excerpt, so equal
       // survivors cannot establish identical failures either.
@@ -255,8 +291,16 @@ export function renderAttemptHistory(details: StepFailedDetails): string {
 }
 
 function renderAttempt(attempt: StepAttemptFailure): string {
+  const transport = [
+    attempt.signal === undefined ? '' : ` signal=${attempt.signal}`,
+    attempt.transportCause === undefined ? '' : ` transport=${attempt.transportCause}`,
+    attempt.transportPhase === undefined ? '' : ` phase=${attempt.transportPhase}`,
+    attempt.errorCode === undefined ? '' : ` error_code=${attempt.errorCode}`,
+    attempt.retryableTransport === undefined ? '' : ` retryable=${attempt.retryableTransport}`,
+  ].join('');
   const head = `  attempt ${attempt.attempt ?? '?'}: ${attempt.completionReason ?? 'unknown'}`
     + (attempt.exitCode === undefined ? '' : ` exit=${attempt.exitCode}`)
+    + transport
     + (attempt.truncated ? ' (excerpt truncated)' : '');
   // An empty `stderrTail` is a journaled fact but not an account of anything,
   // so it never displaces useful stdout the way `detail ?? stderr ?? stdout`
@@ -264,7 +308,7 @@ function renderAttempt(attempt: StepAttemptFailure): string {
   const accounts: Array<[string, string]> = [
     ['detail', attempt.detail], ['stderr', attempt.stderrTail], ['stdout', attempt.stdoutTail],
   ].filter((pair): pair is [string, string] => typeof pair[1] === 'string' && pair[1].length > 0);
-  if (accounts.length === 0) return `${head} — no failure evidence recorded`;
+  if (accounts.length === 0) return transport === '' ? `${head} — no failure evidence recorded` : head;
   const [only] = accounts;
   if (accounts.length === 1 && !only![1].includes('\n')) return `${head} — ${only![0]}: ${only![1]}`;
   return [head, ...accounts.map(([label, value]) => indent(`${label}: ${value}`))].join('\n');

package/src/cli/step-failure.ts

@@ -60,6 +60,7 @@ export async function stepFailureDetails(
   // 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>();
+  const transportBudgets = new Map<string, number>();
   // Keyed by step, so interleaved steps never pool their attempts and a page
   // boundary never splits one step's history.
   const histories = new Map<string, AttemptHistory>();
@@ -82,6 +83,10 @@ export async function stepFailureDetails(
         if (typeof maxIterations === 'number' && Number.isSafeInteger(maxIterations) && maxIterations > 0) {
           budgets.set(stepId, maxIterations);
         }
+        const transportRetries = record(entry['payload'])?.['max_transport_retries'];
+        if (typeof transportRetries === 'number' && Number.isSafeInteger(transportRetries) && transportRetries >= 0) {
+          transportBudgets.set(stepId, transportRetries);
+        }
         continue;
       }
       if (entry['entry_type'] !== 'step.completed') continue;
@@ -117,12 +122,14 @@ export async function stepFailureDetails(
       const stepType = snapshot.steps[stepId]?.type;
       const attempt = entry['attempt'];
       const maxIterations = budgets.get(stepId);
+      const transportRetries = transportBudgets.get(stepId);
       failures.set(stepId, {
         stepId,
         completionReason,
         ...(stepType === undefined ? {} : { stepType }),
         ...(typeof attempt === 'number' && Number.isSafeInteger(attempt) && attempt > 0 ? { attempt } : {}),
         ...(maxIterations === undefined ? {} : { maxIterations }),
+        ...(transportRetries === undefined ? {} : { transportRetries }),
         ...((uncharged.get(stepId) ?? 0) > 0 ? { unchargedAttempts: uncharged.get(stepId) } : {}),
         ...terminalEvidence(payload),
         // A single failed attempt is already fully described by the scalars
@@ -166,7 +173,13 @@ export function renderStepEvidence(details: StepFailedDetails): string {
     + (details.stepType === undefined ? '' : ` (${details.stepType})`)
     + ` completionReason: ${details.completionReason}`
     + renderAttempt(details)
+    + (details.transportRetries === undefined ? '' : ` transportRetries=${details.transportRetries}`)
     + (details.exitCode === undefined ? '' : ` exit=${details.exitCode}`)
+    + (details.signal === undefined ? '' : ` signal=${details.signal}`)
+    + (details.transportCause === undefined ? '' : ` transport=${details.transportCause}`)
+    + (details.transportPhase === undefined ? '' : ` phase=${details.transportPhase}`)
+    + (details.errorCode === undefined ? '' : ` error_code=${details.errorCode}`)
+    + (details.retryableTransport === undefined ? '' : ` retryable=${details.retryableTransport}`)
     + '.'
     + renderAttemptHistory(details)
     + (details.detail === undefined ? '' : `\nDetail: ${details.detail}`)

package/src/cli-commands.ts

@@ -163,11 +163,29 @@ export const CLI_VERBS = [
       { flags: '--name <name>', description: 'Name for the hosted listener' },
       { flags: '--draft', description: 'Create the listener without activating it' },
       { flags: '--plugin <ref>', description: 'Send-only GitHub flow-extension ref; repeatable. Does not write flows.json' },
+      { flags: '--flow <name|listener-id>', description: 'Deploy the source as the next version of this flow; its settings stay unchanged' },
       NO_CONNECT_OPTION,
       JSON_OPTION,
     ],
     variants: ['deploy', 'cloud-deploy'],
   },
+  {
+    name: 'versions',
+    description: 'List a hosted flow’s source versions, the active one marked',
+    args: [{ name: 'flow', description: 'Flow name or listener id', required: true }],
+    options: [JSON_OPTION],
+    variants: ['versions'],
+  },
+  {
+    name: 'rollback',
+    description: 'Make an earlier (or later) recorded version of a hosted flow the active one',
+    args: [
+      { name: 'flow', description: 'Flow name or listener id', required: true },
+      { name: 'version', description: 'Version number to activate', required: true },
+    ],
+    options: [JSON_OPTION],
+    variants: ['rollback'],
+  },
   {
     name: 'deployments',
     description: 'List this workspace’s hosted trigger listeners',

package/src/cli-transport-evidence.ts

@@ -0,0 +1,70 @@
+import { boundedTail, redactText } from './agent-transcript.js';
+
+export type CliTransportPhase = 'spawn' | 'close' | 'abort' | 'timeout' | 'result_exit_grace';
+export type CliTransportCause =
+  | 'exited'
+  | 'nonzero_exit'
+  | 'signal'
+  | 'close_without_status'
+  | 'spawn_error'
+  | 'process_error'
+  | 'lease_lost'
+  | 'timeout'
+  | 'result_exit_timeout'
+  | 'codex_stdin_lifecycle';
+
+export interface CliTransportEvidence {
+  phase: CliTransportPhase;
+  cause: CliTransportCause;
+  exit_code: number | null;
+  signal: NodeJS.Signals | null;
+  /** OS/libuv error code, never an unbounded error message. */
+  error_code?: string;
+  /** True only for a closed set of infrastructure failures. */
+  retryable: boolean;
+  /** Redacted UTF-8 tail with its truncation made explicit. */
+  stderr_tail: string;
+}
+
+/** Infrastructure classification is deliberately narrower than "nonzero". */
+export function agentCompletionReason(
+  result: { exit_code: number | null; transport?: CliTransportEvidence },
+): 'success' | 'crashed' | 'timeout' | 'worker_error' {
+  if (result.exit_code === 0) return 'success';
+  if (result.transport?.retryable === true) return 'crashed';
+  if (result.transport?.cause === 'timeout') return 'timeout';
+  return 'worker_error';
+}
+
+const TRANSPORT_STDERR_MAX_BYTES = 2 * 1024;
+const RETRYABLE_SPAWN_ERROR_CODES = new Set(['EAGAIN', 'EMFILE', 'ENFILE', 'ENOMEM', 'ETXTBSY']);
+
+export function isRetryableSpawnError(code: string | undefined): boolean {
+  return code !== undefined && RETRYABLE_SPAWN_ERROR_CODES.has(code);
+}
+
+export function transportEvidence(
+  value: {
+    phase: CliTransportPhase;
+    cause: CliTransportCause;
+    exitCode: number | null;
+    signal: NodeJS.Signals | null;
+    stderr: string;
+    errorCode?: string;
+    retryable: boolean;
+  },
+  env: NodeJS.ProcessEnv,
+): CliTransportEvidence {
+  const bounded = boundedTail(redactText(value.stderr, env), TRANSPORT_STDERR_MAX_BYTES, 'transport stderr: ');
+  const errorCode = value.errorCode !== undefined && /^[A-Z0-9_-]{1,64}$/.test(value.errorCode)
+    ? value.errorCode : undefined;
+  return {
+    phase: value.phase,
+    cause: value.cause,
+    exit_code: value.exitCode,
+    signal: value.signal,
+    ...(errorCode === undefined ? {} : { error_code: errorCode }),
+    retryable: value.retryable,
+    stderr_tail: bounded.text,
+  };
+}