@relayflows/sdk 2.0.29 → 2.0.31

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(); }

package/src/authored-root.ts

@@ -4,7 +4,9 @@ import { createHash, randomUUID } from 'node:crypto';
 import { readFile } from 'node:fs/promises';
 import { canonicalize } from './canonical.js';
 import { compileSpec, toKernelSpec } from './compile.js';
-import { executeAuthoredFlow, isLoweredCompletion, type AuthoredFlowExecutionResult } from './authored-flow-executor.js';
+import { executeAuthoredFlow, type AuthoredFlowExecutionResult } from './authored-flow-executor.js';
+import { isDurableCompletionDetail, isLoweredCompletion } from './authored-completion.js';
+import { AUTHORED_ROOT_KIND } from './authored-verdict.js';
 import {
   loadAuthoredFlow,
   type LoadedAuthoredFlow,
@@ -19,7 +21,12 @@ import { AuthoredFlowExecutionError, AuthoredHumanParked } from './authored-flow
 import { readOpenHumanWaits } from './authored-human.js';
 import { isSurfaceCompletionReason } from './authored-step-output.js';
 
-const ROOT_KIND = 'relayflows.authored-root.v1';
+/**
+ * Taken from the projection module rather than spelled twice: `flows status`
+ * has to recognise the same root this file writes, and it must not import the
+ * executor to do it.
+ */
+const ROOT_KIND = AUTHORED_ROOT_KIND;
 
 export interface AuthoredRootExtension {
   readonly name: string;
@@ -104,6 +111,7 @@ export async function executeDurableAuthoredFlow(
       return await completedRootResult(journal, outcome.run_id);
     }
     assertRootCanDispatch(outcome);
+    options.lifecycle?.onRunStarted?.({ runId: outcome.run_id, flow: definition.name });
     // `run.start` is an idempotent receipt. If the first caller died after
     // the daemon dispatched this root, a same-daemon retry sees the existing
     // active run but receives no second dispatch from start itself. Resume is
@@ -150,6 +158,7 @@ export async function resumeDurableAuthoredFlow(
     }
     assertRootCanDispatch(outcome);
     await assertNoOpenHumanWait(journal, outcome);
+    options.lifecycle?.onRunStarted?.({ runId: rootRunId, flow: metadata.flowName, resumed: true });
     const dispatch = await dispatchWait.promise;
     return await driveRoot(loaded, metadata, journal, peer, dispatch, options);
   } finally {
@@ -230,6 +239,7 @@ async function driveRoot(
       dispatch.run_id, dispatch.step_id, dispatch.attempt,
       dispatch.idempotency_key, 'success', {
         output: { name: result.name, completionReason: result.completionReason,
+          ...(result.completionDetail === undefined ? {} : { completionDetail: result.completionDetail }),
           journalSteps: result.journalSteps,
           ...(result.executionRuntime === undefined ? {} : { executionRuntime: result.executionRuntime }) },
         started_pins: dispatch.pins, end_pins: dispatch.pins,
@@ -372,9 +382,13 @@ async function completedRootResult(
   if (!isCompletedRootOutput(output)) {
     throw new Error('completed authored root has no durable result');
   }
+  // The stored detail, never a freshly computed one: redaction reads the
+  // CURRENT environment, so recomputing here would let a completed run report
+  // something its journal does not hold.
   return Object.freeze({
     name: output.name,
     completionReason: output.completionReason,
+    ...(output.completionDetail === undefined ? {} : { completionDetail: output.completionDetail }),
     journalSteps: Object.freeze(output.journalSteps.map(step => Object.freeze({ ...step }))),
     rootRunId,
   });
@@ -385,6 +399,10 @@ function isCompletedRootOutput(value: unknown): value is Omit<AuthoredFlowExecut
   const output = value as Partial<AuthoredFlowExecutionResult>;
   return typeof output.name === 'string'
     && isLoweredCompletion(output.completionReason)
+    // A malformed detail fails the whole readback rather than being dropped:
+    // silently discarding it would report the verdict without the evidence
+    // the journal says it was recorded with.
+    && (output.completionDetail === undefined || isDurableCompletionDetail(output.completionDetail))
     && Array.isArray(output.journalSteps)
     && output.journalSteps.every(step => typeof step === 'object' && step !== null
       && typeof step.id === 'string' && typeof step.runId === 'string'

package/src/authored-step-output.ts

@@ -22,19 +22,23 @@ export interface AuthoredStepContext {
 }
 
 /**
- * Shared by every `f.*` verb that lowers to one kernel step run in isolation:
- * find its `step.completed` entry, record it, and refuse anything but a
+ * Shared by every `f.*` verb that lowers to its own kernel run: find the
+ * operation's `step.completed` entry, record it, and refuse anything but a
  * clean success before handing the raw `output` back for verb-specific
  * extraction (a plain string for `f.run`, an `AgentResult` for `f.agent`).
  *
- * Callers are responsible for having already established that the RUN
- * reached a terminal, successful state before calling this — `f.run`'s
- * caller relies on `runStart`'s own immediate response (the kernel drives a
- * deterministic step to completion inline, no race); `f.agent`'s caller
- * relies on `classifyOutcome` (cli/run.ts) having already polled to a true
- * terminal state. Given that, a single read from the start of this run's
- * (small, single-step) journal is enough — no polling here, and no run
- * outcome ever needs re-checking.
+ * Callers are responsible for having already waited for the run to reach a
+ * terminal state — `f.run`'s caller relies on `runStart`'s own immediate
+ * response (the kernel drives a deterministic step to completion inline, no
+ * race); `f.agent`'s caller relies on `classifyOutcome` (cli/run.ts) having
+ * already polled to one. Given that, a single read from the start of this
+ * run's small journal is enough, and no polling happens here.
+ *
+ * What is NOT delegated to the caller is the run's verdict. A child spec has
+ * more than one step whenever the author declared a `.gate()`, and that gate
+ * step runs after the producer, so the producer's own `success` is not the
+ * run's. Both are checked here, and the run-level check is what makes a failed
+ * gate reject the authored operation.
  *
  * A non-success completion used to throw `journal step "run-1" completed with
  * retries_exhausted` and stop there, discarding the evidence it was holding:
@@ -63,26 +67,19 @@ export async function readCompletedStepOutput(
   const edges = context.stepEdges?.(stepId);
   journalSteps.push(Object.freeze({ id: stepId, runId, completionReason: reason, ...edges }));
   if (reason !== 'success') {
-    let message = `journal step "${stepId}" completed with ${reason}`;
-    let details: StepFailedDetails | undefined;
-    try {
-      details = await stepFailureDetails(journal, runId);
-    } catch (error) {
-      // Inspection must not erase the already known step failure; the two
-      // failures stay separately visible, as in classifyOutcome.
-      message += ` Could not inspect the failed step: ${errorMessage(error)}`;
-    }
-    if (details !== undefined) message += renderStepEvidence(details);
-    // Appended whatever inspection found — including nothing. A failure shape
-    // this reader does not recognise must still end with somewhere to go.
-    const where = inspectionHint(runId, details?.stepId ?? stepId, context.dataDir);
-    message += renderInspection(where);
-    message += await alsoRecord(journal, context.rootRunId, {
-      step: stepId, runId, state: 'completed', completionReason: reason,
-      ...(details?.stepId === undefined ? {} : { kernelStep: details.stepId }),
-      ...edges,
-    });
-    throw new AuthoredFlowExecutionError('step_failed', message, reason, runId, { ...details, ...where });
+    throw await stepFailure(journal, runId, stepId, reason, context, edges,
+      `journal step "${stepId}" completed with ${reason}`);
+  }
+  // An authored operation does not always lower to ONE kernel step. A declared
+  // `.gate()` becomes its own barrier step that runs AFTER the producer
+  // (`lowerNamedGates`), so the producer's own success is not the run's
+  // verdict. Reading only the producer's entry let a failed gate resolve as
+  // though the command had passed — the `|| true` invisibility this module's
+  // recording policy exists to remove, reappearing one layer up.
+  const runReason = entries.map(runCompletionReason).find((value) => value !== undefined);
+  if (runReason !== undefined && runReason !== 'success') {
+    throw await stepFailure(journal, runId, stepId, runReason, context, edges,
+      `journal run for step "${stepId}" completed with ${runReason}`);
   }
   await recordAuthoredChild(journal, context.rootRunId, {
     step: stepId, runId, state: 'completed', completionReason: reason, ...edges,
@@ -90,6 +87,42 @@ export async function readCompletedStepOutput(
   return completed.payload.output;
 }
 
+/**
+ * The one `step_failed` grammar both the step-level and the run-level refusal
+ * report through: inspect the journal for the step that actually failed, render
+ * its evidence, name where to look, and index the child before throwing.
+ */
+async function stepFailure(
+  journal: JournalClient,
+  runId: string,
+  stepId: string,
+  reason: ProtocolCompletionReason | ProtocolRunCompletionReason,
+  context: AuthoredStepContext,
+  edges: ReturnType<NonNullable<AuthoredStepContext['stepEdges']>>,
+  header: string,
+): Promise<AuthoredFlowExecutionError> {
+  let message = header;
+  let details: StepFailedDetails | undefined;
+  try {
+    details = await stepFailureDetails(journal, runId);
+  } catch (error) {
+    // Inspection must not erase the already known step failure; the two
+    // failures stay separately visible, as in classifyOutcome.
+    message += ` Could not inspect the failed step: ${errorMessage(error)}`;
+  }
+  if (details !== undefined) message += renderStepEvidence(details);
+  // Appended whatever inspection found — including nothing. A failure shape
+  // this reader does not recognise must still end with somewhere to go.
+  const where = inspectionHint(runId, details?.stepId ?? stepId, context.dataDir);
+  message += renderInspection(where);
+  message += await alsoRecord(journal, context.rootRunId, {
+    step: stepId, runId, state: 'completed', completionReason: reason,
+    ...(details?.stepId === undefined ? {} : { kernelStep: details.stepId }),
+    ...edges,
+  });
+  return new AuthoredFlowExecutionError('step_failed', message, reason, runId, { ...details, ...where });
+}
+
 export async function readSuccessfulOutput(
   journal: JournalClient,
   outcome: RunOutcome,
@@ -98,24 +131,74 @@ export async function readSuccessfulOutput(
   context: AuthoredStepContext = {},
 ): Promise<string> {
   const output = await readCompletedStepOutput(journal, outcome.run_id, stepId, journalSteps, context)
-    .catch(error => {
-      if (error instanceof AuthoredFlowExecutionError
-        && (error.completionReason === 'timeout' || error.completionReason === 'lease_expired')) {
-        // A timeout is still a failed command, and the evidence extracted for
-        // it is the same evidence. Re-labelling the error must not delete it.
-        throw new AuthoredFlowExecutionError('lease_exceeded',
-          `f.run step "${stepId}" exceeded its command timeout.`
-            + ` ${error.message.slice(`${error.code}: `.length)}`,
-          error.completionReason, error.runId, error.details);
-      }
-      throw error;
-    });
+    .catch(relabelCommandTimeout(stepId));
   if (!isRecord(output) || typeof output['stdout_tail'] !== 'string') {
     throw protocolViolation(outcome.run_id, `step "${stepId}" has no string stdout_tail`);
   }
   return output['stdout_tail'];
 }
 
+/** What `f.run` resolves to under `onNonZero: 'record'` (surface `RunResult`). */
+export interface RecordedRunOutcome {
+  ok: boolean;
+  exitCode: number;
+  output: string;
+  stdout: string;
+  stderr: string;
+}
+
+/**
+ * The read side of `onNonZero: 'record'`.
+ *
+ * A recorded red exit is a SUCCESSFUL step, so this takes the same path as
+ * `readSuccessfulOutput` and every field comes from the journaled envelope —
+ * nothing is re-run and nothing is re-measured. What still throws is what the
+ * policy never covered: a timeout, a signal, a step that never ran, or a
+ * declared content or schema gate that failed. The `-1` the executor writes
+ * for "no exit status" is refused rather than handed back as a plausible
+ * code, mirroring the kernel's own rule, so a malformed envelope can never
+ * reach an author's `if (!result.ok)` as a real verdict.
+ */
+export async function readRecordedOutcome(
+  journal: JournalClient,
+  outcome: RunOutcome,
+  stepId: string,
+  journalSteps: AuthoredFlowJournalStep[],
+  context: AuthoredStepContext = {},
+): Promise<RecordedRunOutcome> {
+  const envelope = await readCompletedStepOutput(journal, outcome.run_id, stepId, journalSteps, context)
+    .catch(relabelCommandTimeout(stepId));
+  const exitCode = isRecord(envelope) ? envelope['exit_code'] : undefined;
+  if (!isRecord(envelope) || typeof envelope['stdout_tail'] !== 'string'
+    || typeof envelope['stderr_tail'] !== 'string'
+    || typeof exitCode !== 'number' || !Number.isInteger(exitCode) || exitCode < 0) {
+    throw protocolViolation(outcome.run_id,
+      `step "${stepId}" recorded no {exit_code, stdout_tail, stderr_tail} to report`);
+  }
+  const stdout = envelope['stdout_tail'];
+  const stderr = envelope['stderr_tail'];
+  return {
+    ok: exitCode === 0, exitCode, stdout, stderr,
+    // Concatenated, not interleaved: the two tails were captured separately,
+    // so joining them is a reading convenience and is documented as one.
+    output: stdout !== '' && stderr !== '' ? `${stdout}\n${stderr}` : stdout + stderr,
+  };
+}
+
+/** A timeout is still a failed command; re-labelling it must not delete its evidence. */
+function relabelCommandTimeout(stepId: string): (error: unknown) => never {
+  return (error) => {
+    if (error instanceof AuthoredFlowExecutionError
+      && (error.completionReason === 'timeout' || error.completionReason === 'lease_expired')) {
+      throw new AuthoredFlowExecutionError('lease_exceeded',
+        `f.run step "${stepId}" exceeded its command timeout.`
+          + ` ${error.message.slice(`${error.code}: `.length)}`,
+        error.completionReason, error.runId, error.details);
+    }
+    throw error;
+  };
+}
+
 interface StepCompletedEntry {
   entry_type: 'step.completed';
   step_id: string;
@@ -135,6 +218,20 @@ function isStepCompleted(value: unknown, stepId: string): value is StepCompleted
     && 'output' in payload;
 }
 
+/**
+ * The run's own terminal reason, when this entry is the one carrying it.
+ *
+ * Anything else — including a `run.completed` whose payload this reader does
+ * not recognise — yields `undefined` and leaves the step-level verdict
+ * untouched, so an unfamiliar journal shape cannot invent a failure.
+ */
+function runCompletionReason(entry: unknown): ProtocolRunCompletionReason | undefined {
+  if (!isRecord(entry) || entry['entry_type'] !== 'run.completed') return undefined;
+  const payload = entry['payload'];
+  const reason = isRecord(payload) ? payload['completionReason'] : undefined;
+  return isSurfaceRunCompletionReason(reason) ? reason : undefined;
+}
+
 export function isSurfaceCompletionReason(value: unknown): value is ProtocolCompletionReason {
   return typeof value === 'string'
     && (COMPLETION_REASONS as readonly string[]).includes(value);

package/src/authored-verdict.ts

@@ -0,0 +1,87 @@
+// Project an authored flow's own verdict out of its root journal.
+//
+// `foldRunState` answers what the KERNEL recorded: the root step succeeded, so
+// the run completed with `success`. That is true and must stay printed. It is
+// also not what a reader asking "why did this fail?" needs when the body
+// declared `step_failed` — a verdict the kernel's vocabulary cannot express on
+// a step that succeeded, so it travels as output on the root's own
+// `step.completed`.
+//
+// This is a separate, narrow projection rather than a branch inside the fold:
+// the fold is generic over every run and has no business knowing what an
+// authored root is, and the executor this vocabulary comes from must not
+// become a dependency of `flows status`.
+
+import {
+  isDurableCompletionDetail,
+  isLoweredCompletion,
+  type LoweredCompletionReason,
+} from './authored-completion.js';
+import type { JournalEvent } from './journal-reader.js';
+
+/** The `instruction` discriminator `authored-root.ts` writes into the root step. */
+export const AUTHORED_ROOT_KIND = 'relayflows.authored-root.v1';
+
+export interface AuthoredVerdict {
+  readonly reason: LoweredCompletionReason;
+  /** Absent when the body called `done()` with one argument, as most do. */
+  readonly detail?: string;
+}
+
+/**
+ * The verdict an authored root attested, or `null` when this journal holds none.
+ *
+ * `null` is the answer for an ordinary run, for an authored run still in
+ * flight, and for one whose root output is malformed. The last of those
+ * matters: an ordinary flow may name a step `authored-root`, and a worker may
+ * journal anything into a step's output, so the step id alone attests nothing.
+ * A verdict is reported only when the run's own spec declares the authored
+ * root — carrying {@link AUTHORED_ROOT_KIND} metadata — and the root's last
+ * `step.completed` is a terminal kernel `success` whose output is a complete,
+ * in-bounds authored result. A retry or park completion is not terminal and a
+ * later attempt may still change the answer, so neither is promoted.
+ *
+ * This is a projection for a read-only view, so a malformed record yields no
+ * verdict rather than an error: refusing to render a whole status because one
+ * output field is the wrong type would replace the answer with a worse one.
+ */
+export function authoredVerdictOf(events: readonly JournalEvent[]): AuthoredVerdict | null {
+  const spawned = events[0];
+  if (spawned === undefined || spawned.entry_type !== 'run.spawned') return null;
+  if (!declaresAuthoredRoot(spawned)) return null;
+
+  const completed = [...events].reverse().find((event) =>
+    event.entry_type === 'step.completed' && event.step_id === 'authored-root');
+  const payload = record(completed?.payload);
+  if (payload === null || payload['completionReason'] !== 'success') return null;
+  const disposition = payload['disposition'];
+  if (disposition !== undefined && disposition !== 'step_done') return null;
+
+  const output = record(payload['output']);
+  if (output === null || typeof output['name'] !== 'string') return null;
+  const reason = output['completionReason'];
+  if (!isLoweredCompletion(reason)) return null;
+  const detail = output['completionDetail'];
+  if (detail !== undefined && !isDurableCompletionDetail(detail)) return null;
+
+  return Object.freeze({ reason, ...(detail === undefined ? {} : { detail }) });
+}
+
+function declaresAuthoredRoot(spawned: JournalEvent): boolean {
+  const spec = record(record(spawned.payload)?.['spec']);
+  const steps = spec?.['steps'];
+  if (!Array.isArray(steps)) return false;
+  const step = record(steps[0]);
+  if (step === null || step['id'] !== 'authored-root') return false;
+  if (typeof step['instruction'] !== 'string') return false;
+  try {
+    return record(JSON.parse(step['instruction']))?.['kind'] === AUTHORED_ROOT_KIND;
+  } catch {
+    return false;
+  }
+}
+
+function record(value: unknown): Record<string, unknown> | null {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+    ? value as Record<string, unknown> : null;
+}