@relayflows/sdk 2.0.30 → 2.0.31

package/src/failure-kinds.ts

@@ -74,6 +74,15 @@ export const CHECK_FAILURE_KINDS = [
  * (#442). Warning-only by design: the declaration stays legal and the flow
  * still runs, but an author who wrote one must not be left believing it
  * sandboxes the step.
+ *
+ * `gate_path_unscanned` names an `artifact_exists` path inside a prefix the
+ * bundled agent worker's artifact scan excludes, so the scan can never put it
+ * in the journaled `output.artifacts` the gate reads. It warns rather than
+ * refuses because the scan is not the only writer of that list — the same
+ * worker promotes JSON stdout and completed Relay task output verbatim, and a
+ * custom worker may journal anything — so such a gate is unproven, not
+ * unsatisfiable. Temporary: it describes #513, and retires with
+ * `named-gate-preflight.ts` when the scan stops excluding those paths.
  */
 export const PREFLIGHT_WARNING_KINDS = [
   'unprovable_effects',
@@ -83,6 +92,7 @@ export const PREFLIGHT_WARNING_KINDS = [
   'vacuous_gate',
   'budget_unmetered',
   'permissions_unenforced',
+  'gate_path_unscanned',
 ] as const;
 
 /**
@@ -124,6 +134,14 @@ export const RUN_FAILURE_KINDS = [
   'gate_failed',
   /** `flows answer` named a wait the run is not asking: unknown, or already answered. */
   'human_wait_unknown',
+  /**
+   * `--local-agent` cannot be honoured for this invocation, so it is refused
+   * rather than accepted and ignored. A local agent worker is admitted at run
+   * start and pinned into the authored root's metadata; a resume can only
+   * reproduce the surface the root was started with. Exit 2, before any worker
+   * attaches and before the resume touches the journal.
+   */
+  'local_agent_unavailable',
 ] as const;
 
 /**
@@ -136,8 +154,17 @@ export const RUN_WARNING_KINDS = [
   'connection_file_stale',
 ] as const;
 
-/** File-level editor hints emitted by flows check, outside pure preflight. */
-export const CHECK_WARNING_KINDS = ['editor_schema_missing'] as const;
+/**
+ * Warnings emitted by flows check, outside pure preflight.
+ *
+ * `editor_schema_missing` is a file-level editor hint. `agent_worker_unresolved`
+ * is a property of the *invocation*, not of the spec: a spec with `agent`
+ * steps needs a worker attached for step type `agent`, and only the caller
+ * knows whether it attaches one. `flows check` attaches none and, being
+ * daemon-free, can see none either — so it opts in, while `flows run`, `flows
+ * build` and SDK submissions do not (cli/check-worker-surface.ts).
+ */
+export const CHECK_WARNING_KINDS = ['editor_schema_missing', 'agent_worker_unresolved'] as const;
 export type CheckWarningKind = (typeof CHECK_WARNING_KINDS)[number];
 
 export type PreflightFailureKind = (typeof PREFLIGHT_FAILURE_KINDS)[number];
@@ -146,6 +173,69 @@ export type PreflightWarningKind = (typeof PREFLIGHT_WARNING_KINDS)[number];
 export type RunFailureKind = (typeof RUN_FAILURE_KINDS)[number];
 export type RunWarningKind = (typeof RUN_WARNING_KINDS)[number];
 
+/**
+ * One failed attempt of a step, as the journal recorded it.
+ *
+ * The kernel appends a `step.completed` PER ATTEMPT (relayflowd-core/src/machine.rs
+ * `completion_actions`), so a step that was retried leaves an ordered account
+ * of every failure — not just the one that ran out of budget. Reporting only
+ * the last is how a push rejected by a pre-receive hook was reported as
+ * "nothing staged inside the declared scope": the retry failed for a different
+ * reason than the original attempt, and the original reason was the diagnosis.
+ *
+ * Excerpts here are bounded harder than the terminal attempt's (256 bytes
+ * rather than 1,024): this is history beside the primary account, not a
+ * replacement for it.
+ */
+export interface StepAttemptFailure {
+  /**
+   * The journal entry envelope's attempt number. Absent when the journal did
+   * not carry one; the position in the list is not a substitute, because a
+   * crashed attempt that consumed no iteration is still its own record.
+   */
+  attempt?: number;
+  /** The kernel's label for THIS attempt, e.g. `verification_failed`. */
+  completionReason?: string;
+  /** `retry`, `step_done` or `park`: what the kernel did next, not why it failed. */
+  disposition?: string;
+  exitCode?: number;
+  /** Redacted, terminal-safe UTF-8 excerpt, at most 256 bytes. */
+  stdoutTail?: string;
+  /** Redacted, terminal-safe UTF-8 excerpt, at most 256 bytes. */
+  stderrTail?: string;
+  /** This attempt's own account, from the same fields the terminal one reads. */
+  detail?: string;
+  /** Set when an excerpt above was cut to fit the per-attempt bound. */
+  truncated?: boolean;
+}
+
+/**
+ * What comparing the attempts' recorded evidence established — and no more.
+ *
+ * `differs` means the journal's own failure evidence is not the same across
+ * attempts, which usually means an earlier attempt had a side effect the retry
+ * then tripped over. `unchanged` is a statement about the RECORD, not a proof
+ * that the underlying causes were identical. `unknown` is the honest answer
+ * when an attempt journaled no account of itself, or when its account was
+ * already truncated by its producer: equal evidence that was never complete is
+ * not evidence of equality.
+ */
+export type AttemptEvidenceComparison = 'differs' | 'unchanged' | 'unknown';
+
+/**
+ * Why a run parked, for the reporting side that has to name a remedy.
+ *
+ * `worker_unavailable` is a step nothing is attached to run — the one case
+ * `--local-agent` fixes. `needs_human` is the kernel's manual-recovery wait
+ * after a worker attempt already failed, and attaching a worker does not clear
+ * it. Both arrive as exit 3 under `run_parked`, so the distinction has to
+ * travel as a value: it lives here, beside the run vocabulary, because the
+ * classifier (cli/run.ts), the authored error boundary (authored-flow-error.ts)
+ * and the remedy formatter (cli/local-agent-remedy.ts) all need the same one
+ * and none of them may depend on the others.
+ */
+export type ParkCause = 'worker_unavailable' | 'needs_human';
+
 /**
  * Optional evidence on the existing step_failed diagnostic, not a new kind.
  *
@@ -154,6 +244,9 @@ export type RunWarningKind = (typeof RUN_WARNING_KINDS)[number];
  * agent or llm step leaves `completionReason` and whatever the daemon captured
  * into `detail` (see cli/step-failure.ts). Absent means "not journaled", never
  * "zero" — an exit code is only ever reported when one was actually recorded.
+ *
+ * The scalar evidence fields always describe the TERMINAL attempt. `attempts`
+ * is additive history and is present only when the step failed more than once.
  */
 export interface StepFailedDetails {
   stepId?: string;
@@ -197,6 +290,15 @@ export interface StepFailedDetails {
   detail?: string;
   /** The attempt's redacted `stream-json` transcript on disk, when the worker wrote one. */
   transcriptPath?: string;
+  /**
+   * Every failed attempt of the step this failure names, oldest first, present
+   * only when there was more than one. The last element is the same attempt the
+   * scalar fields above describe; the first is the one `retries_exhausted`
+   * alone used to hide.
+   */
+  attempts?: StepAttemptFailure[];
+  /** What comparing those attempts' recorded evidence established. */
+  attemptEvidence?: AttemptEvidenceComparison;
   /** A runnable `flows replay` invocation for this run. */
   hint?: string;
   /** The on-disk journal for this run, when the data dir is known. */

package/src/flow-requirements.ts

@@ -4,6 +4,7 @@ import type { TriggerSource } from '@relayflows/surface';
 import { providerDeclaration } from './provider-trigger-contract.js';
 import type { FlowSpec } from './spec.js';
 import { helperCall } from './yaml-helpers.js';
+import { helperNamespacesUsed } from './helper-reference.js';
 
 /**
  * What a flow needs from the workspace it deploys into, read from inert
@@ -155,10 +156,14 @@ export function flowRequirements(
     // payload as input, and handler bodies are not dispatched yet (flows #301).
     // A handler's *trigger* is still a requirement — it is what wakes the flow.
     const text = typeof flow.body === 'function' ? Function.prototype.toString.call(flow.body) : '';
-    const root = contextParameter(text);
-    if (root !== undefined) {
+    const rootName = contextParameter(text);
+    const root = rootName === undefined ? undefined : escapeRegExp(rootName);
+    if (root !== undefined && rootName !== undefined) {
+      // The AST walk compares against an Identifier name, so it needs the raw
+      // parameter; the regex scanners below need the escaped one.
+      const referenced = helperNamespacesUsed(text, rootName);
       for (const { provider, namespace } of helperProviders) {
-        if (helperReference(root, namespace).test(text)) declare({ provider, from: 'helper', detail: `f.${namespace}` });
+        if (referenced.has(namespace)) declare({ provider, from: 'helper', detail: `f.${namespace}` });
       }
       for (const use of workerCalls(root, text)) need(use.cli === undefined ? fallback : harnessFromCli(use.cli), use.detail);
       // `f.human(q, { to: "slack:#eng" })` is delivered by Cloud through that
@@ -219,15 +224,25 @@ function stringList(value: unknown): string[] {
   return Array.isArray(value) ? value.filter((entry): entry is string => typeof entry === 'string') : [];
 }
 
-/** The body's first parameter (`f` in `async (f, input) => …`), escaped for a pattern. */
+/**
+ * The body's first parameter (`f` in `async (f, input) => …`), RAW.
+ *
+ * Returned unescaped because the AST walk compares it to an `Identifier`
+ * name: escaping turned a legal parameter like `f$` into `f\$`, which matches
+ * no identifier and hid every helper call in that flow. Callers that build a
+ * pattern escape it themselves with `escapeRegExp`.
+ */
 function contextParameter(body: string): string | undefined {
-  const parameter = body.match(/^(?:async\s+)?(?:function(?:\s+[\w$]+)?\s*)?(?:\(\s*([\w$]+)|([\w$]+)\s*=>)/u);
-  return (parameter?.[1] ?? parameter?.[2])?.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
+  // The third alternative is an object-literal method (`async post(f) { … }`),
+  // a shape `Function.prototype.toString()` can return and which the first two
+  // do not match — leaving `root` undefined and the body unscanned entirely.
+  const parameter = body.match(/^(?:async\s+)?(?:function\s*\*?\s*(?:[\w$]+)?\s*)?(?:\(\s*([\w$]+)|([\w$]+)\s*=>|\*?\s*[\w$]+\s*\(\s*([\w$]+))/u);
+  return parameter?.[1] ?? parameter?.[2] ?? parameter?.[3];
 }
 
-/** Same recognition as `preflightHelpers`: `f.slack`, `f .slack`, `f["slack"]`. */
-function helperReference(root: string, namespace: string): RegExp {
-  return new RegExp(`(?:^|[^\\w$.])${root}\\s*(?:\\.\\s*${namespace}\\b|\\[\\s*['"]${namespace}['"]\\s*\\])`, 'u');
+/** Escape a literal for embedding in a RegExp source. */
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
 }
 
 /**

package/src/gate-contract.ts

@@ -24,6 +24,13 @@ export interface StepGateInspection extends DataGateClassification {
    * identically to a gate that judges something.
    */
   acceptsAnyOutput?: true;
+  /**
+   * Present when the step declares `onNonZero: 'record'`. The `exit_code`
+   * check is still applied and still journaled, but a positive code satisfies
+   * it instead of failing the step. Without this a recording step reads
+   * exactly like a gated one — the `|| true` ambiguity, moved into the report.
+   */
+  recordsNonZeroExit?: true;
 }
 
 /** Annotation-only keywords: present, they still constrain no instance. */
@@ -55,11 +62,15 @@ export function acceptsAnyOutput(schema: unknown): boolean {
 /** Describe the exact named checks the existing kernel applies to a step. */
 export function inspectStepGate(step: StepSpec): StepGateInspection {
   const checks: JournalGateCheck[] = [];
+  // A policy for the step's own exit code, not a gate of its own: it never
+  // adds or removes a check, it changes what a positive code means to one.
+  const recording = step.type === 'deterministic' && step.onNonZero === 'record'
+    ? { recordsNonZeroExit: true as const } : {};
   if (isNamedGate(step.verification)) {
     checks.push('exit_code');
     if (step.verification.type === 'references_input') checks.push('output_contains');
     if (step.verification.type === 'word_count_bounds') checks.push('json_schema');
-    return { stepId: step.id, kind: 'data', checks, evaluator: 'kernel', preflightable: true, replayable: true };
+    return { stepId: step.id, kind: 'data', checks, evaluator: 'kernel', preflightable: true, replayable: true, ...recording };
   }
   if (step.type === 'deterministic') checks.push('exit_code');
   if (step.verification?.type === 'output_contains') checks.push('output_contains');
@@ -75,5 +86,6 @@ export function inspectStepGate(step: StepSpec): StepGateInspection {
     preflightable: true,
     replayable: true,
     ...(vacuous ? { acceptsAnyOutput: true as const } : {}),
+    ...recording,
   };
 }

package/src/helper-preflight.ts

@@ -1,5 +1,6 @@
 import { helperProviders } from '@relayflows/surface/runtime';
 import type { PreflightResult, PreflightDiagnostic } from './preflight.js';
+import { helperNamespacesUsed } from './helper-reference.js';
 
 /** Static discovery never executes the body; dynamic aliases are checked at call time. */
 export function preflightHelpers(
@@ -8,12 +9,18 @@ export function preflightHelpers(
     providers?: Readonly<Record<string, { mount: boolean; mock: boolean; token?: string }>> },
 ): PreflightResult {
   const body = typeof definition.body === 'function' ? Function.prototype.toString.call(definition.body) : '';
-  const parameter = body.match(/^(?:async\s+)?(?:function(?:\s+[\w$]+)?\s*)?(?:\(\s*([\w$]+)|([\w$]+)\s*=>)/);
-  const root = (parameter?.[1] ?? parameter?.[2])?.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const parameter = body.match(/^(?:async\s+)?(?:function\s*\*?\s*(?:[\w$]+)?\s*)?(?:\(\s*([\w$]+)|([\w$]+)\s*=>|\*?\s*[\w$]+\s*\(\s*([\w$]+))/u);
+  // NOT regex-escaped: this is compared to an AST Identifier name, so a legal
+  // parameter like `f$` must stay `f$`. Escaping it hid every helper call.
+  const root = parameter?.[1] ?? parameter?.[2] ?? parameter?.[3];
   const diagnostics: PreflightDiagnostic[] = [];
+  // Read from a parse, not from the text: a helper named inside a string,
+  // comment, template quasi or regex is not used, and refusing on one demands
+  // a mount the flow never touches.
+  const referenced = root === undefined ? new Set<string>() : helperNamespacesUsed(body, root);
   for (const { provider, namespace, supported } of helperProviders) {
     const used = definition.header?.tools?.[namespace] === true
-      || (root !== undefined && new RegExp(`(?:^|[^\\w$.])${root}\\s*(?:\\.\\s*${namespace}\\b|\\[\\s*['"]${namespace}['"]\\s*\\])`).test(body));
+      || referenced.has(namespace);
     if (!used) continue;
     const fact = facts.providers?.[provider] ?? (provider === 'slack'
       ? { mount: facts.slackMount, mock: facts.slackMock, token: facts.slackToken }

package/src/helper-reference.ts

@@ -0,0 +1,130 @@
+import { parse, parseExpressionAt } from 'acorn';
+
+/**
+ * Which `f.<namespace>` helpers a flow body actually USES.
+ *
+ * Read from a parse, not from the text. A helper merely NAMED in a string, a
+ * comment, a template quasi or a regex is not used, and declaring a
+ * requirement from one refuses a flow for a mount it never touches:
+ * `f.run("echo f.gitlab")`, an agent prompt naming `f.slack`, or a PR title in
+ * a commit message were each enough to demand a GitLab mount.
+ *
+ * This was first written as a lexer that blanked comments, strings and
+ * regexes. That is the wrong tool: `/` is a regex or a division depending on
+ * whether the preceding token ends an expression, which is not decidable
+ * without parse context, and the two shapes that ambiguity broke —
+ * interpolations (`${await f.gitlab…}`) and a quote inside a regex (`/'/`) —
+ * both HID real helper use, deploying a flow without its mount to fail at
+ * runtime. A parser settles every one of those by construction.
+ *
+ * What a parser still cannot see is indirection: `const p = 'gitlab';
+ * f[p].issues…` is invisible to any static reading, because it needs value
+ * tracking. This scan is therefore a convenience for the literal case, never
+ * the authority — `header.tools[namespace] === true` is the declaration that
+ * is, and it short-circuits this entirely.
+ */
+export function helperNamespacesUsed(body: string, root: string): ReadonlySet<string> {
+  const program = parseFlowBody(body);
+  if (program === null) return textFallback(body, root);
+  const used = new Set<string>();
+  walk(program, (node) => {
+    if (node.type !== 'MemberExpression') return;
+    const object = node.object as AstNode | undefined;
+    if (object?.type !== 'Identifier' || object.name !== root) return;
+    const namespace = memberName(node);
+    if (namespace !== undefined) used.add(namespace);
+  });
+  return used;
+}
+
+/** `f.slack`, `f["slack"]`, `f?.slack` — but not `f[variable]`, which is unknowable. */
+function memberName(node: AstNode): string | undefined {
+  const property = node.property as AstNode | undefined;
+  if (property === undefined) return undefined;
+  if (node.computed !== true) return property.type === 'Identifier' ? property.name : undefined;
+  return property.type === 'Literal' && typeof property.value === 'string' ? property.value : undefined;
+}
+
+/**
+ * Parse whatever `Function.prototype.toString()` produced.
+ *
+ * It can be an arrow, a function expression, an async method shorthand from an
+ * object literal, or a declaration — only some of which are expressions, so
+ * each shape gets a try. Types are already stripped by the time a body reaches
+ * here (Node strips before evaluating, and bundlers transpile), so this is
+ * plain JavaScript.
+ */
+function parseFlowBody(body: string): AstNode | null {
+  const options = { ecmaVersion: 'latest' as const, allowAwaitOutsideFunction: true, allowReturnOutsideFunction: true };
+  // `parseExpressionAt` stops at the end of the first expression and does not
+  // object to what follows, so `async post(f) { … }` parses as the identifier
+  // `async` and reports success having read three characters. Every attempt
+  // must therefore consume the whole source, or a method body would be walked
+  // as its own name and declare no helpers at all.
+  const whole = (source: string, node: AstNode): AstNode => {
+    const end = typeof node.end === 'number' ? node.end : -1;
+    if (end < 0 || source.slice(end).trim() !== '') throw new SyntaxError('unconsumed input');
+    return node;
+  };
+  for (const attempt of [
+    () => whole(body, parseExpressionAt(body, 0, options) as unknown as AstNode),
+    () => whole(`(${body})`, parseExpressionAt(`(${body})`, 0, options) as unknown as AstNode),
+    () => parse(body, options) as unknown as AstNode,
+    // An object-literal method (`async post(f) { … }`) is neither expression
+    // nor statement on its own; it only parses inside an object.
+    () => whole(`({${body}})`, parseExpressionAt(`({${body}})`, 0, options) as unknown as AstNode),
+  ]) {
+    try {
+      return attempt();
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+
+/**
+ * Last resort when nothing parses: match the text.
+ *
+ * Deliberately the permissive direction. An unparseable body is a shape this
+ * code does not understand, and under-reporting would deploy a flow without a
+ * mount it needs and fail at the call; over-reporting only asks for a mount
+ * that may go unused. Reaching here at all is a bug worth hearing about.
+ */
+function textFallback(body: string, root: string): ReadonlySet<string> {
+  const used = new Set<string>();
+  const escaped = root.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
+  const pattern = new RegExp(`(?:^|[^\\w$.])${escaped}\\s*(?:\\.\\s*([\\w$]+)|\\[\\s*['"]([^'"]+)['"]\\s*\\])`, 'gu');
+  for (const match of body.matchAll(pattern)) {
+    const namespace = match[1] ?? match[2];
+    if (namespace !== undefined) used.add(namespace);
+  }
+  return used;
+}
+
+type AstNode = {
+  type: string;
+  end?: number;
+  name?: string;
+  value?: unknown;
+  computed?: boolean;
+  [key: string]: unknown;
+};
+
+/** Depth-first over every child node, without pulling in a second package. */
+function walk(node: AstNode, visit: (node: AstNode) => void): void {
+  visit(node);
+  for (const key of Object.keys(node)) {
+    if (key === 'type' || key === 'start' || key === 'end' || key === 'loc') continue;
+    const child = node[key];
+    if (Array.isArray(child)) {
+      for (const entry of child) if (isNode(entry)) walk(entry, visit);
+    } else if (isNode(child)) {
+      walk(child, visit);
+    }
+  }
+}
+
+function isNode(value: unknown): value is AstNode {
+  return typeof value === 'object' && value !== null && typeof (value as { type?: unknown }).type === 'string';
+}

package/src/index.ts

@@ -34,6 +34,8 @@ export type {
   LlmStepSpec,
   NamedAgentSpec,
   NamedDataGate,
+  OnNonZero,
+  StepsGreenGate,
   ReferencesInputGate,
   SubprocessGate,
   WordCountBoundsGate,

package/src/journal-client.ts

@@ -51,6 +51,7 @@ interface Pending {
 /** A structured rejection returned by relayflowd over the journal protocol. */
 export class JournalProtocolError extends Error {
   readonly code: string;
+  verb?: string;
 
   constructor(code: string, message: string) {
     super(`${code}: ${message}`);
@@ -223,12 +224,19 @@ export class JournalClient extends EventEmitter {
    * Validate a compiled kernel-dialect spec (zero-agent flows legal), create
    * the run file, and append `run.spawned`. Authoring specs must be compiled
    * with `toKernelSpec` before crossing this journal-protocol boundary.
+   * `watch` streams the run's entries as `'entry'` events while it runs.
    */
-  runStart(spec: KernelRunSpec, reuseFromRunId?: string, admissionKey?: string): Promise<VerbContract['run.start']['result']> {
+  runStart(
+    spec: KernelRunSpec,
+    reuseFromRunId?: string,
+    admissionKey?: string,
+    watch = false,
+  ): Promise<VerbContract['run.start']['result']> {
     return this.request('run.start', {
       spec,
       ...(reuseFromRunId === undefined ? {} : { reuse_from_run_id: reuseFromRunId }),
       ...(admissionKey === undefined ? {} : { admission_key: admissionKey }),
+      ...(watch ? { watch: true } : {}),
     }, null);
   }
 
@@ -370,6 +378,9 @@ export class JournalClient extends EventEmitter {
       step_id: stepId,
       attempt,
       lease_id: leaseId,
+    }).catch(error => {
+      if (error instanceof JournalProtocolError) error.verb = 'step.heartbeat';
+      throw error;
     });
   }
 
@@ -401,7 +412,10 @@ export class JournalClient extends EventEmitter {
       idempotency_key: idempotencyKey,
       completionReason,
       ...extra,
-    }, null);
+    }, null).catch(error => {
+      if (error instanceof JournalProtocolError) error.verb = 'step.complete';
+      throw error;
+    });
   }
 
   /** Satisfy `wait.event`; a human response arrives here too. */
@@ -422,6 +436,9 @@ export class JournalClient extends EventEmitter {
       attempt,
       idempotency_key: idempotencyKey,
       ...wait,
+    }).catch(error => {
+      if (error instanceof JournalProtocolError) error.verb = 'step.wait';
+      throw error;
     });
   }
 

package/src/journal-projection.ts

@@ -0,0 +1,106 @@
+/**
+ * Fold a run's journal entries, as `run.start {watch}` or `run.watch` pushes
+ * them, into a `RunProjection`: `run.spawned` opens it with the declared step
+ * graph, attempt starts and completions become step transitions, and
+ * `run.completed` closes it. Entries journaled before `liveSinceMs` (a resume
+ * replaying history) update the snapshot without publishing a message each.
+ */
+
+import type { JournalEvent } from './journal-reader.js';
+import type { ProgressEvent } from './progress.js';
+import type { DeclaredStep, RunProjection, RunSnapshot } from './run-projection.js';
+import type { StepType } from './spec.js';
+
+export type OpenProjection = (run: { runId: string; flow: string; steps: DeclaredStep[] }) => RunProjection;
+
+export function createJournalProjector(open: OpenProjection, liveSinceMs = 0): (entry: JournalEvent) => void {
+  let projection: RunProjection | undefined;
+  const types = new Map<string, StepType>();
+  const started = new Map<string, number>();
+  const parked = new Set<string>();
+
+  return entry => {
+    const payload = (entry.payload ?? {}) as Record<string, unknown>;
+    const live = entry.at_ms >= liveSinceMs;
+    if (entry.entry_type === 'run.spawned') {
+      if (projection !== undefined) return;
+      const spec = (payload['spec'] ?? {}) as { name?: unknown; steps?: unknown };
+      const steps = (Array.isArray(spec.steps) ? spec.steps : []).flatMap(declaredStep);
+      for (const step of steps) types.set(step.id, step.type);
+      projection = open({ runId: entry.run_id, flow: typeof spec.name === 'string' ? spec.name : 'flow', steps });
+      return;
+    }
+    if (projection === undefined) return;
+    if (entry.entry_type === 'epoch.summary') {
+      started.clear();
+      parked.clear();
+      const done = (payload['steps_done'] ?? {}) as Record<string, { completionReason?: string }>;
+      const pending = (payload['steps_open'] ?? {}) as Record<string, { state?: string; attempt?: number }>;
+      projection.epoch([
+        ...Object.entries(done).map(([id, value]) => ({ id,
+          state: value.completionReason === 'success' ? 'completed' as const : 'failed' as const,
+          completionReason: value.completionReason })),
+        ...Object.entries(pending).map(([id, value]) => ({ id, attempt: value.attempt,
+          state: value.state === 'running' ? 'running' as const : value.state === 'needs_human' ? 'parked' as const : 'pending' as const })),
+      ], live);
+      return;
+    }
+    if (entry.step_id === null && entry.entry_type !== 'run.completed') return;
+    const stepId = entry.step_id ?? '';
+    const stepType = types.get(stepId) ?? 'deterministic';
+    const attempt = entry.attempt ?? undefined;
+    const key = `${stepId}#${attempt ?? 0}`;
+    const event = (type: ProgressEvent['type'], completionReason?: string): void => {
+      const elapsedMs = type === 'step.started' ? 0 : entry.at_ms - (started.get(key) ?? entry.at_ms);
+      projection!.step({
+        type, stepId, stepType, elapsedMs,
+        ...(attempt === undefined ? {} : { attempt }),
+        ...(completionReason === undefined ? {} : { completionReason: completionReason as never }),
+      }, live);
+    };
+    switch (entry.entry_type) {
+      case 'step.attempt.started':
+        parked.delete(key);
+        started.set(key, entry.at_ms);
+        event('step.started');
+        return;
+      case 'wait.human':
+        if (parked.has(key)) return;
+        parked.add(key);
+        event('step.parked');
+        return;
+      case 'step.completed': {
+        const reason = typeof payload['completionReason'] === 'string' ? payload['completionReason'] : undefined;
+        const isParked = payload['disposition'] === 'park';
+        if (isParked && parked.has(key)) return;
+        if (isParked) parked.add(key);
+        event(isParked ? 'step.parked' : reason === 'success' ? 'step.completed' : 'step.failed', reason);
+        return;
+      }
+      case 'run.completed': {
+        // Historical outcomes belong to earlier epochs. The current resume's
+        // report closes the projection if no new terminal entry is appended.
+        if (!live) return;
+        const reason = typeof payload['completionReason'] === 'string' ? payload['completionReason'] : undefined;
+        projection.finish({ status: runStatus(reason), ...(reason === undefined ? {} : { completionReason: reason }) });
+        return;
+      }
+    }
+  };
+}
+
+function declaredStep(value: unknown): DeclaredStep[] {
+  if (typeof value !== 'object' || value === null) return [];
+  const step = value as { id?: unknown; type?: unknown; depends_on?: unknown };
+  if (typeof step.id !== 'string') return [];
+  const type = step.type === 'llm' || step.type === 'agent' ? step.type : 'deterministic';
+  const dependsOn = Array.isArray(step.depends_on)
+    ? step.depends_on.filter((id): id is string => typeof id === 'string') : [];
+  return [{ id: step.id, type, dependsOn }];
+}
+
+function runStatus(reason: string | undefined): RunSnapshot['status'] {
+  if (reason === 'success') return 'completed';
+  if (reason === 'canceled') return 'canceled';
+  return 'failed';
+}

package/src/llm-worker.ts

@@ -46,7 +46,7 @@ export class LlmWorker extends EventEmitter {
 
   private readonly onDispatch = (dispatch: StepDispatchEvent): void => {
     if (this.closing || dispatch.step_type !== 'llm') return;
-    const running = this.execute(dispatch).catch(error => { this.emit('error', error); });
+    const running = this.execute(dispatch).catch(error => { this.emit('error', error, dispatch); });
     this.inFlight.add(running);
     void running.finally(() => { this.inFlight.delete(running); });
   };

package/src/local-agent.ts

@@ -1,3 +1,4 @@
+import { onWorkerFailure } from './worker-lease.js';
 import { randomUUID } from 'node:crypto';
 import type { JournalClient } from './journal-client.js';
 import { AgentWorker } from './worker.js';
@@ -10,6 +11,7 @@ export async function attachLocalAgent(
   onPtyReady?: (path: string) => void,
   requestedStream?: string,
   capacity: number = DEFAULT_LOCAL_AGENT_CAPACITY,
+  runRoot?: string,
 ): Promise<{
   stream: string;
   readonly failure: unknown;
@@ -24,12 +26,12 @@ export async function attachLocalAgent(
     // 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,
+    dataDir, onPtyReady, runRoot,
     pins: { workspace: [], streams: [{ stream, read_offset: 0 }] },
   });
   let failure: unknown;
   // The cause travels with the close, so the flow's next request names it.
-  worker.on('error', error => { failure = error; client.close(error); });
+  worker.on('error', onWorkerFailure('local-agent', error => { failure = error; client.close(error); }));
   await worker.attach();
   return {
     stream,