@relayflows/sdk 2.0.29 → 2.0.31

package/src/journal-projection.ts

@@ -0,0 +1,106 @@
+/**
+ * Fold a run's journal entries, as `run.start {watch}` or `run.watch` pushes
+ * them, into a `RunProjection`: `run.spawned` opens it with the declared step
+ * graph, attempt starts and completions become step transitions, and
+ * `run.completed` closes it. Entries journaled before `liveSinceMs` (a resume
+ * replaying history) update the snapshot without publishing a message each.
+ */
+
+import type { JournalEvent } from './journal-reader.js';
+import type { ProgressEvent } from './progress.js';
+import type { DeclaredStep, RunProjection, RunSnapshot } from './run-projection.js';
+import type { StepType } from './spec.js';
+
+export type OpenProjection = (run: { runId: string; flow: string; steps: DeclaredStep[] }) => RunProjection;
+
+export function createJournalProjector(open: OpenProjection, liveSinceMs = 0): (entry: JournalEvent) => void {
+  let projection: RunProjection | undefined;
+  const types = new Map<string, StepType>();
+  const started = new Map<string, number>();
+  const parked = new Set<string>();
+
+  return entry => {
+    const payload = (entry.payload ?? {}) as Record<string, unknown>;
+    const live = entry.at_ms >= liveSinceMs;
+    if (entry.entry_type === 'run.spawned') {
+      if (projection !== undefined) return;
+      const spec = (payload['spec'] ?? {}) as { name?: unknown; steps?: unknown };
+      const steps = (Array.isArray(spec.steps) ? spec.steps : []).flatMap(declaredStep);
+      for (const step of steps) types.set(step.id, step.type);
+      projection = open({ runId: entry.run_id, flow: typeof spec.name === 'string' ? spec.name : 'flow', steps });
+      return;
+    }
+    if (projection === undefined) return;
+    if (entry.entry_type === 'epoch.summary') {
+      started.clear();
+      parked.clear();
+      const done = (payload['steps_done'] ?? {}) as Record<string, { completionReason?: string }>;
+      const pending = (payload['steps_open'] ?? {}) as Record<string, { state?: string; attempt?: number }>;
+      projection.epoch([
+        ...Object.entries(done).map(([id, value]) => ({ id,
+          state: value.completionReason === 'success' ? 'completed' as const : 'failed' as const,
+          completionReason: value.completionReason })),
+        ...Object.entries(pending).map(([id, value]) => ({ id, attempt: value.attempt,
+          state: value.state === 'running' ? 'running' as const : value.state === 'needs_human' ? 'parked' as const : 'pending' as const })),
+      ], live);
+      return;
+    }
+    if (entry.step_id === null && entry.entry_type !== 'run.completed') return;
+    const stepId = entry.step_id ?? '';
+    const stepType = types.get(stepId) ?? 'deterministic';
+    const attempt = entry.attempt ?? undefined;
+    const key = `${stepId}#${attempt ?? 0}`;
+    const event = (type: ProgressEvent['type'], completionReason?: string): void => {
+      const elapsedMs = type === 'step.started' ? 0 : entry.at_ms - (started.get(key) ?? entry.at_ms);
+      projection!.step({
+        type, stepId, stepType, elapsedMs,
+        ...(attempt === undefined ? {} : { attempt }),
+        ...(completionReason === undefined ? {} : { completionReason: completionReason as never }),
+      }, live);
+    };
+    switch (entry.entry_type) {
+      case 'step.attempt.started':
+        parked.delete(key);
+        started.set(key, entry.at_ms);
+        event('step.started');
+        return;
+      case 'wait.human':
+        if (parked.has(key)) return;
+        parked.add(key);
+        event('step.parked');
+        return;
+      case 'step.completed': {
+        const reason = typeof payload['completionReason'] === 'string' ? payload['completionReason'] : undefined;
+        const isParked = payload['disposition'] === 'park';
+        if (isParked && parked.has(key)) return;
+        if (isParked) parked.add(key);
+        event(isParked ? 'step.parked' : reason === 'success' ? 'step.completed' : 'step.failed', reason);
+        return;
+      }
+      case 'run.completed': {
+        // Historical outcomes belong to earlier epochs. The current resume's
+        // report closes the projection if no new terminal entry is appended.
+        if (!live) return;
+        const reason = typeof payload['completionReason'] === 'string' ? payload['completionReason'] : undefined;
+        projection.finish({ status: runStatus(reason), ...(reason === undefined ? {} : { completionReason: reason }) });
+        return;
+      }
+    }
+  };
+}
+
+function declaredStep(value: unknown): DeclaredStep[] {
+  if (typeof value !== 'object' || value === null) return [];
+  const step = value as { id?: unknown; type?: unknown; depends_on?: unknown };
+  if (typeof step.id !== 'string') return [];
+  const type = step.type === 'llm' || step.type === 'agent' ? step.type : 'deterministic';
+  const dependsOn = Array.isArray(step.depends_on)
+    ? step.depends_on.filter((id): id is string => typeof id === 'string') : [];
+  return [{ id: step.id, type, dependsOn }];
+}
+
+function runStatus(reason: string | undefined): RunSnapshot['status'] {
+  if (reason === 'success') return 'completed';
+  if (reason === 'canceled') return 'canceled';
+  return 'failed';
+}

