@relayflows/sdk 2.0.18 → 2.0.20

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 };

package/src/cloud-sync.ts

@@ -272,37 +272,188 @@ export interface CloudPatch {
   hasChanges: boolean;
 }
 
-/** The sandbox's post-run diff. Multi-path runs carry several patches and are refused here. */
-export async function downloadCloudPatch(runId: string, options: CloudConnectionOptions): Promise<CloudPatch> {
+/** One entry of a multi-path run's patch map: the mounted path's name and its diff. */
+export interface CloudPathPatch extends CloudPatch {
+  name: string;
+}
+
+/**
+ * What `/patch` answered, in both shapes the endpoint can produce.
+ *
+ * A run that declared mounted `paths` gets one `changes-<name>.patch` per path
+ * and the route answers `{ patches: { <name>: { patch, hasChanges } } }`; every
+ * other run gets `changes.patch` and the flat `{ patch, hasChanges }`. The
+ * multi-path shape is not a v1 relic -- `paths` is orthogonal to
+ * `relayflowVersion`, so a v2 run that submits several paths returns it too.
+ */
+export type CloudPatchSet =
+  | { kind: 'single'; patch: string; hasChanges: boolean }
+  | { kind: 'multi-path'; patches: readonly CloudPathPatch[]; hasChanges: boolean };
+
+/**
+ * The sandbox's post-run diff, in whichever shape the run produced.
+ *
+ * Both shapes are modelled rather than one refused at the transport, so a
+ * caller can show a multi-path run's patches (`flows sync --dry-run`) before
+ * deciding what to do with them. Applying them is still the caller's refusal
+ * to make: they target different repositories and no single tree is the right
+ * destination.
+ */
+export async function downloadCloudPatchSet(
+  runId: string, options: CloudConnectionOptions,
+): Promise<CloudPatchSet> {
   const payload = await cloudRequest(`/api/v1/workflows/runs/${encodeURIComponent(cloudRunId(runId))}/patch`, options);
   if (!isCloudRecord(payload)) throw new CloudFlowError('invalid_response', 'Cloud patch response was not an object.');
   if (isCloudRecord(payload.patches)) {
-    const names = Object.keys(payload.patches);
-    throw new CloudFlowError('sync_unsupported',
-      `Run ${runId} produced ${names.length} path-scoped patches (${names.join(', ')}); flows sync applies single-tree runs only.`);
+    const patches: CloudPathPatch[] = [];
+    for (const [name, entry] of Object.entries(payload.patches)) {
+      if (!isCloudRecord(entry) || typeof entry.patch !== 'string' || typeof entry.hasChanges !== 'boolean') {
+        throw new CloudFlowError('invalid_response', `Cloud patch response has an unusable entry for path "${name}".`);
+      }
+      patches.push({ name, patch: entry.patch, hasChanges: entry.hasChanges });
+    }
+    return { kind: 'multi-path', patches, hasChanges: patches.some(entry => entry.hasChanges && entry.patch.trim() !== '') };
   }
   if (typeof payload.patch !== 'string' || typeof payload.hasChanges !== 'boolean') {
     throw new CloudFlowError('invalid_response', 'Cloud patch response is missing patch or hasChanges.');
   }
-  return { patch: payload.patch, hasChanges: payload.hasChanges };
+  return { kind: 'single', patch: payload.patch, hasChanges: payload.hasChanges };
+}
+
+/** The sandbox's post-run diff. Multi-path runs carry several patches and are refused here. */
+export async function downloadCloudPatch(runId: string, options: CloudConnectionOptions): Promise<CloudPatch> {
+  const set = await downloadCloudPatchSet(runId, options);
+  if (set.kind === 'multi-path') {
+    const names = set.patches.map(entry => entry.name);
+    throw new CloudFlowError('sync_unsupported',
+      `Run ${runId} produced ${names.length} path-scoped patches (${names.join(', ')}); flows sync applies single-tree runs only.`);
+  }
+  return { patch: set.patch, hasChanges: set.hasChanges };
+}
+
+/**
+ * Paths a synced patch must never write, the single home for the list.
+ *
+ * These are the agent runtime's own bookkeeping inside a synced tree: helper
+ * binaries staged for the sandbox, the relayfile mount's ACL and state files
+ * (including the temporaries a mid-write state leaves behind), trajectory
+ * records and workflow context. The sandbox commits its baseline before the
+ * run, so every one of them shows up in the post-run diff as a creation or a
+ * modification -- applying that diff verbatim drags the run's own plumbing into
+ * the user's checkout, where at best it is noise in `git diff` and at worst it
+ * overwrites the mount state of the tree being synced into.
+ *
+ * `git apply --exclude` matches these with wildmatch, anchored at the patch
+ * root and with `*` stopping at a `/`: `.agent-bin/**` drops
+ * `.agent-bin/nested/tool` but deliberately not `packages/x/.agent-bin/tool`,
+ * which belongs to a different tree than the one being synced.
+ */
+export const CLOUD_SYNC_PATCH_EXCLUDES = [
+  '.agent-bin/**',
+  '.relayfile.acl',
+  '.relayfile-mount-state.json',
+  '.relayfile-mount-state.json.tmp-*',
+  '.trajectories/**',
+  '.workflow-context/**',
+] as const;
+
+/** The `a/` and `b/` sides of every `diff --git` header, in file order. */
+function patchHeaders(patch: string): { old: string; new: string }[] {
+  const headers: { old: string; new: string }[] = [];
+  for (const match of patch.matchAll(/^diff --git a\/(.+?) b\/(.+)$/gmu)) {
+    headers.push({ old: match[1]!, new: match[2]! });
+  }
+  return headers;
 }
 
 /** Every path a unified diff touches, deletions included, in order of first appearance. */
 export function patchedPaths(patch: string): string[] {
   const paths: string[] = [];
-  for (const match of patch.matchAll(/^diff --git a\/(.+?) b\/(.+)$/gmu)) {
-    for (const path of [match[1]!, match[2]!]) if (!paths.includes(path)) paths.push(path);
+  for (const header of patchHeaders(patch)) {
+    for (const path of [header.old, header.new]) if (!paths.includes(path)) paths.push(path);
   }
   return paths;
 }
 
+/**
+ * `git apply --exclude`'s wildmatch, as a matcher over a patch's own paths.
+ *
+ * Anchored at the patch root, `**` crosses `/` and `*`/`?` do not -- the subset
+ * of wildmatch {@link CLOUD_SYNC_PATCH_EXCLUDES} uses. Kept honest by a test
+ * that runs the same patterns through `git apply --numstat` and requires the
+ * two answers to agree, so a divergence fails here rather than silently
+ * reporting a path as dropped that git actually wrote.
+ */
+function matchesExclude(path: string, pattern: string): boolean {
+  let expression = '^';
+  for (let index = 0; index < pattern.length; index += 1) {
+    const character = pattern[index]!;
+    if (character === '*') {
+      if (pattern[index + 1] === '*') { expression += '.*'; index += 1; continue; }
+      expression += '[^/]*';
+      continue;
+    }
+    expression += character === '?' ? '[^/]' : character.replace(/[.+^${}()|[\]\\]/gu, '\\$&');
+  }
+  return new RegExp(`${expression}$`, 'u').test(path);
+}
+
+/**
+ * The subset of a patch's paths `exclude` drops, in order of first appearance.
+ *
+ * Decided per `diff --git` header on its `b/` side, which is the name `git
+ * apply` itself tests -- so a rename is dropped or kept whole, never half. A
+ * deletion names the same path on both sides, so it is covered by the same rule.
+ */
+export function excludedPatchPaths(
+  patch: string, exclude: readonly string[] = CLOUD_SYNC_PATCH_EXCLUDES,
+): string[] {
+  const paths: string[] = [];
+  for (const header of patchHeaders(patch)) {
+    if (!exclude.some(pattern => matchesExclude(header.new, pattern))) continue;
+    for (const path of [header.old, header.new]) if (!paths.includes(path)) paths.push(path);
+  }
+  return paths;
+}
+
+/** Options for {@link applyCloudPatch}. */
+export interface ApplyCloudPatchOptions {
+  /**
+   * Path patterns to drop, defaulting to {@link CLOUD_SYNC_PATCH_EXCLUDES}.
+   * Pass `[]` to apply a patch whole -- including the runtime artifacts the
+   * default list exists to keep out of a working tree.
+   */
+  exclude?: readonly string[];
+}
+
+/** What {@link applyCloudPatch} wrote, and what it dropped on the way. */
+export interface AppliedCloudPatch {
+  /** Paths the apply wrote, in order of first appearance in the patch. */
+  files: string[];
+  /** Paths `exclude` dropped, in order of first appearance in the patch. */
+  excluded: string[];
+}
+
 /**
  * `git apply --check` then `git apply`; a conflict leaves the tree untouched.
  * The patch lands in the working tree uncommitted, so what the run changed is
- * reviewed with `git diff` before anything is kept — the same contract as v1.
+ * reviewed with `git diff` before anything is kept -- the same contract as v1.
+ *
+ * Both invocations carry the identical `--exclude` arguments. A check run
+ * without them is a different question than the apply answers: it can pass on
+ * an excluded hunk that the apply then never writes, or fail on one and refuse
+ * a patch whose applied part was clean. The exclusions are a property of the
+ * patch that lands, so they belong to both halves or neither.
+ *
+ * A patch whose every path is excluded is a no-op, not a failure: `git apply`
+ * exits 0 having written nothing, and the returned `files` is empty.
  */
-export function applyCloudPatch(root: string, patch: string): void {
-  const args = ['-C', resolve(root), 'apply', '--whitespace=nowarn'];
+export function applyCloudPatch(
+  root: string, patch: string, options: ApplyCloudPatchOptions = {},
+): AppliedCloudPatch {
+  const exclude = options.exclude ?? CLOUD_SYNC_PATCH_EXCLUDES;
+  const args = ['-C', resolve(root), 'apply', '--whitespace=nowarn',
+    ...exclude.map(pattern => `--exclude=${pattern}`)];
   const check = spawnSync('git', [...args, '--check'], { input: patch, encoding: 'utf8' });
   if (check.status !== 0) {
     throw new CloudFlowError('patch_conflict',
@@ -312,4 +463,6 @@ export function applyCloudPatch(root: string, patch: string): void {
   if (apply.status !== 0) {
     throw new CloudFlowError('patch_conflict', `git apply failed:\n${apply.stderr.trim()}`);
   }
+  const excluded = excludedPatchPaths(patch, exclude);
+  return { files: patchedPaths(patch).filter(path => !excluded.includes(path)), excluded };
 }

package/src/flow-requirements.ts

@@ -1,3 +1,4 @@
+import { humanRecipientProvider } from './human-to.js';
 import { helperProviders } from '@relayflows/surface/runtime';
 import type { TriggerSource } from '@relayflows/surface';
 import { providerDeclaration } from './provider-trigger-contract.js';
@@ -26,8 +27,8 @@ export interface FlowIntegrationRequirement {
   /** Cloud integration provider id (`slack`, `github`, `linear`, …). */
   provider: string;
   /** `tools`: a header declaration; `source`: a trigger or deploy target; `helper`: body use without a flag, or a YAML helper step. */
-  from: 'tools' | 'source' | 'helper';
-  /** The declaration that requires it, as a reader would name it: `tools.slack`, `--on github`, `f.slack`. */
+  from: 'tools' | 'source' | 'helper' | 'human';
+  /** The declaration that requires it, as a reader would name it: `tools.slack`, `--on github`, `f.slack`, `f.human to`. */
   detail: string;
 }
 
@@ -119,6 +120,14 @@ export function flowRequirements(
         if (helperReference(root, namespace).test(text)) declare({ provider, from: 'helper', detail: `f.${namespace}` });
       }
       for (const use of workerCalls(root, text)) need(use.cli === undefined ? fallback : harnessFromCli(use.cli), use.detail);
+      // `f.human(q, { to: "slack:#eng" })` is delivered by Cloud through that
+      // provider, so the deploy must have it connected. Only a literal `to`
+      // can be read here; a computed one (`input.approver`) is resolved by
+      // Cloud at park time against the run's own trigger channel.
+      for (const to of humanRecipients(root, text)) {
+        const provider = humanRecipientProvider(to);
+        if (provider !== undefined) declare({ provider, from: 'human', detail: 'f.human to' });
+      }
     }
   }
 
@@ -180,6 +189,138 @@ function helperReference(root: string, namespace: string): RegExp {
   return new RegExp(`(?:^|[^\\w$.])${root}\\s*(?:\\.\\s*${namespace}\\b|\\[\\s*['"]${namespace}['"]\\s*\\])`, 'u');
 }
 
+/**
+ * The literal `to` of each `f.human(question, { to: "…" })` call in the body.
+ *
+ * Bounded to the call's OWN argument list — the text between its `(` and the
+ * matching `)`, string- and nesting-aware — and within that to the top level
+ * of its options object, so a `to:` in a later call, in a nested object, in
+ * the question string, or in an unrelated `{ to }` of the surrounding code is
+ * never read as this call's recipient. Only a plain string literal counts; a
+ * template with interpolation or an identifier is a computed `to`, resolved
+ * by Cloud at park time.
+ */
+function humanRecipients(root: string, body: string): string[] {
+  const call = new RegExp(`(?:^|[^\\w$.])${root}\\s*\\.\\s*human\\s*\\(`, 'gu');
+  const found: string[] = [];
+  for (const match of body.matchAll(call)) {
+    const open = match.index! + match[0].length - 1;
+    const close = matchingClose(body, open);
+    if (close === -1) continue;
+    const args = body.slice(open + 1, close);
+    const options = secondArgumentObject(args);
+    if (options === undefined) continue;
+    const to = topLevelStringProperty(options, 'to');
+    if (to !== undefined) found.push(to);
+  }
+  return found;
+}
+
+/**
+ * Skip the comment or string starting at `i`, returning the index just past
+ * it; `i` itself when nothing skippable starts there; -1 when unterminated.
+ * Every walker below steps through this, so a `,`, `to:` or bracket inside a
+ * comment or string is never read as syntax.
+ */
+function skipCommentOrString(text: string, i: number): number {
+  const ch = text[i]!;
+  const next = text[i + 1];
+  if (ch === '/' && next === '/') { const end = text.indexOf('\n', i); return end === -1 ? text.length : end + 1; }
+  if (ch === '/' && next === '*') { const end = text.indexOf('*/', i + 2); return end === -1 ? -1 : end + 2; }
+  if (ch === '"' || ch === "'" || ch === '`') { const end = stringEnd(text, i); return end === -1 ? -1 : end + 1; }
+  return i;
+}
+
+/** Index of the `)`/`}`/`]` closing the bracket at `open`, skipping strings, templates and comments; -1 if unbalanced. */
+function matchingClose(text: string, open: number): number {
+  const pairs: Record<string, string> = { '(': ')', '{': '}', '[': ']' };
+  const stack: string[] = [pairs[text[open]!]!];
+  let i = open + 1;
+  while (i < text.length && stack.length > 0) {
+    const skipped = skipCommentOrString(text, i);
+    if (skipped === -1) return -1;
+    if (skipped !== i) { i = skipped; continue; }
+    const ch = text[i]!;
+    if (ch in pairs) stack.push(pairs[ch]!);
+    else if (ch === ')' || ch === '}' || ch === ']') { if (stack.pop() !== ch) return -1; }
+    i += 1;
+  }
+  return stack.length === 0 ? i - 1 : -1;
+}
+
+/** Index of the quote closing the string opening at `start` (template `${…}` skipped); -1 if unterminated. */
+function stringEnd(text: string, start: number): number {
+  const quote = text[start]!;
+  let i = start + 1;
+  while (i < text.length) {
+    const ch = text[i]!;
+    if (ch === '\\') { i += 2; continue; }
+    if (ch === quote) return i;
+    if (quote === '`' && ch === '$' && text[i + 1] === '{') {
+      const end = matchingClose(text, i + 1);
+      if (end === -1) return -1;
+      i = end + 1;
+      continue;
+    }
+    i += 1;
+  }
+  return -1;
+}
+
+/** The `{ … }` that is the call's second top-level argument, or undefined. */
+function secondArgumentObject(args: string): string | undefined {
+  let depth = 0;
+  let i = 0;
+  let commas = 0;
+  while (i < args.length) {
+    const skipped = skipCommentOrString(args, i);
+    if (skipped === -1) return undefined;
+    if (skipped !== i) { i = skipped; continue; }
+    const ch = args[i]!;
+    if (ch === '(' || ch === '{' || ch === '[') {
+      if (depth === 0 && commas === 1 && ch === '{') {
+        const close = matchingClose(args, i);
+        return close === -1 ? undefined : args.slice(i, close + 1);
+      }
+      depth += 1;
+    } else if (ch === ')' || ch === '}' || ch === ']') depth -= 1;
+    else if (ch === ',' && depth === 0) commas += 1;
+    i += 1;
+  }
+  return undefined;
+}
+
+/** The plain string literal value of `name:` at the top level of an object literal, else undefined. */
+function topLevelStringProperty(object: string, name: string): string | undefined {
+  const key = new RegExp(`^(?:${name}|'${name}'|"${name}")\\s*:\\s*`, 'u');
+  let depth = 0;
+  let i = 1; // past the opening brace
+  const end = object.length - 1;
+  while (i < end) {
+    const skipped = skipCommentOrString(object, i);
+    if (skipped === -1) return undefined;
+    if (skipped !== i) { i = skipped; continue; }
+    const ch = object[i]!;
+    if (ch === '(' || ch === '{' || ch === '[') { depth += 1; i += 1; continue; }
+    if (ch === ')' || ch === '}' || ch === ']') { depth -= 1; i += 1; continue; }
+    if (depth === 0 && (i === 1 || /[\s,{/]/u.test(object[i - 1]!))) {
+      const match = key.exec(object.slice(i));
+      if (match !== null) {
+        const valueStart = i + match[0].length;
+        const quote = object[valueStart];
+        if (quote !== '"' && quote !== "'" && quote !== '`') return undefined;
+        const valueEnd = stringEnd(object, valueStart);
+        if (valueEnd === -1) return undefined;
+        const raw = object.slice(valueStart + 1, valueEnd);
+        // An interpolated template is computed; a plain one is a literal.
+        return quote === '`' && /\$\{/u.test(raw) ? undefined : raw.replace(/\\(.)/gu, '$1');
+      }
+    }
+    i += 1;
+  }
+  return undefined;
+}
+
 interface WorkerCall { detail: string; cli?: string }
 
 /**