@relayflows/sdk 2.0.41 → 2.0.43

package/src/cli/reuse.ts

@@ -1,4 +1,5 @@
 import type { JournalClient } from '../journal-client.js';
+import type { RunExecution } from './run.js';
 
 /** Count durable facts, including failed executions, across paginated reads. */
 export async function reuseSummary(client: JournalClient, runId: string, fromRunId: string): Promise<{
@@ -21,3 +22,27 @@ export async function reuseSummary(client: JournalClient, runId: string, fromRun
   }
   return { fromRunId, reusedSteps: reused.size, executedSteps: executed.size };
 }
+
+/**
+ * Add the reuse summary to an already classified run. The summary is an extra
+ * journal read after the outcome is known: if it cannot be answered, report
+ * that as a warning and keep the classified outcome rather than recasting a
+ * finished run as resumable or failed.
+ */
+export async function attachReuseSummary(execution: RunExecution, client: JournalClient,
+  runId: string, fromRunId: string): Promise<RunExecution> {
+  // Classification already ended on an unanswered read: the run is resumable and
+  // another read would only spend a fresh budget against the same delayed daemon.
+  if (execution.report.diagnostics.some(diagnostic => diagnostic.kind === 'daemon_unresponsive'
+    || diagnostic.kind === 'daemon_unreachable' || diagnostic.kind === 'inspection_interrupted')) return execution;
+  try {
+    execution.report.reuse = await reuseSummary(client, runId, fromRunId);
+  } catch (error) {
+    // Optional detail after the outcome is decided: no failure here — an
+    // interruption, a cancellation, a bad frame — may replace that outcome.
+    const why = error instanceof Error ? error.message : String(error);
+    execution.report.diagnostics = [...execution.report.diagnostics, { severity: 'warning', kind: 'reuse_summary_unavailable',
+      message: `The run's outcome is final, but the summary of steps reused from ${fromRunId} could not be read: ${why}` }];
+  }
+  return execution;
+}

package/src/cli/run.ts

@@ -1,10 +1,14 @@
+import { waitForRunningStep, type RunningStep } from './running-step.js';
+export { LEASE_SWEEP_GRACE_MS } from './running-step.js';
+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 { communicationInstruction } from '../communication/spec.js';
 import { checkCommunicationEnvironment, CommunicationEnvironmentError } from '../communication/preflight.js';
 import { parseHumanRecipient } from '../human-to.js';
 import { parseDigestReference } from '../bundle-transport.js';
 import { prepareDigestRun } from './run-digest.js';
-import { reuseSummary } from './reuse.js';
+import { attachReuseSummary } from './reuse.js';
 import { resumeHelperEffect } from '../authored-helper-effect.js';
 import { AuthoredFlowExecutionError, AuthoredHumanParked, type AuthoredHumanWait } from '../authored-flow-error.js';
 import { answerCommand, resumeCommand } from '../authored-human.js';
