@relayflows/sdk 2.0.10 → 2.0.12

package/src/authored-flow-loader.ts

@@ -1,6 +1,8 @@
-import { accessSync, constants, realpathSync } from 'node:fs';
+import { accessSync, constants, existsSync, realpathSync } from 'node:fs';
+import { readFile, readdir } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
 import { createRequire } from 'node:module';
-import { dirname, resolve } from 'node:path';
+import { dirname, join, relative, resolve, sep } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import {
   getAuthoredFlowDefinition,
@@ -18,7 +20,15 @@ export class AuthoredFlowLoadError extends Error {
 /** Same signature as `getAuthoredFlowDefinition`, resolved from wherever a flow was loaded. */
 export type GetFlowDefinition = <Input = unknown>(handle: FlowHandle) => AuthoredFlowDefinition<Input>;
 
+export interface SurfaceModuleAuthority {
+  readonly packageName: '@relayflows/surface';
+  readonly version: string;
+  readonly packageSha256: string;
+  readonly runtimeSha256: string;
+}
+
 export interface LoadedAuthoredFlow {
+  readonly sourcePath: string;
   readonly handle: FlowHandle;
   /**
    * Bound to the SAME `@relayflows/surface` module instance the flow file
@@ -28,6 +38,8 @@ export interface LoadedAuthoredFlow {
    * `getAuthoredFlowDefinition` import.
    */
   readonly getDefinition: GetFlowDefinition;
+  /** Exact Surface package/runtime that owns the handle's WeakMap identity. */
+  readonly surfaceAuthority: SurfaceModuleAuthority;
   /** Dependency-first load order, each canonical absolute path appearing once. */
   readonly graph: readonly LoadedAuthoredFlowNode[];
 }
@@ -36,6 +48,7 @@ export interface LoadedAuthoredFlowNode {
   readonly path: string;
   readonly handle: FlowHandle;
   readonly getDefinition: GetFlowDefinition;
+  readonly surfaceAuthority: SurfaceModuleAuthority;
   readonly use: readonly string[];
 }
 
@@ -58,7 +71,7 @@ export async function loadAuthoredFlow(path: string): Promise<LoadedAuthoredFlow
     if (cached !== undefined) return cached;
     visiting.add(absolutePath);
     try {
-      const { handle, getDefinition } = await importAuthoredFlow(absolutePath);
+      const { handle, getDefinition, surfaceAuthority } = await importAuthoredFlow(absolutePath);
       const dependencies: string[] = [];
       for (const entry of getDefinition(handle).header.use ?? []) {
         // Validate again at the SDK boundary: the author's surface package may
@@ -72,7 +85,7 @@ export async function loadAuthoredFlow(path: string): Promise<LoadedAuthoredFlow
         }
         dependencies.push(child.path);
       }
-      const node = Object.freeze({ path: absolutePath, handle, getDefinition, use: Object.freeze(dependencies) });
+      const node = Object.freeze({ path: absolutePath, handle, getDefinition, surfaceAuthority, use: Object.freeze(dependencies) });
       loaded.set(absolutePath, node);
       return node;
     } catch (error) {
@@ -85,10 +98,11 @@ export async function loadAuthoredFlow(path: string): Promise<LoadedAuthoredFlow
     }
   }
   const root = await visit(resolve(path), true);
-  return Object.freeze({ handle: root.handle, getDefinition: root.getDefinition, graph: Object.freeze([...loaded.values()]) });
+  return Object.freeze({ sourcePath: root.path, handle: root.handle, getDefinition: root.getDefinition,
+    surfaceAuthority: root.surfaceAuthority, graph: Object.freeze([...loaded.values()]) });
 }
 
