@relayflows/sdk 2.0.30 → 2.0.32

package/src/preflight.ts

@@ -12,6 +12,7 @@ import { compileSpec, CompileError } from './compile.js';
 import { helperCall } from './yaml-helpers.js';
 import { resolveCliModelSelection, type CliModelSource } from './cli-adapter.js';
 import { isNamedGate, NAMED_GATE_FAILURE_KINDS, type NamedGateFailureKind } from './named-gates.js';
+import { namedGateScanCoverageDiagnostics } from './named-gate-preflight.js';
 import { compileScopes, type ScopeInput, type MountRegistry } from './scope-compiler.js';
 import { readMountRegistry } from './mount-registry.js';
 import type {
@@ -64,7 +65,7 @@ export class CliProbeError extends Error {
   }
 }
 
-type CliProbeOutcome =
+export type CliProbeOutcome =
   | { result: CliProbeResult }
   | { failure: CliProbeFailureDetail | null };
 
@@ -88,6 +89,8 @@ export interface PreflightProbes {
 }
 
 export interface PreflightOptions {
+  /** Reuse only within one run and one CLI resolution environment; failures are cached too. */
+  cliProbeCache?: Map<string, CliProbeOutcome>;
   pluginSearchStart?: string;
   /** Validated tools.mcp header and nearest flows.json connections. */
   mcpServers?: readonly string[];
@@ -98,6 +101,7 @@ export interface PreflightOptions {
   /** Exact, project-owned model allowlist from the nearest flows.json. */
   models?: readonly string[];
   modelRegistryPath?: string;
+  probeCache?: Map<string, CliProbeOutcome>;
   probes: PreflightProbes;
 }
 
@@ -193,7 +197,12 @@ async function probeMcp(result: PreflightResult, options: PreflightOptions): Pro
   return { ...result, ok: !result.diagnostics.some(d => d.severity === 'refusal'), mcpTools: Object.freeze(inventory) };
 }
 
