@relayflows/sdk 2.0.26 → 2.0.28

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 } : {}),

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' },
   {