@relayflows/sdk 2.0.27 → 2.0.28

package/src/cli/run.ts

@@ -26,6 +26,7 @@ import type {
   RunStatus,
 } from '../protocol.js';
 import type { StepType } from '../spec.js';
+import { DEFAULT_LOCAL_AGENT_CAPACITY } from '../worker-slots.js';
 import type { LoweredCompletionReason } from '../authored-flow-executor.js';
 import {
   checkFlow,
@@ -91,6 +92,8 @@ export interface RunLifecycleOptions {
   reuseFromRunId?: string;
   onProgress?: (event: ProgressEvent) => void;
   localAgent?: boolean;
+  /** `--agent-capacity`: the local workers' concurrency; the default is `DEFAULT_LOCAL_AGENT_CAPACITY`. */
+  agentCapacity?: number;
   signal?: AbortSignal;
   onWait?: (progress: RunProgress) => void;
   /**
@@ -148,7 +151,9 @@ async function executeCheckedFlow(
     const spec = toKernelSpec(checked.flow!);
     // Use the checked CLI/model and declared surfaces unchanged. The worker
     // advertises its existing pins; the daemon still owns surface matching.
-    if (options.localAgent) localAgent = await attachLocalAgent(client, dataDir, options.onPtyReady);
+    if (options.localAgent) {
+      localAgent = await attachLocalAgent(client, dataDir, options.onPtyReady, undefined, options.agentCapacity);
+    }
     if (options.localAgent && spec.steps.some(step => step.type === 'agent' && communicationInstruction(step.instruction))) {
       const { attachCommunicationWorkers } = await import('../communication/local.js');
       communicationWorkers = await attachCommunicationWorkers(spec, socketPath, dataDir);
@@ -192,6 +197,7 @@ export async function resumeFlow(
   let authoredAgent: Awaited<ReturnType<typeof attachLocalAgent>> | undefined;
   let authoredLlm: LlmWorker | undefined;
   let authoredLlmClient: JournalClient | undefined;
+  const workerCapacity = options.agentCapacity ?? DEFAULT_LOCAL_AGENT_CAPACITY;
   try {
     const authoredRoot = await readAuthoredRootMetadata(client, runId);
     if (authoredRoot !== undefined) {
@@ -203,17 +209,18 @@ export async function resumeFlow(
       }
       if (options.localAgent) {
         authoredAgent = await attachLocalAgent(
-          client, dataDir, options.onPtyReady, authoredRoot.localAgentStream,
+          client, dataDir, options.onPtyReady, authoredRoot.localAgentStream, workerCapacity,
         );
         authoredLlmClient = new JournalClient(socketPath);
         await authoredLlmClient.connect();
         await authoredLlmClient.hello('flows-authored-resume-llm');
-        authoredLlm = new LlmWorker(authoredLlmClient, `${authoredAgent.stream}-llm`);
+        authoredLlm = new LlmWorker(authoredLlmClient, `${authoredAgent.stream}-llm`, workerCapacity);
         await authoredLlm.attach();
       }
       const result = await resumeDurableAuthoredFlow(runId, client, {
         dataDir,
         localAgentStream: authoredAgent?.stream,
+        ...(authoredAgent === undefined ? {} : { workerCapacity }),
         lifecycle: options,
       });
       if (result === undefined) throw new Error('authored root disappeared during resume');
@@ -224,7 +231,7 @@ export async function resumeFlow(
     // second call the earlier rebase left is a stale reference from before
     // the helper fanout renamed the API.
     if (options.localAgent) {
-      authoredAgent = await attachLocalAgent(client, dataDir, options.onPtyReady);
+      authoredAgent = await attachLocalAgent(client, dataDir, options.onPtyReady, undefined, options.agentCapacity);
       const entries = (await client.journalRead(runId, 1)).entries as Array<{ entry_type: string; payload?: { spec?: import('../spec.js').KernelRunSpec } }>;
       const spec = entries.find(entry => entry.entry_type === 'run.spawned')?.payload?.spec;
       if (spec?.steps.some(step => step.type === 'agent' && communicationInstruction(step.instruction))) {

package/src/cli/step-excerpt.ts

@@ -0,0 +1,332 @@
+/**
+ * One captured stream, cut to something a terminal can print WITHOUT throwing
+ * away the line that says what failed.
+ *
+ * The render this replaces kept the last 1,024 bytes. For any runner that
+ * streams results and prints its summary last — TAP (`node --test`), cargo,
+ * vitest, pytest — the last kilobyte is by construction the totals and the
+ * final few passing cases, so the one `not ok` was always the part that got
+ * cut. A report that proves a failure happened and withholds which one costs
+ * the reader a local re-run, which is the loop the gate exists to avoid.
+ *
+ * So the excerpt is three disjoint ranges of the same source, in source order:
+ * a head, the lines in the elided middle that look like a failing case, and a
+ * tail. The elision is stated in band, in bytes, so the reader is never left
+ * guessing whether what they are looking at is all of it.
+ *
+ * What this can and cannot promise:
+ *
+ * - It selects from the field the journal carried, which for a deterministic
+ *   step is the last 64 KiB the kernel captured (`OUTPUT_TAIL_BYTES`,
+ *   relayflowd/src/exec_det.rs). A failure printed before that window is not
+ *   here to be found, and no marker can say so — hence `captured excerpt`
+ *   rather than a claim about the command's whole output.
+ * - The absence of an elision marker means the supplied field fit whole. It
+ *   does not mean the command printed nothing more.
+ * - The markers are hints, not a parser. They find the common runners' failing
+ *   lines; ordinary prose can match one, and an unknown format matches none
+ *   and still gets head-and-tail context.
+ */
+
+/** Default excerpt budget, in UTF-8 bytes, for one captured stream. */
+export const EXCERPT_BYTES = 4_096;
+
+/**
+ * Below this there is no room to both elide and say so, and an excerpt that
+ * silently drops the claim it makes about itself is the bug being fixed. The
+ * budget is a constant of this module, not configuration, so a caller that
+ * asks for less has made a programming error and is told at the call.
+ */
+export const MIN_EXCERPT_BYTES = 256;
+
+/** How many matched lines the elided middle may contribute. */
+const MAX_HIGHLIGHT_LINES = 20;
+
+/** A highlight cut short is only worth showing if some of the line survives. */
+const MIN_HIGHLIGHT_BYTES = 24;
+
+/** Newlines this module inserts between ranges and markers. */
+const SEPARATOR_RESERVE = 16;
+
+const END_MARKER = '… end of elided region …';
+const TRUNCATED_MARKER = '… line truncated …';
+
+/**
+ * Lines that name a failing case, for the runners this repo actually runs.
+ *
+ * Each is anchored after optional indentation (nested TAP indents its
+ * subtests) and is matched against a comparison view of the line with
+ * terminal escapes removed, so a coloured `FAIL` header still matches. They
+ * are constants rather than user input, which is why `RegExp` is correct
+ * here; a spec-supplied pattern would be untrusted and would have to go
+ * through `re2js`.
+ */
+const FAILURE_MARKERS: readonly RegExp[] = [
+  /^\s*not ok\b/u, // TAP: node --test, prove
+  /^\s*FAILED\b/u, // pytest short test summary: `FAILED tests/x.py::y - ...`
+  /^\s*FAIL\b/u, // vitest / jest file header: `FAIL src/x.test.ts`
+  /^\s*[✖✗×]\s/u, // vitest / jest failure glyph
+  /\.\.\.\s*FAILED\b/u, // cargo: `test pty::exit ... FAILED`
+  /^\s*---- .* ----\s*$/u, // cargo: `---- pty::exit stdout ----`
+  /\bpanicked at\b/u, // rust panic
+];
+
+interface Range { start: number; end: number }
+
+/**
+ * Cut `value` to at most `budget` UTF-8 bytes, markers included.
+ *
+ * A stream that already fits is returned whole (sanitised) with no marker. One
+ * that does not keeps a head of whole lines, up to `MAX_HIGHLIGHT_LINES`
+ * matched lines from the elided middle, and a tail that fills what is left.
+ * Every cut is at a code-point boundary, so slicing never invents a U+FFFD.
+ */
+export function formatStepExcerpt(value: string, budget: number = EXCERPT_BYTES): string {
+  if (!Number.isSafeInteger(budget) || budget < MIN_EXCERPT_BYTES) {
+    throw new Error(`step excerpt budget must be an integer of at least ${MIN_EXCERPT_BYTES} bytes`);
+  }
+  const source = Buffer.from(value, 'utf8');
+  // Sanitised from the original string, not from the round trip: a lone
+  // surrogate the wire delivered is the caller's to keep, and re-encoding it
+  // would be this module inventing a replacement character.
+  if (source.length <= budget) return sanitise(value);
+
+  const lines = lineRanges(source);
+  const matches = lines.filter(isFailureLine(source));
+  // Content space is what is left after the markers can be afforded at their
+  // widest, so the excerpt can always state its own elision.
+  const content = Math.max(0, budget - markerReserve(source.length, matches.length));
+  const tailShare = Math.floor(content / 2);
+  const headShare = Math.floor(content / 4);
+  const highlightShare = content - tailShare - headShare;
+
+  const head = headRange(source, lines, headShare);
+  // Provisional tail, which with the head defines the middle the highlights
+  // are drawn from.
+  const highlights = selectHighlights(source, matches, highlightShare,
+    head.end, tailRange(source, tailShare, head.end).start);
+
+  // Every byte the head and the highlights did not need goes to the tail,
+  // which is where a runner puts the summary. The tail may not cross the last
+  // highlight, so the ranges stay disjoint and in source order.
+  const spare = headShare - size(head)
+    + highlightShare - highlights.reduce((sum, highlight) => sum + size(highlight.range), 0);
+  let tail = tailRange(source, tailShare + spare, highlights.at(-1)?.range.end ?? head.end);
+  // A highlight the tail resumes at the very byte it ends is not a range of
+  // its own: the two are one unbroken run of source, so the tail starts at
+  // the highlight instead. The same bytes either way, with no marker between
+  // them claiming a cut the reader can see did not happen.
+  while (highlights.length > 0 && highlights.at(-1)!.range.end === tail.start) {
+    tail = { start: highlights.pop()!.range.start, end: tail.end };
+  }
+
+  const selected = [head, ...highlights.map(highlight => highlight.range), tail]
+    .filter(range => size(range) > 0);
+  const elided = source.length - selected.reduce((sum, range) => sum + size(range), 0);
+  // Positional, not textual: two identical failing lines at two positions are
+  // two observations, and one of them may be visible while the other is not.
+  // Shown means the line's own start is on screen, because the start is what
+  // names the failing case: a highlight cut short still reports it, while a
+  // range that begins in the middle of the line — a tail whose cut landed
+  // there — shows only the part after the name and reports nothing.
+  const omitted = matches.filter(match =>
+    !selected.some(range => range.start <= match.start && range.end > match.start)).length;
+
+  const parts: string[] = [];
+  const terminated = (chunk: string): string => chunk.endsWith('\n') ? chunk : `${chunk}\n`;
+  if (size(head) > 0) parts.push(terminated(text(source, head)));
+  parts.push(`${openMarker(elided, highlights.length, omitted)}\n`);
+  for (const highlight of highlights) {
+    parts.push(terminated(text(source, highlight.range) + (highlight.truncated ? ` ${TRUNCATED_MARKER}` : '')));
+  }
+  if (highlights.length > 0) {
+    if (omitted > 0) parts.push(`${moreMarker(omitted)}\n`);
+    parts.push(`${END_MARKER}\n`);
+  }
+  if (size(tail) > 0) parts.push(text(source, tail));
+  // Sanitising replaces, never expands, so it cannot push the result over the
+  // budget; the clamp is where the byte bound is enforced, for every path.
+  return clampBytes(sanitise(parts.join('')), budget);
+}
+
+/**
+ * `N bytes elided` counts raw source bytes represented by no selected range,
+ * including the omitted portion of a line shown only in part. Source bytes
+ * shown plus source bytes elided is the input, exactly; the markers this
+ * module inserts are not source bytes, and sanitising can shrink what is
+ * displayed without changing what was selected.
+ */
+function openMarker(elided: number, shown: number, omitted: number): string {
+  const matched = shown > 0
+    ? `; ${plural(shown, 'line')} matched a failure marker`
+    : omitted > 0 ? `; ${plural(omitted, 'line')} matched a failure marker, none shown` : '';
+  return `… ${group(elided)} bytes elided${matched} …`;
+}
+
+function moreMarker(omitted: number): string {
+  return `… +${group(omitted)} more matching ${omitted === 1 ? 'line' : 'lines'} …`;
+}
+
+/** Every marker at its widest, so content space can be assigned once. */
+function markerReserve(sourceBytes: number, matches: number): number {
+  const open = Math.max(
+    byteLength(openMarker(sourceBytes, matches, matches)),
+    byteLength(openMarker(sourceBytes, 0, matches)),
+    byteLength(openMarker(sourceBytes, 0, 0)),
+  );
+  const highlighted = matches === 0 ? 0
+    : byteLength(moreMarker(matches)) + byteLength(END_MARKER) + byteLength(TRUNCATED_MARKER) + 1;
+  return open + highlighted + SEPARATOR_RESERVE;
+}
+
+/**
+ * Matched lines from the middle, in source order, bounded by both the line cap
+ * and the byte share. A whole line is preferred; when the first candidate does
+ * not fit at all, a code-point-safe prefix of it is shown under a truncation
+ * marker, because a cut failing line still names the failing case and no
+ * highlight at all does not.
+ *
+ * The middle ends where the tail begins, but a line the tail begins in the
+ * middle of belongs to the middle: the tail shows its tail, and the marker
+ * that names the failing case is ahead of the cut. Such a line is a candidate
+ * like any other, and the caller keeps the ranges disjoint by starting the
+ * tail after whatever prefix is kept.
+ */
+function selectHighlights(
+  source: Buffer, matches: readonly Range[], share: number, from: number, to: number,
+): Array<{ range: Range; truncated: boolean }> {
+  const selected: Array<{ range: Range; truncated: boolean }> = [];
+  let remaining = share;
+  for (const match of matches) {
+    // Reported once, at its own position: a line whose own start is already
+    // on screen — inside the head, or at or after the start of the tail —
+    // needs no highlight.
+    if (match.start < from || match.start >= to) continue;
+    if (selected.length >= MAX_HIGHLIGHT_LINES) break;
+    if (size(match) <= remaining) {
+      selected.push({ range: match, truncated: false });
+      remaining -= size(match);
+      continue;
+    }
+    if (selected.length === 0 && remaining >= MIN_HIGHLIGHT_BYTES) {
+      const end = floorBoundary(source, match.start + remaining);
+      if (end > match.start) selected.push({ range: { start: match.start, end }, truncated: true });
+    }
+    break;
+  }
+  return selected;
+}
+
+/**
+ * Whole lines from the start, or a bounded prefix when the first line alone is
+ * longer than the share — a long first line must not consume the excerpt.
+ * Whatever whole lines leave unspent is returned to the tail by the caller.
+ */
+function headRange(source: Buffer, lines: readonly Range[], limit: number): Range {
+  let end = 0;
+  for (const line of lines) {
+    if (line.end > limit) break;
+    end = line.end;
+  }
+  return { start: 0, end: end === 0 ? floorBoundary(source, limit) : end };
+}
+
+/**
+ * The last `limit` bytes, cut at a code-point boundary and never crossing
+ * `stop` (the end of the head or of the last highlight).
+ *
+ * Unlike the head, the tail fills its share rather than stopping at a line
+ * boundary. A stream can be one enormous line followed by a one-byte last
+ * line; taking whole lines only would spend one byte of a two-kilobyte share
+ * and drop the summary that the old last-1,024-bytes render always kept.
+ */
+function tailRange(source: Buffer, limit: number, stop: number): Range {
+  return { start: Math.max(ceilBoundary(source, source.length - limit), stop), end: source.length };
+}
+
+function isFailureLine(source: Buffer): (line: Range) => boolean {
+  return line => {
+    const comparable = comparableLine(text(source, line));
+    return FAILURE_MARKERS.some(marker => marker.test(comparable));
+  };
+}
+
+/**
+ * The view a marker is matched against: terminal escape sequences and control
+ * characters removed so a coloured `not ok` or `FAIL` header still matches.
+ * This never touches what is rendered — journal data is not mutated, and the
+ * display sanitiser is a separate, later step.
+ */
+function comparableLine(line: string): string {
+  return line
+    .replace(/\u001b\[[0-9;:?]*[ -/]*[@-~]|\u001b[@-Z\\-_]|\u009b[0-9;:?]*[ -/]*[@-~]/gu, '')
+    .replace(/[\p{Cc}\p{Cf}]/gu, character => character === '\t' ? ' ' : '');
+}
+
+/** Line ranges over the raw bytes; each end includes its own `\n` when it has one. */
+function lineRanges(source: Buffer): Range[] {
+  const ranges: Range[] = [];
+  let start = 0;
+  for (let index = 0; index < source.length; index++) {
+    if (source[index] === 0x0a) {
+      ranges.push({ start, end: index + 1 });
+      start = index + 1;
+    }
+  }
+  if (start < source.length) ranges.push({ start, end: source.length });
+  return ranges;
+}
+
+/**
+ * Preserve tabs and newlines; replace binary controls (including ESC and CR),
+ * C1 controls and Unicode formatting controls without growing the excerpt.
+ * Applied on every path, short inputs included: a control sequence in a
+ * two-line stderr is as able to rewrite the terminal as one in a long stream.
+ */
+function sanitise(value: string): string {
+  return value.replace(/[\p{Cc}\p{Cf}]/gu, character =>
+    character === '\n' || character === '\t' ? character : '?');
+}
+
+function clampBytes(value: string, budget: number): string {
+  const bytes = Buffer.from(value, 'utf8');
+  if (bytes.length <= budget) return value;
+  return bytes.subarray(0, floorBoundary(bytes, budget)).toString('utf8');
+}
+
+function text(source: Buffer, range: Range): string {
+  return source.subarray(range.start, range.end).toString('utf8');
+}
+
+function size(range: Range): number {
+  return range.end - range.start;
+}
+
+function isBoundary(source: Buffer, index: number): boolean {
+  return index >= source.length || (source[index]! & 0xc0) !== 0x80;
+}
+
+function floorBoundary(source: Buffer, index: number): number {
+  let at = Math.max(0, Math.min(index, source.length));
+  while (at > 0 && !isBoundary(source, at)) at -= 1;
+  return at;
+}
+
+function ceilBoundary(source: Buffer, index: number): number {
+  let at = Math.max(0, Math.min(index, source.length));
+  while (at < source.length && !isBoundary(source, at)) at += 1;
+  return at;
+}
+
+function byteLength(value: string): number {
+  return Buffer.byteLength(value, 'utf8');
+}
+
+function plural(count: number, noun: string): string {
+  return `${group(count)} ${noun}${count === 1 ? '' : 's'}`;
+}
+
+/** Locale-independent digit grouping: the same excerpt everywhere it is read. */
+function group(value: number): string {
+  return String(value).replace(/\B(?=(\d{3})+(?!\d))/gu, ',');
+}

package/src/cli/step-failure.ts

@@ -2,8 +2,7 @@ import { join } from 'node:path';
 import { DEFAULT_DATA_DIR } from '../daemon-connection.js';
 import type { StepFailedDetails } from '../failure-kinds.js';
 import type { JournalClient } from '../journal-client.js';
-
-const TAIL_BYTES = 1_024;
+import { formatStepExcerpt } from './step-excerpt.js';
 
 /**
  * Read what a failed step left in the journal — for any step type.
@@ -117,8 +116,8 @@ export function renderStepEvidence(details: StepFailedDetails): string {
     + (details.exitCode === undefined ? '' : ` exit=${details.exitCode}`)
     + '.'
     + (details.detail === undefined ? '' : `\nDetail: ${details.detail}`)
-    + (details.stdoutTail ? `\nStdout (last 1,024 bytes):\n${details.stdoutTail}` : '')
-    + (details.stderrTail ? `\nStderr (last 1,024 bytes):\n${details.stderrTail}` : '')
+    + (details.stdoutTail ? `\nStdout (captured excerpt):\n${details.stdoutTail}` : '')
+    + (details.stderrTail ? `\nStderr (captured excerpt):\n${details.stderrTail}` : '')
     + (details.transcriptPath === undefined ? '' : `\nTranscript: ${details.transcriptPath}`);
 }
 
@@ -195,22 +194,22 @@ function evidence(payload: Record<string, unknown>): Partial<StepFailedDetails>
   const structuredShape = structured !== undefined && processShaped(structured);
   const transcript = record(record(payload['trajectory_tail'])?.['transcript']);
   const failure = record(transcript?.['failure']);
-  const excerpt = failure?.['excerpt'];
+  const failureExcerpt = failure?.['excerpt'];
   const transcriptPath = record(transcript?.['file'])?.['path'];
   // The excerpt is the worker's own pick of the failure; a `stderr` excerpt
   // is the same bytes as `stderrTail`, so it is not printed twice.
-  const excerptDetail = typeof excerpt === 'string' && excerpt.length > 0
+  const excerptDetail = typeof failureExcerpt === 'string' && failureExcerpt.length > 0
     && !(failure?.['kind'] === 'stderr' && typeof stderr === 'string')
-    ? tail(excerpt) : undefined;
+    ? formatStepExcerpt(failureExcerpt) : undefined;
   return {
     ...(typeof exitCode === 'number' && Number.isSafeInteger(exitCode) ? { exitCode } : {}),
-    ...(typeof stdout === 'string' && stdout.length > 0 ? { stdoutTail: tail(stdout) } : {}),
-    ...(typeof stderr === 'string' ? { stderrTail: tail(stderr) } : {}),
+    ...(typeof stdout === 'string' && stdout.length > 0 ? { stdoutTail: formatStepExcerpt(stdout) } : {}),
+    ...(typeof stderr === 'string' ? { stderrTail: formatStepExcerpt(stderr) } : {}),
     // Keep the daemon's account only when it was NOT just a render of the
     // fields above — otherwise the same bytes print twice.
     ...(excerptDetail !== undefined ? { detail: excerptDetail }
       : typeof detail === 'string' && detail.length > 0 && !structuredShape
-        ? { detail: tail(detail) } : {}),
+        ? { detail: formatStepExcerpt(detail) } : {}),
     ...(typeof transcriptPath === 'string' && transcriptPath.length > 0 ? { transcriptPath } : {}),
   };
 }
@@ -233,16 +232,6 @@ function record(value: unknown): Record<string, unknown> | undefined {
     ? value as Record<string, unknown> : undefined;
 }
 
-function tail(value: string): string {
-  const bytes = Buffer.from(value, 'utf8');
-  let start = Math.max(0, bytes.length - TAIL_BYTES);
-  // Drop a partial leading code point, avoiding replacement-byte expansion.
-  while (start < bytes.length && (bytes[start]! & 0xc0) === 0x80) start += 1;
-  // Preserve tabs/newlines; replace binary controls (including ESC and CR),
-  // C1 controls and Unicode formatting controls without growing the excerpt.
-  return bytes.subarray(start).toString('utf8')
-    .replace(/[\p{Cc}\p{Cf}]/gu, character => character === '\n' || character === '\t' ? character : '?');
-}
 
 function shellQuote(value: string): string {
   return /^[A-Za-z0-9_-]+$/.test(value) && !value.startsWith('-')

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