@relayflows/sdk 2.0.11 → 2.0.13

package/src/authored-budget.ts

@@ -2,14 +2,31 @@ import { BudgetSyntaxError, parseBudget, toKernelBudget } from './budget.js';
 import { AuthoredFlowExecutionError } from './authored-flow-error.js';
 import type { JournalClient } from './journal-client.js';
 import type { RunOutcome } from './protocol.js';
-import type { KernelBudgetSpec, KernelRunSpec } from './spec.js';
+import type { KernelBudgetSpec, KernelPriorSpend, KernelRunSpec } from './spec.js';
+
+/**
+ * One journaled charge, in the accumulator's exact integer form.
+ *
+ * `unmetered` mirrors the journal's `budget.dollars_unmetered`: the charge
+ * spent tokens whose dollar cost is unknown, so its `micro` is a lower bound
+ * and not a measured amount. It is carried, not derived from `micro`, because
+ * an unmetered charge and a genuinely free charge both report zero dollars.
+ */
+interface Charge {
+  input: bigint;
+  output: bigint;
+  micro: bigint;
+  ms: bigint;
+  day: number;
+  unmetered: boolean;
+}
 
 /** Serialized admission for the internal authored runner's separate step runs. */
 export class AuthoredBudget {
   private readonly limit: KernelBudgetSpec | undefined;
   private failed = false;
   private tail: Promise<unknown> = Promise.resolve();
-  private charges: { input: bigint; output: bigint; micro: bigint; ms: bigint; day: number }[] = [];
+  private charges: Charge[] = [];
 
   constructor(header: unknown) {
     try {
@@ -20,8 +37,9 @@ export class AuthoredBudget {
     }
   }
 
-  async execute<T>(journal: JournalClient, spec: KernelRunSpec, consume: (outcome: RunOutcome) => Promise<T>): Promise<T> {
-    if (this.limit === undefined) return consume(await journal.runStart(spec));
+  async execute<T>(journal: JournalClient, spec: KernelRunSpec,
+    consume: (outcome: RunOutcome) => Promise<T>, admissionKey?: string): Promise<T> {
+    if (this.limit === undefined) return consume(await journal.runStart(spec, undefined, admissionKey));
     const previous = this.tail;
     let release!: () => void;
     this.tail = new Promise<void>(resolve => { release = resolve; });
@@ -31,14 +49,22 @@ export class AuthoredBudget {
       // Window selection follows journal timestamps, never the SDK host clock.
       const day = this.charges.at(-1)?.day;
       const total = this.charges.filter(c => this.limit!.window !== 'day' || c.day === day)
-        .reduce((s, c) => ({ input: s.input + c.input, output: s.output + c.output, micro: s.micro + c.micro, ms: s.ms + c.ms }),
-          { input: 0n, output: 0n, micro: 0n, ms: 0n });
+        .reduce((s, c) => ({ input: s.input + c.input, output: s.output + c.output, micro: s.micro + c.micro, ms: s.ms + c.ms,
+          // Sticky, exactly as the kernel's running total is: once any charge
+          // in the window was unmetered, the carried dollars are a lower bound.
+          unmetered: s.unmetered || c.unmetered }),
+          { input: 0n, output: 0n, micro: 0n, ms: 0n, unmetered: false });
       const exactNumber = (n: bigint) => { if (n > BigInt(Number.MAX_SAFE_INTEGER)) throw new Error('budget counter overflow'); return Number(n); };
-      const outcome = await journal.runStart({ ...spec, budget: { ...this.limit, prior_spend: {
+      // One explicit conversion to the shared carried-spend shape, so a new
+      // accounting field is added here rather than silently dropped inline.
+      const priorSpend: KernelPriorSpend = {
         tokens_in: exactNumber(total.input), tokens_out: exactNumber(total.output),
         dollars: `${total.micro / 1_000_000n}.${String(total.micro % 1_000_000n).padStart(6, '0')}`,
-        wallclock_ms: exactNumber(total.ms), ...(this.limit.window === 'day' && day !== undefined ? { day } : {}),
-      } } });
+        wallclock_ms: exactNumber(total.ms),
+        ...(this.limit.window === 'day' && day !== undefined ? { day } : {}),
+        ...(total.unmetered ? { dollars_unmetered: true as const } : {}),
+      };
+      const outcome = await journal.runStart({ ...spec, budget: { ...this.limit, prior_spend: priorSpend } }, undefined, admissionKey);
       try {
         if (outcome.completion_reason === 'budget_exceeded') throw new AuthoredFlowExecutionError('step_failed', 'Flow budget exceeded before the next step.', 'budget_exceeded', outcome.run_id);
         return await consume(outcome);
@@ -48,7 +74,7 @@ export class AuthoredBudget {
           const { entries } = await journal.journalRead(outcome.run_id, seq);
           if (entries.length === 0) break;
           for (const raw of entries) {
-            const e = raw as {seq: number; entry_type: string; at_ms: number; payload: {budget?: {tokens_in: number; tokens_out: number; dollars: string}; spend?: {wallclock_ms: number}}};
+            const e = raw as {seq: number; entry_type: string; at_ms: number; payload: {budget?: {tokens_in: number; tokens_out: number; dollars: string; dollars_unmetered?: boolean}; spend?: {wallclock_ms: number}}};
             seq = e.seq + 1;
             if (!['step.completed', 'memory.injected'].includes(e.entry_type)) continue;
             const b = e.payload.budget;
@@ -57,7 +83,8 @@ export class AuthoredBudget {
             if (fraction.length > 6 && /[1-9]/.test(fraction.slice(6))) throw new Error('budget accounting requires microdollar precision');
             this.charges.push({input: BigInt(b.tokens_in), output: BigInt(b.tokens_out),
               micro: BigInt(whole!) * 1_000_000n + BigInt(fraction.slice(0, 6).padEnd(6, '0')),
-              ms: BigInt(e.payload.spend?.wallclock_ms ?? 0), day: Math.floor(e.at_ms / 86_400_000)});
+              ms: BigInt(e.payload.spend?.wallclock_ms ?? 0), day: Math.floor(e.at_ms / 86_400_000),
+              unmetered: b.dollars_unmetered === true});
           }
         }
       }

package/src/authored-flow-error.ts

@@ -9,7 +9,6 @@ export type AuthoredFlowExecutionErrorCode =
   | 'helper_slack.credential_missing'
   | 'helper_slack.mount_required'
   | 'budget_syntax_invalid'
-  | 'budget_missing_price'
   | 'agent_cli_unresolved'
   | 'agent_parked'
   | 'llm_cli_unresolved'

package/src/authored-flow-executor.ts

@@ -1,3 +1,4 @@
+import { assertAuthoredPromiseHooks } from './authored-runtime-capability.js';
 import { pluginHelpers } from './plugin-loader.js';
 import { runPluginEffect } from './authored-plugin-effect.js';
 import { randomUUID } from 'node:crypto';
@@ -71,7 +72,16 @@ export interface AuthoredFlowJournalStep {
   readonly completionReason: ProtocolCompletionReason;
 }
 
+export interface AuthoredExecutionRuntime {
+  readonly kind: 'node';
+  readonly version: string;
+  readonly executableSha256: string;
+  readonly payloadSha256: string;
+}
+
 export interface AuthoredFlowExecutionResult {
+  readonly executionRuntime?: AuthoredExecutionRuntime;
+  readonly rootRunId?: string;
   readonly name: string;
   readonly completionReason: FlowCompletionReason;
   readonly journalSteps: readonly AuthoredFlowJournalStep[];
@@ -122,6 +132,8 @@ export interface ExecuteAuthoredFlowOptions {
   readonly onWait?: RunLifecycleOptions['onWait'];
   readonly onProgress?: (event: ProgressEvent) => void;
   readonly localAgentStream?: string;
+  /** Durable kernel root that owns this body's child admission identities. */
+  readonly rootRunId?: string;
 }
 
 export async function executeAuthoredFlow<Input = undefined>(
@@ -130,11 +142,17 @@ export async function executeAuthoredFlow<Input = undefined>(
   input?: Input,
   options: ExecuteAuthoredFlowOptions = {},
 ): Promise<AuthoredFlowExecutionResult> {
+  assertAuthoredPromiseHooks();
   const getDefinition = options.getDefinition ?? getAuthoredFlowDefinition;
   const localAgentStream = options.localAgentStream;
   const onProgress = options.onProgress;
   const flowPath = options.flowPath ?? join(process.cwd(), 'flow.ts');
   const waitOptions: RunLifecycleOptions = {
+    // Carried so a failed `f.agent` can name the journal that holds its
+    // evidence. Each authored worker call runs as its own kernel run, and
+    // without the data dir the diagnostic can name the run id but not where
+    // on disk to read it.
+    ...(options.dataDir !== undefined ? { dataDir: options.dataDir } : {}),
     ...(options.signal !== undefined ? { signal: options.signal } : {}),
     ...(options.onWait !== undefined ? { onWait: options.onWait } : {}),
   };
@@ -173,9 +191,14 @@ export async function executeAuthoredFlow<Input = undefined>(
   let nextStep = 1;
   let requestedCompletion: FlowCompletionReason | undefined;
 
-  const lowerDeterministic = authoredDeterministicRunner(definition.name, journal, journalSteps, budget);
+  const lowerDeterministic = authoredDeterministicRunner(
+    definition.name, journal, journalSteps, budget, options.rootRunId,
+  );
 
-  const worker = authoredWorkerRunner(definition, journal, flowPath, journalSteps, waitOptions, localAgentStream, budget, definition.header.budget);
+  const worker = authoredWorkerRunner(
+    definition, journal, flowPath, journalSteps, waitOptions,
+    localAgentStream, budget, definition.header.budget, options.rootRunId,
+  );
 
   function llmOperation(strings: TemplateStringsArray, ...values: unknown[]): Step<string>;
   function llmOperation(prompt: string, options: LlmOptions): Step<unknown>;
@@ -205,7 +228,7 @@ export async function executeAuthoredFlow<Input = undefined>(
     return trackStep(authoredSteps, llmOp);
   }
 
-  const slackRun = randomUUID();
+  const slackRun = options.rootRunId ?? randomUUID();
   function slackOperation<T>(call: SlackCall): Step<T> {
     assertOperationAllowed(`slack.${call.verb}`, definition.name, requestedCompletion);
     const snapshot = snapshotJsonValue(call, 'f.slack call') as unknown as SlackCall;
@@ -215,7 +238,7 @@ export async function executeAuthoredFlow<Input = undefined>(
       () => assertOperationAllowed(`slack.${call.verb}`, definition.name, requestedCompletion),
       async () => {
         const receipt = await runHelperEffect(journal, definition.name, id, snapshot,
-          options.dataDir ?? dirname(journal.socketPath), journalSteps);
+          options.dataDir ?? dirname(journal.socketPath), journalSteps, options.rootRunId);
         return (call.verb === 'react' ? undefined : receipt) as T;
       },
       lifecycle,
@@ -231,7 +254,7 @@ export async function executeAuthoredFlow<Input = undefined>(
       return trackStep(authoredSteps, new AuthoredFlowOperation<T>(id, verb,
         () => assertOperationAllowed(verb, definition.name, requestedCompletion),
         async () => await runHelperEffect(journal, definition.name, id, snapshot,
-          options.dataDir ?? dirname(journal.socketPath), journalSteps) as T,
+          options.dataDir ?? dirname(journal.socketPath), journalSteps, options.rootRunId) as T,
         lifecycle));
     }),
     slack: {
@@ -247,7 +270,7 @@ export async function executeAuthoredFlow<Input = undefined>(
         id, 'mcp',
         () => assertOperationAllowed('mcp', definition.name, requestedCompletion),
         () => runMcpEffect(journal, definition.name, id, server, tool, args,
-          known, checkedMcp.servers[server]!, journalSteps),
+          known, checkedMcp.servers[server]!, journalSteps, options.rootRunId),
         lifecycle,
       ));
     }),
@@ -327,7 +350,8 @@ export async function executeAuthoredFlow<Input = undefined>(
     const id = `plugin-${nextStep++}`;
     return trackStep(authoredSteps, new AuthoredFlowOperation(
       id, label, () => assertOperationAllowed(label, definition.name, requestedCompletion),
-      () => runPluginEffect(journal, definition.name, id, plugin, verb, args, journalSteps, budget),
+      () => runPluginEffect(journal, definition.name, id, plugin, verb, args,
+        journalSteps, budget, options.rootRunId),
       lifecycle,
     ));
   }));
@@ -387,6 +411,7 @@ export async function executeAuthoredFlow<Input = undefined>(
   await lowerDeterministic(`complete-${nextStep}`, requestedCompletion === 'needs_human'
     ? `printf '%s' '{"completionReason":"needs_human"}'` : ':', true);
   return Object.freeze({
+    ...(options.rootRunId === undefined ? {} : { rootRunId: options.rootRunId }),
     name: definition.name,
     completionReason: requestedCompletion,
     journalSteps: Object.freeze([...journalSteps]),

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);
+}