-async function importAuthoredFlow(path: string): Promise<Pick<LoadedAuthoredFlow, 'handle' | 'getDefinition'>> {
+async function importAuthoredFlow(path: string): Promise<Pick<LoadedAuthoredFlow, 'handle' | 'getDefinition' | 'surfaceAuthority'>> {
   const absolutePath = resolve(path);
   try {
     accessSync(absolutePath, constants.R_OK);
@@ -98,14 +112,14 @@ async function importAuthoredFlow(path: string): Promise<Pick<LoadedAuthoredFlow
 
   let authoredModule: Record<string, unknown>;
   try {
-    authoredModule = await import(pathToFileURL(absolutePath).href) as Record<string, unknown>;
+    authoredModule = await import(/* @vite-ignore */ pathToFileURL(absolutePath).href) as Record<string, unknown>;
   } catch (error) {
     throw new AuthoredFlowLoadError(
       `Flow "${path}" could not be imported: ${errorMessage(error)}`,
     );
   }
 
-  const getDefinition = await resolveGetFlowDefinition(absolutePath, path);
+  const { getDefinition, surfaceAuthority } = await resolveSurfaceRuntime(absolutePath, path);
   const handle = authoredModule['default'] as FlowHandle;
   try {
     getDefinition(handle);
@@ -114,7 +128,7 @@ async function importAuthoredFlow(path: string): Promise<Pick<LoadedAuthoredFlow
       `Flow "${path}" must default-export flow(...): ${errorMessage(error)}`,
     );
   }
-  return { handle, getDefinition };
+  return { handle, getDefinition, surfaceAuthority };
 }
 
 /**
@@ -138,21 +152,27 @@ async function importAuthoredFlow(path: string): Promise<Pick<LoadedAuthoredFlow
  * compatible `@relayflows/surface` is provably resolvable from this same
  * anchor.
  */
-async function resolveGetFlowDefinition(
+async function resolveSurfaceRuntime(
   absolutePath: string,
   displayPath: string,
-): Promise<GetFlowDefinition> {
+): Promise<{ getDefinition: GetFlowDefinition; surfaceAuthority: SurfaceModuleAuthority }> {
   const require = createRequire(pathToFileURL(absolutePath));
   let resolvedRuntimePath: string;
   try {
     resolvedRuntimePath = require.resolve('@relayflows/surface/runtime');
+    // Some ESM test/load hooks return a percent-encoded absolute path without
+    // a file: scheme. Normalize it only when the literal path does not exist.
+    if (!existsSync(resolvedRuntimePath) && resolvedRuntimePath.includes('%')) {
+      const decoded = decodeURI(resolvedRuntimePath);
+      if (existsSync(decoded)) resolvedRuntimePath = decoded;
+    }
   } catch (error) {
     throw new AuthoredFlowLoadError(
       `Flow "${displayPath}" imports @relayflows/surface, but @relayflows/surface/runtime `
         + `could not be resolved from the same location: ${errorMessage(error)}`,
     );
   }
-  const runtimeModule = await import(pathToFileURL(resolvedRuntimePath).href) as {
+  const runtimeModule = await import(/* @vite-ignore */ resolvedRuntimePath) as {
     getFlowDefinition?: unknown;
   };
   if (typeof runtimeModule.getFlowDefinition !== 'function') {
@@ -161,7 +181,70 @@ async function resolveGetFlowDefinition(
         + 'does not export getFlowDefinition — check its @relayflows/surface version.',
     );
   }
-  return runtimeModule.getFlowDefinition as GetFlowDefinition;
+  let packagePath = dirname(resolvedRuntimePath);
+  for (;;) {
+    const candidate = resolve(packagePath, 'package.json');
+    try {
+      const packageBytes = await readFile(candidate);
+      const manifest = JSON.parse(packageBytes.toString('utf8')) as { name?: unknown; version?: unknown };
+      if (manifest.name === '@relayflows/surface') {
+        if (typeof manifest.version !== 'string' || manifest.version.length === 0) {
+          throw new AuthoredFlowLoadError(`Flow "${displayPath}": @relayflows/surface has no pinned package version.`);
+        }
+        const runtimeBytes = await readFile(resolvedRuntimePath);
+        return {
+          getDefinition: runtimeModule.getFlowDefinition as GetFlowDefinition,
+          surfaceAuthority: Object.freeze({
+            packageName: '@relayflows/surface', version: manifest.version,
+            packageSha256: await packageTreeSha256(packagePath),
+            runtimeSha256: createHash('sha256').update(runtimeBytes).digest('hex'),
+          }),
+        };
+      }
+    } catch (error) {
+      if (!(error instanceof SyntaxError) && (error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+    }
+    const parent = dirname(packagePath);
+    if (parent === packagePath) break;
+    packagePath = parent;
+  }
+  throw new AuthoredFlowLoadError(
+    `Flow "${displayPath}": the resolved @relayflows/surface/runtime is not inside its declared package.`,
+  );
+}
+
+/**
+ * Hash the exact installed Surface package payload, including path boundaries.
+ *
+ * npm may materialize a package-local node_modules tree for workspace and
+ * file: dependencies. That tree is installation state, not part of the
+ * published Surface package, and can contain platform-specific .bin symlinks.
+ * Keep it outside the authority boundary while pinning every package payload
+ * file, including the runtime module hashed separately by the caller.
+ */
+export async function packageTreeSha256(root: string): Promise<string> {
+  const files: string[] = [];
+  async function visit(directory: string): Promise<void> {
+    const entries = await readdir(directory, { withFileTypes: true });
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+    for (const entry of entries) {
+      if (directory === root && entry.name === 'node_modules') continue;
+      const path = join(directory, entry.name);
+      if (entry.isDirectory()) await visit(path);
+      else if (entry.isFile()) files.push(path);
+      else throw new AuthoredFlowLoadError(
+        `@relayflows/surface package contains unsupported entry "${relative(root, path)}".`,
+      );
+    }
+  }
+  await visit(root);
+  const hash = createHash('sha256');
+  for (const path of files) {
+    const bytes = await readFile(path);
+    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');
 }
 
 // Exported for callers (internal SDK tests, and any co-located flow that is

package/src/authored-helper-effect.ts

@@ -13,6 +13,7 @@ import { helperProviders, type HelperCall } from '@relayflows/surface/runtime';
 import { helperWriteback, HelperDeliveryError } from './helper-writeback.js';
 import { checkSlackHelpers } from './slack-preflight.js';
 import { atomicJson, readSlackReceipt, receiptPath, slackWriteback, type SlackCall } from './slack-writeback.js';
+import { authoredChildAdmissionKey } from './authored-admission.js';
 
 type ProviderCall = HelperCall | SlackCall;
 
@@ -30,20 +31,21 @@ export function assertHelperCredentials(provider: string): void {
 /** Each helper uses the existing agent lease + effect protocol; no new kernel verb. */
 export async function runHelperEffect(
   journal: JournalClient, name: string, stepId: string, call: ProviderCall,
-  dataDir: string, journalSteps: AuthoredFlowJournalStep[],
+  dataDir: string, journalSteps: AuthoredFlowJournalStep[], rootRunId?: string,
 ): Promise<unknown> {
   assertHelperCredentials(call.provider);
   if (call.provider === 'notion' && call.verb === 'appendBlock' && process.env.RELAYFLOWS_NOTION_MOCK !== '1') {
     throw new AuthoredFlowExecutionError('helper_provider.unsupported', 'Notion appendBlock has no upstream mount writeback route');
   }
-  const stream = `${call.provider}-helper-${randomUUID()}`;
+  const admissionKey = authoredChildAdmissionKey(rootRunId, stepId);
+  const stream = `${call.provider}-helper-${admissionKey?.slice(-32) ?? randomUUID()}`;
   const spec = toKernelSpec(compileSpec({
     version: SPEC_SCHEMA_VERSION, name: `${name}/${stepId}`,
     steps: [{ id: stepId, type: 'agent', instruction: JSON.stringify(call),
       maxIterations: 3, recoveryMode: 'reset',
       surfaces: { streams: [{ stream }], external: [`/${call.provider}`] } }],
   }));
-  const outcome = await journal.runStart(spec);
+  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);

package/src/authored-mcp.ts

@@ -11,6 +11,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';
 
 /** Own keys expose precisely the preflight inventory, including prototype-like names. */
 export function buildMcpProxy(
@@ -49,11 +50,12 @@ export class McpStepError extends AuthoredFlowExecutionError {
 export async function runMcpEffect(
   journal: JournalClient, flowName: string, id: string, server: string, tool: string,
   args: unknown, known: boolean, config: McpServerConfig,
-  journalSteps: AuthoredFlowJournalStep[],
+  journalSteps: AuthoredFlowJournalStep[], rootRunId?: string,
 ): Promise<unknown> {
   const idempotencyKey = `mcp:${server}:${tool}:${createHash('sha256').update(JSON.stringify(args)).digest('hex')}`;
   const surfacePath = `/mcp/${pathPart(server)}/${pathPart(tool)}`;
-  const stream = `mcp-worker-${randomUUID()}`;
+  const admissionKey = authoredChildAdmissionKey(rootRunId, id);
+  const stream = `mcp-worker-${admissionKey?.slice(-32) ?? randomUUID()}`;
   const instruction = JSON.stringify({ type: 'mcp', server, tool, input: args });
   const peer = journal.createPeer();
   let diagnostic: string | undefined;
@@ -132,11 +134,11 @@ export async function runMcpEffect(
       failed(new Error('MCP worker dispatch deadline exceeded'));
     }, 30_000);
     // Propagate a dispatch failure even if run.start itself is still pending.
-    const starting = journal.runStart(spec);
+    const starting = journal.runStart(spec, undefined, admissionKey);
     await Promise.race([starting, completed]);
     const outcome = await starting;
     childRunId = outcome.run_id;
-    await completed;
+    if (outcome.status !== 'completed') await completed;
     if (diagnostic !== undefined) {
       try { await readCompletedStepOutput(journal, outcome.run_id, id, journalSteps); }
       catch (error) {

package/src/authored-node-entry.ts

@@ -0,0 +1,90 @@
+import { Worker } from 'node:worker_threads';
+import { createHash, createHmac } from 'node:crypto';
+import { readFileSync, writeSync } from 'node:fs';
+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 type { AuthoredRootMetadata } from './authored-root.js';
+
+let channelKey: string | undefined, sequence = 0;
+// Capture writers before loading authored modules; credentials never enter env.
+const writeFrame = writeSync, mac = createHmac;
+const send = (message: unknown): void => {
+  const payload = JSON.stringify(message);
+  if (channelKey === undefined) { writeFrame(3, payload + '\n'); return; }
+  const seq = ++sequence;
+  writeFrame(3, JSON.stringify({ seq, payload,
+    mac: mac('sha256', channelKey).update(`${seq}\0${payload}`).digest('hex') }) + '\n');
+};
+const hash = (path: string): string => createHash('sha256').update(readFileSync(path)).digest('hex');
+const controller = new AbortController();
+let finished = false;
+const abort = (): void => {
+  controller.abort();
+  setTimeout(() => process.exit(1), 2000).unref();
+};
+process.on('SIGINT', abort); process.on('SIGTERM', abort);
+// The parent owns the root lease. Do not continue authored effects after it dies.
+process.stdin.on('end', () => { if (!finished) process.exit(1); });
+process.stdin.on('error', () => process.exit(1));
+// A separate event loop enforces parent loss even while authored JS is blocked.
+// Capture the expected PID in the parent's spawn arguments, before any child work.
+const parentPid = parseAuthoredParentPid(process.argv[2]);
+const watchdog = new Worker(`
+  const {parentPort,workerData}=require('node:worker_threads');
+  function check(){if(process.ppid!==workerData.parentPid)process.kill(process.pid,'SIGKILL');}
+  check();setInterval(check,50);parentPort.postMessage('ready');
+`, { eval: true, workerData: { parentPid } });
+// Enforcement must not silently disappear after the readiness Promise settles.
+const watchdogLost = (): void => { if (!finished) process.kill(process.pid, 'SIGKILL'); };
+watchdog.on('error', watchdogLost);
+watchdog.on('exit', watchdogLost);
+let client: JournalClient | undefined;
+try {
+  assertAuthoredNodeVersion();
+  await new Promise<void>((resolve,reject)=>{watchdog.once('message',()=>resolve());watchdog.once('error',reject);});
+  send({ type: 'ready', runtime: { kind: 'node', version: process.versions.node,
+    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 }>((resolve, reject) => {
+    let buffer = '';
+    process.stdin.setEncoding('utf8');
+    const onData = (chunk: string): void => {
+      buffer += chunk;
+      if (Buffer.byteLength(buffer) > 2 * 1024 * 1024) { reject(new Error('authored runtime request exceeded limit')); return; }
+      const end = buffer.indexOf('\n');
+      if (end < 0) return;
+      process.stdin.off('data', onData);
+      try { resolve(JSON.parse(buffer.slice(0, end))); } catch { reject(new Error('invalid authored runtime request')); }
+    };
+    process.stdin.on('data', onData);
+  });
+  if (typeof request.channelKey !== 'string' || !/^[a-f0-9]{64}$/.test(request.channelKey)) throw new Error('invalid authored channel key');
+  channelKey = request.channelKey;
+  controller.signal.throwIfAborted();
+  const loaded = await loadPinnedAuthoredSource(request.metadata, true);
+  if (request.localAgentStream !== request.metadata.localAgentStream) throw new Error('authored root local agent surface mismatch');
+  client = new JournalClient(request.socketPath);
+  await client.connect(); await client.hello('flows-authored-node');
+  const result = await executeAuthoredFlow(loaded.handle, client,
+    request.metadata.inputPresent ? request.metadata.input : undefined, {
+      getDefinition: loaded.getDefinition, dataDir: request.dataDir,
+      flowPath: request.metadata.flowPath, rootRunId: request.rootRunId,
+      localAgentStream: request.localAgentStream, signal: controller.signal,
+      onProgress: event => send({ type: 'progress', event }),
+      onWait: event => send({ type: 'wait', event }),
+    });
+  send({ type: 'result', result });
+} catch (error) {
+  const message = error instanceof Error ? error.message : 'authored body failed';
+  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 } : {}) });
+  process.exitCode = 1;
+} finally {
+  finished = true; await watchdog.terminate(); client?.close(); process.stdin.destroy();
+  process.off('SIGINT', abort); process.off('SIGTERM', abort);
+}

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