@relayflows/sdk 2.0.30 → 2.0.32

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

package/src/authored-preflight.ts

@@ -0,0 +1,46 @@
+import { dirname, resolve } from 'node:path';
+import { checkAuthoredFlow, readProjectConfig, type ProjectConfig } from './cli/check.js';
+import { probeCliAsync } from './cli/cli-probe.js';
+import { communicationInstruction } from './communication/spec.js';
+import { cliProbeKey, CliProbeError, resolvePreflight, type CliProbeOutcome } from './preflight.js';
+import type { FlowSpec } from './spec.js';
+
+/** Auth/model facts belong to one execution, including concurrent cold callers. */
+export function authoredPreflight(path: string) {
+  const probeCache = new Map<string, CliProbeOutcome>();
+  const pending = new Map<string, Promise<void>>();
+  const directory = dirname(resolve(path));
+  return async (flow: FlowSpec) => {
+    let config: ProjectConfig;
+    try { config = readProjectConfig(directory); }
+    catch { return checkAuthoredFlow(flow, path); }
+    const resolved = resolvePreflight(flow, {
+      projectCli: config.cli, projectConfigPath: config.path, projectSearchStart: directory,
+      models: config.models, modelRegistryPath: config.modelRegistryPath,
+    });
+    if (!resolved.ok) return checkAuthoredFlow(flow, path, config);
+    await Promise.all(resolved.resolutions.map(async resolution => {
+      const step = resolved.compiled!.steps.find(step => step.id === resolution.stepId)!;
+      const managed = step.type === 'agent' && communicationInstruction(step.instruction) !== undefined;
+      const key = cliProbeKey(resolution, managed);
+      if (probeCache.has(key)) return;
+      let probing = pending.get(key);
+      if (probing === undefined) {
+        probing = (async () => {
+          try {
+            probeCache.set(key, { result: await probeCliAsync(resolution.cli,
+              resolution.source === 'project' ? config.directory : directory,
+              resolution.model, managed ? 'managed' : undefined) });
+          } catch (error) {
+            probeCache.set(key, { failure: error instanceof CliProbeError ? error.detail : null });
+          }
+        })();
+        pending.set(key, probing);
+      }
+      await probing;
+      pending.delete(key);
+    }));
+    const result = checkAuthoredFlow(flow, path, config, {}, probeCache);
+    return result;
+  };
+}

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'