@relayflows/sdk 2.0.37 → 2.0.39

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/direct-run.ts

@@ -21,7 +21,7 @@ import { authoredInput, authoredWorkerRemedy, localAgentRemedy } from './local-a
 import {
   authoredCompletion,
   authoredHumanParked,
-  authoredStepFailure,
+  authoredStepFailure, rootLeaseLostReport,
   connect,
   emptyReport,
   fromCheckReport,
@@ -212,6 +212,9 @@ export async function runDirectFlow(
     if (error instanceof AuthoredFlowExecutionError && (error.code === 'step_failed' || error.code === 'gate_failed')) {
       return authoredStepFailure('run', base, socketPath, error);
     }
+    if (error instanceof AuthoredFlowExecutionError && error.code === 'root_lease_lost') {
+      return rootLeaseLostReport('run', base, socketPath, error);
+    }
     if (error instanceof AuthoredHumanParked) {
       return authoredHumanParked('run', base, socketPath, error, { dataDir, localAgent: options.localAgent === true });
     }

package/src/cli/pinned-cli-alias.ts

@@ -0,0 +1,74 @@
+import {
+  mkdtempSync,
+  rmSync,
+  symlinkSync,
+} from 'node:fs';
+import {
+  mkdtemp,
+  rm,
+  symlink,
+} from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { basename, join } from 'node:path';
+
+export interface PinnedCliAlias {
+  executable: string;
+  release(): void;
+}
+
+export interface PinnedCliAliasSync {
+  executable: string;
+  release(): void;
+}
+
+function aliasName(identity: string): string {
+  const name = basename(identity);
+  if (name.length === 0 || name === '.' || name === '..') {
+    throw new Error(`Invalid CLI identity basename: ${JSON.stringify(identity)}`);
+  }
+  return name;
+}
+
+/** Execute pinned canonical bytes through the proved basename, including shebang scripts. */
+export async function pinCliAlias(executable: string, identity: string): Promise<PinnedCliAlias> {
+  const name = aliasName(identity);
+  if (basename(executable) === name) {
+    return { executable, release() {} };
+  }
+  const directory = await mkdtemp(join(tmpdir(), 'relayflow-cli-'));
+  const alias = join(directory, name);
+  try {
+    await symlink(executable, alias, 'file');
+  } catch (error) {
+    await rm(directory, { recursive: true, force: true });
+    throw error;
+  }
+  let released = false;
+  return { executable: alias, release: () => {
+    if (released) return;
+    rmSync(directory, { recursive: true, force: true });
+    released = true;
+  } };
+}
+
+/** Synchronous counterpart for the synchronous preflight contract. */
+export function pinCliAliasSync(executable: string, identity: string): PinnedCliAliasSync {
+  const name = aliasName(identity);
+  if (basename(executable) === name) {
+    return { executable, release() {} };
+  }
+  const directory = mkdtempSync(join(tmpdir(), 'relayflow-cli-'));
+  const alias = join(directory, name);
+  try {
+    symlinkSync(executable, alias, 'file');
+  } catch (error) {
+    rmSync(directory, { recursive: true, force: true });
+    throw error;
+  }
+  let released = false;
+  return { executable: alias, release: () => {
+    if (released) return;
+    rmSync(directory, { recursive: true, force: true });
+    released = true;
+  } };
+}

package/src/cli/run.ts

@@ -408,6 +408,9 @@ export async function resumeFlow(
     if (error instanceof AuthoredFlowExecutionError && (error.code === 'step_failed' || error.code === 'gate_failed')) {
       return authoredStepFailure('resume', base, socketPath, error, runId);
     }
+    if (error instanceof AuthoredFlowExecutionError && error.code === 'root_lease_lost') {
+      return rootLeaseLostReport('resume', base, socketPath, error, runId);
+    }
     // An authored resume that parks for want of a worker is a park, reported
     // like the run path's — and with the same remedy, because an authored root
     // admits its worker at run start: resuming again cannot attach one, so the
@@ -522,6 +525,38 @@ function authoredInputArgument(metadata: AuthoredRootMetadata | undefined): Auth
  * drove correctly, and it produces a report with no `status`, which is the
  * whole of what `RUN <id> unknown` ever meant.
  */
+/**
+ * The authored root's lease was lost and not re-dispatched to this process
+ * (authored-root.ts driveRootFollowingRetries). Exit 1 because this CLI did
+ * not finish the run, but the report says what is true of it: still
+ * `running` in the journal, and resumable -- never `protocol_error` with the
+ * generic "worker wait canceled" and no run id, which is what it was.
+ */
+export function rootLeaseLostReport(
+  command: RunCommand,
+  base: CheckReport | RunReport,
+  socketPath: string,
+  error: AuthoredFlowExecutionError,
+  fallbackRunId?: string,
+): RunExecution {
+  const rootRunId = error.rootRunId ?? fallbackRunId;
+  return {
+    exitCode: 1,
+    report: {
+      ...fromBase(command, base),
+      ok: false,
+      ...(rootRunId === undefined ? {} : { runId: rootRunId, rootRunId }),
+      socketPath,
+      status: 'running',
+      diagnostics: [...base.diagnostics, {
+        severity: 'failure',
+        kind: 'root_lease_lost',
+        message: error.message.replace(/^root_lease_lost: /, ''),
+      }],
+    },
+  };
+}
+
 export function authoredStepFailure(
   command: RunCommand,
   base: CheckReport | RunReport,
@@ -798,13 +833,27 @@ export async function classifyOutcome(
   let parkedStep: ParkedStep | undefined;
   let needsHuman = false;
   let unclassifiedPolls = 0;
-  while (current.status === 'parked') {
+  // `running` too: an authored body re-driven after a lost root lease re-admits
+  // its child by admission key and gets the EXISTING run back, mid-attempt.
+  // Only `parked` was followed, so that child -- on the attempt 2 the kernel
+  // retried it to -- fell straight through to "status running without a
+  // classifiable completion" and failed the flow (customer rw_3a0fcb71).
+  while (current.status === 'parked' || current.status === 'running') {
     const inspection = await inspectOutOfBandStep(client, current.run_id);
     // 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)) {
+    // attempt or by a retry in backoff. Keep driving until that active work
+    // settles before declaring a park.
+    if (inspection?.parkedStep !== undefined && (inspection.needsHuman
+      || (inspection.runningStep === undefined && inspection.backoffStep === undefined))) {
       parkedStep = inspection.parkedStep;
       needsHuman = inspection.needsHuman;
+      // `run.get` reports the live snapshot as `running` for an ordinary
+      // runnable worker wait, even when `run.start`/`run.resume` already
+      // classified the outcome as parked. Conversely, a re-admitted run can
+      // arrive here with a stale `running` outcome after its worker vanished.
+      // The step-level inspection is authoritative that this is a park; do
+      // not copy its broader run status and lose that classification.
+      current = { ...current, status: 'parked' };
       break;
     }
     if (inspection?.runningStep !== undefined) {
@@ -812,6 +861,20 @@ export async function classifyOutcome(
       current = await client.runResume(current.run_id, command === 'run' || options.allowHumanInfluenced);
       continue;
     }
+    // A step in `backoff` is between attempts: the kernel has scheduled the
+    // next one (a dead worker's retry is due at once, but waits for the
+    // worker slot the dead attempt held; a failed attempt waits out the
+    // retry policy's delay, bounded by its max_backoff_ms). That is progress,
+    // not an unclassifiable state -- treating it as one gave up after 2s on a
+    // child whose attempt 2 then succeeded (customer rw_3a0fcb71). Once due,
+    // the step is dispatched (`running`, followed above) or, with no worker,
+    // left `runnable` and reported as a park.
+    if (inspection?.backoffStep !== undefined && inspection.runningStep === undefined) {
+      throwIfCanceled(options.signal, inspection.backoffStep.id);
+      await delay(EXPIRED_LEASE_POLL_MS, options.signal);
+      current = await client.runResume(current.run_id, command === 'run' || options.allowHumanInfluenced);
+      continue;
+    }
     if (inspection?.status === 'completed' || inspection?.status === 'failed') {
       current = await client.runResume(current.run_id, command === 'run' || options.allowHumanInfluenced);
       continue;
@@ -954,6 +1017,8 @@ interface OutOfBandInspection {
   parkedStep?: ParkedStep;
   needsHuman: boolean;
   runningStep?: RunningStep;
+  /** A step waiting out a retry backoff: its next attempt is scheduled. */
+  backoffStep?: ParkedStep;
 }
 
 interface RunningStep extends ParkedStep {
@@ -981,6 +1046,9 @@ async function inspectOutOfBandStep(
   const runningEntry = entries.find(([, step]) =>
     step.type !== 'deterministic' && step.state === 'running',
   );
+  const backoffEntry = entries.find(([, step]) =>
+    step.type !== 'deterministic' && step.state === 'backoff',
+  );
   const parkedEntry = humanEntry ?? runnableEntry;
   const parkedStep = parkedEntry === undefined ? undefined : {
     id: parkedEntry[0],
@@ -996,11 +1064,21 @@ async function inspectOutOfBandStep(
     needsHuman: humanEntry !== undefined,
     ...(parkedStep !== undefined ? { parkedStep } : {}),
     ...(runningStep !== undefined ? { runningStep } : {}),
+    ...(backoffEntry !== undefined ? { backoffStep: {
+      id: backoffEntry[0],
+      type: backoffEntry[1].type as Extract<StepType, 'llm' | 'agent'>,
+    } } : {}),
   };
 }
 
 // Match kernel/relayflowd/src/server/client.rs: allow the lease sweep to dispatch a retry.
 export const LEASE_SWEEP_GRACE_MS = 5_000;
+// How often to re-ask the daemon about a step whose lease looks expired here.
+const EXPIRED_LEASE_POLL_MS = 250;
+// A deadline unchanged for a whole lease (relayflowd LEASE_RENEWAL_MS, 30s)
+// plus the sweep grace was renewed by nobody: the attempt is dead and the
+// daemon never swept it. Fail rather than hang.
+const STALE_LEASE_MS = 30_000 + LEASE_SWEEP_GRACE_MS;
 
 async function waitForRunningStep(
   client: JournalClient,
@@ -1018,20 +1096,29 @@ async function waitForRunningStep(
     stepType: runningStep.type,
     leaseDeadlineMs,
   });
+  // When the lease deadline last changed, on this process's monotonic clock.
+  // A live worker renews every ~10s, moving the deadline; a dead lease the
+  // daemon has not swept keeps it. That -- not a comparison of the daemon's
+  // deadline with our wall clock -- is what separates the two under skew.
+  let deadlineSeenAt = performance.now();
   while (true) {
     throwIfCanceled(options.signal, runningStep.id);
     const remainingMs = leaseDeadlineMs + LEASE_SWEEP_GRACE_MS - Date.now();
-    if (remainingMs <= 0) {
+    if (performance.now() - deadlineSeenAt > STALE_LEASE_MS) {
       throw new Error(
         `worker lease for step "${runningStep.id}" expired at ${leaseDeadlineMs} without completion`,
       );
     }
-    await delay(Math.min(50, remainingMs), options.signal);
+    // Past the deadline by THIS clock alone is not an expiry: the daemon may
+    // still hold the lease (skew) or be sweeping it into a retry. Keep
+    // following the step, at a slower poll, until the daemon says otherwise.
+    await delay(remainingMs <= 0 ? EXPIRED_LEASE_POLL_MS : Math.min(50, remainingMs), options.signal);
     const snapshot = await client.runGet(runId);
     const step = snapshot.steps[runningStep.id];
     if (step?.state !== 'running') return;
     if (step.lease_deadline_ms !== undefined && step.lease_deadline_ms !== leaseDeadlineMs) {
       leaseDeadlineMs = step.lease_deadline_ms;
+      deadlineSeenAt = performance.now();
       options.onWait?.({
         runId,
         stepId: runningStep.id,
@@ -1098,7 +1185,14 @@ function errorMessage(error: unknown): string {
 }
 
 function throwIfCanceled(signal: AbortSignal | undefined, stepId: string): void {
-  if (signal?.aborted === true) throw new Error(`waiting for running step "${stepId}" was canceled`);
+  if (signal?.aborted === true) {
+    throw new Error(`waiting for running step "${stepId}" was canceled${cancelCause(signal)}`, { cause: signal.reason });
+  }
+}
+
+/** Why a wait was canceled, when whoever aborted it said (a lost lease does). */
+function cancelCause(signal: AbortSignal): string {
+  return signal.reason instanceof Error && signal.reason.name !== 'AbortError' ? `: ${signal.reason.message}` : '';
 }
 
 export function delay(ms: number, signal?: AbortSignal): Promise<void> {
@@ -1112,7 +1206,9 @@ export function delay(ms: number, signal?: AbortSignal): Promise<void> {
     const cancel = (): void => {
       clearTimeout(timer);
       signal.removeEventListener('abort', cancel);
-      rejectDelay(new Error('worker wait canceled'));
+      // Carries the abort reason: a bare "worker wait canceled" was all a
+      // lost root lease ever reported (customer rw_3a0fcb71).
+      rejectDelay(new Error(`worker wait canceled${cancelCause(signal)}`, { cause: signal.reason }));
     };
     if (signal.aborted) cancel();
     else signal.addEventListener('abort', cancel, { once: true });

package/src/cli/step-failure.ts

@@ -63,6 +63,8 @@ export async function stepFailureDetails(
   // 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>();
+  // Attempts the kernel itself declared dead (see `unchargedAttempts`).
+  const uncharged = new Map<string, number>();
   while (true) {
     const { entries } = await client.journalRead(runId, fromSeq, 100);
     if (entries.length === 0) break;
@@ -93,6 +95,7 @@ export async function stepFailureDetails(
       // holds every entry; only this diagnostic's candidate is cleared.
       if (payload === undefined || typeof completionReason !== 'string' || completionReason === 'success') {
         histories.delete(stepId);
+        uncharged.delete(stepId);
         continue;
       }
       const history = histories.get(stepId) ?? { records: [], causes: [] };
@@ -101,6 +104,10 @@ export async function stepFailureDetails(
       history.records.push(attemptFailure(entry['attempt'], completionReason, payload['disposition'], payload));
       history.causes.push(failureCause(completionReason, payload));
       histories.set(stepId, history);
+      if (payload['disposition'] !== 'step_done' && payload['completed_by'] === 'kernel'
+        && (completionReason === 'crashed' || completionReason === 'lease_expired')) {
+        uncharged.set(stepId, (uncharged.get(stepId) ?? 0) + 1);
+      }
       // A terminal completion that is not a success is the failure, whatever
       // its step type. The old predicate also demanded a non-zero `exit_code`,
       // which no agent completion carries and which a deterministic step that
@@ -116,6 +123,7 @@ export async function stepFailureDetails(
         ...(stepType === undefined ? {} : { stepType }),
         ...(typeof attempt === 'number' && Number.isSafeInteger(attempt) && attempt > 0 ? { attempt } : {}),
         ...(maxIterations === undefined ? {} : { maxIterations }),
+        ...((uncharged.get(stepId) ?? 0) > 0 ? { unchargedAttempts: uncharged.get(stepId) } : {}),
         ...terminalEvidence(payload),
         // A single failed attempt is already fully described by the scalars
         // above; repeating it as a one-element history would add a clause to
@@ -169,6 +177,16 @@ export function renderStepEvidence(details: StepFailedDetails): string {
 
 function renderAttempt(details: StepFailedDetails): string {
   if (details.attempt === undefined) return '';
+  const uncharged = details.unchargedAttempts ?? 0;
+  // `attempt=N/M` compares like with like only when every attempt was charged.
+  // A worker that died (crashed / lease_expired) costs no iteration, so a
+  // one-iteration step can legitimately run attempt 2 -- printed as
+  // `attempt=2/1` it read as the budget being overrun. Say which is which.
+  if (uncharged > 0 && uncharged < details.attempt) {
+    return ` attempt=${details.attempt}`
+      + ` (iteration ${details.attempt - uncharged}${details.maxIterations === undefined ? '' : `/${details.maxIterations}`};`
+      + ` ${uncharged} earlier attempt${uncharged === 1 ? '' : 's'} lost to a dead worker, not charged)`;
+  }
   return ` attempt=${details.attempt}`
     + (details.maxIterations === undefined ? '' : `/${details.maxIterations}`);
 }

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.ts

@@ -44,6 +44,7 @@ import { checkTypeScriptFlow } from './cli/check-typescript.js';
 import { runCloudCli } from './cli/cloud-run.js';
 import { runCloudSyncCli } from './cli/cloud-sync.js';
 import { parseCloudDeployArgs, runCloudDeployCli, runCloudDeploymentsCli, runCloudUndeployCli, type CloudDeployArgs } from './cli/cloud-deploy.js';
+import { runCloudRollbackCli, runCloudVersionsCli } from './cli/cloud-versions.js';
 import { parseCloudScheduleArgs, runCloudScheduleCli, runCloudSchedulesCli, runCloudUnscheduleCli, type CloudScheduleArgs } from './cli/cloud-schedule.js';
 import { isAuthoredFlowPath } from './direct-input.js';
 import { parseDeployArgs, runDeploy, type DeployArgs } from './cli/deploy.js';
@@ -97,6 +98,8 @@ export type ParsedArgs =
   | CloudDeployArgs
   | { command: 'deployments'; json: boolean }
   | { command: 'undeploy'; agentId: string; json: boolean }
+  | { command: 'versions'; flow: string; json: boolean }
+  | { command: 'rollback'; flow: string; version: string; json: boolean }
   | CloudScheduleArgs
   | { command: 'schedules'; json: boolean }
   | { command: 'unschedule'; scheduleId: string; json: boolean }
@@ -123,7 +126,10 @@ const USAGE = [
   'flows build [--out <dir>] <flow.yaml|flow.ts>',
   'flows build --verify <bundle-dir>',
   'flows deploy <flow.ts> --repo <owner/name> --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]',
+  'flows versions [--json] <name|listener-id>',
+  'flows rollback [--json] <name|listener-id> <version>',
   'flows undeploy [--json] <deployment-id>',
   'flows schedule <flow.yaml|flow.ts> [--cron "<expr>" | --every <n><s|m|h|d>] [--tz <IANA>] [--input <inline-json-or-file>] [--name <name>] [--no-connect] [--json]',
   'flows schedules [--json]',
@@ -244,6 +250,8 @@ export async function runCli(
   if (parsed.command === 'cloud-deploy') return runCloudDeployCli(parsed, io);
   if (parsed.command === 'deployments') return runCloudDeploymentsCli(parsed, io);
   if (parsed.command === 'undeploy') return runCloudUndeployCli(parsed, io);
+  if (parsed.command === 'versions') return runCloudVersionsCli(parsed, io);
+  if (parsed.command === 'rollback') return runCloudRollbackCli(parsed, io);
   if (parsed.command === 'schedule') return runCloudScheduleCli(parsed, io);
   if (parsed.command === 'schedules') return runCloudSchedulesCli(parsed, io);
   if (parsed.command === 'unschedule') return runCloudUnscheduleCli(parsed, io);
@@ -631,6 +639,13 @@ function parseArgs(args: readonly string[]): ParsedArgs | undefined {
     if (json > 1 || rest.length !== 1 || rest[0]!.startsWith('-')) return undefined;
     return { command: 'undeploy', agentId: rest[0]!, json: json === 1 };
   }
+  if (command === 'versions' || command === 'rollback') {
+    const rest = args.slice(1).filter(a => a !== '--json');
+    const json = args.length - 1 - rest.length;
+    if (json > 1 || rest.some(a => a.startsWith('-'))) return undefined;
+    if (command === 'versions') return rest.length === 1 ? { command, flow: rest[0]!, json: json === 1 } : undefined;
+    return rest.length === 2 ? { command, flow: rest[0]!, version: rest[1]!, json: json === 1 } : undefined;
+  }
   if (command === 'deployments') {
     const rest = args.slice(1);
     if (rest.length > 1 || (rest.length === 1 && rest[0] !== '--json')) return undefined;