@relayflows/sdk 2.0.30 → 2.0.32

package/src/cloud-run-record.ts

@@ -0,0 +1,64 @@
+// What a Cloud run record has to say before this client will act on it.
+//
+// One validator, two callers. `waitForCloudFlowRun` (cloud-run.ts) blocks on
+// it to decide when a hosted `flows run --wait` is over, and the live read
+// verbs (cli/cloud-live.ts, through `getCloudRunDetailLive`) block on it to
+// decide when `--watch` and `--follow` stop and with which exit code. Both
+// have to mean the same thing by "this run is over, and it ended well", or a
+// watch would exit 0 on a record the waiter refuses.
+//
+// Deliberately strict and deliberately separate from the *permissive*
+// `getCloudRunDetail` mapping, which exists to show a reader whatever Cloud
+// said. Attesting an outcome is a different job to rendering one: a
+// `completed` header with no valid `completionReason` attests nothing, and
+// must not become exit 0.
+
+import { RUN_COMPLETION_REASONS } from '@relayflows/surface';
+import { CloudFlowError, isCloudRecord } from './cloud-http.js';
+import type { RunCompletionReason } from './protocol.js';
+
+export type CloudRunState =
+  | { runId: string; status: 'pending' | 'launching' | 'running' }
+  | { runId: string; status: 'completed' | 'failed' | 'cancelled'; completionReason: RunCompletionReason };
+
+/** The statuses that mean the hosted run has not finished. */
+const ACTIVE_RUN_STATUSES: readonly string[] = ['pending', 'launching', 'running'];
+
+/**
+ * Is this run still going?
+ *
+ * The one vocabulary for the question, so `run --cloud --wait`,
+ * `status --cloud --watch` and `logs --follow` cannot disagree about what
+ * `launching` means. Note this is about the *run*: a `needs_human` step is
+ * not a run status and never reaches here.
+ */
+export function isCloudRunActive(status: string): boolean {
+  return ACTIVE_RUN_STATUSES.includes(status);
+}
+
+/**
+ * Validate a raw run record into an execution outcome, or refuse.
+ *
+ * Takes the body as Cloud answered it so a caller that also wants the
+ * renderable projection can make one request and validate the same bytes it
+ * rendered, rather than issuing a second GET per poll.
+ */
+export function cloudRunState(body: unknown, runId: string): CloudRunState {
+  if (!isCloudRecord(body) || body.runId !== runId || body.relayflowVersion !== 'v2'
+    || typeof body.status !== 'string'
+    || !['pending', 'launching', 'running', 'completed', 'failed', 'cancelled'].includes(body.status)) {
+    throw new CloudFlowError('invalid_response', 'Cloud returned an invalid v2 run record.');
+  }
+  if (isCloudRunActive(body.status)) {
+    return { runId, status: body.status as 'pending' | 'launching' | 'running' };
+  }
+  const report = body.result;
+  const reason = isCloudRecord(report) ? report.completionReason : undefined;
+  if (typeof reason !== 'string' || !(RUN_COMPLETION_REASONS as readonly string[]).includes(reason)
+    || (body.status === 'completed' && (reason !== 'success' || !isCloudRecord(report) || report.ok !== true || report.status !== 'completed'))
+    || (body.status === 'failed' && !['step_failed', 'budget_exceeded'].includes(reason))
+    || (body.status === 'cancelled' && reason !== 'canceled')) {
+    throw new CloudFlowError('invalid_response', 'Cloud terminal record lacks a valid, consistent run completionReason; no execution outcome is attested.');
+  }
+  return { runId, status: body.status as 'completed' | 'failed' | 'cancelled', completionReason: reason as RunCompletionReason };
+}

package/src/cloud-run.ts

@@ -1,5 +1,4 @@
-import { RUN_COMPLETION_REASONS, type ScheduleTriggerSource } from '@relayflows/surface';
-import type { RunCompletionReason } from './protocol.js';
+import { type ScheduleTriggerSource } from '@relayflows/surface';
 import { readFile } from 'node:fs/promises';
 import { createHash } from 'node:crypto';
 import { setTimeout } from 'node:timers/promises';
