@relayflows/sdk 2.0.15 → 2.0.17

package/src/cloud-sync.ts

@@ -0,0 +1,315 @@
+import { spawnSync } from 'node:child_process';
+import { createReadStream, createWriteStream, existsSync, lstatSync, mkdtempSync, readdirSync, readlinkSync, rmSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { createGzip } from 'node:zlib';
+import {
+  CloudFlowError, cloudFetch, cloudRequest, cloudRunId, isCloudRecord, type CloudConnectionOptions,
+} from './cloud-http.js';
+
+/**
+ * Code sync for hosted v2 runs, Cloud-API transport only.
+ *
+ * v1's `--sync-code` had two transports: an S3 client with STS credentials and
+ * the Cloud API's own storage route. v2 runs on Cloudflare, so this module
+ * speaks only the second: `prepare` must answer with a `cloud-api` storage
+ * backend, the tarball is `PUT` to `/workflows/runs/<id>/storage/<key>`, and
+ * the sandbox's post-run patch is read from `/workflows/runs/<id>/patch`. A
+ * `prepare` that hands back anything else is refused before any upload — the
+ * SDK never carries an AWS dependency and never sends code to a bucket it did
+ * not get through the Cloud API.
+ */
+
+/** Uncompressed bytes. Matches the sandbox's extraction budget with headroom. */
+export const MAX_SYNC_BYTES = 256 * 1024 * 1024;
+const ALWAYS_SKIPPED = new Set(['.git', 'node_modules']);
+const CODE_KEY = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u;
+
+export interface PreparedCloudSync {
+  runId: string;
+  codeKey: string;
+  /** Run-scoped upload credential from `prepare`; falls back to the session token. */
+  uploadToken?: string;
+}
+
+/** `POST /api/v1/workflows/prepare`, refusing every non-Cloud-API storage backend. */
+export async function prepareCloudSync(options: CloudConnectionOptions): Promise<PreparedCloudSync> {
+  const receipt = await cloudFetch('/api/v1/workflows/prepare', options, { method: 'POST' });
+  if (!isCloudRecord(receipt)) throw new CloudFlowError('invalid_response', 'Cloud prepare returned a non-object.');
+  const storage = isCloudRecord(receipt.workflowStorage) ? receipt.workflowStorage : undefined;
+  const credentials = isCloudRecord(receipt.s3Credentials) ? receipt.s3Credentials : undefined;
+  const backend = storage?.backend ?? credentials?.backend;
+  if (backend !== 'cloud-api') {
+    throw new CloudFlowError('unsupported_storage_backend',
+      'Cloud offered a workflow storage backend other than the Cloud API (R2). '
+      + 'flows v2 syncs code only through the Cloud API; it never uploads to AWS directly.');
+  }
+  const codeKey = typeof receipt.s3CodeKey === 'string' ? receipt.s3CodeKey : '';
+  if (!CODE_KEY.test(codeKey)) throw new CloudFlowError('invalid_response', 'Cloud prepare returned an unusable code key.');
+  const uploadToken = credentials?.cloudApiAccessToken;
+  if (uploadToken !== undefined && typeof uploadToken !== 'string') {
+    throw new CloudFlowError('invalid_response', 'Cloud prepare returned an unusable storage credential.');
+  }
+  return {
+    runId: cloudRunId(receipt.runId), codeKey,
+    ...(uploadToken === undefined ? {} : { uploadToken }),
+  };
+}
+
+export interface PackedTree {
+  /** The gzip'd ustar, spooled to a temporary file; `dispose()` removes it. */
+  archivePath: string;
+  /** Archive members, `root`-relative POSIX paths, sorted. */
+  files: string[];
+  /** Uncompressed byte total across regular files. */
+  bytes: number;
+  /** Symlinks left out because their target resolves outside `root`. */
+  skippedLinks: string[];
+  dispose(): void;
+}
+
+/**
+ * gzip'd ustar of the working tree at `root`, streamed to a temporary file so
+ * the peak footprint is one file plus the compressor's window, never the
+ * whole tree. Inside a Git checkout the member list is `git ls-files --cached
+ * --others --exclude-standard`, so `.gitignore` governs and untracked-but-
+ * not-ignored files ride along, as they do in v1. Outside Git, every regular
+ * file and in-tree symlink except `.git`/`node_modules`. A Git failure other
+ * than "not a repository" is refused rather than silently widened to the walk:
+ * an ignored `.env` must never reach Cloud because `git` was missing or the
+ * index was locked. Executable bits survive; symlinks whose target leaves the
+ * tree are dropped and reported, since on the host they would point at
+ * whatever happens to live at that path. Ordering and mtimes are
+ * deterministic, so the same tree packs to the same bytes.
+ */
+export async function packWorkingTree(root: string): Promise<PackedTree> {
+  const absoluteRoot = resolve(root);
+  const files = listTreeFiles(absoluteRoot);
+  const spool = mkdtempSync(join(tmpdir(), 'flows-sync-'));
+  const archivePath = join(spool, 'code.tar.gz');
+  const dispose = (): void => rmSync(spool, { recursive: true, force: true });
+  const members: string[] = [];
+  const skippedLinks: string[] = [];
+  let bytes = 0;
+  async function* entries(): AsyncGenerator<Buffer | NodeJS.ReadableStream> {
+    for (const path of files) {
+      const absolute = join(absoluteRoot, ...path.split('/'));
+      const stat = lstatSync(absolute);
+      if (stat.isSymbolicLink()) {
+        const target = readlinkSync(absolute);
+        const relativeTarget = relative(absoluteRoot, resolve(dirname(absolute), target));
+        if (isAbsolute(target) || relativeTarget === '..' || relativeTarget.startsWith(`..${sep}`)) {
+          skippedLinks.push(path);
+          continue;
+        }
+        members.push(path);
+        yield ustarHeader(path, 0, '2', 0o777, target);
+        continue;
+      }
+      if (!stat.isFile()) continue;
+      bytes += stat.size;
+      if (bytes > MAX_SYNC_BYTES) {
+        throw new CloudFlowError('sync_too_large',
+          `The working tree exceeds the ${MAX_SYNC_BYTES}-byte code sync limit; narrow it with .gitignore.`);
+      }
+      members.push(path);
+      yield ustarHeader(path, stat.size, '0', stat.mode & 0o111 ? 0o755 : 0o644);
+      yield createReadStream(absolute);
+      const padding = (512 - (stat.size % 512)) % 512;
+      if (padding) yield Buffer.alloc(padding);
+    }
+    yield Buffer.alloc(1024);
+  }
+  try {
+    await pipeline(Readable.from(flatten(entries())), createGzip({ level: 6 }), createWriteStream(archivePath));
+  } catch (error) {
+    dispose();
+    throw error;
+  }
+  return { archivePath, files: members, bytes, skippedLinks, dispose };
+}
+
+/** Yield file streams chunk by chunk so `Readable.from` never buffers a whole file. */
+async function* flatten(source: AsyncGenerator<Buffer | NodeJS.ReadableStream>): AsyncGenerator<Buffer> {
+  for await (const part of source) {
+    if (Buffer.isBuffer(part)) { yield part; continue; }
+    for await (const chunk of part as AsyncIterable<Buffer>) yield chunk;
+  }
+}
+
+/** The nearest `.git` entry at `root` or any ancestor — the checkout a .gitignore would belong to. */
+function nearestGitEntry(root: string): string | undefined {
+  let directory = root;
+  while (true) {
+    if (existsSync(join(directory, '.git'))) return join(directory, '.git');
+    const parent = dirname(directory);
+    if (parent === directory) return undefined;
+    directory = parent;
+  }
+}
+
+function listTreeFiles(root: string): string[] {
+  const inside = spawnSync('git', ['-C', root, 'rev-parse', '--is-inside-work-tree'], { encoding: 'utf8' });
+  if (inside.error !== undefined) {
+    // Without git there is no way to honour a .gitignore, so a tree that has
+    // one anywhere above it cannot be described honestly; a tree with none is
+    // a plain directory and can be walked.
+    const entry = nearestGitEntry(root);
+    if (entry !== undefined) {
+      throw new CloudFlowError('sync_unsupported',
+        `git is not available (${summarize(inside.error.message)}) but ${entry} exists; `
+        + 'refusing to upload a checkout without its .gitignore.');
+    }
+  }
+  const notARepository = inside.error !== undefined
+    || (inside.status !== 0 && /not a git repository/iu.test(inside.stderr));
+  let candidates: string[];
+  if (notARepository) {
+    // A `.git` that git itself cannot read — here or in a parent — is a broken
+    // checkout, not a plain directory: its .gitignore was meant to apply, so
+    // walking would upload exactly what it excluded.
+    const entry = nearestGitEntry(root);
+    if (entry !== undefined) {
+      throw new CloudFlowError('sync_unsupported',
+        `${entry} exists but git cannot read it (${summarize(inside.stderr ?? inside.error?.message)}); `
+        + 'refusing to upload a checkout without its .gitignore.');
+    }
+    candidates = [];
+    walk(root, root, candidates);
+  } else {
+    if (inside.status !== 0 || inside.stdout.trim() !== 'true') {
+      throw new CloudFlowError('sync_unsupported',
+        `git could not describe ${root} (${summarize(inside.stderr)}); refusing to guess which files to upload.`);
+    }
+    const git = spawnSync('git', ['-C', root, 'ls-files', '-z', '--cached', '--others', '--exclude-standard'],
+      { encoding: 'utf8', maxBuffer: 256 * 1024 * 1024 });
+    if (git.status !== 0) {
+      throw new CloudFlowError('sync_unsupported',
+        `git ls-files failed in ${root} (${summarize(git.stderr)}); refusing to upload without .gitignore.`);
+    }
+    candidates = git.stdout.split('\0').filter(Boolean);
+  }
+  const files = new Set<string>();
+  for (const candidate of candidates) {
+    const path = candidate.split(sep).join('/');
+    const segments = path.split('/');
+    if (segments.some(segment => ALWAYS_SKIPPED.has(segment) || segment === '..' || segment === '')) continue;
+    let stat;
+    try { stat = lstatSync(join(root, ...segments)); } catch { continue; }
+    if (stat.isFile() || stat.isSymbolicLink()) files.add(path);
+  }
+  return [...files].sort();
+}
+
+function summarize(stderr: string | undefined): string {
+  const line = (stderr ?? '').split('\n').map(l => l.trim()).find(Boolean) ?? 'no diagnostic';
+  return line.length > 160 ? `${line.slice(0, 157)}...` : line;
+}
+
+function walk(root: string, current: string, out: string[]): void {
+  for (const entry of readdirSync(current, { withFileTypes: true })) {
+    if (ALWAYS_SKIPPED.has(entry.name)) continue;
+    const path = join(current, entry.name);
+    if (entry.isDirectory()) walk(root, path, out);
+    else if (entry.isFile() || entry.isSymbolicLink()) out.push(relative(root, path));
+  }
+}
+
+/** POSIX ustar header. Names beyond the 100+155 split are refused, not truncated. */
+function ustarHeader(path: string, size: number, type: '0' | '2', mode: number, link = ''): Buffer {
+  let name = path;
+  let prefix = '';
+  if (Buffer.byteLength(name) > 100) {
+    const cut = name.lastIndexOf('/', 154);
+    if (cut <= 0 || Buffer.byteLength(name.slice(cut + 1)) > 100 || Buffer.byteLength(name.slice(0, cut)) > 155) {
+      throw new CloudFlowError('sync_unsupported', `Path "${path}" is too long for the code sync archive.`);
+    }
+    prefix = name.slice(0, cut);
+    name = name.slice(cut + 1);
+  }
+  if (Buffer.byteLength(link) > 100) {
+    throw new CloudFlowError('sync_unsupported', `Symlink target of "${path}" is too long for the code sync archive.`);
+  }
+  const header = Buffer.alloc(512);
+  header.write(name, 0, 100);
+  header.write(mode.toString(8).padStart(7, '0'), 100, 8);
+  header.write('0000000', 108, 8);
+  header.write('0000000', 116, 8);
+  header.write(size.toString(8).padStart(11, '0'), 124, 12);
+  header.write('00000000000', 136, 12);
+  header.write('        ', 148, 8);
+  header.write(type, 156, 1);
+  header.write(link, 157, 100);
+  header.write('ustar\0', 257, 6);
+  header.write('00', 263, 2);
+  header.write(prefix, 345, 155);
+  let checksum = 0;
+  for (const byte of header) checksum += byte;
+  header.write(checksum.toString(8).padStart(6, '0') + '\0 ', 148, 8);
+  return header;
+}
+
+/** `PUT` the archive through the Cloud API; the run-scoped credential wins when present. */
+export async function uploadCloudCode(
+  prepared: PreparedCloudSync, packed: PackedTree, options: CloudConnectionOptions,
+): Promise<void> {
+  // The request needs a sized body, so the compressed archive is read back
+  // once; that is the one copy that has to exist, and it is the small one.
+  const tarball = await readFile(packed.archivePath);
+  await cloudFetch(
+    `/api/v1/workflows/runs/${encodeURIComponent(prepared.runId)}/storage/${encodeURIComponent(prepared.codeKey)}`,
+    { ...options, requestTimeoutMs: options.requestTimeoutMs ?? 300_000 },
+    { method: 'PUT', body: tarball, contentType: 'application/gzip',
+      ...(prepared.uploadToken === undefined ? {} : { bearerToken: prepared.uploadToken }) },
+  );
+}
+
+export interface CloudPatch {
+  patch: string;
+  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> {
+  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.`);
+  }
+  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 };
+}
+
+/** 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);
+  }
+  return paths;
+}
+
+/**
+ * `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.
+ */
+export function applyCloudPatch(root: string, patch: string): void {
+  const args = ['-C', resolve(root), 'apply', '--whitespace=nowarn'];
+  const check = spawnSync('git', [...args, '--check'], { input: patch, encoding: 'utf8' });
+  if (check.status !== 0) {
+    throw new CloudFlowError('patch_conflict',
+      `The patch does not apply cleanly to ${resolve(root)}:\n${check.stderr.trim()}`);
+  }
+  const apply = spawnSync('git', args, { input: patch, encoding: 'utf8' });
+  if (apply.status !== 0) {
+    throw new CloudFlowError('patch_conflict', `git apply failed:\n${apply.stderr.trim()}`);
+  }
+}

package/src/failure-kinds.ts

@@ -85,6 +85,13 @@ export const PREFLIGHT_WARNING_KINDS = [
  * serving and this invocation was told not to start one" (`--no-spawn`), while
  * a spawn that was attempted and did not produce a serving daemon names which
  * step failed. All of them are still exit 2 — refused before a journal write.
+ *
+ * Despite the name, this list is the run-outcome diagnostic vocabulary rather
+ * than failures alone. `run_parked` has always sat here and exits 3 under
+ * severity `parked`; `run_declined` joins it, exiting 0 under severity
+ * `declined`. The mismatch between the constant's name and its non-failure
+ * members is pre-existing — renaming it is a separate change, and neither this
+ * list nor `RunDiagnostic` is exported from the package index.
  */
 export const RUN_FAILURE_KINDS = [
   'bucket_unconfigured',
@@ -102,7 +109,10 @@ export const RUN_FAILURE_KINDS = [
   'relayflowd_not_found',
   'protocol_error',
   'run_parked',
+  'run_declined',
   'run_unavailable',
+  /** A predicate `.gate(fn)` judged false; the verdict is journaled as `<step>.gate`. */
+  'gate_failed',
 ] as const;
 
 /**

package/src/index.ts

@@ -63,6 +63,19 @@ export {
   runInCloud, getCloudFlowRun, waitForCloudFlowRun,
   type CloudFlowSource, type RunInCloudOptions, type CloudRunReceipt, type CloudRunState,
 } from './cloud-run.js';
+export {
+  downloadCloudPatch, applyCloudPatch, packWorkingTree, patchedPaths, MAX_SYNC_BYTES,
+  type CloudPatch, type PackedTree,
+} from './cloud-sync.js';
+export {
+  scheduleInCloud, listCloudSchedules, unscheduleInCloud, everyToCron, declaredScheduleCron,
+  type ScheduleInCloudInput, type CloudSchedule,
+} from './cloud-schedule.js';
+export { prepareCloudSubmission, cloudSubmissionBody, type CloudSubmission } from './cloud-run.js';
+export {
+  deployToCloud, listCloudDeployments, undeployFromCloud, parseRepository, parseTriggerSource, FLOW_TRIGGER_PROVIDERS,
+  type DeployToCloudInput, type CloudDeployment, type CloudDeploymentSummary, type FlowTriggerSource, type FlowTriggerProvider,
+} from './cloud-deploy.js';
 
 export { canonicalize, specHash } from './canonical.js';
 export {
@@ -225,3 +238,4 @@ export { createFlow, type CreateFlowOptions, type CreatedFlow } from './create-f
 
 export { renderProgress, type ProgressEvent } from './progress.js';
 export { webhookTriggerSpec } from './trigger-executor.js';
+export { scheduleTriggerSpec, scheduleLowering, SCHEDULE_EXECUTOR, type ScheduleLowering } from './schedule-trigger.js';

package/src/named-gate-lowering.ts

@@ -60,6 +60,15 @@ export function lowerNamedGates(steps: readonly StepSpec[]): StepSpec[] {
 }
 
 function gateCommand(gate: NamedDataGate, deterministic: boolean): string {
+  if (gate.type === 'artifact_exists') {
+    // The whole output envelope is bound; the verdict is whether the worker's
+    // journaled `artifacts` list names the path. Nothing on disk is consulted,
+    // so the journal alone reproduces the verdict on replay and resume.
+    return `node -e ${quote(`const input=JSON.parse(process.env.FLOWS_INPUT);
+const output=input.output;
+const artifacts=output!==null&&typeof output==='object'&&Array.isArray(output.artifacts)?output.artifacts:[];
+process.exit(artifacts.includes(${JSON.stringify(gate.path)})?0:1);`)}`;
+  }
   const path = gate.type === 'subprocess_gate' ? gate.from_output
     : gate.type === 'word_count_bounds' ? undefined : gate.in_output_at;
   // Only compiler-owned code is serialized. Author strings are JSON literals;

package/src/named-gates.ts

@@ -2,7 +2,7 @@ import { RE2JS } from 're2js';
 import type { NamedDataGate, VerificationSpec } from './spec.js';
 
 export const NAMED_GATE_FAILURE_KINDS = [
-  'unknown_gate_kind', 'gate_pattern_invalid', 'gate_command_missing', 'gate_bound_invalid',
+  'unknown_gate_kind', 'gate_pattern_invalid', 'gate_command_missing', 'gate_bound_invalid', 'gate_path_invalid',
 ] as const;
 export type NamedGateFailureKind = typeof NAMED_GATE_FAILURE_KINDS[number];
 
@@ -11,6 +11,7 @@ export const NAMED_GATE_KEYS: Record<NamedDataGate['type'], readonly string[]> =
   subprocess_gate: ['type', 'command', 'from_output'],
   word_count_bounds: ['type', 'min', 'max'],
   regex_match: ['type', 'pattern', 'in_output_at', 'flags'],
+  artifact_exists: ['type', 'path'],
 };
 
 export function isNamedGate(gate: VerificationSpec | undefined): gate is NamedDataGate {
@@ -45,6 +46,15 @@ export function namedGateErrors(gate: Record<string, unknown>, input: unknown, a
         errors.push(`${at}.command: gate_command_missing: expected a non-empty shell command`);
       }
       break;
+    case 'artifact_exists': {
+      const path = gate.path;
+      const segments = typeof path === 'string' ? path.split('/') : [];
+      if (typeof path !== 'string' || !path.trim() || path.includes('\0') || path.startsWith('/')
+        || path !== path.trim() || segments.some(segment => segment === '' || segment === '.' || segment === '..')) {
+        errors.push(`${at}.path: gate_path_invalid: expected a relative POSIX path without empty, "." or ".." segments`);
+      }
+      break;
+    }
     case 'word_count_bounds': {
       const { min, max } = gate;
       if ([min, max].some(n => n !== undefined && (!Number.isSafeInteger(n) || (n as number) < 0))

package/src/preflight.ts

@@ -133,7 +133,9 @@ export function preflightWebhookTriggers(
   triggers: readonly TriggerSource[],
   executors: readonly string[],
 ): PreflightRefusal[] {
-  return [...new Set(triggers.map(trigger => trigger.name))]
+  // Schedule sources are driven by the CLI's own tick runner, not an inbox
+  // executor, so they need no flows.json registration.
+  return [...new Set(triggers.filter(trigger => trigger.kind === 'webhook').map(trigger => trigger.name))]
     .filter(name => !executors.includes(name))
     .map(name => ({
       severity: 'refusal',
@@ -584,8 +586,8 @@ function warnOnUnprovableEffects(
   diagnostics: PreflightDiagnostic[],
 ): void {
   if (step.type !== 'deterministic') return;
-  const binary = firstCommandWord(step.command);
-  if (binary === undefined) {
+  const first = firstCommandWordDetailed(step.command);
+  if (first === undefined) {
     diagnostics.push({
       severity: 'warning',
       kind: 'command_unprovable',
@@ -594,6 +596,19 @@ function warnOnUnprovableEffects(
     });
     return;
   }
+  if (first.shell) {
+    // `set -e`, `if …`, `cd …`: the shell supplies these, so there is nothing
+    // to resolve on PATH — and nothing to refuse. What they go on to run is
+    // the rest of the script, whose effects preflight never claimed to prove.
+    diagnostics.push({
+      severity: 'warning',
+      kind: 'unprovable_effects',
+      stepId: step.id,
+      message: `Step "${step.id}" starts with the shell ${first.kind} "${first.word}", whose effects cannot be proven before execution.`,
+    });
+    return;
+  }
+  const binary = first.word;
   let exists: boolean;
   try {
     exists = probes.command(binary);
@@ -628,7 +643,115 @@ function warnOnUnprovableEffects(
     });
 }
 
+/** POSIX special builtins and reserved words: the shell supplies them, PATH never does. */
+const SHELL_SPECIAL_BUILTINS = new Set([
+  '.', ':', 'break', 'continue', 'eval', 'exec', 'exit', 'export', 'readonly', 'return', 'set',
+  'shift', 'times', 'trap', 'unset',
+  // Regular builtins that no sane flow ships as an executable.
+  'cd', 'alias', 'unalias', 'local', 'source', 'wait', 'umask', 'ulimit', 'read', 'command', 'type',
+]);
+const SHELL_RESERVED_WORDS = new Set([
+  'if', 'then', 'else', 'elif', 'fi', 'for', 'while', 'until', 'do', 'done', 'case', 'esac', 'in',
+  'function', 'select', 'time', '{', '}', '(', ')', '!', '[[', ']]',
+]);
+
+interface FirstCommandWord {
+  word: string;
+  /** True when the shell itself provides the word, so there is nothing to look up. */
+  shell: boolean;
+  kind: 'command' | 'builtin' | 'reserved word';
+}
+
 function firstCommandWord(command: string): string | undefined {
+  return firstCommandWordDetailed(command)?.word;
+}
+
+function firstCommandWordDetailed(command: string): FirstCommandWord | undefined {
+  // A lightweight lexical pass — not a shell parser. It walks the script once,
+  // quote-aware: comments outside quotes are dropped, quoted text is opaque
+  // (an apostrophe in `# don't` or a `<<EOF` inside `VALUE='<<EOF'` is data),
+  // and the script is split into simple-command segments on unquoted `;`,
+  // `&&`, `||`, `|` and newlines. The first segment that is not only
+  // assignments and redirections holds the command word (cloud#3777).
+  //
+  // A heredoc opener or a quote left open at the end of the script means the
+  // following text is data the shell never executes; if no command word was
+  // found before it, the answer is "cannot be proven", not "missing".
+  const segments = lexSimpleCommands(command);
+  if (segments === undefined) return undefined;
+  for (const segment of segments) {
+    const remainder = stripShellPrefixes(segment);
+    if (remainder === '') continue;
+    const match = remainder.match(/^(?:"([^"]*)"|'([^']*)'|([^\s]+))/);
+    const word = match?.[1] ?? match?.[2] ?? match?.[3];
+    if (word === undefined || word === '') continue;
+    if (SHELL_SPECIAL_BUILTINS.has(word)) return { word, shell: true, kind: 'builtin' };
+    if (SHELL_RESERVED_WORDS.has(word)) return { word, shell: true, kind: 'reserved word' };
+    return { word, shell: false, kind: 'command' };
+  }
+  return undefined;
+}
+
+/**
+ * Split a script into simple-command segments, comments removed, quotes kept.
+ * Returns undefined when a heredoc or an unclosed quote begins before any
+ * segment could be completed past it — the rest is data.
+ */
+function lexSimpleCommands(script: string): string[] | undefined {
+  const segments: string[] = [];
+  let current = '';
+  let quote: string | undefined;
+  let heredoc = false;
+  const flush = (): void => {
+    if (current.trim() !== '') segments.push(current.trim());
+    current = '';
+  };
+  for (let i = 0; i < script.length; i += 1) {
+    const char = script[i]!;
+    if (quote !== undefined) {
+      current += char;
+      if (char === '\\' && quote === '"' && i + 1 < script.length) { current += script[++i]; continue; }
+      if (char === quote) quote = undefined;
+      continue;
+    }
+    if (char === '\\' && i + 1 < script.length) { current += char + script[++i]; continue; }
+    if (char === '"' || char === "'") { quote = char; current += char; continue; }
+    if (char === '#' && (current === '' || /\s$/.test(current))) {
+      // Comment to end of line, outside quotes only.
+      while (i + 1 < script.length && script[i + 1] !== '\n') i += 1;
+      continue;
+    }
+    if (char === '<' && script[i + 1] === '<') {
+      // A heredoc: everything after this line is its body, so the current
+      // segment is the last one the shell reads as a command.
+      heredoc = true;
+      while (i + 1 < script.length && script[i + 1] !== '\n') i += 1;
+      flush();
+      break;
+    }
+    if (char === '\n' || char === ';') { flush(); continue; }
+    if ((char === '&' && script[i + 1] === '&') || (char === '|' && script[i + 1] === '|')) { flush(); i += 1; continue; }
+    if (char === '|') { flush(); continue; }
+    if (char === '&') {
+      // `&` is a boundary only as a background operator. In `2>&1`, `>&2`,
+      // `<&0` and `&>file` it is part of a redirection: the `&` after a `>`
+      // or `<` (with an optional fd number before that), or the `&` that
+      // starts `&>`.
+      const afterRedirect = /[<>]\s*$/.test(current);
+      if (afterRedirect || script[i + 1] === '>') { current += char; continue; }
+      flush();
+      continue;
+    }
+    current += char;
+  }
+  if (!heredoc && quote === undefined) flush();
+  // Whatever was accumulated when a heredoc or an open quote cut the scan is
+  // not a complete command; only the segments closed before it count.
+  if (segments.length === 0 && (heredoc || quote !== undefined)) return undefined;
+  return segments;
+}
+
+function stripShellPrefixes(segment: string): string {
   // Skip the shell prefixes that can legally precede the command word.
   //
   // Review caught this on PR #47: the new path-like refusal keys on the first
@@ -638,16 +761,16 @@ function firstCommandWord(command: string): string | undefined {
   // which is exactly the "refusing would reject valid flows" failure the warn
   // behaviour exists to avoid.
   //
-  // An assignment is NAME=value with a shell-legal name; a redirection starts
-  // with < or > (optionally with a leading fd number). Neither is the command.
-  let rest = command.trim();
+  // An assignment is NAME=value with a shell-legal name and an opaque quoted
+  // value; a redirection starts with < or > (optionally with a leading fd
+  // number). Neither is the command. Segments never contain `;`/newlines.
+  let rest = segment;
   for (;;) {
-    const prefix = rest.match(/^(?:[A-Za-z_][A-Za-z0-9_]*=(?:"[^"]*"|'[^']*'|[^\s]*)|[0-9]*[<>]{1,2}\s*[^\s]+)\s+/);
+    const prefix = rest.match(/^(?:[A-Za-z_][A-Za-z0-9_]*=(?:"(?:[^"\\]|\\.)*"|'[^']*'|[^\s]*)|(?:[0-9]*[<>]{1,2}&?|&>>?)\s*[^\s]+)(?:\s+|$)/);
     if (prefix === null) break;
     rest = rest.slice(prefix[0].length);
   }
-  const match = rest.match(/^(?:"([^"]+)"|'([^']+)'|([^\s]+))/);
-  return match?.[1] ?? match?.[2] ?? match?.[3];
+  return rest.trim();
 }
 
 function probeNamedGate(step: StepSpec, probes: PreflightProbes, diagnostics: PreflightDiagnostic[]): void {

package/src/schedule-trigger.ts

@@ -0,0 +1,73 @@
+import {
+  TICK_EVENT_TYPE, TICK_DEDUPE_KEY_TEMPLATE,
+} from './tick-source.js';
+import { cronMaxGapMs, parseCron, scheduleIdFor, type ScheduleTriggerSource } from '@relayflows/surface';
+import type { TriggerSpec } from './spec.js';
+
+/**
+ * The executor name a schedule subscription is registered under. It is the
+ * name `flows tick start` submits through, and `testdata/tick-heartbeat.flow.yaml`
+ * binds by hand; unlike a provider inbox it needs no `flows.json` entry, because
+ * the tick source ships with the CLI itself.
+ */
+export const SCHEDULE_EXECUTOR = 'flows.tick';
+
+/** Three missed slots before the kernel's liveness sweep journals `subscription.stale`. */
+export const SCHEDULE_STALE_SLOTS = 3;
+
+export interface ScheduleLowering {
+  readonly scheduleId: string;
+  /** The `flows tick start --interval-ms` value, when the schedule is exactly a tick grid. */
+  readonly intervalMs?: number;
+  /** The `flows tick start --epoch-ms` value: the grid's phase past the Unix epoch. Present with `intervalMs`. */
+  readonly epochMs?: number;
+  readonly cron?: string;
+  readonly tz?: string;
+  /** The silence budget the subscription declares, in milliseconds. */
+  readonly staleAfterMs?: number;
+  /** Why the local tick runner cannot drive this schedule, when it cannot. */
+  readonly localUnsupported?: string;
+}
+
+export function scheduleLowering(flowName: string, source: ScheduleTriggerSource): ScheduleLowering {
+  const scheduleId = scheduleIdFor(flowName, source);
+  const base = {
+    scheduleId,
+    ...(source.cron === undefined ? {} : { cron: source.cron }),
+    ...(source.tz === undefined ? {} : { tz: source.tz }),
+  };
+  if (source.intervalMs === undefined || source.epochMs === undefined) {
+    // Not a grid. The kernel's default silence budget is five minutes, which
+    // a daily cron would trip every day at 09:05 — so the budget is declared
+    // from the cron's own longest quiet period instead of left to default.
+    const gap = source.cron === undefined ? undefined : cronMaxGapMs(parseCron(source.cron));
+    return {
+      ...base,
+      ...(gap === undefined ? {} : { staleAfterMs: gap * SCHEDULE_STALE_SLOTS }),
+      localUnsupported: `cron "${source.cron}"${source.tz === undefined ? '' : ` in ${source.tz}`} is not a UTC tick grid `
+        + '(a fixed period dividing the hour or day, one fixed phase); the local tick runner cannot reproduce it. '
+        + 'Run it on Cloud with `flows schedule`, or declare schedule.every(...) for local runs.',
+    };
+  }
+  return { ...base, intervalMs: source.intervalMs, epochMs: source.epochMs, staleAfterMs: source.intervalMs * SCHEDULE_STALE_SLOTS };
+}
+
+/**
+ * Lower a `schedule.*` declaration to the `flows.tick` subscription the tick
+ * source drives: one event type, a pattern pinned to this flow's schedule id,
+ * the shared dedupe key so a re-delivered slot spawns one run, and a silence
+ * budget of three slots — three intervals for a grid, three times the cron's
+ * longest quiet period otherwise — so a dead source is journaled rather than
+ * silent, and a weekly cron is not declared stale on Monday at 09:05.
+ */
+export function scheduleTriggerSpec(id: string, flowName: string, source: ScheduleTriggerSource): TriggerSpec {
+  const lowering = scheduleLowering(flowName, source);
+  return {
+    id,
+    executor: SCHEDULE_EXECUTOR,
+    eventType: TICK_EVENT_TYPE,
+    pattern: { schedule_id: lowering.scheduleId },
+    dedupeKeyTemplate: TICK_DEDUPE_KEY_TEMPLATE,
+    ...(lowering.staleAfterMs === undefined ? {} : { staleAfterMs: lowering.staleAfterMs }),
+  };
+}