@relayflows/sdk 2.0.42 → 2.0.43

package/src/cli/cloud-human.ts

@@ -0,0 +1,24 @@
+import { cloudAnswerCommand } from '../authored-human.js';
+import type { CloudHumanWait } from '../cloud-human-wait.js';
+import type { CloudRunState } from '../cloud-run-record.js';
+import { redact } from '../redact.js';
+import { safe } from './cloud-format.js';
+
+export function scrubCloudHumanWait(wait: CloudHumanWait | undefined, env = process.env): CloudHumanWait | undefined {
+  if (!wait) return undefined;
+  return {
+    ...wait,
+    ...(wait.recipient === undefined ? {} : { recipient: { ...wait.recipient, target: safe(redact(wait.recipient.target, env)) } }),
+    ...(wait.question === undefined ? {} : { question: safe(redact(wait.question, env)) }),
+    ...(wait.to === undefined ? {} : { to: safe(redact(wait.to, env)) }),
+  };
+}
+
+export function cloudParkLines(state: Extract<CloudRunState, { status: 'needs_human' }>, env = process.env): string[] {
+  const wait = scrubCloudHumanWait(state.humanWait, env);
+  return [
+    `NEEDS_HUMAN ${state.runId} completionReason: needs_human`,
+    ...(wait ? [`Waiting for ${wait.to ?? '(recipient unavailable)'} to answer ${wait.waitId}: ${JSON.stringify(wait.question ?? '(question unavailable)')}`] : []),
+    `Answer with: ${cloudAnswerCommand(state.runId)}`,
+  ];
+}

package/src/cli/cloud-live.ts

@@ -21,6 +21,7 @@
 // owns for the verb's duration, and nothing here installs a process handler.
 // Aborting stops the observation, not the hosted run — the refusal says so.
 