@@ -14,6 +13,7 @@ import {
   CloudFlowError, cloudConnection, cloudFetch, cloudRequest, cloudRunId, isCloudRecord,
   type CloudConnectionOptions,
 } from './cloud-http.js';
+import { cloudRunState, isCloudRunActive, type CloudRunState } from './cloud-run-record.js';
 import { packWorkingTree, prepareCloudSync, uploadCloudCode } from './cloud-sync.js';
 
 export type CloudFlowSource = FlowSpec | { path: string };
@@ -66,9 +66,7 @@ export function cloudSubmissionBody(submission: CloudSubmission): Record<string,
   };
 }
 
-export type CloudRunState =
-  | { runId: string; status: 'pending' | 'launching' | 'running' }
-  | { runId: string; status: 'completed' | 'failed' | 'cancelled'; completionReason: RunCompletionReason };
+export type { CloudRunState };
 
 /**
  * Submit a declarative flow to Cloud's pinned v2 runtime. Compilation only
@@ -269,24 +267,7 @@ export async function getCloudFlowRun(
   options: CloudConnectionOptions = {},
 ): Promise<CloudRunState> {
   cloudRunId(runId);
-  const result = await cloudRequest(`/api/v1/workflows/runs/${runId}`, options);
-  if (!isCloudRecord(result) || result.runId !== runId || result.relayflowVersion !== 'v2'
-    || typeof result.status !== 'string'
-    || !['pending', 'launching', 'running', 'completed', 'failed', 'cancelled'].includes(result.status)) {
-    throw new CloudFlowError('invalid_response', 'Cloud returned an invalid v2 run record.');
-  }
-  if (result.status === 'pending' || result.status === 'launching' || result.status === 'running') {
-    return { runId, status: result.status };
-  }
-  const report = result.result;
-  const reason = isCloudRecord(report) ? report.completionReason : undefined;
-  if (typeof reason !== 'string' || !(RUN_COMPLETION_REASONS as readonly string[]).includes(reason)
-    || (result.status === 'completed' && (reason !== 'success' || !isCloudRecord(report) || report.ok !== true || report.status !== 'completed'))
-    || (result.status === 'failed' && !['step_failed', 'budget_exceeded'].includes(reason))
-    || (result.status === 'cancelled' && reason !== 'canceled')) {
-    throw new CloudFlowError('invalid_response', 'Cloud terminal record lacks a valid, consistent run completionReason; no execution outcome is attested.');
-  }
-  return { runId, status: result.status as 'completed' | 'failed' | 'cancelled', completionReason: reason as RunCompletionReason };
+  return cloudRunState(await cloudRequest(`/api/v1/workflows/runs/${runId}`, options), runId);
 }
 
 /** Wait without a fixed execution deadline. Abort stops observation, not the hosted run. */
