@relayflows/sdk 2.0.18 → 2.0.19

package/src/cli/serve-webhook.ts

@@ -4,6 +4,7 @@ import { createServer, type Server, type ServerResponse } from 'node:http';
 import { join, resolve } from 'node:path';
 import { TextDecoder } from 'node:util';
 import type { CliIo } from '../cli.js';
+import { DEFAULT_DATA_DIR } from '../daemon-connection.js';
 import { providerInboxEvent } from '../trigger-executor.js';
 import { verifySignature, schemeFor } from '../webhook-signature.js';
 import { TokenBucketLimiter, keyFor, type RateLimitConfig } from '../webhook-rate-limit.js';
@@ -24,9 +25,12 @@ export function parseWebhookArgs(args: readonly string[]): {
       || !value || value.startsWith('-')) return undefined;
     values.set(flag, value);
   }
-  const dataDir = values.get('--data-dir');
+  // `--data-dir` is optional here as it is on every other verb, and defaults to
+  // the same directory: the command surface advertises that default, so a
+  // receiver started without the flag has to run rather than exit 2.
+  const dataDir = values.get('--data-dir') ?? DEFAULT_DATA_DIR;
   const portText = values.get('--port');
-  if (!dataDir || !portText || !/^\d+$/.test(portText)) return undefined;
+  if (!portText || !/^\d+$/.test(portText)) return undefined;
   const port = Number(portText);
   if (!Number.isInteger(port) || port < 0 || port > 65535) return undefined;
   const allow = values.get('--allow');
