@relayflows/sdk 2.0.27 → 2.0.29

package/src/cli-commands.ts

@@ -1,5 +1,6 @@
 import { DEFAULT_DATA_DIR } from './daemon-connection.js';
 import { DEFAULT_RUN_LIMIT } from './cli/cloud-read.js';
+import { DEFAULT_LOCAL_AGENT_CAPACITY, MAX_LOCAL_AGENT_CAPACITY } from './worker-slots.js';
 import type { ParsedArgs } from './cli.js';
 
 /**
@@ -88,6 +89,11 @@ const LOCAL_EXECUTION_OPTIONS = [
   JSON_OPTION,
   DATA_DIR_OPTION,
   { flags: '--local-agent', description: 'Run agent steps in this process instead of a worker' },
+  {
+    flags: '--agent-capacity <n>',
+    description: `With --local-agent, how many agent steps (and, separately, LLM steps) run at once (1-${MAX_LOCAL_AGENT_CAPACITY})`,
+    defaultValue: String(DEFAULT_LOCAL_AGENT_CAPACITY),
+  },
   { flags: '--no-spawn', description: 'Require a running relayflowd rather than starting one' },
   { flags: '--no-observer-link', description: 'Do not mint an observer link for this run' },
   {

package/src/cli.ts

@@ -4,6 +4,7 @@ import { parsePluginArgs, runPluginCommand, type PluginArgs } from './cli/plugin
 import { watchCheck } from './cli-watch.js';
 import { checkHelperBody } from './cli/check-helper-body.js';
 import { describeFlowRequirements } from './flow-requirements.js';
+import type { CliModelSource } from './cli-adapter.js';
 
 import { renderProgress, type ProgressEvent } from './progress.js';
 import { realpathSync } from 'node:fs';
@@ -44,6 +45,7 @@ import { runHnMonitor } from './cli/hn-monitor.js';
 import { runTickRunner } from './cli/tick-runner.js';
 import { DEFAULT_DATA_DIR } from './daemon-connection.js';
 import { CLI_VERB_NAMES } from './cli-commands.js';
+import { isAgentCapacity } from './worker-slots.js';
 import {
   mintObserverUrl,
   resolveObserverLinkEnv,
@@ -80,8 +82,8 @@ export type ParsedArgs =
   | { command: 'schedules'; json: boolean }
   | { command: 'unschedule'; scheduleId: string; json: boolean }
   | { command: 'check'; json: boolean; watch: boolean; value: string }
-  | { command: 'run'; bucket: string | undefined; reuseFromRunId: string | undefined; localAgent: boolean; dataDir: string; input: string | undefined; json: boolean; spawn: boolean; noObserverLink: boolean; allowHumanInfluenced: boolean; value: string }
-  | { command: 'resume'; localAgent: boolean; dataDir: string; json: boolean; spawn: boolean; noObserverLink: boolean; allowHumanInfluenced: boolean; value: string }
+  | { command: 'run'; bucket: string | undefined; reuseFromRunId: string | undefined; localAgent: boolean; agentCapacity: number | undefined; dataDir: string; input: string | undefined; json: boolean; spawn: boolean; noObserverLink: boolean; allowHumanInfluenced: boolean; value: string }
+  | { command: 'resume'; localAgent: boolean; agentCapacity: number | undefined; dataDir: string; json: boolean; spawn: boolean; noObserverLink: boolean; allowHumanInfluenced: boolean; value: string }
   | { command: 'answer'; dataDir: string; json: boolean; spawn: boolean; note: string | undefined; by: string | undefined; runId: string; waitId: string; answer: boolean }
   | RunsArgs
   | LogsArgs
@@ -111,13 +113,13 @@ const USAGE = [
   'flows run <flow>@sha256:<digest> [--bucket <file-bucket-uri>] [--data-dir <dir>] [--json]',
   'flows check [--watch] [--json] <flow.ts|flow.yaml|spec.json>',
   'flows serve-webhook --data-dir <dir> --port <p> [--allow <name>[,<name>]]',
-  'flows run [--json] [--no-spawn] [--no-observer-link] [--data-dir <dir>] [--local-agent] [--reuse-from <run-id>] <flow.yaml|spec.json>',
+  'flows run [--json] [--no-spawn] [--no-observer-link] [--data-dir <dir>] [--local-agent [--agent-capacity <n>]] [--reuse-from <run-id>] <flow.yaml|spec.json>',
   'flows run --cloud [--json] [--wait] [--sync-code] [--no-connect] <flow.yaml|spec.json>',
   'flows run --cloud [--json] [--wait] [--sync-code] [--no-connect] <flow.ts> --input <inline-json-or-file>',
   'flows sync [--json] [--dry-run] [--dir <path>] <run-id>',
-  'flows run [--json] [--no-spawn] [--no-observer-link] [--data-dir <dir>] [--local-agent] <flow.ts> --input <inline-json-or-file>',
+  'flows run [--json] [--no-spawn] [--no-observer-link] [--data-dir <dir>] [--local-agent [--agent-capacity <n>]] <flow.ts> --input <inline-json-or-file>',
   'flows tick start --schedule-id <id> --interval-ms <ms> [--epoch-ms <ms>] [--max-catch-up <n>] [--poll-interval-ms <ms>] [--data-dir <dir>] <spec.json>',
-  'flows resume [--allow-human-influenced] [--json] [--no-spawn] [--no-observer-link] [--data-dir <dir>] [--local-agent] <run-id>',
+  'flows resume [--allow-human-influenced] [--json] [--no-spawn] [--no-observer-link] [--data-dir <dir>] [--local-agent [--agent-capacity <n>]] <run-id>',
   'flows answer [--json] [--no-spawn] [--data-dir <dir>] [--note <text>] [--by <identity>] <run-id> <wait-id> <yes|no>',
   'flows replay [--allow-human-influenced] [--json] [--data-dir <dir>] <run-id> [--at <step-id>]',
   'flows status [--json] [--data-dir <dir>] [--tail <n>] [<run-id>]',
@@ -295,6 +297,7 @@ export async function runCli(
     onPtyReady: (path: string) => io.stderr(`PTY ${path}`),
     ...(parsed.command === 'run' && parsed.reuseFromRunId !== undefined ? { reuseFromRunId: parsed.reuseFromRunId } : {}),
     localAgent: parsed.localAgent,
+    ...(parsed.agentCapacity === undefined ? {} : { agentCapacity: parsed.agentCapacity }),
     onProgress: showProgress,
     onWait: (progress: RunProgress) => {
       emitWait(progress, io);
@@ -581,6 +584,7 @@ function parseArgs(args: readonly string[]): ParsedArgs | undefined {
   let syncCode = false;
   let noConnect = false;
   let localAgent = false;
+  let agentCapacity: number | undefined;
   let allowHumanInfluenced = false;
   let dataDir = DEFAULT_DATA_DIR;
   let sawDataDir = false;
@@ -612,6 +616,14 @@ function parseArgs(args: readonly string[]): ParsedArgs | undefined {
       localAgent = true;
       continue;
     }
+    if (argument === '--agent-capacity') {
+      // Decimal digits only: `Number` would also read "0x4", "4e0" and " 4".
+      const value = args[++index];
+      if (command === 'check' || agentCapacity !== undefined || value === undefined || !/^[0-9]+$/.test(value)) return undefined;
+      agentCapacity = Number(value);
+      if (!isAgentCapacity(agentCapacity)) return undefined;
+      continue;
+    }
     if (argument === '--watch') {
       if (command !== 'check' || watch) return undefined;
       watch = true;
@@ -669,6 +681,8 @@ function parseArgs(args: readonly string[]): ParsedArgs | undefined {
     positionals.push(argument);
   }
   if (positionals.length !== 1) return undefined;
+  // It sizes the in-process worker, so without `--local-agent` it describes nothing.
+  if (agentCapacity !== undefined && !localAgent) return undefined;
 
   if (bucket !== undefined && (cloud || !parseDigestReference(positionals[0]!))) return undefined;
   if (cloud) {
@@ -688,8 +702,8 @@ function parseArgs(args: readonly string[]): ParsedArgs | undefined {
   return command === 'check'
     ? { command, json, watch, value: positionals[0]! }
     : command === 'run'
-      ? { command, bucket, reuseFromRunId, localAgent, dataDir, input, json, spawn, noObserverLink, allowHumanInfluenced, value: positionals[0]! }
-      : { command, localAgent, dataDir, json, spawn, noObserverLink, allowHumanInfluenced, value: positionals[0]! };
+      ? { command, bucket, reuseFromRunId, localAgent, agentCapacity, dataDir, input, json, spawn, noObserverLink, allowHumanInfluenced, value: positionals[0]! }
+      : { command, localAgent, agentCapacity, dataDir, json, spawn, noObserverLink, allowHumanInfluenced, value: positionals[0]! };
 }
 
 /**
@@ -927,6 +941,17 @@ function parseTickArgs(rest: readonly string[]): ParsedArgs | undefined {
   };
 }
 
+const MODEL_PROVENANCE: Readonly<Record<CliModelSource, string>> = {
+  step: 'step',
+  named: 'named agent',
+  adapter: 'adapter default',
+};
+
+/** A resolution carrying no model source prints no provenance rather than a guess. */
+function modelProvenance(source: CliModelSource | undefined): string {
+  return source === undefined ? '' : ` from ${MODEL_PROVENANCE[source]}`;
+}
+
 function emitCheckReport(report: CheckReport, json: boolean, io: CliIo): void {
   emitDiagnostics(report.diagnostics, io);
   if (json) {
@@ -963,8 +988,14 @@ function emitCheckReport(report: CheckReport, json: boolean, io: CliIo): void {
     const config = resolution.source === 'project' && report.projectConfigPath !== undefined
       ? ` (${report.projectConfigPath})`
       : '';
-    const model = resolution.model === undefined ? '' : ` model "${resolution.model}"`;
-    io.stdout(`RESOLVED step "${resolution.stepId}" cli "${resolution.cli}"${model} from ${resolution.source}${config}`);
+    // `from <source>` describes whatever noun precedes it, and the source here
+    // is the CLI's. Printing it after the model made every step whose CLI and
+    // model come from different places claim the model was declared where the
+    // CLI was — a step `cli:` plus an adapter default read as `from step`.
+    const model = resolution.model === undefined
+      ? ''
+      : ` model "${resolution.model}"${modelProvenance(resolution.modelSource)}`;
+    io.stdout(`RESOLVED step "${resolution.stepId}" cli "${resolution.cli}" from ${resolution.source}${config}${model}`);
   }
   // What the workspace must have connected before this flow can run there;
   // the hosted verbs check the same list against Cloud before submitting.

package/src/failure-kinds.ts

@@ -177,9 +177,17 @@ export interface StepFailedDetails {
    */
   maxIterations?: number;
   exitCode?: number;
-  /** Terminal-safe UTF-8 excerpt, at most 1,024 bytes. */
+  /**
+   * Terminal-safe UTF-8 excerpt of the captured stdout, at most
+   * `EXCERPT_BYTES` (cli/step-excerpt.ts). The field name is kept for
+   * compatibility; it is no longer a plain tail. When the captured field did
+   * not fit, the excerpt keeps a head, the lines from the elided middle that
+   * match a failure marker, and a tail, and states the elision in band. The
+   * absence of an elision marker means the field the journal carried fit
+   * whole — not that the command printed no more than this.
+   */
   stdoutTail?: string;
-  /** Terminal-safe UTF-8 excerpt, at most 1,024 bytes. */
+  /** Terminal-safe UTF-8 excerpt of the captured stderr; see `stdoutTail`. */
   stderrTail?: string;
   /**
    * The daemon's own account when it was not a render of the fields above, or

package/src/journal-client.ts

@@ -61,6 +61,8 @@ export class JournalProtocolError extends Error {
 
 export class JournalClient extends EventEmitter {
   private socket: Socket | null = null;
+  /** Why the connection ended, so a later "not connected" names its cause rather than hiding it. */
+  private disconnectCause: Error | undefined;
   private buffer = '';
   private readonly pending = new Map<string, Pending>();
   private readonly requestTimeoutMs: number;
@@ -103,18 +105,31 @@ export class JournalClient extends EventEmitter {
       socket.once('connect', () => {
         clearTimeout(timer);
         socket.removeListener('error', onError);
-        socket.on('error', (err) => this.failAll(err));
+        socket.on('error', (err) => { this.disconnectCause ??= err; this.failAll(err); });
         socket.on('data', (chunk) => this.onData(chunk));
-        socket.on('close', () => this.failAll(new Error('journal client: connection closed')));
+        socket.on('close', () => {
+          const closed = new Error('journal client: connection closed');
+          this.disconnectCause ??= closed;
+          this.failAll(closed);
+        });
+        this.disconnectCause = undefined;
         this.socket = socket;
         resolve();
       });
     });
   }
 
-  /** Close the connection and reject any pending requests. */
-  close(): void {
-    this.failAll(new Error('journal client: closed by caller'));
+  /**
+   * Close the connection and reject any pending requests. A `cause` (for
+   * example the worker failure that forced the close) is carried into every
+   * later "not connected" rejection.
+   */
+  close(cause?: unknown): void {
+    const closed = cause === undefined
+      ? new Error('journal client: closed by caller')
+      : new Error(`journal client: closed after ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+    this.disconnectCause ??= closed;
+    this.failAll(closed);
     this.socket?.destroy();
     this.socket = null;
     this.buffer = '';
@@ -170,7 +185,11 @@ export class JournalClient extends EventEmitter {
   ): Promise<VerbContract[V]['result']> {
     return new Promise((resolve, reject) => {
       if (!this.socket || this.socket.destroyed) {
-        reject(new Error(`journal client: not connected (${verb})`));
+        const cause = this.disconnectCause;
+        reject(new Error(
+          `journal client: not connected (${verb})${cause === undefined ? '' : `: ${cause.message}`}`,
+          cause === undefined ? undefined : { cause },
+        ));
         return;
       }
       const id = randomUUID();

package/src/llm-worker.ts

@@ -1,4 +1,5 @@
 import { workerSpend } from './worker-spend.js';
+import { DEFAULT_LOCAL_AGENT_CAPACITY } from './worker-slots.js';
 import type { WorkerCliResult } from './worker-cli.js';
 import { EventEmitter } from 'node:events';
 import type { JournalClient } from './journal-client.js';
@@ -17,7 +18,11 @@ export class LlmWorker extends EventEmitter {
   private closing = false;
   private readonly inFlight = new Set<Promise<void>>();
 
-  constructor(private readonly client: JournalClient, private readonly workerId: string) {
+  constructor(
+    private readonly client: JournalClient,
+    private readonly workerId: string,
+    private readonly capacity: number = DEFAULT_LOCAL_AGENT_CAPACITY,
+  ) {
     super();
   }
 
@@ -25,7 +30,7 @@ export class LlmWorker extends EventEmitter {
     if (this.attached || this.closing) throw new Error('llm worker: cannot attach twice or after close');
     this.client.on('step.dispatch', this.onDispatch);
     try {
-      await this.client.workerAttach(this.workerId, ['llm'], { workspace: [], streams: [] }, 1);
+      await this.client.workerAttach(this.workerId, ['llm'], { workspace: [], streams: [] }, this.capacity);
       this.attached = true;
     } catch (error) {
       this.client.off('step.dispatch', this.onDispatch);

package/src/local-agent.ts

@@ -1,6 +1,7 @@
 import { randomUUID } from 'node:crypto';
 import type { JournalClient } from './journal-client.js';
 import { AgentWorker } from './worker.js';
+import { DEFAULT_LOCAL_AGENT_CAPACITY } from './worker-slots.js';
 
 /** A local worker for stream-only steps; no workspace recovery is claimed. */
 export async function attachLocalAgent(
@@ -8,6 +9,7 @@ export async function attachLocalAgent(
   dataDir?: string,
   onPtyReady?: (path: string) => void,
   requestedStream?: string,
+  capacity: number = DEFAULT_LOCAL_AGENT_CAPACITY,
 ): Promise<{
   stream: string;
   readonly failure: unknown;
@@ -18,12 +20,16 @@ export async function attachLocalAgent(
   const stream = requestedStream ?? `local-agent-${randomUUID()}`;
   const worker = new AgentWorker(client, {
     workerId: stream,
-    capacity: 1,
+    // More than one: independent agent steps run side by side instead of the
+    // second parking behind the first. Authored bodies size their admission to
+    // this same number (worker-slots.ts), so they never ask for more.
+    capacity,
     dataDir, onPtyReady,
     pins: { workspace: [], streams: [{ stream, read_offset: 0 }] },
   });
   let failure: unknown;
-  worker.on('error', error => { failure = error; client.close(); });
+  // The cause travels with the close, so the flow's next request names it.
+  worker.on('error', error => { failure = error; client.close(error); });
   await worker.attach();
   return {
     stream,

package/src/preflight.ts

@@ -395,7 +395,9 @@ function unknownModelDiagnostics(
       stepId: step.id,
       ...(resolution === undefined ? {} : { cli: resolution.cli }),
       model,
-      message: unknownModelMessage(step.id, model, resolution?.cli, options.modelRegistryPath),
+      message: unknownModelMessage(
+        step.id, model, resolution?.cli, options.modelRegistryPath, resolution?.modelSource,
+      ),
     });
   }
 
@@ -418,15 +420,46 @@ function isKnownModel(model: string, models: readonly string[] | undefined): boo
   return models?.includes(model) === true;
 }
 
+/**
+ * Attribute an effective model to where its value actually came from. Only a
+ * `step` value was written on the step; saying "declares" about an adapter
+ * default sends the reader looking for a `model:` key that is not there.
+ */
+function describeEffectiveModel(
+  stepId: string,
+  model: string,
+  cli: string,
+  modelSource: CliModelSource | undefined,
+): string {
+  if (modelSource === 'adapter') {
+    return `Step "${stepId}" declares no model; the default for CLI "${cli}" is "${model}"`;
+  }
+  if (modelSource === 'named') {
+    return `Step "${stepId}" uses model "${model}" from its named agent for CLI "${cli}"`;
+  }
+  return `Step "${stepId}" declares model "${model}" for CLI "${cli}"`;
+}
+
 function unknownModelMessage(
   stepId: string,
   model: string,
   cli: string | undefined,
   registryPath: string | undefined,
+  modelSource: CliModelSource | undefined,
 ): string {
   const source = registryPath === undefined
     ? 'the nearest project config (no model registry was found)'
     : `project model registry "${registryPath}"`;
+  if (modelSource === 'adapter' && cli !== undefined) {
+    // Registry policy still governs a default — it is the model that will run
+    // — but the remedy has to name the value the author never typed, and the
+    // second way out: declaring a model the registry already allows.
+    const add = registryPath === undefined
+      ? 'add the exact model'
+      : `add the exact model to "models" in "${registryPath}"`;
+    return `${describeEffectiveModel(stepId, model, cli, modelSource)}, which is not listed in ${source}; `
+      + `${add} only after verifying that project is allowed to use it, or declare an allowed model on the step.`;
+  }
   const cliContext = cli === undefined ? '' : ` for CLI "${cli}"`;
   return `Step "${stepId}" declares model "${model}"${cliContext}, but it is not listed in ${source}; add the exact model only after verifying that project is allowed to use it.`;
 }
@@ -545,7 +578,9 @@ function probeResolvedCli(
       stepId: resolution.stepId,
       cli: resolution.cli,
       model: resolution.model,
-      message: `Step "${resolution.stepId}" declares model "${resolution.model}" for CLI "${resolution.cli}", but its model-scoped "${result.modelCommand ?? `${resolution.cli} auth status`}" probe exited non-zero; verify the model name and this credential's access.`,
+      message: describeEffectiveModel(resolution.stepId, resolution.model, resolution.cli, resolution.modelSource)
+        + `, but its model-scoped "${result.modelCommand ?? `${resolution.cli} auth status`}" probe exited non-zero;`
+        + ` verify the model name and this credential's access.`,
     });
   }
 }

