@relayflows/sdk 2.0.29 → 2.0.31

package/src/authored-completion-record.ts

@@ -0,0 +1,119 @@
+// The authored verdict, written to the root BEFORE the marker is admitted.
+//
+// The terminal marker's command embeds the detail, and the marker run is
+// opened under a stable admission key (`authored-child:<hash(root, step)>`).
+// Those two facts together mean the detail has to be a durable decision, not a
+// recomputed one: normalization redacts against `process.env`, so a credential
+// rotated or removed while this process was down makes the SAME authored
+// sentence normalize differently. A body resumed into that environment would
+// retry the marker's admission key with a drifted spec, and the kernel refuses
+// that as `run_admission_conflict` — losing an explanation the root had
+// already journaled, for a flow whose every step succeeded.
+//
+// So the verdict is appended to a stream on the root run before the marker run
+// is opened, and a later attempt reaching the same terminal step reuses what
+// is recorded. That is exactly the durability the executor already gives a
+// predicate gate (`applyPredicateGate`): record the decision first, so the
+// spec built from it is identical on every attempt and author code is never
+// asked the question twice.
+//
+// Nothing is recorded for a `done()` with no detail. Without one the marker
+// command is a function of the reason alone — no environment, no drift, and
+// nothing to recover — so a flow that does not opt in writes exactly the
+// journal it has always written.
+
+import {
+  isDurableCompletionDetail,
+  isLoweredCompletion,
+  type LoweredCompletionReason,
+} from './authored-completion.js';
+import type { JournalClient } from './journal-client.js';
+
+export const AUTHORED_VERDICT_STREAM = 'authored-verdict';
+
+/** Versioned so a reader can tell this record from a future one. */
+const RECORD_KIND = 'relayflows.authored-verdict.v1';
+
+export interface AuthoredVerdictRecord {
+  readonly reason: LoweredCompletionReason;
+  /** Recorded only when the body passed one; see the module comment. */
+  readonly detail?: string;
+}
+
+/**
+ * Commit this body's verdict, or recover the one this root already committed.
+ *
+ * Returns the verdict the marker must be built from — the recorded one when
+ * the root holds it, this attempt's otherwise. With no root run there is
+ * nothing durable to write to (the non-durable executor seam), so that path
+ * passes straight through without a round trip. A root run is always read
+ * first: a committed record stays authoritative even for an attempt that has
+ * no detail of its own — an optional source can be present on the first
+ * execution and gone on the retry, and "this attempt has no detail" is not
+ * "this root never recorded one". Only when no record exists AND this attempt
+ * has no detail does it return without appending, preserving the no-detail
+ * marker, spec hash, and journal exactly as before.
+ */
+export async function commitAuthoredVerdict(
+  journal: JournalClient,
+  rootRunId: string | undefined,
+  step: string,
+  verdict: AuthoredVerdictRecord,
+): Promise<AuthoredVerdictRecord> {
+  if (rootRunId === undefined) return verdict;
+  const committed = await readAuthoredVerdict(journal, rootRunId, step);
+  if (committed !== undefined) return committed;
+  if (verdict.detail === undefined) return verdict;
+  await journal.streamAppend(rootRunId, AUTHORED_VERDICT_STREAM, {
+    verdict: RECORD_KIND, step, reason: verdict.reason, detail: verdict.detail,
+  });
+  return verdict;
+}
+
+/**
+ * The verdict this root recorded for `step`, or `undefined`.
+ *
+ * The FIRST valid record wins: it is the one the marker was — or was about to
+ * be — admitted from, and a later attempt's differently-redacted text must not
+ * displace it. Records this version does not recognise, and details that fail
+ * the durable check every other read boundary applies, are skipped rather than
+ * trusted; the marker then drifts and the kernel refuses it loudly, which is
+ * the right outcome for a record this process cannot read.
+ */
+export async function readAuthoredVerdict(
+  journal: JournalClient,
+  rootRunId: string,
+  step: string,
+): Promise<AuthoredVerdictRecord | undefined> {
+  let offset = 0;
+  for (;;) {
+    const page = await journal.streamRead(rootRunId, AUTHORED_VERDICT_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 (isVerdictRecord(raw) && raw.step === step) {
+        return Object.freeze({ reason: raw.reason, detail: raw.detail });
+      }
+    }
+    if (page.messages.length === 0 || page.next_offset <= offset) break;
+    offset = page.next_offset;
+  }
+  return undefined;
+}
+
+interface StoredVerdict {
+  readonly verdict: typeof RECORD_KIND;
+  readonly step: string;
+  readonly reason: LoweredCompletionReason;
+  readonly detail: string;
+}
+
+function isVerdictRecord(value: unknown): value is StoredVerdict {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false;
+  const record = value as Partial<StoredVerdict>;
+  return record.verdict === RECORD_KIND
+    && typeof record.step === 'string' && record.step.length > 0
+    && isLoweredCompletion(record.reason)
+    && isDurableCompletionDetail(record.detail);
+}

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, {
@@ -325,7 +341,16 @@ export async function executeAuthoredFlow<Input = undefined>(
         (await recordedVerdicts)?.set(id, record);
       }
     }
-    const literal = `'${JSON.stringify(record).replaceAll("'", "'\\''")}'`;
+    // Fixed field order, never the record as it came back: the journal stores
+    // stream messages with sorted keys, so JSON.stringify of a resumed record
+    // would lower a different command than the first run did, and the gate
+    // run's admission key would refuse it as bound to a different spec.
+    const canonical: PredicateRecord = {
+      gate: 'predicate', step: record.step, verdict: record.verdict,
+      ...(record.because === undefined ? {} : { because: record.because }),
+      ...(record.threw === undefined ? {} : { threw: record.threw }),
+    };
+    const literal = `'${JSON.stringify(canonical).replaceAll("'", "'\\''")}'`;
     const command = record.verdict === 'pass' ? `printf '%s' ${literal}` : `printf '%s' ${literal} >&2; exit 1`;
     try {
       await observeStep(`${id}.gate`, 'deterministic', () => lowerDeterministic(`${id}.gate`, command, false), options.onProgress);
@@ -373,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);
@@ -435,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);
@@ -553,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',
@@ -586,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),
@@ -661,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]),
   });
 }
@@ -686,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 {