@@ -304,7 +285,7 @@ export async function waitForCloudFlowRun(
     try {
       const run = await getCloudFlowRun(runId, options);
       failures = 0;
-      if (run.status !== 'pending' && run.status !== 'launching' && run.status !== 'running') return run;
+      if (!isCloudRunActive(run.status)) return run;
     } catch (error) {
       options.signal?.throwIfAborted();
       const transient = error instanceof CloudFlowError && (error.code === 'transient_error'

package/src/communication/local.ts

@@ -1,3 +1,4 @@
+import { onWorkerFailure } from '../worker-lease.js';
 import { randomUUID } from 'node:crypto';
 import { JournalClient } from '../journal-client.js';
 import { AgentWorker } from '../worker.js';
@@ -31,7 +32,7 @@ export async function attachCommunicationWorkers(spec: KernelRunSpec, socketPath
         requiredStreams: [channelName(step.id, '$receipts')],
         pins: { workspace: [], streams: step.surfaces?.streams?.map(({ stream }) => ({ stream, read_offset: 0 })) ?? [] } });
       workers.push({ client, worker });
-      worker.on('error', error => { failure = error; client.close(); });
+      worker.on('error', onWorkerFailure('communication', error => { failure = error; client.close(); }));
       await client.connect();
       await client.hello('flows-communication');
       await worker.attach();

package/src/communication/worker.ts

@@ -7,6 +7,7 @@ import type { KernelAgentStep } from '../spec.js';
 import { withWorkerLease } from '../worker-lease.js';
 import { workerInstruction } from '../worker-input.js';
 import { resolveCliModel } from '../cli-adapter.js';
+import { resolveAgentCwd } from '../agent-cwd.js';
 import { channelName, type CommunicationInstruction } from './spec.js';
 import { acquireRelayRuntime, type RelayHandle } from './relay.js';
 import { CommunicationSession } from './session.js';
@@ -17,13 +18,13 @@ export function requireCommunicationCli(cli: string | undefined): void {
   if (!cli?.trim()) throw new Error('Agent communication requires a declared CLI executable');
 }
 export async function completeCommunicationDispatch(client: JournalClient, dispatch: StepDispatchEvent,
-  instruction: CommunicationInstruction, dataDir: string): Promise<void> {
+  instruction: CommunicationInstruction, dataDir: string, runRoot?: string): Promise<void> {
   const spec = dispatch.spec as KernelAgentStep;
   requireCommunicationCli(spec.cli);
   let output: unknown;
   let completionReason: 'success' | 'worker_error' = 'success';
   try {
-    output = await withWorkerLease(client, dispatch, signal => run(client, dispatch, instruction, spec, dataDir, signal));
+    output = await withWorkerLease(client, dispatch, signal => run(client, dispatch, instruction, spec, dataDir, signal, runRoot));
   } catch (error) {
     completionReason = 'worker_error';
     output = { error: error instanceof Error ? error.message : String(error) };
@@ -33,7 +34,14 @@ export async function completeCommunicationDispatch(client: JournalClient, dispa
       started_pins: dispatch.pins, end_pins: dispatch.pins });
 }
 async function run(client: JournalClient, dispatch: StepDispatchEvent, instruction: CommunicationInstruction,
-  spec: KernelAgentStep, dataDir: string, lease: AbortSignal): Promise<unknown> {
+  spec: KernelAgentStep, dataDir: string, lease: AbortSignal, runRoot?: string): Promise<unknown> {
+  // Same contract as the CLI worker: a declared directory is resolved and held
+  // inside the same run root the CLI worker measures against, before anything
+  // is spawned. Thrown, not reported, because `completeCommunicationDispatch`
+  // already turns a throw here into a `worker_error` completion carrying the
+  // message.
+  const root = runRoot ?? process.cwd();
+  const directory = resolveAgentCwd(root, spec.cwd) ?? root;
   const controller = new AbortController();
   const signal = AbortSignal.any([lease, controller.signal, AbortSignal.timeout(instruction.timeoutMs)]);
   const relay = await acquireRelayRuntime(dataDir, dispatch.run_id);
@@ -70,9 +78,9 @@ async function run(client: JournalClient, dispatch: StepDispatchEvent, instructi
     });
     // Relay supplies each CLI's launch flags and injection behavior.
     handle = await relay.broker.spawnPty({ name, cli: basename(spec.cli!).replace(/\.exe$/i, ''), task: prompt, channels: [], skipRelayPrompt: true,
-      model: resolveCliModel(spec.cli!, spec.model), cwd: spec.cwd ?? process.cwd(),
+      model: resolveCliModel(spec.cli!, spec.model), cwd: directory,
       harnessConfig: { runtime: 'pty', command: quote(spec.cli!), args: [],
-        cwd: spec.cwd ?? process.cwd(), env: { ...agentEnvironment(spec.cli!),
+        cwd: directory, env: { ...agentEnvironment(spec.cli!),
           RELAYFLOW_COMMUNICATION_SOCKET: tools.path, RELAYFLOW_COMMUNICATION_TOKEN: tools.token },
         delivery: { mode: 'pty-injection', format: 'relay-block' } } });
     const ready = await handle.waitForReady(Math.min(instruction.timeoutMs, 90_000));

package/src/compile.ts

@@ -19,6 +19,7 @@ import { parseBudget, toKernelBudget } from './budget.js';
 import { bindingDependencies } from './input-binding.js';
 import { namedGateFailure } from './named-gates.js';
 import { lowerNamedGates } from './named-gate-lowering.js';
+import { lowerStepsGreenGates } from './steps-green.js';
 import type {
   AgentStepSpec,
   DeterministicStepSpec,
@@ -208,6 +209,10 @@ function compileStep(step: StepSpec): StepSpec {
         // their dispatch timeout. It must be spread HERE and nowhere in `base`.
         ...(s.timeoutMs !== undefined ? { timeoutMs: s.timeoutMs } : {}),
         ...(s.lease_ms !== undefined ? { lease_ms: parseStepTimeout(s.lease_ms) } : {}),
+        // Normalized away when it names the default, so an author who spells
+        // out `fail` gets the same canonical spec — and the same hash — as one
+        // who omits the field entirely.
+        ...(s.onNonZero !== undefined && s.onNonZero !== 'fail' ? { onNonZero: s.onNonZero } : {}),
       };
     }
     case 'llm': {
@@ -259,6 +264,11 @@ function outputGate(gate: VerificationSpec, stepId: string): OutputVerificationS
       `step "${stepId}": exit_code is supported only on deterministic steps`,
     ]);
   }
+  if (gate.type === 'steps_green') {
+    throw new CompileError([
+      `step "${stepId}": gate_host_unsupported: steps_green is supported only on deterministic steps`,
+    ], 'gate_host_unsupported');
+  }
   return gate;
 }
 
