@relayflows/sdk 2.0.11 → 2.0.13

package/src/authored-node-runner.ts

@@ -0,0 +1,219 @@
+import { JournalClient } from './journal-client.js';
+import { spawn, spawnSync } from 'node:child_process';
+import { createHash, createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { readFileSync, realpathSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { isAbsolute, join } from 'node:path';
+import type { Readable } from 'node:stream';
+import type { AuthoredRootMetadata } from './authored-root.js';
+import type { AuthoredExecutionRuntime, AuthoredFlowExecutionResult, ExecuteAuthoredFlowOptions } from './authored-flow-executor.js';
+import { AuthoredFlowExecutionError, type AuthoredFlowExecutionErrorCode } from './authored-flow-error.js';
+import { assertAuthoredPromiseHooks } from './authored-runtime-capability.js';
+
+let embeddedSource: string | undefined;
+/** Installed by the standalone build; never fetched or resolved from a workspace. */
+export function installAuthoredNodeSource(source: string): void {
+  if (embeddedSource !== undefined || source.length === 0) throw new Error('invalid authored runtime payload');
+  embeddedSource = source;
+}
+const hash = (value: Uint8Array | string): string => createHash('sha256').update(value).digest('hex');
+const refusal = (): AuthoredFlowExecutionError => new AuthoredFlowExecutionError(
+  'unsupported_promise_lifecycle',
+  'authored execution requires the embedded Node runner and Node >=22.14 on PATH (or an absolute FLOWS_AUTHORED_NODE); no workflow body was executed',
+);
+interface NodeAuthority { path: string; version: string; executableSha256: string }
+function nodeAuthority(): NodeAuthority {
+  if (embeddedSource === undefined) throw refusal();
+  const override = process.env['FLOWS_AUTHORED_NODE'];
+  if (override !== undefined && !isAbsolute(override)) throw refusal();
+  const probe = spawnSync(override ?? 'node', ['--input-type=module', '--eval', `
+import {createHook} from 'node:async_hooks';
+import {stripTypeScriptTypes,register} from 'node:module';
+const [major,minor]=process.versions.node.split('.').map(Number);
+let init=false,resolve=false;
+const h=createHook({init(_id,type){if(type==='PROMISE')init=true},promiseResolve(){resolve=true}}).enable();
+new Promise(r=>r());h.disable();
+if(process.versions.bun || major<22 || (major===22 && minor<14) || !init || !resolve || typeof stripTypeScriptTypes!=='function' || typeof register!=='function') process.exit(2);
+process.stdout.write(JSON.stringify({path:process.execPath,version:process.versions.node}));
+`], { encoding: 'utf8', timeout: 10_000, maxBuffer: 4096, env: process.env });
+  if (probe.error || probe.status !== 0) throw refusal();
+  try {
+    const value = JSON.parse(probe.stdout) as { path: string; version: string };
+    if (!isAbsolute(value.path) || !/^\d+\.\d+\.\d+$/.test(value.version)) throw refusal();
+    const [major, minor] = value.version.split('.').map(Number);
+    if (major! < 22 || (major === 22 && minor! < 14)) throw refusal();
+    const path = realpathSync(value.path);
+    return { path, version: value.version, executableSha256: hash(readFileSync(path)) };
+  } catch { throw refusal(); }
+}
+
+/** Called before root admission/resume; declarative commands never reach it. */
+export function assertAuthoredRuntimeAvailable(): void {
+  if (process.versions['bun'] === undefined) assertAuthoredPromiseHooks();
+  else nodeAuthority();
+}
+
+/** Bun retains the root lease and local workers. Only the authored body uses Node. */
+export async function runAuthoredInNode(
+  metadata: AuthoredRootMetadata,
+  socketPath: string,
+  rootRunId: string,
+  options: ExecuteAuthoredFlowOptions,
+): Promise<AuthoredFlowExecutionResult> {
+  const authority = nodeAuthority();
+  const source = embeddedSource!;
+  const runtime: AuthoredExecutionRuntime = {
+    kind: 'node', version: authority.version,
+    executableSha256: authority.executableSha256, payloadSha256: hash(source),
+  };
+  options.signal?.throwIfAborted();
+  const directory = await mkdtemp(join(tmpdir(), 'flows-authored-node-'));
+  const entry = join(directory, 'runner.mjs');
+  try {
+    await writeFile(entry, source, { mode: 0o400, flag: 'wx' });
+    if (hash(await readFile(entry)) !== runtime.payloadSha256) throw refusal();
+    const child = spawn(authority.path, ['--experimental-transform-types', entry, String(process.pid)], {
+      cwd: process.cwd(), env: process.env,
+      stdio: ['pipe', 'inherit', 'inherit', 'pipe'],
+    });
+    const result = await new Promise<AuthoredFlowExecutionResult>((resolve, reject) => {
+      const channelKey = randomBytes(32).toString('hex');
+      let expectedSequence = 1;
+      let buffer = '', ready = false, result: AuthoredFlowExecutionResult | undefined;
+      let failure: Error | undefined, killTimer: ReturnType<typeof setTimeout> | undefined;
+      const stop = (error: Error): void => {
+        failure ??= error;
+        child.kill('SIGTERM');
+        killTimer ??= setTimeout(() => child.kill('SIGKILL'), 2500);
+        killTimer.unref();
+      };
+      const abort = (): void => stop(new Error('authored root execution was aborted'));
+      options.signal?.addEventListener('abort', abort, { once: true });
+      if (options.signal?.aborted) abort();
+      // Do not intercept the parent's signals: its normal exit keeps the root
+      // recoverable. The child observes parent EOF (and shared process-group signals).
+      const startupTimer = setTimeout(() => stop(new Error('authored runtime readiness timed out')), 10_000);
+      startupTimer.unref();
+      const pipe = child.stdio[3] as Readable;
+      pipe.setEncoding('utf8');
+      pipe.on('data', (chunk: string) => {
+        buffer += chunk;
+        if (Buffer.byteLength(buffer) > 16 * 1024 * 1024) { stop(new Error('authored runtime response exceeded limit')); return; }
+        for (;;) {
+          const end = buffer.indexOf('\n'); if (end < 0) break;
+          const line = buffer.slice(0, end); buffer = buffer.slice(end + 1);
+          try {
+            let message = JSON.parse(line);
+            if (ready) {
+              if (message.seq !== expectedSequence || typeof message.payload !== 'string'
+                || typeof message.mac !== 'string' || !/^[a-f0-9]{64}$/.test(message.mac)) {
+                throw new Error('invalid authored runtime authenticated frame');
+              }
+              const expected = createHmac('sha256', channelKey)
+                .update(`${expectedSequence}\0${message.payload}`).digest();
+              if (!timingSafeEqual(expected, Buffer.from(message.mac, 'hex'))) {
+                throw new Error('invalid authored runtime authenticated frame');
+              }
+              expectedSequence++;
+              message = JSON.parse(message.payload);
+            }
+            if (message.type === 'ready' && !ready && !result) {
+              if (JSON.stringify(message.runtime) !== JSON.stringify(runtime)) throw refusal();
+              ready = true;
+              clearTimeout(startupTimer);
+              // Keep stdin open: EOF tells the child its lease-owning parent died.
+              child.stdin!.write(JSON.stringify({ channelKey, metadata, socketPath, rootRunId,
+                dataDir: options.dataDir, localAgentStream: options.localAgentStream }) + '\n');
+            } else if (!ready || result) throw new Error('unexpected authored runtime message');
+            else if (message.type === 'progress') options.onProgress?.(message.event);
+            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);
+            } else throw new Error('unknown authored runtime message');
+          } catch (error) { stop(error instanceof Error ? error : new Error('invalid authored runtime message')); }
+        }
+      });
+      child.stdin!.on('error', () => stop(new Error('authored runtime request pipe closed')));
+      pipe.on('error', () => stop(new Error('authored runtime result pipe failed')));
+      child.once('error', () => { failure = refusal(); });
+      child.once('close', (code) => {
+        clearTimeout(startupTimer);
+        if (killTimer !== undefined) clearTimeout(killTimer);
+        options.signal?.removeEventListener('abort', abort);
+        if (failure) reject(failure);
+        else if (code !== 0 || !ready || result === undefined || buffer.length > 0) reject(new Error('authored runtime exited without a complete result'));
+        else resolve(result);
+      });
+    });
+    await verifyAuthoredNodeResult(result, metadata, rootRunId, socketPath);
+    return result;
+  } finally { await rm(directory, { recursive: true, force: true }); }
+}
+
+/** 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'); };
+  if (result.rootRunId !== rootRunId || result.name !== metadata.flowName
+    || !['success', 'needs_human'].includes(result.completionReason)
+    || !Array.isArray(result.journalSteps) || result.journalSteps.length === 0) invalid();
+  const terminal = result.journalSteps.at(-1)!;
+  if (!terminal || !/^complete-[1-9][0-9]*$/.test(terminal.id)) invalid();
+  const count = Number(terminal.id.slice('complete-'.length));
+  if (!Number.isSafeInteger(count) || result.journalSteps.length !== count) invalid();
+  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 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()) {
+      if (!claimed || typeof claimed.id !== 'string' || typeof claimed.runId !== 'string'
+        || ordinal(claimed.id) !== index+1 || claimed.completionReason !== 'success'
+        || runs.has(claimed.runId)) invalid();
+      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();
+      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}> };
+        };
+      }> = [];
+      let fromSeq = 1;
+      for (;;) {
+        const page = (await journal.journalRead(claimed.runId, fromSeq, 100)).entries;
+        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();
+          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);
+        }
+      }
+      const spec = entries.find(entry => entry.entry_type === 'run.spawned')?.payload?.spec;
+      const step = spec?.steps?.[0];
+      const completed = entries.filter(entry => entry.entry_type === 'step.completed' && entry.step_id === claimed.id);
+      const terminalFacts = entries.filter(entry => entry.entry_type === 'run.completed');
+      if (spec?.name !== `${metadata.flowName}/${claimed.id}` || spec?.steps?.length !== 1
+        || step?.id !== claimed.id || completed.length !== 1
+        || completed[0]?.payload?.completionReason !== 'success'
+        || terminalFacts.length !== 1 || terminalFacts[0]?.payload?.completionReason !== 'success') invalid();
+      if (claimed === terminal) {
+        const command = result.completionReason === 'needs_human'
+          ? `printf '%s' '{"completionReason":"needs_human"}'` : ':';
+        if (step?.type !== 'deterministic' || step.command !== command) invalid();
+      }
+    }
+  } finally { journal.close(); }
+}

package/src/authored-plugin-effect.ts

@@ -10,6 +10,7 @@ import { AuthoredFlowExecutionError } from './authored-flow-error.js';
 import type { AuthoredFlowJournalStep } from './authored-flow-executor.js';
 import { readCompletedStepOutput } from './authored-step-output.js';
 import { withWorkerLease } from './worker-lease.js';
+import { authoredChildAdmissionKey } from './authored-admission.js';
 
 export class PluginStepError extends AuthoredFlowExecutionError {
   constructor(readonly diagnostic: string, runId: string) {
@@ -24,12 +25,14 @@ export class PluginStepError extends AuthoredFlowExecutionError {
 export async function runPluginEffect(
   journal: JournalClient, flowName: string, id: string, plugin: LoadedPlugin, verb: PluginVerb,
   args: unknown, journalSteps: AuthoredFlowJournalStep[], budget: AuthoredBudget,
+  rootRunId?: string,
 ): Promise<unknown> {
   const server = verb.namespace;
   const tool = verb.method;
   const idempotencyKey = `plugin:${server}:${tool}:${createHash('sha256').update(JSON.stringify(args)).digest('hex')}`;
   const surfacePath = `/plugins/${pathPart(server)}/${pathPart(tool)}`;
-  const stream = `plugin-worker-${randomUUID()}`;
+  const admissionKey = authoredChildAdmissionKey(rootRunId, id);
+  const stream = `plugin-worker-${admissionKey?.slice(-32) ?? randomUUID()}`;
   const instruction = JSON.stringify({ type: 'effect', server, tool, input: args });
   const peer = journal.createPeer();
   let diagnostic: string | undefined;
@@ -120,7 +123,7 @@ export async function runPluginEffect(
       childRunId = outcome.run_id;
       // run.start may answer after the deadline and the outer cleanup.
       if (dispatchExpired) await cancelChildRun();
-      await completed;
+      if (outcome.status !== 'completed') await completed;
       if (diagnostic !== undefined) {
         try { await readCompletedStepOutput(journal, outcome.run_id, id, journalSteps); }
         catch (error) {
@@ -130,7 +133,7 @@ export async function runPluginEffect(
       }
       const receipt = await readCompletedStepOutput(journal, outcome.run_id, id, journalSteps) as { output: unknown };
       return receipt.output;
-    }), deadline]);
+    }, admissionKey), deadline]);
   } finally {
     clearTimeout(timer);
     finishDeadline();

package/src/authored-root.ts

@@ -0,0 +1,396 @@
+import { loadPinnedAuthoredSource } from './authored-source-authority.js';
+import { assertAuthoredRuntimeAvailable, runAuthoredInNode } from './authored-node-runner.js';
+import { createHash, randomUUID } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { canonicalize } from './canonical.js';
+import { compileSpec, toKernelSpec } from './compile.js';
+import { executeAuthoredFlow, type AuthoredFlowExecutionResult } from './authored-flow-executor.js';
+import {
+  loadAuthoredFlow,
+  type LoadedAuthoredFlow,
+  type SurfaceModuleAuthority,
+} from './authored-flow-loader.js';
+import { JournalClient } from './journal-client.js';
+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 { isSurfaceCompletionReason } from './authored-step-output.js';
+
+const ROOT_KIND = 'relayflows.authored-root.v1';
+
+export interface AuthoredRootMetadata {
+  readonly kind: typeof ROOT_KIND;
+  readonly flowName: string;
+  readonly flowPath: string;
+  readonly sourceSha256: string;
+  readonly surface: SurfaceModuleAuthority;
+  readonly sources: readonly AuthoredRootSourceAuthority[];
+  readonly localAgentStream?: string;
+  readonly inputPresent: boolean;
+  readonly input?: unknown;
+}
+
+export interface AuthoredRootSourceAuthority {
+  readonly path: string;
+  readonly sourceSha256: string;
+  readonly surface: SurfaceModuleAuthority;
+}
+
+export interface DurableAuthoredOptions {
+  readonly dataDir: string;
+  readonly admissionKey?: string;
+  readonly localAgentStream?: string;
+  readonly lifecycle?: RunLifecycleOptions;
+}
+
+/** Admit and execute one authored body under a durable kernel root. */
+export async function executeDurableAuthoredFlow(
+  loaded: LoadedAuthoredFlow,
+  journal: JournalClient,
+  input: unknown,
+  options: DurableAuthoredOptions,
+): Promise<AuthoredFlowExecutionResult & { readonly rootRunId: string }> {
+  assertAuthoredRuntimeAvailable();
+  const source = await readFile(loaded.sourcePath);
+  const sources = await Promise.all(loaded.graph.map(async node => Object.freeze({
+    path: node.path,
+    sourceSha256: sha256(await readFile(node.path)),
+    surface: node.surfaceAuthority,
+  })));
+  const definition = loaded.getDefinition(loaded.handle);
+  const metadata: AuthoredRootMetadata = Object.freeze({
+    kind: ROOT_KIND,
+    flowName: definition.name,
+    flowPath: loaded.sourcePath,
+    sourceSha256: sha256(source),
+    surface: loaded.surfaceAuthority,
+    sources: Object.freeze(sources),
+    ...(options.localAgentStream === undefined ? {} : { localAgentStream: options.localAgentStream }),
+    inputPresent: input !== undefined,
+    ...(input === undefined ? {} : { input: jsonSnapshot(input, 'authored root input') }),
+  });
+  const admissionKey = rootAdmissionKey(options.admissionKey ?? randomUUID());
+  const stream = `authored-root-${admissionKey.slice(-40)}`;
+  const spec = rootSpec(metadata, stream);
+  const peer = journal.createPeer();
+  await peer.connect();
+  await peer.hello('flows-authored-root');
+  let cancelDispatch = () => {};
+  try {
+    const dispatchWait = nextRootDispatch(peer);
+    cancelDispatch = dispatchWait.cancel;
+    await peer.workerAttach(`worker-${stream}`, ['agent'], {
+      workspace: [], streams: [{ stream, read_offset: 0 }],
+    });
+    const outcome = await journal.runStart(spec, undefined, admissionKey);
+    if (outcome.status === 'completed') {
+      dispatchWait.cancel();
+      return await completedRootResult(journal, outcome.run_id);
+    }
+    assertRootCanDispatch(outcome);
+    // `run.start` is an idempotent receipt. If the first caller died after
+    // the daemon dispatched this root, a same-daemon retry sees the existing
+    // active run but receives no second dispatch from start itself. Resume is
+    // 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 dispatch = await dispatchWait.promise;
+    return await driveRoot(loaded, metadata, journal, peer, dispatch, options);
+  } finally {
+    cancelDispatch();
+    peer.close();
+  }
+}
+
+/** Resume the exact source and Surface instance recorded by an authored root. */
+export async function resumeDurableAuthoredFlow(
+  rootRunId: string,
+  journal: JournalClient,
+  options: Omit<DurableAuthoredOptions, 'admissionKey'>,
+): Promise<(AuthoredFlowExecutionResult & { readonly rootRunId: string }) | undefined> {
+  const metadata = await readAuthoredRootMetadata(journal, rootRunId);
+  if (metadata === undefined) return undefined;
+  assertAuthoredRuntimeAvailable();
+  const loaded = await loadPinnedAuthoredSource(metadata);
+  if (metadata.localAgentStream !== options.localAgentStream) {
+    throw new Error('authored root local agent surface mismatch');
+  }
+  const stream = rootStreamFromMetadata(await rootKernelStep(journal, rootRunId));
+  const peer = journal.createPeer();
+  await peer.connect();
+  await peer.hello('flows-authored-root-resume');
+  let cancelDispatch = () => {};
+  try {
+    const dispatchWait = nextRootDispatch(peer);
+    cancelDispatch = dispatchWait.cancel;
+    await peer.workerAttach(`worker-${stream}-${randomUUID()}`, ['agent'], {
+      workspace: [], streams: [{ stream, read_offset: 0 }],
+    });
+    const outcome = await journal.runResume(rootRunId);
+    if (outcome.status === 'completed') {
+      dispatchWait.cancel();
+      return await completedRootResult(journal, rootRunId);
+    }
+    assertRootCanDispatch(outcome);
+    const dispatch = await dispatchWait.promise;
+    return await driveRoot(loaded, metadata, journal, peer, dispatch, options);
+  } finally {
+    cancelDispatch();
+    peer.close();
+  }
+}
+
+export async function readAuthoredRootMetadata(
+  journal: JournalClient,
+  runId: string,
+): Promise<AuthoredRootMetadata | undefined> {
+  const step = await rootKernelStep(journal, runId).catch(() => undefined);
+  if (step === undefined || step.id !== 'authored-root' || !hasRootStream(step)) return undefined;
+  if (typeof step.instruction !== 'string') {
+    throw new Error('authored root journal has malformed authority metadata');
+  }
+  let value: unknown;
+  try { value = JSON.parse(step.instruction); } catch {
+    throw new Error('authored root journal has malformed authority metadata');
+  }
+  if (!isRootMetadata(value)) {
+    throw new Error('authored root journal has malformed authority metadata');
+  }
+  return value;
+}
+
+async function driveRoot(
+  loaded: LoadedAuthoredFlow,
+  metadata: AuthoredRootMetadata,
+  journal: JournalClient,
+  peer: JournalClient,
+  dispatch: StepDispatchEvent,
+  options: Omit<DurableAuthoredOptions, 'admissionKey'>,
+): Promise<AuthoredFlowExecutionResult & { readonly rootRunId: string }> {
+  try {
+    const result = await withWorkerLease(peer, dispatch, async rootSignal => {
+      const callerSignal = options.lifecycle?.signal;
+      const signal = callerSignal === undefined ? rootSignal : AbortSignal.any([callerSignal, rootSignal]);
+      if (process.versions['bun'] !== undefined) {
+        return runAuthoredInNode(metadata, journal.socketPath, dispatch.run_id, {
+          dataDir: options.dataDir, localAgentStream: options.localAgentStream,
+          ...options.lifecycle, signal,
+        });
+      }
+      return await executeAuthoredFlow(
+        loaded.handle,
+        journal,
+        metadata.inputPresent ? metadata.input : undefined,
+        {
+          getDefinition: loaded.getDefinition,
+          dataDir: options.dataDir,
+          flowPath: metadata.flowPath,
+          localAgentStream: options.localAgentStream,
+          rootRunId: dispatch.run_id,
+          ...options.lifecycle,
+          signal: callerSignal === undefined
+            ? rootSignal
+            : AbortSignal.any([callerSignal, rootSignal]),
+        },
+      );
+    });
+    await peer.stepComplete(
+      dispatch.run_id, dispatch.step_id, dispatch.attempt,
+      dispatch.idempotency_key, 'success', {
+        output: { name: result.name, completionReason: result.completionReason,
+          journalSteps: result.journalSteps,
+          ...(result.executionRuntime === undefined ? {} : { executionRuntime: result.executionRuntime }) },
+        started_pins: dispatch.pins, end_pins: dispatch.pins,
+      },
+    );
+    return Object.freeze({ ...result, rootRunId: dispatch.run_id });
+  } catch (error) {
+    await terminalizeRootFailure(peer, dispatch, error);
+    throw error;
+  }
+}
+
+/**
+ * A returned body failure is deterministic for this root attempt. Complete
+ * every kernel retry with the same declared failure so the run reaches its
+ * durable `step_failed` terminal instead of being stranded waiting for a
+ * worker after the CLI has already returned. A process crash never enters
+ * this path: the running attempt remains recoverable by `run.resume`.
+ */
+async function terminalizeRootFailure(
+  peer: JournalClient,
+  firstDispatch: StepDispatchEvent,
+  error: unknown,
+): Promise<void> {
+  let dispatch = firstDispatch;
+  const output = { error: error instanceof Error ? error.message : 'authored root failed' };
+  for (;;) {
+    const next = nextRootDispatch(peer);
+    let outcome: RunOutcome;
+    try {
+      outcome = await peer.stepComplete(
+        dispatch.run_id, dispatch.step_id, dispatch.attempt,
+        dispatch.idempotency_key, 'worker_error', {
+          output, started_pins: dispatch.pins, end_pins: dispatch.pins,
+        },
+      );
+    } catch (completionError) {
+      next.cancel();
+      throw completionError;
+    }
+    if (outcome.status === 'failed') {
+      next.cancel();
+      return;
+    }
+    try { assertRootCanDispatch(outcome); } catch (outcomeError) {
+      next.cancel();
+      throw outcomeError;
+    }
+    dispatch = await next.promise;
+    if (dispatch.run_id !== firstDispatch.run_id) {
+      throw new Error('authored root retry was dispatched for a different run');
+    }
+  }
+}
+
+function rootSpec(metadata: AuthoredRootMetadata, stream: string) {
+  return toKernelSpec(compileSpec({
+    version: SPEC_SCHEMA_VERSION,
+    name: `authored-root/${metadata.flowName}`,
+    steps: [{
+      id: 'authored-root', type: 'agent',
+      instruction: canonicalize(metadata),
+      surfaces: { streams: [{ stream }] },
+      recoveryMode: 'reset', maxIterations: 8,
+    }],
+  }));
+}
+
+async function rootKernelStep(journal: JournalClient, runId: string): Promise<Record<string, unknown>> {
+  const entries = (await journal.journalRead(runId, 1)).entries as Array<Record<string, unknown>>;
+  const spawned = entries.find(entry => entry.entry_type === 'run.spawned');
+  const payload = spawned?.payload as { spec?: { steps?: unknown[] } } | undefined;
+  const step = payload?.spec?.steps?.[0];
+  if (typeof step !== 'object' || step === null || Array.isArray(step)) {
+    throw new Error('authored root journal has no root step');
+  }
+  return step as Record<string, unknown>;
+}
+
+function rootStreamFromMetadata(step: Record<string, unknown>): string {
+  const surfaces = step.surfaces as { streams?: Array<{ stream?: unknown }> } | undefined;
+  const stream = surfaces?.streams?.[0]?.stream;
+  if (typeof stream !== 'string' || !stream.startsWith('authored-root-')) {
+    throw new Error('authored root journal has no pinned stream');
+  }
+  return stream;
+}
+
+function hasRootStream(step: Record<string, unknown>): boolean {
+  try { rootStreamFromMetadata(step); return true; } catch { return false; }
+}
+
+function nextRootDispatch(peer: JournalClient): {
+  promise: Promise<StepDispatchEvent>;
+  cancel(): void;
+} {
+  let cancel = () => {};
+  const promise = new Promise<StepDispatchEvent>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      peer.off('step.dispatch', onDispatch);
+      reject(new Error('authored root was not dispatched'));
+    }, 30_000);
+    const onDispatch = (dispatch: StepDispatchEvent) => {
+      if (dispatch.step_id !== 'authored-root') return;
+      clearTimeout(timer);
+      peer.off('step.dispatch', onDispatch);
+      resolve(dispatch);
+    };
+    peer.on('step.dispatch', onDispatch);
+    cancel = () => {
+      clearTimeout(timer);
+      peer.off('step.dispatch', onDispatch);
+    };
+  });
+  return { promise, cancel };
+}
+
+async function completedRootResult(
+  journal: JournalClient,
+  rootRunId: string,
+): Promise<AuthoredFlowExecutionResult & { readonly rootRunId: string }> {
+  const entries = (await journal.journalRead(rootRunId, 1)).entries as Array<Record<string, unknown>>;
+  const completed = entries.slice().reverse().find(entry => entry.entry_type === 'step.completed'
+    && entry.step_id === 'authored-root'
+    && (entry.payload as { completionReason?: unknown } | undefined)?.completionReason === 'success');
+  const output = (completed?.payload as { output?: unknown } | undefined)?.output;
+  if (!isCompletedRootOutput(output)) {
+    throw new Error('completed authored root has no durable result');
+  }
+  return Object.freeze({
+    name: output.name,
+    completionReason: output.completionReason,
+    journalSteps: Object.freeze(output.journalSteps.map(step => Object.freeze({ ...step }))),
+    rootRunId,
+  });
+}
+
+function isCompletedRootOutput(value: unknown): value is Omit<AuthoredFlowExecutionResult, 'rootRunId'> {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false;
+  const output = value as Partial<AuthoredFlowExecutionResult>;
+  return typeof output.name === 'string'
+    && (output.completionReason === 'success' || output.completionReason === 'needs_human')
+    && Array.isArray(output.journalSteps)
+    && output.journalSteps.every(step => typeof step === 'object' && step !== null
+      && typeof step.id === 'string' && typeof step.runId === 'string'
+      && isSurfaceCompletionReason(step.completionReason));
+}
+
+function assertRootCanDispatch(outcome: RunOutcome): void {
+  // The kernel reports `parked` after handing an agent lease to its worker;
+  // the pushed dispatch is the authority that work is live. An idempotent
+  // start retry may instead observe the same active state as `running`.
+  if (outcome.status === 'running' || outcome.status === 'parked') return;
+  throw new Error(`authored root "${outcome.run_id}" is ${outcome.status}`
+    + (outcome.completion_reason === null ? '' : ` (${outcome.completion_reason})`));
+}
+
+function rootAdmissionKey(value: string): string {
+  return `authored-root:${createHash('sha256').update(value).digest('hex')}`;
+}
+
+function sha256(bytes: Uint8Array): string {
+  return createHash('sha256').update(bytes).digest('hex');
+}
+
+function jsonSnapshot(value: unknown, label: string): unknown {
+  const encoded = JSON.stringify(value);
+  if (encoded === undefined) throw new Error(`${label} is not JSON serializable`);
+  return JSON.parse(encoded) as unknown;
+}
+
+function isRootMetadata(value: unknown): value is AuthoredRootMetadata {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false;
+  const root = value as Partial<AuthoredRootMetadata>;
+  const surface = root.surface as Partial<SurfaceModuleAuthority> | undefined;
+  const sources = root.sources;
+  return root.kind === ROOT_KIND && typeof root.flowName === 'string'
+    && typeof root.flowPath === 'string' && /^[a-f0-9]{64}$/.test(root.sourceSha256 ?? '')
+    && typeof root.inputPresent === 'boolean' && surface?.packageName === '@relayflows/surface'
+    && typeof surface.version === 'string' && /^[a-f0-9]{64}$/.test(surface.packageSha256 ?? '')
+    && /^[a-f0-9]{64}$/.test(surface.runtimeSha256 ?? '')
+    && Array.isArray(sources) && sources.length > 0 && sources.every(isRootSourceAuthority)
+    && (root.localAgentStream === undefined
+      || /^local-agent-[a-f0-9-]+$/.test(root.localAgentStream));
+}
+
+function isRootSourceAuthority(value: unknown): value is AuthoredRootSourceAuthority {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false;
+  const source = value as Partial<AuthoredRootSourceAuthority>;
+  const surface = source.surface as Partial<SurfaceModuleAuthority> | undefined;
+  return typeof source.path === 'string' && /^[a-f0-9]{64}$/.test(source.sourceSha256 ?? '')
+    && surface?.packageName === '@relayflows/surface' && typeof surface.version === 'string'
+    && /^[a-f0-9]{64}$/.test(surface.packageSha256 ?? '')
+    && /^[a-f0-9]{64}$/.test(surface.runtimeSha256 ?? '');
+}