package/src/json-value.ts

@@ -1,4 +1,38 @@
 import { isProxy } from 'node:util/types';
+import { appendIntrinsicArray } from './intrinsic-array.js';
+
+const ARRAY_IS_ARRAY = Array.isArray;
+const ARRAY_PROTOTYPE = Array.prototype;
+const ERROR = Error;
+const IS_PROXY = isProxy;
+const JSON_STRINGIFY = JSON.stringify;
+const NUMBER = Number;
+const NUMBER_IS_FINITE = Number.isFinite;
+const NUMBER_IS_INTEGER = Number.isInteger;
+const OBJECT_CREATE = Object.create;
+const OBJECT_DEFINE_PROPERTY = Object.defineProperty;
+const OBJECT_FREEZE = Object.freeze;
+const OBJECT_GET_OWN_PROPERTY_DESCRIPTOR = Object.getOwnPropertyDescriptor;
+const OBJECT_GET_PROTOTYPE_OF = Object.getPrototypeOf;
+const OBJECT_HAS_OWN = Object.hasOwn;
+const OBJECT_PROTOTYPE = Object.prototype;
+const REGEXP_TEST = Function.prototype.call.bind(RegExp.prototype.test) as (
+  regexp: RegExp, value: string,
+) => boolean;
+const STRING = String;
+const STRING_CHAR_CODE_AT = Function.prototype.call.bind(String.prototype.charCodeAt) as (
+  value: string, index: number,
+) => number;
+const WEAK_SET = WeakSet;
+const WEAK_SET_ADD = Function.prototype.call.bind(WeakSet.prototype.add) as <T extends object>(
+  set: WeakSet<T>, value: T,
+) => WeakSet<T>;
+const WEAK_SET_DELETE = Function.prototype.call.bind(WeakSet.prototype.delete) as <T extends object>(
+  set: WeakSet<T>, value: T,
+) => boolean;
+const WEAK_SET_HAS = Function.prototype.call.bind(WeakSet.prototype.has) as <T extends object>(
+  set: WeakSet<T>, value: T,
+) => boolean;
 
 export type JsonValue =
   | null
@@ -8,15 +42,45 @@ export type JsonValue =
   | JsonValue[]
   | { [key: string]: JsonValue };
 
+export interface JsonSnapshotLimits {
+  readonly maxDepth: number;
+  readonly maxNodes: number;
+  readonly maxBytes: number;
+}
+
+interface SnapshotBudget {
+  readonly limits?: JsonSnapshotLimits;
+  nodes: number;
+  properties: number;
+  bytes: number;
+}
+
 /** Copy runtime input into frozen, behavior-free JSON data. */