+import { cloudParkLines } from './cloud-human.js';
 import { canonicalize } from '../canonical.js';
 import {
   getCloudRunDetailLive, getCloudRunLog, getCloudRunSteps,
@@ -56,7 +57,8 @@ function delayFor(failures: number, interval: number): number {
 }
 
 /** The hosted `flows run --wait` mapping: only an attested success is 0. */
-function exitFor(state: CloudRunState): 0 | 1 {
+function exitFor(state: CloudRunState): 0 | 1 | 3 {
+  if (state.status === 'needs_human') return 3;
   return state.status === 'completed' ? 0 : 1;
 }
 
@@ -99,7 +101,7 @@ export async function runCloudStatusWatch(
   args: { runId?: string; json: boolean },
   io: CliIo,
   options: CloudLiveOptions = {},
-): Promise<0 | 1 | 2> {
+): Promise<0 | 1 | 2 | 3> {
   const env = options.env ?? process.env;
   const clock = options.now ?? Date.now;
   const signal = options.signal;
@@ -132,12 +134,15 @@ export async function runCloudStatusWatch(
     }
     failures = 0;
 
-    const run = scrubRun(live.detail, env);
+    const run = scrubRun(live.state.status === 'needs_human'
+      ? { ...live.detail, status: 'needs_human' } : live.detail, env);
     const scrubbed = scrubSteps(steps, env);
     const terminal = !isCloudRunActive(live.state.status);
     // Rendered before the abort check and emitted after it, in one call: an
     // interrupt between two lines of a frame would leave a torn page.
-    const page = args.json ? '' : `${clearSequence(io)}${renderCloudStatus(run, scrubbed, clock()).join('\n')}`;
+    const lines = renderCloudStatus(run, scrubbed, clock());
+    if (live.state.status === 'needs_human') lines.push(...cloudParkLines(live.state, env));
+    const page = args.json ? '' : `${clearSequence(io)}${lines.join('\n')}`;
     if (isAborted(signal)) return aborted('watching', runId, args.json, io);
     if (!args.json) io.stdout(page);
     if (terminal) {
@@ -265,7 +270,7 @@ export async function runCloudLogsFollow(
   args: { runId: string; step: string | undefined; json: boolean },
   io: CliIo,
   options: CloudLiveOptions = {},
-): Promise<0 | 1 | 2> {
+): Promise<0 | 1 | 2 | 3> {
   const env = options.env ?? process.env;
   const signal = options.signal;
   const interval = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;

package/src/cli/cloud-mirror-session.ts

@@ -25,7 +25,7 @@
 import { readFile } from 'node:fs/promises';
 import type { CliIo } from '../cli.js';
 import { canonicalize } from '../canonical.js';
-import { cloudConnection, CloudFlowError } from '../cloud-http.js';
+import { resolveCloudConnection, CloudFlowError } from '../cloud-http.js';
 import { recordMirroredRun, readMirroredRun } from '../cloud-mirror-ledger.js';
 import { createRunMirror, readJournalEvents, type RunMirror } from '../cloud-mirror.js';
 import { MirrorClient, registerLocalRun, type MirrorRunSource } from '../cloud-mirror-transport.js';
@@ -231,7 +231,8 @@ export function mirrorSourceFromJournal(dataDir: string): (runId: string) => Pro
     // the deployment this invocation will actually register with, so a run
     // mirrored to staging never claims to continue an id that means something
     // else in production.
-    const resumedFromRunId = await readMirroredRun(dataDir, runId, cloudConnection({}).baseUrl)
+    const { baseUrl } = await resolveCloudConnection({});
+    const resumedFromRunId = await readMirroredRun(dataDir, runId, baseUrl)
       .catch(() => undefined);
     // Through the retrying reader: a resume reads this journal while the
     // daemon is writing to it, and a single `journal_busy` used to abandon

package/src/cli/cloud-run.ts

@@ -1,3 +1,5 @@
+import { cloudAnswerCommand } from '../authored-human.js';
+import { scrubCloudHumanWait, cloudParkLines } from './cloud-human.js';
 import { CloudFlowError } from '../cloud-http.js';
 import { runInCloud, waitForCloudFlowRun, type RunInCloudOptions } from '../cloud-run.js';
 import { DirectInputError, isAuthoredFlowPath, parseDirectInput } from '../direct-input.js';
@@ -17,7 +19,7 @@ export async function runCloudCli(
    * handler is installed here.
    */
   signal: AbortSignal,
-): Promise<0 | 1 | 2> {
+): Promise<0 | 1 | 2 | 3> {
   let runId: string | undefined;
   // Flips at the run submission. An interruption before it — during prepare,
   // packing or upload — admitted nothing and is safe to retry; only an
@@ -65,6 +67,13 @@ export async function runCloudCli(
       return 0;
     }
     const run = await waitForCloudFlowRun(receipt.runId, { signal });
+    if (run.status === 'needs_human') {
+      const humanWait = scrubCloudHumanWait(run.humanWait);
+      const next = cloudAnswerCommand(run.runId);
+      if (json) io.stdout(JSON.stringify({ ok: false, ...receipt, ...run, humanWait, next }));
+      else for (const line of cloudParkLines(run)) io.stdout(line);
+      return 3;
+    }
     const ok = run.status === 'completed';
     if (json) io.stdout(JSON.stringify({ ok, ...receipt, ...run }));
     else io.stdout(`${run.status.toUpperCase()} ${run.runId} completionReason: ${'completionReason' in run ? run.completionReason : 'unavailable'}`);

package/src/cli/detached-record.ts

@@ -0,0 +1,71 @@
+import { readFileSync, renameSync, writeFileSync } from 'node:fs';
+import type { RunExecution } from './run.js';
+
+export const DETACH_RECORD_ENV = 'FLOWS_DETACH_RECORD';
+
+/** A receipt/index, never run state: the journal remains authoritative. */
+export interface DetachedRecord {
+  phase: 'started' | 'finished' | 'refused';
+  pid: number;
+  runId?: string;
+  observerUrl?: string;
+  execution?: RunExecution;
+}
+
+export function readDetachedRecord(path: string): DetachedRecord | undefined {
+  let text: string;
+  try { text = readFileSync(path, 'utf8'); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined;
+    throw error;
+  }
+  const record = JSON.parse(text) as DetachedRecord;
+  if (!['started', 'finished', 'refused'].includes(record.phase)
+    || !Number.isSafeInteger(record.pid) || record.pid <= 0
+    || (record.phase === 'started' && typeof record.runId !== 'string')
+    || (record.phase !== 'started' && record.execution === undefined)) {
+    throw new Error('Invalid detached receipt');
+  }
+  return record;
+}
+
+export interface DetachedReceipt {
+  /** The daemon admitted the run: the only signal that makes a detach succeed. */
+  started(run: { runId: string }): void;
+  observerUrl(url: string): void;
+  finished(execution: RunExecution): void;
+}
+
+/** Only the standalone child consumes this marker, before authored code loads. */
+export function takeDetachedReceipt(env: NodeJS.ProcessEnv = process.env): DetachedReceipt | undefined {
+  const path = env[DETACH_RECORD_ENV];
+  delete env[DETACH_RECORD_ENV];
+  if (path === undefined) return undefined;
+  let runId: string | undefined;
+  let observerUrl: string | undefined;
+  let execution: RunExecution | undefined;
+  const publish = (): void => {
+    const record: DetachedRecord = {
+      pid: process.pid,
+      // Never admitted means the parent reports this execution as-is.
+      phase: execution === undefined ? 'started' : runId === undefined ? 'refused' : 'finished',
+      ...(runId === undefined ? {} : { runId }),
+      ...(observerUrl === undefined ? {} : { observerUrl }),
+      ...(execution === undefined ? {} : { execution }),
+    };
+    if (runId === undefined && execution === undefined) return;
+    const temporary = `${path}.${process.pid}.tmp`;
+    writeFileSync(temporary, JSON.stringify(record), { mode: 0o600 });
+    renameSync(temporary, path);
+  };
+  return {
+    started(run) { runId ??= run.runId; publish(); },
+    observerUrl(url) { observerUrl = url; publish(); },
+    finished(result) {
+      // Admission is explicit. A failure report can name the requested run
+      // (e.g. resume's pre-admission source check) without having admitted it.
+      execution = result;
+      publish();
+    },
+  };
+}

package/src/cli/detached-run.ts

@@ -0,0 +1,131 @@
+import { spawn } from 'node:child_process';
+import { closeSync, mkdirSync, mkdtempSync, openSync, readSync, fstatSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { setTimeout as sleep } from 'node:timers/promises';
+import type { CliIo } from '../cli.js';
+import { LOCAL_AGENT_ENV_FD } from '../local-agent-environment.js';
+import { shellWord } from '../shell-word.js';
+import { DETACH_RECORD_ENV, readDetachedRecord } from './detached-record.js';
+import type { RunExecution } from './run.js';
+
+// Preflight may compile authored code or fetch a bundle; it runs only in the child.
+export const DETACHED_START_TIMEOUT_MS = 60_000;
+// Observation is optional. Never wait for it for the duration of the run.
+export const DETACHED_OBSERVER_GRACE_MS = 2_000;
+const POLL_MS = 50;
+
+export interface DetachedHandle {
+  detached: true;
+  runId: string;
+  pid: number;
+  logPath: string;
+  recordPath: string;
+  observerUrl?: string;
+  follow: string;
+  notice: string;
+}
+
+export type DetachedResult = { handle: DetachedHandle } | { execution: RunExecution };
+
+export function detachedArgv(args: readonly string[]): string[] {
+  return args.filter(argument => argument !== '--detach');
+}
+
+export async function startDetachedRun(
+  args: readonly string[],
+  options: { command: 'run' | 'resume'; dataDir: string; noObserverLink: boolean; selfCommand?: readonly string[] },
+): Promise<DetachedResult> {
+  const failure = (message: string, refusal = false): DetachedResult => ({ execution: {
+    exitCode: refusal ? 2 : 1,
+    report: { ok: false, command: options.command, resolutions: [], diagnostics: [refusal
+      ? { severity: 'refusal', kind: 'invalid_invocation', message }
+      : { severity: 'failure', kind: 'protocol_error', message }] },
+  } });
+  // This descriptor is deliberately not inherited. Silently losing its provider
+  // credentials would admit a run that cannot execute its steps.
+  if (process.env[LOCAL_AGENT_ENV_FD] !== undefined) {
+    return failure(`detach_environment_fd_unsupported: --detach cannot forward ${LOCAL_AGENT_ENV_FD}; use foreground execution.`, true);
+  }
+  let logPath: string | undefined;
+  let child: ReturnType<typeof spawn> | undefined;
+  try {
+    const directory = join(resolve(options.dataDir), 'detached');
+    mkdirSync(directory, { recursive: true, mode: 0o700 });
+    const handleDir = mkdtempSync(join(directory, 'run-'));
+    logPath = join(handleDir, 'run.log');
+    const recordPath = join(handleDir, 'record.json');
+    const log = openSync(logPath, 'a', 0o600);
+    let spawnError: Error | undefined;
+    let exited = false;
+    try {
+      const [executable, ...prefix] = options.selfCommand ?? defaultSelfCommand();
+      child = spawn(executable!, [...prefix, ...detachedArgv(args)], {
+        detached: true, stdio: ['ignore', log, log], cwd: process.cwd(),
+        env: { ...process.env, [DETACH_RECORD_ENV]: recordPath },
+      });
+      child.once('error', error => { spawnError = error; });
+      child.once('exit', () => { exited = true; });
+      child.unref();
+    } finally { closeSync(log); }
+    const deadline = Date.now() + DETACHED_START_TIMEOUT_MS;
+    let observerDeadline: number | undefined;
+    for (;;) {
+      const record = readDetachedRecord(recordPath);
+      if (record?.phase === 'refused') return { execution: record.execution! };
+      if (record?.runId !== undefined) {
+        observerDeadline ??= Date.now() + DETACHED_OBSERVER_GRACE_MS;
+        if (options.noObserverLink || record.observerUrl !== undefined
+          || exited || Date.now() >= observerDeadline) {
+          return { handle: {
+            detached: true, runId: record.runId, pid: record.pid, logPath, recordPath,
+            ...(record.observerUrl === undefined ? {} : { observerUrl: record.observerUrl }),
+            follow: `flows status ${shellWord(record.runId)} --data-dir ${shellWord(resolve(options.dataDir))}`,
+            notice: 'Started in background; the run may later fail or park. Check status and the log for any park remedy.',
+          } };
+        }
+      } else if (spawnError !== undefined || exited) {
+        return failure(`detached_start_failed: ${spawnError?.message ?? 'child exited before publishing a run id'}. Log: ${logPath}\n${logTail(logPath)}`);
+      } else if (Date.now() >= deadline) {
+        // Signal only this child, never a pre-existing daemon. The agent reaper
+        // owns provider-tree cleanup. A timeout is not a run cancellation.
+        child.kill('SIGTERM');
+        return failure(`detached_start_timeout: no receipt within ${DETACHED_START_TIMEOUT_MS}ms; sent SIGTERM to child. Inspect ${logPath} before retrying; a journal may already exist.\n${logTail(logPath)}`);
+      }
+      await sleep(POLL_MS);
+    }
+  } catch (error) {
+    child?.kill('SIGTERM');
+    return failure(`detached_start_failed: ${error instanceof Error ? error.message : String(error)}${logPath === undefined ? '' : `. Log: ${logPath}`}`);
+  }
+}
+
+/**
+ * cli-watch.ts's re-exec precedent supports both source and built entries. A
+ * compiled executable is its own entry: its module path is virtual and would
+ * reach the CLI as an extra positional, so it passes `selfCommand` instead.
+ */
+function defaultSelfCommand(): string[] {
+  const entry = fileURLToPath(new URL(import.meta.url.endsWith('.ts') ? '../cli.ts' : '../cli.js', import.meta.url));
+  return [process.execPath, ...process.execArgv, entry];
+}
+
+export function emitDetachedHandle(handle: DetachedHandle, json: boolean, io: CliIo): void {
+  if (json) { io.stdout(JSON.stringify(handle)); return; }
+  io.stdout(`DETACHED ${handle.runId}  pid ${handle.pid}`);
+  io.stdout(`Log: ${handle.logPath}`);
+  io.stdout(`Receipt: ${handle.recordPath}`);
+  if (handle.observerUrl !== undefined) io.stdout(`Observer: ${handle.observerUrl}`);
+  io.stdout(`Follow: ${handle.follow}`);
+  io.stdout(handle.notice);
+}
+
+function logTail(path: string): string {
+  const fd = openSync(path, 'r');
+  try {
+    const size = fstatSync(fd).size;
+    const buffer = Buffer.alloc(Math.min(size, 4096));
+    const count = readSync(fd, buffer, 0, buffer.length, Math.max(0, size - buffer.length));
+    return buffer.subarray(0, count).toString('utf8');
+  } finally { closeSync(fd); }
+}

package/src/cli/diagnostic-fold.ts

@@ -0,0 +1,28 @@
+export interface FoldOptions {
+  /** Collapse repeated warnings only when the caller opts in. */
+  fold?: boolean;
+  explain?: boolean;
+  /** Every step in the spec, including llm and agent steps. */
+  totalSteps?: number;
+}
+
+/** Presentation only: retain the original diagnostics for machine consumers. */
+export function foldUnprovableEffects<D extends {
+  severity: string; kind: string; message: string; stepId?: string;
+}>(diagnostics: readonly D[], options: FoldOptions = {}): readonly (D | {
+  severity: 'warning'; kind: 'unprovable_effects'; message: string;
+})[] {
+  if (options.fold !== true || options.explain) return diagnostics;
+  const warnings = diagnostics.filter(d => d.kind === 'unprovable_effects');
+  const count = new Set(warnings.flatMap(d => d.stepId === undefined ? [] : [d.stepId])).size
+    + warnings.filter(d => d.stepId === undefined).length;
+  if (count < 2) return diagnostics;
+  const denominator = options.totalSteps === undefined ? '' : ` of ${options.totalSteps}`;
+  return [
+    ...diagnostics.filter(d => d.kind !== 'unprovable_effects'),
+    {
+      severity: 'warning', kind: 'unprovable_effects',
+      message: `${count}${denominator} steps have effects that cannot be proven before execution (rerun with --explain-warnings to list them).`,
+    },
+  ];
+}

package/src/cli/direct-run.ts

@@ -1,3 +1,5 @@
+import { completedResultUnreadableReport, daemonUnresponsiveReport, isReadInterruption } from './journal-timeout.js';
+import { FLOW_READ_BUDGET_MS } from '../journal-read-policy.js';
 import { onWorkerFailure } from '../worker-lease.js';
 import { McpStepError } from '../authored-mcp.js';
 import { randomUUID } from 'node:crypto';
@@ -25,6 +27,7 @@ import {
   connect,
   emptyReport,
   fromCheckReport,
+  memoryWriteFailure,
   protocolFailure,
   suspendedExecution,
   socketFor,
@@ -67,7 +70,8 @@ export async function runDirectFlow(
   }
   const socketPath = socketFor(dataDir);
   const base: RunReport = { ...emptyReport('run'), path };
-  const client = new JournalClient(socketPath);
+  const client = new JournalClient(socketPath, { readBudgetMs: FLOW_READ_BUDGET_MS,
+    ...(options.signal === undefined ? {} : { readSignal: options.signal }) });
   const connected = await connect(client, 'run', dataDir, base, options);
   if (connected !== undefined) return connected;
 
@@ -105,6 +109,7 @@ export async function runDirectFlow(
         lifecycle: {
           onProgress: options.onProgress,
           ...(options.onRunStarted !== undefined ? { onRunStarted: options.onRunStarted } : {}),
+          ...(options.onRunReceipt !== undefined ? { onRunReceipt: options.onRunReceipt } : {}),
           ...(options.signal !== undefined ? { signal: options.signal } : {}),
           ...(options.onWait !== undefined ? { onWait: options.onWait } : {}),
         },
@@ -212,6 +217,14 @@ export async function runDirectFlow(
     if (error instanceof AuthoredFlowExecutionError && (error.code === 'step_failed' || error.code === 'gate_failed')) {
       return authoredStepFailure('run', base, socketPath, error);
     }
+    if (error instanceof AuthoredFlowExecutionError && error.code === 'result_unreadable') {
+      return completedResultUnreadableReport('run', base, socketPath, error);
+    }
+    if (error instanceof AuthoredFlowExecutionError) {
+      const memoryFailure = memoryWriteFailure('run', base, socketPath, error, base.rootRunId);
+      if (memoryFailure !== undefined) return memoryFailure;
+    }
+    if (isReadInterruption(error)) return daemonUnresponsiveReport('run', base, socketPath, error, base.rootRunId, options, dataDir);
     if (error instanceof AuthoredFlowExecutionError && error.code === 'root_lease_lost') {
       return rootLeaseLostReport('run', base, socketPath, error);
     }

package/src/cli/eval.ts

@@ -0,0 +1,141 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import type { CliIo } from '../cli.js';
+import { CloudFlowError } from '../cloud-http.js';
+import {
+  evaluateFlow, FlowEvalError, loadFlowEvalSuite,
+  type FlowEvalExecutor, type FlowEvalReport,
+} from '../flow-eval.js';
+import { cloudFlowEvalExecutor } from '../flow-eval-cloud.js';
+import { localFlowEvalExecutor } from '../flow-eval-local.js';
+
+export interface EvalArgs {
+  command: 'eval';
+  value: string;
+  cases: string;
+  json: boolean;
+  cloud: boolean;
+  dataDir: string;
+  localAgent: boolean;
+  concurrency?: number;
+  report?: string;
+  baseline?: string;
+  expectVersion?: string;
+}
+
+export function parseEvalArgs(args: readonly string[]): EvalArgs | undefined {
+  const flags = new Set<string>();
+  const values = new Map<string, string>();
+  const positionals: string[] = [];
+  const valued = ['--cases', '--data-dir', '--concurrency', '--report', '--baseline', '--expect-version'];
+  for (let index = 0; index < args.length; index += 1) {
+    const argument = args[index]!;
+    if (argument === '--json' || argument === '--cloud' || argument === '--local-agent') {
+      if (flags.has(argument)) return undefined;
+      flags.add(argument);
+    } else if (valued.includes(argument)) {
+      const value = args[++index];
+      if (value === undefined || value.length === 0 || value.startsWith('-') || values.has(argument)) return undefined;
+      values.set(argument, value);
+    } else if (argument.startsWith('-')) {
+      return undefined;
+    } else {
+      positionals.push(argument);
+    }
+  }
+  const cases = values.get('--cases');
+  if (positionals.length !== 1 || cases === undefined) return undefined;
+  // Local-only options have no meaning against Cloud; refuse rather than ignore.
+  if (flags.has('--cloud') && (flags.has('--local-agent') || values.has('--data-dir'))) return undefined;
+  let concurrency: number | undefined;
+  if (values.has('--concurrency')) {
+    concurrency = Number(values.get('--concurrency'));
+    if (!Number.isSafeInteger(concurrency) || concurrency < 1 || concurrency > 64) return undefined;
+  }
+  return {
+    command: 'eval',
+    value: positionals[0]!,
+    cases,
+    json: flags.has('--json'),
+    cloud: flags.has('--cloud'),
+    localAgent: flags.has('--local-agent'),
+    dataDir: values.get('--data-dir') ?? '.relayflowd',
+    ...(concurrency === undefined ? {} : { concurrency }),
+    ...(values.has('--report') ? { report: values.get('--report')! } : {}),
+    ...(values.has('--baseline') ? { baseline: values.get('--baseline')! } : {}),
+    ...(values.has('--expect-version') ? { expectVersion: values.get('--expect-version')! } : {}),
+  };
+}
+
+/**
+ * `flows eval`: re-execute the flow against every case and print the report.
+ * Exit 0 when the gate passes, 1 when it fails, 2 when the evaluation was refused.
+ */
+export async function runEvalCli(
+  args: EvalArgs,
+  io: CliIo,
+  signal: AbortSignal,
+  executor?: FlowEvalExecutor,
+): Promise<0 | 1 | 2> {
+  let report: FlowEvalReport;
+  try {
+    const suite = await loadFlowEvalSuite(args.cases);
+    let baseline: unknown;
+    if (args.baseline !== undefined) {
+      try {
+        baseline = JSON.parse(await readFile(args.baseline, 'utf8'));
+      } catch {
+        throw new FlowEvalError('invalid_baseline', `Baseline report "${args.baseline}" is not readable JSON.`);
+      }
+    }
+    report = await evaluateFlow({
+      flow: { path: args.value },
+      suite,
+      executor: executor ?? (args.cloud
+        ? cloudFlowEvalExecutor({ signal })
+        : localFlowEvalExecutor({ dataDir: args.dataDir, localAgent: args.localAgent })),
+      executorName: executor !== undefined ? 'custom' : args.cloud ? 'cloud' : 'local',
+      signal,
+      ...(args.concurrency === undefined ? {} : { concurrency: args.concurrency }),
+      ...(args.expectVersion === undefined ? {} : { expectVersion: args.expectVersion }),
+      ...(baseline === undefined ? {} : { baseline }),
+    });
+  } catch (error) {
+    if (signal.aborted) {
+      io.stderr('CANCELED evaluation interrupted; runs already started are not stopped by this command.');
+      return 2;
+    }
+    const kind = error instanceof FlowEvalError || error instanceof CloudFlowError ? error.code : 'eval_failed';
+    const message = error instanceof Error ? error.message : String(error);
+    return refuse(args, io, kind, message);
+  }
+  if (args.report !== undefined) {
+    try {
+      await writeFile(args.report, `${JSON.stringify(report, null, 2)}\n`);
+    } catch {
+      return refuse(args, io, 'report_unwritable', `Could not write the report to "${args.report}".`);
+    }
+  }
+  if (args.json) {
+    io.stdout(JSON.stringify(report));
+  } else {
+    for (const result of report.cases) {
+      const cost = result.costUsd === null ? 'cost=?' : `cost=$${result.costUsd}`;
+      io.stdout(`${result.outcome.toUpperCase()} ${result.id} latency=${result.latencyMs}ms ${cost}`
+        + (result.runId === undefined ? '' : ` run=${result.runId}`));
+      for (const failure of result.failures) io.stdout(`  - ${failure}`);
+    }
+    const { summary } = report;
+    io.stdout(`${summary.passed}/${summary.total} passed, ${summary.failed} failed, ${summary.errored} errored; `
+      + `p50=${summary.latencyMs.p50}ms p95=${summary.latencyMs.p95}ms `
+      + `cost=${summary.totalCostUsd === null ? '?' : `$${summary.totalCostUsd}`}`);
+    io.stdout(`flow ${report.flow.version} suite ${report.suite.sha256}`);
+    io.stdout(report.gate.pass ? 'GATE PASS' : `GATE FAIL: ${report.gate.reasons.join('; ')}`);
+  }
+  return report.gate.pass ? 0 : 1;
+}
+
+function refuse(args: EvalArgs, io: CliIo, kind: string, message: string): 2 {
+  if (args.json) io.stdout(JSON.stringify({ ok: false, diagnostics: [{ severity: 'refusal', kind, message }] }));
+  else io.stderr(`REFUSED [${kind}] ${message}`);
+  return 2;
+}

package/src/cli/journal-timeout.ts

@@ -0,0 +1,49 @@
+import { probeSocket } from '../daemon-connection.js';
+import { AuthoredFlowExecutionError } from '../authored-flow-error.js';
+import { resumeCommand } from '../authored-human.js';
+import { isReadInterruptionError, JournalReadInterruptedError } from '../journal-read-policy.js';
+import type { CheckReport } from './check.js';
+import type { RunExecution, RunReport, RunLifecycleOptions, RunCommand } from './run.js';
+
+export function isReadInterruption(error: unknown): boolean {
+  return isReadInterruptionError(error)
+    || (error instanceof AuthoredFlowExecutionError && error.code === 'daemon_unresponsive');
+}
+
+/**
+ * A completed run whose stored result could not be read back. The run is
+ * finished — nothing to resume — but its authored verdict is unknown, so the
+ * report claims neither success nor a reason, and says how to read it later.
+ */
+export function completedResultUnreadableReport(command: RunCommand, base: CheckReport | RunReport,
+  socketPath: string, error: AuthoredFlowExecutionError): RunExecution {
+  const runId = error.rootRunId ?? error.runId;
+  return { exitCode: 1, report: {
+    ...base, command, ok: false, socketPath, status: 'completed',
+    ...(runId === undefined ? {} : { runId, rootRunId: runId }),
+    diagnostics: [...base.diagnostics, { severity: 'warning', kind: 'result_unreadable',
+      message: `${error.message}. The run is finished; its verdict is unconfirmed`
+        + (runId === undefined ? '.' : ` — read it with \`flows status ${runId}\` once relayflowd answers.`) }],
+  } as RunExecution['report'] };
+}
+
+export async function daemonUnresponsiveReport(command: RunCommand,
+  base: CheckReport | RunReport, socketPath: string, error: unknown, fallbackRunId?: string,
+  options: RunLifecycleOptions = {}, dataDir?: string): Promise<RunExecution> {
+  const runId = error instanceof AuthoredFlowExecutionError ? error.rootRunId ?? fallbackRunId : fallbackRunId;
+  const reachable = (await probeSocket(socketPath)).reachable;
+  const kind = reachable ? 'daemon_unresponsive' : 'daemon_unreachable';
+  const detail = error instanceof JournalReadInterruptedError
+    ? (reachable ? 'relayflowd answers a fresh connection but the run read session kept being interrupted.'
+      : 'relayflowd did not answer a fresh connection after the run read session was interrupted; it may be unreachable or delayed by CPU load.')
+    : reachable ? 'relayflowd answers a fresh connection but the run read timed out; CPU load may be delaying it.'
+    : 'relayflowd did not answer a fresh connection; it may be unreachable or delayed by CPU load.';
+  return { exitCode: 1, report: {
+    ...base, command, ok: false, socketPath, status: 'running',
+    ...(runId === undefined ? {} : { runId, rootRunId: runId }),
+    diagnostics: [...base.diagnostics, { severity: 'failure', kind,
+      message: `${detail} ${error instanceof Error ? error.message : String(error)}`
+        + (runId === undefined ? '' : ` The run remains resumable. Continue with: ${resumeCommand(runId, dataDir ?? options.dataDir, options.localAgent === true)}.`),
+    }],
+  } };
+}

package/src/cli/local-agent-remedy.ts

@@ -66,6 +66,8 @@ export function authoredInput(argument: string | undefined): AuthoredInput {
  */
 const PINS = 'Declared workspace or stream surfaces require a worker that holds their pins.';
 
+const DETACH = ' --local-agent binds the worker to this terminal. Add --detach to run in the background.';
+
 /**
  * The remedy clause appended to a worker-park diagnostic, with a leading
  * space, or `''` when there is nothing to add.
@@ -82,11 +84,11 @@ export function localAgentRemedy(remedy: LocalAgentRemedy): string {
         + ` ${PINS} The local agent worker holds only its own stream.`;
     case 'spec-run':
       return ` To start a new run with a local agent worker: ${
-        newRunCommand(remedy.path, undefined, remedy.dataDir)}. ${PINS}`;
+        newRunCommand(remedy.path, undefined, remedy.dataDir)}. ${PINS}${DETACH}`;
     case 'spec-resume':
       // This run is resumable, so the remedy is this run — not a new one.
       return ` To continue this run with a local agent worker: ${
-        resumeCommand(remedy.runId, remedy.dataDir, true)}. ${PINS}`;
+        resumeCommand(remedy.runId, remedy.dataDir, true)}. ${PINS}${DETACH}`;
     case 'authored-run':
       return authoredRunRemedy(remedy);
   }
@@ -103,7 +105,7 @@ export function localAgentRemedy(remedy: LocalAgentRemedy): string {
 function authoredRunRemedy(remedy: Extract<LocalAgentRemedy, { kind: 'authored-run' }>): string {
   if (remedy.input.kind === 'inline') {
     return ` To start a new run with a local agent worker: ${
-      newRunCommand(remedy.path, remedy.input.argument, remedy.dataDir)}. ${PINS}`;
+      newRunCommand(remedy.path, remedy.input.argument, remedy.dataDir)}. ${PINS}${DETACH}`;
   }
   const requirement = ' A local agent worker is admitted at run start, so this run needs a new one.'
     + ` Starting one needs --local-agent, the flow path ${shellQuote(remedy.path)}, and the same`
@@ -115,7 +117,7 @@ function authoredRunRemedy(remedy: Extract<LocalAgentRemedy, { kind: 'authored-r
     // printed `--input '<json>'` would fail before the CLI ran at all.
     : `the journal recorded ${remedy.input.bytes} bytes of input, more than a shell`
       + ' can carry in one argument, so pass the input file this run was started from.')
-    + ` ${PINS}`;
+    + ` ${PINS}${DETACH}`;
 }
 
 /**

package/src/cli/observer-session.ts

@@ -36,6 +36,7 @@ export interface ObserverSession {
 }
 
 export interface ObserverSessionDeps {
+  onObserverUrl?: (url: string) => void;
   fetch?: ProjectionFetch;
   mint?: (options: MintObserverOptions) => Promise<MintOutcome>;
 }
@@ -72,7 +73,12 @@ export function createObserverSession(
       diagnostic: message => io.stderr(`[observer] ${message}`),
     }, run);
     void mintFor(run.runId).then(outcome => {
-      if (outcome.observerUrl !== undefined) io.stderr(`Observer: ${outcome.observerUrl}`);
+      if (outcome.observerUrl !== undefined) {
+        io.stderr(`Observer: ${outcome.observerUrl}`);
+        try { deps.onObserverUrl?.(outcome.observerUrl); } catch (error) {
+          io.stderr(`[observer] could not publish observer URL: ${error instanceof Error ? error.message : String(error)}`);
+        }
+      }
     });
     return projection;
   };