@relayflows/sdk 2.0.55 → 2.0.56

package/src/authored-broker.ts

@@ -0,0 +1,73 @@
+import { randomUUID } from 'node:crypto';
+import type { AgentOptions, AgentResult, NamedGate } from '@relayflows/surface';
+import { parseAgentStepTimeout } from './compile.js';
+import type { StepSpec } from './spec.js';
+import { BROKER_TYPE, brokerAgentName, brokerOptionsError, type BrokerInstruction } from './communication/broker-spec.js';
+import { AuthoredFlowExecutionError } from './authored-flow-error.js';
+
+type Declaration = { instruction: BrokerInstruction; cli?: string; model?: string; secrets?: string[] };
+
+/** Broker options stay in a journaled instruction; the kernel only sees agent steps. */
+export function authoredBroker(definition: { name: string }, rootRunId: string | undefined,
+  localStream: string | undefined, run: (step: StepSpec) => Promise<unknown>) {
+  const owner = rootRunId ?? randomUUID();
+  const declarations = new Map<string, Declaration>();
+  const invalid = (message: string): never => { throw new AuthoredFlowExecutionError('agent_cli_unresolved', message); };
+  const execute = async (id: string, declaration: Declaration, verification?: NamedGate): Promise<AgentResult> => {
+    const { instruction, cli, model, secrets } = declaration;
+    const output = await run({ id, type: 'agent', instruction: JSON.stringify(instruction), cli, model,
+      timeoutMs: instruction.timeoutMs,
+      // Retained sessions must return to the same worker, including after a child completes.
+      surfaces: localStream === undefined ? undefined : { streams: [{ stream: localStream }] },
+      maxIterations: 1, transportRetries: 0,
+      ...(secrets?.length ? { secrets } : {}),
+      ...(verification === undefined ? {} : { verification }) });
+    if (!output || typeof output !== 'object' || !('completionReason' in output)) {
+      throw new AuthoredFlowExecutionError('journal_protocol_violation', 'Broker step produced an invalid result');
+    }
+    return output as AgentResult;
+  };
+  const lookup = (name: string): Declaration => declarations.get(name) ?? invalid(`No retained broker agent named ${name} in this flow`);
+  return {
+    async agent(id: string, name: string, options: AgentOptions, verification?: NamedGate,
+      secrets?: string[]): Promise<AgentResult> {
+      const problem = brokerOptionsError(options);
+      if (problem) invalid(`f.agent options: ${problem}`);
+      if (options.keepAlive && localStream === undefined) invalid('Retained broker agents require a local agent worker stream');
+      if (options.keepAlive && verification !== undefined) invalid('Retained broker agents do not support gates; validate their result in a later step');
+      if (typeof options.task !== 'string' || !options.task.trim()) invalid('f.agent task must be nonempty');
+      if (options.workspace !== undefined || options.permissions !== undefined) invalid('Broker agents use cwd; workspace and permissions are not supported');
+      if ((options.maxIterations ?? 1) !== 1 || (options.transportRetries ?? 0) !== 0
+        || options.recoveryMode !== undefined) invalid('Broker sessions require maxIterations 1, transportRetries 0, and no recoveryMode');
+      if (typeof name !== 'string' || !name.trim()) invalid('Broker agent name must be nonempty');
+      const instruction: BrokerInstruction = { type: BROKER_TYPE, operation: 'spawn', owner,
+        flow: definition.name, step: name, agentName: brokerAgentName(definition.name, name, owner, id),
+        task: options.task, cwd: options.cwd, skills: options.skills ?? [],
+        channel: options.channel ?? `flow-${owner}`, keepAlive: options.keepAlive ?? false,
+        timeoutMs: options.timeout === undefined ? 3_600_000 : parseAgentStepTimeout(options.timeout) };
+      const declaration = { instruction, cli: options.cli, model: options.model,
+        ...(secrets?.length ? { secrets } : {}) };
+      const result = await execute(id, declaration, verification);
+      if (instruction.keepAlive && result.completionReason === 'success') declarations.set(instruction.agentName, declaration);
+      return result;
+    },
+    async message(id: string, name: string, text: string, options?: { timeout?: string | number },
+      verification?: NamedGate): Promise<AgentResult> {
+      const declaration = lookup(name);
+      if (typeof text !== 'string' || !text.trim()) invalid('f.message text must be nonempty');
+      const result = await execute(id, { ...declaration, instruction: { ...declaration.instruction,
+        operation: 'message', task: text, timeoutMs: options?.timeout === undefined
+          ? declaration.instruction.timeoutMs : parseAgentStepTimeout(options.timeout) } }, verification);
+      return result;
+    },
+    async release(id: string, name: string): Promise<void> {
+      const declaration = lookup(name);
+      await run({ id, type: 'agent', cli: declaration.cli, model: declaration.model,
+        instruction: JSON.stringify({ ...declaration.instruction, operation: 'release' }),
+        surfaces: localStream === undefined ? undefined : { streams: [{ stream: localStream }] },
+        ...(declaration.secrets?.length ? { secrets: declaration.secrets } : {}),
+        maxIterations: 1, transportRetries: 0 });
+      // Keep the declaration so an explicit release remains idempotent.
+    },
+  };
+}