package/src/promise-ancestry.ts

@@ -0,0 +1,98 @@
+/**
+ * Which of a fixed set of `targets` each of `starts` can reach by following
+ * `edgesOf` — the batch form of asking `dependsOn(start, target)` for every
+ * pair, with the same answer (a node reaches itself).
+ *
+ * The completion gate used to ask that pair-by-pair, re-walking each start's
+ * whole ancestry every time: operations × combinator members × tracked
+ * promises. A flow of ~110 steps whose agents ran for twenty minutes produced
+ * enough tracked promises (journal polling while each step waited) that the
+ * gate ran for three minutes without yielding, starving the root's lease
+ * renewal until the run was reaped as crashed.
+ *
+ * Here the upward closure of every start is visited once, cycles (a promise
+ * resolved from a context created after it) are condensed with an iterative
+ * Tarjan pass, and target sets flow as bitsets from ancestors to descendants
+ * in the order Tarjan emits components. Cost is O((V + E) · ⌈T / 32⌉) for the
+ * visited subgraph, whatever the number of starts.
+ */
+export function reachableTargets(
+  starts: readonly number[],
+  targets: readonly number[],
+  edgesOf: (node: number) => readonly number[],
+): Map<number, ReadonlySet<number>> {
+  const bit = new Map<number, number>();
+  for (const target of targets) if (!bit.has(target)) bit.set(target, bit.size);
+  const words = Math.max(1, Math.ceil(bit.size / 32));
+
+  const index = new Map<number, number>();
+  const low = new Map<number, number>();
+  const onStack = new Set<number>();
+  const stack: number[] = [];
+  const component = new Map<number, number>();
+  const labels: Uint32Array[] = [];
+
+  const closeComponent = (root: number): void => {
+    const label = new Uint32Array(words);
+    const members: number[] = [];
+    let member: number;
+    do {
+      member = stack.pop()!;
+      onStack.delete(member);
+      members.push(member);
+    } while (member !== root);
+    const id = labels.length;
+    for (const node of members) component.set(node, id);
+    for (const node of members) {
+      const own = bit.get(node);
+      if (own !== undefined) label[own >>> 5]! |= 1 << (own & 31);
+      // Every edge leaving the component points at one Tarjan already closed.
+      for (const edge of edgesOf(node)) {
+        const target = component.get(edge);
+        if (target === undefined || target === id) continue;
+        const inherited = labels[target]!;
+        for (let word = 0; word < words; word++) label[word]! |= inherited[word]!;
+      }
+    }
+    labels.push(label);
+  };
+
+  // Iterative Tarjan: a deep promise chain must not overflow the JS stack.
+  for (const start of starts) {
+    if (index.has(start)) continue;
+    const frames: Array<{ node: number; edges: readonly number[]; next: number }> = [];
+    const open = (node: number): void => {
+      index.set(node, index.size);
+      low.set(node, index.get(node)!);
+      stack.push(node);
+      onStack.add(node);
+      frames.push({ node, edges: edgesOf(node), next: 0 });
+    };
+    open(start);
+    while (frames.length > 0) {
+      const frame = frames.at(-1)!;
+      if (frame.next < frame.edges.length) {
+        const edge = frame.edges[frame.next++]!;
+        if (!index.has(edge)) open(edge);
+        else if (onStack.has(edge)) low.set(frame.node, Math.min(low.get(frame.node)!, index.get(edge)!));
+        continue;
+      }
+      frames.pop();
+      const parent = frames.at(-1);
+      if (parent !== undefined) low.set(parent.node, Math.min(low.get(parent.node)!, low.get(frame.node)!));
+      if (low.get(frame.node) === index.get(frame.node)) closeComponent(frame.node);
+    }
+  }
+
+  const reached = new Map<number, ReadonlySet<number>>();
+  for (const start of starts) {
+    if (reached.has(start)) continue;
+    const label = labels[component.get(start)!]!;
+    const found = new Set<number>();
+    for (const [target, position] of bit) {
+      if ((label[position >>> 5]! & (1 << (position & 31))) !== 0) found.add(target);
+    }
+    reached.set(start, found);
+  }
+  return reached;
+}

