@relayflows/sdk 2.0.21 → 2.0.23

package/src/authored-flow-executor.ts

@@ -206,7 +206,10 @@ export async function executeAuthoredFlow<Input = undefined>(
   let requestedCompletion: LoweredCompletionReason | undefined;
 
   const lowerDeterministic = authoredDeterministicRunner(
-    definition.name, journal, journalSteps, budget, options.rootRunId,
+    definition.name, journal, journalSteps, budget, {
+      ...(options.rootRunId === undefined ? {} : { rootRunId: options.rootRunId }),
+      ...(options.dataDir === undefined ? {} : { dataDir: options.dataDir }),
+    },
   );
 
   const worker = authoredWorkerRunner(

package/src/authored-node-entry.ts

@@ -81,8 +81,12 @@ try {
   const message = error instanceof Error ? error.message : 'authored body failed';
   const prefix = error instanceof AuthoredFlowExecutionError ? `${error.code}: ` : '';
   send({ type: 'error', message: prefix && message.startsWith(prefix) ? message.slice(prefix.length) : message,
+    // `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.
     ...(error instanceof AuthoredFlowExecutionError ? { code: error.code,
-      completionReason: error.completionReason, runId: error.runId } : {}),
+      completionReason: error.completionReason, runId: error.runId,
+      details: error.details } : {}),
     ...(error instanceof AuthoredHumanParked ? { wait: error.wait } : {}) });
   process.exitCode = 1;
 } finally {

package/src/authored-node-runner.ts

@@ -13,6 +13,7 @@ import {
   AuthoredFlowExecutionError, AuthoredHumanParked,
   type AuthoredFlowExecutionErrorCode, type AuthoredHumanWait,
 } from './authored-flow-error.js';
+import type { StepFailedDetails } from './failure-kinds.js';
 import { HUMAN_WAIT_ID } from './authored-human.js';
 import { assertAuthoredPromiseHooks } from './authored-runtime-capability.js';
 
@@ -139,7 +140,8 @@ export async function runAuthoredInNode(
                 ? new AuthoredHumanParked(message.wait, rootRunId)
                 : typeof message.code === 'string'
                   ? new AuthoredFlowExecutionError(message.code as AuthoredFlowExecutionErrorCode,
-                    message.message, message.completionReason, message.runId)
+                    message.message, message.completionReason, message.runId,
+                    stepFailedFrame(message.details))
                   : 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')); }
@@ -171,6 +173,36 @@ function isHumanWaitFrame(value: unknown): value is AuthoredHumanWait {
     && typeof wait.to === 'string' && wait.to !== '';
 }
 
+/**
+ * Step evidence arriving over IPC, reduced to the fields `StepFailedDetails`
+ * declares and the types it declares them as. The child is the same pinned
+ * payload the parent hashed, but the frame is still a claim: an unrecognised
+ * or mistyped field is dropped rather than trusted, and a malformed `details`
+ * yields no details at all. It throws on nothing `JSON.parse` can produce —
+ * the run is already failing, and losing the original failure to report a bad
+ * 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 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')],
+  ] as const) {
+    if (parsed !== undefined) (details as Record<string, unknown>)[key] = parsed;
+  }
+  return Object.keys(details).length === 0 ? undefined : details;
+}
+
 /** The IPC frame is a claim, not a durable terminal fact or a sandbox boundary. */
 export async function verifyAuthoredNodeResult(
   result: AuthoredFlowExecutionResult, metadata: AuthoredRootMetadata,

package/src/authored-root.ts

@@ -15,7 +15,7 @@ import type { RunOutcome, StepDispatchEvent } from './protocol.js';
 import { SPEC_SCHEMA_VERSION } from './spec.js';
 import type { RunLifecycleOptions } from './cli/run.js';
 import { withWorkerLease } from './worker-lease.js';
-import { AuthoredHumanParked } from './authored-flow-error.js';
+import { AuthoredFlowExecutionError, AuthoredHumanParked } from './authored-flow-error.js';
 import { readOpenHumanWaits } from './authored-human.js';
 import { isSurfaceCompletionReason } from './authored-step-output.js';
 
@@ -234,6 +234,7 @@ async function driveRoot(
       throw error;
     }
     await terminalizeRootFailure(peer, dispatch, error);
+    if (error instanceof AuthoredFlowExecutionError) error.rootRunId = dispatch.run_id;
     throw error;
   }
 }

