@relayflows/sdk 2.0.29 → 2.0.31

package/src/cli.ts

@@ -7,6 +7,8 @@ import { describeFlowRequirements } from './flow-requirements.js';
 import type { CliModelSource } from './cli-adapter.js';
 
 import { renderProgress, type ProgressEvent } from './progress.js';
+import type { JournalEvent } from './journal-reader.js';
+import { createObserverSession } from './cli/observer-session.js';
 import { realpathSync } from 'node:fs';
 import { pathToFileURL } from 'node:url';
 import {
@@ -31,6 +33,7 @@ import {
   parseLogsArgs, parseRunsArgs, runCloudLogsCli, runCloudRunsCli, runCloudStatusCli,
   type LogsArgs, type RunsArgs,
 } from './cli/cloud-read.js';
+import { runCloudLogsFollow, runCloudStatusWatch } from './cli/cloud-live.js';
 import { transcriptTailSource } from './transcript-tail.js';
 import { checkTypeScriptFlow } from './cli/check-typescript.js';
 import { runCloudCli } from './cli/cloud-run.js';
@@ -57,6 +60,16 @@ export type { CheckInputDiagnostic, CheckReport } from './cli/check.js';
 export interface CliIo {
   stdout(line: string): void;
   stderr(line: string): void;
+  /**
+   * True when stdout is an interactive terminal.
+   *
+   * Only the live views read it, and only to decide whether a redraw may use
+   * ANSI control sequences: `flows status --cloud --watch` clears the screen
+   * for a terminal and appends whole pages when its output is redirected or
+   * mounted in a host that renders text. Absent means "not a terminal", so an
+   * embedder that says nothing gets the safe form.
+   */
+  tty?: boolean;
 }
 
 type CliExitCode = 0 | 1 | 2 | 3;
@@ -123,9 +136,9 @@ const USAGE = [
   'flows answer [--json] [--no-spawn] [--data-dir <dir>] [--note <text>] [--by <identity>] <run-id> <wait-id> <yes|no>',
   'flows replay [--allow-human-influenced] [--json] [--data-dir <dir>] <run-id> [--at <step-id>]',
   'flows status [--json] [--data-dir <dir>] [--tail <n>] [<run-id>]',
-  'flows status --cloud [--json] <run-id>',
+  'flows status --cloud [--json] [--watch] <run-id>',
   'flows runs [--limit <n>] [--json]',
-  'flows logs [--step <name>] [--raw] [--json] <run-id>',
+  'flows logs [--step <name>] [--raw] [--json] [--follow] <run-id>',
   'flows observer [--data-dir <dir>]',
   'flows hn-monitor start [--data-dir <dir>] [--poll-interval-ms <n>] <spec.json>',
 ].join('\n');
@@ -143,6 +156,7 @@ function spawnAllowedByEnv(env: NodeJS.ProcessEnv = process.env): boolean {
 const PROCESS_IO: CliIo = {
   stdout: (line) => process.stdout.write(`${line}\n`),
   stderr: (line) => process.stderr.write(`${line}\n`),
+  tty: process.stdout.isTTY === true,
 };
 
 /** Optional knobs for an embedded caller. `bin/flows.js` passes none. */
@@ -222,13 +236,21 @@ export async function runCli(
   // works inside a step of a run whose daemon is gone (kernel/DAEMON-LIFECYCLE.md §4).
   if (parsed.command === 'status') {
     // One verb, two sources. `--cloud` never reaches `runStatus`, so the
-    // offline reader stays offline (cli/status.ts).
-    return parsed.cloud === true
-      ? runCloudStatusCli(parsed, io)
-      : runStatus(parsed, io, { tails: transcriptTailSource() });
+    // offline reader stays offline (cli/status.ts). Only `--watch` blocks, so
+    // only `--watch` takes a signal: a one-shot read keeps installing none.
+    if (parsed.cloud !== true) return runStatus(parsed, io, { tails: transcriptTailSource() });
+    const cloudStatus = parsed;
+    return cloudStatus.watch === true
+      ? withInterrupt(options.signal, (signal) => runCloudStatusWatch(cloudStatus, io, { signal }))
+      : runCloudStatusCli(cloudStatus, io);
   }
   if (parsed.command === 'runs') return runCloudRunsCli(parsed, io);
-  if (parsed.command === 'logs') return runCloudLogsCli(parsed, io);
+  if (parsed.command === 'logs') {
+    const logs = parsed;
+    return logs.follow
+      ? withInterrupt(options.signal, (signal) => runCloudLogsFollow(logs, io, { signal }))
+      : runCloudLogsCli(logs, io);
+  }
   if (parsed.command === 'answer') {
     const execution = await answerFlow(parsed.runId, parsed.waitId, parsed.answer, parsed.dataDir, {
       ...(parsed.note === undefined ? {} : { note: parsed.note }),
@@ -250,8 +272,13 @@ export async function runCli(
     // refuses `--data-dir` on `check`, so there is no data dir to attach to.
     // `flows check` keeps working with no daemon, no relayflowd binary and no
     // data directory at all -- a property worth keeping, not an omission.
+    // Only this invocation opts into `agent_worker_unresolved`: `flows check`
+    // attaches no worker and, being daemon-free, cannot see one attached
+    // elsewhere. The authored `.flow.ts` path checks header declarations
+    // without compiling steps, so it has no agent steps to count.
     const checked = /\.(?:[cm]?[jt]s)$/.test(parsed.value)
-      ? await checkAuthoredFlowComposed(parsed.value) : checkFlow(parsed.value);
+      ? await checkAuthoredFlowComposed(parsed.value)
+      : checkFlow(parsed.value, { warnUnresolvedAgentWorker: true });
     emitCheckReport(checked.report, parsed.json, io);
     return checked.report.ok ? 0 : 2;
   }
@@ -287,9 +314,11 @@ export async function runCli(
   // not here. Hoisting it above the dispatch would start a daemon as a side
   // effect of an invocation that is about to be refused for bad input.
   const startedSteps = new Map<string, number>();
+  const observer = parsed.noObserverLink ? undefined : createObserverSession(parsed.command, io);
   const showProgress = (event: ProgressEvent): void => {
     if (event.type === 'step.started') startedSteps.set(event.stepId, performance.now());
     if (!parsed.json) for (const line of renderProgress([event])) io.stderr(line);
+    observer?.onProgress(event);
   };
   const lifecycle = {
     ...(parsed.command === 'run' ? { bucket: parsed.bucket } : {}),
@@ -299,6 +328,10 @@ export async function runCli(
     localAgent: parsed.localAgent,
     ...(parsed.agentCapacity === undefined ? {} : { agentCapacity: parsed.agentCapacity }),
     onProgress: showProgress,
+    ...(observer === undefined ? {} : {
+      onJournalEntry: (entry: JournalEvent) => observer.onJournalEntry(entry),
+      onRunStarted: (run: { runId: string; flow: string; resumed?: boolean }) => observer.onRunStarted(run),
+    }),
     onWait: (progress: RunProgress) => {
       emitWait(progress, io);
       const now = performance.now();
@@ -308,16 +341,15 @@ export async function runCli(
     },
     daemon: { spawn: parsed.spawn && spawnAllowedByEnv() },
   };
-  // Mint the observer token in parallel with the run so the mint round-trip
-  // never adds to the RUN summary latency. The outcome is only consulted at
-  // emit time; a rejected promise here can never fail the run (see
-  // `observerUrlFrom`, which swallows every failure into `warning`).
-  const observerMint = startObserverMint(parsed);
   const execution = parsed.command === 'run'
     ? isAuthoredFlowPath(parsed.value)
       ? await runDirectFlow(parsed.value, parsed.input, parsed.dataDir, lifecycle)
       : await runFlow(parsed.value, parsed.dataDir, lifecycle)
     : await resumeFlow(parsed.value, parsed.dataDir, lifecycle);
+  // The link is scoped to the run's channel, so it exists only once the run
+  // does. `finish` drains the projection and settles the mint, both bounded;
+  // it never rejects (see `createObserverSession`).
+  const observerMint = observer?.finish(execution.report);
   // In `--json` mode the report is a single machine-readable object that
   // MUST carry `observerUrl` when one is available, so a consumer sees one
   // authoritative signal. That justifies blocking up to `MINT_TIMEOUT_MS`
@@ -369,35 +401,6 @@ async function checkAuthoredFlowComposed(path: string): Promise<{ report: CheckR
   };
 }
 
-/**
- * Start the observer-token mint if the environment says one should happen.
- * Returns `undefined` when no attempt should be made — no workspace key
- * configured, or `FLOWS_NO_OBSERVER=1` / `--no-observer-link` — which is the
- * silent-skip branch. The returned promise always resolves; a rejection here
- * would slip past `observerUrlFrom` and could fail the run, which the feature
- * expressly forbids.
- */
-function startObserverMint(
-  parsed: { command: 'run' | 'resume'; noObserverLink: boolean },
-  env: NodeJS.ProcessEnv = process.env,
-  mint: (options: MintObserverOptions) => Promise<{ observerUrl?: string; warning?: string }> = mintObserverUrl,
-): Promise<{ observerUrl?: string; warning?: string }> | undefined {
-  if (parsed.noObserverLink) return undefined;
-  // `resolveObserverLinkEnv` (not `readObserverLinkEnv`) falls back to the
-  // `agent-relay cloud login` workspace store (~/.agentworkforce/relay/
-  // workspaces.json) when RELAYCAST_WORKSPACE_KEY is unset. Env wins if set;
-  // FLOWS_NO_OBSERVER=1 still suppresses regardless of source.
-  const link = resolveObserverLinkEnv(env);
-  if (link.suppressed || link.workspaceKey === undefined) return undefined;
-  return mint({
-    workspaceKey: link.workspaceKey,
-    ...(link.baseUrl !== undefined ? { baseUrl: link.baseUrl } : {}),
-    ...(link.dashboardUrl !== undefined ? { dashboardUrl: link.dashboardUrl } : {}),
-  }).catch((error) => ({
-    warning: error instanceof Error ? error.message : 'unknown mint error',
-  }));
-}
-
 /**
  * Resolve the pending observer-mint into a URL (or nothing), and route any
  * mint warning to stderr under a `[observer]` label. Silent-skip (`undefined`
@@ -941,6 +944,18 @@ function parseTickArgs(rest: readonly string[]): ParsedArgs | undefined {
   };
 }
 
+/**
+ * `agent_worker_unresolved` reads as a footnote to `REQUIRES codex (step
+ * "implement"), …`: that line already names the steps that need an agent
+ * worker, and this says what has to be true for one to be attached. So the
+ * plain-text pass holds it back and emits it in that position, exactly once —
+ * the leading batch below skips it rather than printing it twice. JSON mode
+ * returns before any of this and keeps the single ordered diagnostics array.
+ */
+function isWorkerSurfaceWarning(diagnostic: CheckReport['diagnostics'][number]): boolean {
+  return diagnostic.kind === 'agent_worker_unresolved';
+}
+
 const MODEL_PROVENANCE: Readonly<Record<CliModelSource, string>> = {
   step: 'step',
   named: 'named agent',
@@ -953,16 +968,20 @@ function modelProvenance(source: CliModelSource | undefined): string {
 }
 
 function emitCheckReport(report: CheckReport, json: boolean, io: CliIo): void {
-  emitDiagnostics(report.diagnostics, io);
   if (json) {
+    emitDiagnostics(report.diagnostics, io);
     io.stdout(JSON.stringify(report));
     return;
   }
+  const deferred = report.diagnostics.filter(isWorkerSurfaceWarning);
+  emitDiagnostics(report.diagnostics.filter((diagnostic) => !isWorkerSurfaceWarning(diagnostic)), io);
   for (const gate of report.gates) {
     // A gate that accepts every output is legal, but it must not read like a
     // gate that judges something.
     const vacuous = gate.acceptsAnyOutput === true ? ' [json_schema accepts any output]' : '';
-    io.stdout(`GATE step "${gate.stepId}" ${gate.checks.join('+')} from data (kernel, journal-replayable)${vacuous}`);
+    // Red-but-complete is a declared shape, so it is a visible one.
+    const recorded = gate.recordsNonZeroExit === true ? ' [onNonZero: record]' : '';
+    io.stdout(`GATE step "${gate.stepId}" ${gate.checks.join('+')} from data (kernel, journal-replayable)${vacuous}${recorded}`);
   }
   for (const schedule of report.schedules ?? []) {
     const declared = schedule.cron !== undefined
@@ -1001,6 +1020,7 @@ function emitCheckReport(report: CheckReport, json: boolean, io: CliIo): void {
   // the hosted verbs check the same list against Cloud before submitting.
   const requires = report.requirements === undefined ? '' : describeFlowRequirements(report.requirements);
   if (requires) io.stdout(`REQUIRES ${requires}`);
+  emitDiagnostics(deferred, io);
   if (report.ok) io.stdout(`CHECK PASSED ${report.path ?? ''}`.trimEnd());
 }
 

package/src/cloud-read.ts

@@ -15,6 +15,7 @@
 // key is ignored, a route that drops one yields `null`, never a throw.
 
 import { CloudFlowError, cloudFetch, cloudRunId, isCloudRecord, type CloudConnectionOptions } from './cloud-http.js';
+import { cloudRunState, type CloudRunState } from './cloud-run-record.js';
 
 /** One row of `GET /api/v1/workflows/runs`. */
 export interface CloudRunSummary {
@@ -334,8 +335,31 @@ export async function getCloudRunDetail(
   options: CloudConnectionOptions = {},
 ): Promise<CloudRunDetail> {
   const asked = callerRunId(runId);
-  const body = record(await cloudFetch(`/api/v1/workflows/runs/${asked}`, options,
+  return runDetail(asked, await cloudFetch(`/api/v1/workflows/runs/${asked}`, options,
     { method: 'GET', detail: true }));
+}
+
+/**
+ * The run record twice over: what to render, and what it attests.
+ *
+ * `--watch` and `--follow` need both, from the same bytes. The rendered view
+ * is the permissive mapping below, which shows whatever Cloud said; the exit
+ * code comes from `cloudRunState`, the same validator `flows run --wait`
+ * blocks on, so a live read cannot exit 0 on a record the waiter refuses.
+ * One request, because a second GET per poll could observe a different run
+ * than the one that was drawn.
+ */
+export async function getCloudRunDetailLive(
+  runId: string,
+  options: CloudConnectionOptions = {},
+): Promise<{ detail: CloudRunDetail; state: CloudRunState }> {
+  const asked = callerRunId(runId);
+  const answered = await cloudFetch(`/api/v1/workflows/runs/${asked}`, options, { method: 'GET', detail: true });
+  return { detail: runDetail(asked, answered), state: cloudRunState(answered, asked) };
+}
+
+function runDetail(asked: string, answeredBody: unknown): CloudRunDetail {
+  const body = record(answeredBody);
   if (body === null) throw new CloudFlowError('invalid_response', 'Cloud returned no run record.');
   // The record has to be the record that was asked for, and it has to say what
   // the run is doing. `getCloudFlowRun` (cloud-run.ts) already refuses a

package/src/cloud-run-record.ts

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

package/src/cloud-run.ts

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

package/src/communication/local.ts

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

package/src/communication/worker.ts

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

package/src/compile.ts

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

package/src/direct-input.ts

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