@relayflows/sdk 2.0.50 → 2.0.52

package/src/authored-preflight.ts

@@ -13,16 +13,16 @@ export function authoredPreflight(path: string, environment?: NodeJS.ProcessEnv)
   return async (flow: FlowSpec) => {
     let config: ProjectConfig;
     try { config = readProjectConfig(directory); }
-    catch { return checkAuthoredFlow(flow, path); }
+    catch { return checkAuthoredFlow(flow, path, undefined, { environment }); }
     const resolved = resolvePreflight(flow, {
       projectCli: config.cli, projectConfigPath: config.path, projectSearchStart: directory,
       models: config.models, modelRegistryPath: config.modelRegistryPath,
     });
-    if (!resolved.ok) return checkAuthoredFlow(flow, path, config);
+    if (!resolved.ok) return checkAuthoredFlow(flow, path, config, { environment });
     await Promise.all(resolved.resolutions.map(async resolution => {
       const step = resolved.compiled!.steps.find(step => step.id === resolution.stepId)!;
       const managed = step.type === 'agent' && communicationInstruction(step.instruction) !== undefined;
-      const key = cliProbeKey(resolution, managed);
+      const key = cliProbeKey(resolution, managed, step.secrets);
       if (probeCache.has(key)) return;
       let probing = pending.get(key);
       if (probing === undefined) {
@@ -30,7 +30,7 @@ export function authoredPreflight(path: string, environment?: NodeJS.ProcessEnv)
           try {
             probeCache.set(key, { result: await probeCliAsync(resolution.cli,
               resolution.source === 'project' ? config.directory : directory,
-              resolution.model, managed ? 'managed' : undefined, environment) });
+              resolution.model, managed ? 'managed' : undefined, environment, step.secrets) });
           } catch (error) {
             probeCache.set(key, { failure: error instanceof CliProbeError ? error.detail : null });
           }

package/src/authored-promise-graph.ts

@@ -30,12 +30,15 @@ export class AuthoredPromiseGraph {
   private readonly triggers = new Map<number, number>();
   private readonly creationContexts = new Map<number, number>();
   private readonly resolutionCauses = new Map<number, number>();
+  /** Promises attributed only when another promise's reaction resolved them. */
+  private readonly adoptedFromResolvingContext = new Set<number>();
   private readonly promiseIds = new WeakMap<object, number>();
   private readonly handles = new Map<number, Promise<unknown>>();
   private readonly unattributedChildren = new Map<number, number[]>();
   private readonly attributedRoots = new Map<number, number>();
   private readonly roots = new Set<number>();
   private readonly pending = new Set<number>();
+  private readonly combinatorCaptures: Set<number>[] = [];
   private dependencyCache: { readonly start: number; readonly found: ReadonlySet<number>; readonly version: number } | undefined;
   /** Bumped by every graph change, so derived answers can be cached between changes. */
   private changes = 0;
@@ -52,6 +55,7 @@ export class AuthoredPromiseGraph {
         this.triggers.set(asyncId, triggerAsyncId);
         this.creationContexts.set(asyncId, executionAsyncId());
         this.promiseIds.set(resource, asyncId);
+        for (const capture of this.combinatorCaptures) capture.add(asyncId);
         this.handles.set(asyncId, resource as Promise<unknown>);
         this.pending.add(asyncId);
         const root = this.roots.has(triggerAsyncId)
@@ -77,6 +81,7 @@ export class AuthoredPromiseGraph {
         // success. Measured; see ops/probes/pr134-repair-0903/combinators.mjs.
         const adopted = this.attributedRoots.get(cause);
         if (adopted !== undefined) {
+          this.adoptedFromResolvingContext.add(asyncId);
           this.attribute(asyncId, adopted);
           return;
         }
@@ -100,6 +105,18 @@ export class AuthoredPromiseGraph {
     return this.promiseIds.get(value);
   }
 
+  isPending(asyncId: number): boolean {
+    return this.pending.has(asyncId);
+  }
+
+  /** The intrinsic creates per-member reaction promises as well as its aggregate. */
+  captureCombinator<T>(call: () => T): { readonly value: T; readonly created: ReadonlySet<number> } {
+    const created = new Set<number>();
+    this.combinatorCaptures.push(created);
+    try { return { value: call(), created }; }
+    finally { this.combinatorCaptures.pop(); }
+  }
+
   /** Mark a promise whose descendants belong to an authored operation. */
   registerRoot(asyncId: number): void {
     if (asyncId <= 0 || this.roots.has(asyncId)) return;
@@ -145,6 +162,22 @@ export class AuthoredPromiseGraph {
     return causes;
   }
 
+  /**
+   * A promise created directly in one async context but settled in another
+   * can be a join. Its resolution edge names only the settling member, so a
+   * frontier may use it only when a combinator registered all members.
+   */
+  hasUnobservedJoinShape(asyncId: number): boolean {
+    const trigger = this.triggers.get(asyncId);
+    const resolution = this.resolutionCauses.get(asyncId);
+    return trigger !== undefined && trigger === this.creationContexts.get(asyncId)
+      && resolution !== undefined && resolution !== trigger;
+  }
+
+  wasAdoptedFromResolvingContext(asyncId: number): boolean {
+    return this.adoptedFromResolvingContext.has(asyncId);
+  }
+
   dependsOn(descendant: number, ancestor: number): boolean {
     return this.dependenciesOf(descendant).has(ancestor);
   }
@@ -167,11 +200,13 @@ export class AuthoredPromiseGraph {
     this.triggers.clear();
     this.creationContexts.clear();
     this.resolutionCauses.clear();
+    this.adoptedFromResolvingContext.clear();
     this.handles.clear();
     this.unattributedChildren.clear();
     this.attributedRoots.clear();
     this.roots.clear();
     this.pending.clear();
+    this.combinatorCaptures.length = 0;
     this.dependencyCache = undefined;
   }
 

package/src/authored-root-readback.ts

@@ -3,7 +3,6 @@ import type { AuthoredFlowExecutionResult } from './authored-flow-executor.js';
 import { AuthoredFlowExecutionError } from './authored-flow-error.js';
 import { isSurfaceCompletionReason } from './authored-step-output.js';
 import { JournalFrameError, JournalProtocolError, type JournalClient } from './journal-client.js';
-import type { RunOutcome } from './protocol.js';
 
 /*
  * Reading an authored root back from its journal, and what a failed read
@@ -44,7 +43,7 @@ export async function rootStepIfPresent(journal: JournalClient, runId: string):
  * it back is interrupted, the outcome is still known: say so, rather than
  * recasting a finished run as resumable.
  */
-export function completedResult(journal: JournalClient, outcome: RunOutcome, rootRunId: string): Promise<AuthoredFlowExecutionResult & { readonly rootRunId: string }> {
+export function completedResult(journal: JournalClient, rootRunId: string): Promise<AuthoredFlowExecutionResult & { readonly rootRunId: string }> {
   return completedRootResult(journal, rootRunId).catch(error => {
     // A bad frame or a journal with no stored result is a definite fact; any
     // other failure — interrupted, canceled, or a daemon-side read error such

package/src/authored-root.ts

@@ -6,7 +6,7 @@ import { readFile } from 'node:fs/promises';
 import { canonicalize } from './canonical.js';
 import { compileSpec, toKernelSpec } from './compile.js';
 import { executeAuthoredFlow, type AuthoredFlowExecutionResult, type AuthoredFlowSuspendedResult } from './authored-flow-executor.js';
-import { AUTHORED_ROOT_KIND } from './authored-verdict.js';
+import { AUTHORED_PARALLEL_ROOT_KIND, AUTHORED_ROOT_KIND } from './authored-verdict.js';
 import {
   loadAuthoredFlow,
   type LoadedAuthoredFlow,
@@ -23,6 +23,7 @@ import { helperReceiptWaitId, releaseHelperReceiptWaits } from './helper-park.js
 import { readSubscriptionPark } from './authored-subscription-park.js';
 import { localAgentCredentialEnvironment } from './local-agent-environment.js';
 import { completedResult, rootKernelStep, rootStepIfPresent } from './authored-root-readback.js';
+import { parallelPromiseIntrinsicsIntact } from './authored-flow-lifecycle.js';
 
 export type DurableAuthoredFlowResult =
   | (AuthoredFlowExecutionResult & { readonly rootRunId: string })
@@ -42,7 +43,7 @@ export interface AuthoredRootExtension {
 }
 
 export interface AuthoredRootMetadata {
-  readonly kind: typeof ROOT_KIND;
+  readonly kind: typeof ROOT_KIND | typeof AUTHORED_PARALLEL_ROOT_KIND;
   readonly flowName: string;
   readonly flowPath: string;
   readonly sourceSha256: string;
@@ -50,6 +51,10 @@ export interface AuthoredRootMetadata {
   readonly sources: readonly AuthoredRootSourceAuthority[];
   /** Plugin-level provenance in lock order; empty when the project declares none. */
   readonly extensions: readonly AuthoredRootExtension[];
+  /** Absent on roots admitted before causal identities existed. */
+  readonly identityVersion?: 2;
+  /** Immutable admission choice; serial uses the 2.0.50 child identity contract. */
+  readonly executionMode?: 'serial' | 'parallel';
   readonly localAgentStream?: string;
   readonly inputPresent: boolean;
   readonly input?: unknown;
@@ -89,8 +94,19 @@ export async function executeDurableAuthoredFlow(
     surface: node.surfaceAuthority,
   })));
   const definition = loaded.getDefinition(loaded.handle);
+  let parallelEligible = false;
+  if (loaded.graph.length === 1 && (loaded.extensions?.length ?? 0) === 0
+    && definition.header.budget === undefined && parallelPromiseIntrinsicsIntact()) {
+    // The parser is needed only for an authored run, never for an ordinary
+    // CLI check or watch reload. Recheck intrinsics after the async import;
+    // author code could have replaced them while it was loading.
+    const { parallelRunEligible } = await import('./authored-parallel-eligibility.js');
+    parallelEligible = parallelPromiseIntrinsicsIntact()
+      && parallelRunEligible(definition.body, source.toString('utf8'));
+  }
+  const executionMode = parallelEligible ? 'parallel' : 'serial';
   const metadata: AuthoredRootMetadata = Object.freeze({
-    kind: ROOT_KIND,
+    kind: executionMode === 'parallel' ? AUTHORED_PARALLEL_ROOT_KIND : ROOT_KIND,
     flowName: definition.name,
     flowPath: loaded.sourcePath,
     sourceSha256: sha256(source),
@@ -99,6 +115,8 @@ export async function executeDurableAuthoredFlow(
     extensions: Object.freeze((loaded.extensions ?? []).map(extension => Object.freeze({
       name: extension.name, digest: extension.digest, ref: extension.ref,
     }))),
+    identityVersion: 2,
+    executionMode,
     ...(options.localAgentStream === undefined ? {} : { localAgentStream: options.localAgentStream }),
     inputPresent: input !== undefined,
     ...(input === undefined ? {} : { input: jsonSnapshot(input, 'authored root input') }),
@@ -121,7 +139,7 @@ export async function executeDurableAuthoredFlow(
     options.lifecycle?.onRunReceipt?.({ runId: outcome.run_id, flow: definition.name });
     if (outcome.status === 'completed') {
       dispatchWait.cancel();
-      return await completedResult(journal, outcome, outcome.run_id);
+      return await completedResult(journal, outcome.run_id);
     }
     assertRootCanDispatch(outcome);
     await releaseHelperReceiptWaits(journal, outcome.run_id);
@@ -152,11 +170,23 @@ export async function resumeDurableAuthoredFlow(
 ): Promise<DurableAuthoredFlowResult | 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 completed = await completedParallelRootOrAssertRuntime(metadata, rootRunId, journal);
+  if (completed !== undefined) {
+    options.lifecycle?.onRunReceipt?.({ runId: rootRunId, flow: metadata.flowName });
+    return completed;
+  }
+  assertAuthoredRuntimeAvailable();
+  const loaded = await loadPinnedAuthoredSource(metadata);
+  // Source loading itself can alter a process-wide intrinsic. Refuse before
+  // run.resume dispatches a pinned parallel root in that environment.
+  const completedAfterLoad = await completedParallelRootOrAssertRuntime(metadata, rootRunId, journal);
+  if (completedAfterLoad !== undefined) {
+    options.lifecycle?.onRunReceipt?.({ runId: rootRunId, flow: metadata.flowName });
+    return completedAfterLoad;
+  }
   const stream = rootStreamFromMetadata(await rootKernelStep(journal, rootRunId));
   const peer = journal.createPeer();
   await peer.connect();
@@ -173,7 +203,7 @@ export async function resumeDurableAuthoredFlow(
     options.lifecycle?.onRunReceipt?.({ runId: rootRunId, flow: metadata.flowName });
     if (outcome.status === 'completed') {
       dispatchWait.cancel();
-      return await completedResult(journal, outcome, rootRunId);
+      return await completedResult(journal, rootRunId);
     }
     assertRootCanDispatch(outcome);
     await assertNoOpenHumanWait(journal, outcome);
@@ -189,6 +219,22 @@ export async function resumeDurableAuthoredFlow(
   }
 }
 
+async function completedParallelRootOrAssertRuntime(
+  metadata: AuthoredRootMetadata, rootRunId: string, journal: JournalClient,
+): Promise<DurableAuthoredFlowResult | undefined> {
+  if (metadata.identityVersion !== 2 || metadata.executionMode !== 'parallel'
+    || parallelPromiseIntrinsicsIntact()) return undefined;
+  // A completed root has nothing left to dispatch. A read-only snapshot avoids
+  // refusing it under a preload while preserving the pre-dispatch guard for
+  // an active root. Readback still uses the journaled authored verdict.
+  const snapshot = await journal.runGet(rootRunId);
+  if (snapshot.status === 'completed') return completedResult(journal, rootRunId);
+  const error = new AuthoredFlowExecutionError('unsafe_parallel_runtime',
+    `pinned parallel root ${rootRunId} cannot resume while a Promise or Array intrinsic is replaced or a Node preload is active. The run remains resumable in a clean process.`);
+  error.rootRunId = rootRunId;
+  throw error;
+}
+
 /**
  * A root parked on an unanswered `f.human` will not be dispatched: the
  * kernel holds it in `needs_human` until `event.emit` closes the wait. Report
@@ -353,6 +399,8 @@ async function driveRoot(
             ...(options.agentEnvironment === undefined ? {} : { agentEnvironment: options.agentEnvironment }),
             ...(options.workerCapacity === undefined ? {} : { workerCapacity: options.workerCapacity }),
             rootRunId: dispatch.run_id,
+            executionMode: metadata.identityVersion === 2 && metadata.executionMode === 'parallel'
+              ? 'parallel' : 'serial',
             extensions: loaded.extensions,
             flowGraph: loaded.graph,
             ...options.lifecycle,
@@ -600,7 +648,10 @@ function isRootMetadata(value: unknown): value is AuthoredRootMetadata {
   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'
+  return (root.kind === ROOT_KIND || root.kind === AUTHORED_PARALLEL_ROOT_KIND)
+    && (root.kind !== AUTHORED_PARALLEL_ROOT_KIND
+      || (root.identityVersion === 2 && root.executionMode === 'parallel'))
+    && 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 ?? '')
@@ -608,7 +659,9 @@ function isRootMetadata(value: unknown): value is AuthoredRootMetadata {
     && Array.isArray(sources) && sources.length > 0 && sources.every(isRootSourceAuthority)
     && (root.extensions === undefined || (Array.isArray(root.extensions) && root.extensions.every(isRootExtension)))
     && (root.localAgentStream === undefined
-      || /^local-agent-[a-f0-9-]+$/.test(root.localAgentStream));
+      || /^local-agent-[a-f0-9-]+$/.test(root.localAgentStream))
+    && ((root.identityVersion === undefined && root.executionMode === undefined)
+      || (root.identityVersion === 2 && (root.executionMode === 'serial' || root.executionMode === 'parallel')));
 }
 
 function isRootExtension(value: unknown): value is AuthoredRootExtension {

package/src/authored-step-graph.ts

@@ -32,14 +32,16 @@ import { MAX_AFTER, displayLabel, type AuthoredStepEdges } from './authored-step
  * body walks a few nodes per step. A walk that still exceeds `walkLimit` stops
  * and says so (`afterTruncated`) rather than guessing silently.
  *
- * This is observational metadata: it never gates execution, and it changes no
- * step id, admission key or resume identity.
+ * Most consumers use this as observational metadata. Parallel f.run follow-up
+ * IDs also use the causal frontier; the executor refuses a truncated frontier
+ * rather than choosing a replay key from incomplete predecessors.
  */
 export const MAX_WALK = 10_000;
 
 interface Frontier {
   readonly steps: readonly string[];
   readonly truncated: boolean;
+  readonly unregisteredAggregate: boolean;
 }
 
 interface StepNode {
@@ -62,6 +64,7 @@ const EXPANDS_ON: Readonly<Record<Combinator, Outcome | 'always' | undefined>> =
 
 interface Aggregate {
   readonly promise: Promise<unknown>;
+  readonly combinator: Combinator;
   /** Cached once settled: a settled promise never changes state. */
   outcome?: Outcome;
   readonly expandsOn: Outcome | 'always';
@@ -71,6 +74,10 @@ interface Aggregate {
 export class AuthoredStepGraph {
   private readonly stepPromises = new Map<number, string>();
   private readonly aggregates = new Map<number, Aggregate>();
+  private readonly registeredAggregates = new Set<number>();
+  private readonly registeredCombinatorInternals = new Set<number>();
+  private readonly certifiedMembers = new Set<number>();
+  private readonly unsafeAggregates = new Set<number>();
   private readonly contexts = new Map<number, Frontier>();
   private readonly nodes = new Map<string, StepNode>();
   private readonly edges = new Map<string, AuthoredStepEdges>();
@@ -78,6 +85,7 @@ export class AuthoredStepGraph {
   constructor(
     private readonly causesOf: (asyncId: number) => readonly number[],
     private readonly walkLimit = MAX_WALK,
+    private readonly unobservedJoinShape: (asyncId: number) => boolean = () => false,
   ) {}
 
   /** A combinator's aggregate and its members, for expansion once it settles. */
@@ -86,10 +94,19 @@ export class AuthoredStepGraph {
     promise: Promise<unknown>,
     combinator: Combinator,
     members: readonly number[],
+    created: ReadonlySet<number> = new Set(),
   ): void {
+    this.registeredAggregates.add(aggregateId);
+    for (const id of created) this.registeredCombinatorInternals.add(id);
+    if (combinator === 'race' || combinator === 'any') this.unsafeAggregates.add(aggregateId);
     const expandsOn = EXPANDS_ON[combinator];
     if (expandsOn === undefined || members.length === 0) return;
-    this.aggregates.set(aggregateId, { promise, expandsOn, members });
+    this.aggregates.set(aggregateId, { promise, combinator, expandsOn, members });
+  }
+
+  /** Only direct steps and branch calls proven by the body grammar are safe members. */
+  certifyMember(asyncId: number): void {
+    this.certifiedMembers.add(asyncId);
   }
 
   /**
@@ -119,10 +136,19 @@ export class AuthoredStepGraph {
     return this.edges.get(step);
   }
 
+  /** Causal predecessors of a step being declared in the current async context. */
+  predecessorsAt(contextId: number): Frontier {
+    return this.frontierOf(contextId);
+  }
+
   /** Drop the walk state; recorded edges stay readable for late record writes. */
   release(): void {
     this.stepPromises.clear();
     this.aggregates.clear();
+    this.registeredAggregates.clear();
+    this.registeredCombinatorInternals.clear();
+    this.certifiedMembers.clear();
+    this.unsafeAggregates.clear();
     this.contexts.clear();
     this.nodes.clear();
   }
@@ -132,6 +158,7 @@ export class AuthoredStepGraph {
     if (memo !== undefined) return memo;
     const candidates = new Set<string>();
     let truncated = false;
+    let unregisteredAggregate = false;
     const visited = new Set<number>([start]);
     const queue = [start];
     // Breadth-first, so that a walk cut short by the limit has already found
@@ -143,10 +170,24 @@ export class AuthoredStepGraph {
         candidates.add(step);
         continue;
       }
+      // A join's resolution edge contains only its settling member. In
+      // parallel mode the full member list is safe only if our combinator
+      // observer registered it before the promise settled. The creation and
+      // resolution contexts also catch an unobserved join created after a
+      // previous step, where root-adoption alone cannot detect it.
+      const aggregate = this.aggregates.get(current);
+      const rejectedAll = aggregate?.combinator === 'all'
+        && promiseOutcome(aggregate.promise) === 'rejected';
+      const possibleJoin = this.unsafeAggregates.has(current) || rejectedAll
+        || (this.unobservedJoinShape(current)
+        && !this.registeredAggregates.has(current) && !this.certifiedMembers.has(current)
+        && !this.registeredCombinatorInternals.has(current));
+      unregisteredAggregate ||= possibleJoin;
       const answered = current === start ? undefined : this.contexts.get(current);
       if (answered !== undefined) {
         for (const found of answered.steps) candidates.add(found);
         truncated ||= answered.truncated;
+        unregisteredAggregate ||= answered.unregisteredAggregate;
         continue;
       }
       for (const id of [...this.waitedFor(current), ...this.causesOf(current)]) {
@@ -162,7 +203,11 @@ export class AuthoredStepGraph {
       }
     }
     const reduced = this.reduce(candidates);
-    const frontier = Object.freeze({ steps: reduced.steps, truncated: truncated || reduced.truncated });
+    const frontier = Object.freeze({
+      steps: reduced.steps,
+      truncated: truncated || reduced.truncated,
+      unregisteredAggregate,
+    });
     this.contexts.set(start, frontier);
     return frontier;
   }
@@ -184,7 +229,7 @@ export class AuthoredStepGraph {
    * reduction reads recorded `after` lists; when one it reads is incomplete,
    * a redundant ancestor can survive, and the result says so.
    */
-  private reduce(candidates: ReadonlySet<string>): Frontier {
+  private reduce(candidates: ReadonlySet<string>): Pick<Frontier, 'steps' | 'truncated'> {
     const ordered = [...candidates].sort((a, b) => this.orderOf(a) - this.orderOf(b));
     if (ordered.length <= 1) return { steps: ordered, truncated: false };
     // An ancestor is always registered before its descendant, so nothing

package/src/authored-step-index.ts

@@ -150,7 +150,8 @@ export async function alsoRecord(
  * Fold the root's stream back into one record per authored step.
  *
  * A `completed` record supersedes the `admitted` one for the same step; first
- * admission order is preserved so the index reads in the order the body ran.
+ * admission order is preserved for each step, while different children can
+ * first appear in completion order when they finish concurrently.
  * Records this version does not recognise are skipped rather than trusted.
  */
 export async function readAuthoredStepIndex(

package/src/authored-verdict.ts

@@ -21,6 +21,8 @@ import type { JournalEvent } from './journal-reader.js';
 
 /** The `instruction` discriminator `authored-root.ts` writes into the root step. */
 export const AUTHORED_ROOT_KIND = 'relayflows.authored-root.v1';
+/** Older CLIs do not recognize this root and must refuse a parallel rollback. */
+export const AUTHORED_PARALLEL_ROOT_KIND = 'relayflows.authored-root.parallel.v2';
 
 export interface AuthoredVerdict {
   readonly reason: LoweredCompletionReason;
@@ -76,7 +78,8 @@ export function declaresAuthoredRoot(spawned: JournalEvent): boolean {
   if (step === null || step['id'] !== 'authored-root') return false;
   if (typeof step['instruction'] !== 'string') return false;
   try {
-    return record(JSON.parse(step['instruction']))?.['kind'] === AUTHORED_ROOT_KIND;
+    const kind = record(JSON.parse(step['instruction']))?.['kind'];
+    return kind === AUTHORED_ROOT_KIND || kind === AUTHORED_PARALLEL_ROOT_KIND;
   } catch {
     return false;
   }

package/src/authored-worker-step.ts

@@ -19,7 +19,8 @@ import { authoredChildAdmissionKey } from './authored-admission.js';
 import { alsoRecord, recordAuthoredChild } from './authored-step-index.js';
 import type { StepFailedDetails } from './failure-kinds.js';
 import { LOCAL_AGENT_WORKSPACE } from './local-agent-pins.js';
-import { authoredWorkerSlots, type AuthoredWorkerSlots } from './worker-slots.js';
+import { authoredWorkerSlots, WorkerSlots, type AuthoredWorkerSlots } from './worker-slots.js';
+import { validateStepSecrets } from './step-secrets.js';
 
 const AGENT_TIMEOUT = Symbol('declared agent timeout');
 const WORKSPACE_PERMISSION_ANNOTATION = /:\s*(readonly|readwrite)\s*$/i;
@@ -177,6 +178,8 @@ export function authoredWorkerRunner(
       }
     },
     async agent(id: string, options: AgentOptions, verification?: NamedGate): Promise<AgentResult> {
+      const secrets = validateStepSecrets((options as AgentOptions & { secrets?: unknown }).secrets,
+        agentEnvironment ?? process.env);
       if (options.workspace !== undefined && localAgentStream !== undefined) {
         throw new AuthoredFlowExecutionError('unsupported_workspace_permission',
           'The local agent worker accepts stream-only steps. Remove workspace or attach a worker that holds its revision pins.');
@@ -277,6 +280,7 @@ export function authoredWorkerRunner(
         : snapshotJsonValue(permissions, 'f.agent options.permissions') as unknown as PermissionsSpec;
       const output = await run({
         id, type: 'agent', instruction: options.task,
+        ...(secrets.length ? { secrets } : {}),
         ...(timeoutMs === undefined ? {} : { timeoutMs }),
         ...(permissionsSnapshot === undefined ? {} : { permissions: permissionsSnapshot }),
         ...(localAgentStream === undefined ? {} : { surfaces: {
@@ -323,11 +327,14 @@ export function authoredWorkerRunner(
       }
       const snapshot = options === undefined ? undefined : snapshotJsonValue(options, 'f.llm options');
       if (snapshot !== undefined && (typeof snapshot !== 'object' || snapshot === null || Array.isArray(snapshot)
-        || Object.keys(snapshot).some(key => !['output', 'cli', 'model'].includes(key)))) {
-        throw new AuthoredFlowExecutionError('llm_cli_unresolved', 'f.llm options accepts only output, cli, and model.');
+        || Object.keys(snapshot).some(key => !['output', 'cli', 'model', 'secrets'].includes(key)))) {
+        throw new AuthoredFlowExecutionError('llm_cli_unresolved', 'f.llm options accepts only output, cli, model, and secrets.');
       }
+      const secrets = validateStepSecrets((snapshot as { secrets?: unknown } | undefined)?.secrets,
+        agentEnvironment ?? process.env);
       const output = await run({
         id, type: 'llm', prompt, ...snapshot as unknown as LlmOptions,
+        ...(secrets.length ? { secrets } : {}),
         ...(verification === undefined ? {} : { verification }),
       });
       if (options === undefined && typeof output !== 'string') {
@@ -349,8 +356,14 @@ export function authoredWorkerRunner(
 export function authoredDeterministicRunner(
   name: string, journal: JournalClient, journalSteps: AuthoredFlowJournalStep[], budget: AuthoredBudget,
   context: AuthoredStepContext = {},
+  parallel = false,
 ) {
   const rootRunId = context.rootRunId;
+  // run.start drives a deterministic child to completion before replying. The
+  // daemon reads one connection in order, so sharing the body's connection
+  // would serialize Promise.all. Each admitted child gets its own connection;
+  // this limit bounds both daemon threads and shell commands per authored body.
+  const slots = new WorkerSlots(8);
   // One lowering, two readers. `record` changes what the child run's verdict
   // MEANS, so the reader changes with it; everything before the read — spec,
   // admission key, budget, child index — is deliberately shared, because a
@@ -358,6 +371,7 @@ export function authoredDeterministicRunner(
   function lower<T>(
     id: string, command: string, terminal: boolean, leaseMs: number | undefined,
     verification: NamedGate | undefined, onNonZero: 'record' | undefined,
+    secrets: string[] | undefined,
     read: (outcome: import('./protocol.js').RunOutcome) => Promise<T>,
   ): Promise<T> {
     const spec = toKernelSpec(compileSpec({
@@ -365,6 +379,7 @@ export function authoredDeterministicRunner(
       name: `${name}/${id}`,
       steps: [{
         id, type: 'deterministic', command,
+        ...(secrets?.length ? { secrets } : {}),
         ...(leaseMs === undefined ? {} : { lease_ms: leaseMs }),
         ...(onNonZero === undefined ? {} : { onNonZero }),
         ...(verification === undefined ? {} : { verification }),
@@ -377,16 +392,21 @@ export function authoredDeterministicRunner(
       });
       return read(outcome);
     };
-    if (terminal) return journal.runStart(spec, undefined, admissionKey).then(consume);
-    return budget.execute(journal, spec, consume, admissionKey);
+    const admit = async () => terminal
+      ? consume(await journal.runStart(spec, undefined, admissionKey, false, parallel))
+      : budget.execute(journal, spec, consume, admissionKey, parallel);
+    return parallel ? slots.run(admit) : admit();
   }
-  const lowerRun = (id: string, command: string, terminal = false, leaseMs?: number, verification?: NamedGate): Promise<string> =>
-    lower(id, command, terminal, leaseMs, verification, undefined,
+  const lowerRun = (id: string, command: string, terminal = false, leaseMs?: number, verification?: NamedGate,
+    secrets?: string[]): Promise<string> =>
+    lower(id, command, terminal, leaseMs, verification, undefined, secrets,
       outcome => readSuccessfulOutput(journal, outcome, id, journalSteps, context));
   /** `f.run(..., { onNonZero: 'record' })`: the exit code is the result, not a throw. */
-  lowerRun.recording = (id: string, command: string, leaseMs?: number, verification?: NamedGate): Promise<RecordedRunOutcome> =>
-    lower(id, command, false, leaseMs, verification, 'record',
+  lowerRun.recording = (id: string, command: string, leaseMs?: number, verification?: NamedGate,
+    secrets?: string[]): Promise<RecordedRunOutcome> =>
+    lower(id, command, false, leaseMs, verification, 'record', secrets,
       outcome => readRecordedOutcome(journal, outcome, id, journalSteps, context));
+  lowerRun.stop = (reason: unknown): void => slots.close(reason);
   return lowerRun;
 }
 

package/src/cli/check.ts

@@ -492,8 +492,8 @@ function findConfig(start: string): string | undefined {
 function systemProbes(flowDirectory: string, config: ProjectConfig, environment?: NodeJS.ProcessEnv): PreflightProbes {
   return {
     helper: helperReady,
-    cli: (cli, source, model, execution) => probeCli(cli,
-      source === 'project' ? config.directory : flowDirectory, model, execution, environment),
+    cli: (cli, source, model, execution, secrets) => probeCli(cli,
+      source === 'project' ? config.directory : flowDirectory, model, execution, environment, secrets),
     executor: (trigger) => config.executors.includes(trigger.executor),
     // A deterministic step runs in the daemon's working directory — the
     // directory `flows run` was invoked from, or Cloud's code mount — not in
@@ -521,7 +521,7 @@ function bindResolvedCliPaths(
       if (resolution === undefined) return step;
       const directory = resolution.source === 'project' ? configDirectory : flowDirectory;
       const managed = step.type === 'agent' && communicationInstruction(step.instruction) !== undefined;
-      const outcome = probeCache.get(cliProbeKey(resolution, managed));
+      const outcome = probeCache.get(cliProbeKey(resolution, managed, step.secrets));
       const executable = outcome !== undefined && 'result' in outcome
         ? outcome.result.executable
         : undefined;

package/src/cli/cli-probe.ts

@@ -7,6 +7,7 @@ import { adapterIdentification, authenticationProbe, classifyModelProbeFailure,
 import { MODEL_ENV } from '../worker-cli.js';
 import { CliProbeError, type CliProbeResult } from '../preflight.js';
 import { pinCliAlias, pinCliAliasSync } from './pinned-cli-alias.js';
+import { agentProbeEnvironment } from '../step-secrets.js';
 
 interface ProbeRequest {
   argv0?: string;
@@ -30,7 +31,8 @@ export async function probeCliAsync(...args: Parameters<typeof probeSequence>):
 }
 
 export function resolveExecutable(command: string, directory: string, environment: NodeJS.ProcessEnv = process.env): string | undefined {
-  return driveSync(executableSequence(command, directory, environment));
+  return driveSync(executableSequence(command, directory,
+    agentProbeEnvironment(environment, 'relayflows-wrapper-v1')));
 }
 
 function driveSync<T>(sequence: Generator<ProbeRequest, T, ProbeOutput>): T {
@@ -94,23 +96,24 @@ function* probeSequence(
   model?: string,
   execution?: 'managed',
   sourceEnvironment: NodeJS.ProcessEnv = process.env,
+  grants?: string[],
 ): Generator<ProbeRequest, CliProbeResult, ProbeOutput> {
-  const executable = yield* executableSequence(cli, directory, sourceEnvironment);
+  const kind = cliAdapterKind(cli);
+  const environment = execution === 'managed'
+    ? { ...brokerEnvironment(sourceEnvironment), ...agentEnvironment(cli, sourceEnvironment, grants) }
+    : agentProbeEnvironment(sourceEnvironment, kind, grants);
+  const executable = yield* executableSequence(cli, directory, environment);
   if (executable === undefined) return { exists: false, authenticated: false };
   // The declaration selects the adapter; the canonical executable selects
   // the bytes. Package-manager links commonly name `claude` or `codex` while
   // targeting a generic `cli.js`, whose basename must not rewrite the adapter
   // contract after resolution.
-  const kind = cliAdapterKind(cli);
   // Relay owns interactive CLI launch/injection. Its generic PTY path is not
   // the headless wrapper protocol; do not demand that protocol from Gemini,
   // Cursor, OpenCode, or other interactive tools. Never invent an auth pass.
   if (execution === 'managed' && kind === 'relayflows-wrapper-v1') {
     return { exists: true, supported: true, authenticated: 'unverified', executable };
   }
-  const environment = execution === 'managed'
-    ? { ...brokerEnvironment(sourceEnvironment), ...agentEnvironment(cli, sourceEnvironment) }
-    : sourceEnvironment;
   const probe = (invocation: CliInvocation): ProbeRequest => ({
     executable,
     argv0: basename(cli),

package/src/cli/run.ts

@@ -415,9 +415,11 @@ export async function resumeFlow(
       return { exitCode: 2, report: { ...base, runId, socketPath,
         diagnostics: [{ severity: 'refusal', kind: 'human_influenced_run', message: error.message.replace(/^human_influenced_run: /, '') }] } };
     }
-    if (error instanceof AuthoredFlowExecutionError && error.code === 'unsupported_promise_lifecycle') {
+    if (error instanceof AuthoredFlowExecutionError
+      && (error.code === 'unsafe_parallel_runtime' || error.code === 'unsupported_promise_lifecycle')) {
       return { exitCode: 2, report: { ...base, runId, socketPath,
-        diagnostics: [{ severity: 'refusal', kind: 'invalid_spec', message: error.message }] } };
+        diagnostics: [{ severity: 'refusal',
+          kind: error.code === 'unsafe_parallel_runtime' ? error.code : 'invalid_spec', message: error.message }] } };
     }
     if (error instanceof AuthoredFlowExecutionError
       && (error.code === 'helper_slack.credential_missing' || error.code === 'helper_slack.mount_required'