@relayflows/sdk 2.0.16 → 2.0.18

package/src/authored-flow-executor.ts

@@ -32,8 +32,10 @@ import type { GetFlowDefinition } from './authored-flow-loader.js';
 import type { RunLifecycleOptions } from './cli/run.js';
 import {
   AuthoredFlowExecutionError,
+  AuthoredHumanParked,
   type AuthoredFlowExecutionErrorCode,
 } from './authored-flow-error.js';
+import { readHumanAnswer } from './authored-human.js';
 import {
   AuthoredFlowOperation,
   stopAuthoredOperations,
@@ -211,6 +213,93 @@ export async function executeAuthoredFlow<Input = undefined>(
     localAgentStream, budget, definition.header.budget, options.rootRunId,
   );
 
+  /**
+   * Predicate gates (docs/SURFACE.md §6). The closure runs here, once, on the
+   * value the journal handed back; the VERDICT is then journaled as a lowered
+   * `<id>.gate` deterministic step that succeeds or fails, so a resume or
+   * replay reads the recorded verdict and never re-runs author code. A false
+   * verdict fails the step as `gate_failed`, carrying the author's reason.
+   *
+   * Durability across a resume: the verdict is appended to the root run's
+   * `predicate-gates` stream BEFORE the gate run is opened. A resumed body
+   * re-executes and reaches the same gate; it finds the recorded verdict and
+   * reuses it, so the gate run's spec (which embeds the verdict) is identical
+   * under its admission key and the closure is never re-run. Without a root
+   * run there is nothing to resume, and the closure simply runs.
+   */
+  const PREDICATE_STREAM = 'predicate-gates';
+  interface PredicateRecord { gate: 'predicate'; step: string; verdict: 'pass' | 'fail'; because?: string; threw?: string }
+  // The stream is read once per execution; concurrent gates (Promise.all)
+  // share the single in-flight load, so none of them can observe an empty
+  // map while the read is still pending and re-run a closure whose verdict
+  // was already recorded.
+  let recordedVerdicts: Promise<Map<string, PredicateRecord>> | undefined;
+  async function loadRecordedVerdicts(rootRunId: string): Promise<Map<string, PredicateRecord>> {
+    const verdicts = new Map<string, PredicateRecord>();
+    let offset = 0;
+    for (;;) {
+      const page = await journal.streamRead(rootRunId, PREDICATE_STREAM, offset, 1000);
+      for (const message of page.messages) {
+        const record = (message as { message?: unknown }).message ?? message;
+        if (typeof record === 'object' && record !== null && (record as PredicateRecord).gate === 'predicate'
+          && typeof (record as PredicateRecord).step === 'string'
+          && ((record as PredicateRecord).verdict === 'pass' || (record as PredicateRecord).verdict === 'fail')) {
+          verdicts.set((record as PredicateRecord).step, record as PredicateRecord);
+        }
+      }
+      if (page.messages.length === 0 || page.next_offset <= offset) break;
+      offset = page.next_offset;
+    }
+    return verdicts;
+  }
+  async function recordedVerdict(id: string): Promise<PredicateRecord | undefined> {
+    if (options.rootRunId === undefined) return undefined;
+    recordedVerdicts ??= loadRecordedVerdicts(options.rootRunId);
+    return (await recordedVerdicts).get(id);
+  }
+  async function applyPredicateGate<T>(operation: { id: string; predicateGate: unknown }, value: T): Promise<T> {
+    const gate = operation.predicateGate as { predicate: (value: T) => boolean; because?: string } | undefined;
+    if (gate === undefined) return value;
+    const id = operation.id;
+    let record = await recordedVerdict(id);
+    if (record === undefined) {
+      let verdict: boolean;
+      let detail: string | undefined;
+      try {
+        verdict = gate.predicate(value) === true;
+      } catch (error) {
+        verdict = false;
+        detail = error instanceof Error ? error.message : String(error);
+      }
+      record = {
+        gate: 'predicate', step: id, verdict: verdict ? 'pass' : 'fail',
+        ...(gate.because === undefined ? {} : { because: gate.because }),
+        ...(detail === undefined ? {} : { threw: detail }),
+      };
+      if (options.rootRunId !== undefined) {
+        await journal.streamAppend(options.rootRunId, PREDICATE_STREAM, record);
+        (await recordedVerdicts)?.set(id, record);
+      }
+    }
+    const literal = `'${JSON.stringify(record).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);
+    } catch (error) {
+      if (record.verdict === 'pass') throw error;
+      throw new AuthoredFlowExecutionError(
+        'gate_failed',
+        `step "${id}" failed its predicate gate`
+          + (record.because === undefined ? '' : `: ${record.because}`)
+          + (record.threw === undefined ? '' : ` (predicate threw: ${record.threw})`),
+        'verification_failed',
+        error instanceof AuthoredFlowExecutionError ? error.runId : undefined,
+      );
+    }
+    return value;
+  }
+  lifecycle.applyPredicateGate = applyPredicateGate;
+
   function llmOperation(strings: TemplateStringsArray, ...values: unknown[]): Step<string>;
   function llmOperation(prompt: string, options: LlmOptions): Step<unknown>;
   function llmOperation(prompt: string | TemplateStringsArray, ...values: unknown[]): Step<unknown> {
@@ -319,9 +408,59 @@ export async function executeAuthoredFlow<Input = undefined>(
       );
       return trackStep(authoredSteps, agentOp);
     },
-    human() {
+    /**
+     * `f.human` (docs/SURFACE.md §1, §7). The question is not a child run: it
+     * is the ROOT attempt parking on the kernel's `wait.human`. The body
+     * cannot park itself — it holds no lease — so when no answer is journaled
+     * it throws `AuthoredHumanParked`, the durable root turns that into
+     * `step.wait`, and the CLI reports the question with exit 3.
+     *
+     * The wait id is the operation's ordinal (`human-N`), so a resumed body
+     * re-executes to the same call and finds the recorded
+     * `wait.completed{human_responded}`. The ANSWER is then lowered as a
+     * `human-N` deterministic step carrying `{"answer":…}` on stdout: the
+     * boolean the author's code branches on is a journaled, memoized fact in
+     * the same shape as every other authored step, so the IPC verifier and a
+     * later replay hold it to the same evidence.
+     */
+    human(question, humanOptions) {
       assertOperationAllowed('human', definition.name, requestedCompletion);
-      throw unsupportedVerb('human');
+      if (typeof question !== 'string' || question.trim() === '') {
+        throw new AuthoredFlowExecutionError('human_answer_invalid', 'f.human requires a non-empty question');
+      }
+      if (typeof humanOptions?.to !== 'string' || humanOptions.to.trim() === '') {
+        throw new AuthoredFlowExecutionError('human_answer_invalid', 'f.human requires { to } naming who answers');
+      }
+      const id = `human-${nextStep++}`;
+      const to = humanOptions.to;
+      // Hoisted like `llmOp`/`runOp`: the start closure reads the caller's
+      // `.gate(config)` at spec-build time, so a named gate on the answer is
+      // lowered into the `human-N` step's `verification` like any other step's.
+      let humanOp!: AuthoredFlowOperation<boolean>;
+      humanOp = new AuthoredFlowOperation<boolean>(
+        id, 'human',
+        () => assertOperationAllowed('human', definition.name, requestedCompletion),
+        () => observeStep(id, 'deterministic', async () => {
+          const rootRunId = options.rootRunId;
+          if (rootRunId === undefined) {
+            throw new AuthoredFlowExecutionError(
+              'unsupported_verb',
+              `f.human needs a durable root to park in; "${id}" has no run to wait on. Run the flow with flows run.`,
+            );
+          }
+          const recorded = await readHumanAnswer(journal, rootRunId, id);
+          if (recorded === undefined) throw new AuthoredHumanParked({ waitId: id, question, to }, rootRunId);
+          const record = { human: id, to, answer: recorded.answer,
+            ...(recorded.note === undefined ? {} : { note: recorded.note }),
+            answeredBy: recorded.answeredBy,
+            ...(recorded.atMs === undefined ? {} : { at: new Date(recorded.atMs).toISOString() }) };
+          const literal = `'${JSON.stringify(record).replaceAll("'", "'\\''")}'`;
+          await lowerDeterministic(id, `printf '%s' ${literal}`, false, undefined, humanOp.namedGate);
+          return recorded.answer;
+        }, options.onProgress),
+        lifecycle,
+      );
+      return trackStep(authoredSteps, humanOp);
     },
     dispatch<T>() {
       assertOperationAllowed('dispatch', definition.name, requestedCompletion);

package/src/authored-flow-lifecycle.ts

@@ -109,6 +109,13 @@ function collectMembers(values: Iterable<unknown>): unknown[] | undefined {
  * called the operation's then method.
  */
 export class AuthoredFlowLifecycle {
+  /**
+   * Installed by the executor: runs an operation's predicate gate (if any) on
+   * its resolved value before the operation fulfills. Lives on the lifecycle
+   * so EVERY authored operation — core steps, helpers, MCP, plugins — passes
+   * through it; a gate accepted on a Step must never be silently ignored.
+   */
+  applyPredicateGate: (<T>(operation: { id: string; predicateGate: unknown }, value: T) => Promise<T>) | undefined = undefined;
   private readonly graph: AuthoredPromiseGraph;
   private readonly activeResolverProbes: ResolverProbe[] = [];
   private readonly invocations = new Map<OperationToken, AuthoredOperationInvocation[]>();

package/src/authored-flow-operation.ts

@@ -8,7 +8,7 @@ import {
 
 /** Slice-P kinds the surface `.gate(config)` accepts and the SDK lowers. */
 const NAMED_GATE_KINDS = new Set([
-  'references_input', 'subprocess_gate', 'word_count_bounds', 'regex_match',
+  'references_input', 'subprocess_gate', 'word_count_bounds', 'regex_match', 'artifact_exists',
 ]);
 
 function isNamedGateConfig(candidate: unknown): candidate is NamedGate {
@@ -31,6 +31,14 @@ export class AuthoredFlowOperation<T> {
    * still throws `unsupported_gate` and never sets this field.
    */
   namedGate: NamedGate | undefined = undefined;
+  /**
+   * Predicate gate attached via `.gate(fn, because?)`. Author code: it runs
+   * in this process after the step completes, and its verdict is journaled as
+   * a lowered `<id>.gate` deterministic step (docs/SURFACE.md §6), so replay
+   * and resume see the recorded verdict and never re-run the closure. The
+   * function itself is never serialized. `flows check` cannot prove it.
+   */
+  predicateGate: { predicate: (value: T) => boolean; because?: string } | undefined = undefined;
   private state: OperationState = 'created';
   private thenInvoked = false;
   private rootFailureRecorded = false;
@@ -61,20 +69,29 @@ export class AuthoredFlowOperation<T> {
     const operation = this;
     const step: Step<T> = {
       gate(configOrPredicate: NamedGate | ((value: T) => boolean), _because?: string): Step<T> {
+        if (operation.namedGate !== undefined || operation.predicateGate !== undefined) {
+          throw new AuthoredFlowExecutionError('unsupported_gate', 'a step takes one .gate().');
+        }
         if (isNamedGateConfig(configOrPredicate)) {
           // Config-object gate: lowers into the compiled StepSpec's
           // `verification:` field via slice-P named-gate lowering.
           operation.namedGate = configOrPredicate;
           return step;
         }
-        // Predicate gate: closures cannot be journaled (covenant 1
-        // journal-as-truth). Refuse — authors should use a config-object
-        // gate or the declarative `verification:` block.
-        throw new AuthoredFlowExecutionError(
-          'unsupported_gate',
-          'postfix .gate(predicate) closures cannot be journaled; '
-            + 'use .gate({type: "…", …}) with a slice-P named gate instead.',
-        );
+        // Predicate gate: runtime control flow. The closure cannot be
+        // journaled, but its VERDICT can — the executor runs it once after
+        // the step completes and records pass/fail as a `<id>.gate` step.
+        if (typeof configOrPredicate !== 'function') {
+          throw new AuthoredFlowExecutionError(
+            'unsupported_gate',
+            '.gate() takes a named gate config ({type: "…", …}) or a predicate function.',
+          );
+        }
+        if (_because !== undefined && typeof _because !== 'string') {
+          throw new AuthoredFlowExecutionError('unsupported_gate', '.gate(predicate, because) takes a string reason.');
+        }
+        operation.predicateGate = { predicate: configOrPredicate, ...(_because === undefined ? {} : { because: _because }) };
+        return step;
       },
       then<TResult1 = T, TResult2 = never>(
         onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | null,
@@ -144,7 +161,15 @@ export class AuthoredFlowOperation<T> {
     try {
       this.assertCanStart();
       this.state = 'running';
-      const value = await this.start();
+      const started = await this.start();
+      // The predicate gate, when present, is applied here for every kind of
+      // operation, so a helper or plugin step cannot carry a gate that never
+      // runs. The executor installs the applier; without one, a predicate
+      // gate is refused rather than skipped.
+      const value = this.predicateGate === undefined ? started
+        : this.scope.applyPredicateGate === undefined
+          ? (() => { throw new AuthoredFlowExecutionError('unsupported_gate', 'this runtime cannot apply predicate gates'); })()
+          : await this.scope.applyPredicateGate(this as unknown as { id: string; predicateGate: unknown }, started);
       this.state = 'fulfilled';
       this.resolve(value);
     } catch (error) {

package/src/authored-human.ts

@@ -0,0 +1,150 @@
+import { AuthoredFlowExecutionError, type AuthoredHumanWait } from './authored-flow-error.js';
+import type { JournalClient } from './journal-client.js';
+
+/**
+ * The answer contract for a parked `f.human`.
+ *
+ * The CLIENT sends `{ answer, note?, answeredBy }` as the `payload` of the
+ * `event.emit` that closes the wait (kernel DESIGN.md §5: `event_key` is the
+ * `wait_id`); `answeredBy` is required — the kernel refuses an unattributed
+ * answer. The KERNEL journals it as the `result` of
+ * `wait.completed{human_responded}` with two fields of its own: `at_ms`, the
+ * entry's clock (any client `at` is dropped — the journal says when), and
+ * `attribution: "client_asserted"`, because the daemon socket, not the kernel,
+ * is what authenticated whoever said `answeredBy`. `flows answer` and Cloud's
+ * resumed sandbox both produce the client half; the body reads the kernel half.
+ */
+export interface HumanAnswer {
+  readonly answer: boolean;
+  readonly note?: string;
+  readonly answeredBy: string;
+  /** Kernel clock at the journaled `wait.completed`, epoch milliseconds. */
+  readonly atMs?: number;
+  /** How `answeredBy` was established. The kernel writes `client_asserted`. */
+  readonly attribution?: string;
+}
+
+export type HumanAnswerPayload = Pick<HumanAnswer, 'answer' | 'note' | 'answeredBy'>;
+
+/** An open `wait.human` on a run: asked, not yet answered. */
+export interface OpenHumanWait extends AuthoredHumanWait {
+  readonly stepId: string;
+  readonly attempt: number;
+}
+
+export const HUMAN_WAIT_ID = /^human-[1-9][0-9]*$/;
+
+export function humanAnswerPayload(answer: boolean, extra: { note?: string; answeredBy: string }): HumanAnswerPayload {
+  if (extra.answeredBy.trim() === '') {
+    throw new AuthoredFlowExecutionError('human_answer_invalid', 'an answer must say who gave it (answeredBy)');
+  }
+  return {
+    answer,
+    ...(extra.note === undefined || extra.note === '' ? {} : { note: extra.note }),
+    answeredBy: extra.answeredBy,
+  };
+}
+
+/** Narrow an untrusted journal `result` to the answer contract, or refuse it. */
+export function parseHumanAnswer(value: unknown, waitId: string): HumanAnswer {
+  const record = value as { answer?: unknown; note?: unknown; answeredBy?: unknown; at_ms?: unknown; attribution?: unknown } | null;
+  if (typeof record !== 'object' || record === null || typeof record.answer !== 'boolean'
+    || (record.note !== undefined && typeof record.note !== 'string')
+    || typeof record.answeredBy !== 'string' || record.answeredBy.trim() === ''
+    || (record.at_ms !== undefined && !Number.isSafeInteger(record.at_ms))
+    || (record.attribution !== undefined && typeof record.attribution !== 'string')) {
+    throw new AuthoredFlowExecutionError(
+      'human_answer_invalid',
+      `the recorded answer to ${waitId} is not { answer: boolean, answeredBy: string }; answer it again with flows answer`,
+    );
+  }
+  return {
+    answer: record.answer,
+    ...(record.note === undefined ? {} : { note: record.note }),
+    answeredBy: record.answeredBy,
+    ...(record.at_ms === undefined ? {} : { atMs: record.at_ms as number }),
+    ...(record.attribution === undefined ? {} : { attribution: record.attribution }),
+  };
+}
+
+interface WaitEntry {
+  entry_type?: string;
+  step_id?: string | null;
+  attempt?: number | null;
+  payload?: {
+    wait_id?: unknown; prompt?: unknown; requested_of?: unknown;
+    completionReason?: unknown; result?: unknown;
+  };
+}
+
+async function readWaitEntries(journal: JournalClient, runId: string): Promise<WaitEntry[]> {
+  const waits: WaitEntry[] = [];
+  let fromSeq = 1;
+  for (;;) {
+    const page = (await journal.journalRead(runId, fromSeq, 1000)).entries as Array<WaitEntry & { seq?: number }>;
+    if (page.length === 0) break;
+    for (const entry of page) {
+      if (typeof entry.seq !== 'number' || entry.seq < fromSeq) {
+        throw new AuthoredFlowExecutionError('journal_protocol_violation', `journal.read for ${runId} returned out-of-order entries`);
+      }
+      fromSeq = entry.seq + 1;
+      if (entry.entry_type === 'wait.human' || entry.entry_type === 'wait.completed') waits.push(entry);
+    }
+  }
+  return waits;
+}
+
+/**
+ * The recorded answer to `waitId`, or `undefined` while the question is open
+ * or not yet asked. The first `human_responded` completion wins: the kernel
+ * closes a wait once, so a second answer never reaches the journal.
+ */
+export async function readHumanAnswer(
+  journal: JournalClient,
+  runId: string,
+  waitId: string,
+): Promise<HumanAnswer | undefined> {
+  for (const entry of await readWaitEntries(journal, runId)) {
+    if (entry.entry_type === 'wait.completed' && entry.payload?.wait_id === waitId
+      && entry.payload.completionReason === 'human_responded') {
+      return parseHumanAnswer(entry.payload.result, waitId);
+    }
+  }
+  return undefined;
+}
+
+/** Every `wait.human` on the run that no `wait.completed` has closed. */
+export async function readOpenHumanWaits(journal: JournalClient, runId: string): Promise<OpenHumanWait[]> {
+  const open = new Map<string, OpenHumanWait>();
+  for (const entry of await readWaitEntries(journal, runId)) {
+    const waitId = entry.payload?.wait_id;
+    if (typeof waitId !== 'string') continue;
+    if (entry.entry_type === 'wait.human') {
+      open.set(waitId, {
+        waitId,
+        question: typeof entry.payload?.prompt === 'string' ? entry.payload.prompt : '',
+        to: typeof entry.payload?.requested_of === 'string' ? entry.payload.requested_of : '',
+        stepId: typeof entry.step_id === 'string' ? entry.step_id : '',
+        attempt: typeof entry.attempt === 'number' ? entry.attempt : 0,
+      });
+    } else {
+      open.delete(waitId);
+    }
+  }
+  return [...open.values()];
+}
+
+/** How to answer a parked question from a shell, with the run's own data dir. */
+export function answerCommand(runId: string, waitId: string, dataDir?: string): string {
+  const dir = dataDir === undefined ? '' : ` --data-dir ${shellWord(dataDir)}`;
+  return `flows answer${dir} ${runId} ${waitId} yes|no`;
+}
+
+export function resumeCommand(runId: string, dataDir?: string, localAgent = false): string {
+  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

@@ -5,7 +5,7 @@ import { JournalClient } from './journal-client.js';
 import { executeAuthoredFlow } from './authored-flow-executor.js';
 import { loadPinnedAuthoredSource } from './authored-source-authority.js';
 import { assertAuthoredNodeVersion, parseAuthoredParentPid } from './authored-runtime-capability.js';
-import { AuthoredFlowExecutionError } from './authored-flow-error.js';
+import { AuthoredFlowExecutionError, AuthoredHumanParked } from './authored-flow-error.js';
 import type { AuthoredRootMetadata } from './authored-root.js';
 
 let channelKey: string | undefined, sequence = 0;
@@ -82,7 +82,8 @@ try {
   const prefix = error instanceof AuthoredFlowExecutionError ? `${error.code}: ` : '';
   send({ type: 'error', message: prefix && message.startsWith(prefix) ? message.slice(prefix.length) : message,
     ...(error instanceof AuthoredFlowExecutionError ? { code: error.code,
-      completionReason: error.completionReason, runId: error.runId } : {}) });
+      completionReason: error.completionReason, runId: error.runId } : {}),
+    ...(error instanceof AuthoredHumanParked ? { wait: error.wait } : {}) });
   process.exitCode = 1;
 } finally {
   finished = true; await watchdog.terminate(); client?.close(); process.stdin.destroy();

package/src/authored-node-runner.ts

@@ -9,7 +9,11 @@ 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 { AuthoredFlowExecutionError, type AuthoredFlowExecutionErrorCode } from './authored-flow-error.js';
+import {
+  AuthoredFlowExecutionError, AuthoredHumanParked,
+  type AuthoredFlowExecutionErrorCode, type AuthoredHumanWait,
+} from './authored-flow-error.js';
+import { HUMAN_WAIT_ID } from './authored-human.js';
 import { assertAuthoredPromiseHooks } from './authored-runtime-capability.js';
 
 let embeddedSource: string | undefined;
@@ -131,10 +135,12 @@ 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 = typeof message.code === 'string'
-                ? new AuthoredFlowExecutionError(message.code as AuthoredFlowExecutionErrorCode,
-                  message.message, message.completionReason, message.runId)
-                : new Error(message.message);
+              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)
+                  : 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')); }
         }
@@ -156,35 +162,58 @@ export async function runAuthoredInNode(
   } finally { await rm(directory, { recursive: true, force: true }); }
 }
 
+/** A park signal from the child names the question the parent must journal. */
+function isHumanWaitFrame(value: unknown): value is AuthoredHumanWait {
+  const wait = value as Partial<AuthoredHumanWait> | null;
+  return typeof wait === 'object' && wait !== null
+    && typeof wait.waitId === 'string' && HUMAN_WAIT_ID.test(wait.waitId)
+    && typeof wait.question === 'string' && wait.question !== ''
+    && typeof wait.to === 'string' && wait.to !== '';
+}
+
 /** The IPC frame is a claim, not a durable terminal fact or a sandbox boundary. */
 export async function verifyAuthoredNodeResult(
   result: AuthoredFlowExecutionResult, metadata: AuthoredRootMetadata,
   rootRunId: string, socketPath: string,
 ): Promise<void> {
-  const invalid = (): never => { throw new Error('authored runtime result has no matching durable completion'); };
+  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)
-    || !Array.isArray(result.journalSteps) || result.journalSteps.length === 0) invalid();
+    || !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();
+  if (!terminal || !/^complete-[1-9][0-9]*$/.test(terminal.id)) invalid('terminal');
   const count = Number(terminal.id.slice('complete-'.length));
-  if (!Number.isSafeInteger(count) || result.journalSteps.length !== count) invalid();
+  // A predicate gate is journaled as `<step>.gate`: a child run subordinate
+  // to the authored step it judges, in the same `<step>.gate` shape a named
+  // gate lowers to inside its step's own spec. Neither consumes an ordinal —
+  // `complete-N` counts the operations the author wrote (SURFACE.md §6) —
+  // so gates are set aside from the count and the contiguity check, and
+  // verified separately: every gate must name a claimed parent, and is then
+  // held to the same durable-completion evidence as any other child run.
+  const isGate = (id: string): boolean => /\.gate$/.test(id);
+  const authored = result.journalSteps.filter(step => typeof step?.id === 'string' && !isGate(step.id));
+  const gates = result.journalSteps.filter(step => typeof step?.id === 'string' && isGate(step.id));
+  if (!Number.isSafeInteger(count) || authored.length !== count || isGate(terminal.id)) invalid(`count ${authored.length}!=${count}`);
   const ordinal = (id: string): number => Number(/-([1-9][0-9]*)$/.exec(id)?.[1]);
   // Parallel awaits may finish in either order; validate a copy in declaration order.
-  const ordered = [...result.journalSteps].sort((a,b)=>ordinal(a.id)-ordinal(b.id));
+  const ordered = [...authored].sort((a,b)=>ordinal(a.id)-ordinal(b.id));
+  const authoredIds = new Set(ordered.map(step => step.id));
+  for (const gate of gates) {
+    if (!authoredIds.has(gate.id.slice(0, -'.gate'.length))) invalid(`orphan ${gate.id}`);
+  }
   const runs = new Set<string>();
   const journal = new JournalClient(socketPath);
   await journal.connect();
   try {
     await journal.hello('flows-authored-result-verifier');
-    for (const [index, claimed] of ordered.entries()) {
+    for (const [index, claimed] of [...ordered, ...gates].entries()) {
       if (!claimed || typeof claimed.id !== 'string' || typeof claimed.runId !== 'string'
-        || ordinal(claimed.id) !== index+1 || claimed.completionReason !== 'success'
-        || runs.has(claimed.runId)) invalid();
+        || (index < ordered.length && ordinal(claimed.id) !== index+1) || claimed.completionReason !== 'success'
+        || runs.has(claimed.runId)) invalid(`claim ${claimed?.id}`);
       runs.add(claimed.runId);
       const state = await journal.runGet(claimed.runId);
       if (state.run_id !== claimed.runId || state.status !== 'completed'
-        || state.steps[claimed.id]?.state !== 'done') invalid();
+        || state.steps[claimed.id]?.state !== 'done') invalid(`state ${claimed.id} ${state.status} ${state.steps[claimed.id]?.state}`);
       const entries: Array<{
         seq: number; entry_type: string; step_id?: string; payload?: {
           completionReason?: string; spec?: { name?: string; steps?: Array<{id?:string;type?:string;command?:string}> };
@@ -196,7 +225,7 @@ export async function verifyAuthoredNodeResult(
         if (page.length === 0) break;
         for (const raw of page) {
           const entry = raw as typeof entries[number];
-          if (!Number.isSafeInteger(entry?.seq) || entry.seq < fromSeq) invalid();
+          if (!Number.isSafeInteger(entry?.seq) || entry.seq < fromSeq) invalid('seq');
           fromSeq = entry.seq + 1;
           // Keep only completion evidence; streaming logs can span many pages.
           if (['run.spawned', 'step.completed', 'run.completed'].includes(entry.entry_type)) entries.push(entry);
@@ -204,12 +233,20 @@ export async function verifyAuthoredNodeResult(
       }
       const spec = entries.find(entry => entry.entry_type === 'run.spawned')?.payload?.spec;
       const step = spec?.steps?.[0];
+      // A named gate lowers INTO the step's own spec as a second, dependent
+      // `<id>.gate` step (named-gate-lowering.ts); that is the only other
+      // step a child spec may carry, and it must have completed too.
+      const lowered = spec?.steps ?? [];
+      const specShape = lowered.length === 1 || (lowered.length === 2 && lowered[1]?.id === `${claimed.id}.gate`);
       const completed = entries.filter(entry => entry.entry_type === 'step.completed' && entry.step_id === claimed.id);
+      const gateCompleted = lowered.length === 2
+        ? entries.filter(entry => entry.entry_type === 'step.completed' && entry.step_id === `${claimed.id}.gate`) : [];
       const terminalFacts = entries.filter(entry => entry.entry_type === 'run.completed');
-      if (spec?.name !== `${metadata.flowName}/${claimed.id}` || spec?.steps?.length !== 1
+      if (spec?.name !== `${metadata.flowName}/${claimed.id}` || !specShape
         || step?.id !== claimed.id || completed.length !== 1
         || completed[0]?.payload?.completionReason !== 'success'
-        || terminalFacts.length !== 1 || terminalFacts[0]?.payload?.completionReason !== 'success') invalid();
+        || (lowered.length === 2 && (gateCompleted.length !== 1 || gateCompleted[0]?.payload?.completionReason !== 'success'))
+        || terminalFacts.length !== 1 || terminalFacts[0]?.payload?.completionReason !== 'success') invalid(`evidence ${claimed.id} spec=${spec?.name} step=${step?.id} completed=${completed.length}`);
       if (claimed === terminal) {
         // The claimed verdict must match the marker the journal actually
         // recorded, so an IPC frame cannot claim `success` over a run whose
@@ -219,7 +256,7 @@ export async function verifyAuthoredNodeResult(
         // the runtime validation of untrusted IPC, and it is why nothing has
         // to be re-asserted here just to satisfy the type.
         if (step?.type !== 'deterministic'
-          || step.command !== completionMarker(result.completionReason)) invalid();
+          || step.command !== completionMarker(result.completionReason)) invalid('marker');
       }
     }
   } finally { journal.close(); }

package/src/authored-root.ts

@@ -15,6 +15,8 @@ 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 { readOpenHumanWaits } from './authored-human.js';
 import { isSurfaceCompletionReason } from './authored-step-output.js';
 
 const ROOT_KIND = 'relayflows.authored-root.v1';
@@ -94,7 +96,8 @@ export async function executeDurableAuthoredFlow(
     // active run but receives no second dispatch from start itself. Resume is
     // safe for the first caller too: the daemon preserves a live lease and
     // redelivers only when the former worker connection is gone.
-    await journal.runResume(outcome.run_id);
+    const resumed = await journal.runResume(outcome.run_id);
+    await assertNoOpenHumanWait(journal, resumed);
     const dispatch = await dispatchWait.promise;
     return await driveRoot(loaded, metadata, journal, peer, dispatch, options);
   } finally {
@@ -133,6 +136,7 @@ export async function resumeDurableAuthoredFlow(
       return await completedRootResult(journal, rootRunId);
     }
     assertRootCanDispatch(outcome);
+    await assertNoOpenHumanWait(journal, outcome);
     const dispatch = await dispatchWait.promise;
     return await driveRoot(loaded, metadata, journal, peer, dispatch, options);
   } finally {
@@ -141,6 +145,17 @@ export async function resumeDurableAuthoredFlow(
   }
 }
 
+/**
+ * A root parked on an unanswered `f.human` will not be dispatched: the
+ * kernel holds it in `needs_human` until `event.emit` closes the wait. Report
+ * the open question instead of waiting for a dispatch that cannot arrive.
+ */
+async function assertNoOpenHumanWait(journal: JournalClient, outcome: RunOutcome): Promise<void> {
+  if (outcome.status !== 'parked') return;
+  const [open] = await readOpenHumanWaits(journal, outcome.run_id);
+  if (open !== undefined) throw new AuthoredHumanParked(open, outcome.run_id);
+}
+
 export async function readAuthoredRootMetadata(
   journal: JournalClient,
   runId: string,
@@ -206,6 +221,18 @@ async function driveRoot(
     );
     return Object.freeze({ ...result, rootRunId: dispatch.run_id });
   } catch (error) {
+    if (error instanceof AuthoredHumanParked) {
+      // Not a failure: the body reached a question nobody has answered. Park
+      // THIS attempt on the kernel's `wait.human` under the body's own wait
+      // id, so the answer (`event.emit` keyed by it) re-dispatches the root
+      // and the re-run body finds it. The lease is released by the verb; the
+      // signal propagates so the CLI reports the question with exit 3.
+      await peer.stepWait(dispatch.run_id, dispatch.step_id, dispatch.attempt, dispatch.idempotency_key, {
+        wait_id: error.wait.waitId, prompt: error.wait.question, requested_of: error.wait.to,
+        options: ['yes', 'no'],
+      });
+      throw error;
+    }
     await terminalizeRootFailure(peer, dispatch, error);
     throw error;
   }