@@ -215,6 +219,12 @@ async function directory(path: string): Promise<void> {
 
 export async function runServeWebhook(
   options: { dataDir: string; port: number; admitted?: readonly string[] }, io: CliIo,
+  /**
+   * Shutdown, owned by the caller. `runCli` supplies either the embedder's
+   * signal or one it drives from SIGINT/SIGTERM, so the receiver installs no
+   * process-wide handler of its own.
+   */
+  signal: AbortSignal,
 ): Promise<0 | 1> {
   try {
     const admittedNames = options.admitted === undefined ? undefined : new Set(options.admitted);
@@ -231,12 +241,9 @@ export async function runServeWebhook(
         server.closeAllConnections();
       };
       server.once('error', reject);
-      process.once('SIGINT', stop);
-      process.once('SIGTERM', stop);
-      server.once('close', () => {
-        process.off('SIGINT', stop);
-        process.off('SIGTERM', stop);
-      });
+      if (signal.aborted) { stop(); return; }
+      signal.addEventListener('abort', stop, { once: true });
+      server.once('close', () => signal.removeEventListener('abort', stop));
     });
     return 0;
   } catch (error) {

package/src/cli-commands.ts

@@ -0,0 +1,339 @@
+import { DEFAULT_DATA_DIR } from './daemon-connection.js';
+import type { ParsedArgs } from './cli.js';
+
+/**
+ * The one declaration of the `flows` command surface.
+ *
+ * Two consumers read this table and nothing else:
+ *
+ * 1. `parseArgs` in `cli.ts` gates its verb dispatch on {@link CLI_VERB_NAMES},
+ *    so a token that is not in this table can never reach a parser.
+ * 2. `createRelayCliSurface` in `relay-cli.ts` projects it into the
+ *    `RelayCliSurface.commands` tree the `agent-relay` host mounts.
+ *
+ * Because both sides derive from one array, `commands` and `run` cannot
+ * describe different trees. The drift test proves the remaining direction --
+ * that each declared command actually parses -- and {@link CLI_VERBS} carries a
+ * compile-time assertion that every `ParsedArgs` variant is claimed by some
+ * verb, so extending the union without extending this table fails `tsc`.
+ *
+ * The types here are deliberately local rather than imported from
+ * `@agent-relay/cli-surface`: they are structurally identical, and keeping the
+ * import out means `dist/relay-cli.d.ts` stands alone, so a consumer of
+ * `@relayflows/sdk` never needs the contract package resolvable. Assignability
+ * to the real contract is asserted in `tests/relay-cli-surface.test.ts`.
+ */
+
+/** A positional argument. Mirrors `RelayCliArgSpec`. */
+export interface CliArgSpec {
+  name: string;
+  description: string;
+  required: boolean;
+  variadic?: boolean;
+}
+
+/** A flag, in commander's flag-string form. Mirrors `RelayCliOptionSpec`. */
+export interface CliOptionSpec {
+  flags: string;
+  description: string;
+  defaultValue?: string | boolean | number;
+}
+
+/** One node of the command tree. Mirrors `RelayCliCommandSpec`. */
+export interface CliCommandSpec {
+  name: string;
+  description: string;
+  aliases?: readonly string[];
+  args?: readonly CliArgSpec[];
+  options?: readonly CliOptionSpec[];
+  subcommands?: readonly CliCommandSpec[];
+}
+
+/** A top-level verb, plus the `ParsedArgs` variants it can produce. */
+export interface CliVerbSpec extends CliCommandSpec {
+  /**
+   * Every `ParsedArgs.command` this verb can parse to.
+   *
+   * Usually one, but the verb set and the variant set are not one-to-one:
+   * `deploy` produces `deploy` for a digest reference and `cloud-deploy` for
+   * authored source, and `run` produces `cloud-run` under `--cloud`.
+   */
+  variants: readonly ParsedArgs['command'][];
+}
+
+const DATA_DIR_OPTION: CliOptionSpec = {
+  flags: '--data-dir <dir>',
+  description: 'Daemon data directory',
+  defaultValue: DEFAULT_DATA_DIR,
+};
+
+const JSON_OPTION: CliOptionSpec = {
+  flags: '--json',
+  description: 'Emit one machine-readable JSON object instead of text',
+};
+
+/**
+ * Shared by the verbs that hand a flow to Cloud. Each of them preflights what
+ * the source needs connected and offers to connect it; this refuses instead,
+ * which is what a non-interactive caller wants.
+ */
+const NO_CONNECT_OPTION: CliOptionSpec = {
+  flags: '--no-connect',
+  description: 'Refuse a missing integration instead of offering to connect it',
+};
+
+/** Flags shared by the two verbs that execute a flow locally. */
+const LOCAL_EXECUTION_OPTIONS = [
+  JSON_OPTION,
+  DATA_DIR_OPTION,
+  { flags: '--local-agent', description: 'Run agent steps in this process instead of a worker' },
+  { flags: '--no-spawn', description: 'Require a running relayflowd rather than starting one' },
+  { flags: '--no-observer-link', description: 'Do not mint an observer link for this run' },
+  {
+    flags: '--allow-human-influenced',
+    description: 'Proceed even though the run carries human-influenced state',
+  },
+] as const satisfies readonly CliOptionSpec[];
+
+/**
+ * `as const satisfies` rather than a type annotation on purpose: an annotation
+ * would widen every `variants` entry to `ParsedArgs['command']` and the
+ * compile-time exhaustiveness assertion below would pass vacuously.
+ */
+export const CLI_VERBS = [
+  {
+    name: 'add',
+    description: 'Install a helper plugin into this project',
+    args: [{ name: 'helper', description: 'Helper name or @flows/<helper-name>', required: true }],
+    variants: ['add'],
+  },
+  {
+    name: 'answer',
+    description: 'Answer a run’s parked f.human question; `flows resume` then continues the body',
+    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 },
+    ],
+    options: [
+      JSON_OPTION,
+      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'],
+  },
+  {
+    name: 'build',
+    description: 'Compile a flow into a sealed, content-addressed bundle',
+    args: [{ name: 'source', description: 'flow.yaml, flow.ts, or a bundle directory with --verify', required: true }],
+    options: [
+      { flags: '--out <dir>', description: 'Directory to write the bundle into; not valid with --verify' },
+      { flags: '--verify', description: 'Verify an existing bundle directory instead of building' },
+      JSON_OPTION,
+    ],
+    variants: ['build'],
+  },
+  {
+    name: 'check',
+    description: 'Compile and preflight a flow without running it, or opening a daemon socket',
+    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' }],
+    variants: ['check'],
+  },
+  {
+    name: 'deploy',
+    description: 'Copy a sealed bundle into a file bucket, or deploy a hosted trigger listener',
+    args: [{ name: 'flow', description: 'flow.ts for a hosted listener, or <flow>@sha256:<digest> for a bundle', required: true }],
+    options: [
+      { flags: '--to <file-bucket-uri>', description: 'Destination file bucket for a sealed bundle' },
+      { flags: '--repo <owner/name>', description: 'Repository the hosted listener watches' },
+      { flags: '--on <provider>', description: 'Trigger source, as <provider>[:key=value,...]; repeatable' },
+      { flags: '--approver <handle>', description: 'Handle delivered to every launched run as input.approver' },
+      { flags: '--agents <list>', description: 'Agent harnesses to allow, as claude[,codex]' },
+      { flags: '--name <name>', description: 'Name for the hosted listener' },
+      { flags: '--draft', description: 'Create the listener without activating it' },
+      NO_CONNECT_OPTION,
+      JSON_OPTION,
+    ],
+    variants: ['deploy', 'cloud-deploy'],
+  },
+  {
+    name: 'deployments',
+    description: 'List this workspace’s hosted trigger listeners',
+    options: [JSON_OPTION],
+    variants: ['deployments'],
+  },
+  {
+    name: 'hn-monitor',
+    description: 'Hacker News monitor: poll for matching stories and launch a flow per hit',
+    subcommands: [
+      {
+        name: 'start',
+        description: 'Start polling in the foreground',
+        args: [{ name: 'spec', description: 'Monitor spec.json', required: true }],
+        options: [
+          DATA_DIR_OPTION,
+          { flags: '--poll-interval-ms <ms>', description: 'Milliseconds between polls' },
+        ],
+      },
+    ],
+    variants: ['hn-monitor'],
+  },
+  {
+    name: 'observer',
+    description: 'Mint a read-only observer link without running a flow',
+    options: [DATA_DIR_OPTION],
+    variants: ['observer'],
+  },
+  {
+    name: 'replay',
+    description: 'Replay a finished run from its local journal',
+    args: [{ name: 'run-id', description: 'Run id to replay', required: true }],
+    options: [
+      JSON_OPTION,
+      DATA_DIR_OPTION,
+      { flags: '--at <step-id>', description: 'Replay up to this step' },
+      {
+        flags: '--allow-human-influenced',
+        description: 'Proceed even though the run carries human-influenced state',
+      },
+    ],
+    variants: ['replay'],
+  },
+  {
+    name: 'resume',
+    description: 'Resume an interrupted local run from where its journal left off',
+    args: [{ name: 'run-id', description: 'Run id to resume', required: true }],
+    options: LOCAL_EXECUTION_OPTIONS,
+    variants: ['resume'],
+  },
+  {
+    name: 'run',
+    description: 'Run a flow locally, or submit it to Cloud with --cloud',
+    args: [{ name: 'flow', description: 'flow.yaml, flow.ts, spec.json, or <flow>@sha256:<digest>', required: true }],
+    options: [
+      ...LOCAL_EXECUTION_OPTIONS,
+      { flags: '--input <json-or-file>', description: 'Input for an authored .flow.ts, inline JSON or a file path' },
+      { flags: '--bucket <file-bucket-uri>', description: 'File bucket to fetch a sealed bundle from' },
+      { flags: '--reuse-from <run-id>', description: 'Reuse memoized step outputs from an earlier run' },
+      { flags: '--cloud', description: 'Submit to Agent Relay Cloud instead of running locally' },
+      { flags: '--wait', description: 'With --cloud, poll until the hosted run reaches a terminal state' },
+      {
+        flags: '--sync-code',
+        description: 'With --cloud, upload the working directory as the run’s tree; pull results back with `flows sync`',
+      },
+      {
+        flags: '--no-connect',
+        description: 'With --cloud, refuse a missing integration instead of offering to connect it',
+      },
+    ],
+    variants: ['run', 'cloud-run'],
+  },
+  {
+    name: 'schedule',
+    description: 'Register a flow to run in Cloud on a cron or interval, or on the one it declares',
+    args: [{ name: 'flow', description: 'flow.yaml or flow.ts submitted on every fire', required: true }],
+    options: [
+      {
+        flags: '--cron <expr>',
+        description: 'Cron expression to fire on; with neither this nor --every, the flow’s own schedule.* handler supplies it',
+      },
+      { flags: '--every <duration>', description: 'Fixed cadence, as <n><s|m|h|d>; not valid with --cron' },
+      { flags: '--tz <iana>', description: 'IANA timezone the cron is read in' },
+      { flags: '--input <json-or-file>', description: 'Input for an authored .flow.ts, inline JSON or a file path' },
+      { flags: '--name <name>', description: 'Name for the schedule' },
+      NO_CONNECT_OPTION,
+      JSON_OPTION,
+    ],
+    variants: ['schedule'],
+  },
+  {
+    name: 'schedules',
+    description: 'List this workspace’s Cloud schedules',
+    options: [JSON_OPTION],
+    variants: ['schedules'],
+  },
+  {
+    name: 'serve-webhook',
+    description: 'Run the local webhook receiver that writes provider deliveries into the trigger inbox',
+    options: [
+      DATA_DIR_OPTION,
+      { flags: '--port <port>', description: 'Port to listen on, bound to 127.0.0.1; required' },
+      { flags: '--allow <names>', description: 'Comma-separated flow names this receiver admits' },
+    ],
+    variants: ['serve-webhook'],
+  },
+  {
+    name: 'sync',
+    description: 'Apply a hosted run’s code changes to a local tree (replaces `agent-relay cloud sync`)',
+    args: [{ name: 'run-id', description: 'Hosted run id whose patch to apply', required: true }],
+    options: [
+      JSON_OPTION,
+      { flags: '--dry-run', description: 'Print the patch and apply nothing' },
+      { flags: '--dir <path>', description: 'Tree to apply the patch to', defaultValue: '.' },
+    ],
+    variants: ['sync'],
+  },
+  {
+    name: 'tick',
+    description: 'Interval scheduler: launch a flow on a fixed local cadence',
+    subcommands: [
+      {
+        name: 'start',
+        description: 'Start ticking in the foreground',
+        args: [{ name: 'spec', description: 'Flow spec.json to launch each tick', required: true }],
+        options: [
+          DATA_DIR_OPTION,
+          { flags: '--schedule-id <id>', description: 'Stable id identifying this schedule' },
+          { flags: '--interval-ms <ms>', description: 'Milliseconds between ticks' },
+          { flags: '--epoch-ms <ms>', description: 'Epoch the tick grid is aligned to' },
+          { flags: '--max-catch-up <n>', description: 'Most missed ticks to replay after a gap' },
+          { flags: '--poll-interval-ms <ms>', description: 'Milliseconds between schedule polls' },
+        ],
+      },
+    ],
+    variants: ['tick'],
+  },
+  {
+    name: 'undeploy',
+    description: 'Remove a hosted trigger listener',
+    args: [{ name: 'deployment-id', description: 'Deployment id to remove', required: true }],
+    options: [JSON_OPTION],
+    variants: ['undeploy'],
+  },
+  {
+    name: 'unschedule',
+    description: 'Remove a Cloud schedule, so it stops firing',
+    args: [{ name: 'schedule-id', description: 'Schedule id to remove', required: true }],
+    options: [JSON_OPTION],
+    variants: ['unschedule'],
+  },
+] as const satisfies readonly CliVerbSpec[];
+
+/**
+ * Every `ParsedArgs` variant claimed by some verb in {@link CLI_VERBS}.
+ *
+ * Widened from the table rather than written down, so it tracks the table.
+ */
+type DeclaredVariant = (typeof CLI_VERBS)[number]['variants'][number];
+
+/**
+ * Compile-time drift guard, the half a runtime test cannot cover.
+ *
+ * Adding a variant to `ParsedArgs` without giving some verb a claim on it
+ * leaves `Exclude<ParsedArgs['command'], DeclaredVariant>` non-`never`, and
+ * this assignment stops compiling. The reverse direction catches a table entry
+ * naming a variant that no longer exists.
+ */
+type AssertNever<T extends never> = T;
+export type _EveryVariantIsDeclared = AssertNever<Exclude<ParsedArgs['command'], DeclaredVariant>>;
+export type _EveryDeclaredVariantExists = AssertNever<Exclude<DeclaredVariant, ParsedArgs['command']>>;
+
+/**
+ * The verbs `parseArgs` accepts. A token outside this set is refused before any
+ * per-verb parser sees it, which is what keeps dispatch and {@link CLI_VERBS}
+ * from drifting apart.
+ */
+export const CLI_VERB_NAMES: ReadonlySet<string> = new Set(CLI_VERBS.map((verb) => verb.name));