-export function snapshotJsonValue(value: unknown, at: string): JsonValue {
-  return snapshot(value, at, new WeakSet<object>());
+export function snapshotJsonValue(value: unknown, at: string, limits?: JsonSnapshotLimits): JsonValue {
+  return snapshot(value, at, new WEAK_SET<object>(), { limits, nodes: 0, properties: 0, bytes: 0 }, 0);
 }
 
-function snapshot(value: unknown, at: string, ancestors: WeakSet<object>): JsonValue {
-  if (value === null || typeof value === 'string' || typeof value === 'boolean') return value;
+function snapshot(
+  value: unknown,
+  at: string,
+  ancestors: WeakSet<object>,
+  budget: SnapshotBudget,
+  depth: number,
+): JsonValue {
+  consumeNode(budget, at, depth);
+  if (typeof value === 'string') {
+    consumeStringBytes(budget, value, at);
+    return value;
+  }
+  if (value === null || typeof value === 'boolean') {
+    consumeBytes(budget, value === null ? 4 : value ? 4 : 5, at);
+    return value;
+  }
   if (typeof value === 'number') {
-    if (Number.isFinite(value)) return value;
+    if (NUMBER_IS_FINITE(value)) {
+      consumeBytes(budget, STRING(value).length, at);
+      return value;
+    }
     throw nonJson(at, 'numbers must be finite');
   }
   if (typeof value !== 'object') {
@@ -25,15 +89,15 @@ function snapshot(value: unknown, at: string, ancestors: WeakSet<object>): JsonV
   // Every ordinary reflective operation on a Proxy can execute author code.
   // Node and Bun expose this trap-free brand check, so reject before touching
   // its prototype, keys, descriptors, or identity collection.
-  if (isProxy(value)) throw nonJson(at, 'Proxy objects are not allowed');
-  if (ancestors.has(value)) throw nonJson(at, 'cycles are not allowed');
-  ancestors.add(value);
+  if (IS_PROXY(value)) throw nonJson(at, 'Proxy objects are not allowed');
+  if (WEAK_SET_HAS(ancestors, value)) throw nonJson(at, 'cycles are not allowed');
+  WEAK_SET_ADD(ancestors, value);
   try {
-    return Array.isArray(value)
-      ? snapshotArray(value, at, ancestors)
-      : snapshotObject(value, at, ancestors);
+    return ARRAY_IS_ARRAY(value)
+      ? snapshotArray(value, at, ancestors, budget, depth)
+      : snapshotObject(value, at, ancestors, budget, depth);
   } finally {
-    ancestors.delete(value);
+    WEAK_SET_DELETE(ancestors, value);
   }
 }
 
@@ -41,53 +105,88 @@ function snapshotArray(
   value: unknown[],
   at: string,
   ancestors: WeakSet<object>,
+  budget: SnapshotBudget,
+  depth: number,
 ): JsonValue[] {
-  const keys = Reflect.ownKeys(value);
-  for (const key of keys) {
-    if (key === 'length') continue;
-    if (typeof key !== 'string' || !isArrayIndex(key, value.length)) {
+  if (OBJECT_GET_PROTOTYPE_OF(value) !== ARRAY_PROTOTYPE
+    || OBJECT_GET_PROTOTYPE_OF(ARRAY_PROTOTYPE) !== OBJECT_PROTOTYPE) {
+    throw nonJson(at, 'only arrays with the intrinsic prototype are allowed');
+  }
+  consumeBytes(budget, 2, at);
+  if (budget.limits !== undefined && value.length > budget.limits.maxNodes - budget.nodes) {
+    throw nonJson(at, 'snapshot depth or node limit exceeded');
+  }
+  // `Reflect.ownKeys` allocates the complete key list before a caller can
+  // enforce cardinality. Enumerate JSON-visible keys one at a time instead.
+  // Symbols and non-enumerable properties are deliberately ignored, matching
+  // JSON.stringify; the copied value has neither, so they cannot affect later
+  // validation or serialization.
+  for (const key in value) {
+    consumeProperty(budget, at);
+    if (!OBJECT_HAS_OWN(value, key)) continue;
+    if (!isArrayIndex(key, value.length)) {
       throw nonJson(at, 'arrays may contain only indexed data');
     }
   }
   const out: JsonValue[] = [];
   for (let index = 0; index < value.length; index += 1) {
-    const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+    if (index > 0) consumeBytes(budget, 1, at);
+    const descriptor = OBJECT_GET_OWN_PROPERTY_DESCRIPTOR(value, STRING(index));
     if (descriptor === undefined) throw nonJson(`${at}[${index}]`, 'array holes are not allowed');
-    out.push(snapshotDescriptor(descriptor, `${at}[${index}]`, ancestors));
+    appendIntrinsicArray(out, snapshotDescriptor(descriptor, `${at}[${index}]`, ancestors, budget, depth + 1));
   }
-  return Object.freeze(out) as unknown as JsonValue[];
+  // JSON.stringify consults `toJSON` before applying array semantics. Shadow
+  // any poisoned Array.prototype hook with inert, non-JSON-visible data while
+  // retaining the intrinsic prototype expected by downstream array consumers.
+  OBJECT_DEFINE_PROPERTY(out, 'toJSON', { value: undefined });
+  return OBJECT_FREEZE(out) as unknown as JsonValue[];
 }
 
 function snapshotObject(
   value: object,
   at: string,
   ancestors: WeakSet<object>,
+  budget: SnapshotBudget,
+  depth: number,
 ): { [key: string]: JsonValue } {
-  const prototype = Object.getPrototypeOf(value);
-  if (prototype !== Object.prototype && prototype !== null) {
+  const prototype = OBJECT_GET_PROTOTYPE_OF(value);
+  if (prototype !== OBJECT_PROTOTYPE && prototype !== null) {
     throw nonJson(at, 'only plain objects are allowed');
   }
-  const out = Object.create(null) as { [key: string]: JsonValue };
-  for (const key of Reflect.ownKeys(value)) {
-    if (typeof key !== 'string') throw nonJson(at, 'symbol keys are not allowed');
+  consumeBytes(budget, 2, at);
+  const out = OBJECT_CREATE(null) as { [key: string]: JsonValue };
+  let included = 0;
+  // Avoid materializing an attacker-sized key array in the unsandboxed
+  // parent. This visits only JSON-visible own string properties; symbols and
+  // non-enumerable properties are omitted exactly as JSON.stringify omits
+  // them, and cannot influence the null-prototype copy.
+  for (const key in value) {
+    consumeProperty(budget, at);
+    if (!OBJECT_HAS_OWN(value, key)) continue;
     const childAt = propertyPath(at, key);
-    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    const descriptor = OBJECT_GET_OWN_PROPERTY_DESCRIPTOR(value, key);
     if (descriptor === undefined) throw nonJson(childAt, 'missing property descriptor');
     const child = descriptorValue(descriptor, childAt);
     // JSON.stringify and the pre-existing compiler omit undefined object
     // optionals. Arrays remain strict because undefined there becomes null.
     if (child === undefined) continue;
-    out[key] = snapshot(child, childAt, ancestors);
+    if (included > 0) consumeBytes(budget, 1, at);
+    consumeStringBytes(budget, key, childAt);
+    consumeBytes(budget, 1, childAt);
+    out[key] = snapshot(child, childAt, ancestors, budget, depth + 1);
+    included += 1;
   }
-  return Object.freeze(out);
+  return OBJECT_FREEZE(out);
 }
 
 function snapshotDescriptor(
   descriptor: PropertyDescriptor,
   at: string,
   ancestors: WeakSet<object>,
+  budget: SnapshotBudget,
+  depth: number,
 ): JsonValue {
-  return snapshot(descriptorValue(descriptor, at), at, ancestors);
+  return snapshot(descriptorValue(descriptor, at), at, ancestors, budget, depth);
 }
 
 function descriptorValue(descriptor: PropertyDescriptor, at: string): unknown {
@@ -97,14 +196,67 @@ function descriptorValue(descriptor: PropertyDescriptor, at: string): unknown {
 }
 
 function isArrayIndex(key: string, length: number): boolean {
-  const index = Number(key);
-  return Number.isInteger(index) && index >= 0 && index < length && String(index) === key;
+  const index = NUMBER(key);
+  return NUMBER_IS_INTEGER(index) && index >= 0 && index < length && STRING(index) === key;
 }
 
 function propertyPath(at: string, key: string): string {
-  return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key) ? `${at}.${key}` : `${at}[${JSON.stringify(key)}]`;
+  if (key.length > 100) return `${at}[long property]`;
+  return REGEXP_TEST(/^[A-Za-z_$][A-Za-z0-9_$]*$/, key)
+    ? `${at}.${key}`
+    : `${at}[${JSON_STRINGIFY(key)}]`;
+}
+
+function consumeNode(budget: SnapshotBudget, at: string, depth: number): void {
+  budget.nodes += 1;
+  if (budget.limits !== undefined
+    && (depth > budget.limits.maxDepth || budget.nodes > budget.limits.maxNodes)) {
+    throw nonJson(at, 'snapshot depth or node limit exceeded');
+  }
+}
+
+function consumeProperty(budget: SnapshotBudget, at: string): void {
+  if (budget.limits === undefined) return;
+  budget.properties += 1;
+  if (budget.properties > budget.limits.maxNodes) {
+    throw nonJson(at, 'snapshot depth or node limit exceeded');
+  }
+}
+
+/** Count JSON's UTF-8 string encoding without allocating the escaped value. */
+function consumeStringBytes(budget: SnapshotBudget, value: string, at: string): void {
+  consumeBytes(budget, 2, at);
+  if (budget.limits !== undefined && value.length > budget.limits.maxBytes - budget.bytes) {
+    throw nonJson(at, 'snapshot byte limit exceeded');
+  }
+  for (let index = 0; index < value.length; index += 1) {
+    const code = STRING_CHAR_CODE_AT(value, index);
+    if (code === 0x22 || code === 0x5c || code === 0x08 || code === 0x09
+      || code === 0x0a || code === 0x0c || code === 0x0d) {
+      consumeBytes(budget, 2, at);
+    } else if (code < 0x20 || (code >= 0xd800 && code <= 0xdfff)) {
+      if (code >= 0xd800 && code <= 0xdbff && index + 1 < value.length) {
+        const low = STRING_CHAR_CODE_AT(value, index + 1);
+        if (low >= 0xdc00 && low <= 0xdfff) {
+          consumeBytes(budget, 4, at);
+          index += 1;
+          continue;
+        }
+      }
+      consumeBytes(budget, 6, at);
+    } else if (code < 0x80) consumeBytes(budget, 1, at);
+    else if (code < 0x800) consumeBytes(budget, 2, at);
+    else consumeBytes(budget, 3, at);
+  }
+}
+
+function consumeBytes(budget: SnapshotBudget, bytes: number, at: string): void {
+  budget.bytes += bytes;
+  if (budget.limits !== undefined && budget.bytes > budget.limits.maxBytes) {
+    throw nonJson(at, 'snapshot byte limit exceeded');
+  }
 }
 
 function nonJson(at: string, detail: string): Error {
-  return new Error(`${at}: expected JSON-compatible data; ${detail}`);
+  return new ERROR(`${at}: expected JSON-compatible data; ${detail}`);
 }

package/src/llm-worker.ts

@@ -46,7 +46,7 @@ export class LlmWorker extends EventEmitter {
 
   private readonly onDispatch = (dispatch: StepDispatchEvent): void => {
     if (this.closing || dispatch.step_type !== 'llm') return;
-    const running = this.execute(dispatch).catch(error => { this.emit('error', error); });
+    const running = this.execute(dispatch).catch(error => { this.emit('error', error, dispatch); });
     this.inFlight.add(running);
     void running.finally(() => { this.inFlight.delete(running); });
   };
@@ -67,7 +67,7 @@ export class LlmWorker extends EventEmitter {
     let detail = result.stderr_tail;
     if (reason === 'success' && schema !== undefined) {
       try {
-        output = JSON.parse(result.stdout_tail);
+        output = JSON.parse(unfenced(result.stdout_tail));
         const invalid = jsonSchemaOutputError(schema, output);
         if (invalid !== undefined) {
           reason = 'verification_failed';
@@ -98,3 +98,17 @@ export class LlmWorker extends EventEmitter {
       });
   }
 }
+
+/**
+ * A reply that is exactly one markdown code fence around a value, reduced to
+ * that value. Models add the fence despite the instruction not to; the schema
+ * still judges what is inside it. A fence opens with three or more backticks
+ * or tildes and closes with a run of the same character at least as long.
+ * Anything else (prose around the JSON, two fences) is returned unchanged and
+ * fails the parse as before.
+ */
+export function unfenced(text: string): string {
+  const fence = /^\s*(?:(`{3,})[^`\n]*\n([\s\S]*?)\n?\1`*|(~{3,})[^\n]*\n([\s\S]*?)\n?\3~*)\s*$/.exec(text);
+  if (fence === null) return text;
+  return fence[2] ?? fence[4]!;
+}

package/src/local-agent.ts

@@ -1,3 +1,4 @@
+import { onWorkerFailure } from './worker-lease.js';
 import { randomUUID } from 'node:crypto';
 import type { JournalClient } from './journal-client.js';
 import { AgentWorker } from './worker.js';
@@ -10,6 +11,7 @@ export async function attachLocalAgent(
   onPtyReady?: (path: string) => void,
   requestedStream?: string,
   capacity: number = DEFAULT_LOCAL_AGENT_CAPACITY,
+  runRoot?: string,
 ): Promise<{
   stream: string;
   readonly failure: unknown;
@@ -24,12 +26,12 @@ export async function attachLocalAgent(
     // second parking behind the first. Authored bodies size their admission to
     // this same number (worker-slots.ts), so they never ask for more.
     capacity,
-    dataDir, onPtyReady,
+    dataDir, onPtyReady, runRoot,
     pins: { workspace: [], streams: [{ stream, read_offset: 0 }] },
   });
   let failure: unknown;
   // The cause travels with the close, so the flow's next request names it.
-  worker.on('error', error => { failure = error; client.close(error); });
+  worker.on('error', onWorkerFailure('local-agent', error => { failure = error; client.close(error); }));
   await worker.attach();
   return {
     stream,

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(),
   };