@@ -331,7 +341,13 @@ export function toKernelSpec(flow: FlowSpec): KernelRunSpec {
     // reverts the other, and `validateSpec` and `flows check` would both still
     // look correct. See ops/reviews/20260903-pr139-repair-0903.md section 10.
     ...(compiled.triggers?.length ? { triggers: compiled.triggers.map(toKernelTrigger) } : {}),
-    steps: lowerNamedGates(compiled.steps).map((step) => toKernelStep(resolveNamedAgent(step, compiled.agents))),
+    // `steps_green` lowers FIRST: it rewrites the steps it reads to the
+    // permissive envelope schema its bindings need, and the named-gate pass
+    // then adds each source's own gate barrier to the generated step. The
+    // reverse order would hand the green gate a source whose barrier it does
+    // not wait for.
+    steps: lowerNamedGates(lowerStepsGreenGates(compiled.steps))
+      .map((step) => toKernelStep(resolveNamedAgent(step, compiled.agents))),
     ...(compiled.budget !== undefined ? { budget: toKernelBudget(compiled.budget) } : {}),
   };
 }
@@ -426,18 +442,18 @@ function kernelTriggerToAuthoring(value: unknown, at: string): unknown {
 function kernelStepToAuthoring(value: unknown, at: string): unknown {
   const unionKeys = [
     'id', 'type', 'depends_on', 'max_iterations', 'retry', 'verification', 'memory', 'requirements', 'input',
-    'command', 'timeout_ms', 'lease_ms', 'prompt', 'model', 'cli', 'instruction',
-    'recovery_mode', 'surfaces', 'permissions',
+    'command', 'timeout_ms', 'lease_ms', 'on_non_zero', 'prompt', 'model', 'cli', 'instruction',
+    'cwd', 'recovery_mode', 'surfaces', 'permissions',
   ] as const;
   const step = requireKernelObject(value, unionKeys, at);
   const type = step['type'];
   const commonKeys = ['id', 'type', 'depends_on', 'max_iterations', 'retry', 'verification', 'memory', 'requirements', 'input'] as const;
   const typeKeys = type === 'deterministic'
-    ? ['command', 'timeout_ms', 'lease_ms'] as const
+    ? ['command', 'timeout_ms', 'lease_ms', 'on_non_zero'] as const
     : type === 'llm'
       ? ['prompt', 'model', 'cli'] as const
       : type === 'agent'
-        ? ['instruction', 'cli', 'model', 'recovery_mode', 'surfaces', 'permissions'] as const
+        ? ['instruction', 'cli', 'model', 'cwd', 'recovery_mode', 'surfaces', 'permissions'] as const
         : [];
   assertKernelKeys(step, [...commonKeys, ...typeKeys], at);
   if (step['retry'] !== undefined) validateAuthoringRetryDefaults(step['retry'], `${at}.retry`);
@@ -460,6 +476,7 @@ function kernelStepToAuthoring(value: unknown, at: string): unknown {
       command: step['command'],
       ...(step['timeout_ms'] !== undefined ? { timeoutMs: step['timeout_ms'] } : {}),
       ...(step['lease_ms'] !== undefined ? { lease_ms: step['lease_ms'] } : {}),
+      ...(step['on_non_zero'] !== undefined ? { onNonZero: step['on_non_zero'] } : {}),
     };
   }
   if (type === 'llm') {
@@ -470,7 +487,7 @@ function kernelStepToAuthoring(value: unknown, at: string): unknown {
       ...common,
       instruction: step['instruction'],
       ...(step['recovery_mode'] !== undefined ? { recoveryMode: step['recovery_mode'] } : {}),
-      ...copyDefined(step, ['cli', 'model', 'surfaces']),
+      ...copyDefined(step, ['cli', 'model', 'cwd', 'surfaces']),
       ...(step['permissions'] !== undefined
         ? { permissions: kernelPermissionsToAuthoring(step['permissions'], `${at}.permissions`) }
         : {}),
@@ -610,6 +627,11 @@ function toKernelStep(step: StepSpec): KernelStepSpec {
         command: step.command,
         ...(step.timeoutMs !== undefined ? { timeout_ms: step.timeoutMs } : {}),
         ...(step.lease_ms !== undefined ? { lease_ms: parseStepTimeout(step.lease_ms) } : {}),
+        // Omitted for the default, exactly as the kernel skips serializing it:
+        // a spec written before this field existed keeps its canonical bytes
+        // and therefore its spec hash.
+        ...(step.onNonZero !== undefined && step.onNonZero !== 'fail'
+          ? { on_non_zero: step.onNonZero } : {}),
       };
     case 'llm': {
       return {

package/src/direct-input.ts

@@ -39,7 +39,7 @@ export function parseDirectInput(argument: string | undefined): unknown {
     }
   } catch (error) {
     if (error instanceof DirectInputError) throw error;
-    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') {
+    if (!namesNoFile(error)) {
       throw new DirectInputError('input_unreadable', `Input file "${argument}" could not be inspected.`);
     }
   }
@@ -56,6 +56,27 @@ export function parseDirectInput(argument: string | undefined): unknown {
   }
 }
 
+/**
+ * Whether the `stat` failed because the argument names no file at all, rather
+ * than because a file exists and could not be inspected.
+ *
+ * `ENOENT` is the ordinary "nothing there". `ENAMETOOLONG` is the same answer
+ * for a longer argument: no path component may exceed the filesystem's limit
+ * (255 bytes on ext4 and on APFS), so an inline JSON object of a few hundred
+ * bytes cannot be a filename on any filesystem this runs on. Calling that
+ * `input_unreadable` refused every inline input longer than a filename — the
+ * recorded-input recovery commands `cli/local-agent-remedy.ts` prints for a
+ * parked run among them, which is how it was found.
+ *
+ * Anything else — a permission error, an I/O error — still refuses, because it
+ * means a path is there and this process could not look at it. Guessing that
+ * such an argument was inline JSON would parse a filename as a document.
+ */
+function namesNoFile(error: unknown): boolean {
+  const code = (error as NodeJS.ErrnoException).code;
+  return code === 'ENOENT' || code === 'ENAMETOOLONG';
+}
+
 function tooLarge(argument: string, fromFile: boolean): DirectInputError {
   const sourceKind = fromFile ? `Input file "${argument}"` : 'Inline input';
   return new DirectInputError(

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 }