package/src/authored-budget.ts

@@ -109,13 +109,17 @@ export class AuthoredBudget {
 
   async execute<T>(journal: JournalClient, spec: KernelRunSpec,
     consume: (outcome: RunOutcome) => Promise<T>, admissionKey?: string,
-    isolatedStart = false): Promise<T> {
+    isolatedStart = false, cleanup = false): Promise<T> {
     if (this.limit === undefined) return consume(await journal.runStart(spec, undefined, admissionKey, false, isolatedStart));
     const previous = this.tail;
     let release!: () => void;
     this.tail = new Promise<void>(resolve => { release = resolve; });
     await previous;
     try {
+      // A broker release stays journaled after a failed gate or an exhausted
+      // header. It carries no budget, so the kernel cannot refuse it, and it
+      // does not latch another failure over the one that required cleanup.
+      if (cleanup) return await consume(await journal.runStart(spec, undefined, admissionKey, false, isolatedStart));
       if (this.failed) throw new AuthoredFlowExecutionError('step_failed', 'A prior budgeted step did not finish successfully.');
       // Window selection follows journal timestamps, never the SDK host clock.
       const day = this.charges.at(-1)?.day;
@@ -162,7 +166,7 @@ export class AuthoredBudget {
         }
       }
     } catch (error) {
-      this.failed = true;
+      if (!cleanup) this.failed = true;
       throw error;
     } finally { release(); }
   }

package/src/authored-flow-error.ts

@@ -58,6 +58,12 @@ export type AuthoredFlowExecutionErrorCode =
   | 'unsupported_header'
   | 'unsettled_derived_work'
   | 'unsupported_promise_lifecycle'
+  /**
+   * A resumed serial body reached a journaled step id with a different call:
+   * concurrent branches resolved in another order than the journaled run.
+   * Refused before the step is admitted (authored-serial-ordinals.ts).
+   */
+  | 'serial_replay_order_mismatch'
   /** A pinned parallel root cannot dispatch safely in this process environment. */
   | 'unsafe_parallel_runtime'
   | 'unsupported_workspace_permission'

package/src/authored-flow-executor.ts

@@ -48,7 +48,7 @@ import {
   AuthoredHumanParked,
   type AuthoredFlowExecutionErrorCode,
 } from './authored-flow-error.js';
