@relayflows/sdk 2.0.30 → 2.0.31

package/src/authored-completion.ts

@@ -0,0 +1,203 @@
+// The authored verdict: which completions this runtime lowers, the durable
+// marker that carries one, and the optional detail that says why.
+//
+// Split out of `authored-flow-executor.ts` so the CLI report and the status
+// projection can read this vocabulary without importing the executor — and
+// with it every provider adapter, MCP client and helper the executor pulls
+// in. Nothing here does I/O or reads a clock.
+
+import { AuthoredFlowExecutionError } from './authored-flow-error.js';
+import { redact } from './redact.js';
+
+/**
+ * The completion reasons an authored body may declare and this executor lowers.
+ *
+ * `FlowCompletionReason` is wider than this on purpose — it is the journal's
+ * run vocabulary plus authored verdicts — but the two sets drifting silently is
+ * exactly what made a type-valid `done("step_failed")` die at runtime as
+ * `unsupported_completion`. Every gate that asks "is this a completion this
+ * runtime can lower?" now asks this one function, so a reason cannot be
+ * accepted in one place and rejected in another.
+ *
+ * These are internal cross-module helpers for the authored seam (the executor,
+ * the durable root, the IPC verifier, the CLI report and `flows status`), NOT
+ * public SDK surface. `src/index.ts` deliberately re-exports nothing from this
+ * module — keep it that way, or the whole authored seam leaks with them.
+ */
+export const LOWERED_COMPLETIONS = ['success', 'needs_human', 'step_failed', 'declined'] as const;
+export type LoweredCompletionReason = (typeof LOWERED_COMPLETIONS)[number];
+
+export function isLoweredCompletion(value: unknown): value is LoweredCompletionReason {
+  return typeof value === 'string' && (LOWERED_COMPLETIONS as readonly string[]).includes(value);
+}
+
+/**
+ * The bound on a normalized completion detail: 2,000 Unicode code points in
+ * the FINAL string, {@link COMPLETION_DETAIL_TRUNCATED_SUFFIX} included.
+ *
+ * Code points, not `String.length`: `.length` counts UTF-16 code units, so an
+ * emoji-heavy detail measured that way is half the length a reader would call
+ * it. The number matches `@relayflows/surface`'s
+ * `COMPLETION_DETAIL_MAX_CODE_POINTS`, which is what an author sees; it is the
+ * same order as the kernel's gate-detail cap
+ * (`kernel/relayflowd/src/engine/remote.rs`) but deliberately NOT the same
+ * bound — that one takes 2,000 characters and then appends its suffix, so its
+ * final string is longer than the number it advertises.
+ */
+export const COMPLETION_DETAIL_MAX_CODE_POINTS = 2000;
+
+/** Fixed width, so the bound above can reserve exactly its room. */
+export const COMPLETION_DETAIL_TRUNCATED_SUFFIX = '… (truncated)';
+
+/**
+ * Read `done()`'s optional second argument into the detail the marker carries.
+ *
+ * Absence has four spellings — no argument, `undefined`, `{}`, and
+ * `{ detail: undefined }` — and all four mean the same thing: no detail, and a
+ * marker command byte-identical to the one the one-argument call has always
+ * produced. Whitespace-only joins them: say nothing, or say something.
+ *
+ * A `detail` that is present and not a string is a programming error the type
+ * system already catches for TypeScript callers; the runtime check is here for
+ * the same reason `isSurfaceFlowCompletionReason` is, and it refuses with the
+ * existing closed `unsupported_completion` code rather than widening the
+ * taxonomy. Refusals name the type they got, never the value — a malformed
+ * detail is exactly the kind of text that may carry a credential.
+ *
+ * Redaction runs BEFORE truncation, and the order is load-bearing rather than
+ * cosmetic: truncating first can split a token so no pattern matches it any
+ * more, which is a truncation that *causes* a leak. What redaction recognises
+ * is the SDK's existing policy — known token shapes, named credential fields,
+ * and the values of secret-looking environment variables (`redact.ts`) — not a
+ * guarantee to recognise every possible secret.
+ *
+ * Lone surrogates are substituted here too, so what leaves this function is a
+ * well-formed string the journal protocol can carry — see {@link wellFormed}.
+ */
+export function normalizeCompletionDetail(
+  options: unknown,
+  env: NodeJS.ProcessEnv = process.env,
+): string | undefined {
+  if (options === undefined) return undefined;
+  if (typeof options !== 'object' || options === null || Array.isArray(options)) {
+    throw new AuthoredFlowExecutionError(
+      'unsupported_completion',
+      `done() options must be an object with an optional string "detail"; received ${typeName(options)}`,
+    );
+  }
+  const detail = (options as { detail?: unknown }).detail;
+  if (detail === undefined) return undefined;
+  if (typeof detail !== 'string') {
+    throw new AuthoredFlowExecutionError(
+      'unsupported_completion',
+      `done() detail must be a string; received ${typeName(detail)}`,
+    );
+  }
+  const redacted = wellFormed(redact(detail, env)).trim();
+  return redacted.length === 0 ? undefined : bound(redacted);
+}
+
+/**
+ * Lone UTF-16 surrogates, as code points.
+ *
+ * Under `u` a subject string is iterated by CODE POINT, so a well-formed pair
+ * is one code point above U+FFFF and never enters this class. What the class
+ * matches is exactly a surrogate with no partner.
+ */
+const LONE_SURROGATE = /[\uD800-\uDFFF]/u;
+const LONE_SURROGATES = /[\uD800-\uDFFF]/gu;
+
+/**
+ * Replace every lone surrogate with U+FFFD, the replacement character.
+ *
+ * A JavaScript string is UTF-16 code units, not text. Slicing a character off
+ * the end of an agent's output — `(prose + '\u{1F642}').slice(0, -1)` — leaves
+ * a high surrogate with no partner, and the type system calls the result a
+ * `string`. Nothing downstream does.
+ * `JSON.stringify` escapes it, so the marker COMMAND is admitted; the raw
+ * detail then travels in the root's `step.complete` output, where the kernel's
+ * JSON decoder refuses it ("unexpected end of hex escape") and answers with a
+ * `bad_request` carrying a null request id — which resolves no pending
+ * request, so the call hangs and the authored explanation never lands.
+ *
+ * Substituting is right here where refusing is not: the flow has already done
+ * its work and reached a verdict, and losing the whole explanation over one
+ * broken code unit destroys more than it protects. One code unit in, one code
+ * unit out, so the bound below still counts what a reader would count.
+ */
+function wellFormed(text: string): string {
+  return LONE_SURROGATE.test(text) ? text.replace(LONE_SURROGATES, '\uFFFD') : text;
+}
+
+/**
+ * Is this a detail a durable record may carry?
+ *
+ * The gate every read boundary uses — the completed root's output, and the
+ * IPC frame the Bun runner returns — so an over-long or wrong-typed value
+ * fails closed there instead of flowing into a report as if it had been
+ * journaled by this process.
+ */
+export function isDurableCompletionDetail(value: unknown): value is string {
+  return typeof value === 'string'
+    && value.length > 0
+    && !LONE_SURROGATE.test(value)
+    && [...value].length <= COMPLETION_DETAIL_MAX_CODE_POINTS;
+}
+
+/**
+ * The detail as ONE line, for a diagnostic message.
+ *
+ * Cloud renders a run's `error` through a line-oriented view that elides the
+ * middle of a long one (`cli/cloud-read.ts` `errorLines`), so a forty-line
+ * detail can lose the very finding it exists to carry. Escaping the breaks
+ * keeps the whole detail on the single line that renderer cannot elide, and
+ * keeps control characters out of a terminal. The unescaped normalized detail
+ * still travels in the structured fields beside it.
+ */
+export function singleLineCompletionDetail(detail: string): string {
+  return detail.replace(/[\u0000-\u001F\u007F-\u009F]/gu, (char) =>
+    NAMED_ESCAPE[char] ?? `\\u${char.codePointAt(0)!.toString(16).padStart(4, '0')}`);
+}
+
+const NAMED_ESCAPE: Record<string, string> = { '\n': '\\n', '\r': '\\r', '\t': '\\t' };
+
+/**
+ * The deterministic command that carries an authored verdict into the journal.
+ *
+ * `success` with no detail lowers to `:` because success needs no marker: the
+ * marker run's own kernel `success` already IS that record. Every other
+ * lowered verdict is something the kernel's completion vocabulary cannot
+ * express on a step that *succeeded*, so it travels as data on stdout and is
+ * read back from `step.completed`. It is deliberately not lowered as a failing
+ * command: no step failed here, and a fabricated failure would put bogus
+ * evidence in the journal for a flow whose steps all ran correctly.
+ *
+ * A detail rides in the same JSON object, so the marker stays the one durable
+ * record of the verdict and the IPC verifier's existing command comparison
+ * checks the detail against the journal for free. With no detail the command
+ * is byte-identical to the one this function has always returned, which is
+ * what keeps `spec_hash` stable for every flow that does not opt in.
+ */
+export function completionMarker(reason: LoweredCompletionReason, detail?: string): string {
+  if (detail === undefined) {
+    return reason === 'success' ? ':' : `printf '%s' '{"completionReason":"${reason}"}'`;
+  }
+  // `JSON.stringify` escapes quotes, backslashes and every control character,
+  // so the command is one line and the only shell-significant character left
+  // in it is `'` — which the single-quote escape below closes.
+  const json = JSON.stringify({ completionReason: reason, detail });
+  return `printf '%s' '${json.replaceAll("'", "'\\''")}'`;
+}
+
+function typeName(value: unknown): string {
+  if (value === null) return 'null';
+  if (Array.isArray(value)) return 'an array';
+  return `a ${typeof value}`;
+}
+
+function bound(text: string): string {
+  const points = [...text];
+  if (points.length <= COMPLETION_DETAIL_MAX_CODE_POINTS) return text;
+  const keep = COMPLETION_DETAIL_MAX_CODE_POINTS - [...COMPLETION_DETAIL_TRUNCATED_SUFFIX].length;
+  return `${points.slice(0, keep).join('')}${COMPLETION_DETAIL_TRUNCATED_SUFFIX}`;
+}

