@relayflows/sdk 2.0.21 → 2.0.23

package/src/cli/run.ts

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

package/src/cli/status.ts

@@ -0,0 +1,349 @@
+// `flows status`: what an agent can see about its own run, from disk.
+//
+// Read-only and offline. Opens exactly one file — the run's journal, through
+// the same copy-then-verify `walkJournal` that `flows replay` uses — and never
+// the registry, `connection.json`, the daemon socket or the network. There is
+// no credential to hold because nothing here is authenticated: the journal is
+// on the same filesystem as the process asking. Everything a hosted run knows
+// about itself is in that file; whatever is not (its Cloud run id, its
+// sandbox, its listener) is Cloud's to answer, and this verb does not guess.
+
+import type { CliIo } from '../cli.js';
+import { canonicalize } from '../canonical.js';
+import { DEFAULT_DATA_DIR } from '../daemon-connection.js';
+import { JournalReadError, walkJournal, type JournalEvent } from '../journal-client.js';
+import { redact } from '../redact.js';
+import { foldRunState, RunStateError, type RunView, type StepView } from '../run-state.js';
+import { DATA_DIR_ENV, RUN_ID_ENV, STEP_ID_ENV } from '../step-env.js';
+
+export interface StatusArgs {
+  command: 'status';
+  json: boolean;
+  dataDir?: string;
+  tail?: number;
+  runId?: string;
+  /**
+   * `--cloud`: read the run from the Cloud API instead of a local journal.
+   *
+   * Parsed here because the verb is one verb — a reader should not have to
+   * know that a hosted run is a different command — but never *handled* here:
+   * `runCli` routes a `--cloud` invocation to `cli/cloud-read.ts`, so this
+   * module keeps its property of opening one file and no socket.
+   */
+  cloud?: true;
+}
+
+export const DEFAULT_TAIL_LINES = 20;
+/** A gate's `detail` may be 2,000 chars (engine/remote.rs); the view shows the head. */
+const DETAIL_LIMIT = 1024;
+const BUSY_RETRIES = 5;
+const BUSY_RETRY_DELAY_MS = 50;
+
+/** One transcript tail on disk, already redacted, as `--tail` renders it. */
+export interface TranscriptTail {
+  attempt: number;
+  bytes: number;
+  lines: string[];
+}
+
+export type StepTails = { stdout: TranscriptTail | null; stderr: TranscriptTail | null } | null;
+
+/** How the verb finds transcript tails; `null` until the tail writer ships. */
+export interface TailSource {
+  read(dataDir: string, runId: string, step: StepView, lines: number): Promise<StepTails>;
+}
+
+export interface StatusOptions {
+  env?: NodeJS.ProcessEnv;
+  now?: () => number;
+  tails?: TailSource;
+  sleep?: (ms: number) => Promise<void>;
+}
+
+export function parseStatusArgs(args: readonly string[]): StatusArgs | undefined {
+  let json = false;
+  let cloud = false;
+  let dataDir: string | undefined;
+  let tail: number | undefined;
+  const positionals: string[] = [];
+  for (let index = 0; index < args.length; index += 1) {
+    const argument = args[index]!;
+    if (argument === '--json') {
+      if (json) return undefined;
+      json = true;
+    } else if (argument === '--cloud') {
+      if (cloud) return undefined;
+      cloud = true;
+    } else if (argument === '--data-dir' || argument === '--tail') {
+      const value = args[++index];
+      if (value === undefined || value.length === 0 || value.startsWith('-')) return undefined;
+      if (argument === '--data-dir') {
+        if (dataDir !== undefined) return undefined;
+        dataDir = value;
+      } else {
+        if (tail !== undefined || !/^\d{1,4}$/.test(value)) return undefined;
+        tail = Number(value);
+      }
+    } else if (argument.startsWith('-')) {
+      return undefined;
+    } else {
+      positionals.push(argument);
+    }
+  }
+  if (positionals.length > 1) return undefined;
+  // `--data-dir` and `--tail` name things on this filesystem: a data directory
+  // to read a journal out of, and per-attempt tail files beside it. A hosted
+  // run has neither, so pairing them with `--cloud` is not a narrower request
+  // but a contradiction, and is refused as an invocation rather than silently
+  // ignored. A hosted run id is mandatory: there is no ambient one.
+  if (cloud && (dataDir !== undefined || tail !== undefined || positionals.length === 0)) return undefined;
+  return {
+    command: 'status', json,
+    ...(cloud ? { cloud: true as const } : {}),
+    ...(dataDir === undefined ? {} : { dataDir }),
+    ...(tail === undefined ? {} : { tail }),
+    ...(positionals[0] === undefined ? {} : { runId: positionals[0] }),
+  };
+}
+
+interface Snapshot {
+  events: JournalEvent[];
+  partial: string[];
+  failure?: JournalReadError;
+}
+
+/**
+ * Take one consistent snapshot of the journal. `journal_busy` means a writer
+ * was mid-flight, so wait briefly and try again; any other mid-walk failure
+ * keeps the events read so far and reports the section as partial.
+ */
+async function snapshot(runId: string, dataDir: string, sleep: (ms: number) => Promise<void>): Promise<Snapshot> {
+  for (let attempt = 1; ; attempt += 1) {
+    const events: JournalEvent[] = [];
+    try {
+      for await (const event of walkJournal(runId, dataDir)) events.push(event);
+      return { events, partial: [] };
+    } catch (error) {
+      const failure = error instanceof JournalReadError ? error
+        : new JournalReadError('journal_read_failed', error instanceof Error ? error.message : String(error));
+      if (failure.code === 'journal_busy' && attempt < BUSY_RETRIES) { await sleep(BUSY_RETRY_DELAY_MS); continue; }
+      return { events, partial: [failure.code], failure };
+    }
+  }
+}
+
+export async function runStatus(args: StatusArgs, io: CliIo, options: StatusOptions = {}): Promise<0 | 1 | 2> {
+  const env = options.env ?? process.env;
+  const now = options.now ?? Date.now;
+  const sleep = options.sleep ?? ((ms) => new Promise<void>((resolve) => setTimeout(resolve, ms)));
+  // Discovery: an explicit run id wins; otherwise the step's own identity from
+  // the environment the worker set. A shared data dir holds other people's
+  // runs, so there is no "list everything" mode to fall back to.
+  const runId = args.runId ?? env[RUN_ID_ENV];
+  if (runId === undefined || runId.length === 0) {
+    io.stderr(`REFUSED [run_unknown] pass <run-id> or run inside a step (${RUN_ID_ENV} unset)`);
+    return 2;
+  }
+  const dataDir = args.dataDir ?? env[DATA_DIR_ENV] ?? DEFAULT_DATA_DIR;
+  const thisStep = args.runId === undefined ? env[STEP_ID_ENV] ?? null : null;
+
+  const taken = await snapshot(runId, dataDir, sleep);
+  if (taken.events.length === 0) {
+    const failure = taken.failure ?? new JournalReadError('journal_read_failed', 'Journal holds no entries.');
+    io.stderr(`REFUSED [${failure.code}] ${failure.message}`);
+    return 2;
+  }
+  let view: RunView;
+  try {
+    view = foldRunState(taken.events, now());
+  } catch (error) {
+    const message = error instanceof RunStateError ? error.message : error instanceof Error ? error.message : String(error);
+    io.stderr(`REFUSED [run_state_invalid] ${message}`);
+    return 2;
+  }
+
+  // Tails are read for JSON (bounded, and the schema carries them) and for
+  // text only on request; a plain `flows status` opens the journal and nothing else.
+  const wantTails = args.json || args.tail !== undefined;
+  const tails = new Map<string, StepTails>();
+  if (options.tails !== undefined && wantTails) {
+    for (const step of view.steps) {
+      try {
+        tails.set(step.id, await options.tails.read(dataDir, runId, step, args.tail ?? DEFAULT_TAIL_LINES));
+      } catch {
+        if (!taken.partial.includes('transcript_tail_unreadable')) taken.partial.push('transcript_tail_unreadable');
+        tails.set(step.id, null);
+      }
+    }
+  }
+
+  const presented = present(view, thisStep, tails, env);
+  if (args.json) {
+    io.stdout(canonicalize({ v: 1, ...presented, partial: taken.partial }));
+  } else {
+    for (const line of renderText(presented, taken.partial, args.tail !== undefined)) io.stdout(line);
+  }
+  if (taken.failure !== undefined) io.stderr(`FAILED [${taken.failure.code}] ${taken.failure.message}`);
+  return taken.partial.length === 0 ? 0 : 1;
+}
+
+type PresentedStep = StepView & { tails: StepTails };
+type Presented = Omit<RunView, 'steps'> & { this_step: string | null; steps: PresentedStep[] };
+
+/** Apply the redaction and size bounds the on-disk model does not have. */
+function present(view: RunView, thisStep: string | null, tails: Map<string, StepTails>, env: NodeJS.ProcessEnv): Presented {
+  return {
+    ...view,
+    this_step: thisStep,
+    steps: view.steps.map((step) => ({
+      ...step,
+      // An agent names the files it writes, and it inherits this process's
+      // environment, so a path is free text like any other here.
+      artifacts: { ...step.artifacts, paths: step.artifacts.paths.map((path) => redact(path, env)) },
+      last_attempt: step.last_attempt === null ? null : {
+        ...step.last_attempt,
+        verification: step.last_attempt.verification === null ? null : {
+          ...step.last_attempt.verification,
+          detail: redact(step.last_attempt.verification.detail, env).slice(0, DETAIL_LIMIT),
+        },
+        // The digest's strings were redacted when it was built (flows#491), by
+        // a redactor with a different rule set to this one. Redacting again on
+        // the way out costs nothing and closes the difference — this module is
+        // the one place that decides what reaches an agent-facing page.
+        transcript: step.last_attempt.transcript === null ? null : {
+          ...step.last_attempt.transcript,
+          path: step.last_attempt.transcript.path === null
+            ? null : redact(step.last_attempt.transcript.path, env),
+          model: step.last_attempt.transcript.model === null
+            ? null : redact(step.last_attempt.transcript.model, env),
+          failure: step.last_attempt.transcript.failure === null ? null : {
+            ...step.last_attempt.transcript.failure,
+            excerpt: redact(step.last_attempt.transcript.failure.excerpt, env).slice(0, DETAIL_LIMIT),
+          },
+        },
+      },
+      tails: tails.get(step.id) ?? null,
+    })),
+  };
+}
+
+const GLYPH: Record<StepView['state'], string> = {
+  pending: '○', runnable: '○', running: '↻', backoff: '↻', waiting: '⏸', needs_human: '⏸', done: '✓',
+};
+
+/** Agent-authored names cannot inject terminal control sequences (progress.ts). */
+function safe(name: string): string {
+  return name.replace(/[\x00-\x1f\x7f-\x9f]/g, '?');
+}
+
+export function formatDuration(ms: number): string {
+  const seconds = Math.max(0, ms) / 1000;
+  if (seconds < 60) return `${seconds.toFixed(1)}s`;
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes}m${String(Math.floor(seconds % 60)).padStart(2, '0')}s`;
+  return `${Math.floor(minutes / 60)}h${String(minutes % 60).padStart(2, '0')}m`;
+}
+
+function thousands(value: number): string {
+  return String(value).replace(/\B(?=(\d{3})+(?!\d))/g, ',');
+}
+
+function instant(ms: number): string {
+  return new Date(ms).toISOString().replace(/\.\d{3}Z$/, 'Z');
+}
+
+function renderText(view: Presented, partial: string[], wantTails: boolean): string[] {
+  const lines: string[] = [];
+  const spend = `${thousands(view.spend.tokens_in)} in / ${thousands(view.spend.tokens_out)} out / $${view.spend.dollars}`
+    + (view.spend.dollars_unmetered ? ' (unmetered)' : '');
+  const finished = view.completion_reason === null ? '' : `   finished ${view.completion_reason}`;
+  lines.push(`RUN ${view.run_id}   ${safe(view.name)}   ${view.status}   started ${formatDuration(view.now_ms - view.spawned_at_ms)} ago${finished}   spend ${spend}`);
+  const counts = (['done', 'running', 'pending', 'backoff', 'waiting', 'needs_human'] as const)
+    .filter((key) => view.counts[key] > 0).map((key) => `${view.counts[key]} ${key}`);
+  // The denominator is always printed, even for zero steps, so a reader can
+  // tell "nothing to show" from "nothing was read".
+  lines.push(`steps ${view.counts.total}${counts.length === 0 ? '' : `: ${counts.join(' · ')}`}`);
+  if (partial.length > 0) lines.push(`partial: ${partial.join(', ')}`);
+  lines.push('');
+  const idWidth = Math.max(4, ...view.steps.map((step) => Math.min(24, step.id.length)));
+  for (const step of view.steps) lines.push(...renderStep(step, view, idWidth, wantTails));
+  return lines;
+}
+
+function renderStep(step: PresentedStep, view: Presented, idWidth: number, wantTails: boolean): string[] {
+  // `completion_reason`, not `last_attempt`: an epoch summary carries the
+  // reason without an attempt record, and reading the latter marked every
+  // compacted success as a failure.
+  const failed = step.state === 'done' && step.completion_reason !== 'success';
+  const glyph = failed ? '✗' : GLYPH[step.state];
+  const cells = [safe(step.id).slice(0, 24).padEnd(idWidth), step.type.padEnd(13), step.state.padEnd(11)];
+  const iterations = step.max_iterations === null ? '' : `/${step.max_iterations}`;
+  // `> 0` matters for a step carried done by an epoch summary: the summary
+  // has no attempt count, so the fold leaves it 0 and printing "0 attempts"
+  // would state a fact the journal no longer holds. Blank, like every other
+  // state does at 0.
+  if (step.state === 'done' && step.attempt > 0) cells.push(`${step.attempt} attempt${step.attempt === 1 ? '' : 's'}`);
+  else if (step.attempt > 0) cells.push(`attempt ${step.attempt}${iterations}`);
+  if (step.elapsed_ms !== null) cells.push(formatDuration(step.elapsed_ms));
+  if (step.state === 'running' && step.lease !== null) {
+    cells.push(step.lease.overdue_ms > 0
+      ? `LEASE OVERDUE by ${formatDuration(step.lease.overdue_ms)}`
+      : `lease ok (expires in ${formatDuration(step.lease.deadline_ms - view.now_ms)})`);
+  }
+  if (step.state === 'backoff' && step.backoff_until_ms !== null) cells.push(`backoff until ${instant(step.backoff_until_ms)}`);
+  if (step.wait !== null) cells.push(`awaiting ${step.wait.kind}: ${safe(step.wait.wait_id)}`);
+  if (step.state === 'done' && step.completion_reason !== null) {
+    // From the step, not the attempt: an epoch-carried step has the reason
+    // and no attempt record, and the reason is the thing worth printing.
+    cells.push(step.completion_reason);
+    const verification = step.last_attempt?.verification ?? null;
+    if (verification !== null) cells.push(`gate: ${verification.gate} ${verification.verdict}`);
+  }
+  if (step.id === view.this_step) cells.push('← this step');
+  const lines = [`  ${glyph} ${cells.join('  ')}`.trimEnd()];
+
+  const last = step.last_attempt;
+  if (last !== null && step.state !== 'done') {
+    lines.push(`      last attempt ${last.attempt}: ${last.completion_reason} → ${last.disposition}`);
+  }
+  if (last?.verification !== null && last?.verification !== undefined && last.verification.verdict !== 'pass') {
+    lines.push(`        gate: ${last.verification.gate} ${last.verification.verdict.toUpperCase()} — ${JSON.stringify(last.verification.detail)}`);
+  }
+  const transcript = last?.transcript ?? null;
+  if (transcript !== null) {
+    // One line of provenance: what ran, how much it cost, and where the full
+    // transcript is. `flows status` never prints the transcript itself — that
+    // is `--tail`'s job for the live attempt, and the file's for a finished one.
+    const facts = [
+      transcript.model === null ? null : safe(transcript.model),
+      transcript.num_turns === null ? null : `${transcript.num_turns} turn${transcript.num_turns === 1 ? '' : 's'}`,
+      transcript.tool_calls === null ? null : `${transcript.tool_calls} tool call${transcript.tool_calls === 1 ? '' : 's'}`,
+      transcript.total_cost_usd === null ? null : `$${transcript.total_cost_usd}`,
+    ].filter((fact): fact is string => fact !== null);
+    const size = transcript.bytes === null ? '' : ` (${transcript.bytes} bytes${transcript.truncated ? ', truncated' : ''})`;
+    lines.push(`      transcript (attempt ${last!.attempt})${facts.length === 0 ? '' : `: ${facts.join(' · ')}`}`);
+    if (transcript.path !== null) lines.push(`        ${safe(transcript.path)}${size}`);
+    if (transcript.failure !== null && transcript.failure.excerpt.length > 0) {
+      lines.push(`        failed at ${safe(transcript.failure.kind)}: ${JSON.stringify(transcript.failure.excerpt)}`);
+    }
+  }
+  if (step.type === 'agent' && last !== null) {
+    const shown = step.artifacts.paths.slice(0, 10).map(safe).join(', ');
+    const more = step.artifacts.paths.length > 10 ? ` +${step.artifacts.paths.length - 10} more` : '';
+    lines.push(`      artifacts (attempt ${last.attempt}): ${step.artifacts.journaled
+      ? step.artifacts.paths.length === 0 ? 'none' : `${shown}${more}`
+      : 'none journaled (output was a JSON object)'}`);
+  }
+  if (wantTails && step.type === 'agent' && step.attempt > 0) {
+    for (const stream of ['stdout', 'stderr'] as const) {
+      const tail = step.tails?.[stream] ?? null;
+      if (tail === null) {
+        lines.push(`      ${stream} tail: no transcript on disk for attempt ${step.attempt}`);
+        continue;
+      }
+      lines.push(`      ${stream} tail (attempt ${tail.attempt}, last ${tail.lines.length} of ${tail.bytes} bytes):`);
+      for (const line of tail.lines) lines.push(`        ${safe(line)}`);
+    }
+  }
+  return lines;
+}