@relayflows/sdk 2.0.27 → 2.0.28

package/src/authored-node-runner.ts

@@ -130,7 +130,8 @@ export async function runAuthoredInNode(
               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');
+                dataDir: options.dataDir, localAgentStream: options.localAgentStream,
+                workerCapacity: options.workerCapacity }) + '\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);

package/src/authored-promise-graph.ts

@@ -1,4 +1,5 @@
 import { createHook, executionAsyncId, type AsyncHook } from 'node:async_hooks';
+import { reachableTargets } from './promise-ancestry.js';
 
 /**
  * The promise graph an authored flow body actually creates.
@@ -35,7 +36,9 @@ export class AuthoredPromiseGraph {
   private readonly attributedRoots = new Map<number, number>();
   private readonly roots = new Set<number>();
   private readonly pending = new Set<number>();
-  private dependencyCache: { readonly start: number; readonly found: ReadonlySet<number> } | undefined;
+  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;
 
   constructor(
     private readonly inScope: () => boolean,
@@ -45,6 +48,7 @@ export class AuthoredPromiseGraph {
       init: (asyncId, type, triggerAsyncId, resource) => {
         if (type !== 'PROMISE' || typeof resource !== 'object' || resource === null) return;
         if (!this.inScope()) return;
+        this.changes++;
         this.triggers.set(asyncId, triggerAsyncId);
         this.creationContexts.set(asyncId, executionAsyncId());
         this.promiseIds.set(resource, asyncId);
@@ -59,6 +63,7 @@ export class AuthoredPromiseGraph {
       promiseResolve: (asyncId) => {
         this.onPromiseResolve(asyncId);
         if (!this.triggers.has(asyncId)) return;
+        this.changes++;
         const cause = executionAsyncId();
         if (cause !== asyncId) this.resolutionCauses.set(asyncId, cause);
         this.pending.delete(asyncId);
@@ -98,6 +103,7 @@ export class AuthoredPromiseGraph {
   /** Mark a promise whose descendants belong to an authored operation. */
   registerRoot(asyncId: number): void {
     if (asyncId <= 0 || this.roots.has(asyncId)) return;
+    this.changes++;
     this.roots.add(asyncId);
     const parked = this.unattributedChildren.get(asyncId);
     if (parked === undefined) return;
@@ -105,31 +111,58 @@ export class AuthoredPromiseGraph {
     for (const child of parked) this.attribute(child, asyncId);
   }
 
-  /** Promises derived from `roots` that have not settled. */
-  inFlightFrom(roots: ReadonlySet<number>): number[] {
-    const found: number[] = [];
+  /** The roots that still have derived promises in flight. One pass over `pending`. */
+  rootsInFlight(): Set<number> {
+    const found = new Set<number>();
     for (const asyncId of this.pending) {
       const root = this.attributedRoots.get(asyncId);
-      if (root !== undefined && roots.has(root)) found.push(asyncId);
+      if (root !== undefined) found.add(root);
     }
     return found;
   }
 
-  /** Settled promises derived from `roots`, with their handles. */
-  settledFrom(roots: ReadonlySet<number>): Promise<unknown>[] {
-    const found: Promise<unknown>[] = [];
+  /** Every settled derived promise with its root, in attribution order. One pass. */
+  settledWithRoots(): Array<{ readonly root: number; readonly handle: Promise<unknown> }> {
+    const found: Array<{ root: number; handle: Promise<unknown> }> = [];
     for (const [asyncId, root] of this.attributedRoots) {
-      if (!roots.has(root) || this.pending.has(asyncId)) continue;
+      if (this.pending.has(asyncId)) continue;
       const handle = this.handles.get(asyncId);
-      if (handle !== undefined) found.push(handle);
+      if (handle !== undefined) found.push({ root, handle });
     }
     return found;
   }
 
+  /** The three recorded edges out of one promise, for walks that stop early. */
+  causesOf(asyncId: number): number[] {
+    const causes: number[] = [];
+    for (const edge of [
+      this.triggers.get(asyncId),
+      this.resolutionCauses.get(asyncId),
+      this.creationContexts.get(asyncId),
+    ]) {
+      if (edge !== undefined && edge !== asyncId) causes.push(edge);
+    }
+    return causes;
+  }
+
   dependsOn(descendant: number, ancestor: number): boolean {
     return this.dependenciesOf(descendant).has(ancestor);
   }
 
+  /** A counter that changes whenever the graph does; equal values mean equal answers. */
+  get version(): number {
+    return this.changes;
+  }
+
+  /**
+   * `dependsOn(start, target)` for every pair at once: for each start, the
+   * targets it depends on. One pass over the shared ancestry instead of one
+   * walk per pair (see promise-ancestry.ts).
+   */
+  dependenciesAmong(starts: readonly number[], targets: readonly number[]): Map<number, ReadonlySet<number>> {
+    return reachableTargets(starts, targets, (node) => this.causesOf(node));
+  }
+
   clear(): void {
     this.triggers.clear();
     this.creationContexts.clear();
@@ -175,22 +208,16 @@ export class AuthoredPromiseGraph {
    */
   private dependenciesOf(start: number): ReadonlySet<number> {
     const cached = this.dependencyCache;
-    if (cached !== undefined && cached.start === start) return cached.found;
+    if (cached !== undefined && cached.start === start && cached.version === this.changes) return cached.found;
     const found = new Set<number>();
     const stack = [start];
     while (stack.length > 0) {
       const current = stack.pop()!;
       if (found.has(current)) continue;
       found.add(current);
-      for (const edge of [
-        this.triggers.get(current),
-        this.resolutionCauses.get(current),
-        this.creationContexts.get(current),
-      ]) {
-        if (edge !== undefined && edge !== current) stack.push(edge);
-      }
+      for (const edge of this.causesOf(current)) stack.push(edge);
     }
-    this.dependencyCache = { start, found };
+    this.dependencyCache = { start, found, version: this.changes };
     return found;
   }
 }

package/src/authored-root.ts

@@ -51,6 +51,8 @@ export interface DurableAuthoredOptions {
   readonly dataDir: string;
   readonly admissionKey?: string;
   readonly localAgentStream?: string;
+  /** Concurrency of the attached local workers; see `ExecuteAuthoredFlowOptions.workerCapacity`. */
+  readonly workerCapacity?: number;
   readonly lifecycle?: RunLifecycleOptions;
 }
 
@@ -201,6 +203,7 @@ async function driveRoot(
       if (process.versions['bun'] !== undefined) {
         return runAuthoredInNode(metadata, journal.socketPath, dispatch.run_id, {
           dataDir: options.dataDir, localAgentStream: options.localAgentStream,
+          ...(options.workerCapacity === undefined ? {} : { workerCapacity: options.workerCapacity }),
           ...options.lifecycle, signal,
         });
       }
@@ -213,6 +216,7 @@ async function driveRoot(
           dataDir: options.dataDir,
           flowPath: metadata.flowPath,
           localAgentStream: options.localAgentStream,
+          ...(options.workerCapacity === undefined ? {} : { workerCapacity: options.workerCapacity }),
           rootRunId: dispatch.run_id,
           extensions: loaded.extensions,
           ...options.lifecycle,

package/src/authored-step-graph.ts

@@ -0,0 +1,246 @@
+import { inspect } from 'node:util';
+import { MAX_AFTER, displayLabel, type AuthoredStepEdges } from './authored-step-index.js';
+
+/**
+ * The named DAG an authored body draws, recorded as it runs.
+ *
+ * An authored flow is plain TypeScript, so the shape Cloud wants to draw — which
+ * `f.agent` waited for which — is not declared anywhere. It is, however, a fact
+ * the runtime already holds: the promise graph (`authored-promise-graph.ts`)
+ * records, for every promise the body creates, what triggered it, what resolved
+ * it, and which context created it. A step's causal predecessors are the step
+ * promises reachable backward from the context that invoked it.
+ *
+ * Three rules make that walk an answer rather than an approximation:
+ *
+ * 1. **Stop at steps.** A step promise is a frontier; what it waited for is its
+ *    own `after`, not ours.
+ * 2. **Expand an aggregate that waited for every member.** The runtime links a
+ *    combinator's aggregate only to the member whose settlement settled it.
+ *    That member is the whole answer when the aggregate settled on the first
+ *    member that could decide it — a rejected `all`, a fulfilled `any`, any
+ *    `race` — and a fraction of it when the aggregate had to wait for all of
+ *    them: a fulfilled `all`, a rejected `any`, every `allSettled`. Which case
+ *    applies is known only once the aggregate settles, so it is decided when a
+ *    walk reaches the aggregate (`registerAggregate`, `promiseOutcome`).
+ * 3. **Reduce transitively.** `a → b → c` reaches both `a` and `b` from `c`;
+ *    `a` is an ancestor of `b`, so it is dropped.
+ *
+ * Cost is bounded, not quadratic. Each invocation context's frontier is
+ * memoized, and a walk that reaches an already-answered context takes its
+ * answer instead of re-walking the history behind it — so a long sequential
+ * 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.
+ */
+export const MAX_WALK = 10_000;
+
+interface Frontier {
+  readonly steps: readonly string[];
+  readonly truncated: boolean;
+}
+
+interface StepNode {
+  readonly order: number;
+  readonly after: readonly string[];
+  /** `after` may be incomplete, so a reduction that relies on it may keep an ancestor. */
+  readonly truncated: boolean;
+}
+
+type Combinator = 'all' | 'allSettled' | 'any' | 'race';
+type Outcome = 'pending' | 'fulfilled' | 'rejected';
+
+/** The settlement on which a combinator had waited for every member. */
+const EXPANDS_ON: Readonly<Record<Combinator, Outcome | 'always' | undefined>> = {
+  all: 'fulfilled',
+  allSettled: 'always',
+  any: 'rejected',
+  race: undefined,
+};
+
+interface Aggregate {
+  readonly promise: Promise<unknown>;
+  /** Cached once settled: a settled promise never changes state. */
+  outcome?: Outcome;
+  readonly expandsOn: Outcome | 'always';
+  readonly members: readonly number[];
+}
+
+export class AuthoredStepGraph {
+  private readonly stepPromises = new Map<number, string>();
+  private readonly aggregates = new Map<number, Aggregate>();
+  private readonly contexts = new Map<number, Frontier>();
+  private readonly nodes = new Map<string, StepNode>();
+  private readonly edges = new Map<string, AuthoredStepEdges>();
+
+  constructor(
+    private readonly causesOf: (asyncId: number) => readonly number[],
+    private readonly walkLimit = MAX_WALK,
+  ) {}
+
+  /** A combinator's aggregate and its members, for expansion once it settles. */
+  registerAggregate(
+    aggregateId: number,
+    promise: Promise<unknown>,
+    combinator: Combinator,
+    members: readonly number[],
+  ): void {
+    const expandsOn = EXPANDS_ON[combinator];
+    if (expandsOn === undefined || members.length === 0) return;
+    this.aggregates.set(aggregateId, { promise, expandsOn, members });
+  }
+
+  /**
+   * Record a step invoked from `contextId`. `promiseId` is the step's own
+   * promise, when the promise graph saw it, so later walks stop there.
+   */
+  registerStep(
+    step: string,
+    promiseId: number | undefined,
+    contextId: number,
+    label?: string,
+  ): AuthoredStepEdges {
+    const frontier = this.frontierOf(contextId);
+    this.nodes.set(step, { order: this.nodes.size, after: frontier.steps, truncated: frontier.truncated });
+    if (promiseId !== undefined) this.stepPromises.set(promiseId, step);
+    const truncated = frontier.truncated || frontier.steps.length > MAX_AFTER;
+    const edges: AuthoredStepEdges = Object.freeze({
+      ...displayLabel(label),
+      ...(frontier.steps.length === 0 ? {} : { after: Object.freeze(frontier.steps.slice(0, MAX_AFTER)) }),
+      ...(truncated ? { afterTruncated: true as const } : {}),
+    });
+    this.edges.set(step, edges);
+    return edges;
+  }
+
+  edgesOf(step: string): AuthoredStepEdges | undefined {
+    return this.edges.get(step);
+  }
+
+  /** Drop the walk state; recorded edges stay readable for late record writes. */
+  release(): void {
+    this.stepPromises.clear();
+    this.aggregates.clear();
+    this.contexts.clear();
+    this.nodes.clear();
+  }
+
+  private frontierOf(start: number): Frontier {
+    const memo = this.contexts.get(start);
+    if (memo !== undefined) return memo;
+    const candidates = new Set<string>();
+    let truncated = false;
+    const visited = new Set<number>([start]);
+    const queue = [start];
+    // Breadth-first, so that a walk cut short by the limit has already found
+    // the nearest predecessors and lost only distant history.
+    for (let head = 0; head < queue.length; head++) {
+      const current = queue[head]!;
+      const step = this.stepPromises.get(current);
+      if (step !== undefined) {
+        candidates.add(step);
+        continue;
+      }
+      const answered = current === start ? undefined : this.contexts.get(current);
+      if (answered !== undefined) {
+        for (const found of answered.steps) candidates.add(found);
+        truncated ||= answered.truncated;
+        continue;
+      }
+      for (const id of [...this.waitedFor(current), ...this.causesOf(current)]) {
+        if (visited.has(id)) continue;
+        // At the limit, stop growing the walk but still drain what is queued:
+        // those nodes are already known and cost one lookup each.
+        if (visited.size >= this.walkLimit) {
+          truncated = true;
+          break;
+        }
+        visited.add(id);
+        queue.push(id);
+      }
+    }
+    const reduced = this.reduce(candidates);
+    const frontier = Object.freeze({ steps: reduced.steps, truncated: truncated || reduced.truncated });
+    this.contexts.set(start, frontier);
+    return frontier;
+  }
+
+  /** The members an aggregate waited for beyond its own resolution edge. */
+  private waitedFor(asyncId: number): readonly number[] {
+    const aggregate = this.aggregates.get(asyncId);
+    if (aggregate === undefined) return [];
+    if (aggregate.expandsOn === 'always') return aggregate.members;
+    if (aggregate.outcome === undefined) {
+      const outcome = promiseOutcome(aggregate.promise);
+      if (outcome !== 'pending') aggregate.outcome = outcome;
+    }
+    return aggregate.outcome === aggregate.expandsOn ? aggregate.members : [];
+  }
+
+  /**
+   * Drop every candidate that is an ancestor of another candidate. The
+   * 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 {
+    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
+    // older than the oldest candidate can be one: the walk stops there.
+    const oldest = this.orderOf(ordered[0]!);
+    const reached = new Set<string>();
+    // Predecessor lists are read through cursors, never copied onto the stack, and every entry
+    // inspected counts toward the limit — duplicates included — so a wide fan-in bounds both
+    // allocation and work, not just the number of distinct steps reached.
+    const stack: Array<{ readonly values: readonly string[]; next: number }> = [];
+    const pushList = (values: readonly string[] | undefined): void => {
+      if (values !== undefined && values.length > 0) stack.push({ values, next: 0 });
+    };
+    for (const step of ordered) pushList(this.nodes.get(step)?.after);
+    let inspected = 0;
+    let truncated = ordered.some((step) => this.nodes.get(step)?.truncated === true);
+    while (stack.length > 0) {
+      const frame = stack[stack.length - 1]!;
+      const step = frame.values[frame.next++]!;
+      if (frame.next === frame.values.length) stack.pop();
+      if (++inspected > this.walkLimit) {
+        truncated = true;
+        break;
+      }
+      if (reached.has(step)) continue;
+      reached.add(step);
+      const node = this.nodes.get(step);
+      if (node === undefined || node.order <= oldest) continue;
+      truncated ||= node.truncated;
+      pushList(node.after);
+    }
+    return { steps: ordered.filter((step) => !reached.has(step)), truncated };
+  }
+
+  private orderOf(step: string): number {
+    return this.nodes.get(step)?.order ?? -1;
+  }
+}
+
+/**
+ * Whether a promise has settled, and how, read without attaching a handler.
+ *
+ * Attaching one would mark an author's rejected aggregate as handled and hide
+ * an unhandled rejection the process would otherwise report, so the state is
+ * read the one public way that has no such effect: Node's own inspection.
+ * `customInspect`, `getters` and `showProxy` keep author code and proxy traps
+ * from running; `depth: 0` and the length caps keep the rendered value small.
+ * Every option the match depends on is set here, because `inspect` fills the
+ * rest from `util.inspect.defaultOptions`, which any code in the process can
+ * change — `colors: true` there would wrap `<rejected>` in ANSI escapes.
+ */
+export function promiseOutcome(promise: Promise<unknown>): Outcome {
+  const shown = inspect(promise, {
+    depth: 0, customInspect: false, getters: false, showProxy: true, colors: false,
+    compact: 3, sorted: false, maxArrayLength: 0, maxStringLength: 0, breakLength: Infinity,
+  });
+  const state = /^[^{]*\{\s*<(pending|rejected)>/u.exec(shown)?.[1];
+  return state === 'pending' ? 'pending' : state === 'rejected' ? 'rejected' : 'fulfilled';
+}

package/src/authored-step-index.ts

@@ -57,6 +57,40 @@ export interface AuthoredStepRecord {
    * `<step>` — saying which is the difference between an index and a guess.
    */
   readonly kernelStep?: string;
+  /**
+   * Human name for the step: the author-chosen `f.agent` or `f.hook` name,
+   * whole or not at all (`displayLabel`).
+   */
+  readonly label?: string;
+  /**
+   * The steps this one causally waited for, transitively reduced
+   * (`authored-step-graph.ts`). Absent means none were found, not unknown.
+   */
+  readonly after?: readonly string[];
+  /** Present when `after` is incomplete: the walk hit its limit or the list its cap. */
+  readonly afterTruncated?: true;
+}
+
+/** The graph fields one authored step carries on every record about it. */
+export type AuthoredStepEdges = Pick<AuthoredStepRecord, 'label' | 'after' | 'afterTruncated'>;
+
+/** Most predecessors one record lists; the rest are marked `afterTruncated`. */
+export const MAX_AFTER = 32;
+
+/** Longest label a record carries. A longer one is omitted, never cut. */
+export const MAX_LABEL = 256;
+
+/**
+ * A label, whole, or nothing.
+ *
+ * A label is displayed and persisted by Cloud after its redactor runs, and the
+ * redactor matches whole secret values: a label cut mid-secret would arrive as
+ * an unredactable prefix. So a label is never truncated — one over the bound
+ * is dropped — and only author-chosen names are labels at all. Commands are
+ * not: they carry literal tokens and URLs, so `f.run` has no label.
+ */
+export function displayLabel(label: string | undefined): { readonly label?: string } {
+  return label === undefined || label.trim() === '' || label.length > MAX_LABEL ? {} : { label };
 }
 
 /**
@@ -85,6 +119,10 @@ export async function recordAuthoredChild(
     ...(record.completionReason === undefined ? {} : { completionReason: bound(record.completionReason) }),
     ...(record.kernelStep === undefined || record.kernelStep === record.step
       ? {} : { kernelStep: bound(record.kernelStep) }),
+    ...displayLabel(record.label),
+    ...(record.after === undefined ? {} : { after: record.after.slice(0, MAX_AFTER).map(bound) }),
+    ...(record.afterTruncated === true || (record.after?.length ?? 0) > MAX_AFTER
+      ? { afterTruncated: true } : {}),
   });
 }
 
@@ -149,7 +187,12 @@ function isAuthoredStepRecord(value: unknown): value is AuthoredStepRecord {
     && typeof record.runId === 'string' && record.runId.length > 0
     && (record.state === 'admitted' || record.state === 'completed')
     && (record.completionReason === undefined || typeof record.completionReason === 'string')
-    && (record.kernelStep === undefined || typeof record.kernelStep === 'string');
+    && (record.kernelStep === undefined || typeof record.kernelStep === 'string')
+    && (record.label === undefined || (typeof record.label === 'string' && record.label.length <= MAX_LABEL))
+    && (record.after === undefined || (Array.isArray(record.after)
+      && record.after.length <= MAX_AFTER
+      && record.after.every((step) => typeof step === 'string' && step.length > 0)))
+    && (record.afterTruncated === undefined || record.afterTruncated === true);
 }
 
 function bound(value: string): string {

package/src/authored-step-output.ts

@@ -5,7 +5,7 @@ import type { CompletionReason as ProtocolCompletionReason, RunCompletionReason
 import type { AuthoredFlowJournalStep } from './authored-flow-executor.js';
 import type { StepFailedDetails } from './failure-kinds.js';
 import { inspectionHint, renderInspection, renderStepEvidence, stepFailureDetails } from './cli/step-failure.js';
-import { alsoRecord, recordAuthoredChild } from './authored-step-index.js';
+import { alsoRecord, recordAuthoredChild, type AuthoredStepEdges } from './authored-step-index.js';
 
 /**
  * What an authored operation needs in order to leave readable evidence:
@@ -17,6 +17,8 @@ import { alsoRecord, recordAuthoredChild } from './authored-step-index.js';
 export interface AuthoredStepContext {
   readonly rootRunId?: string;
   readonly dataDir?: string;
+  /** The step's label and causal predecessors, carried on every record about it. */
+  readonly stepEdges?: (step: string) => AuthoredStepEdges | undefined;
 }
 
 /**
@@ -58,7 +60,8 @@ export async function readCompletedStepOutput(
   }
 
   const reason = completed.payload.completionReason;
-  journalSteps.push(Object.freeze({ id: stepId, runId, completionReason: reason }));
+  const edges = context.stepEdges?.(stepId);
+  journalSteps.push(Object.freeze({ id: stepId, runId, completionReason: reason, ...edges }));
   if (reason !== 'success') {
     let message = `journal step "${stepId}" completed with ${reason}`;
     let details: StepFailedDetails | undefined;
@@ -77,11 +80,12 @@ export async function readCompletedStepOutput(
     message += await alsoRecord(journal, context.rootRunId, {
       step: stepId, runId, state: 'completed', completionReason: reason,
       ...(details?.stepId === undefined ? {} : { kernelStep: details.stepId }),
+      ...edges,
     });
     throw new AuthoredFlowExecutionError('step_failed', message, reason, runId, { ...details, ...where });
   }
   await recordAuthoredChild(journal, context.rootRunId, {
-    step: stepId, runId, state: 'completed', completionReason: reason,
+    step: stepId, runId, state: 'completed', completionReason: reason, ...edges,
   });
   return completed.payload.output;
 }

package/src/authored-worker-step.ts

@@ -1,3 +1,4 @@
+import { resolve } from 'node:path';
 import type { AuthoredBudget } from './authored-budget.js';
 import { parseBudget } from './budget.js';
 import type { AgentOptions, AgentResult, LlmOptions, NamedGate } from '@relayflows/surface';
@@ -14,6 +15,7 @@ import { snapshotJsonValue } from './json-value.js';
 import { authoredChildAdmissionKey } from './authored-admission.js';
 import { alsoRecord, recordAuthoredChild } from './authored-step-index.js';
 import type { StepFailedDetails } from './failure-kinds.js';
+import { WorkerSlots } from './worker-slots.js';
 
 const WORKSPACE_PERMISSION_ANNOTATION = /:\s*(readonly|readwrite)\s*$/i;
 
@@ -22,11 +24,16 @@ export function authoredWorkerRunner(
   definition: { name: string }, journal: JournalClient, flowPath: string,
   journalSteps: AuthoredFlowJournalStep[], waitOptions: RunLifecycleOptions,
   localAgentStream?: string, budget?: AuthoredBudget, headerBudget?: unknown,
-  rootRunId?: string,
+  rootRunId?: string, workerCapacity?: number, stepEdges?: AuthoredStepContext['stepEdges'],
 ) {
+  // Sized to the attached local workers, so concurrent calls wait here for a
+  // slot instead of being admitted and parked for want of a free worker.
+  const slots = workerCapacity === undefined ? undefined
+    : { agent: new WorkerSlots(workerCapacity), llm: new WorkerSlots(workerCapacity) };
   const context: AuthoredStepContext = {
     ...(rootRunId === undefined ? {} : { rootRunId }),
     ...(waitOptions.dataDir === undefined ? {} : { dataDir: waitOptions.dataDir }),
+    ...(stepEdges === undefined ? {} : { stepEdges }),
   };
   async function run(step: StepSpec): Promise<unknown> {
     const id = step.id;
@@ -55,7 +62,9 @@ export function authoredWorkerRunner(
     // Written BEFORE the wait, not after it. An agent runs for as long as its
     // lease allows; if this process dies mid-step, this record is the only
     // thing that still names the child run holding the evidence.
-    await recordAuthoredChild(journal, rootRunId, { step: id, runId: outcome.run_id, state: 'admitted' });
+    await recordAuthoredChild(journal, rootRunId, {
+      step: id, runId: outcome.run_id, state: 'admitted', ...stepEdges?.(id),
+    });
     // Reuse the declarative CLI's own wait/classification (cli/run.ts) rather
     // than a hand-rolled poll: `step.completed` and the run's own terminal
     // state are appended as two SEPARATE actions (kernel/relayflowd-core/src/machine.rs
@@ -95,12 +104,13 @@ export function authoredWorkerRunner(
       // a manufactured completion.
       if (isSurfaceCompletionReason(details?.completionReason)) {
         journalSteps.push(Object.freeze({
-          id, runId: outcome.run_id, completionReason: details.completionReason,
+          id, runId: outcome.run_id, completionReason: details.completionReason, ...stepEdges?.(id),
         }));
         message += await alsoRecord(journal, rootRunId, {
           step: id, runId: outcome.run_id, state: 'completed',
           completionReason: details.completionReason,
           ...(details.stepId === undefined ? {} : { kernelStep: details.stepId }),
+          ...stepEdges?.(id),
         });
       }
       throw new AuthoredFlowExecutionError(
@@ -113,12 +123,18 @@ export function authoredWorkerRunner(
     return readCompletedStepOutput(journal, outcome.run_id, id, journalSteps, context);
     };
     const admissionKey = authoredChildAdmissionKey(rootRunId, id);
-    return budget === undefined
+    const admit = async () => budget === undefined
       ? consume(await journal.runStart(spec, undefined, admissionKey))
       : budget.execute(journal, spec, consume, admissionKey);
+    return slots === undefined ? admit() : slots[step.type === 'llm' ? 'llm' : 'agent'].run(admit);
   }
 
   return {
+    /** Refuse every agent/LLM call still waiting for a worker slot (body teardown). */
+    stop(reason: unknown): void {
+      slots?.agent.close(reason);
+      slots?.llm.close(reason);
+    },
     async agent(id: string, options: AgentOptions, verification?: NamedGate): Promise<AgentResult> {
       if (options.workspace !== undefined && localAgentStream !== undefined) {
         throw new AuthoredFlowExecutionError('unsupported_workspace_permission',
@@ -167,7 +183,8 @@ export function authoredWorkerRunner(
         ...(options.workspace === undefined ? {} : { surfaces: { workspace: [{ surface: options.workspace }] } }),
         ...(options.cli === undefined ? {} : { cli: options.cli }),
         ...(options.model === undefined ? {} : { model: options.model }),
-        ...(options.cwd === undefined ? {} : { cwd: options.cwd }),
+        // The kernel takes only an absolute cwd; a relative one means the runner's own directory.
+        ...(options.cwd === undefined ? {} : { cwd: resolve(options.cwd) }),
         ...(options.transport === undefined ? {} : { transport: options.transport }),
         ...(verification === undefined ? {} : { verification }),
       });
@@ -229,7 +246,9 @@ export function authoredDeterministicRunner(
     }));
     const admissionKey = authoredChildAdmissionKey(rootRunId, id);
     const consume = async (outcome: import('./protocol.js').RunOutcome): Promise<string> => {
-      await recordAuthoredChild(journal, rootRunId, { step: id, runId: outcome.run_id, state: 'admitted' });
+      await recordAuthoredChild(journal, rootRunId, {
+        step: id, runId: outcome.run_id, state: 'admitted', ...context.stepEdges?.(id),
+      });
       return readSuccessfulOutput(journal, outcome, id, journalSteps, context);
     };
     if (terminal) return consume(await journal.runStart(spec, undefined, admissionKey));

package/src/cli/direct-run.ts

@@ -4,6 +4,7 @@ import { authoredLocalAgentStream } from '../authored-admission.js';
 import { McpPreflightError } from './check-typescript.js';
 import { attachLocalAgent } from '../local-agent.js';
 import { LlmWorker } from '../llm-worker.js';
+import { DEFAULT_LOCAL_AGENT_CAPACITY } from '../worker-slots.js';
 import {
   AuthoredFlowExecutionError,
 } from '../authored-flow-executor.js';
@@ -67,19 +68,20 @@ export async function runDirectFlow(
   let localLlm: LlmWorker | undefined;
   let llmClient: JournalClient | undefined;
   let llmFailure: unknown;
+  const workerCapacity = options.agentCapacity ?? DEFAULT_LOCAL_AGENT_CAPACITY;
   const admissionIdentity = options.authoredAdmissionKey
     ?? process.env['RELAYFLOW_AUTHORED_ADMISSION_KEY'] ?? randomUUID();
   try {
     if (options.localAgent) {
       localAgent = await attachLocalAgent(
-        client, dataDir, options.onPtyReady, authoredLocalAgentStream(admissionIdentity),
+        client, dataDir, options.onPtyReady, authoredLocalAgentStream(admissionIdentity), workerCapacity,
       );
       // A session owns one worker registration. Keep the workspace-free LLM
       // worker on its own connection so it cannot replace the agent worker.
       llmClient = new JournalClient(socketPath);
       await llmClient.connect();
       await llmClient.hello('flows-local-llm');
-      localLlm = new LlmWorker(llmClient, `${localAgent.stream}-llm`);
+      localLlm = new LlmWorker(llmClient, `${localAgent.stream}-llm`, workerCapacity);
       localLlm.on('error', error => { llmFailure = error; client.close(); });
       await localLlm.attach();
     }
@@ -89,6 +91,7 @@ export async function runDirectFlow(
         dataDir,
         admissionKey: admissionIdentity,
         localAgentStream: localAgent?.stream,
+        ...(localAgent === undefined ? {} : { workerCapacity }),
         lifecycle: {
           onProgress: options.onProgress,
           ...(options.signal !== undefined ? { signal: options.signal } : {}),