package/src/authored-flow-error.ts

@@ -1,5 +1,5 @@
 import type { HumanRecipient } from './human-to.js';
-import type { StepFailedDetails } from './failure-kinds.js';
+import type { ParkCause, StepFailedDetails } from './failure-kinds.js';
 import type {
   CompletionReason as ProtocolCompletionReason,
   RunCompletionReason as ProtocolRunCompletionReason,
@@ -42,6 +42,18 @@ export type AuthoredFlowExecutionErrorCode =
 export class AuthoredFlowExecutionError extends Error {
   /** Set by the durable root driver after the child error crosses any IPC boundary. */
   rootRunId?: string;
+  /**
+   * Why an `agent_parked`/`llm_parked` child run parked, as the child's own
+   * classification established it (`RunReport.parkCause`).
+   *
+   * Set by the worker runner beside the code, because the code alone does not
+   * say: `agent_parked` covers both "nothing is attached to run this step" and
+   * the kernel's `needs_human` recovery wait, and only the first is fixed by
+   * attaching a worker. The CLI boundary reads this field rather than matching
+   * the message, so the remedy it prints cannot drift from the cause. Absent
+   * means unestablished — the boundary then says nothing about workers.
+   */
+  parkCause?: ParkCause;
   constructor(
     readonly code: AuthoredFlowExecutionErrorCode,
     message: string,

package/src/authored-flow-executor.ts

@@ -13,6 +13,13 @@ import { AuthoredBudget } from './authored-budget.js';
 import { assertMemoryReachable, authoredMemory, scriptMemoryScope } from './authored-memory.js';
 import { authoredDeterministicRunner, authoredWorkerRunner } from './authored-worker-step.js';
 import { isSurfaceFlowCompletionReason, isSurfaceRunCompletionReason } from './authored-step-output.js';
+import {
+  completionMarker,
+  isLoweredCompletion,
+  normalizeCompletionDetail,
+  type LoweredCompletionReason,
+} from './authored-completion.js';
+import { commitAuthoredVerdict } from './authored-completion-record.js';
 import {
   type AgentResult,
   type LlmOptions,
@@ -21,6 +28,8 @@ import {
   type Ctx,
   type FlowCompletionReason,
   type RunCompletionReason as SurfaceRunCompletionReason,
+  type RunOptions,
+  type RunResult,
   type Step,
 } from '@relayflows/surface';
 import { createHelpers, helperProviders, type HelperCall, type FlowHandle } from '@relayflows/surface/runtime';
@@ -96,6 +105,12 @@ export interface AuthoredFlowExecutionResult {
   readonly rootRunId?: string;
   readonly name: string;
   readonly completionReason: LoweredCompletionReason;
+  /**
+   * Why, when the body said. Normalized at `done()` — redacted, trimmed and
+   * bounded — and absent for every one-argument call, so the durable output,
+   * the IPC frame and the report keep the shapes they had.
+   */
+  readonly completionDetail?: string;
   readonly journalSteps: readonly AuthoredFlowJournalStep[];
 }
 
@@ -243,6 +258,7 @@ export async function executeAuthoredFlow<Input = undefined>(
   const stepEdges = (step: string): AuthoredStepEdges | undefined => lifecycle.stepEdges(step);
   let nextStep = 1;
   let requestedCompletion: LoweredCompletionReason | undefined;
+  let requestedDetail: string | undefined;
 
   const lowerDeterministic = authoredDeterministicRunner(
     definition.name, journal, journalSteps, budget, {
@@ -382,6 +398,56 @@ export async function executeAuthoredFlow<Input = undefined>(
     return trackStep(authoredSteps, llmOp);
   }
 
+  /**
+   * `f.run` (docs/SURFACE.md §1). Declared as overloads like `llmOperation`,
+   * because the exit-code policy decides the RESULT TYPE: the default keeps
+   * the stdout string every body is written against, and `'record'` widens it
+   * to the `RunResult` whose `ok` is the journaled exit code.
+   */
+  function runOperation(command: string, options?: RunOptions & { onNonZero?: 'fail' }): Step<string>;
+  function runOperation(command: string, options: RunOptions & { onNonZero: 'record' }): Step<RunResult>;
+  function runOperation(command: string, options: RunOptions): Step<string | RunResult>;
+  function runOperation(command: string, runOptions?: RunOptions): Step<string> | Step<RunResult> {
+    assertOperationAllowed('run', definition.name, requestedCompletion);
+    const leaseMs = runOptions?.timeout === undefined ? undefined : parseStepTimeout(runOptions.timeout);
+    // Refused before an ordinal is consumed or anything is journaled. A
+    // misspelled policy must not quietly fall back to the fatal default and
+    // take away the very branch the author wrote below this line.
+    const policy = runOptions?.onNonZero;
+    if (policy !== undefined && policy !== 'fail' && policy !== 'record') {
+      throw new AuthoredFlowExecutionError(
+        'unsupported_verb',
+        `f.run options.onNonZero must be 'fail' or 'record' (got ${JSON.stringify(policy)}).`,
+      );
+    }
+    const id = `run-${nextStep++}`;
+    if (policy === 'record') {
+      let recordOp!: AuthoredFlowOperation<RunResult>;
+      recordOp = new AuthoredFlowOperation<RunResult>(
+        id, 'run',
+        () => assertOperationAllowed('run', definition.name, requestedCompletion),
+        () => observeStep(id, 'deterministic',
+          () => lowerDeterministic.recording(id, command, leaseMs, recordOp.namedGate), options.onProgress),
+        lifecycle,
+        // No label: a command is not a display name. It carries literal
+        // tokens and URLs, and no prefix of it is safe to show (displayLabel).
+        {},
+      );
+      return trackStep(authoredSteps, recordOp);
+    }
+    let runOp!: AuthoredFlowOperation<string>;
+    runOp = new AuthoredFlowOperation<string>(
+      id, 'run',
+      () => assertOperationAllowed('run', definition.name, requestedCompletion),
+      () => observeStep(id, 'deterministic', () => lowerDeterministic(id, command, false, leaseMs, runOp.namedGate), options.onProgress),
+      lifecycle,
+      // No label: a command is not a display name. It carries literal
+      // tokens and URLs, and no prefix of it is safe to show (displayLabel).
+      {},
+    );
+    return trackStep(authoredSteps, runOp);
+  }
+
   const slackRun = options.rootRunId ?? randomUUID();
   function slackOperation<T>(call: SlackCall): Step<T> {
     assertOperationAllowed(`slack.${call.verb}`, definition.name, requestedCompletion);
@@ -444,23 +510,7 @@ export async function executeAuthoredFlow<Input = undefined>(
       () => assertOperationAllowed('memory', definition.name, requestedCompletion),
       definition.header.memory?.script !== false,
     ),
-    run(command, runOptions) {
-      assertOperationAllowed('run', definition.name, requestedCompletion);
-      const leaseMs = runOptions?.timeout === undefined ? undefined : parseStepTimeout(runOptions.timeout);
-      const id = `run-${nextStep++}`;
-      let runOp!: AuthoredFlowOperation<string>;
-      runOp = new AuthoredFlowOperation<string>(
-        id,
-        'run',
-        () => assertOperationAllowed('run', definition.name, requestedCompletion),
-        () => observeStep(id, 'deterministic', () => lowerDeterministic(id, command, false, leaseMs, runOp.namedGate), options.onProgress),
-        lifecycle,
-        // No label: a command is not a display name. It carries literal
-        // tokens and URLs, and no prefix of it is safe to show (displayLabel).
-        {},
-      );
-      return trackStep(authoredSteps, runOp);
-    },
+    run: runOperation,
     llm: llmOperation,
     agent(name, options) {
       assertOperationAllowed('agent', definition.name, requestedCompletion);
@@ -562,7 +612,7 @@ export async function executeAuthoredFlow<Input = undefined>(
         displayLabel(typeof name === 'string' ? name : undefined),
       ));
     },
-    done(reason) {
+    done(reason, doneOptions) {
       if (!isSurfaceFlowCompletionReason(reason)) {
         throw new AuthoredFlowExecutionError(
           'unsupported_completion',
@@ -595,8 +645,13 @@ export async function executeAuthoredFlow<Input = undefined>(
           reason,
         );
       }
+      // Validated before the completion is marked, so a malformed `detail`
+      // leaves the flow exactly as any other refused `done()` does: not
+      // completed, and still able to report the real refusal.
+      const detail = normalizeCompletionDetail(doneOptions);
       lifecycle.markCompletion();
       requestedCompletion = reason;
+      requestedDetail = detail;
     },
     cloud: unsupportedCloud(
       () => assertOperationAllowed('cloud', definition.name, requestedCompletion),
@@ -670,12 +725,27 @@ export async function executeAuthoredFlow<Input = undefined>(
   // not as a fabricated kernel run.completed reason. The marker step reports
   // what the body decided; it is not itself a step that failed. The CLI turns
   // the verdict into the exit code (success/declined 0, needs_human 3, step_failed 1).
-  await lowerDeterministic(`complete-${nextStep}`,
-    completionMarker(requestedCompletion), true);
+  //
+  // The verdict is committed to the root BEFORE the marker run is opened, and
+  // a resumed body reuses what was committed rather than recomputing it
+  // (authored-completion-record.ts). A detail is redacted against
+  // `process.env`, so a credential rotated while this process was down would
+  // otherwise re-normalize the same authored sentence differently, retry the
+  // marker's stable admission key with a drifted spec, and lose the
+  // explanation the root had already journaled to `run_admission_conflict`.
+  // With no detail there is no environment in the command and nothing to
+  // commit, so that path is untouched.
+  const terminalId = `complete-${nextStep}`;
+  const verdict = await commitAuthoredVerdict(journal, options.rootRunId, terminalId, {
+    reason: requestedCompletion,
+    ...(requestedDetail === undefined ? {} : { detail: requestedDetail }),
+  });
+  await lowerDeterministic(terminalId, completionMarker(verdict.reason, verdict.detail), true);
   return Object.freeze({
     ...(options.rootRunId === undefined ? {} : { rootRunId: options.rootRunId }),
     name: definition.name,
-    completionReason: requestedCompletion,
+    completionReason: verdict.reason,
+    ...(verdict.detail === undefined ? {} : { completionDetail: verdict.detail }),
     journalSteps: Object.freeze([...journalSteps]),
   });
 }
@@ -695,43 +765,6 @@ function unsupportedVerb(verb: string): AuthoredFlowExecutionError {
   );
 }
 
-/**
- * The completion reasons an authored body may declare and this executor lowers.
- *
- * `FlowCompletionReason` is wider than this on purpose — it is the journal's
- * run vocabulary plus authored verdicts — but the two sets drifting silently is
- * exactly what made a type-valid `done("step_failed")` die at runtime as
- * `unsupported_completion`. Every gate that asks "is this a completion this
- * runtime can lower?" now asks this one function, so a reason cannot be
- * accepted in one place and rejected in another.
- *
- * These three are internal cross-module helpers for the authored seam (the
- * executor, the durable root, the IPC verifier and the CLI report), NOT public
- * SDK surface. `src/index.ts` deliberately re-exports nothing from this module
- * — keep it that way, or the whole authored seam leaks with them.
- */
-export const LOWERED_COMPLETIONS = ['success', 'needs_human', 'step_failed', 'declined'] as const;
-export type LoweredCompletionReason = (typeof LOWERED_COMPLETIONS)[number];
-
-export function isLoweredCompletion(value: unknown): value is LoweredCompletionReason {
-  return typeof value === 'string' && (LOWERED_COMPLETIONS as readonly string[]).includes(value);
-}
-
-/**
- * The deterministic command that carries an authored verdict into the journal.
- *
- * `success` lowers to `:` because success needs no marker: the marker run's own
- * kernel `success` already IS that record. Every other lowered verdict is
- * something the kernel's completion vocabulary cannot express on a step that
- * *succeeded*, so it travels as data on stdout and is read back from
- * `step.completed`. It is deliberately not lowered as a failing command: no
- * step failed here, and a fabricated failure would put bogus evidence in the
- * journal for a flow whose steps all ran correctly.
- */
-export function completionMarker(reason: LoweredCompletionReason): string {
-  return reason === 'success' ? ':' : `printf '%s' '{"completionReason":"${reason}"}'`;
-}
-
 function assertOperationAllowed(
   verb: string,
   flowName: string,

package/src/authored-human.ts

@@ -1,5 +1,6 @@
 import { AuthoredFlowExecutionError, type AuthoredHumanWait } from './authored-flow-error.js';
 import type { JournalClient } from './journal-client.js';
+import { shellWord } from './shell-word.js';
 
 /**
  * The answer contract for a parked `f.human`.
@@ -144,7 +145,3 @@ export function resumeCommand(runId: string, dataDir?: string, localAgent = fals
   const dir = dataDir === undefined ? '' : ` --data-dir ${shellWord(dataDir)}`;
   return `flows resume${dir}${localAgent ? ' --local-agent' : ''} ${runId}`;
 }
-
-function shellWord(value: string): string {
-  return /^[A-Za-z0-9_./=:@%+,-]+$/.test(value) ? value : `'${value.replaceAll("'", "'\\''")}'`;
-}

package/src/authored-node-entry.ts

@@ -88,9 +88,12 @@ try {
     // `details` is the failing child step's journal evidence. Without it the
     // parent can only re-render the message, and the machine-readable
     // diagnostic loses the command's exit code and output tails.
+    // `parkCause` travels for the same reason: it is the difference between
+    // "attach a worker" and "a human has to recover this", and this process is
+    // the only one that saw the child's classification.
     ...(error instanceof AuthoredFlowExecutionError ? { code: error.code,
       completionReason: error.completionReason, runId: error.runId,
-      details: error.details } : {}),
+      details: error.details, parkCause: error.parkCause } : {}),
     ...(error instanceof AuthoredHumanParked ? { wait: error.wait } : {}) });
   process.exitCode = 1;
 } finally {

package/src/authored-node-runner.ts

@@ -8,12 +8,14 @@ import { isAbsolute, join } from 'node:path';
 import type { Readable } from 'node:stream';
 import type { AuthoredRootMetadata } from './authored-root.js';
 import type { AuthoredExecutionRuntime, AuthoredFlowExecutionResult, ExecuteAuthoredFlowOptions } from './authored-flow-executor.js';
-import { completionMarker, isLoweredCompletion } from './authored-flow-executor.js';
+import { completionMarker, isDurableCompletionDetail, isLoweredCompletion } from './authored-completion.js';
 import {
   AuthoredFlowExecutionError, AuthoredHumanParked,
   type AuthoredFlowExecutionErrorCode, type AuthoredHumanWait,
 } from './authored-flow-error.js';
-import type { StepFailedDetails } from './failure-kinds.js';
+import type {
+  AttemptEvidenceComparison, ParkCause, StepAttemptFailure, StepFailedDetails,
+} from './failure-kinds.js';
 import { HUMAN_WAIT_ID } from './authored-human.js';
 import { assertAuthoredPromiseHooks } from './authored-runtime-capability.js';
 
@@ -137,13 +139,18 @@ export async function runAuthoredInNode(
             else if (message.type === 'wait') options.onWait?.(message.event);
             else if (message.type === 'result') result = { ...message.result, executionRuntime: runtime };
             else if (message.type === 'error') {
-              failure = message.code === 'human_parked' && isHumanWaitFrame(message.wait) && message.runId === rootRunId
-                ? new AuthoredHumanParked(message.wait, rootRunId)
-                : typeof message.code === 'string'
-                  ? new AuthoredFlowExecutionError(message.code as AuthoredFlowExecutionErrorCode,
-                    message.message, message.completionReason, message.runId,
-                    stepFailedFrame(message.details))
-                  : new Error(message.message);
+              if (message.code === 'human_parked' && isHumanWaitFrame(message.wait) && message.runId === rootRunId) {
+                failure = new AuthoredHumanParked(message.wait, rootRunId);
+              } else if (typeof message.code === 'string') {
+                const authored = new AuthoredFlowExecutionError(message.code as AuthoredFlowExecutionErrorCode,
+                  message.message, message.completionReason, message.runId,
+                  stepFailedFrame(message.details));
+                // Validated, not trusted, like `details`: an unrecognised cause
+                // is dropped so the boundary says nothing about workers rather
+                // than acting on a value this frame could have invented.
+                authored.parkCause = parkCauseFrame(message.parkCause);
+                failure = authored;
+              } else failure = new Error(message.message);
             } else throw new Error('unknown authored runtime message');
           } catch (error) { stop(error instanceof Error ? error : new Error('invalid authored runtime message')); }
         }
@@ -174,6 +181,17 @@ function isHumanWaitFrame(value: unknown): value is AuthoredHumanWait {
     && typeof wait.to === 'string' && wait.to !== '';
 }
 
+/**
+ * A park cause arriving over IPC, accepted only as one of the two values the
+ * type admits. Anything else — absent, misspelled, a different type — becomes
+ * `undefined`, which the remedy formatter reads as "unestablished" and answers
+ * with silence. Guessing `worker_unavailable` here would let a malformed frame
+ * put "attach a worker" on a park a worker cannot clear.
+ */
+export function parkCauseFrame(value: unknown): ParkCause | undefined {
+  return value === 'worker_unavailable' || value === 'needs_human' ? value : undefined;
+}
+
 /**
  * Step evidence arriving over IPC, reduced to the fields `StepFailedDetails`
  * declares and the types it declares them as. The child is the same pinned
@@ -184,26 +202,76 @@ function isHumanWaitFrame(value: unknown): value is AuthoredHumanWait {
  * evidence frame would replace the answer with a worse one.
  */
 export function stepFailedFrame(value: unknown): StepFailedDetails | undefined {
-  if (typeof value !== 'object' || value === null || Array.isArray(value)) return undefined;
-  const frame = value as Record<string, unknown>;
-  const text = (key: string): string | undefined =>
-    typeof frame[key] === 'string' ? (frame[key] as string).slice(0, 8192) : undefined;
-  const count = (key: string): number | undefined =>
-    typeof frame[key] === 'number' && Number.isSafeInteger(frame[key]) ? frame[key] as number : undefined;
+  const frame = frameRecord(value);
+  if (frame === undefined) return undefined;
   const details: StepFailedDetails = {};
   for (const [key, parsed] of [
-    ['stepId', text('stepId')], ['stepType', text('stepType')],
-    ['completionReason', text('completionReason')], ['attempt', count('attempt')],
-    ['maxIterations', count('maxIterations')], ['exitCode', count('exitCode')],
-    ['stdoutTail', text('stdoutTail')], ['stderrTail', text('stderrTail')],
-    ['detail', text('detail')], ['transcriptPath', text('transcriptPath')],
-    ['hint', text('hint')], ['journalPath', text('journalPath')],
+    ['stepId', frameText(frame, 'stepId')], ['stepType', frameText(frame, 'stepType')],
+    ['completionReason', frameText(frame, 'completionReason')], ['attempt', frameCount(frame, 'attempt')],
+    ['maxIterations', frameCount(frame, 'maxIterations')], ['exitCode', frameCount(frame, 'exitCode')],
+    ['stdoutTail', frameText(frame, 'stdoutTail')], ['stderrTail', frameText(frame, 'stderrTail')],
+    ['detail', frameText(frame, 'detail')], ['transcriptPath', frameText(frame, 'transcriptPath')],
+    ['attempts', attemptFrames(frame['attempts'])],
+    ['attemptEvidence', comparisonFrame(frame['attemptEvidence'])],
+    ['hint', frameText(frame, 'hint')], ['journalPath', frameText(frame, 'journalPath')],
   ] as const) {
     if (parsed !== undefined) (details as Record<string, unknown>)[key] = parsed;
   }
   return Object.keys(details).length === 0 ? undefined : details;
 }
 
+/**
+ * The attempt history, reduced element by element on the same terms as the
+ * frame that carries it. An element that is not an object contributes nothing
+ * rather than voiding the whole history: a report naming three of four
+ * attempts is still the first attempt's error, which is the fact the terminal
+ * scalars cannot supply.
+ */
+function attemptFrames(value: unknown): StepAttemptFailure[] | undefined {
+  if (!Array.isArray(value)) return undefined;
+  const attempts: StepAttemptFailure[] = [];
+  for (const element of value) {
+    const source = frameRecord(element);
+    if (source === undefined) continue;
+    const attempt: StepAttemptFailure = {};
+    for (const [key, parsed] of [
+      ['attempt', frameCount(source, 'attempt')],
+      ['completionReason', frameText(source, 'completionReason')],
+      ['disposition', frameText(source, 'disposition')],
+      ['exitCode', frameCount(source, 'exitCode')],
+      ['stdoutTail', frameText(source, 'stdoutTail')],
+      ['stderrTail', frameText(source, 'stderrTail')],
+      ['detail', frameText(source, 'detail')],
+      // Only a literal `true` claims truncation; anything else leaves the
+      // excerpt unlabelled rather than labelling a complete one as cut.
+      ['truncated', source['truncated'] === true ? true : undefined],
+    ] as const) {
+      if (parsed !== undefined) (attempt as Record<string, unknown>)[key] = parsed;
+    }
+    if (Object.keys(attempt).length > 0) attempts.push(attempt);
+  }
+  return attempts.length === 0 ? undefined : attempts;
+}
+
+/** An unrecognised verdict is dropped, and rendering then says `unknown`. */
+function comparisonFrame(value: unknown): AttemptEvidenceComparison | undefined {
+  return value === 'differs' || value === 'unchanged' || value === 'unknown' ? value : undefined;
+}
+
+function frameRecord(value: unknown): Record<string, unknown> | undefined {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? value as Record<string, unknown> : undefined;
+}
+
+function frameText(frame: Record<string, unknown>, key: string): string | undefined {
+  return typeof frame[key] === 'string' ? (frame[key] as string).slice(0, 8192) : undefined;
+}
+
+function frameCount(frame: Record<string, unknown>, key: string): number | undefined {
+  return typeof frame[key] === 'number' && Number.isSafeInteger(frame[key])
+    ? frame[key] as number : undefined;
+}
+
 /** The IPC frame is a claim, not a durable terminal fact or a sandbox boundary. */
 export async function verifyAuthoredNodeResult(
   result: AuthoredFlowExecutionResult, metadata: AuthoredRootMetadata,
@@ -212,6 +280,9 @@ export async function verifyAuthoredNodeResult(
   const invalid = (why = ''): never => { throw new Error(`authored runtime result has no matching durable completion${process.env['FLOWS_VERIFIER_DEBUG'] && why ? ` (${why})` : ''}`); };
   if (result.rootRunId !== rootRunId || result.name !== metadata.flowName
     || !isLoweredCompletion(result.completionReason)
+    // Type- and bound-check the claimed detail here, so the marker comparison
+    // below compares two values this process would itself have produced.
+    || (result.completionDetail !== undefined && !isDurableCompletionDetail(result.completionDetail))
     || !Array.isArray(result.journalSteps) || result.journalSteps.length === 0) invalid('frame');
   const terminal = result.journalSteps.at(-1)!;
   if (!terminal || !/^complete-[1-9][0-9]*$/.test(terminal.id)) invalid('terminal');
@@ -288,8 +359,11 @@ export async function verifyAuthoredNodeResult(
         // rejected a frame whose reason is not lowerable at all — that one is
         // the runtime validation of untrusted IPC, and it is why nothing has
         // to be re-asserted here just to satisfy the type.
+        // The detail is inside the marker, so this one comparison also
+        // attests it: a frame cannot claim a detail the journal does not
+        // hold, drop one it does, or alter a character of it.
         if (step?.type !== 'deterministic'
-          || step.command !== completionMarker(result.completionReason)) invalid('marker');
+          || step.command !== completionMarker(result.completionReason, result.completionDetail)) invalid('marker');
       }
     }
   } finally { journal.close(); }