-function preflightSync(flow: unknown, options: PreflightOptions): PreflightResult {
+type ResolutionOptions = Omit<PreflightOptions, 'probes' | 'probeCache'>;
+
+/** Resolve static declarations before any CLI, model, command or trigger probe. */
+export function resolvePreflight(flow: unknown, options: ResolutionOptions): PreflightResult & {
+  compiled?: import('./compile.js').CompiledFlowSpec;
+} {
   // Compile before touching any environment fact. `compileSpec` snapshots raw
   // input into inert data, validates it against the closed authoring schema,
   // and lowers `output` sugar into its json_schema gate — so the gate plan
@@ -234,7 +243,7 @@ function preflightSync(flow: unknown, options: PreflightOptions): PreflightResul
   const cliResolutionDiagnostics: PreflightDiagnostic[] = [];
   const resolutions: CliResolution[] = [];
   const resolutionByStep = new Map<string, CliResolution>();
-  const cliProbeResults = new Map<string, CliProbeOutcome>();
+  const cliProbeResults = options.cliProbeCache ?? new Map<string, CliProbeOutcome>();
 
   // A pure fact about the compiled snapshot, collected before anything that
   // can return early. An unresolved CLI, an unknown model or a bad scope all
@@ -242,6 +251,12 @@ function preflightSync(flow: unknown, options: PreflightOptions): PreflightResul
   // permissions they declared on the same file are not enforced.
   diagnostics.push(...permissionsDiagnostics(compiled));
   diagnostics.push(...scopeDiagnostics(compiled, options));
+  // Same rule, same reason: whether the bundled worker's artifact scan can
+  // reach an `artifact_exists` path is decidable from the snapshot, so it is
+  // collected here rather than beside `probeNamedGate` below — which CLI
+  // resolution, an unknown model, a bad scope or a budget refusal all return
+  // before.
+  diagnostics.push(...compiled.steps.flatMap(namedGateScanCoverageDiagnostics));
   for (const server of new Set(options.mcpServers ?? [])) {
     if (options.mcp !== undefined && Object.hasOwn(options.mcp, server)) continue;
     diagnostics.push({ severity: 'refusal', kind: 'mcp_undeclared_server', server,
@@ -282,6 +297,18 @@ function preflightSync(flow: unknown, options: PreflightOptions): PreflightResul
     return { ok: false, gates: compiled.steps.map(inspectStepGate), resolutions, diagnostics };
   }
 
+  return { ok: true, gates: compiled.steps.map(inspectStepGate), resolutions, diagnostics, compiled };
+}
+
+function preflightSync(flow: unknown, options: PreflightOptions): PreflightResult {
+  const { compiled, ...result } = resolvePreflight(flow, options);
+  if (!result.ok || compiled === undefined) return result;
+  const { diagnostics, resolutions } = result;
+  const resolutionByStep = new Map(resolutions.map(resolution => [resolution.stepId, resolution]));
+  // `cliProbeCache` is the public run-scoped name; `probeCache` is retained as
+  // a compatibility alias for the async authored-preflight path.
+  const cliProbeResults = options.cliProbeCache ?? options.probeCache ?? new Map<string, CliProbeOutcome>();
+
   for (const step of compiled.steps) {
     probeNamedGate(step, options.probes, diagnostics);
     warnOnVacuousGate(step, diagnostics);
@@ -326,7 +353,7 @@ function preflightSync(flow: unknown, options: PreflightOptions): PreflightResul
  * fact about the filesystem. Missing manifest means no known mounts — a grant
  * still parses but refuses as `mount_unknown` in that case.
  */
-function scopeDiagnostics(flow: FlowSpec, options: PreflightOptions): PreflightRefusal[] {
+function scopeDiagnostics(flow: FlowSpec, options: ResolutionOptions): PreflightRefusal[] {
   const workspace = flow.workspace;
   const toolsFs = flow.tools?.fs;
   if (workspace === undefined && toolsFs === undefined) return [];
@@ -350,7 +377,7 @@ function scopeDiagnostics(flow: FlowSpec, options: PreflightOptions): PreflightR
 /** Pure authoring validation: no executable, command, trigger, or daemon probe. */
 function unknownModelDiagnostics(
   flow: FlowSpec,
-  options: PreflightOptions,
+  options: ResolutionOptions,
   resolutionByStep: ReadonlyMap<string, CliResolution> = new Map(),
 ): PreflightRefusal[] {
   const diagnostics: PreflightRefusal[] = [];
@@ -464,7 +491,7 @@ function unknownModelMessage(
   return `Step "${stepId}" declares model "${model}"${cliContext}, but it is not listed in ${source}; add the exact model only after verifying that project is allowed to use it.`;
 }
 
-function unresolvedCliMessage(stepId: string, options: PreflightOptions): string {
+function unresolvedCliMessage(stepId: string, options: ResolutionOptions): string {
   const context = options.projectConfigPath !== undefined
     ? ` Nearest project config "${options.projectConfigPath}" declares no cli; outer configs are shadowed.`
     : options.projectSearchStart !== undefined
@@ -494,6 +521,10 @@ function resolveCli(
   return undefined;
 }
 
+export function cliProbeKey(resolution: CliResolution, managed = false): string {
+  return JSON.stringify([resolution.cli, resolution.source, resolution.model ?? null, managed]);
+}
+
 function probeResolvedCli(
   resolution: CliResolution,
   probes: PreflightProbes,
@@ -507,7 +538,7 @@ function probeResolvedCli(
   // Model is part of the key: the same CLI probed with two different models
   // is two different questions, and caching on the CLI alone would let a
   // model that the CLI cannot resolve inherit an earlier model's pass.
-  const cacheKey = JSON.stringify([resolution.cli, resolution.source, resolution.model ?? null, managed]);
+  const cacheKey = cliProbeKey(resolution, managed);
   let outcome = cache.get(cacheKey);
   if (outcome === undefined) {
     try {

package/src/protocol.ts

@@ -96,6 +96,8 @@ export type StepUsage =
 export interface RunStartParams {
   /** Caller-owned retry identity. Reuse with a different spec is refused. */
   admission_key?: string;
+  /** Push the new run's entries to this connection from `run.spawned` on, as `run.watch` does. */
+  watch?: boolean;
   reuse_from_run_id?: string;
   /**
    * The kernel spec dialect — the ONE boundary shape `RunSpec::parse`

package/src/redact.ts

@@ -104,3 +104,114 @@ export function redactRelayError(message: string, env: NodeJS.ProcessEnv = proce
   }
   return redact(message, env);
 }
+
+/**
+ * Credential heads whose value may continue past a line boundary.
+ *
+ * Every NAMED_VALUE pattern puts `\s` between the name and the value, and
+ * `\s` matches newlines: `authorization:` alone at the end of a poll is a
+ * complete, unredacted line, while the opaque value that lands on the next
+ * poll arrives with no recognizable credential context and would print
+ * verbatim. A trailing header — the colon plus only whitespace, or for
+ * `authorization` one scheme word — is therefore an open context. A header
+ * already followed by a non-space word has its value on that line and is not
+ * open. `Bearer` is the one bare scheme word the patterns treat as a name.
+ */
+const OPEN_HEADER_PATTERNS: readonly RegExp[] = [
+  /\bauthorization:(?:\s+\w+)?\s*$/i,
+  /\bx-callback-token:\s*$/i,
+  /\bx-nightcto-evidence-token:\s*$/i,
+  /\bBearer\s*$/,
+];
+
+/** A quoted JSON field name; the value side is inspected by the scanner. */
+const JSON_FIELD_HEAD = /"([A-Za-z0-9_.\-]{1,64})"/g;
+
+/**
+ * Where a named-credential context may still be half-arrived at the end of
+ * `text`.
+ *
+ * `openSecretStart` covers secret env *values*; this covers the credential
+ * *names* whose patterns can span a line break: a header released on one poll
+ * leaves its late-arriving value unrecognizable on the next, and a credential
+ * JSON field whose value string is not yet closed leaks its first fragment.
+ * Returns the earliest index at which such a context is open — the point past
+ * which nothing may be released until more of the stream arrives — or
+ * `text.length` when none is open. Holding back is line-granular upstream, so
+ * a false positive delays one line one poll rather than dropping it.
+ */
+export function openCredentialStart(text: string): number {
+  let hold = text.length;
+  for (const pattern of OPEN_HEADER_PATTERNS) {
+    const match = pattern.exec(text);
+    if (match && match.index < hold) hold = match.index;
+  }
+  JSON_FIELD_HEAD.lastIndex = 0;
+  let head: RegExpExecArray | null;
+  while ((head = JSON_FIELD_HEAD.exec(text)) !== null) {
+    if (!isCredentialName(head[1]!)) continue;
+    let i = head.index + head[0].length;
+    while (i < text.length && /\s/.test(text[i]!)) i++;
+    if (i >= text.length) { hold = Math.min(hold, head.index); continue; }
+    if (text[i] !== ':') continue;
+    i++;
+    while (i < text.length && /\s/.test(text[i]!)) i++;
+    if (i >= text.length) { hold = Math.min(hold, head.index); continue; }
+    if (text.startsWith('[redacted]', i) || text[i] !== '"') continue;
+    i++;
+    let closed = false;
+    while (i < text.length) {
+      if (text[i] === '\\') { i += 2; continue; }
+      if (text[i] === '"') { closed = true; break; }
+      i++;
+    }
+    if (!closed) hold = Math.min(hold, head.index);
+  }
+  return hold;
+}
+
+/**
+ * Does `text` end on a bare credential header — a named credential line whose
+ * value, if it has one, begins on the NEXT line?
+ *
+ * The stream releaser needs this apart from `openCredentialStart`: that check
+ * sees only a header at the very end of the consumed text, but the danger is
+ * wider — a released block that *ends* on `x-callback-token:` prints the
+ * header now and its value, arriving on the next line in some later poll,
+ * without the context `redact` needs. `redact` folds the header's newline into
+ * its own named-pattern match, so the releaser's block-prefix check cannot
+ * detect the dependency on its own. Trailing whitespace-only lines after the
+ * header count as part of it — the value is still to come.
+ */
+export function endsWithOpenCredentialHeader(text: string): boolean {
+  const stripped = text.replace(/\s+$/, '');
+  const lastLine = stripped.slice(stripped.lastIndexOf('\n') + 1);
+  return OPEN_HEADER_PATTERNS.some((pattern) => pattern.test(lastLine));
+}
+
+/**
+ * Where a secret value may still be half-arrived at the end of `text`.
+ *
+ * A stream is redacted in pieces, and `redact` only replaces a secret it can
+ * see whole: releasing text up to a point where a secret has begun but not
+ * ended would print the first half of it and never match the second. This
+ * returns the smallest index `i` for which `text.slice(i)` is a proper prefix
+ * of some secret env value — the point past which nothing may be released
+ * until more of the stream arrives — or `text.length` when no value is open.
+ *
+ * Values only, not the token and header *shapes*: those are bounded by
+ * whitespace, so a reader that releases whole lines cannot cut one in half.
+ */
+export function openSecretStart(text: string, env: NodeJS.ProcessEnv = process.env): number {
+  let start = text.length;
+  for (const [, value] of secretEnvValues(env)) {
+    // A proper prefix is shorter than the value, so it can only begin inside
+    // the last `value.length - 1` characters; the first character narrows the
+    // scan to the few positions worth comparing.
+    const first = Math.max(0, text.length - value.length + 1);
+    for (let at = text.indexOf(value[0]!, first); at >= 0 && at < start; at = text.indexOf(value[0]!, at + 1)) {
+      if (value.startsWith(text.slice(at))) { start = at; break; }
+    }
+  }
+  return start;
+}

package/src/relay-cli.ts

@@ -1,7 +1,6 @@
-import { readFileSync } from 'node:fs';
-
 import { runCli } from './cli.js';
 import { CLI_VERBS, CLI_VERB_NAMES, type CliCommandSpec } from './cli-commands.js';
+import { packageVersion } from './package-version.js';
 
 /**
  * The `@relayflows/sdk/relay-cli` entrypoint: a mountable CLI surface.
@@ -56,28 +55,6 @@ function toCommandSpec(verb: CliCommandSpec & { variants?: unknown }): CliComman
   return spec;
 }
 
-/**
- * Read this package's version from its own manifest.
- *
- * Resolved from `import.meta.url` rather than imported, because `package.json`
- * sits outside `rootDir` and a hardcoded literal would silently go stale at the
- * next release. `src/` and `dist/` are both one level below the manifest, so
- * the same relative path is correct before and after a build.
- */
-function packageVersion(): string {
-  try {
-    const manifest: unknown = JSON.parse(
-      readFileSync(new URL('../package.json', import.meta.url), 'utf8'),
-    );
-    const version = (manifest as { version?: unknown }).version;
-    return typeof version === 'string' && version.length > 0 ? version : '0.0.0';
-  } catch {
-    // A surface that cannot read its own manifest is still perfectly runnable;
-    // refusing to mount over a cosmetic field would be the worse failure.
-    return '0.0.0';
-  }
-}
-
 /**
  * Build the relayflows CLI surface.
  *

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/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[]>;