@relayflows/sdk 2.0.29 → 2.0.31

package/src/run-projection.ts

@@ -0,0 +1,247 @@
+/**
+ * Project a run's lifecycle into its Relaycast channel, `wf-<runId>`, so the
+ * observer dashboard shows the flow: one message per step transition, each
+ * carrying the whole run snapshot under `metadata.relayflow` for a renderer
+ * that draws the step graph.
+ *
+ * A projection, never a source of truth (RFC-0001 settled decision 7): the
+ * journal is the record. Publication is serialized and fire-and-forget; a
+ * failure is reported once through `diagnostic` and never reaches the run.
+ */
+
+import { randomUUID } from 'node:crypto';
+import { renderProgress, type ProgressEvent } from './progress.js';
+import type { StepType } from './spec.js';
+
+export const RELAYFLOW_METADATA_VERSION = 1;
+
+export type ProjectedStepState = 'pending' | 'running' | 'completed' | 'failed' | 'parked';
+
+export interface ProjectedStep {
+  id: string;
+  type: StepType;
+  dependsOn: string[];
+  state: ProjectedStepState;
+  attempt?: number;
+  elapsedMs?: number;
+  completionReason?: string;
+}
+
+export interface RunSnapshot {
+  runId: string;
+  flow: string;
+  status: 'running' | 'completed' | 'failed' | 'parked' | 'canceled';
+  completionReason?: string;
+  steps: ProjectedStep[];
+}
+
+export interface DeclaredStep {
+  id: string;
+  type: StepType;
+  dependsOn?: string[];
+}
+
+export interface RunProjection {
+  readonly channel: string;
+  /** Apply a transition; `publish: false` folds replayed history into the snapshot silently. */
+  step(event: ProgressEvent & { attempt?: number }, publish?: boolean): void;
+  /** Rebuild an epoch boundary from journal facts, never from old terminal state. */
+  epoch(states: Array<{ id: string; state: ProjectedStepState; attempt?: number; completionReason?: string }>, publish?: boolean): void;
+  /** Close the run; only the first call publishes. */
+  finish(outcome: { status: RunSnapshot['status']; completionReason?: string }): void;
+  /** Resolves when every queued publication settled, or after `timeoutMs`. */
+  drain(timeoutMs: number): Promise<void>;
+  /** Stop publication and remove this session's publisher after its queue settles. */
+  close(timeoutMs: number): Promise<void>;
+}
+
+export type ProjectionFetch = (url: string, init: {
+  method: string;
+  headers: Record<string, string>;
+  body?: string;
+  signal?: AbortSignal;
+}) => Promise<{ ok: boolean; status: number; json: () => Promise<unknown> }>;
+
+export interface RunProjectionOptions {
+  workspaceKey: string;
+  /** Relaycast API base, default `https://cast.agentrelay.com`. */
+  baseUrl?: string;
+  fetch?: ProjectionFetch;
+  diagnostic: (message: string) => void;
+}
+
+const DEFAULT_BASE_URL = 'https://cast.agentrelay.com';
+const REQUEST_TIMEOUT_MS = 5_000;
+
+export function runChannelName(runId: string): string {
+  return `wf-${runId.toLowerCase()}`;
+}
+
+export function createRunProjection(
+  options: RunProjectionOptions,
+  run: { runId: string; flow: string; steps?: DeclaredStep[]; resumed?: boolean },
+): RunProjection {
+  const doFetch = options.fetch ?? (globalThis.fetch as unknown as ProjectionFetch);
+  const base = options.baseUrl ?? DEFAULT_BASE_URL;
+  const channel = runChannelName(run.runId);
+  const snapshot: RunSnapshot = {
+    runId: run.runId, flow: run.flow, status: 'running',
+    steps: (run.steps ?? []).map(step => ({
+      id: step.id, type: step.type, dependsOn: step.dependsOn ?? [], state: 'pending',
+    })),
+  };
+
+  const call = async (path: string, token: string, body?: unknown, idempotencyKey?: string, method?: string): Promise<unknown> => {
+    const response = await doFetch(new URL(`/v1${path}`, base).toString(), {
+      method: method ?? (body === undefined ? 'GET' : 'POST'),
+      headers: {
+        Authorization: `Bearer ${token}`,
+        'Content-Type': 'application/json',
+        ...(idempotencyKey === undefined ? {} : { 'Idempotency-Key': idempotencyKey }),
+      },
+      ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+    const parsed = await response.json().catch(() => undefined) as
+      { data?: unknown; error?: { code?: string } } | undefined;
+    if (!response.ok) {
+      throw new RelaycastError(response.status, parsed?.error?.code ?? `http_${response.status}`);
+    }
+    return parsed?.data;
+  };
+
+  // A per-session publisher: agent names are unique per workspace, and a
+  // resumed run publishes from a fresh session into the same channel.
+  const publisherName = `flow-${randomUUID()}`;
+  let cleanup: Promise<void> | undefined;
+  const removePublisher = (reportFailure = true): Promise<void> => cleanup ??= (async () => {
+    // The unique name is known before POST. A lost create response is not
+    // proof that creation failed: retire it even after an ambiguous outcome.
+    try {
+      await call(`/agents/${encodeURIComponent(publisherName)}`, options.workspaceKey, undefined, undefined, 'DELETE');
+    } catch (error) {
+      if (error instanceof RelaycastError && error.status === 404) return;
+      if (reportFailure) options.diagnostic(`publisher cleanup for #${channel} failed; the run is unaffected`);
+    }
+  })();
+  const setup = (async (): Promise<string> => {
+    const agent = await call('/agents', options.workspaceKey, {
+      name: publisherName, type: 'agent', auto_join_general: false,
+    }) as { token?: unknown } | undefined;
+    if (typeof agent?.token !== 'string') throw new RelaycastError(0, 'agent_token_missing');
+    const token = agent.token;
+    try {
+      await call('/channels', token, { name: channel, topic: `relayflow ${run.flow} · run ${run.runId}` });
+    } catch (error) {
+      // Agent communication in the same run may have created it first.
+      if (!(error instanceof RelaycastError) || error.code !== 'channel_already_exists') throw error;
+      await call(`/channels/${encodeURIComponent(channel)}/join`, token, {});
+    }
+    return token;
+  })().catch(async (error: unknown) => { await removePublisher(false); throw error; });
+
+  let queue: Promise<unknown> = setup;
+  let failed = false;
+  let sequence = 0;
+  let closed = false;
+  const sessionId = randomUUID().slice(0, 8);
+  const publish = (event: string, text: string): void => {
+    if (closed) return;
+    const data = { relayflow: { version: RELAYFLOW_METADATA_VERSION, event, run: structuredClone(snapshot) } };
+    const key = `${sessionId}-${++sequence}`;
+    queue = queue.then(async () => {
+      if (failed) return;
+      await call(`/channels/${encodeURIComponent(channel)}/messages`, await setup, { text, data }, key);
+    }).catch((error: unknown) => {
+      if (failed) return;
+      failed = true;
+      options.diagnostic(`run projection to #${channel} failed (${errorMessage(error)}); `
+        + 'the observer will not show this run, which is unaffected');
+    });
+  };
+
+  const declared = snapshot.steps.length;
+  publish('run.started', `▶ ${run.flow} ${run.resumed ? 'resumed' : 'started'}`
+    + `${declared > 0 ? ` · ${declared} step${declared === 1 ? '' : 's'}` : ''} · run ${run.runId}`);
+
+  return {
+    channel,
+    epoch(states, shouldPublish = true) {
+      snapshot.status = 'running';
+      delete snapshot.completionReason;
+      for (const step of snapshot.steps) {
+        step.state = 'pending';
+        delete step.attempt;
+        delete step.elapsedMs;
+        delete step.completionReason;
+        const state = states.find(candidate => candidate.id === step.id);
+        if (state !== undefined) Object.assign(step, state);
+      }
+      if (shouldPublish) publish('run.started', `▶ ${run.flow} resumed · run ${run.runId}`);
+    },
+    step(event, shouldPublish = true) {
+      let step = snapshot.steps.find(candidate => candidate.id === event.stepId);
+      if (step === undefined) {
+        step = { id: event.stepId, type: event.stepType, dependsOn: [], state: 'pending' };
+        snapshot.steps.push(step);
+      }
+      step.state = STATE[event.type];
+      if (event.attempt !== undefined) step.attempt = event.attempt;
+      if (event.type === 'step.started') {
+        delete step.elapsedMs;
+        delete step.completionReason;
+      } else {
+        step.elapsedMs = Math.max(0, Math.round(event.elapsedMs));
+      }
+      if (event.completionReason !== undefined) step.completionReason = event.completionReason;
+      if (!shouldPublish || event.type === 'step.running') return;
+      publish(event.type, event.type === 'step.started'
+        ? `○ ${step.id} (${step.type}) started${step.attempt !== undefined && step.attempt > 1 ? ` · attempt ${step.attempt}` : ''}`
+        : renderProgress([event])[0]!);
+    },
+    finish(outcome) {
+      if (snapshot.status !== 'running') return;
+      snapshot.status = outcome.status;
+      if (outcome.completionReason !== undefined) snapshot.completionReason = outcome.completionReason;
+      const icon = outcome.status === 'completed' ? '■' : outcome.status === 'parked' ? '⏸' : '✗';
+      publish('run.completed', `${icon} ${run.flow} ${outcome.status}`
+        + `${outcome.completionReason === undefined ? '' : ` · completionReason: ${outcome.completionReason}`}`);
+    },
+    async drain(timeoutMs) {
+      let timer: NodeJS.Timeout | undefined;
+      await Promise.race([
+        queue,
+        new Promise<void>(resolve => { timer = setTimeout(resolve, timeoutMs); timer.unref?.(); }),
+      ]);
+      clearTimeout(timer);
+    },
+    async close(timeoutMs) {
+      if (!closed) {
+        closed = true;
+        queue = queue.then(() => removePublisher(), () => removePublisher());
+      }
+      let timer: NodeJS.Timeout | undefined;
+      try {
+        await Promise.race([queue, new Promise<void>(resolve => { timer = setTimeout(resolve, timeoutMs); timer.unref?.(); })]);
+      } finally { clearTimeout(timer); }
+    },
+  };
+}
+
+const STATE: Record<ProgressEvent['type'], ProjectedStepState> = {
+  'step.started': 'running',
+  'step.running': 'running',
+  'step.completed': 'completed',
+  'step.failed': 'failed',
+  'step.parked': 'parked',
+};
+
+class RelaycastError extends Error {
+  constructor(readonly status: number, readonly code: string) {
+    super(status === 0 ? code : `HTTP ${status} ${code}`);
+  }
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/semver-range.ts

@@ -9,19 +9,41 @@
  */
 const VERSION = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/;
 const RANGE = /^(\*|(?:[\^~]|>=)?\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?: <\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)?)$/;
+const MATH_MAX = Math.max;
+const NUMBER = Number;
+const NUMBER_IS_SAFE_INTEGER = Number.isSafeInteger;
+const REGEXP_EXEC = Function.prototype.call.bind(RegExp.prototype.exec) as (
+  regexp: RegExp,
+  value: string,
+) => RegExpExecArray | null;
+const REGEXP_TEST = Function.prototype.call.bind(RegExp.prototype.test) as (
+  regexp: RegExp,
+  value: string,
+) => boolean;
+const STRING_SLICE = Function.prototype.call.bind(String.prototype.slice) as (
+  value: string,
+  start: number,
+  end?: number,
+) => string;
+const STRING_SPLIT = Function.prototype.call.bind(String.prototype.split) as (
+  value: string,
+  separator: string,
+) => string[];
 
 interface Parsed { readonly triple: readonly [number, number, number]; readonly pre?: string }
 
 export function parseVersion(value: string): Parsed | undefined {
-  const m = VERSION.exec(value);
+  const m = REGEXP_EXEC(VERSION, value);
   if (!m) return undefined;
-  const triple = [Number(m[1]), Number(m[2]), Number(m[3])] as const;
-  if (triple.some(n => !Number.isSafeInteger(n))) return undefined;
+  const triple = [NUMBER(m[1]), NUMBER(m[2]), NUMBER(m[3])] as const;
+  for (let index = 0; index < triple.length; index += 1) {
+    if (!NUMBER_IS_SAFE_INTEGER(triple[index])) return undefined;
+  }
   return m[4] === undefined ? { triple } : { triple, pre: m[4] };
 }
 
 export function isVersionRange(value: string): boolean {
-  return RANGE.test(value);
+  return REGEXP_TEST(RANGE, value);
 }
 
 function compare(a: Parsed, b: Parsed): number {
@@ -33,16 +55,16 @@ function compare(a: Parsed, b: Parsed): number {
 }
 
 function comparePrerelease(a: string, b: string): number {
-  const as = a.split('.');
-  const bs = b.split('.');
-  const n = Math.max(as.length, bs.length);
+  const as = STRING_SPLIT(a, '.');
+  const bs = STRING_SPLIT(b, '.');
+  const n = MATH_MAX(as.length, bs.length);
   for (let i = 0; i < n; i++) {
     const left = as[i];
     const right = bs[i];
     if (left === undefined) return -1;
     if (right === undefined) return 1;
-    const leftNum = /^\d+$/.test(left) ? Number(left) : undefined;
-    const rightNum = /^\d+$/.test(right) ? Number(right) : undefined;
+    const leftNum = REGEXP_TEST(/^\d+$/, left) ? NUMBER(left) : undefined;
+    const rightNum = REGEXP_TEST(/^\d+$/, right) ? NUMBER(right) : undefined;
     if (leftNum !== undefined && rightNum !== undefined) {
       if (leftNum !== rightNum) return leftNum - rightNum;
       continue;
@@ -59,15 +81,18 @@ export function satisfiesRange(version: string, range: string): boolean {
   const v = parseVersion(version);
   if (v === undefined || !isVersionRange(range)) return false;
   if (range === '*') return true;
-  const [lowerText, upperText] = range.split(' ') as [string, string | undefined];
-  const operator = /^[\^~]|^>=/.exec(lowerText)?.[0] ?? '';
-  const lower = parseVersion(lowerText.slice(operator.length))!;
+  const parts = STRING_SPLIT(range, ' ');
+  const lowerText = parts[0]!;
+  const upperText = parts[1];
+  const operator = REGEXP_EXEC(/^[\^~]|^>=/, lowerText)?.[0] ?? '';
+  const lower = parseVersion(STRING_SLICE(lowerText, operator.length))!;
   if (compare(v, lower) < 0) return false;
   if (operator === '') return compare(v, lower) === 0;
   let upper: Parsed | undefined;
-  if (upperText !== undefined) upper = parseVersion(upperText.slice(1));
+  if (upperText !== undefined) upper = parseVersion(STRING_SLICE(upperText, 1));
   else if (operator === '^') {
-    const [major, minor] = lower.triple;
+    const major = lower.triple[0];
+    const minor = lower.triple[1];
     upper = major > 0 ? { triple: [major + 1, 0, 0] } : minor > 0 ? { triple: [0, minor + 1, 0] } : { triple: [0, 0, lower.triple[2] + 1] };
   } else if (operator === '~') upper = { triple: [lower.triple[0], lower.triple[1] + 1, 0] };
   return upper === undefined || compare(v, upper) < 0;

package/src/shell-word.ts

@@ -0,0 +1,24 @@
+/**
+ * POSIX shell quoting for the invocations diagnostics tell people to run.
+ *
+ * Dependency-free on purpose: every module that renders a command reaches for
+ * this, and two of them (`cli/run.ts` and `authored-human.ts`) already import
+ * each other's neighbours. A copy per call site is how one of them ends up
+ * emitting a path with a space in it unquoted.
+ */
+
+/** `value` as a single word, quoted only when it would not survive a shell. */
+export function shellWord(value: string): string {
+  return /^[A-Za-z0-9_./=:@%+,-]+$/.test(value) ? value : shellQuote(value);
+}
+
+/**
+ * `value` as a single-quoted word, always.
+ *
+ * Used where the rendered argument is arbitrary author data — a flow path or a
+ * JSON `--input` — and the quotes are worth keeping even when unnecessary, so
+ * the command reads the same for `a.flow.ts` and for `my flows/a.flow.ts`.
+ */
+export function shellQuote(value: string): string {
+  return `'${value.replaceAll("'", "'\\''")}'`;
+}

package/src/spec.ts

@@ -15,6 +15,13 @@ export type { JsonOutputSchema } from './output-schema.js';
 /** The three rungs of the ladder (RFC §1; AGENTS.md rule 7). */
 export type StepType = 'deterministic' | 'llm' | 'agent';
 
+/**
+ * A deterministic step's exit-code policy. `'fail'` is the kernel's implicit
+ * gate; `'record'` completes the step with its exit code journaled so a later
+ * step can read the outcome instead of re-running the command.
+ */
+export type OnNonZero = 'fail' | 'record';
+
 /** Project-owned MCP connections. env contains names, never secret values. */
 export type McpServerConfig =
   | { command: string; args?: string[]; env?: string[] }
@@ -93,9 +100,24 @@ export interface ArtifactExistsGate {
   path: string;
 }
 
+/**
+ * Asserts that every named step recorded a zero exit code, reading the
+ * journaled outcome instead of re-running the command. This is the read side
+ * of `onNonZero: 'record'`: red work is allowed to exist, and this gate is
+ * where a flow declares that it stops being allowed.
+ *
+ * Deterministic hosts only — a worker step has no recorded exit code to read —
+ * and the ids it names must be deterministic steps that precede it.
+ */
+export interface StepsGreenGate {
+  type: 'steps_green';
+  /** Earlier deterministic step ids whose recorded exit codes must all be zero. */
+  ids: string[];
+}
+
 export type NamedDataGate = ReferencesInputGate | SubprocessGate | WordCountBoundsGate | RegexMatchGate | ArtifactExistsGate;
 export type OutputVerificationSpec = OutputContainsGate | JsonSchemaGate | NamedDataGate;
-export type VerificationSpec = ExitCodeGate | OutputVerificationSpec;
+export type VerificationSpec = ExitCodeGate | StepsGreenGate | OutputVerificationSpec;
 
 /**
  * Agent-step recovery modes (RFC Appendix A rule 4). Default is `reset`.
@@ -226,6 +248,15 @@ export interface DeterministicStepSpec extends BaseStepSpec {
   timeoutMs?: number;
   /** Per-invocation deterministic lease in milliseconds (maximum 15 minutes). */
   lease_ms?: number;
+  /**
+   * What a nonzero exit means. `'fail'` (the default) is the implicit
+   * `exit_code == 0` gate. `'record'` journals the exit code and output tails
+   * as the step's outcome, completes the step red, and lets dependents run —
+   * the repair-before-failure shape, without discarding the exit code the way
+   * `<command> || true` does. Declared content and schema gates, timeouts and
+   * worker errors keep their existing fatal semantics.
+   */
+  onNonZero?: OnNonZero;
   /** Omit to get the implicit `exit_code` gate. */
   verification?: VerificationSpec;
 }
@@ -274,7 +305,17 @@ export interface AgentStepSpec extends BaseStepSpec {
   surfaces?: AgentSurfaces;
   recoveryMode?: RecoveryMode;
   permissions?: PermissionsSpec;
-  /** Working directory for the CLI subprocess; defaults to the flow-runner's cwd. */
+  /**
+   * Directory the declared CLI is spawned in, as a path relative to the run
+   * root — the flow-runner's working directory, which is also where the CLI
+   * runs when this is absent. Absolute paths, `.`, `..` and empty components
+   * are refused lexically by `flows check` and by the kernel; the worker that
+   * spawns the CLI additionally requires the symlink-free directory to exist
+   * inside the symlink-free run root. A declaration, not a sandbox: nothing
+   * stops a CLI from writing outside it. Not supported with
+   * `transport: 'relay'`, where the agent runs on a host this process cannot
+   * resolve. See docs/SURFACE.md.
+   */
   cwd?: string;
   /**
    * Dispatch transport (flows#385). `'direct'` (default) spawns the CLI as
@@ -440,6 +481,12 @@ export interface KernelDeterministicStep extends KernelStepCommon {
   command: string;
   timeout_ms?: number;
   lease_ms?: number;
+  /**
+   * Omitted for the default `'fail'`, exactly as the kernel skips serializing
+   * it: a step that does not declare the policy keeps the canonical bytes —
+   * and therefore the step hash — it had before this field existed.
+   */
+  on_non_zero?: OnNonZero;
 }
 
 export interface KernelLlmStep extends KernelStepCommon {
@@ -469,7 +516,11 @@ export interface KernelAgentStep extends KernelStepCommon {
   recovery_mode: RecoveryMode;
   surfaces?: KernelAgentSurfaces;
   permissions?: KernelPermissionsSpec;
-  /** Working directory for the CLI subprocess; kernel passes through untouched. */
+  /**
+   * Run-root-relative directory the attached worker spawns the CLI in. The
+   * kernel checks the shape and does no I/O: existence and containment are
+   * decided by the worker, on the host that shares the agent's filesystem.
+   */
   cwd?: string;
   /**
    * Dispatch transport (flows#385). Kernel passes through untouched;

package/src/step-fields.ts

@@ -35,7 +35,7 @@ export const STEP_COMMON_FIELDS = [
  * per-verb boundary through a second, drifting allowlist.
  */
 export const STEP_FIELDS_BY_TYPE = {
-  deterministic: ['command', 'timeoutMs', 'lease_ms'],
+  deterministic: ['command', 'timeoutMs', 'lease_ms', 'onNonZero'],
   llm: ['prompt', 'model', 'cli', 'output'],
   agent: ['instruction', 'agent', 'cli', 'model', 'cwd', 'transport', 'surfaces', 'recoveryMode', 'permissions', 'output'],
 } as const satisfies Record<StepType, readonly string[]>;

package/src/steps-green.ts

@@ -0,0 +1,168 @@
+// The read side of `onNonZero: 'record'`. A `steps_green` gate names earlier
+// deterministic steps and asserts every one of them recorded exit code zero.
+// The verdict comes from the journal — the recorded outcome each step already
+// produced — so asserting it costs nothing and cannot disagree with what ran.
+
+import { bindingDependencies } from './input-binding.js';
+import type { StepSpec, StepsGreenGate, VerificationSpec } from './spec.js';
+
+export const STEPS_GREEN_KEYS = ['type', 'ids'] as const;
+
+export function isStepsGreenGate(gate: VerificationSpec | undefined): gate is StepsGreenGate {
+  return gate?.type === 'steps_green';
+}
+
+/** Shape errors for one gate, without reference to the rest of the flow. */
+export function stepsGreenErrors(gate: Record<string, unknown>, at: string, stepType: string): string[] {
+  const errors: string[] = [];
+  if (stepType !== 'deterministic') {
+    errors.push(`${at}: gate_host_unsupported: steps_green is supported only on deterministic steps`);
+  }
+  const ids = gate['ids'];
+  if (!Array.isArray(ids) || ids.length === 0
+    || !ids.every(id => typeof id === 'string' && id.trim().length > 0)) {
+    errors.push(`${at}.ids: gate_ids_invalid: expected a non-empty array of step ids`);
+    return errors;
+  }
+  if (new Set(ids).size !== ids.length) {
+    errors.push(`${at}.ids: gate_ids_invalid: step ids must be unique`);
+  }
+  return errors;
+}
+
+/**
+ * Flow-level errors: the ids must resolve to earlier deterministic steps whose
+ * recorded outcome this gate can actually read. Refusing here is the whole
+ * point — a gate that silently reads nothing is the `|| true` failure mode
+ * this feature replaces.
+ */
+export function stepsGreenReferenceErrors(steps: readonly unknown[]): string[] {
+  const errors: string[] = [];
+  const sources = new Map(steps.flatMap((step, index) =>
+    isObject(step) && typeof step['id'] === 'string' ? [[step['id'], { step, index }] as const] : []));
+  for (const [index, step] of steps.entries()) {
+    if (!isObject(step)) continue;
+    const gate = step['verification'];
+    if (!isObject(gate) || gate['type'] !== 'steps_green') continue;
+    const ids = gate['ids'];
+    if (!Array.isArray(ids)) continue;
+    const at = `spec.steps[${index}].verification.ids`;
+    for (const id of ids) {
+      if (typeof id !== 'string') continue;
+      const source = sources.get(id);
+      if (source === undefined) {
+        errors.push(`${at}: gate_source_unsupported: unknown step "${id}"`);
+        continue;
+      }
+      if (source.index >= index) {
+        errors.push(`${at}: gate_source_unsupported: source "${id}" must precede this step; forward and self references are not supported`);
+        continue;
+      }
+      if (source.step['type'] !== 'deterministic') {
+        errors.push(`${at}: gate_source_unsupported: source "${id}" is a ${String(source.step['type'])} step and records no exit code`);
+        continue;
+      }
+      // The gate binds the source's whole output envelope, which requires a
+      // declared output schema. Every source shape is reachable except this
+      // one: `output_contains` is the single gate the compiler cannot widen
+      // without dropping the author's own check.
+      const sourceGate = source.step['verification'];
+      if (isObject(sourceGate) && sourceGate['type'] === 'output_contains') {
+        errors.push(`${at}: gate_source_unsupported: source "${id}" declares an output_contains gate, which cannot also carry the output schema this gate reads`);
+      }
+    }
+  }
+  return errors;
+}
+
+/**
+ * Lower every `steps_green` gate into a generated deterministic gate step.
+ *
+ * The host keeps its own command and its own exit policy; the gate is a
+ * separate step, always fatal, that binds each named source's journaled output
+ * envelope and refuses any nonzero or malformed exit code. Dependents of the
+ * host gain a barrier on the gate, so "these steps were green" is established
+ * before anything downstream of the assertion runs.
+ *
+ * Runs BEFORE `lowerNamedGates`, which then adds each source's own named-gate
+ * barrier to the generated step and rewrites named-gate hosts to the permissive
+ * envelope schema this gate's bindings need.
+ */
+export function lowerStepsGreenGates(steps: readonly StepSpec[]): StepSpec[] {
+  const used = new Set(steps.map(step => step.id));
+  const barriers = new Map<string, string>();
+  for (const step of steps) {
+    // Deterministic hosts only, which `validateSpec` already enforces; the
+    // narrowing here is what lets the rewrite below stay type-exact.
+    if (step.type !== 'deterministic' || !isStepsGreenGate(step.verification)) continue;
+    let id = `${step.id}.green`;
+    while (used.has(id)) id += '.green';
+    used.add(id);
+    barriers.set(step.id, id);
+  }
+  if (barriers.size === 0) return [...steps];
+
+  // Every source's envelope has to be bindable. A source that declares no
+  // gate, or the implicit exit_code gate, gets the permissive whole-output
+  // schema; its exit policy is untouched, so a recording source stays red.
+  const bound = new Set(steps.flatMap(step =>
+    isStepsGreenGate(step.verification) ? step.verification.ids : []));
+  const output: StepSpec[] = [];
+  for (const step of steps) {
+    const dependencies = [...new Set([...(step.dependsOn ?? []), ...bindingDependencies(step.input)])];
+    const dependsOn = [...new Set([...dependencies, ...dependencies.flatMap(id => barriers.get(id) ?? [])])];
+    let producer: StepSpec = dependsOn.length ? { ...step, dependsOn } : step;
+    if (bound.has(step.id) && producer.type === 'deterministic'
+      && (producer.verification === undefined || producer.verification.type === 'exit_code')) {
+      producer = { ...producer, verification: { type: 'json_schema', schema: true } };
+    }
+    const gate = step.verification;
+    if (producer.type !== 'deterministic' || !isStepsGreenGate(gate)) {
+      output.push(producer);
+      continue;
+    }
+    // The host's own gate becomes the implicit exit_code check. Its command
+    // still runs, and its own `onNonZero` still applies to its own exit. A
+    // host that is itself read by a later gate keeps the bindable envelope.
+    output.push({
+      ...producer,
+      verification: bound.has(step.id) ? { type: 'json_schema', schema: true } : { type: 'exit_code' },
+    });
+    const input = Object.fromEntries(gate.ids.map((id, index) => [String(index), { step: id }]));
+    output.push({
+      id: barriers.get(step.id)!, type: 'deterministic',
+      // A named source that is itself a gate host must have passed its own
+      // assertion too — depending on the source alone would read its command
+      // exit and let this barrier pass while the inner gate is still red.
+      dependsOn: [...new Set([step.id, ...gate.ids, ...gate.ids.flatMap(id => barriers.get(id) ?? [])])], input,
+      command: greenCommand(gate.ids),
+      verification: { type: 'exit_code' }, maxIterations: step.maxIterations ?? 1,
+      ...(step.requirements === undefined ? {} : { requirements: step.requirements }),
+    });
+  }
+  return output;
+}
+
+/**
+ * Compiler-owned Node command. Author-supplied ids are JSON literals and the
+ * recorded envelopes travel only through FLOWS_INPUT, never through shell text.
+ */
+function greenCommand(ids: readonly string[]): string {
+  const script = `const input=JSON.parse(process.env.FLOWS_INPUT);
+const ids=${JSON.stringify(ids)};
+const red=[];
+for(let i=0;i<ids.length;i++){
+const envelope=input[String(i)];
+if(envelope===null||typeof envelope!=='object'||Array.isArray(envelope)){red.push(ids[i]+': no recorded outcome');continue;}
+const code=envelope.exit_code;
+if(typeof code!=='number'||!Number.isInteger(code)){red.push(ids[i]+': recorded no integer exit_code');continue;}
+if(code!==0)red.push(ids[i]+': exit code '+code);
+}
+if(red.length>0){process.stderr.write('steps_green: '+red.join('; ')+'\\n');process.exit(1);}
+process.stdout.write('steps_green:pass');`;
+  return `node -e '${script.replaceAll("'", "'\\''")}'`;
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}