@relayflows/sdk 2.0.29 → 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-extension-compat.ts

@@ -1,20 +1,38 @@
-import { readFileSync } from 'node:fs';
+import packageManifest from '../package.json' with { type: 'json' };
 import type { FlowExtensionManifest } from './flow-extension-manifest.js';
 import { PluginError } from './plugin-manifest.js';
 import { satisfiesRange } from './semver-range.js';
 
+const OBJECT_FREEZE = Object.freeze;
+// This static import is resolved before module evaluation and embedded by the
+// standalone Bun build. It neither consults mutable fs exports after authored
+// code nor depends on import.meta.url naming a real package directory.
+const RUNTIME_VERSIONS = OBJECT_FREEZE({
+  sdk: packageManifest.version,
+  surface: packageManifest.dependencies['@relayflows/surface']!,
+});
+
 export interface RuntimeVersions { readonly sdk: string; readonly surface: string }
 
 /** The versions a plugin's `compat` is checked against: this SDK and the surface it pins. */
 export function runtimeVersions(): RuntimeVersions {
-  const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')) as { version: string; dependencies: Record<string, string> };
-  return { sdk: pkg.version, surface: pkg.dependencies['@relayflows/surface']! };
+  return RUNTIME_VERSIONS;
 }
 
 /** `compat.surface` / `compat.sdk` against the runtime: a miss is a refusal, never a warning. */
 export function assertCompatible(manifest: FlowExtensionManifest, versions: RuntimeVersions): void {
-  for (const [what, range, actual] of [['surface', manifest.compat.surface, versions.surface], ['sdk', manifest.compat.sdk, versions.sdk]] as const) {
-    if (!satisfiesRange(actual, range)) throw new PluginError('plugin_incompatible', `${manifest.name} requires ${what} ${range}; this runtime has ${actual}.`);
+  assertRuntimeRange(manifest, 'surface', manifest.compat.surface, versions.surface);
+  assertRuntimeRange(manifest, 'sdk', manifest.compat.sdk, versions.sdk);
+}
+
+function assertRuntimeRange(
+  manifest: FlowExtensionManifest,
+  what: 'surface' | 'sdk',
+  range: string,
+  actual: string,
+): void {
+  if (!satisfiesRange(actual, range)) {
+    throw new PluginError('plugin_incompatible', `${manifest.name} requires ${what} ${range}; this runtime has ${actual}.`);
   }
 }
 
@@ -23,9 +41,16 @@ export function assertCompatible(manifest: FlowExtensionManifest, versions: Runt
  * optional: a base without it matches only `"*"`.
  */
 export function assertBaseCompatible(manifest: FlowExtensionManifest, base: { readonly name: string; readonly version?: string }): void {
-  const entry = manifest.compat.base.find(b => b.name === base.name);
+  let entry: FlowExtensionManifest['compat']['base'][number] | undefined;
+  for (let index = 0; index < manifest.compat.base.length; index += 1) {
+    if (manifest.compat.base[index]!.name === base.name) entry = manifest.compat.base[index];
+  }
   if (entry === undefined) {
-    throw new PluginError('plugin_incompatible', `${manifest.name} extends ${manifest.compat.base.map(b => b.name).join(', ')}, not "${base.name}".`);
+    let names = '';
+    for (let index = 0; index < manifest.compat.base.length; index += 1) {
+      names += `${index === 0 ? '' : ', '}${manifest.compat.base[index]!.name}`;
+    }
+    throw new PluginError('plugin_incompatible', `${manifest.name} extends ${names}, not "${base.name}".`);
   }
   if (base.version === undefined) {
     if (entry.version !== '*') throw new PluginError('plugin_incompatible', `${manifest.name} requires ${base.name} ${entry.version}, but the base flow declares no version; only "*" can be satisfied.`);

package/src/flow-extension-loader.ts

@@ -1,4 +1,3 @@
-import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import type { Ctx } from '@relayflows/surface';
 import type { AuthoredFlowDefinition, FlowHandle } from './authored-flow.js';
@@ -6,9 +5,22 @@ import { sha256 } from './bundle.js';
 import { assertBaseCompatible, assertCompatible, runtimeVersions, type RuntimeVersions } from './flow-extension-compat.js';
 import { validateFlowExtensionManifest, type FlowExtensionManifest } from './flow-extension-manifest.js';
 import { findPluginProject } from './plugin-loader.js';
+import { appendIntrinsicArray } from './intrinsic-array.js';
 import { reconcileDeclaredExtensions, type PluginLockEntry } from './plugin-lock.js';
 import { PluginError } from './plugin-manifest.js';
-import { pluginStoreDirectory, verifyStoredPlugin } from './plugin-store.js';
+import { pluginStoreDirectory, readStoredPluginFiles } from './plugin-store.js';
+
+const JSON_PARSE = JSON.parse;
+const ARRAY_IS_ARRAY = Array.isArray;
+const JSON_STRINGIFY = JSON.stringify;
+const OBJECT_FREEZE = Object.freeze;
+const REGEXP_TEST = Function.prototype.call.bind(RegExp.prototype.test) as (
+  regexp: RegExp, value: string,
+) => boolean;
+const STRING_SPLIT = Function.prototype.call.bind(String.prototype.split) as (
+  value: string,
+  separator: string | RegExp,
+) => string[];
 
 /**
  * Compose schema-2 flow extensions onto a base authored flow.
@@ -94,7 +106,7 @@ function subscriptionOf(handler: TriggerHandler): { provider: string; event: str
   if (trigger.kind !== 'webhook' || trigger.filter === undefined) return undefined;
   const { provider, type, payload } = trigger.filter as { provider?: unknown; type?: unknown; payload?: unknown };
   if (typeof provider !== 'string' || provider !== trigger.name || typeof type !== 'string') return undefined;
-  const action = typeof payload === 'object' && payload !== null && !Array.isArray(payload) ? (payload as { action?: unknown }).action : undefined;
+  const action = typeof payload === 'object' && payload !== null && !ARRAY_IS_ARRAY(payload) ? (payload as { action?: unknown }).action : undefined;
   if (action !== undefined && typeof action !== 'string') return undefined;
   return action === undefined ? { provider, event: type } : { provider, event: type, action };
 }
@@ -115,32 +127,41 @@ export type HostedExtensionDispatch = {
   readonly deliveryId: string;
 };
 
-type HostedEventIdentity = { readonly provider: string; readonly event: string; readonly action?: string };
+export type HostedEventIdentity = { readonly provider: string; readonly event: string; readonly action?: string };
 const DISPATCH_PROVIDER = /^[a-z0-9][a-z0-9-]{0,63}$/;
 const DISPATCH_EVENT = /^[A-Za-z_][A-Za-z0-9_]*$/;
 const DISPATCH_DELIVERY = /^[A-Za-z0-9_.:-]{1,200}$/;
 
 function hostedEventIdentity(dispatch: unknown): HostedEventIdentity {
-  if (typeof dispatch !== 'object' || dispatch === null || Array.isArray(dispatch)) {
+  if (typeof dispatch !== 'object' || dispatch === null || ARRAY_IS_ARRAY(dispatch)) {
     throw new PluginError('plugin_event_unroutable', 'Hosted extension dispatch authority is malformed.');
   }
   const { provenance, provider, eventType, deliveryId } = dispatch as Partial<HostedExtensionDispatch>;
   if ((dispatch as Partial<HostedExtensionDispatch>)[HOSTED_EXTENSION_DISPATCH_AUTHORITY] !== true
     || provenance !== 'integration-watch'
-    || typeof provider !== 'string' || !DISPATCH_PROVIDER.test(provider)
-    || typeof deliveryId !== 'string' || !DISPATCH_DELIVERY.test(deliveryId)
+    || typeof provider !== 'string' || !REGEXP_TEST(DISPATCH_PROVIDER, provider)
+    || typeof deliveryId !== 'string' || !REGEXP_TEST(DISPATCH_DELIVERY, deliveryId)
     || typeof eventType !== 'string') {
     throw new PluginError('plugin_event_unroutable', 'Hosted extension dispatch authority is malformed.');
   }
-  const parts = eventType.split('.');
-  if ((parts.length !== 1 && parts.length !== 2) || parts.some(part => !DISPATCH_EVENT.test(part))) {
-    throw new PluginError('plugin_event_unroutable', `Hosted extension event ${JSON.stringify(eventType)} is malformed.`);
+  const parts = STRING_SPLIT(eventType, '.');
+  let valid = parts.length === 1 || parts.length === 2;
+  for (let index = 0; valid && index < parts.length; index += 1) {
+    valid = REGEXP_TEST(DISPATCH_EVENT, parts[index]!);
+  }
+  if (!valid) {
+    throw new PluginError('plugin_event_unroutable', `Hosted extension event ${JSON_STRINGIFY(eventType)} is malformed.`);
   }
   return parts.length === 1
     ? { provider, event: parts[0]! }
     : { provider, event: parts[0]!, action: parts[1]! };
 }
 
+/** Validate and project branded host authority without making it serializable. */
+export function hostedExtensionDispatchIdentity(dispatch: unknown): HostedEventIdentity {
+  return OBJECT_FREEZE(hostedEventIdentity(dispatch));
+}
+
 /**
  * Brand metadata only after the host has authenticated the integration
  * delivery. The symbol is deliberately not serializable, so copying a direct
@@ -149,7 +170,7 @@ function hostedEventIdentity(dispatch: unknown): HostedEventIdentity {
 export function hostedExtensionDispatchFromVerifiedDelivery(
   delivery: Omit<HostedExtensionDispatch, typeof HOSTED_EXTENSION_DISPATCH_AUTHORITY | 'provenance'>,
 ): HostedExtensionDispatch {
-  const dispatch = Object.freeze({
+  const dispatch = OBJECT_FREEZE({
     [HOSTED_EXTENSION_DISPATCH_AUTHORITY]: true as const,
     provenance: 'integration-watch' as const,
     ...delivery,
@@ -171,16 +192,29 @@ export function extensionHandlerForHostedDispatch(
 ): { readonly extension: Pick<LoadedFlowExtension, 'name' | 'handlers'>; readonly handler: TriggerHandler } | undefined {
   if (dispatch === undefined) return undefined;
   const identity = hostedEventIdentity(dispatch);
-  const matches = extensions.flatMap(extension => extension.handlers.flatMap(handler => {
-    const subscription = subscriptionOf(handler);
-    if (subscription === undefined || subscription.provider !== identity.provider || subscription.event !== identity.event) return [];
-    if (subscription.action !== undefined && subscription.action !== identity.action) return [];
-    return [{ extension, handler }];
-  }));
+  const matches: Array<{
+    extension: Pick<LoadedFlowExtension, 'name' | 'handlers'>;
+    handler: TriggerHandler;
+  }> = [];
+  for (let extensionIndex = 0; extensionIndex < extensions.length; extensionIndex += 1) {
+    const extension = extensions[extensionIndex]!;
+    for (let handlerIndex = 0; handlerIndex < extension.handlers.length; handlerIndex += 1) {
+      const handler = extension.handlers[handlerIndex]!;
+      const subscription = subscriptionOf(handler);
+      if (subscription === undefined || subscription.provider !== identity.provider
+        || subscription.event !== identity.event) continue;
+      if (subscription.action !== undefined && subscription.action !== identity.action) continue;
+      appendIntrinsicArray(matches, { extension, handler });
+    }
+  }
   if (matches.length > 1) {
+    let matchingNames = '';
+    for (let index = 0; index < matches.length; index += 1) {
+      matchingNames += `${index === 0 ? '' : ', '}${matches[index]!.extension.name}`;
+    }
     throw new PluginError(
       'plugin_event_ambiguous',
-      `Hosted event ${identity.provider}.${identity.event}${identity.action === undefined ? '' : `.${identity.action}`} matches multiple extension handlers (${matches.map(match => match.extension.name).join(', ')}).`,
+      `Hosted event ${identity.provider}.${identity.event}${identity.action === undefined ? '' : `.${identity.action}`} matches multiple extension handlers (${matchingNames}).`,
     );
   }
   return matches[0];
@@ -206,11 +240,12 @@ async function loadOne<Authority>(
   options: LoadFlowExtensionsOptions<Authority>,
 ): Promise<LoadedFlowExtension> {
   const directory = pluginStoreDirectory(root, lock.name, lock.digest);
-  await verifyStoredPlugin(directory, lock.digest);
-  const manifestBytes = readFileSync(join(directory, 'flows-plugin.json'));
+  const stored = await readStoredPluginFiles(directory, lock.digest);
+  const manifestBytes = stored.find(file => file.path === 'flows-plugin.json')?.data;
+  if (manifestBytes === undefined) throw new PluginError('plugin_source_drift', `${ref}: flows-plugin.json is missing.`);
   if (sha256(manifestBytes) !== lock.manifestSha256) throw new PluginError('plugin_source_drift', `${ref}: flows-plugin.json differs from the lockfile's manifest hash.`);
   let input: unknown;
-  try { input = JSON.parse(manifestBytes.toString('utf8')); }
+  try { input = JSON_PARSE(manifestBytes.toString('utf8')); }
   catch { throw new PluginError('plugin_manifest_invalid', `${ref}: flows-plugin.json is not valid JSON.`); }
   const manifest = validateFlowExtensionManifest(input);
   if (manifest.name !== lock.name || manifest.version !== lock.version) throw new PluginError('plugin_source_drift', `${ref}: manifest names ${manifest.name}@${manifest.version}, lockfile has ${lock.name}@${lock.version}.`);

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/fs-descriptor.ts

@@ -0,0 +1,127 @@
+import {
+  Dir,
+  Dirent,
+  Stats,
+  close,
+  fstat,
+  lstat,
+  open,
+  opendir,
+  read,
+  readdir,
+  type BigIntStats,
+  type PathLike,
+} from 'node:fs';
+import { hostedPromiseValue } from './hosted-promise-safety.js';
+
+const CLOSE = close;
+const FSTAT = fstat;
+const LSTAT = lstat;
+const OPEN = open;
+const OPENDIR = opendir;
+const READ = read;
+const READDIR = readdir;
+const PROMISE = Promise;
+const DIRENT_IS_DIRECTORY = Function.prototype.call.bind(Dirent.prototype.isDirectory) as (
+  entry: Dirent,
+) => boolean;
+const DIRENT_IS_FILE = Function.prototype.call.bind(Dirent.prototype.isFile) as (
+  entry: Dirent,
+) => boolean;
+const DIR_CLOSE = Function.prototype.call.bind(Dir.prototype.close) as (
+  directory: Dir,
+  callback: (error?: NodeJS.ErrnoException | null) => void,
+) => void;
+const DIR_READ = Function.prototype.call.bind(Dir.prototype.read) as (
+  directory: Dir,
+  callback: (error: NodeJS.ErrnoException | null, entry: Dirent | null) => void,
+) => void;
+const STATS_IS_DIRECTORY = Function.prototype.call.bind(Stats.prototype.isDirectory) as (
+  stats: Stats | BigIntStats,
+) => boolean;
+const STATS_IS_FILE = Function.prototype.call.bind(Stats.prototype.isFile) as (
+  stats: Stats | BigIntStats,
+) => boolean;
+
+export const descriptorIsDirectory = STATS_IS_DIRECTORY;
+export const descriptorIsFile = STATS_IS_FILE;
+export const directoryEntryIsDirectory = DIRENT_IS_DIRECTORY;
+export const directoryEntryIsFile = DIRENT_IS_FILE;
+
+export function closeDescriptor(descriptor: number): Promise<void> {
+  return new PROMISE<void>((resolvePromise, rejectPromise) => {
+    CLOSE(descriptor, error => error === null ? resolvePromise() : rejectPromise(error));
+  });
+}
+
+export function openDescriptor(path: PathLike, flags: number): Promise<number> {
+  return new PROMISE<number>((resolvePromise, rejectPromise) => {
+    OPEN(path, flags, (error, descriptor) => error === null ? resolvePromise(descriptor) : rejectPromise(error));
+  });
+}
+
+export function statDescriptor(descriptor: number, options: { bigint: true }): Promise<BigIntStats> {
+  return new PROMISE<BigIntStats>((resolvePromise, rejectPromise) => {
+    FSTAT(descriptor, options, (error, stats) => {
+      if (error !== null) rejectPromise(error);
+      else resolvePromise(hostedPromiseValue(stats));
+    });
+  });
+}
+
+export function lstatPath(path: PathLike): Promise<Stats> {
+  return new PROMISE<Stats>((resolvePromise, rejectPromise) => {
+    LSTAT(path, (error, stats) => {
+      if (error !== null) rejectPromise(error);
+      else resolvePromise(hostedPromiseValue(stats));
+    });
+  });
+}
+
+export function openDirectory(path: PathLike): Promise<Dir> {
+  return new PROMISE<Dir>((resolvePromise, rejectPromise) => {
+    OPENDIR(path, (error, directory) => {
+      if (error !== null) rejectPromise(error);
+      else resolvePromise(hostedPromiseValue(directory));
+    });
+  });
+}
+
+export function readDirectory(path: PathLike): Promise<Dirent[]> {
+  return new PROMISE<Dirent[]>((resolvePromise, rejectPromise) => {
+    READDIR(path, { withFileTypes: true }, (error, entries) => {
+      if (error !== null) rejectPromise(error);
+      else resolvePromise(hostedPromiseValue(entries));
+    });
+  });
+}
+
+export function readDirectoryEntry(directory: Dir): Promise<Dirent | null> {
+  return new PROMISE<Dirent | null>((resolvePromise, rejectPromise) => {
+    DIR_READ(directory, (error, entry) => {
+      if (error !== null) rejectPromise(error);
+      else resolvePromise(entry === null ? null : hostedPromiseValue(entry));
+    });
+  });
+}
+
+export function closeDirectory(directory: Dir): Promise<void> {
+  return new PROMISE<void>((resolvePromise, rejectPromise) => {
+    DIR_CLOSE(directory, error => error == null ? resolvePromise() : rejectPromise(error));
+  });
+}
+
+export async function readDescriptor(
+  descriptor: number,
+  buffer: Buffer,
+  offset: number,
+  length: number,
+  position: number,
+): Promise<number> {
+  return await new PROMISE<number>((resolvePromise, rejectPromise) => {
+    READ(descriptor, buffer, offset, length, position, (error, bytesRead) => {
+      if (error !== null) rejectPromise(error);
+      else resolvePromise(bytesRead);
+    });
+  });
+}

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 }