package/src/validate.ts

@@ -486,6 +486,13 @@ class Validator {
     }
     this.validateCli(st.cli, at);
     this.validateModel(st.model, at);
+    // The kernel refuses a relative cwd at run.start; refuse it here so `flows
+    // check` and the run agree. Not resolved against the checking directory:
+    // that would make the compiled spec (and its hash) depend on where the
+    // check ran. `f.agent` resolves before compiling, so it never lands here.
+    if (st.cwd !== undefined && (!isNonEmptyString(st.cwd) || !st.cwd.startsWith('/'))) {
+      this.fail(`${at}.cwd: expected an absolute path (got ${JSON.stringify(st.cwd)})`);
+    }
     if (st.surfaces !== undefined) this.validateSurfaces(st.surfaces, `${at}.surfaces`);
     if (st.permissions !== undefined) this.validatePermissions(st.permissions, `${at}.permissions`);
   }

package/src/worker-cli.ts

@@ -1,5 +1,5 @@
 import { realpathSync } from 'node:fs';
-import { resolve, sep } from 'node:path';
+import { basename, dirname, join, resolve, sep } from 'node:path';
 import { diffWorkspaceFiles, snapshotWorkspaceFiles } from './agent-artifacts.js';
 import { claudeResultOutcome, decodeProviderResult, decodeWrapperResult, requirePricedUsage } from './worker-usage.js';
 import { openSidechannel, type SidechannelContext } from './pty-sidechannel.js';
