@relayflows/sdk 2.0.30 → 2.0.31

package/src/named-gate-lowering.ts

@@ -71,19 +71,33 @@ process.exit(artifacts.includes(${JSON.stringify(gate.path)})?0:1);`)}`;
   }
   const path = gate.type === 'subprocess_gate' ? gate.from_output
     : gate.type === 'word_count_bounds' ? undefined : gate.in_output_at;
+  const pathKey = gate.type === 'subprocess_gate' ? 'from_output' : 'in_output_at';
   // Only compiler-owned code is serialized. Author strings are JSON literals;
   // upstream output travels exclusively through FLOWS_INPUT, never shell text.
+  //
+  // `fail` answers a gate that exits 1 having said nothing. Every exit that is
+  // NOT the author's own predicate or command verdict goes through it: a
+  // selection that missed, input the child cannot carry, a child that never
+  // started, a child killed by a signal. It writes ONE bounded line to fd 2
+  // and nothing to fd 1 — `references_input` and `word_count_bounds` verify
+  // against stdout, so a stray byte there would change a verdict.
+  //
+  // `writeSync` rather than `process.stderr.write`: on a pipe the latter is
+  // asynchronous, and the `process.exit` on the same line would drop the
+  // diagnostic exactly when it is the only account of the failure there is.
   const setup = `const cp=require('node:child_process');
+const fail=m=>{require('node:fs').writeSync(2,${JSON.stringify(`${gate.type}: `)}+m.replace(/[\\r\\n]+/g,' ').slice(0,400)+'\\n');process.exit(1);};
 const input=JSON.parse(process.env.FLOWS_INPUT);
 let value=input.output;
 const path=${JSON.stringify(path ?? null)};
 if(path!==null){for(const key of path){
 if(value===null||typeof value!=='object'||!Object.hasOwn(value,key)||
-(typeof key==='number'?!Array.isArray(value):Array.isArray(value)))process.exit(1);
+(typeof key==='number'?!Array.isArray(value):Array.isArray(value)))
+fail(${JSON.stringify(`${pathKey} ${JSON.stringify(path ?? null)} selected nothing: no `)}+JSON.stringify(key)+' at that position in the producer output');
 value=value[key];
 }}else if(${deterministic})value=value.stdout_tail;
 const text=typeof value==='string'?value:JSON.stringify(value);
-if(typeof text!=='string')process.exit(1);
+if(typeof text!=='string')fail('the selected value could not be read as text');
 `;
   let body: string;
   switch (gate.type) {
@@ -93,16 +107,32 @@ if(typeof reference!=='string'||reference.length===0||!text.includes(reference))
 process.stdout.write('references_input:pass');`;
       break;
     case 'subprocess_gate':
-      body = `if(text.includes('\\0'))process.exit(1);
+      // `stdio: 'inherit'` hands the child the gate step's own stdout/stderr,
+      // which ARE the kernel's capture pipes (relayflowd/src/exec_det.rs:78),
+      // so the command's output is journaled as it is produced — including
+      // whatever it wrote before a timeout killed the process group. Buffering
+      // it for a post-wait flush would lose exactly that. What was missing is
+      // below: `status` is null for every outcome that is not an exit, and all
+      // of them used to collapse into an indistinguishable bare `exit 1`.
+      body = `if(text.includes('\\0'))fail('the selected text contains a NUL byte and cannot be passed to the gate command');
 const result=cp.spawnSync('/bin/sh',['-c',${JSON.stringify(gate.command)}],{
 env:{...process.env,INPUT:text},stdio:'inherit'});
+if(result.error)fail('could not run the gate command: '+(result.error.code||result.error.message)+' (the selected input was '+Buffer.byteLength(text)+' bytes)');
+if(result.signal)fail('the gate command was terminated by '+result.signal);
 process.exit(result.status===0?0:1);`;
       break;
     case 'word_count_bounds':
+      // The other gate that spawns a child. Its `wc` stderr was piped and then
+      // discarded, so a broken or absent `wc` was reported as a word count out
+      // of bounds. A bounded suffix of what it said travels with the cause.
       body = `const result=cp.spawnSync('wc',['-w'],{input:text,encoding:'utf8',env:{...process.env,LC_ALL:'C'}});
-if(result.status!==0)process.exit(1);
+const noise=(result.stderr||'').trim().slice(-200);
+const said=noise===''?'':': '+noise;
+if(result.error)fail('could not run wc -w: '+(result.error.code||result.error.message)+said);
+if(result.signal)fail('wc -w was terminated by '+result.signal+said);
+if(result.status!==0)fail('wc -w exited '+result.status+said);
 const count=result.stdout.trim();
-if(!/^[0-9]+$/.test(count))process.exit(1);
+if(!/^[0-9]+$/.test(count))fail('wc -w printed '+JSON.stringify(count.slice(0,80))+' instead of a word count'+said);
 process.stdout.write(BigInt(count).toString());`;
       break;
     case 'regex_match':

package/src/named-gate-preflight.ts

@@ -0,0 +1,47 @@
+import { unscannedArtifactPrefix } from './artifact-scan-policy.js';
+import { isNamedGate } from './named-gates.js';
+import type { StepSpec } from './spec.js';
+import type { PreflightWarning } from './preflight.js';
+
+/**
+ * Static named-gate scan coverage, decided from the compiled snapshot alone.
+ *
+ * An `artifact_exists` gate lowers to a deterministic step that asks whether
+ * the producer's journaled `output.artifacts` list contains the literal path
+ * (`named-gate-lowering.ts`). One writer of that list is the bundled agent
+ * worker's filesystem scan, which walks the step's cwd under the policy in
+ * `artifact-scan-policy.ts` and records nothing under a dot-named or
+ * `node_modules` entry. A path inside one of those prefixes can never come
+ * from that scan, on any host, in any environment.
+ *
+ * A warning rather than a refusal, because the scan is not the only writer.
+ * The same bundled worker promotes object-shaped JSON stdout — and a completed
+ * Relay task's output — straight to the journaled `output` (`worker.ts`), so
+ * an agent that reports its own `artifacts` array makes a hidden path pass;
+ * the journal protocol lets a custom worker do the same. Which of those an
+ * `agent` step will take is not decidable from the spec, so this reports the
+ * scan's limitation and leaves the verdict to the run rather than declaring a
+ * satisfiable gate impossible.
+ *
+ * Temporary: this describes #513. When the scan stops excluding these paths,
+ * delete this module and its call site.
+ */
+export function namedGateScanCoverageDiagnostics(step: StepSpec): PreflightWarning[] {
+  const gate = step.verification;
+  if (!isNamedGate(gate) || gate.type !== 'artifact_exists') return [];
+  // A malformed path is already `gate_path_invalid` from compilation; only
+  // validated relative POSIX paths reach here.
+  const prefix = unscannedArtifactPrefix(gate.path);
+  if (prefix === undefined) return [];
+  return [{
+    severity: 'warning',
+    kind: 'gate_path_unscanned',
+    stepId: step.id,
+    message: `Step "${step.id}" gates on artifact_exists path "${gate.path}", but the bundled agent worker's `
+      + `artifact scan records nothing under "${prefix}": it skips entries named `
+      + '".git", ".relayflowd" and "node_modules". The gate reads the journaled output.artifacts and never the disk, so '
+      + 'writing the file is not enough: the step has to report the path itself — as object-shaped JSON stdout '
+      + 'carrying its own "artifacts" array, as a completed Relay task output, or from a custom worker. If the '
+      + 'gate is meant to rest on the scan, write the artifact to a path the scan records.',
+  }];
+}

package/src/named-gates.ts

@@ -3,6 +3,9 @@ import type { NamedDataGate, VerificationSpec } from './spec.js';
 
 export const NAMED_GATE_FAILURE_KINDS = [
   'unknown_gate_kind', 'gate_pattern_invalid', 'gate_command_missing', 'gate_bound_invalid', 'gate_path_invalid',
+  // steps_green refusals: the gate is declarative like the named gates above,
+  // so it reports through the same kind channel a caller already switches on.
+  'gate_host_unsupported', 'gate_ids_invalid', 'gate_source_unsupported',
 ] as const;
 export type NamedGateFailureKind = typeof NAMED_GATE_FAILURE_KINDS[number];
 

package/src/observer-link.ts

@@ -238,6 +238,13 @@ export interface MintObserverOptions {
    * (default `https://agentrelay.com`). Separate axis from `baseUrl` — the
    * mint API lives on a different subdomain from the dashboard. */
   dashboardUrl?: string;
+  /**
+   * Scope the token to this one channel, so the dashboard opens on it — the
+   * run's `wf-<runId>` channel — rather than on whichever channel the
+   * workspace lists first. DMs are excluded: a run projects its
+   * conversation into that channel. Omitted: the whole workspace.
+   */
+  channel?: string;
   fetch?: ObserverFetch;
   now?: () => number;
   /** Called for the token's uniquely-suffixed name; injectable for tests. */
@@ -299,7 +306,9 @@ export async function mintObserverUrl(
     name: `flows-run-${uuid}`,
     description: 'Auto-minted by `flows run` for the observer dashboard link.',
     scopes: OBSERVER_SCOPES,
-    filters: { include_dms: true },
+    filters: options.channel === undefined
+      ? { include_dms: true }
+      : { channel_names: [options.channel], include_dms: false },
     expires_at: new Date(now() + OBSERVER_TOKEN_TTL_MS).toISOString(),
   };
 

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 {
@@ -242,6 +243,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,

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/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("'", "'\\''")}'`;
+}