package/src/authored-source-authority.ts

@@ -46,7 +46,20 @@ function installPinnedSourceLoader(sources: Map<string, string>): void {
   pinnedSourceLoaderInstalled = true;
   // Node >=22.14 supports register and stripTypeScriptTypes. A loader thread
   // receives the captured bytes, never reopening mutable authored paths.
+  // The `stripTypeScriptTypes` call below makes Node emit
+  // `ExperimentalWarning: stripTypeScriptTypes …` on the child's inherited
+  // stderr, where a bootstrap that reads the CLI's stderr takes it for the
+  // error text. It is emitted on this loader thread, so a listener on the
+  // main thread cannot intercept it, and `--disable-warning` on the child
+  // would silence every ExperimentalWarning the authored body raises too.
+  // Dropping it by its own text, on this thread only, is the narrow form:
+  // Node's own printer still handles every other warning.
   const loader = `
+    const emitWarning = process.emitWarning.bind(process);
+    process.emitWarning = (warning, ...rest) => {
+      if (rest[0] === 'ExperimentalWarning' && String(warning).startsWith('stripTypeScriptTypes')) return;
+      emitWarning(warning, ...rest);
+    };
     import {stripTypeScriptTypes} from 'node:module';
     let sources;
     export function initialize(data){sources=new Map(data);}

package/src/authored-step-index.ts

@@ -0,0 +1,157 @@
+import type { JournalClient } from './journal-client.js';
+
+/**
+ * The root run's durable index of the child runs an authored body opened.
+ *
+ * An authored flow is not one kernel run: every `f.run`, `f.agent`, `f.llm`
+ * and lowered gate is its own single-step child run with its own
+ * `<dataDir>/runs/<runId>.sqlite3`. The only thing that ties a child back to
+ * the root id a caller (or Cloud) knows is an index — and until now that index
+ * existed only in the root's SUCCESS completion output
+ * (`authored-root.ts` `driveRoot`). A failed body took
+ * `terminalizeRootFailure`, which journals `{ error }` and nothing else, so a
+ * failed run named no child at all. A failed run is exactly when its children
+ * are worth reading.
+ *
+ * The completion output could not be made to carry it either: the root is
+ * lowered as `type: 'agent'`, and the kernel nulls a failed agent's `output`
+ * (`preserve_failure_output`, relayflowd-core/src/machine.rs), preserving only
+ * a 2,000-character render in `verification.detail`. So the index is written
+ * where a failure cannot erase it — appended to a stream on the ROOT run as
+ * each child is opened, using the same `journal.streamAppend` durability the
+ * executor already relies on for predicate verdicts.
+ *
+ * Each record is bounded on its own rather than the index being truncated as
+ * one blob: a hundredth child must not push the first one out of the record.
+ */
+export const AUTHORED_STEP_STREAM = 'authored-steps';
+
+/** Versioned so a reader can tell this record from a future one. */
+const RECORD_KIND = 'relayflows.authored-step.v1';
+
+/**
+ * Per-field cap. Step ids and run ids are short by construction; the cap
+ * exists so a hostile or buggy id cannot make one record unbounded.
+ */
+const FIELD_CHARS = 256;
+
+/**
+ * `admitted` and `completed` are kept distinct on purpose. `admitted` says
+ * only "this child run exists and here is where to read it" — it never
+ * carries a `completionReason`, because manufacturing one for an attempt
+ * that has not completed would turn an unfinished child into a false fact.
+ * `completed` is written only from a terminal `step.completed` the journal
+ * actually holds.
+ */
+export interface AuthoredStepRecord {
+  readonly index: typeof RECORD_KIND;
+  readonly step: string;
+  readonly runId: string;
+  readonly state: 'admitted' | 'completed';
+  /** Present only on `completed`. */
+  readonly completionReason?: string;
+  /**
+   * The kernel step the completion came from, when it is not the authored
+   * operation's own id. A child spec has two steps once a named gate is
+   * lowered, so the terminal failure can be `<step>.verify` rather than
+   * `<step>` — saying which is the difference between an index and a guess.
+   */
+  readonly kernelStep?: string;
+}
+
+/**
+ * Append one record, or do nothing when there is no root to append to.
+ *
+ * The undefined-root case is the non-durable executor seam (`executeAuthoredFlow`
+ * called without `rootRunId`), which has no root run and therefore nothing to
+ * index. It is not a silent fallback: there is no durable place for the record
+ * to go, and the caller already knows it opted out of one.
+ *
+ * Append failures propagate (AGENTS.md rule 4). Callers on a path that is
+ * already failing must surface the persistence error ALONGSIDE the original
+ * failure rather than letting it replace it — see `alsoRecord`.
+ */
+export async function recordAuthoredChild(
+  journal: JournalClient,
+  rootRunId: string | undefined,
+  record: Omit<AuthoredStepRecord, 'index'>,
+): Promise<void> {
+  if (rootRunId === undefined) return;
+  await journal.streamAppend(rootRunId, AUTHORED_STEP_STREAM, {
+    index: RECORD_KIND,
+    step: bound(record.step),
+    runId: bound(record.runId),
+    state: record.state,
+    ...(record.completionReason === undefined ? {} : { completionReason: bound(record.completionReason) }),
+    ...(record.kernelStep === undefined || record.kernelStep === record.step
+      ? {} : { kernelStep: bound(record.kernelStep) }),
+  });
+}
+
+/**
+ * Record a child on a path that is already throwing, keeping both facts.
+ *
+ * A failed append must not be relabelled as successful collection, and it must
+ * not replace the failure the caller is about to report. It returns the note
+ * to append to that failure's message instead.
+ */
+export async function alsoRecord(
+  journal: JournalClient,
+  rootRunId: string | undefined,
+  record: Omit<AuthoredStepRecord, 'index'>,
+): Promise<string> {
+  try {
+    await recordAuthoredChild(journal, rootRunId, record);
+    return '';
+  } catch (error) {
+    return `\nCould not persist the step index: ${error instanceof Error ? error.message : String(error)}`;
+  }
+}
+
+/**
+ * Fold the root's stream back into one record per authored step.
+ *
+ * A `completed` record supersedes the `admitted` one for the same step; first
+ * admission order is preserved so the index reads in the order the body ran.
+ * Records this version does not recognise are skipped rather than trusted.
+ */
+export async function readAuthoredStepIndex(
+  journal: JournalClient,
+  rootRunId: string,
+): Promise<AuthoredStepRecord[]> {
+  const index = new Map<string, AuthoredStepRecord>();
+  let offset = 0;
+  for (;;) {
+    const page = await journal.streamRead(rootRunId, AUTHORED_STEP_STREAM, offset, 1000);
+    for (const message of page.messages) {
+      // `stream.read` returns either the envelope or the bare message,
+      // matching how the executor reads predicate verdicts.
+      const raw = (message as { message?: unknown }).message ?? message;
+      if (!isAuthoredStepRecord(raw)) continue;
+      const previous = index.get(raw.step);
+      // An `admitted` record arriving after a `completed` one (a resumed body
+      // re-admitting the same child under its stable admission key) must not
+      // un-complete it.
+      if (previous?.state === 'completed' && raw.state === 'admitted') continue;
+      index.set(raw.step, raw);
+    }
+    if (page.messages.length === 0 || page.next_offset <= offset) break;
+    offset = page.next_offset;
+  }
+  return [...index.values()];
+}
+
+function isAuthoredStepRecord(value: unknown): value is AuthoredStepRecord {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false;
+  const record = value as Partial<AuthoredStepRecord>;
+  return record.index === RECORD_KIND
+    && typeof record.step === 'string' && record.step.length > 0
+    && typeof record.runId === 'string' && record.runId.length > 0
+    && (record.state === 'admitted' || record.state === 'completed')
+    && (record.completionReason === undefined || typeof record.completionReason === 'string')
+    && (record.kernelStep === undefined || typeof record.kernelStep === 'string');
+}
+
+function bound(value: string): string {
+  return value.length <= FIELD_CHARS ? value : `${value.slice(0, FIELD_CHARS)}…`;
+}

package/src/authored-step-output.ts

@@ -3,6 +3,21 @@ import { AuthoredFlowExecutionError } from './authored-flow-error.js';
 import type { JournalClient } from './journal-client.js';
 import type { CompletionReason as ProtocolCompletionReason, RunCompletionReason as ProtocolRunCompletionReason, RunOutcome } from './protocol.js';
 import type { AuthoredFlowJournalStep } from './authored-flow-executor.js';
+import type { StepFailedDetails } from './failure-kinds.js';
+import { inspectionHint, renderInspection, renderStepEvidence, stepFailureDetails } from './cli/step-failure.js';
+import { alsoRecord, recordAuthoredChild } from './authored-step-index.js';
+
+/**
+ * What an authored operation needs in order to leave readable evidence:
+ * the root run its child index belongs to, and the data dir whose journals
+ * a reader would open. Both optional — the non-durable executor seam has no
+ * root, and a caller that did not name a data dir still gets the `flows
+ * replay <run-id>` hint, just without the on-disk path.
+ */
+export interface AuthoredStepContext {
+  readonly rootRunId?: string;
+  readonly dataDir?: string;
+}
 
 /**
  * Shared by every `f.*` verb that lowers to one kernel step run in isolation:
@@ -18,12 +33,23 @@ import type { AuthoredFlowJournalStep } from './authored-flow-executor.js';
  * 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.
+ *
+ * A non-success completion used to throw `journal step "run-1" completed with
+ * retries_exhausted` and stop there, discarding the evidence it was holding:
+ * the kernel PRESERVES a failed deterministic step's `output`
+ * (`preserve_failure_output`, relayflowd-core/src/machine.rs), so
+ * `{exit_code, stdout_tail, stderr_tail}` — the answer to "which command
+ * failed and what did it print" — was in hand and dropped. Four different
+ * causes produced that one identical line. It now reads the same extractor
+ * `f.agent`/`f.llm` already reach through `classifyOutcome`, so both step
+ * families report one grammar instead of two divergent ones.
  */
 export async function readCompletedStepOutput(
   journal: JournalClient,
   runId: string,
   stepId: string,
   journalSteps: AuthoredFlowJournalStep[],
+  context: AuthoredStepContext = {},
 ): Promise<unknown> {
   const entries = (await journal.journalRead(runId, 1)).entries;
   const completed = entries.find((entry) => isStepCompleted(entry, stepId));
@@ -34,13 +60,29 @@ export async function readCompletedStepOutput(
   const reason = completed.payload.completionReason;
   journalSteps.push(Object.freeze({ id: stepId, runId, completionReason: reason }));
   if (reason !== 'success') {
-    throw new AuthoredFlowExecutionError(
-      'step_failed',
-      `journal step "${stepId}" completed with ${reason}`,
-      reason,
-      runId,
-    );
+    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 }),
+    });
+    throw new AuthoredFlowExecutionError('step_failed', message, reason, runId, { ...details, ...where });
   }
+  await recordAuthoredChild(journal, context.rootRunId, {
+    step: stepId, runId, state: 'completed', completionReason: reason,
+  });
   return completed.payload.output;
 }
 
@@ -49,15 +91,21 @@ export async function readSuccessfulOutput(
   outcome: RunOutcome,
   stepId: string,
   journalSteps: AuthoredFlowJournalStep[],
+  context: AuthoredStepContext = {},
 ): Promise<string> {
-  const output = await readCompletedStepOutput(journal, outcome.run_id, stepId, journalSteps).catch(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.completionReason, error.runId);
-    }
-    throw error;
-  });
+  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;
+    });
   if (!isRecord(output) || typeof output['stdout_tail'] !== 'string') {
     throw protocolViolation(outcome.run_id, `step "${stepId}" has no string stdout_tail`);
   }
@@ -102,6 +150,10 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
 function protocolViolation(runId: string, detail: string): AuthoredFlowExecutionError {
   return new AuthoredFlowExecutionError(
     'journal_protocol_violation',

package/src/authored-worker-step.ts

@@ -3,15 +3,17 @@ import { parseBudget } from './budget.js';
 import type { AgentOptions, AgentResult, LlmOptions, NamedGate } from '@relayflows/surface';
 import { compileSpec, toKernelSpec } from './compile.js';
 import { checkAuthoredFlow } from './cli/check.js';
-import { classifyOutcome, type RunLifecycleOptions } from './cli/run.js';
+import { classifyOutcome, type RunLifecycleOptions, type RunReport } from './cli/run.js';
 import type { PreflightDiagnostic } from './preflight.js';
 import { AuthoredFlowExecutionError } from './authored-flow-error.js';
 import type { JournalClient } from './journal-client.js';
 import { SPEC_SCHEMA_VERSION, type FlowSpec, type PermissionsSpec, type StepSpec } from './spec.js';
-import { isSurfaceCompletionReason, readCompletedStepOutput, readSuccessfulOutput } from './authored-step-output.js';
+import { isSurfaceCompletionReason, readCompletedStepOutput, readSuccessfulOutput, type AuthoredStepContext } from './authored-step-output.js';
 import type { AuthoredFlowJournalStep } from './authored-flow-executor.js';
 import { snapshotJsonValue } from './json-value.js';
 import { authoredChildAdmissionKey } from './authored-admission.js';
+import { alsoRecord, recordAuthoredChild } from './authored-step-index.js';
+import type { StepFailedDetails } from './failure-kinds.js';
 
 const WORKSPACE_PERMISSION_ANNOTATION = /:\s*(readonly|readwrite)\s*$/i;
 
@@ -22,6 +24,10 @@ export function authoredWorkerRunner(
   localAgentStream?: string, budget?: AuthoredBudget, headerBudget?: unknown,
   rootRunId?: string,
 ) {
+  const context: AuthoredStepContext = {
+    ...(rootRunId === undefined ? {} : { rootRunId }),
+    ...(waitOptions.dataDir === undefined ? {} : { dataDir: waitOptions.dataDir }),
+  };
   async function run(step: StepSpec): Promise<unknown> {
     const id = step.id;
     const authoring: FlowSpec = { version: SPEC_SCHEMA_VERSION, name: `${definition.name}/${id}`, steps: [step], ...(headerBudget === undefined ? {} : { budget: parseBudget(headerBudget) }) };
@@ -46,6 +52,10 @@ export function authoredWorkerRunner(
     }
     const spec = toKernelSpec(resolved);
     const consume = async (outcome: import('./protocol.js').RunOutcome) => {
+    // Written BEFORE the wait, not after it. An agent runs for as long as its
+    // lease allows; if this process dies mid-step, this record is the only
+    // thing that still names the child run holding the evidence.
+    await recordAuthoredChild(journal, rootRunId, { step: id, runId: outcome.run_id, state: 'admitted' });
     // Reuse the declarative CLI's own wait/classification (cli/run.ts) rather
     // than a hand-rolled poll: `step.completed` and the run's own terminal
     // state are appended as two SEPARATE actions (kernel/relayflowd-core/src/machine.rs
@@ -69,17 +79,38 @@ export function authoredWorkerRunner(
       );
     }
     if (execution.exitCode !== 0) {
+      // `execution.report.completionReason` is the RUN's reason (normally
+      // `step_failed`), not the step's. The step's terminal facts are the
+      // ones `classifyOutcome` already extracted with `stepFailureDetails`
+      // and assigned onto this diagnostic — read them from there rather than
+      // re-walking the journal or mislabelling the run reason as a step one.
+      const diagnostic = execution.report.diagnostics.at(-1);
+      const details = stepDetails(diagnostic);
       const reason = execution.report.completionReason;
+      let message = diagnostic?.message
+        ?? `flow "${definition.name}" step "${id}" did not complete successfully `
+          + `(status: ${execution.report.status ?? 'unknown'})`;
+      // Only a reason the journal actually recorded for a step is indexed;
+      // an unfinished or unreadable child is left as `admitted`, never given
+      // a manufactured completion.
+      if (isSurfaceCompletionReason(details?.completionReason)) {
+        journalSteps.push(Object.freeze({
+          id, runId: outcome.run_id, completionReason: details.completionReason,
+        }));
+        message += await alsoRecord(journal, rootRunId, {
+          step: id, runId: outcome.run_id, state: 'completed',
+          completionReason: details.completionReason,
+          ...(details.stepId === undefined ? {} : { kernelStep: details.stepId }),
+        });
+      }
       throw new AuthoredFlowExecutionError(
-        'step_failed',
-        execution.report.diagnostics.at(-1)?.message
-          ?? `flow "${definition.name}" step "${id}" did not complete successfully `
-            + `(status: ${execution.report.status ?? 'unknown'})`,
+        'step_failed', message,
         isSurfaceCompletionReason(reason) ? reason : undefined,
         outcome.run_id,
+        details,
       );
     }
-    return readCompletedStepOutput(journal, outcome.run_id, id, journalSteps);
+    return readCompletedStepOutput(journal, outcome.run_id, id, journalSteps, context);
     };
     const admissionKey = authoredChildAdmissionKey(rootRunId, id);
     return budget === undefined
@@ -173,11 +204,19 @@ export function authoredWorkerRunner(
   };
 }
 
-/** Deterministic commands execute inline under their per-invocation lease. */
+/**
+ * Deterministic commands execute inline under their per-invocation lease.
+ *
+ * `context` carries the root run (so each child is indexed on it) and the
+ * data dir (so a failure can name the journal on disk). It is the same object
+ * the worker runner builds; a failed `f.run` and a failed `f.agent` now report
+ * through one grammar.
+ */
 export function authoredDeterministicRunner(
   name: string, journal: JournalClient, journalSteps: AuthoredFlowJournalStep[], budget: AuthoredBudget,
-  rootRunId?: string,
+  context: AuthoredStepContext = {},
 ) {
+  const rootRunId = context.rootRunId;
   return async (id: string, command: string, terminal = false, leaseMs?: number, verification?: NamedGate): Promise<string> => {
     const spec = toKernelSpec(compileSpec({
       version: SPEC_SCHEMA_VERSION,
@@ -189,11 +228,45 @@ export function authoredDeterministicRunner(
       }],
     }));
     const admissionKey = authoredChildAdmissionKey(rootRunId, id);
-    if (terminal) return readSuccessfulOutput(
-      journal, await journal.runStart(spec, undefined, admissionKey), id, journalSteps,
-    );
-    return budget.execute(
-      journal, spec, outcome => readSuccessfulOutput(journal, outcome, id, journalSteps), admissionKey,
-    );
+    const consume = async (outcome: import('./protocol.js').RunOutcome): Promise<string> => {
+      await recordAuthoredChild(journal, rootRunId, { step: id, runId: outcome.run_id, state: 'admitted' });
+      return readSuccessfulOutput(journal, outcome, id, journalSteps, context);
+    };
+    if (terminal) return consume(await journal.runStart(spec, undefined, admissionKey));
+    return budget.execute(journal, spec, consume, admissionKey);
+  };
+}
+
+/**
+ * Lift the step-shaped fields off a run diagnostic.
+ *
+ * `RunDiagnostic extends StepFailedDetails`, so `classifyOutcome`'s
+ * `Object.assign(diagnostic, details)` leaves the extraction right there. The
+ * fields are picked explicitly rather than spread, so `severity`, `kind` and
+ * `message` — which describe the RUN, not the step — cannot leak into
+ * something typed as the step's evidence.
+ */
+function stepDetails(
+  diagnostic: RunReport['diagnostics'][number] | undefined,
+): StepFailedDetails | undefined {
+  if (diagnostic === undefined) return undefined;
+  // `RunDiagnostic` is the only member of this union that extends
+  // `StepFailedDetails`; the check-report shapes carry none of these fields,
+  // so reading them as optionals yields `undefined` and contributes nothing.
+  const found = diagnostic as Partial<StepFailedDetails>;
+  const details: StepFailedDetails = {
+    ...(found.stepId === undefined ? {} : { stepId: found.stepId }),
+    ...(found.stepType === undefined ? {} : { stepType: found.stepType }),
+    ...(found.completionReason === undefined ? {} : { completionReason: found.completionReason }),
+    ...(found.attempt === undefined ? {} : { attempt: found.attempt }),
+    ...(found.maxIterations === undefined ? {} : { maxIterations: found.maxIterations }),
+    ...(found.exitCode === undefined ? {} : { exitCode: found.exitCode }),
+    ...(found.stdoutTail === undefined ? {} : { stdoutTail: found.stdoutTail }),
+    ...(found.stderrTail === undefined ? {} : { stderrTail: found.stderrTail }),
+    ...(found.detail === undefined ? {} : { detail: found.detail }),
+    ...(found.transcriptPath === undefined ? {} : { transcriptPath: found.transcriptPath }),
+    ...(found.hint === undefined ? {} : { hint: found.hint }),
+    ...(found.journalPath === undefined ? {} : { journalPath: found.journalPath }),
   };
+  return Object.keys(details).length === 0 ? undefined : details;
 }