@@ -121,7 +121,7 @@ export async function runAgentCli(
   const artifactRoot = mode === 'agent' ? resolve(cwd ?? process.cwd()) : undefined;
   return artifactRoot === undefined
     ? execute()
-    : serializedByDirectory(artifactRoot, async () => {
+    : serializedByDirectory(canonicalTree(artifactRoot), async () => {
       const before = await snapshotWorkspaceFiles(artifactRoot);
       const result = await execute();
       const kernelData = sidechannel === undefined ? undefined : realPath(resolve(sidechannel.dataDir));
@@ -214,20 +214,52 @@ function under(path: string | undefined, directory: string | undefined): boolean
   return path === directory || path.startsWith(directory.endsWith(sep) ? directory : directory + sep);
 }
 
+/**
+ * Symlink-free form of an absolute path that may not exist yet: the deepest
+ * existing ancestor is resolved and the missing tail is kept. A plain
+ * `realPath` fallback would leave `/link/new` unresolved while `/link`
+ * resolves, and the overlap check would then treat them as disjoint trees.
+ */
+export function canonicalTree(path: string): string {
+  const missing: string[] = [];
+  let current = path;
+  for (;;) {
+    try {
+      return join(realpathSync(current), ...missing.reverse());
+    } catch {
+      const parent = dirname(current);
+      if (parent === current) return path;
+      missing.push(basename(current));
+      current = parent;
+    }
+  }
+}
+
 /** Symlink-free form of a path, or the path itself when it cannot be resolved. */
 function realPath(path: string | undefined): string | undefined {
   if (path === undefined) return undefined;
   try { return realpathSync(path); } catch { return path; }
 }
 
-/** One agent at a time per canonical working directory, for the artifact interval. */
-const directoryQueues = new Map<string, Promise<unknown>>();
+/**
+ * One agent at a time per overlapping working tree, for the artifact interval.
+ *
+ * `directory` must be canonical (symlink-free): `/repo` and a `/tmp/link` to it
+ * are one tree. Two trees overlap when one contains the other, because the
+ * snapshot walks the whole subtree — an agent in `/repo` would otherwise be
+ * credited with files an agent in `/repo/.wt/api` wrote meanwhile. Disjoint
+ * trees (sibling worktrees) run side by side. Each run waits for every
+ * earlier-registered overlapping run, so order within an overlap is arrival.
+ */
+const directoryRuns = new Set<{ readonly directory: string; readonly settled: Promise<void> }>();
 function serializedByDirectory<T>(directory: string, task: () => Promise<T>): Promise<T> {
-  const previous = directoryQueues.get(directory) ?? Promise.resolve();
-  const run = previous.then(task, task);
-  const settled = run.then(() => undefined, () => undefined);
-  directoryQueues.set(directory, settled);
-  void settled.then(() => { if (directoryQueues.get(directory) === settled) directoryQueues.delete(directory); });
+  const blockers = [...directoryRuns]
+    .filter(other => under(other.directory, directory) || under(directory, other.directory))
+    .map(other => other.settled);
+  const run = Promise.all(blockers).then(task);
+  const entry = { directory, settled: run.then(() => undefined, () => undefined) };
+  directoryRuns.add(entry);
+  void entry.settled.then(() => { directoryRuns.delete(entry); });
   return run;
 }
 

package/src/worker-slots.ts

@@ -0,0 +1,92 @@
+/** The local agent worker's default concurrency, and the ceiling `--agent-capacity` accepts. */
+export const DEFAULT_LOCAL_AGENT_CAPACITY = 4;
+export const MAX_LOCAL_AGENT_CAPACITY = 32;
+
+/** A positive integer no larger than the ceiling; anything else is not a capacity. */
+export function isAgentCapacity(value: unknown): value is number {
+  return Number.isInteger(value) && (value as number) >= 1 && (value as number) <= MAX_LOCAL_AGENT_CAPACITY;
+}
+
+/**
+ * First-come admission to a worker that holds `capacity` dispatches at once.
+ *
+ * The kernel never queues a step for a busy worker: an attempt with no worker
+ * below capacity parks the run ("no worker is attached for step type …"). An
+ * authored body opens one child run per `f.agent`/`f.llm`, so `Promise.all`
+ * over more calls than the worker holds would park the overflow. Holding the
+ * overflow here, before `run.start`, keeps the kernel's admission exact and
+ * turns "too many at once" into "wait for a slot".
+ */
+export class WorkerSlots {
+  private held = 0;
+  private readonly waiting: Array<{ resolve: () => void; reject: (reason: unknown) => void }> = [];
+  private closed: { readonly reason: unknown } | undefined;
+
+  constructor(readonly capacity: number) {
+    if (!isAgentCapacity(capacity)) throw new RangeError(`worker capacity must be an integer from 1 to ${MAX_LOCAL_AGENT_CAPACITY} (got ${capacity})`);
+  }
+
+  async run<T>(work: () => Promise<T>): Promise<T> {
+    if (this.closed !== undefined) throw this.closed.reason;
+    if (this.held < this.capacity) this.held++;
+    // A released slot is handed straight to the next waiter, so `held` never
+    // dips below capacity while anyone is queued and no later caller can jump it.
+    else {
+      await new Promise<void>((resolve, reject) => this.waiting.push({ resolve, reject }));
+      // Woken with the slot, but the body may have failed in between (see release).
+      const closed = this.closedReason();
+      if (closed !== undefined) {
+        this.release();
+        throw closed.reason;
+      }
+    }
+    try {
+      return await work();
+    } finally {
+      this.release();
+    }
+  }
+
+  /** Read through a call so a check after an `await` is not narrowed away. */
+  private closedReason(): { readonly reason: unknown } | undefined {
+    return this.closed;
+  }
+
+  /**
+   * Hand the slot to the next waiter on a later macrotask, not synchronously.
+   * When the work that held it rejected and that rejection fails the body, the
+   * failure reaches `close` through microtasks only (operation → Promise.all →
+   * body → executor). Waking the waiter synchronously let it admit a child run
+   * before `close` could refuse it; deferring lets the teardown land first.
+   */
+  private release(): void {
+    const next = this.waiting.shift();
+    if (next === undefined) {
+      this.held--;
+      return;
+    }
+    setImmediate(() => {
+      if (this.closed === undefined) {
+        next.resolve();
+        return;
+      }
+      // Closed meanwhile. `close` could not see this waiter (already taken off
+      // the queue), so refuse it here, and pass the slot on instead of leaking it.
+      next.reject(this.closed.reason);
+      this.release();
+    });
+  }
+
+  /**
+   * Refuse every queued and future admission with `reason`; work already
+   * holding a slot is not interrupted. The authored body calls this when it
+   * fails: a queued call is already `running` as an operation, so operation
+   * cancellation cannot reach it, and without this it would still be admitted
+   * and run after the flow had failed.
+   */
+  close(reason: unknown): void {
+    if (this.closed !== undefined) return;
+    this.closed = { reason };
+    for (const waiter of this.waiting.splice(0)) waiter.reject(reason);
+  }
+}