-import { readHumanAnswer } from './authored-human.js';
+import { readHumanWait } from './authored-human.js';
 import { parseHumanTo } from './human-to.js';
 import {
   AuthoredFlowOperation,
@@ -58,6 +58,7 @@ import {
 import { AuthoredFlowLifecycle, parallelPromiseIntrinsicsIntact } from './authored-flow-lifecycle.js';
 import { AuthoredActivities } from './authored-activity.js';
 import { displayLabel, type AuthoredStepEdges } from './authored-step-index.js';
+import { assertSerialOrdinal, serialOrdinals, serialReplayOrderMismatch, type SerialOrdinals } from './authored-serial-ordinals.js';
 import { JournalClient } from './journal-client.js';
 import { PluginError } from './plugin-manifest.js';
 import { createHookEvaluator } from './authored-hooks.js';
@@ -209,6 +210,15 @@ export interface ExecuteAuthoredFlowOptions {
   readonly flowGraph?: readonly LoadedAuthoredFlowNode[];
   /** Internal namespace for descendant step/admission identities. */
   readonly stepPrefix?: string;
+  /**
+   * The step ids the root's index held when this attempt began, read by the
+   * root driver on a re-dispatch and shared with dispatched children, so a
+   * serial body is checked against the journal it is replaying
+   * (authored-serial-ordinals.ts). Absent on a first attempt: nothing to replay.
+   */
+  readonly journaledSteps?: readonly string[];
+  /** Root-owned replay refusal, shared with dispatched children so one refusal stops the whole tree. */
+  readonly replayLatch?: { violation?: AuthoredFlowExecutionError };
   /** Current child depth. Root is zero; dispatch is capped at three. */
   readonly dispatchDepth?: number;
   /** Parent predecessors inherited by the first operation in a child body. */
@@ -327,10 +337,42 @@ export async function executeAuthoredFlow<Input = undefined>(
   const assertParallelRunOnly = (kind: string): void => {
     if (options.executionMode === 'parallel') rejectParallel(`parallel f.run body attempted ${kind} before admission`);
   };
+  // Serial bodies only: parallel ids come from the causal frontier, not one
+  // shared counter. A refusal is latched, so an author `catch` around the
+  // call cannot let the body go on to admit anything else.
+  const journaledSteps = options.executionMode === 'parallel' || options.rootRunId === undefined
+    ? undefined : options.journaledSteps;
+  const ordinals: SerialOrdinals | undefined = journaledSteps === undefined
+    ? undefined : serialOrdinals(journaledSteps, options.stepPrefix ?? '');
+  const replayLatch = options.replayLatch ?? {};
+  const refuseReplay = (error: AuthoredFlowExecutionError): never => {
+    replayLatch.violation ??= error;
+    throw replayLatch.violation;
+  };
+  const assertNoReplayViolation = (): void => {
+    if (replayLatch.violation !== undefined) throw replayLatch.violation;
+  };
+  // Every operation re-checks at start: a step declared before the refusal
+  // and awaited after it is refused too, not admitted.
+  const assertStartAllowed = (verb: string): void => {
+    assertNoReplayViolation();
+    assertOperationAllowed(verb, definition.name, requestedCompletion);
+  };
+  const claimedOrdinals = new Set<number>();
+  const serialId = (kind: string, sequence: number): string => {
+    assertNoReplayViolation();
+    claimedOrdinals.add(sequence);
+    if (ordinals !== undefined) {
+      try { assertSerialOrdinal(ordinals, kind, sequence); } catch (error) {
+        refuseReplay(error as AuthoredFlowExecutionError);
+      }
+    }
+    return qualify(`${kind}-${sequence}`);
+  };
   const nextId = (kind: string): string => {
     if (parallelViolation !== undefined) throw parallelViolation;
+    if (options.executionMode !== 'parallel') return serialId(kind, nextStep++);
     const sequence = nextStep++;
-    if (options.executionMode !== 'parallel') return qualify(`${kind}-${sequence}`);
     if (kind !== 'run') rejectParallel(`parallel f.run body attempted ${kind} before admission`);
     if (!lifecycle.combinatorsObserved()) rejectParallel(
       'cannot assign a replay-stable f.run identity: a Promise intrinsic was replaced');
@@ -486,7 +528,7 @@ export async function executeAuthoredFlow<Input = undefined>(
     let llmOp!: AuthoredFlowOperation<unknown>;
     llmOp = new AuthoredFlowOperation(
       id, 'llm',
-      () => assertOperationAllowed('llm', definition.name, requestedCompletion),
+      () => assertStartAllowed('llm'),
       () => observeStep(id, 'llm', () => {
         if (typeof prompt === 'string') {
           if (values.length !== 1 || values[0] === undefined) {
@@ -532,7 +574,7 @@ export async function executeAuthoredFlow<Input = undefined>(
       let recordOp!: AuthoredFlowOperation<RunResult>;
       recordOp = new AuthoredFlowOperation<RunResult>(
         id, 'run',
-        () => assertOperationAllowed('run', definition.name, requestedCompletion),
+        () => assertStartAllowed('run'),
         () => observeStep(id, 'deterministic',
           () => lowerDeterministic.recording(id, command, leaseMs, recordOp.namedGate, secrets), options.onProgress),
         lifecycle,
@@ -545,7 +587,7 @@ export async function executeAuthoredFlow<Input = undefined>(
     let runOp!: AuthoredFlowOperation<string>;
     runOp = new AuthoredFlowOperation<string>(
       id, 'run',
-      () => assertOperationAllowed('run', definition.name, requestedCompletion),
+      () => assertStartAllowed('run'),
       () => observeStep(id, 'deterministic', () => lowerDeterministic(id, command, false, leaseMs, runOp.namedGate, secrets), options.onProgress),
       lifecycle,
       // No label: a command is not a display name. It carries literal
@@ -561,10 +603,10 @@ export async function executeAuthoredFlow<Input = undefined>(
     assertOperationAllowed(`slack.${call.verb}`, definition.name, requestedCompletion);
     assertHelperAllowed(call.provider);
     const snapshot = snapshotJsonValue(call, 'f.slack call') as unknown as SlackCall;
-    const id = qualify(`slack-${slackRun}-${nextStep++}`);
+    const id = serialId(`slack-${slackRun}`, nextStep++);
     return trackStep(authoredSteps, new AuthoredFlowOperation<T>(
       id, `slack.${call.verb}`,
-      () => assertOperationAllowed(`slack.${call.verb}`, definition.name, requestedCompletion),
+      () => assertStartAllowed(`slack.${call.verb}`),
       async () => {
         const receipt = await runHelperEffect(journal, definition.name, id, snapshot,
           options.dataDir ?? dirname(journal.socketPath), journalSteps, options.rootRunId);
@@ -581,7 +623,22 @@ export async function executeAuthoredFlow<Input = undefined>(
     declared: definition.header?.hooks ?? [],
     extensions: options.extensions ?? [],
     peekStep: () => nextStep,
-    restoreStep: (step) => { nextStep = step; },
+    restoreStep: (step, hook) => {
+      // A replayed verdict jumps the counter to the watermark it recorded,
+      // which also counts ordinals other branches took while the hook ran.
+      // Skipping one of those would hand that branch's completed step a fresh
+      // ordinal and run it again, so a jump over a journaled ordinal this
+      // attempt has not claimed is refused. (It also refuses skipping the
+      // hook's own steps; resuming past those already fails at the kernel.)
+      for (let ordinal = nextStep; ordinals !== undefined && ordinal < step; ordinal++) {
+        const journaled = ordinals.get(ordinal)?.[0];
+        if (journaled !== undefined && !claimedOrdinals.has(ordinal)) {
+          refuseReplay(serialReplayOrderMismatch(
+            `hook step "${hook}" would skip ordinal ${ordinal}, journaled as step "${journaled.step}"`));
+        }
+      }
+      nextStep = step;
+    },
     ...(options.signal === undefined ? {} : { signal: options.signal }),
   });
 
@@ -592,9 +649,9 @@ export async function executeAuthoredFlow<Input = undefined>(
       assertOperationAllowed(verb, definition.name, requestedCompletion);
       assertHelperAllowed(call.provider);
       const snapshot = snapshotJsonValue(call, `f.${verb} call`) as unknown as HelperCall;
-      const id = qualify(`${call.provider}-${slackRun}-${nextStep++}`);
+      const id = serialId(`${call.provider}-${slackRun}`, nextStep++);
       return trackStep(authoredSteps, new AuthoredFlowOperation<T>(id, verb,
-        () => assertOperationAllowed(verb, definition.name, requestedCompletion),
+        () => assertStartAllowed(verb),
         async () => await runHelperEffect(journal, definition.name, id, snapshot,
           options.dataDir ?? dirname(journal.socketPath), journalSteps, options.rootRunId) as T,
         lifecycle));
@@ -610,7 +667,7 @@ export async function executeAuthoredFlow<Input = undefined>(
       const id = nextId('mcp');
       return trackStep(authoredSteps, new AuthoredFlowOperation(
         id, 'mcp',
-        () => assertOperationAllowed('mcp', definition.name, requestedCompletion),
+        () => assertStartAllowed('mcp'),
         () => runMcpEffect(journal, definition.name, id, server, tool, args,
           known, checkedMcp.servers[server]!, journalSteps, options.rootRunId),
         lifecycle,
@@ -618,7 +675,7 @@ export async function executeAuthoredFlow<Input = undefined>(
     }),
     memory: authoredMemory(
       scriptMemoryScope(flowPath, definition.name),
-      () => { assertParallelRunOnly('memory'); assertOperationAllowed('memory', definition.name, requestedCompletion); },
+      () => { assertParallelRunOnly('memory'); assertNoReplayViolation(); assertOperationAllowed('memory', definition.name, requestedCompletion); },
       definition.header.memory?.script !== false,
       memoryWrites,
       options.rootRunId === undefined ? undefined : journalLearnLedger(journal, options.rootRunId),
@@ -634,15 +691,41 @@ export async function executeAuthoredFlow<Input = undefined>(
       agentOp = new AuthoredFlowOperation<AgentResult>(
         id,
         'agent',
-        () => assertOperationAllowed('agent', definition.name, requestedCompletion),
-        () => observeStep(id, 'agent', () => worker.agent(id, options, agentOp.namedGate), onProgress),
+        () => assertStartAllowed('agent'),
+        () => observeStep(id, 'agent', () => {
+          if (options.transport === 'broker' && options.keepAlive
+            && (agentOp.namedGate !== undefined || agentOp.predicateGate !== undefined)) {
+            throw new AuthoredFlowExecutionError('agent_cli_unresolved',
+              'Retained broker agents do not support gates; validate their result in a later step');
+          }
+          return worker.agent(id, options, agentOp.namedGate, name);
+        }, onProgress),
         lifecycle,
         displayLabel(typeof name === 'string' ? name : undefined),
       );
       return trackStep(authoredSteps, agentOp);
     },
+    message(agentName, text, messageOptions) {
+      assertOperationAllowed('message', definition.name, requestedCompletion);
+      const id = nextId('agent');
+      let messageOp!: AuthoredFlowOperation<AgentResult>;
+      messageOp = new AuthoredFlowOperation<AgentResult>(id, 'message',
+        () => assertStartAllowed('message'),
+        () => observeStep(id, 'agent',
+          () => worker.message(id, agentName, text, messageOptions, messageOp.namedGate), onProgress),
+        lifecycle);
+      return trackStep(authoredSteps, messageOp);
+    },
+    release(agentName) {
+      assertOperationAllowed('release', definition.name, requestedCompletion);
+      const id = nextId('agent');
+      return trackStep(authoredSteps, new AuthoredFlowOperation<void>(id, 'release',
+        () => assertStartAllowed('release'),
+        () => observeStep(id, 'agent', () => worker.release(id, agentName), onProgress), lifecycle));
+    },
     on(source, activityOptions) {
       assertParallelRunOnly('on');
+      assertNoReplayViolation();
       assertOperationAllowed('on', definition.name, requestedCompletion);
       // Activity ids are root-scoped (`activity-N`); a child's own counter would collide.
       if ((options.dispatchDepth ?? 0) > 0) {
@@ -697,7 +780,7 @@ export async function executeAuthoredFlow<Input = undefined>(
       let humanOp!: AuthoredFlowOperation<boolean>;
       humanOp = new AuthoredFlowOperation<boolean>(
         id, 'human',
-        () => assertOperationAllowed('human', definition.name, requestedCompletion),
+        () => assertStartAllowed('human'),
         () => observeStep(id, 'deterministic', async () => {
           const rootRunId = options.rootRunId;
           if (rootRunId === undefined) {
@@ -706,7 +789,15 @@ export async function executeAuthoredFlow<Input = undefined>(
               `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);
+          const { answer: recorded, asked } = await readHumanWait(journal, rootRunId, id);
+          // The answer is keyed by the wait id alone, and a reordered resume
+          // can hand that id to a different f.human: never apply an answer
+          // to a question nobody was asked.
+          if (asked.some(wait => wait.question !== question || wait.to !== to)) {
+            refuseReplay(serialReplayOrderMismatch(
+              `ordinal ${id.slice(id.lastIndexOf('-') + 1)} is journaled as human step "${id}" asking a `
+                + 'different question or recipient, but this resume reached it with another f.human'));
+          }
           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 }),
@@ -735,7 +826,7 @@ export async function executeAuthoredFlow<Input = undefined>(
       dispatchOp = new AuthoredFlowOperation<DispatchResult>(
         id,
         'dispatch',
-        () => assertOperationAllowed('dispatch', definition.name, requestedCompletion),
+        () => assertStartAllowed('dispatch'),
         async () => {
           const inheritedAfter = stepEdges(id)?.after ?? [];
           const currentHelperAuthority = helperAuthority(definition);
@@ -743,6 +834,8 @@ export async function executeAuthoredFlow<Input = undefined>(
             ? currentHelperAuthority
             : new Set([...currentHelperAuthority].filter(provider => options.allowedHelperProviders!.has(provider)));
           const childResult = await executeAuthoredFlow(child.handle, journal, inputSnapshot, {
+            ...(journaledSteps === undefined ? {} : { journaledSteps }),
+            replayLatch,
             getDefinition: child.getDefinition,
             dataDir: options.dataDir,
             flowPath: child.path,
@@ -799,7 +892,7 @@ export async function executeAuthoredFlow<Input = undefined>(
       const snapshot = snapshotJsonValue(input, 'f.hook input');
       return trackStep(authoredSteps, new AuthoredFlowOperation<boolean>(
         id, 'hook',
-        () => assertOperationAllowed('hook', definition.name, requestedCompletion),
+        () => assertStartAllowed('hook'),
         async () => {
           const verdict = await evaluateHook(id, name, snapshot, context);
           const record = { hook: name, step: id, verdict: verdict ? 'pass' : 'fail' };
@@ -862,7 +955,7 @@ export async function executeAuthoredFlow<Input = undefined>(
     assertOperationAllowed(label, definition.name, requestedCompletion);
     const id = nextId('plugin');
     return trackStep(authoredSteps, new AuthoredFlowOperation(
-      id, label, () => assertOperationAllowed(label, definition.name, requestedCompletion),
+      id, label, () => assertStartAllowed(label),
       () => runPluginEffect(journal, definition.name, id, plugin, verb, args,
         journalSteps, budget, options.rootRunId),
       lifecycle,
@@ -890,6 +983,7 @@ export async function executeAuthoredFlow<Input = undefined>(
   // A source certificate is a performance admission decision, never a way
   // for authored try/catch to turn a refused effect into successful output.
   if (parallelViolation !== undefined) { bodyFailed = true; bodyFailure = parallelViolation; }
+  if (replayLatch.violation !== undefined) { bodyFailed = true; bodyFailure = replayLatch.violation; }
   if (bodyFailed) {
     // Refuse queued work immediately. A slow memory commit must not leave an
     // admission slot open after the body has already failed.
@@ -982,7 +1076,8 @@ export async function executeAuthoredFlow<Input = undefined>(
   // 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 = qualify(`complete-${nextStep}`);
+  const terminalId = options.executionMode === 'parallel'
+    ? qualify(`complete-${nextStep}`) : serialId('complete', nextStep);
   const verdict = await commitAuthoredVerdict(journal, options.rootRunId, terminalId, {
     reason: requestedCompletion,
     ...(requestedDetail === undefined ? {} : { detail: requestedDetail }),

package/src/authored-flow-loader.ts

@@ -311,14 +311,54 @@ export async function packageTreeSha256(root: string): Promise<string> {
   }
   await visit(root);
   const hash = createHash('sha256');
-  for (const path of files) {
-    const bytes = await readFile(path);
+  await readInOrder(files, SURFACE_READ_CONCURRENCY, (path, bytes) => {
     const name = relative(root, path).split(sep).join('/');
     hash.update(name).update('\0').update(String(bytes.length)).update('\0').update(bytes);
-  }
+  });
   return hash.digest('hex');
 }
 
+/**
+ * Surface is about 600 small files, and both the CLI and the authored Node
+ * child hash it on the startup path. Awaiting one read at a time paid a
+ * filesystem round trip per file; a sandbox disk made that several hundred ms.
+ */
+const SURFACE_READ_CONCURRENCY = 32;
+
+/**
+ * Read `paths` through a window of at most `limit` files, started in order
+ * and handed to `consume` strictly in `paths` order, so the digest is the
+ * serial walk's. The window bounds buffered bytes as well as reads in flight:
+ * a slow early file stops new reads instead of letting later files pile up.
+ * After any read fails no new read starts. The lowest-index failure, the
+ * error a serial walk would meet first, is thrown once every started read
+ * has settled.
+ */
+async function readInOrder(
+  paths: readonly string[],
+  limit: number,
+  consume: (path: string, bytes: Buffer) => void,
+): Promise<void> {
+  const reads: Array<Promise<Buffer>> = [];
+  let failed = false, next = 0;
+  const start = (): void => {
+    const read = readFile(paths[next++]!);
+    read.catch(() => { failed = true; });
+    reads.push(read);
+  };
+  while (next < paths.length && reads.length < limit) start();
+  for (let index = 0; reads.length !== 0; index += 1) {
+    let bytes: Buffer;
+    try { bytes = await reads[0]!; } catch (error) {
+      await Promise.allSettled(reads);
+      throw error;
+    }
+    reads.shift();
+    consume(paths[index]!, bytes);
+    if (!failed && next < paths.length) start();
+  }
+}
+
 // Exported for callers (internal SDK tests, and any co-located flow that is
 // provably the same `@relayflows/surface` instance as this package) that
 // have no need to resolve a separate copy.

package/src/authored-helper-effect.ts

@@ -51,7 +51,8 @@ export async function runHelperEffect(
   const outcome = await journal.runStart(spec, undefined, admissionKey);
   await atomicJson(join(dataDir, 'helper-runs', `${outcome.run_id}.json`), { provider: call.provider });
   await driveHelperEffect(journal, outcome.run_id, spec.steps[0] as KernelAgentStep, call, dataDir);
-  const output = await readCompletedStepOutput(journal, outcome.run_id, stepId, journalSteps);
+  const output = await readCompletedStepOutput(journal, outcome.run_id, stepId, journalSteps,
+    rootRunId === undefined ? {} : { rootRunId });
   return (output as { receipt: unknown }).receipt;
 }
 

package/src/authored-hooks.ts

@@ -32,7 +32,8 @@ export function createHookEvaluator(options: {
   readonly declared: readonly string[];
   readonly extensions: readonly LoadedFlowExtension[];
   readonly peekStep?: () => number;
-  readonly restoreStep?: (step: number) => void;
+  /** Restore the parent watermark a recorded verdict carries; `hook` is the replayed hook step. */
+  readonly restoreStep?: (step: number, hook: string) => void;
   readonly signal?: AbortSignal;
 }): (id: string, name: string, input: unknown, context: Ctx) => Promise<boolean> {
   let recorded: Promise<Map<string, HookRecord>> | undefined;
@@ -83,7 +84,7 @@ export function createHookEvaluator(options: {
       const existing = await lookup(`${id}:noop`);
       const record = existing ?? { hook: name, step: id, plugin: null, verdict: 'noop' as const };
       if (existing === undefined) await append(record);
-      else if (existing.afterStep !== undefined) options.restoreStep?.(existing.afterStep);
+      else if (existing.afterStep !== undefined) options.restoreStep?.(existing.afterStep, id);
       return true;
     }
     for (const extension of impls) {
@@ -111,7 +112,7 @@ export function createHookEvaluator(options: {
         };
         await append(record);
       } else if (record.afterStep !== undefined) {
-        options.restoreStep?.(record.afterStep);
+        options.restoreStep?.(record.afterStep, id);
       }
       if (record.verdict === 'fail') return false;
     }

package/src/authored-human.ts

@@ -105,13 +105,44 @@ export async function readHumanAnswer(
   runId: string,
   waitId: string,
 ): Promise<HumanAnswer | undefined> {
+  return (await readHumanWait(journal, runId, waitId)).answer;
+}
+
+/**
+ * `readHumanAnswer`, plus every question the run has parked on under
+ * `waitId`. The answer is keyed by the wait id alone, so the executor checks
+ * that the question it is about to answer is the one that was asked.
+ */
+export async function readHumanWait(
+  journal: JournalClient,
+  runId: string,
+  waitId: string,
+): Promise<{ answer?: HumanAnswer; asked: Array<{ question: unknown; to: unknown }> }> {
+  const asked: Array<{ question: unknown; to: unknown }> = [];
   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);
+    if (entry.payload?.wait_id !== waitId) continue;
+    if (entry.entry_type === 'wait.human') {
+      asked.push({ question: entry.payload.prompt, to: entry.payload.requested_of });
+    } else if (entry.payload.completionReason === 'human_responded') {
+      return { answer: parseHumanAnswer(entry.payload.result, waitId), asked };
     }
   }
-  return undefined;
+  return { asked };
+}
+
+/**
+ * Every `f.human` wait id the run has parked on, answered or not. A parked
+ * question is not in the step index until its answer is lowered, but it
+ * already holds its serial ordinal.
+ */
+export async function readHumanWaitIds(journal: JournalClient, runId: string): Promise<string[]> {
+  const ids = new Set<string>();
+  for (const entry of await readWaitEntries(journal, runId)) {
+    const waitId = entry.payload?.wait_id;
+    if (entry.entry_type === 'wait.human' && typeof waitId === 'string'
+      && /(?:^|--)human-[1-9][0-9]*$/u.test(waitId)) ids.add(waitId);
+  }
+  return [...ids];
 }
 
 /** Every `wait.human` on the run that no `wait.completed` has closed. */

package/src/authored-mcp.ts

@@ -142,13 +142,18 @@ export async function runMcpEffect(
     childRunId = outcome.run_id;
     if (outcome.status !== 'completed') await completed;
     if (diagnostic !== undefined) {
-      try { await readCompletedStepOutput(journal, outcome.run_id, id, journalSteps, {}, outcome.status); }
+      try {
+        await readCompletedStepOutput(journal, outcome.run_id, id, journalSteps,
+          rootRunId === undefined ? {} : { rootRunId }, outcome.status);
+      }
       catch (error) {
         if (!(error instanceof AuthoredFlowExecutionError) || error.code !== 'step_failed') throw error;
         throw new McpStepError(diagnostic, outcome.run_id);
       }
     }
-    const receipt = await readCompletedStepOutput(journal, outcome.run_id, id, journalSteps, {}, outcome.status) as { output: unknown };
+    // Indexed on the root like every other child, so a resume can see its ordinal.
+    const receipt = await readCompletedStepOutput(journal, outcome.run_id, id, journalSteps,
+      rootRunId === undefined ? {} : { rootRunId }, outcome.status) as { output: unknown };
     return receipt.output;
   } finally {
     clearTimeout(timer);

package/src/authored-node-entry.ts

@@ -53,7 +53,7 @@ try {
     executableSha256: hash(process.execPath), payloadSha256: hash(process.argv[1]!) } });
   const request = await new Promise<{ channelKey: string; metadata: AuthoredRootMetadata; socketPath: string;
     rootRunId: string; dataDir: string; localAgentStream?: string; workerCapacity?: number;
-    agentEnvironment?: unknown }>((resolve, reject) => {
+    journaledSteps?: unknown; agentEnvironment?: unknown }>((resolve, reject) => {
     let buffer = '';
     process.stdin.setEncoding('utf8');
     const onData = (chunk: string): void => {
@@ -90,6 +90,8 @@ try {
   }
   if (request.localAgentStream !== request.metadata.localAgentStream) throw new Error('authored root local agent surface mismatch');
   if (request.workerCapacity !== undefined && !isAgentCapacity(request.workerCapacity)) throw new Error('invalid authored worker capacity');
+  if (request.journaledSteps !== undefined && (!Array.isArray(request.journaledSteps)
+    || !request.journaledSteps.every(step => typeof step === 'string'))) throw new Error('invalid authored journaled steps');
   client = new JournalClient(request.socketPath, { readBudgetMs: FLOW_READ_BUDGET_MS, budgetHandshake: true });
   await client.connect(); await client.hello('flows-authored-node');
   const result = await executeAuthoredFlow(loaded.handle, client,
@@ -102,6 +104,7 @@ try {
       flowGraph: loaded.graph,
       localAgentStream: request.localAgentStream, signal: controller.signal,
       ...(request.workerCapacity === undefined ? {} : { workerCapacity: request.workerCapacity }),
+      ...(request.journaledSteps === undefined ? {} : { journaledSteps: request.journaledSteps as string[] }),
       ...(agentEnvironment === undefined ? {} : { agentEnvironment: { ...process.env, ...agentEnvironment } }),
       onProgress: event => send({ type: 'progress', event }),
       onWait: event => send({ type: 'wait', event }),

package/src/authored-node-runner.ts

@@ -191,6 +191,7 @@ export async function runAuthoredInNode(
               child.stdin!.write(JSON.stringify({ channelKey, metadata, socketPath, rootRunId,
                 dataDir: options.dataDir, localAgentStream: options.localAgentStream,
                 workerCapacity: options.workerCapacity,
+                ...(options.journaledSteps === undefined ? {} : { journaledSteps: options.journaledSteps }),
                 agentEnvironment: options.agentEnvironment }) + '\n');
             } else if (!ready || result) throw new Error('unexpected authored runtime message');
             else if (message.type === 'progress') options.onProgress?.(message.event);

package/src/authored-plugin-effect.ts

@@ -127,13 +127,18 @@ export async function runPluginEffect(
       if (dispatchExpired) await cancelChildRun();
       if (outcome.status !== 'completed') await completed;
       if (diagnostic !== undefined) {
-        try { await readCompletedStepOutput(journal, outcome.run_id, id, journalSteps, {}, outcome.status); }
+        try {
+          await readCompletedStepOutput(journal, outcome.run_id, id, journalSteps,
+            rootRunId === undefined ? {} : { rootRunId }, outcome.status);
+        }
         catch (error) {
           if (!(error instanceof AuthoredFlowExecutionError) || error.code !== 'step_failed') throw error;
           throw new PluginStepError(diagnostic, outcome.run_id);
         }
       }
-      const receipt = await readCompletedStepOutput(journal, outcome.run_id, id, journalSteps, {}, outcome.status) as { output: unknown };
+      // Indexed on the root like every other child, so a resume can see its ordinal.
+      const receipt = await readCompletedStepOutput(journal, outcome.run_id, id, journalSteps,
+        rootRunId === undefined ? {} : { rootRunId }, outcome.status) as { output: unknown };
       return receipt.output;
     }, admissionKey), deadline]);
   } finally {

package/src/authored-preflight.ts

@@ -1,3 +1,4 @@
+import { brokerInstruction } from './communication/broker-spec.js';
 import { dirname, resolve } from 'node:path';
 import { checkAuthoredFlow, readProjectConfig, type ProjectConfig } from './cli/check.js';
 import { probeCliAsync } from './cli/cli-probe.js';
@@ -21,7 +22,7 @@ export function authoredPreflight(path: string, environment?: NodeJS.ProcessEnv)
     if (!resolved.ok) return checkAuthoredFlow(flow, path, config, { environment });
     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 managed = step.type === 'agent' && (communicationInstruction(step.instruction) !== undefined || brokerInstruction(step.instruction) !== undefined);
       const key = cliProbeKey(resolution, managed, step.secrets);
       if (probeCache.has(key)) return;
       let probing = pending.get(key);