@relayflows/sdk 2.0.29 → 2.0.31

package/src/cli/run.ts

@@ -1,3 +1,4 @@
+import { onWorkerFailure } from '../worker-lease.js';
 import { communicationInstruction } from '../communication/spec.js';
 import { checkCommunicationEnvironment, CommunicationEnvironmentError } from '../communication/preflight.js';
 import { parseHumanRecipient } from '../human-to.js';
@@ -9,25 +10,33 @@ import { AuthoredFlowExecutionError, AuthoredHumanParked, type AuthoredHumanWait
 import { answerCommand, resumeCommand } from '../authored-human.js';
 import { join, resolve } from 'node:path';
 import type { ProgressEvent } from '../progress.js';
+import type { JournalEvent } from '../journal-reader.js';
 import { toKernelSpec } from '../compile.js';
 import { socketPathFor } from '../daemon-connection.js';
 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 {
+  authoredInput, authoredWorkerRemedy, localAgentRemedy,
+  type AuthoredInput, type LocalAgentRemedy,
+} from './local-agent-remedy.js';
+import type { ParkCause, RunFailureKind, RunWarningKind, StepFailedDetails } from '../failure-kinds.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';
-import { readAuthoredRootMetadata, resumeDurableAuthoredFlow } from '../authored-root.js';
+import { readAuthoredRootMetadata, resumeDurableAuthoredFlow, type AuthoredRootMetadata } from '../authored-root.js';
 import type {
   RunCompletionReason,
   RunOutcome,
   RunStatus,
 } from '../protocol.js';
 import type { StepType } from '../spec.js';
+import {
+  singleLineCompletionDetail,
+  type LoweredCompletionReason,
+} from '../authored-completion.js';
 import { DEFAULT_LOCAL_AGENT_CAPACITY } from '../worker-slots.js';
-import type { LoweredCompletionReason } from '../authored-flow-executor.js';
 import {
   checkFlow,
   type CheckReport,
@@ -57,9 +66,27 @@ export interface RunReport {
   socketPath?: string;
   status?: RunStatus;
   completionReason?: RunCompletionReason;
+  /**
+   * What the body passed to `done(reason, { detail })`, normalized: redacted,
+   * trimmed, and bounded to 2,000 code points. Absent for every one-argument
+   * call, so an existing report keeps its exact shape — and absent on the
+   * paths where no authored body declared the outcome at all.
+   */
+  completionDetail?: string;
   completedSteps?: number;
   reuse?: { fromRunId: string; reusedSteps: number; executedSteps: number };
   parkedStep?: ParkedStep;
+  /**
+   * Why an exit-3 park happened, when classification established it.
+   *
+   * Carried structurally so a consumer — including this package's own authored
+   * boundaries — can tell "nothing is attached to run this step" from "the
+   * kernel is waiting for a human to recover it" without matching on the
+   * rendered message. Absent means the cause was not established, never
+   * `worker_unavailable` by default: recommending a worker for a `needs_human`
+   * park is the wrong answer, and guessing it is worse than saying nothing.
+   */
+  parkCause?: ParkCause;
   /** The open `f.human` question a parked authored run is waiting on. */
   humanWait?: AuthoredHumanWait;
   /** `flows answer` only: the answer it recorded. */
@@ -91,6 +118,10 @@ export interface RunLifecycleOptions {
   onPtyReady?: (path: string) => void;
   reuseFromRunId?: string;
   onProgress?: (event: ProgressEvent) => void;
+  /** Stream the run's journal entries while it runs (YAML runs, via `run.start {watch}` / `run.watch`). */
+  onJournalEntry?: (entry: JournalEvent) => void;
+  /** An authored root was admitted: its id is known before its body runs. */
+  onRunStarted?: (run: { runId: string; flow: string; resumed?: boolean }) => void;
   localAgent?: boolean;
   /** `--agent-capacity`: the local workers' concurrency; the default is `DEFAULT_LOCAL_AGENT_CAPACITY`. */
   agentCapacity?: number;
@@ -158,7 +189,8 @@ async function executeCheckedFlow(
       const { attachCommunicationWorkers } = await import('../communication/local.js');
       communicationWorkers = await attachCommunicationWorkers(spec, socketPath, dataDir);
     }
-    const outcome = await client.runStart(spec, options.reuseFromRunId);
+    if (options.onJournalEntry !== undefined) client.on('entry', options.onJournalEntry);
+    const outcome = await startWatched(client, spec, options);
     const execution = await classifyOutcome(client, 'run', outcome, base, socketPath, { ...options, dataDir });
     if (options.reuseFromRunId !== undefined) {
       execution.report.reuse = await reuseSummary(client, outcome.run_id, options.reuseFromRunId);
@@ -178,10 +210,33 @@ async function executeCheckedFlow(
     }
     return protocolFailure('run', base, socketPath, communicationWorkers?.failure ?? localAgent?.failure ?? error);
   } finally {
+    if (options.onJournalEntry !== undefined) client.off('entry', options.onJournalEntry);
     try { await communicationWorkers?.close(); } finally { try { await localAgent?.close(); } finally { client.close(); } }
   }
 }
 
+/**
+ * `run.start`, streaming the run's entries to `onJournalEntry` when one is
+ * given. A daemon that predates `watch` refuses the field while decoding,
+ * before any run exists, so starting again without it is the same request
+ * minus the observation — never a second run.
+ */
+async function startWatched(
+  client: JournalClient,
+  spec: ReturnType<typeof toKernelSpec>,
+  options: RunLifecycleOptions,
+): Promise<RunOutcome> {
+  const onEntry = options.onJournalEntry;
+  if (onEntry === undefined) return client.runStart(spec, options.reuseFromRunId);
+  try {
+    return await client.runStart(spec, options.reuseFromRunId, undefined, true);
+  } catch (error) {
+    if (!(error instanceof JournalProtocolError) || error.code !== 'bad_request'
+      || !/unknown field `watch`/.test(error.message)) throw error;
+    return await client.runStart(spec, options.reuseFromRunId);
+  }
+}
+
 export async function resumeFlow(
   runId: string,
   dataDir: string,
@@ -196,16 +251,34 @@ export async function resumeFlow(
   let communicationWorkers: Awaited<ReturnType<typeof import('../communication/local.js').attachCommunicationWorkers>> | undefined;
   let authoredAgent: Awaited<ReturnType<typeof attachLocalAgent>> | undefined;
   let authoredLlm: LlmWorker | undefined;
+  let llmFailure: unknown;
   let authoredLlmClient: JournalClient | undefined;
+  // Hoisted so the catch below can build the authored park remedy from the same
+  // metadata this resume was admitted against — the journal is the only place
+  // the flow path and the original `--input` survive a process boundary.
+  let authoredRoot: AuthoredRootMetadata | undefined;
   const workerCapacity = options.agentCapacity ?? DEFAULT_LOCAL_AGENT_CAPACITY;
   try {
-    const authoredRoot = await readAuthoredRootMetadata(client, runId);
+    authoredRoot = await readAuthoredRootMetadata(client, runId);
     if (authoredRoot !== undefined) {
+      // Both worker-surface mismatches are refusals, not protocol failures.
+      // They used to throw bare `Error`s, which landed on `protocol_error`
+      // ("RUN <id> unknown") and told nobody what to do instead; and the
+      // second one is the exact complaint this change answers — `--local-agent`
+      // accepted on a run that cannot grow one is worse than rejected, because
+      // the run parks again with a message that has not changed.
       if (authoredRoot.localAgentStream !== undefined && !options.localAgent) {
-        throw new Error('authored root requires --local-agent to resume its pinned worker surface');
+        return localAgentRefusal(base, runId, socketPath,
+          `Run "${runId}" was started with a local agent worker surface, so resuming it needs the same flag.`
+            + ` To continue this run: ${resumeCommand(runId, dataDir, true)}.`);
       }
       if (authoredRoot.localAgentStream === undefined && options.localAgent) {
-        throw new Error('authored root was started without a local agent worker surface');
+        return localAgentRefusal(base, runId, socketPath,
+          `Run "${runId}" was started without a local agent worker surface:`
+            + ' --local-agent is admitted at run start; start a new run.'
+            + localAgentRemedy(authoredWorkerRemedy('worker_unavailable', false, {
+              path: authoredRoot.flowPath, input: authoredInputArgument(authoredRoot), dataDir,
+            })));
       }
       if (options.localAgent) {
         authoredAgent = await attachLocalAgent(
@@ -215,6 +288,10 @@ export async function resumeFlow(
         await authoredLlmClient.connect();
         await authoredLlmClient.hello('flows-authored-resume-llm');
         authoredLlm = new LlmWorker(authoredLlmClient, `${authoredAgent.stream}-llm`, workerCapacity);
+        authoredLlm.on('error', onWorkerFailure('resume-llm', error => {
+          llmFailure = error;
+          client.close();
+        }));
         await authoredLlm.attach();
       }
       const result = await resumeDurableAuthoredFlow(runId, client, {
@@ -239,6 +316,13 @@ export async function resumeFlow(
         communicationWorkers = await attachCommunicationWorkers(spec, socketPath, dataDir);
       }
     }
+    const onEntry = options.onJournalEntry;
+    if (onEntry !== undefined) {
+      client.on('entry', onEntry);
+      // Observation never decides a resume: a watch the daemon refuses leaves
+      // the run unprojected, and the resume below reports the run's own fate.
+      await client.runWatch(runId).catch(() => client.off('entry', onEntry));
+    }
     let outcome = await client.runResume(runId, options.allowHumanInfluenced);
     if (await resumeHelperEffect(client, runId, dataDir)) {
       outcome = await client.runResume(runId, options.allowHumanInfluenced);
@@ -269,11 +353,41 @@ export async function resumeFlow(
     if (error instanceof AuthoredFlowExecutionError && (error.code === 'step_failed' || error.code === 'gate_failed')) {
       return authoredStepFailure('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
+    // only honest instruction is a new run carrying the same `--input`.
+    // `runId` here is the CHILD run holding the evidence; the root this resume
+    // named stays separate, so `flows` can still collect it.
+    if (error instanceof AuthoredFlowExecutionError && (error.code === 'agent_parked' || error.code === 'llm_parked')) {
+      return {
+        exitCode: 3,
+        report: {
+          ...base,
+          ok: false,
+          runId: error.runId ?? runId,
+          rootRunId: runId,
+          socketPath,
+          status: 'parked',
+          parkCause: error.parkCause,
+          diagnostics: [...base.diagnostics, {
+            severity: 'parked',
+            kind: 'run_parked',
+            message: error.message + localAgentRemedy(authoredWorkerRemedy(
+              error.parkCause, options.localAgent === true,
+              { path: authoredRoot?.flowPath, input: authoredInputArgument(authoredRoot), dataDir },
+            )),
+          }],
+        },
+      };
+    }
     if (error instanceof AuthoredHumanParked) {
       return authoredHumanParked('resume', base, socketPath, error, { dataDir, localAgent: options.localAgent === true });
     }
     if (!(error instanceof JournalProtocolError) || error.code !== 'run_not_found') {
-      return protocolFailure('resume', base, socketPath, error, runId);
+      const cause = error instanceof AuthoredFlowExecutionError
+        ? error : llmFailure ?? authoredAgent?.failure ?? error;
+      return protocolFailure('resume', base, socketPath, cause, runId);
     }
     return {
       exitCode: 2,
@@ -290,6 +404,7 @@ export async function resumeFlow(
     };
   } finally {
     try {
+      if (options.onJournalEntry !== undefined) client.off('entry', options.onJournalEntry);
       await communicationWorkers?.close();
       await authoredLlm?.close();
       authoredLlmClient?.close();
@@ -300,6 +415,45 @@ export async function resumeFlow(
   }
 }
 
+/**
+ * A `--local-agent` mismatch, refused before the resume touches the journal.
+ *
+ * Exit 2 and `ok` left false by `emptyReport`: nothing ran, so this is the same
+ * shape as every other pre-journal refusal on this surface (docs/SURFACE.md §5).
+ * It returns rather than throwing so no worker is attached on the way out.
+ */
+function localAgentRefusal(
+  base: RunReport, runId: string, socketPath: string, message: string,
+): RunExecution {
+  return {
+    exitCode: 2,
+    report: { ...base, runId, socketPath,
+      diagnostics: [...base.diagnostics, { severity: 'refusal', kind: 'local_agent_unavailable', message }] },
+  };
+}
+
+/**
+ * The `--input` argument a new run of this authored root would have to repeat,
+ * rendered back from the journaled metadata.
+ *
+ * `absent` when the root recorded no input, and also when the recorded input is
+ * something `JSON.stringify` cannot render — the remedy formatter then says an
+ * input is required instead of printing a command that would be refused as
+ * `input_invalid`. What it must never do is substitute `{}`: that is a
+ * different invocation of the flow than the one that parked.
+ *
+ * Unlike `runDirectFlow`, this side has only the decoded value: the journal
+ * records the input, not the `--input` word that carried it, so a run started
+ * from a file comes back as inline JSON. `authoredInput` is what keeps that
+ * honest about its own size — a recorded input can be larger than a shell
+ * argument even when the file that supplied it was unremarkable.
+ */
+function authoredInputArgument(metadata: AuthoredRootMetadata | undefined): AuthoredInput {
+  if (metadata === undefined || !metadata.inputPresent) return { kind: 'absent' };
+  const rendered = JSON.stringify(metadata.input);
+  return authoredInput(typeof rendered === 'string' ? rendered : undefined);
+}
+
 /**
  * A step that ran and failed, reported as the run failure it is.
  *
@@ -405,15 +559,30 @@ export function authoredCompletion(
   command: RunCommand,
   base: RunReport,
   socketPath: string,
-  result: { name: string; completionReason: LoweredCompletionReason; journalSteps: readonly unknown[] },
+  result: {
+    name: string;
+    completionReason: LoweredCompletionReason;
+    completionDetail?: string;
+    journalSteps: readonly unknown[];
+  },
   runId: string | undefined,
 ): RunExecution {
   const common: RunReport = {
     ...fromBase(command, base),
     ...(runId === undefined ? {} : { runId }),
     socketPath,
+    ...(result.completionDetail === undefined ? {} : { completionDetail: result.completionDetail }),
     completedSteps: result.journalSteps.length,
   };
+  // Two spellings of the same fact, on purpose. `detail` is the structured
+  // one — the `StepFailedDetails` key the diagnostic already declares, here
+  // describing the AUTHOR's verdict rather than the daemon's account of a
+  // failing step — and keeps the body's own line breaks. `said` is the same
+  // text folded onto one line for the message, because Cloud renders a run's
+  // `error` through a view that elides the middle of a long one.
+  const detail = result.completionDetail;
+  const evidence = detail === undefined ? {} : { detail };
+  const said = detail === undefined ? '' : singleLineCompletionDetail(detail);
   switch (result.completionReason) {
     case 'success':
       return {
@@ -427,7 +596,9 @@ export function authoredCompletion(
           ...common, ok: true, status: 'completed', completionReason: 'success',
           diagnostics: [...base.diagnostics, {
             severity: 'declined', kind: 'run_declined',
-            message: 'Flow deliberately chose not to act on this input.',
+            ...evidence,
+            message: 'Flow deliberately chose not to act on this input.'
+              + (detail === undefined ? '' : ` ${said}`),
           }],
         },
       };
@@ -438,7 +609,9 @@ export function authoredCompletion(
           ...common, ok: false, status: 'parked',
           diagnostics: [...base.diagnostics, {
             severity: 'parked', kind: 'run_parked',
-            message: `Flow "${result.name}" needs_human; see the journal for accumulated blockers.`,
+            ...evidence,
+            message: `Flow "${result.name}" needs_human; see the journal for accumulated blockers.`
+              + (detail === undefined ? '' : ` ${said}`),
           }],
         },
       };
@@ -454,9 +627,16 @@ export function authoredCompletion(
           ...common, ok: false, status: 'failed', completionReason: 'step_failed',
           diagnostics: [...base.diagnostics, {
             severity: 'failure', kind: 'step_failed',
-            message: `Flow "${result.name}" declared done("step_failed"): its own checks did not pass. `
-              + 'No step failed, so there is no step-level evidence to inspect; the journal holds '
-              + 'every step the flow ran before it decided.',
+            ...evidence,
+            // With a detail, the flow's own account REPLACES the generic
+            // sentence: "no step-level evidence to inspect" is the only thing
+            // there is to say when the body said nothing, and saying it
+            // beside a real explanation would bury the explanation.
+            message: detail === undefined
+              ? `Flow "${result.name}" declared done("step_failed"): its own checks did not pass. `
+                + 'No step failed, so there is no step-level evidence to inspect; the journal holds '
+                + 'every step the flow ran before it decided.'
+              : `Flow "${result.name}" declared done("step_failed"): ${said}`,
           }],
         },
       };
@@ -664,25 +844,14 @@ export async function classifyOutcome(
       report: {
         ...report,
         parkedStep,
+        parkCause: needsHuman ? 'needs_human' : 'worker_unavailable',
         diagnostics: [...report.diagnostics, {
           severity: 'parked',
           kind: 'run_parked',
           message: needsHuman
             ? `Run "${current.run_id}" parked at step "${parkedStep.id}" (${parkedStep.type}): waiting for human recovery after the worker attempt failed.`
             : `Run "${current.run_id}" parked at step "${parkedStep.id}" (${parkedStep.type}): no worker is attached for step type "${parkedStep.type}".`
-              // Only suggest the `--local-agent` remedy for YAML flows.
-              // Authored TS flows require `--input`; the bare command below
-              // would be refused (Cursor Bugbot flagged as LOW on flows#293).
-              // For TS we omit the hint rather than fabricate a syntactically
-              // valid but semantically wrong command — the direct-run refusal
-              // for TS already names its own missing --input.
-              + (command === 'run'
-                  && parkedStep.type === 'agent'
-                  && !options.localAgent
-                  && base.path !== undefined
-                  && !isAuthoredFlowPath(base.path)
-                ? ` To start a new run with a local agent worker: flows run --local-agent '${base.path.replace(/'/g, "'\\''")}'. Declared workspace or stream surfaces require a worker that holds their pins.`
-                : ''),
+              + localAgentRemedy(declarativeWorkerRemedy(command, current.run_id, parkedStep, base, options)),
         }],
       },
     };
@@ -692,6 +861,39 @@ export async function classifyOutcome(
   ), current.run_id);
 }
 
+/**
+ * Which remedy a worker park gets from the declarative classifier.
+ *
+ * An authored `.flow.ts` is deliberately SILENT here, and the suppression is
+ * tested first on purpose. Its remedy is a new run carrying the same `--input`,
+ * an argument this function does not have; `runDirectFlow` and `resumeFlow`
+ * render it once at the authored boundary where the input (or the journaled
+ * metadata holding it) is in hand. `classifyOutcome` also runs once per
+ * authored `f.agent` CHILD run, so answering here as well would append a
+ * remedy to every child message on the way out — and, on resume, a second
+ * contradictory one after the attached-worker branch below.
+ *
+ * `llm` parks get nothing, unchanged: the declarative verbs attach an
+ * agent-only worker (local-agent.ts advertises `['agent']`), so `--local-agent`
+ * is not a remedy for an `llm` step outside the authored path, which attaches
+ * an `LlmWorker` of its own.
+ */
+function declarativeWorkerRemedy(
+  command: RunCommand,
+  runId: string,
+  parkedStep: ParkedStep,
+  base: CheckReport | RunReport,
+  options: RunLifecycleOptions,
+): LocalAgentRemedy {
+  const dataDir = options.dataDir;
+  if (parkedStep.type !== 'agent') return { kind: 'none' };
+  if (base.path !== undefined && isAuthoredFlowPath(base.path)) return { kind: 'none' };
+  if (options.localAgent === true) return { kind: 'attached' };
+  if (command === 'resume') return { kind: 'spec-resume', runId, dataDir };
+  if (command === 'run' && base.path !== undefined) return { kind: 'spec-run', path: base.path, dataDir };
+  return { kind: 'none' };
+}
+
 interface OutOfBandInspection {
   status: RunStatus;
   parkedStep?: ParkedStep;
@@ -742,6 +944,9 @@ async function inspectOutOfBandStep(
   };
 }
 
+// Match kernel/relayflowd/src/server/client.rs: allow the lease sweep to dispatch a retry.
+const LEASE_SWEEP_GRACE_MS = 5_000;
+
 async function waitForRunningStep(
   client: JournalClient,
   runId: string,
@@ -760,7 +965,7 @@ async function waitForRunningStep(
   });
   while (true) {
     throwIfCanceled(options.signal, runningStep.id);
-    const remainingMs = leaseDeadlineMs - Date.now();
+    const remainingMs = leaseDeadlineMs + LEASE_SWEEP_GRACE_MS - Date.now();
     if (remainingMs <= 0) {
       throw new Error(
         `worker lease for step "${runningStep.id}" expired at ${leaseDeadlineMs} without completion`,

package/src/cli/status.ts

@@ -13,6 +13,8 @@ import { AUTHORED_STEP_STREAM, foldAuthoredStepRecords, type AuthoredStepRecord
 import { canonicalize } from '../canonical.js';
 import { DEFAULT_DATA_DIR } from '../daemon-connection.js';
 import { JournalReadError, walkJournal, type JournalEvent } from '../journal-client.js';
+import { singleLineCompletionDetail } from '../authored-completion.js';
+import { authoredVerdictOf, type AuthoredVerdict } from '../authored-verdict.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';
@@ -32,11 +34,25 @@ export interface StatusArgs {
    * module keeps its property of opening one file and no socket.
    */
   cloud?: true;
+  /**
+   * `--watch`: redraw the hosted page until the run is terminal.
+   *
+   * Only with `--cloud`. A local `flows status` reads one journal file and
+   * returns; there is no loop for it to hang in, so `--watch` without
+   * `--cloud` is a contradiction rather than a narrower request, and is
+   * refused with the rest of the invocation. Handled in `cli/cloud-live.ts`.
+   */
+  watch?: 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;
+// An authored completion detail is NOT held to `DETAIL_LIMIT`. That bound is
+// the head of a gate render the journal holds in full; this text is already
+// bounded to 2,000 code points at `done()`, it is the whole of what the flow
+// said about its own verdict, and cutting it at 1,024 would drop the finding
+// as often as not.
 const BUSY_RETRIES = 5;
 const BUSY_RETRY_DELAY_MS = 50;
 
@@ -64,6 +80,7 @@ export interface StatusOptions {
 export function parseStatusArgs(args: readonly string[]): StatusArgs | undefined {
   let json = false;
   let cloud = false;
+  let watch = false;
   let dataDir: string | undefined;
   let tail: number | undefined;
   const positionals: string[] = [];
@@ -75,6 +92,9 @@ export function parseStatusArgs(args: readonly string[]): StatusArgs | undefined
     } else if (argument === '--cloud') {
       if (cloud) return undefined;
       cloud = true;
+    } else if (argument === '--watch') {
+      if (watch) return undefined;
+      watch = true;
     } else if (argument === '--data-dir' || argument === '--tail') {
       const value = args[++index];
       if (value === undefined || value.length === 0 || value.startsWith('-')) return undefined;
@@ -98,9 +118,11 @@ export function parseStatusArgs(args: readonly string[]): StatusArgs | undefined
   // 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;
+  if (watch && !cloud) return undefined;
   return {
     command: 'status', json,
     ...(cloud ? { cloud: true as const } : {}),
+    ...(watch ? { watch: true as const } : {}),
     ...(dataDir === undefined ? {} : { dataDir }),
     ...(tail === undefined ? {} : { tail }),
     ...(positionals[0] === undefined ? {} : { runId: positionals[0] }),
@@ -178,7 +200,7 @@ export async function runStatus(args: StatusArgs, io: CliIo, options: StatusOpti
     }
   }
 
-  const presented = present(view, thisStep, tails, env);
+  const presented = present(view, thisStep, tails, env, authoredVerdictOf(taken.events));
   if (args.json) {
     const authored = authoredSteps(taken.events, env);
     io.stdout(canonicalize({
@@ -237,13 +259,41 @@ function authoredSteps(events: readonly JournalEvent[], env: NodeJS.ProcessEnv):
 }
 
 type PresentedStep = StepView & { tails: StepTails };
-type Presented = Omit<RunView, 'steps'> & { this_step: string | null; steps: PresentedStep[] };
+type Presented = Omit<RunView, 'steps'> & {
+  this_step: string | null;
+  steps: PresentedStep[];
+  /**
+   * The verdict the BODY declared, beside — never instead of — the kernel
+   * facts above. `status`, `completion_reason` and every step stay exactly
+   * what the journal recorded, because they are true: an authored
+   * `step_failed` run completes with a root step that succeeded.
+   *
+   * Present only when the body actually said why. A one-argument `done()`
+   * adds nothing a reader could not already see from `completion_reason`, and
+   * emitting a null here for every legacy and non-authored run would change a
+   * shape that nobody asked to change.
+   */
+  authored_completion?: { reason: string; detail: string };
+};
 
 /** 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 {
+function present(
+  view: RunView,
+  thisStep: string | null,
+  tails: Map<string, StepTails>,
+  env: NodeJS.ProcessEnv,
+  authored: AuthoredVerdict | null,
+): Presented {
   return {
     ...view,
     this_step: thisStep,
+    ...(authored?.detail === undefined ? {} : {
+      // Redacted again on the way out. It was redacted before it was
+      // journaled, by this same redactor against a different environment;
+      // doing it here too costs nothing and keeps this module the one place
+      // that decides what reaches an agent-facing page.
+      authored_completion: { reason: authored.reason, detail: redact(authored.detail, env) },
+    }),
     steps: view.steps.map((step) => ({
       ...step,
       // An agent names the files it writes, and it inherits this process's
@@ -307,6 +357,12 @@ function renderText(view: Presented, partial: string[], wantTails: boolean): str
     + (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}`);
+  // Labelled, so nobody reads a failure explanation as a claim that the run's
+  // kernel status is anything other than the line above says it is.
+  if (view.authored_completion !== undefined) {
+    lines.push(`authored done("${safe(view.authored_completion.reason)}"): `
+      + safe(singleLineCompletionDetail(view.authored_completion.detail)));
+  }
   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