@@ -149,7 +153,7 @@ export interface RunLifecycleOptions {
   onJournalEntry?: (entry: JournalEvent) => void;
   /** An authored root was admitted: its id is known before its body runs. */
   onRunStarted?: (run: { runId: string; flow: string; resumed?: boolean }) => void;
-  /** A declarative root returned its admission receipt, even if no watched entry arrived. */
+  /** The daemon admitted a root (declarative or authored, even an already completed one). */
   onRunReceipt?: (run: { runId: string; flow: string }) => void;
   localAgent?: boolean;
   /** `--agent-capacity`: the local workers' concurrency; the default is `DEFAULT_LOCAL_AGENT_CAPACITY`. */
@@ -203,7 +207,8 @@ async function executeCheckedFlow(
     catch (error) { return { exitCode: 2, report: { ...base, diagnostics: [...base.diagnostics,
       { severity: 'refusal', kind: 'probe_failed', message: error instanceof Error ? error.message : 'Communication environment could not be checked.' }] } }; }
   }
-  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;
 
@@ -225,6 +230,7 @@ async function executeCheckedFlow(
     }
     if (options.onJournalEntry !== undefined) client.on('entry', options.onJournalEntry);
     const outcome = await startWatched(client, spec, options);
+    base.runId = outcome.run_id;
     // `run.start { watch: true }` is an event stream, not the source of the
     // root identity. A short deterministic run can finish before its first
     // watched entry is delivered (and an older daemon may refuse `watch`), so
@@ -234,11 +240,10 @@ async function executeCheckedFlow(
     // truthful "not projected" diagnostic.
     options.onRunReceipt?.({ runId: outcome.run_id, flow: spec.name ?? 'flow' });
     const execution = await classifyOutcome(client, 'run', outcome, base, socketPath, { ...options, dataDir });
-    if (options.reuseFromRunId !== undefined) {
-      execution.report.reuse = await reuseSummary(client, outcome.run_id, options.reuseFromRunId);
-    }
-    return execution;
+    return options.reuseFromRunId === undefined ? execution
+      : await attachReuseSummary(execution, client, outcome.run_id, options.reuseFromRunId);
   } catch (error) {
+    if (isReadInterruption(error)) return daemonUnresponsiveReport('run', base, socketPath, error, base.runId, options, dataDir);
     if (error instanceof CommunicationEnvironmentError) return { exitCode: 2, report: { ...base,
       diagnostics: [...base.diagnostics, { severity: 'refusal', kind: 'probe_failed', message: error.message }] } };
     if (error instanceof JournalProtocolError && (
@@ -289,7 +294,8 @@ export async function resumeFlow(
   const agentEnvironment = localAgentEnvironment();
   const socketPath = socketFor(dataDir);
   const base = emptyReport('resume');
-  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, 'resume', dataDir, base, options);
   if (connected !== undefined) return connected;
 
@@ -379,6 +385,7 @@ export async function resumeFlow(
       await client.runWatch(runId).catch(() => client.off('entry', onEntry));
     }
     let outcome = await client.runResume(runId, options.allowHumanInfluenced);
+    options.onRunReceipt?.({ runId, flow: 'flow' });
     if (await resumeHelperEffect(client, runId, dataDir)) {
       outcome = await client.runResume(runId, options.allowHumanInfluenced);
     }
@@ -408,6 +415,14 @@ export async function resumeFlow(
     if (error instanceof AuthoredFlowExecutionError && (error.code === 'step_failed' || error.code === 'gate_failed')) {
       return authoredStepFailure('resume', base, socketPath, error, runId);
     }
+    if (error instanceof AuthoredFlowExecutionError && error.code === 'result_unreadable') {
+      return completedResultUnreadableReport('resume', base, socketPath, error);
+    }
+    if (error instanceof AuthoredFlowExecutionError) {
+      const memoryFailure = memoryWriteFailure('resume', base, socketPath, error, runId);
+      if (memoryFailure !== undefined) return memoryFailure;
+    }
+    if (isReadInterruption(error)) return daemonUnresponsiveReport('resume', base, socketPath, error, runId, options, dataDir);
     if (error instanceof AuthoredFlowExecutionError && error.code === 'root_lease_lost') {
       return rootLeaseLostReport('resume', base, socketPath, error, runId);
     }
@@ -822,6 +837,19 @@ export async function connect(
 /// needs a stubbed client rather than a real run -- the integration test that
 /// found it reproduced the bug roughly 1 time in 12.
 export async function classifyOutcome(
+  client: JournalClient, command: RunCommand, outcome: RunOutcome,
+  base: CheckReport | RunReport, socketPath: string, options: RunLifecycleOptions,
+): Promise<RunExecution> {
+  try { return await classifyOutcomeInner(client, command, outcome, base, socketPath, options); }
+  catch (error) {
+    // Authored child calls have no CLI socket path: let their durable root
+    // handle the interruption, rather than turn it into a child step failure.
+    if (socketPath !== '' && isReadInterruption(error)) return daemonUnresponsiveReport(command, base, socketPath, error, outcome.run_id, options);
+    throw error;
+  }
+}
+
+async function classifyOutcomeInner(
   client: JournalClient,
   command: RunCommand,
   outcome: RunOutcome,
@@ -929,6 +957,7 @@ export async function classifyOutcome(
       kind: current.completion_reason,
       message: `Run "${current.run_id}" failed with completionReason: ${current.completion_reason}.`,
     };
+    let interrupted: RunDiagnostic | undefined;
     if (current.completion_reason === 'step_failed') {
       let details: StepFailedDetails | undefined;
       try {
@@ -936,6 +965,10 @@ export async function classifyOutcome(
       } catch (error) {
         // Inspection must not erase the already known run failure.
         diagnostic.message += ` Could not inspect the failed step: ${errorMessage(error)}`;
+        // Mark an unanswered read so optional follow-up reads do not spend a
+        // fresh budget on the same delayed daemon.
+        if (isReadInterruption(error)) interrupted = { severity: 'warning', kind: 'inspection_interrupted',
+          message: `The failed step could not be inspected: ${errorMessage(error)}` };
       }
       if (details !== undefined) {
         Object.assign(diagnostic, details);
@@ -952,7 +985,7 @@ export async function classifyOutcome(
       exitCode: 1,
       report: {
         ...report,
-        diagnostics: [...report.diagnostics, diagnostic],
+        diagnostics: [...report.diagnostics, diagnostic, ...(interrupted === undefined ? [] : [interrupted])],
       },
     };
   }
@@ -1021,10 +1054,6 @@ interface OutOfBandInspection {
   backoffStep?: ParkedStep;
 }
 
-interface RunningStep extends ParkedStep {
-  leaseDeadlineMs: number;
-}
-
 // Bound on re-polling a run that reports `running` with no identifiable step.
 // 40 x 50ms = 2s, far longer than the sub-second window observed in #179, and
 // short enough that a genuinely stuck run still reports rather than hangs.
@@ -1071,62 +1100,41 @@ async function inspectOutOfBandStep(
   };
 }
 
-// Match kernel/relayflowd/src/server/client.rs: allow the lease sweep to dispatch a retry.
-export const LEASE_SWEEP_GRACE_MS = 5_000;
-// How often to re-ask the daemon about a step whose lease looks expired here.
 const EXPIRED_LEASE_POLL_MS = 250;
-// A deadline unchanged for a whole lease (relayflowd LEASE_RENEWAL_MS, 30s)
-// plus the sweep grace was renewed by nobody: the attempt is dead and the
-// daemon never swept it. Fail rather than hang.
-const STALE_LEASE_MS = 30_000 + LEASE_SWEEP_GRACE_MS;
 
-async function waitForRunningStep(
-  client: JournalClient,
-  runId: string,
-  runningStep: RunningStep,
-  options: RunLifecycleOptions,
-): Promise<void> {
-  let leaseDeadlineMs = runningStep.leaseDeadlineMs;
-  if (!Number.isFinite(leaseDeadlineMs)) {
-    throw new Error(`running step "${runningStep.id}" omitted lease_deadline_ms`);
-  }
-  options.onWait?.({
-    runId,
-    stepId: runningStep.id,
-    stepType: runningStep.type,
-    leaseDeadlineMs,
-  });
-  // When the lease deadline last changed, on this process's monotonic clock.
-  // A live worker renews every ~10s, moving the deadline; a dead lease the
-  // daemon has not swept keeps it. That -- not a comparison of the daemon's
-  // deadline with our wall clock -- is what separates the two under skew.
-  let deadlineSeenAt = performance.now();
-  while (true) {
-    throwIfCanceled(options.signal, runningStep.id);
-    const remainingMs = leaseDeadlineMs + LEASE_SWEEP_GRACE_MS - Date.now();
-    if (performance.now() - deadlineSeenAt > STALE_LEASE_MS) {
-      throw new Error(
-        `worker lease for step "${runningStep.id}" expired at ${leaseDeadlineMs} without completion`,
-      );
-    }
-    // Past the deadline by THIS clock alone is not an expiry: the daemon may
-    // still hold the lease (skew) or be sweeping it into a retry. Keep
-    // following the step, at a slower poll, until the daemon says otherwise.
-    await delay(remainingMs <= 0 ? EXPIRED_LEASE_POLL_MS : Math.min(50, remainingMs), options.signal);
-    const snapshot = await client.runGet(runId);
-    const step = snapshot.steps[runningStep.id];
-    if (step?.state !== 'running') return;
-    if (step.lease_deadline_ms !== undefined && step.lease_deadline_ms !== leaseDeadlineMs) {
-      leaseDeadlineMs = step.lease_deadline_ms;
-      deadlineSeenAt = performance.now();
-      options.onWait?.({
-        runId,
-        stepId: runningStep.id,
-        stepType: runningStep.type,
-        leaseDeadlineMs,
-      });
-    }
-  }
+/**
+ * `f.memory` failures keep their own kind instead of collapsing into
+ * `protocol_error`. By then the root has been terminalized as failed, so the
+ * report names it the way a step failure does.
+ */
+export function memoryWriteFailure(
+  command: RunCommand,
+  base: CheckReport | RunReport,
+  socketPath: string,
+  error: AuthoredFlowExecutionError,
+  fallbackRunId?: string,
+): RunExecution | undefined {
+  if (error.code !== 'memory_finding_invalid' && error.code !== 'memory_unwritable'
+    && error.code !== 'memory_unjournaled' && error.code !== 'memory_unreachable') return undefined;
+  const rootRunId = error.rootRunId ?? fallbackRunId;
+  const runId = error.runId ?? rootRunId;
+  return {
+    exitCode: 1,
+    report: {
+      ...fromBase(command, base),
+      ok: false,
+      ...(runId === undefined ? {} : { runId }),
+      ...(rootRunId === undefined ? {} : { rootRunId }),
+      socketPath,
+      status: 'failed',
+      completionReason: 'step_failed',
+      diagnostics: [...base.diagnostics, {
+        severity: 'failure', kind: error.code,
+        // The `<code>: ` prefix `AuthoredFlowExecutionError` adds is redundant once the diagnostic is labelled.
+        message: error.message.startsWith(`${error.code}: `) ? error.message.slice(error.code.length + 2) : error.message,
+      }],
+    },
+  };
 }
 
 export function protocolFailure(

package/src/cli/running-step.ts

@@ -0,0 +1,140 @@
+import { JournalFrameError, JournalProtocolError, type JournalClient } from '../journal-client.js';
+import { AuthoredFlowExecutionError } from '../authored-flow-error.js';
+import type { JournalEvent } from '../journal-reader.js';
+import type { RunLifecycleOptions, ParkedStep } from './run.js';
+
+export const LEASE_SWEEP_GRACE_MS = 5_000;
+const LEASE_POLL_MS = 2_000;
+const STALE_LEASE_MS = 30_000 + LEASE_SWEEP_GRACE_MS;
+export interface RunningStep extends ParkedStep { leaseDeadlineMs: number }
+
+/** Watch completion; snapshots only refresh the non-journaled live lease deadline. */
+export async function waitForRunningStep(client: JournalClient, runId: string,
+  runningStep: RunningStep, options: RunLifecycleOptions): Promise<void> {
+  let leaseDeadlineMs = runningStep.leaseDeadlineMs;
+  if (!Number.isFinite(leaseDeadlineMs)) {
+    throw new Error(`running step "${runningStep.id}" omitted lease_deadline_ms`);
+  }
+  const notify = () => options.onWait?.({ runId, stepId: runningStep.id,
+    stepType: runningStep.type, leaseDeadlineMs });
+  notify();
+  let deadlineSeenAt = performance.now();
+  // The protocol has no unwatch. Closing this scoped, non-worker session removes
+  // the server watcher, even on cancellation or a read/registration failure.
+  const watch = client.createPeer();
+  let settled = false;
+  let ready = false;
+  let finish: () => void = () => {};
+  let cancel: () => void = () => {};
+  let fail: (error: unknown) => void = () => {};
+  const canceled = () => new Error(`worker wait for step "${runningStep.id}" was canceled`);
+  const completed = new Promise<void>((resolve, reject) => {
+    finish = resolve;
+    cancel = () => reject(canceled());
+    fail = reject;
+  });
+  // The subscription handshake itself may be pending when cancellation arrives.
+  void completed.catch(() => {});
+  // A completion push aborts the lease snapshot in flight: the answer is known.
+  let snapshotRead: AbortController | undefined;
+  const onEntry = (entry: JournalEvent) => {
+    if (entry.run_id !== runId) return;
+    if (entry.entry_type === 'run.completed') settled = true;
+    else if (entry.step_id === runningStep.id) {
+      if (entry.entry_type === 'step.attempt.started') settled = false;
+      if (entry.entry_type === 'step.completed' || entry.entry_type === 'wait.human') settled = true;
+    }
+    // Fold the entire replay before deciding: an older attempt may have failed.
+    if (ready && settled) {
+      finish();
+      snapshotRead?.abort(new Error(`step "${runningStep.id}" completed during the lease snapshot`));
+    }
+  };
+  watch.on('entry', onEntry);
+  // A malformed frame after registration has no pending request to reject: fail closed here.
+  let protocolFailure: unknown;
+  const onProtocolError = (error: unknown) => { protocolFailure ??= error; fail(error); snapshotRead?.abort(error); };
+  watch.on('protocol_error', onProtocolError);
+  // A dropped watch loses its completion pushes: a resumable read interruption.
+  const onDisconnected = (error: Error) => {
+    if (settled) return;
+    const lost = new AuthoredFlowExecutionError('daemon_unresponsive',
+      `the completion watch for step "${runningStep.id}" disconnected: ${error.message}`);
+    protocolFailure ??= lost;
+    fail(lost);
+    snapshotRead?.abort(lost);
+  };
+  watch.on('disconnected', onDisconnected);
+  options.signal?.addEventListener('abort', cancel, { once: true });
+  if (options.signal?.aborted) cancel();
+  try {
+    // Every transport failure up to and including the watch registration is a
+    // read interruption: the step may still be running and the run resumable.
+    let unconfirmed: unknown;
+    await Promise.race([watch.connect().then(() => watch.hello('flows-step-watch'))
+      .then(() => watch.runWatch(runId)).catch(error => {
+        // The replay precedes the response, but a drop may have truncated it
+        // (an older completion, the retry not yet seen): confirm below.
+        if (settled) { unconfirmed = error; return; }
+        // Refusals and malformed frames are protocol facts, not lost transport: fail closed.
+        if (error instanceof JournalProtocolError || error instanceof JournalFrameError) throw error;
+        throw new AuthoredFlowExecutionError('daemon_unresponsive',
+          `could not establish the completion watch: ${error instanceof Error ? error.message : String(error)}`);
+      }), completed]);
+    if (unconfirmed !== undefined) {
+      const snapshot = await client.runGet(runId, options.signal === undefined ? {} : { signal: options.signal });
+      if (snapshot.steps[runningStep.id]?.state !== 'running') return;
+      throw new AuthoredFlowExecutionError('daemon_unresponsive',
+        `could not establish the completion watch: ${unconfirmed instanceof Error ? unconfirmed.message : String(unconfirmed)}`);
+    }
+    ready = true;
+    if (settled) return;
+    while (true) {
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      let releaseTimer: () => void = () => {};
+      try {
+        const elapsed = await Promise.race([
+          new Promise<boolean>(resolve => { releaseTimer = () => resolve(false); timer = setTimeout(() => resolve(true), LEASE_POLL_MS); }),
+          completed.then(() => false),
+        ]);
+        if (!elapsed) return;
+      } finally { clearTimeout(timer); releaseTimer(); }
+      // Drain the read before leaving the authored promise scope. A raced but
+      // unresolved read would look like unawaited derived work to that scope,
+      // so cancellation aborts the read itself and it settles at once.
+      const read = snapshotRead = new AbortController();
+      const signal = options.signal === undefined ? read.signal
+        : AbortSignal.any([options.signal, read.signal]);
+      const snapshot = await client.runGet(runId, { signal })
+        .catch(error => {
+          if (options.signal?.aborted) throw canceled();
+          if (protocolFailure !== undefined) throw protocolFailure;
+          // A completion push aborted this read: completion was observed, and
+          // finish() is one-shot, even if a retry attempt started right after.
+          if (settled || read.signal.aborted) return undefined;
+          throw error;
+        })
+        .finally(() => { snapshotRead = undefined; });
+      if (options.signal?.aborted) throw canceled();
+      if (protocolFailure !== undefined) throw protocolFailure;
+      if (settled || snapshot === undefined || snapshot.steps[runningStep.id]?.state !== 'running') return;
+      const deadline = snapshot.steps[runningStep.id]?.lease_deadline_ms;
+      if (deadline !== undefined && deadline !== leaseDeadlineMs) {
+        leaseDeadlineMs = deadline;
+        deadlineSeenAt = performance.now();
+        notify();
+      } else if (performance.now() - deadlineSeenAt > STALE_LEASE_MS) {
+        // A stalled sweep/renewal is not evidence that the body itself failed.
+        throw new AuthoredFlowExecutionError('daemon_unresponsive',
+          `worker lease for step "${runningStep.id}" expired at ${leaseDeadlineMs} without completion; relayflowd's lease sweep may be delayed by CPU load`);
+      }
+    }
+  } finally {
+    finish();
+    options.signal?.removeEventListener('abort', cancel);
+    watch.off('entry', onEntry);
+    watch.off('protocol_error', onProtocolError);
+    watch.off('disconnected', onDisconnected);
+    watch.close();
+  }
+}

package/src/cli-adapter.ts

@@ -84,8 +84,14 @@ export function agentExecution(
   kind: CliAdapterKind,
   instruction: string,
   model?: string,
+  resume?: string,
 ): CliInvocation {
-  return registeredAdapters()[kind].buildAgentInvocation(instruction, model);
+  return registeredAdapters()[kind].buildAgentInvocation(instruction, model, resume);
+}
+
+/** Whether this CLI can continue a recorded session (`f.agent` `resume`). */
+export function agentResumable(kind: CliAdapterKind): boolean {
+  return registeredAdapters()[kind].resumable === true;
 }
 
 /** Reuse the workspace-free model probe's provider flags for a real LLM call. */

package/src/cli-commands.ts

@@ -88,7 +88,8 @@ const NO_CONNECT_OPTION: CliOptionSpec = {
 const LOCAL_EXECUTION_OPTIONS = [
   JSON_OPTION,
   DATA_DIR_OPTION,
-  { flags: '--local-agent', description: 'Run agent steps in this process instead of a worker' },
+  { flags: '--local-agent', description: 'Run agent steps in this process (bound to this terminal unless --detach)' },
+  { flags: '--detach', description: 'Start in a separate process, print the run handle and exit; follow with flows status' },
   {
     flags: '--agent-capacity <n>',
     description: `With --local-agent, how many agent steps (and, separately, LLM steps) run at once (1-${MAX_LOCAL_AGENT_CAPACITY})`,
@@ -117,20 +118,22 @@ export const CLI_VERBS = [
   },
   {
     name: 'answer',
-    description: 'Answer a run’s parked f.human question; `flows resume` then continues the body',
+    description: 'Answer a parked f.human; --cloud also resumes, local answers need flows resume',
     args: [
       { name: 'run-id', description: 'Run parked on the question', required: true },
-      { name: 'wait-id', description: 'Which question to answer, named human-<n> in the order the body asked', required: true },
-      { name: 'answer', description: 'The decision, as yes or no (also true or false)', required: true },
+      { name: 'wait-id-or-answer', description: 'Local: human-<n> wait id; Cloud: yes or no', required: true },
+      { name: 'answer', description: 'Local decision, as yes or no (also true or false)', required: false },
     ],
     options: [
       JSON_OPTION,
+      { flags: '--cloud', description: 'Answer and resume a Cloud run using its open wait' },
+      { flags: '--source <path>', description: 'Original Cloud flow source when the stored copy is unavailable or truncated' },
       DATA_DIR_OPTION,
       { flags: '--no-spawn', description: 'Require a running relayflowd rather than starting one' },
       { flags: '--note <text>', description: 'Reason recorded on the journal alongside the answer' },
       { flags: '--by <identity>', description: 'Who answered, when relaying a person’s decision; defaults to the OS user' },
     ],
-    variants: ['answer'],
+    variants: ['answer', 'cloud-answer'],
   },
   {
     name: 'build',
@@ -145,9 +148,10 @@ export const CLI_VERBS = [
   },
   {
     name: 'check',
-    description: 'Compile and preflight a flow without running it, or opening a daemon socket',
+    description: 'Compile, preflight, and validate with the installed runtime when available; never start a run',
     args: [{ name: 'source', description: 'flow.ts, flow.yaml, or spec.json', required: true }],
-    options: [JSON_OPTION, { flags: '--watch', description: 'Re-check on every change to the flow and its imports' }],
+    options: [{ flags: '--against-daemon', description: 'Require acceptance by the installed relayflowd validator (FLOWS_CHECK_AGAINST_DAEMON=1)' }, { flags: '--no-daemon-check', description: 'Local compile and preflight only (FLOWS_NO_DAEMON_CHECK=1)' }, JSON_OPTION, { flags: '--watch', description: 'Re-check on every change to the flow and its imports' },
+      { flags: '--explain-warnings', description: 'List every unprovable-effects warning per step instead of one summary line' }],
     variants: ['check'],
   },
   {
@@ -192,6 +196,23 @@ export const CLI_VERBS = [
     options: [JSON_OPTION],
     variants: ['deployments'],
   },
+  {
+    name: 'eval',
+    description: 'Re-execute a flow against a frozen suite of input cases and gate on the score report',
+    args: [{ name: 'flow', description: 'flow.ts, flow.yaml, or spec.json: the exact version to evaluate', required: true }],
+    options: [
+      { flags: '--cases <suite.json>', description: 'Required. Frozen suite: { name, cases: [{ id, input?, expect? }], thresholds? }' },
+      JSON_OPTION,
+      { flags: '--cloud', description: 'Execute each case as a hosted Cloud run instead of a local run' },
+      DATA_DIR_OPTION,
+      { flags: '--local-agent', description: 'Attach a local agent worker to each local run' },
+      { flags: '--concurrency <n>', description: 'Cases executed at once', defaultValue: '1' },
+      { flags: '--report <file>', description: 'Also write the JSON report to this file' },
+      { flags: '--baseline <report.json>', description: 'Fail the gate on any case that passed in this prior report' },
+      { flags: '--expect-version <sha256:hex>', description: 'Refuse unless the flow version (its local source manifest) hashes to exactly this' },
+    ],
+    variants: ['eval'],
+  },
   {
     name: 'hn-monitor',
     description: 'Hacker News monitor: poll for matching stories and launch a flow per hit',
@@ -427,3 +448,18 @@ export type _EveryDeclaredVariantExists = AssertNever<Exclude<DeclaredVariant, P
  * from drifting apart.
  */
 export const CLI_VERB_NAMES: ReadonlySet<string> = new Set(CLI_VERBS.map((verb) => verb.name));
+
+/**
+ * Flags `runCli` handles before verb parsing, each only as the sole argument.
+ * The CLI reference renders this list, so it is the only place they are spelled.
+ */
+export const CLI_GLOBAL_OPTIONS = [
+  { flags: '-h, --help', description: 'Print usage and exit.' },
+  { flags: '-V, --version', description: 'Print the SDK version and exit.' },
+] as const satisfies readonly CliOptionSpec[];
+
+/** Whether `args` is exactly one spelling of the global option whose long form is `long`. */
+export function isGlobalOption(args: readonly string[], long: '--help' | '--version'): boolean {
+  const option = CLI_GLOBAL_OPTIONS.find((candidate) => candidate.flags.split(', ').includes(long));
+  return args.length === 1 && option !== undefined && option.flags.split(', ').includes(args[0]!);
+}

package/src/cli-watch.ts

@@ -1,3 +1,4 @@
+import type { DaemonValidationMode } from './daemon-spec-validation.js';
 import { spawn } from 'node:child_process';
 import { accessSync, constants, existsSync, readFileSync, watch, type FSWatcher } from 'node:fs';
 import { dirname, join, resolve, sep } from 'node:path';
@@ -11,17 +12,18 @@ type ExitCode = 0 | 1 | 2 | 3;
 /** A runner around the ordinary CLI, with a fresh module cache for every check. */
 export async function watchCheck(
   path: string,
-  json: boolean,
+  options: { json: boolean; explainWarnings: boolean },
   io: CliIo,
   /** Cancellation, owned by the caller; this function installs no signal handler. */
   signal: AbortSignal,
+  daemonValidation: DaemonValidationMode = 'auto',
 ): Promise<ExitCode> {
   try {
     return await watchChecks({
       path,
       signal,
-      check: () => checkOnce(path, json, io),
-      clear: () => { if (!json) io.stdout('\x1b[2J\x1b[H'); },
+      check: () => checkOnce(path, { ...options, daemonValidation }, io),
+      clear: () => { if (!options.json) io.stdout('\x1b[2J\x1b[H'); },
     });
   } catch (error) {
     io.stderr(`REFUSED [input_unreadable] Could not watch "${path}": ${error instanceof Error ? error.message : String(error)}`);
@@ -140,13 +142,14 @@ function discoverWatchPaths(path: string, imports: Map<string, string[]>): Set<s
   return paths;
 }
 
-function checkOnce(path: string, json: boolean, io: CliIo): Promise<ExitCode> {
+function checkOnce(path: string, options: { json: boolean; explainWarnings: boolean; daemonValidation: DaemonValidationMode }, io: CliIo): Promise<ExitCode> {
+  const mode = options.daemonValidation;
   // Importing an authored TS file in this process again would return its stale
   // cached definition (including transitive imports). A fresh CLI process uses
   // precisely the same check pipeline and reporting as a one-shot invocation.
   const entry = fileURLToPath(new URL(import.meta.url.endsWith('.ts') ? './cli.ts' : './cli.js', import.meta.url));
   return new Promise((resolveCode, reject) => {
-    const child = spawn(process.execPath, [...process.execArgv, entry, 'check', ...(json ? ['--json'] : []), path], {
+    const child = spawn(process.execPath, [...process.execArgv, entry, 'check', ...(mode === 'required' ? ['--against-daemon'] : mode === 'off' ? ['--no-daemon-check'] : []), ...(options.json ? ['--json'] : []), ...(options.explainWarnings ? ['--explain-warnings'] : []), path], {
       stdio: ['ignore', 'pipe', 'pipe'],
       // Ctrl-C belongs to the watcher; let an active check finish so its report
       // and exit status remain a pair, then release all resources.