package/src/cli-watch.ts

@@ -9,24 +9,23 @@ const DEBOUNCE_MS = 150;
 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, io: CliIo): Promise<ExitCode> {
-  const controller = new AbortController();
-  const stop = (): void => controller.abort();
-  process.once('SIGINT', stop);
-  process.once('SIGTERM', stop);
+export async function watchCheck(
+  path: string,
+  json: boolean,
+  io: CliIo,
+  /** Cancellation, owned by the caller; this function installs no signal handler. */
+  signal: AbortSignal,
+): Promise<ExitCode> {
   try {
     return await watchChecks({
       path,
-      signal: controller.signal,
+      signal,
       check: () => checkOnce(path, json, io),
       clear: () => { if (!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)}`);
     return 2;
-  } finally {
-    process.off('SIGINT', stop);
-    process.off('SIGTERM', stop);
   }
 }
 

package/src/cli.ts

@@ -36,6 +36,7 @@ import { parseBuildArgs, runBuild, type BuildArgs } from './cli/build.js';
 import { runHnMonitor } from './cli/hn-monitor.js';
 import { runTickRunner } from './cli/tick-runner.js';
 import { DEFAULT_DATA_DIR } from './daemon-connection.js';
+import { CLI_VERB_NAMES } from './cli-commands.js';
 import {
   mintObserverUrl,
   resolveObserverLinkEnv,
@@ -50,14 +51,19 @@ export interface CliIo {
 }
 
 type CliExitCode = 0 | 1 | 2 | 3;
-type ParsedArgs =
+
+/**
+ * Every shape `parseArgs` can produce. Exported for `cli-commands.ts`, whose
+ * table must claim each variant or fail to compile.
+ */
+export type ParsedArgs =
   | { command: 'add'; value: string }
   | ReplayArgs
   | BuildArgs
   | DeployArgs
   | { command: 'serve-webhook'; dataDir: string; port: number; admitted?: readonly string[] }
   | { command: 'cloud-run'; value: string; json: boolean; wait: boolean; input: string | undefined; syncCode: boolean; noConnect: boolean }
-  | { command: 'sync'; runId: string; json: boolean; root: string }
+  | { command: 'sync'; runId: string; json: boolean; root: string; dryRun: boolean }
   | CloudDeployArgs
   | { command: 'deployments'; json: boolean }
   | { command: 'undeploy'; agentId: string; json: boolean }
@@ -92,7 +98,7 @@ const USAGE = [
   'flows run [--json] [--no-spawn] [--no-observer-link] [--data-dir <dir>] [--local-agent] [--reuse-from <run-id>] <flow.yaml|spec.json>',
   'flows run --cloud [--json] [--wait] [--sync-code] [--no-connect] <flow.yaml|spec.json>',
   'flows run --cloud [--json] [--wait] [--sync-code] [--no-connect] <flow.ts> --input <inline-json-or-file>',
-  'flows sync [--json] [--dir <path>] <run-id>',
+  'flows sync [--json] [--dry-run] [--dir <path>] <run-id>',
   'flows run [--json] [--no-spawn] [--no-observer-link] [--data-dir <dir>] [--local-agent] <flow.ts> --input <inline-json-or-file>',
   'flows tick start --schedule-id <id> --interval-ms <ms> [--epoch-ms <ms>] [--max-catch-up <n>] [--poll-interval-ms <ms>] [--data-dir <dir>] <spec.json>',
   'flows resume [--allow-human-influenced] [--json] [--no-spawn] [--no-observer-link] [--data-dir <dir>] [--local-agent] <run-id>',
@@ -117,9 +123,48 @@ const PROCESS_IO: CliIo = {
   stderr: (line) => process.stderr.write(`${line}\n`),
 };
 
+/** Optional knobs for an embedded caller. `bin/flows.js` passes none. */
+export interface RunCliOptions {
+  /**
+   * Cancellation for the long-running verbs (`run --cloud`, `check --watch`,
+   * `serve-webhook`, `hn-monitor start`, `tick start`).
+   *
+   * Supply one and `runCli` installs **no** process signal handlers -- required
+   * of a CLI surface mounted into another host, which owns SIGINT itself.
+   * Omit it and the standalone `flows` binary keeps today's behaviour exactly:
+   * SIGINT/SIGTERM are handled here, for the duration of that verb only.
+   */
+  signal?: AbortSignal;
+}
+
+/**
+ * Run one long-running verb under a cancellation signal.
+ *
+ * With a caller-supplied signal this installs nothing. Without one it owns
+ * SIGINT/SIGTERM for the duration of `body` and removes the handlers after --
+ * the pre-existing standalone behaviour, unchanged.
+ */
+async function withInterrupt<T>(
+  provided: AbortSignal | undefined,
+  body: (signal: AbortSignal) => Promise<T>,
+): Promise<T> {
+  if (provided !== undefined) return body(provided);
+  const controller = new AbortController();
+  const onSignal = (): void => controller.abort();
+  process.once('SIGINT', onSignal);
+  process.once('SIGTERM', onSignal);
+  try {
+    return await body(controller.signal);
+  } finally {
+    process.off('SIGINT', onSignal);
+    process.off('SIGTERM', onSignal);
+  }
+}
+
 export async function runCli(
   args: readonly string[],
   io: CliIo = PROCESS_IO,
+  options: RunCliOptions = {},
 ): Promise<CliExitCode> {
   if (args.length === 1 && (args[0] === '--help' || args[0] === '-h')) {
     io.stdout(USAGE);
@@ -135,9 +180,13 @@ export async function runCli(
 
   if (parsed.command === 'add') return addPlugin(parsed.value, io);
 
-  if (parsed.command === 'serve-webhook') return runServeWebhook(parsed, io);
+  if (parsed.command === 'serve-webhook') {
+    return withInterrupt(options.signal, (signal) => runServeWebhook(parsed, io, signal));
+  }
 
-  if (parsed.command === 'cloud-run') return runCloudCli(parsed, io);
+  if (parsed.command === 'cloud-run') {
+    return withInterrupt(options.signal, (signal) => runCloudCli(parsed, io, signal));
+  }
   if (parsed.command === 'sync') return runCloudSyncCli(parsed, io);
   if (parsed.command === 'cloud-deploy') return runCloudDeployCli(parsed, io);
   if (parsed.command === 'deployments') return runCloudDeploymentsCli(parsed, io);
@@ -159,7 +208,9 @@ export async function runCli(
   if (parsed.command === 'deploy') return runDeploy(parsed, io);
 
   if (parsed.command === 'check') {
-    if (parsed.watch) return watchCheck(parsed.value, parsed.json, io);
+    if (parsed.watch) {
+      return withInterrupt(options.signal, (signal) => watchCheck(parsed.value, parsed.json, io, signal));
+    }
     // Deliberately daemon-free (kernel/DAEMON-LIFECYCLE.md §4). `checkFlow` is
     // a compile-and-preflight that opens no daemon socket, and the parser
     // refuses `--data-dir` on `check`, so there is no data dir to attach to.
@@ -174,45 +225,27 @@ export async function runCli(
   if (parsed.command === 'observer') return runObserverCommand(io);
 
   if (parsed.command === 'hn-monitor') {
-    const controller = new AbortController();
-    const onSignal = (): void => controller.abort();
-    process.once('SIGINT', onSignal);
-    process.once('SIGTERM', onSignal);
-    try {
-      return await runHnMonitor({
-        dataDir: parsed.dataDir,
-        specPath: parsed.specPath,
-        pollIntervalMs: parsed.pollIntervalMs,
-        signal: controller.signal,
-      }, io);
-    } finally {
-      process.off('SIGINT', onSignal);
-      process.off('SIGTERM', onSignal);
-    }
+    return withInterrupt(options.signal, (signal) => runHnMonitor({
+      dataDir: parsed.dataDir,
+      specPath: parsed.specPath,
+      pollIntervalMs: parsed.pollIntervalMs,
+      signal,
+    }, io));
   }
 
   if (parsed.command === 'tick') {
-    const controller = new AbortController();
-    const onSignal = (): void => controller.abort();
-    process.once('SIGINT', onSignal);
-    process.once('SIGTERM', onSignal);
-    try {
-      return await runTickRunner({
-        dataDir: parsed.dataDir,
-        specPath: parsed.specPath,
-        schedule: {
-          scheduleId: parsed.scheduleId,
-          intervalMs: parsed.intervalMs,
-          ...(parsed.epochMs === undefined ? {} : { epochMs: parsed.epochMs }),
-          ...(parsed.maxCatchUp === undefined ? {} : { maxCatchUp: parsed.maxCatchUp }),
-        },
-        pollIntervalMs: parsed.pollIntervalMs,
-        signal: controller.signal,
-      }, io) as CliExitCode;
-    } finally {
-      process.off('SIGINT', onSignal);
-      process.off('SIGTERM', onSignal);
-    }
+    return withInterrupt(options.signal, async (signal) => await runTickRunner({
+      dataDir: parsed.dataDir,
+      specPath: parsed.specPath,
+      schedule: {
+        scheduleId: parsed.scheduleId,
+        intervalMs: parsed.intervalMs,
+        ...(parsed.epochMs === undefined ? {} : { epochMs: parsed.epochMs }),
+        ...(parsed.maxCatchUp === undefined ? {} : { maxCatchUp: parsed.maxCatchUp }),
+      },
+      pollIntervalMs: parsed.pollIntervalMs,
+      signal,
+    }, io) as CliExitCode);
   }
 
   // Attach-or-spawn runs inside `runFlow`/`resumeFlow`/`runDirectFlow`, at the
@@ -458,6 +491,11 @@ function emitWait(
 
 function parseArgs(args: readonly string[]): ParsedArgs | undefined {
   const command = args[0];
+  // The verb set lives in exactly one place -- `CLI_VERBS` in cli-commands.ts --
+  // which is also what `createRelayCliSurface` projects into `commands`. Gating
+  // dispatch on it means a token the surface does not declare can never reach a
+  // parser, so the declared tree and the dispatched tree cannot drift apart.
+  if (command === undefined || !CLI_VERB_NAMES.has(command)) return undefined;
   if (command === 'add') return args.length === 2 ? { command: 'add', value: args[1]! } : undefined;
   if (command === 'replay') return parseReplayArgs(args.slice(1));
   if (command === 'build') return parseBuildArgs(args.slice(1));
@@ -718,9 +756,13 @@ function parseHnMonitorArgs(rest: readonly string[]): ParsedArgs | undefined {
  * directory at all -- the mint is a pure Relaycast API round-trip. No
  * positional argument, no other flags.
  */
-/** `flows sync [--json] [--dir <path>] <run-id>`: apply a hosted run's patch to a local tree. */
+/**
+ * `flows sync [--json] [--dry-run] [--dir <path>] <run-id>`: apply a hosted
+ * run's patch to a local tree, or with `--dry-run` print it and apply nothing.
+ */
 function parseSyncArgs(args: readonly string[]): ParsedArgs | undefined {
   let json = false;
+  let dryRun = false;
   let root: string | undefined;
   const positionals: string[] = [];
   for (let index = 0; index < args.length; index += 1) {
@@ -730,6 +772,11 @@ function parseSyncArgs(args: readonly string[]): ParsedArgs | undefined {
       json = true;
       continue;
     }
+    if (argument === '--dry-run') {
+      if (dryRun) return undefined;
+      dryRun = true;
+      continue;
+    }
     if (argument === '--dir') {
       const value = args[index + 1];
       if (root !== undefined || value === undefined || value.startsWith('-')) return undefined;
@@ -741,7 +788,7 @@ function parseSyncArgs(args: readonly string[]): ParsedArgs | undefined {
     positionals.push(argument);
   }
   if (positionals.length !== 1) return undefined;
-  return { command: 'sync', runId: positionals[0]!, json, root: root ?? '.' };
+  return { command: 'sync', runId: positionals[0]!, json, dryRun, root: root ?? '.' };
 }
 
 function parseObserverArgs(rest: readonly string[]): ParsedArgs | undefined {
@@ -956,3 +1003,15 @@ if (isDirectInvocation(process.argv[1])) {
     process.exitCode = exitCode;
   });
 }
+
+/**
+ * The argv parser, exported for the CLI-surface drift test.
+ *
+ * The drift test must prove that every command `cli-commands.ts` declares
+ * actually routes to a `ParsedArgs` variant, and that every variant is
+ * reachable from some declared command. Observing that through `runCli` would
+ * mean executing the commands. Not part of the package's public API --
+ * `@relayflows/sdk/cli` exports `runCli`, and `@relayflows/sdk/relay-cli`
+ * exports the surface.
+ */
+export { parseArgs as parseCliArgs };