@relayflows/sdk 2.0.30 → 2.0.32

package/src/cli/step-evidence.ts

@@ -0,0 +1,310 @@
+import { redact } from '../redact.js';
+import { formatStepExcerpt } from './step-excerpt.js';
+import type {
+  AttemptEvidenceComparison,
+  StepAttemptFailure,
+  StepFailedDetails,
+} from '../failure-kinds.js';
+
+/** Per-attempt history is context beside that account, not a second copy of it. */
+export const ATTEMPT_TAIL_BYTES = 256;
+
+/**
+ * What the daemon appends when it cut a render before journaling it
+ * (`worker_failure_detail`, relayflowd/src/engine/remote.rs). Evidence that
+ * arrived already truncated cannot establish that two attempts failed
+ * identically, however equal the surviving bytes are.
+ */
+const PRODUCER_TRUNCATED = /…\s*\((?:render bounded|[\d,]+ bytes truncated)\)$/u;
+
+/**
+ * The evidence fields a step failure reports, as the journal held them.
+ *
+ * Extraction and display bounds are separated deliberately. The terminal
+ * attempt renders at 1,024 bytes and each historical attempt at 256, but the
+ * COMPARISON that decides whether a retry failed differently runs on the
+ * unbounded record (`failureCause`): two different errors can share a 256-byte
+ * suffix, and calling those the same failure is the bug this reader exists to
+ * avoid.
+ */
+export interface SelectedEvidence {
+  exitCode?: number;
+  /** Present only when nonempty. */
+  stdoutTail?: string;
+  /** Present whenever the journal carried one, including the empty string. */
+  stderrTail?: string;
+  detail?: string;
+  transcriptPath?: string;
+}
+
+/**
+ * Pull the process-shaped fields out of whichever field carried them.
+ *
+ * `verification.detail` is last because it is the daemon's own render rather
+ * than the worker's structured report — but for an agent step it is the only
+ * thing that survives, so it is parsed when it parses and kept verbatim when
+ * it does not. A truncated render (the daemon caps at 2,000 chars and appends
+ * a truncation note) will not parse; that falls through to the raw string,
+ * which is still the account of what went wrong.
+ *
+ * An agent or llm completion now also carries `trajectory_tail.transcript`
+ * (agent-transcript.ts) on every attempt. That object is not process-shaped,
+ * so it must not shadow the render that is: the first candidate that carries
+ * an exit code or a tail wins. The digest contributes what only it has — the
+ * failure excerpt the worker picked out of the provider's frames, and the
+ * path of the transcript file.
+ */
+export function selectEvidence(payload: Record<string, unknown>): SelectedEvidence {
+  const detail = record(payload['verification'])?.['detail'];
+  const rendered = typeof detail === 'string' ? parsed(detail) : undefined;
+  const candidates = [
+    record(payload['output']),
+    record(payload['trajectory_tail']),
+    rendered,
+  ].filter((candidate): candidate is Record<string, unknown> => candidate !== undefined);
+  const structured = candidates.find(processShaped) ?? candidates[0];
+  const exitCode = structured?.['exit_code'];
+  const stdout = structured?.['stdout_tail'];
+  const stderr = structured?.['stderr_tail'];
+  const transcript = record(record(payload['trajectory_tail'])?.['transcript']);
+  const failure = record(transcript?.['failure']);
+  const excerpt = failure?.['excerpt'];
+  const transcriptPath = record(transcript?.['file'])?.['path'];
+  // The excerpt is the worker's own pick of the failure; a `stderr` excerpt
+  // is the same bytes as `stderrTail`, so it is not printed twice.
+  const excerptDetail = typeof excerpt === 'string' && excerpt.length > 0
+    && !(failure?.['kind'] === 'stderr' && typeof stderr === 'string')
+    ? excerpt : undefined;
+  return {
+    ...(typeof exitCode === 'number' && Number.isSafeInteger(exitCode) ? { exitCode } : {}),
+    ...(typeof stdout === 'string' && stdout.length > 0 ? { stdoutTail: stdout } : {}),
+    ...(typeof stderr === 'string' ? { stderrTail: stderr } : {}),
+    ...(excerptDetail !== undefined ? { detail: excerptDetail }
+      : typeof detail === 'string' && detail.length > 0 && !duplicates(detail, rendered, exitCode)
+        ? { detail } : {}),
+    ...(typeof transcriptPath === 'string' && transcriptPath.length > 0 ? { transcriptPath } : {}),
+  };
+}
+
+/**
+ * Whether printing `verification.detail` would print bytes already printed.
+ *
+ * Only two shapes do. The daemon's render of a worker failure IS the
+ * `{exit_code, stdout_tail, stderr_tail}` report (`worker_failure_detail`,
+ * relayflowd/src/engine/remote.rs), which a deterministic step journals
+ * alongside its preserved `output`; and the `exit_code` gate's verdict on its
+ * own is the exit code that is already reported beside it (`exit code was 1`,
+ * relayflowd-core/src/verify.rs).
+ *
+ * Every other verdict is the ONLY account of its failure. `output did not
+ * contain "READY"` accompanies exit 0 and empty tails, so suppressing the
+ * detail whenever some field happened to be process-shaped left the attempt
+ * saying `exit=0 — no failure evidence recorded` while the journal held the
+ * gate error — the first attempt hidden again, inside the diagnostic that
+ * exists to surface it.
+ */
+function duplicates(
+  detail: string,
+  rendered: Record<string, unknown> | undefined,
+  exitCode: unknown,
+): boolean {
+  if (rendered !== undefined && processShaped(rendered)) return true;
+  return typeof exitCode === 'number' && detail === `exit code was ${exitCode}`;
+}
+
+/** The `StepFailedDetails` scalars for one completion, as a failure excerpt. */
+export function terminalEvidence(payload: Record<string, unknown>): Partial<StepFailedDetails> {
+  const selected = selectEvidence(payload);
+  return {
+    ...(selected.exitCode === undefined ? {} : { exitCode: selected.exitCode }),
+    ...(selected.stdoutTail === undefined ? {} : { stdoutTail: formatStepExcerpt(selected.stdoutTail) }),
+    ...(selected.stderrTail === undefined ? {} : { stderrTail: formatStepExcerpt(selected.stderrTail) }),
+    ...(selected.detail === undefined ? {} : { detail: formatStepExcerpt(selected.detail) }),
+    ...(selected.transcriptPath === undefined ? {} : { transcriptPath: selected.transcriptPath }),
+  };
+}
+
+/**
+ * One historical attempt's record, redacted and then bounded.
+ *
+ * Redaction runs first so a credential cannot survive by sitting outside the
+ * excerpt window on one attempt and inside it on another. Control-character
+ * replacement alone is not redaction: an agent that echoed `rk_live_...` into
+ * its stderr would otherwise reach a terminal through this new field.
+ */
+export function attemptFailure(
+  attempt: unknown,
+  completionReason: string,
+  disposition: unknown,
+  payload: Record<string, unknown>,
+): StepAttemptFailure {
+  const selected = selectEvidence(payload);
+  let truncated = false;
+  const bound = (value: string): string => {
+    const redacted = redact(value);
+    if (Buffer.byteLength(redacted, 'utf8') > ATTEMPT_TAIL_BYTES) truncated = true;
+    return tail(redacted, ATTEMPT_TAIL_BYTES);
+  };
+  const record_: StepAttemptFailure = {
+    ...(typeof attempt === 'number' && Number.isSafeInteger(attempt) && attempt > 0
+      ? { attempt } : {}),
+    completionReason,
+    ...(typeof disposition === 'string' && disposition.length > 0 ? { disposition } : {}),
+    ...(selected.exitCode === undefined ? {} : { exitCode: selected.exitCode }),
+    ...(selected.stdoutTail === undefined ? {} : { stdoutTail: bound(selected.stdoutTail) }),
+    ...(selected.stderrTail === undefined ? {} : { stderrTail: bound(selected.stderrTail) }),
+    ...(selected.detail === undefined ? {} : { detail: bound(selected.detail) }),
+  };
+  return truncated ? { ...record_, truncated } : record_;
+}
+
+/**
+ * Everything about a completion that bears on WHY it failed, unbounded.
+ *
+ * Deliberately not the display selection: `selectEvidence` suppresses the
+ * daemon's render when process-shaped output exists, and prefers a transcript
+ * excerpt over both, so two attempts can show identical excerpts over
+ * different gate verdicts. Everything the journal recorded about the failure
+ * is read here instead, before any bound is applied.
+ *
+ * Timestamps, transcript paths, dispositions and attempt numbers are NOT
+ * causes and are excluded: they differ on every attempt by construction.
+ */
+export function failureCause(
+  completionReason: string,
+  payload: Record<string, unknown>,
+): AttemptCause {
+  const verification = record(payload['verification']);
+  const output = record(payload['output']);
+  const trajectory = record(payload['trajectory_tail']);
+  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(failure?.['excerpt']),
+  ];
+  const exitCodes = [output?.['exit_code'], trajectory?.['exit_code']]
+    .filter(value => typeof value === 'number');
+  return {
+    key: JSON.stringify([
+      // `verification_failed` on a retry and `retries_exhausted` at the budget
+      // limit are the SAME fallback over the same failure: `completion_actions`
+      // picks the label from the branch it took, not from the cause. Comparing
+      // them literally would report "the retry failed differently" on every
+      // ordinary repeated failure. No other pair of labels is collapsed.
+      completionReason === 'verification_failed' || completionReason === 'retries_exhausted'
+        ? 'kernel_rejected' : completionReason,
+      text(verification?.['gate']), text(verification?.['verdict']), verificationDetail,
+      ...exitCodes, ...accounts, 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))
+      // The transcript digest's own flag (`boundTranscriptDigest`,
+      // agent-transcript.ts): the worker already cut this excerpt, so equal
+      // survivors cannot establish identical failures either.
+      || failure?.['truncated'] === true,
+  };
+}
+
+export interface AttemptCause {
+  readonly key: string;
+  readonly recorded: boolean;
+  readonly producerTruncated: boolean;
+}
+
+/**
+ * Only attempts that recorded something can establish a difference.
+ *
+ * An attempt that journaled no account of itself differs from every other one
+ * on paper while saying nothing about why it failed, and reporting that as
+ * `differs` would put "an earlier attempt may have had side effects" on a
+ * crash that is evidence of nothing. Truncation is not the same case: two
+ * renders the daemon already cut can only look MORE alike than they were, so
+ * surviving bytes that disagree still prove the causes disagreed.
+ */
+export function compareAttempts(causes: readonly AttemptCause[]): AttemptEvidenceComparison {
+  const recorded = causes.filter(cause => cause.recorded);
+  if (new Set(recorded.map(cause => cause.key)).size > 1) return 'differs';
+  return recorded.length === causes.length && causes.every(cause => !cause.producerTruncated)
+    ? 'unchanged' : 'unknown';
+}
+
+const COMPARISON_CLAUSE: Record<AttemptEvidenceComparison, string> = {
+  differs: 'recorded failure evidence differs. An earlier attempt may have had side effects.',
+  unchanged: 'recorded failure evidence is unchanged across them.',
+  unknown: 'recorded failure evidence is incomplete, so whether the causes differ is unknown.',
+};
+
+/**
+ * Every failed attempt, oldest first, under one line saying whether they
+ * agree. Rendered in full rather than elided: `flows logs` prints the runner
+ * log without eliding it, so an attempt dropped here is an attempt that
+ * reaches no reader at all.
+ */
+export function renderAttemptHistory(details: StepFailedDetails): string {
+  const attempts = details.attempts;
+  if (attempts === undefined || attempts.length < 2) return '';
+  const comparison = COMPARISON_CLAUSE[details.attemptEvidence ?? 'unknown'];
+  return [`\nAttempts: ${attempts.length} failed; ${comparison}`, ...attempts.map(renderAttempt)]
+    .join('\n');
+}
+
+function renderAttempt(attempt: StepAttemptFailure): string {
+  const head = `  attempt ${attempt.attempt ?? '?'}: ${attempt.completionReason ?? 'unknown'}`
+    + (attempt.exitCode === undefined ? '' : ` exit=${attempt.exitCode}`)
+    + (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`
+  // would. Both are kept when both exist.
+  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`;
+  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');
+}
+
+/** Continuation lines are indented past the label so the list stays readable. */
+function indent(block: string): string {
+  const [first, ...rest] = block.split('\n');
+  return [`    ${first}`, ...rest.map(line => `      ${line}`)].join('\n');
+}
+
+function text(value: unknown): string | undefined {
+  return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+
+function processShaped(value: Record<string, unknown>): boolean {
+  return typeof value['exit_code'] === 'number'
+    || typeof value['stdout_tail'] === 'string' || typeof value['stderr_tail'] === 'string';
+}
+
+function parsed(value: string): Record<string, unknown> | undefined {
+  try {
+    return record(JSON.parse(value));
+  } catch {
+    return undefined;
+  }
+}
+
+export function record(value: unknown): Record<string, unknown> | undefined {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+    ? value as Record<string, unknown> : undefined;
+}
+
+export function tail(value: string, limit: number): string {
+  const bytes = Buffer.from(value, 'utf8');
+  let start = Math.max(0, bytes.length - limit);
+  // Drop a partial leading code point, avoiding replacement-byte expansion.
+  while (start < bytes.length && (bytes[start]! & 0xc0) === 0x80) start += 1;
+  // Preserve tabs/newlines; replace binary controls (including ESC and CR),
+  // C1 controls and Unicode formatting controls without growing the excerpt.
+  return bytes.subarray(start).toString('utf8')
+    .replace(/[\p{Cc}\p{Cf}]/gu, character => character === '\n' || character === '\t' ? character : '?');
+}

package/src/cli/step-failure.ts

@@ -1,8 +1,22 @@
 import { join } from 'node:path';
 import { DEFAULT_DATA_DIR } from '../daemon-connection.js';
-import type { StepFailedDetails } from '../failure-kinds.js';
+import type { StepAttemptFailure, StepFailedDetails } from '../failure-kinds.js';
 import type { JournalClient } from '../journal-client.js';
-import { formatStepExcerpt } from './step-excerpt.js';
+import {
+  attemptFailure,
+  compareAttempts,
+  failureCause,
+  record,
+  renderAttemptHistory,
+  terminalEvidence,
+  type AttemptCause,
+} from './step-evidence.js';
+
+/** Every failed attempt of one step, in journal order, with its causes. */
+interface AttemptHistory {
+  records: StepAttemptFailure[];
+  causes: AttemptCause[];
+}
 
 /**
  * Read what a failed step left in the journal — for any step type.
@@ -21,10 +35,16 @@ import { formatStepExcerpt } from './step-excerpt.js';
  * agent or llm step the worker's `{exit_code, stdout_tail, stderr_tail}` is
  * nulled out of `output` and survives only as the bounded render the daemon
  * captured into `verification.detail` (`worker_failure_detail`,
- * relayflowd/src/engine/remote.rs). Both are read, in that order, and the
- * daemon's render is re-parsed when it carries that same shape: an exit code
- * the daemon stringified on its way into the journal is still an exit code,
- * and printing it as one is the difference between a diagnosis and a blob.
+ * relayflowd/src/engine/remote.rs). Both are read by `selectEvidence`, in that
+ * order, and the daemon's render is re-parsed when it carries that same shape.
+ *
+ * EVERY failed attempt is collected, not only the terminal one. The kernel
+ * appends a `step.completed` per attempt, so a retried step's first failure is
+ * in the journal — but `retries_exhausted` reported only the last attempt, and
+ * a retry that fails differently (because the first attempt already had a side
+ * effect) is exactly when the last attempt is the least informative record
+ * there is. The scalar fields still describe the terminal attempt; `attempts`
+ * is additive.
  */
 export async function stepFailureDetails(
   client: JournalClient,
@@ -40,6 +60,9 @@ 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>();
+  // 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>();
   while (true) {
     const { entries } = await client.journalRead(runId, fromSeq, 100);
     if (entries.length === 0) break;
@@ -63,15 +86,27 @@ export async function stepFailureDetails(
       // A later completion supersedes an earlier failed attempt.
       failures.delete(stepId);
       const payload = record(entry['payload']);
-      if (payload === undefined) continue;
-      const completionReason = payload['completionReason'];
+      const completionReason = payload?.['completionReason'];
+      // A success — or a completion this reader cannot read — ends the failure
+      // history too: what a step that eventually succeeded printed on the way
+      // is not the diagnosis of a later, different failure. The journal still
+      // holds every entry; only this diagnostic's candidate is cleared.
+      if (payload === undefined || typeof completionReason !== 'string' || completionReason === 'success') {
+        histories.delete(stepId);
+        continue;
+      }
+      const history = histories.get(stepId) ?? { records: [], causes: [] };
+      // Recorded for `retry` and `park` alike: the kernel's disposition says
+      // what it did next, not whether the attempt failed.
+      history.records.push(attemptFailure(entry['attempt'], completionReason, payload['disposition'], payload));
+      history.causes.push(failureCause(completionReason, payload));
+      histories.set(stepId, history);
       // 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
       // exits 0 and then fails its gate does not carry either — both were
       // silently skipped.
-      if (payload['disposition'] !== 'step_done'
-        || typeof completionReason !== 'string' || completionReason === 'success') continue;
+      if (payload['disposition'] !== 'step_done') continue;
       const stepType = snapshot.steps[stepId]?.type;
       const attempt = entry['attempt'];
       const maxIterations = budgets.get(stepId);
@@ -81,7 +116,13 @@ export async function stepFailureDetails(
         ...(stepType === undefined ? {} : { stepType }),
         ...(typeof attempt === 'number' && Number.isSafeInteger(attempt) && attempt > 0 ? { attempt } : {}),
         ...(maxIterations === undefined ? {} : { maxIterations }),
-        ...evidence(payload),
+        ...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
+        // every ordinary failure report without adding a fact.
+        ...(history.records.length > 1
+          ? { attempts: history.records, attemptEvidence: compareAttempts(history.causes) }
+          : {}),
       });
     }
   }
@@ -104,6 +145,10 @@ export async function stepFailureDetails(
  * stops it being misread. Unknown values are omitted rather than defaulted —
  * an absent budget must not be reported as one attempt.
  *
+ * The attempt history follows that line and precedes the terminal attempt's
+ * own clauses, so the first error is visible without scrolling past the last
+ * one's output tails.
+ *
  * 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).
@@ -115,6 +160,7 @@ export function renderStepEvidence(details: StepFailedDetails): string {
     + renderAttempt(details)
     + (details.exitCode === undefined ? '' : ` exit=${details.exitCode}`)
     + '.'
+    + renderAttemptHistory(details)
     + (details.detail === undefined ? '' : `\nDetail: ${details.detail}`)
     + (details.stdoutTail ? `\nStdout (captured excerpt):\n${details.stdoutTail}` : '')
     + (details.stderrTail ? `\nStderr (captured excerpt):\n${details.stderrTail}` : '')
@@ -163,76 +209,6 @@ export function inspectionHint(
   };
 }
 
-/**
- * Pull the process-shaped fields out of whichever field carried them.
- *
- * `verification.detail` is last because it is the daemon's own render rather
- * than the worker's structured report — but for an agent step it is the only
- * thing that survives, so it is parsed when it parses and kept verbatim when
- * it does not. A truncated render (the daemon caps at 2,000 chars and appends
- * a truncation note) will not parse; that falls through to the raw string,
- * which is still the account of what went wrong.
- *
- * An agent or llm completion now also carries `trajectory_tail.transcript`
- * (agent-transcript.ts) on every attempt. That object is not process-shaped,
- * so it must not shadow the render that is: the first candidate that carries
- * an exit code or a tail wins. The digest contributes what only it has — the
- * failure excerpt the worker picked out of the provider's frames, and the
- * path of the transcript file.
- */
-function evidence(payload: Record<string, unknown>): Partial<StepFailedDetails> {
-  const detail = record(payload['verification'])?.['detail'];
-  const candidates = [
-    record(payload['output']),
-    record(payload['trajectory_tail']),
-    typeof detail === 'string' ? parsed(detail) : undefined,
-  ].filter((candidate): candidate is Record<string, unknown> => candidate !== undefined);
-  const structured = candidates.find(processShaped) ?? candidates[0];
-  const exitCode = structured?.['exit_code'];
-  const stdout = structured?.['stdout_tail'];
-  const stderr = structured?.['stderr_tail'];
-  const structuredShape = structured !== undefined && processShaped(structured);
-  const transcript = record(record(payload['trajectory_tail'])?.['transcript']);
-  const failure = record(transcript?.['failure']);
-  const failureExcerpt = failure?.['excerpt'];
-  const transcriptPath = record(transcript?.['file'])?.['path'];
-  // The excerpt is the worker's own pick of the failure; a `stderr` excerpt
-  // is the same bytes as `stderrTail`, so it is not printed twice.
-  const excerptDetail = typeof failureExcerpt === 'string' && failureExcerpt.length > 0
-    && !(failure?.['kind'] === 'stderr' && typeof stderr === 'string')
-    ? formatStepExcerpt(failureExcerpt) : undefined;
-  return {
-    ...(typeof exitCode === 'number' && Number.isSafeInteger(exitCode) ? { exitCode } : {}),
-    ...(typeof stdout === 'string' && stdout.length > 0 ? { stdoutTail: formatStepExcerpt(stdout) } : {}),
-    ...(typeof stderr === 'string' ? { stderrTail: formatStepExcerpt(stderr) } : {}),
-    // Keep the daemon's account only when it was NOT just a render of the
-    // fields above — otherwise the same bytes print twice.
-    ...(excerptDetail !== undefined ? { detail: excerptDetail }
-      : typeof detail === 'string' && detail.length > 0 && !structuredShape
-        ? { detail: formatStepExcerpt(detail) } : {}),
-    ...(typeof transcriptPath === 'string' && transcriptPath.length > 0 ? { transcriptPath } : {}),
-  };
-}
-
-function processShaped(value: Record<string, unknown>): boolean {
-  return typeof value['exit_code'] === 'number'
-    || typeof value['stdout_tail'] === 'string' || typeof value['stderr_tail'] === 'string';
-}
-
-function parsed(value: string): Record<string, unknown> | undefined {
-  try {
-    return record(JSON.parse(value));
-  } catch {
-    return undefined;
-  }
-}
-
-function record(value: unknown): Record<string, unknown> | undefined {
-  return value !== null && typeof value === 'object' && !Array.isArray(value)
-    ? value as Record<string, unknown> : undefined;
-}
-
-
 function shellQuote(value: string): string {
   return /^[A-Za-z0-9_-]+$/.test(value) && !value.startsWith('-')
     ? value : `'${value.replace(/'/g, "'\\''")}'`;

package/src/cli-commands.ts

@@ -96,6 +96,7 @@ const LOCAL_EXECUTION_OPTIONS = [
   },
   { flags: '--no-spawn', description: 'Require a running relayflowd rather than starting one' },
   { flags: '--no-observer-link', description: 'Do not mint an observer link for this run' },
+  { flags: '--cloud-mirror', description: 'Also put this run on the Cloud dashboard (also FLOWS_CLOUD_MIRROR=1)' },
   {
     flags: '--allow-human-influenced',
     description: 'Proceed even though the run carries human-influenced state',
@@ -196,6 +197,7 @@ export const CLI_VERBS = [
     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)' },
+      { flags: '--follow', description: 'Append new runner output until the run ends; exits with the run’s outcome' },
       JSON_OPTION,
     ],
     variants: ['logs'],
@@ -331,6 +333,7 @@ export const CLI_VERBS = [
       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' },
+      { flags: '--watch', description: 'With --cloud: redraw until the run ends, then exit with its outcome' },
     ],
     variants: ['status'],
   },