@relayflows/sdk 2.0.16 → 2.0.17

package/src/authored-flow-operation.ts

@@ -8,7 +8,7 @@ import {
 
 /** Slice-P kinds the surface `.gate(config)` accepts and the SDK lowers. */
 const NAMED_GATE_KINDS = new Set([
-  'references_input', 'subprocess_gate', 'word_count_bounds', 'regex_match',
+  'references_input', 'subprocess_gate', 'word_count_bounds', 'regex_match', 'artifact_exists',
 ]);
 
 function isNamedGateConfig(candidate: unknown): candidate is NamedGate {
@@ -31,6 +31,14 @@ export class AuthoredFlowOperation<T> {
    * still throws `unsupported_gate` and never sets this field.
    */
   namedGate: NamedGate | undefined = undefined;
+  /**
+   * Predicate gate attached via `.gate(fn, because?)`. Author code: it runs
+   * in this process after the step completes, and its verdict is journaled as
+   * a lowered `<id>.gate` deterministic step (docs/SURFACE.md §6), so replay
+   * and resume see the recorded verdict and never re-run the closure. The
+   * function itself is never serialized. `flows check` cannot prove it.
+   */
+  predicateGate: { predicate: (value: T) => boolean; because?: string } | undefined = undefined;
   private state: OperationState = 'created';
   private thenInvoked = false;
   private rootFailureRecorded = false;
@@ -61,20 +69,29 @@ export class AuthoredFlowOperation<T> {
     const operation = this;
     const step: Step<T> = {
       gate(configOrPredicate: NamedGate | ((value: T) => boolean), _because?: string): Step<T> {
+        if (operation.namedGate !== undefined || operation.predicateGate !== undefined) {
+          throw new AuthoredFlowExecutionError('unsupported_gate', 'a step takes one .gate().');
+        }
         if (isNamedGateConfig(configOrPredicate)) {
           // Config-object gate: lowers into the compiled StepSpec's
           // `verification:` field via slice-P named-gate lowering.
           operation.namedGate = configOrPredicate;
           return step;
         }
-        // Predicate gate: closures cannot be journaled (covenant 1
-        // journal-as-truth). Refuse — authors should use a config-object
-        // gate or the declarative `verification:` block.
-        throw new AuthoredFlowExecutionError(
-          'unsupported_gate',
-          'postfix .gate(predicate) closures cannot be journaled; '
-            + 'use .gate({type: "…", …}) with a slice-P named gate instead.',
-        );
+        // Predicate gate: runtime control flow. The closure cannot be
+        // journaled, but its VERDICT can — the executor runs it once after
+        // the step completes and records pass/fail as a `<id>.gate` step.
+        if (typeof configOrPredicate !== 'function') {
+          throw new AuthoredFlowExecutionError(
+            'unsupported_gate',
+            '.gate() takes a named gate config ({type: "…", …}) or a predicate function.',
+          );
+        }
+        if (_because !== undefined && typeof _because !== 'string') {
+          throw new AuthoredFlowExecutionError('unsupported_gate', '.gate(predicate, because) takes a string reason.');
+        }
+        operation.predicateGate = { predicate: configOrPredicate, ...(_because === undefined ? {} : { because: _because }) };
+        return step;
       },
       then<TResult1 = T, TResult2 = never>(
         onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | null,
@@ -144,7 +161,15 @@ export class AuthoredFlowOperation<T> {
     try {
       this.assertCanStart();
       this.state = 'running';
-      const value = await this.start();
+      const started = await this.start();
+      // The predicate gate, when present, is applied here for every kind of
+      // operation, so a helper or plugin step cannot carry a gate that never
+      // runs. The executor installs the applier; without one, a predicate
+      // gate is refused rather than skipped.
+      const value = this.predicateGate === undefined ? started
+        : this.scope.applyPredicateGate === undefined
+          ? (() => { throw new AuthoredFlowExecutionError('unsupported_gate', 'this runtime cannot apply predicate gates'); })()
+          : await this.scope.applyPredicateGate(this as unknown as { id: string; predicateGate: unknown }, started);
       this.state = 'fulfilled';
       this.resolve(value);
     } catch (error) {

package/src/authored-node-runner.ts

@@ -161,30 +161,44 @@ export async function verifyAuthoredNodeResult(
   result: AuthoredFlowExecutionResult, metadata: AuthoredRootMetadata,
   rootRunId: string, socketPath: string,
 ): Promise<void> {
-  const invalid = (): never => { throw new Error('authored runtime result has no matching durable completion'); };
+  const invalid = (why = ''): never => { throw new Error(`authored runtime result has no matching durable completion${process.env['FLOWS_VERIFIER_DEBUG'] && why ? ` (${why})` : ''}`); };
   if (result.rootRunId !== rootRunId || result.name !== metadata.flowName
     || !isLoweredCompletion(result.completionReason)
-    || !Array.isArray(result.journalSteps) || result.journalSteps.length === 0) invalid();
+    || !Array.isArray(result.journalSteps) || result.journalSteps.length === 0) invalid('frame');
   const terminal = result.journalSteps.at(-1)!;
-  if (!terminal || !/^complete-[1-9][0-9]*$/.test(terminal.id)) invalid();
+  if (!terminal || !/^complete-[1-9][0-9]*$/.test(terminal.id)) invalid('terminal');
   const count = Number(terminal.id.slice('complete-'.length));
-  if (!Number.isSafeInteger(count) || result.journalSteps.length !== count) invalid();
+  // A predicate gate is journaled as `<step>.gate`: a child run subordinate
+  // to the authored step it judges, in the same `<step>.gate` shape a named
+  // gate lowers to inside its step's own spec. Neither consumes an ordinal —
+  // `complete-N` counts the operations the author wrote (SURFACE.md §6) —
+  // so gates are set aside from the count and the contiguity check, and
+  // verified separately: every gate must name a claimed parent, and is then
+  // held to the same durable-completion evidence as any other child run.
+  const isGate = (id: string): boolean => /\.gate$/.test(id);
+  const authored = result.journalSteps.filter(step => typeof step?.id === 'string' && !isGate(step.id));
+  const gates = result.journalSteps.filter(step => typeof step?.id === 'string' && isGate(step.id));
+  if (!Number.isSafeInteger(count) || authored.length !== count || isGate(terminal.id)) invalid(`count ${authored.length}!=${count}`);
   const ordinal = (id: string): number => Number(/-([1-9][0-9]*)$/.exec(id)?.[1]);
   // Parallel awaits may finish in either order; validate a copy in declaration order.
-  const ordered = [...result.journalSteps].sort((a,b)=>ordinal(a.id)-ordinal(b.id));
+  const ordered = [...authored].sort((a,b)=>ordinal(a.id)-ordinal(b.id));
+  const authoredIds = new Set(ordered.map(step => step.id));
+  for (const gate of gates) {
+    if (!authoredIds.has(gate.id.slice(0, -'.gate'.length))) invalid(`orphan ${gate.id}`);
+  }
   const runs = new Set<string>();
   const journal = new JournalClient(socketPath);
   await journal.connect();
   try {
     await journal.hello('flows-authored-result-verifier');
-    for (const [index, claimed] of ordered.entries()) {
+    for (const [index, claimed] of [...ordered, ...gates].entries()) {
       if (!claimed || typeof claimed.id !== 'string' || typeof claimed.runId !== 'string'
-        || ordinal(claimed.id) !== index+1 || claimed.completionReason !== 'success'
-        || runs.has(claimed.runId)) invalid();
+        || (index < ordered.length && ordinal(claimed.id) !== index+1) || claimed.completionReason !== 'success'
+        || runs.has(claimed.runId)) invalid(`claim ${claimed?.id}`);
       runs.add(claimed.runId);
       const state = await journal.runGet(claimed.runId);
       if (state.run_id !== claimed.runId || state.status !== 'completed'
-        || state.steps[claimed.id]?.state !== 'done') invalid();
+        || state.steps[claimed.id]?.state !== 'done') invalid(`state ${claimed.id} ${state.status} ${state.steps[claimed.id]?.state}`);
       const entries: Array<{
         seq: number; entry_type: string; step_id?: string; payload?: {
           completionReason?: string; spec?: { name?: string; steps?: Array<{id?:string;type?:string;command?:string}> };
@@ -196,7 +210,7 @@ export async function verifyAuthoredNodeResult(
         if (page.length === 0) break;
         for (const raw of page) {
           const entry = raw as typeof entries[number];
-          if (!Number.isSafeInteger(entry?.seq) || entry.seq < fromSeq) invalid();
+          if (!Number.isSafeInteger(entry?.seq) || entry.seq < fromSeq) invalid('seq');
           fromSeq = entry.seq + 1;
           // Keep only completion evidence; streaming logs can span many pages.
           if (['run.spawned', 'step.completed', 'run.completed'].includes(entry.entry_type)) entries.push(entry);
@@ -204,12 +218,20 @@ export async function verifyAuthoredNodeResult(
       }
       const spec = entries.find(entry => entry.entry_type === 'run.spawned')?.payload?.spec;
       const step = spec?.steps?.[0];
+      // A named gate lowers INTO the step's own spec as a second, dependent
+      // `<id>.gate` step (named-gate-lowering.ts); that is the only other
+      // step a child spec may carry, and it must have completed too.
+      const lowered = spec?.steps ?? [];
+      const specShape = lowered.length === 1 || (lowered.length === 2 && lowered[1]?.id === `${claimed.id}.gate`);
       const completed = entries.filter(entry => entry.entry_type === 'step.completed' && entry.step_id === claimed.id);
+      const gateCompleted = lowered.length === 2
+        ? entries.filter(entry => entry.entry_type === 'step.completed' && entry.step_id === `${claimed.id}.gate`) : [];
       const terminalFacts = entries.filter(entry => entry.entry_type === 'run.completed');
-      if (spec?.name !== `${metadata.flowName}/${claimed.id}` || spec?.steps?.length !== 1
+      if (spec?.name !== `${metadata.flowName}/${claimed.id}` || !specShape
         || step?.id !== claimed.id || completed.length !== 1
         || completed[0]?.payload?.completionReason !== 'success'
-        || terminalFacts.length !== 1 || terminalFacts[0]?.payload?.completionReason !== 'success') invalid();
+        || (lowered.length === 2 && (gateCompleted.length !== 1 || gateCompleted[0]?.payload?.completionReason !== 'success'))
+        || terminalFacts.length !== 1 || terminalFacts[0]?.payload?.completionReason !== 'success') invalid(`evidence ${claimed.id} spec=${spec?.name} step=${step?.id} completed=${completed.length}`);
       if (claimed === terminal) {
         // The claimed verdict must match the marker the journal actually
         // recorded, so an IPC frame cannot claim `success` over a run whose
@@ -219,7 +241,7 @@ export async function verifyAuthoredNodeResult(
         // the runtime validation of untrusted IPC, and it is why nothing has
         // to be re-asserted here just to satisfy the type.
         if (step?.type !== 'deterministic'
-          || step.command !== completionMarker(result.completionReason)) invalid();
+          || step.command !== completionMarker(result.completionReason)) invalid('marker');
       }
     }
   } finally { journal.close(); }

package/src/authored-worker-step.ts

@@ -7,12 +7,11 @@ import { classifyOutcome, type RunLifecycleOptions } from './cli/run.js';
 import type { PreflightDiagnostic } from './preflight.js';
 import { AuthoredFlowExecutionError } from './authored-flow-error.js';
 import type { JournalClient } from './journal-client.js';
-import { SPEC_SCHEMA_VERSION, type FlowSpec, type StepSpec } from './spec.js';
+import { SPEC_SCHEMA_VERSION, type FlowSpec, type PermissionsSpec, type StepSpec } from './spec.js';
 import { isSurfaceCompletionReason, readCompletedStepOutput, readSuccessfulOutput } from './authored-step-output.js';
 import type { AuthoredFlowJournalStep } from './authored-flow-executor.js';
 import { snapshotJsonValue } from './json-value.js';
 import { authoredChildAdmissionKey } from './authored-admission.js';
-import { diffWorkspaceFiles, snapshotWorkspaceFiles } from './agent-artifacts.js';
 
 const WORKSPACE_PERMISSION_ANNOTATION = /:\s*(readonly|readwrite)\s*$/i;
 
@@ -97,13 +96,10 @@ export function authoredWorkerRunner(
       if (options.workspace !== undefined && WORKSPACE_PERMISSION_ANNOTATION.test(options.workspace)) {
         throw new AuthoredFlowExecutionError(
           'unsupported_workspace_permission',
-          `flow "${definition.name}" step "${id}": workspace "${options.workspace}" declares a `
-            + 'permission annotation ("...: readonly" / "...: readwrite"), but nothing enforces it — '
-            + 'no parser anywhere in this package turns that annotation into a real restriction '
-            + '(kernel/DAEMON-LIFECYCLE.md\'s permission model is untouched by f.agent). '
-            + 'Silently accepting and ignoring it would let a flow believe a restriction is in effect '
-            + "when it is not. Declare a bare surface name (no trailing \": readonly\"/\": readwrite\") "
-            + 'if you do not need enforcement, or use the declarative spec\'s `permissions` field, which is real.',
+          `flow "${definition.name}" step "${id}": workspace "${options.workspace}": `
+            + "Workspace permission suffixes are unsupported. Use a bare workspace name and f.agent's "
+            + "permissions option, for example permissions: { fileGlobs: ['src/**'], accessPreset: 'readonly' }. "
+            + 'This declaration is validated and recorded with the step spec; it is not currently enforced (gate 8 / #442).',
         );
       }
       if (options.cli !== undefined && typeof options.cli !== 'string') {
@@ -130,22 +126,12 @@ export function authoredWorkerRunner(
           `f.agent options.transport must be 'direct' or 'relay' (got ${JSON.stringify(options.transport)}).`,
         );
       }
-      // Artifact detection only tells the truth for the local-agent DIRECT
-      // path: that is the only case that runs in this same process, on this
-      // same filesystem, so `options.cwd` (or `process.cwd()`) is provably
-      // where the CLI actually wrote — a workspace-scoped step never reaches
-      // here with a local agent attached (refused above). `transport: 'relay'`
-      // dispatches to agent-relay, which executes on a remote host even
-      // though a local agent stream is still attached, so it gets no local
-      // snapshot either. Any other worker attachment may execute on a
-      // different host entirely; snapshotting this process's filesystem for
-      // that case would be a guess, not a fact, so `artifacts` stays `[]`
-      // there, exactly as before this fix.
-      const artifactRoot = localAgentStream === undefined || options.transport === 'relay'
-        ? undefined : options.cwd ?? process.cwd();
-      const before = artifactRoot === undefined ? undefined : await snapshotWorkspaceFiles(artifactRoot);
+      const permissions = options.permissions;
+      const permissionsSnapshot = permissions === undefined ? undefined
+        : snapshotJsonValue(permissions, 'f.agent options.permissions') as unknown as PermissionsSpec;
       const output = await run({
         id, type: 'agent', instruction: options.task,
+        ...(permissionsSnapshot === undefined ? {} : { permissions: permissionsSnapshot }),
         ...(localAgentStream === undefined ? {} : { surfaces: { streams: [{ stream: localAgentStream }] } }),
         ...(options.workspace === undefined ? {} : { surfaces: { workspace: [{ surface: options.workspace }] } }),
         ...(options.cli === undefined ? {} : { cli: options.cli }),
@@ -158,9 +144,12 @@ export function authoredWorkerRunner(
         throw new AuthoredFlowExecutionError('journal_protocol_violation', `step "${id}" produced a non-object output`);
       }
       const stdout = 'stdout_tail' in output ? output.stdout_tail : undefined;
-      const artifacts = before === undefined || artifactRoot === undefined
-        ? []
-        : diffWorkspaceFiles(before, await snapshotWorkspaceFiles(artifactRoot));
+      // The worker that ran the CLI measured the artifacts and journaled them
+      // in the step's output; read that fact back rather than re-scanning a
+      // directory this process may not even share with the agent.
+      const journaled = 'artifacts' in output ? output.artifacts : undefined;
+      const artifacts = Array.isArray(journaled) && journaled.every(entry => typeof entry === 'string')
+        ? [...journaled] : [];
       return { summary: typeof stdout === 'string' ? stdout : JSON.stringify(output), artifacts };
     },
     async llm(id: string, prompt: string, options?: LlmOptions, verification?: NamedGate): Promise<unknown> {

package/src/cli/check-triggers.ts

@@ -2,6 +2,7 @@ import { dirname, resolve } from 'node:path';
 import { loadAuthoredFlow, type LoadedAuthoredFlow } from '../authored-flow-loader.js';
 import { preflightWebhookTriggers } from '../preflight.js';
 import { preflightProviderTriggers } from '../provider-trigger-contract.js';
+import { scheduleLowering } from '../schedule-trigger.js';
 import { checkSlackHelpers } from '../slack-preflight.js';
 import { inputFailureReport, readProjectConfig, type CheckReport } from './check.js';
 
@@ -31,12 +32,20 @@ export async function checkAuthoredTriggers(path: string): Promise<{
     const diagnostics = [
       ...triggerDiagnostics, ...providerDiagnostics, ...helperReport.diagnostics,
     ];
+    // A schedule is inspectable data: print what it lowers to, and say plainly
+    // when the local runner cannot drive it. Neither is a refusal — Cloud can.
+    const schedules = triggers.flatMap((trigger, handler) => {
+      if (trigger.kind !== 'schedule') return [];
+      const lowering = scheduleLowering(definition.name, trigger);
+      return [{ handler, ...lowering }];
+    });
     return {
       loaded,
       report: {
         // Severity, not emptiness: a warning must never refuse a flow.
         ok: !diagnostics.some(diagnostic => diagnostic.severity === 'refusal'),
         path, gates: [], resolutions: [], diagnostics,
+        ...(schedules.length === 0 ? {} : { schedules }),
         ...(config.path === undefined ? {} : { projectConfigPath: config.path }),
       },
     };

package/src/cli/check.ts

@@ -45,9 +45,24 @@ export interface CheckReport {
   projectConfigPath?: string;
   gates: StepGateInspection[];
   resolutions: CliResolution[];
+  /** Authored `schedule.*` handlers and the `flows.tick` subscription each lowers to. */
+  schedules?: ScheduleInspection[];
   diagnostics: Array<PreflightDiagnostic | CheckInputDiagnostic | CheckWarningDiagnostic>;
 }
 
+export interface ScheduleInspection {
+  /** Position among the flow's handlers, so two identical declarations stay distinct. */
+  handler: number;
+  cron?: string;
+  tz?: string;
+  intervalMs?: number;
+  epochMs?: number;
+  staleAfterMs?: number;
+  scheduleId: string;
+  /** Present when the local tick runner cannot drive it (only a cron-aware runner can). */
+  localUnsupported?: string;
+}
+
 export interface CheckWarningDiagnostic {
   severity: 'warning';
   kind: CheckWarningKind;

package/src/cli/cloud-schedule.ts

@@ -0,0 +1,135 @@
+import { CloudFlowError } from '../cloud-http.js';
+import { listCloudSchedules, scheduleInCloud, unscheduleInCloud, type CloudSchedule } from '../cloud-schedule.js';
+import { DirectInputError, isAuthoredFlowPath, parseDirectInput } from '../direct-input.js';
+import { snapshotJsonValue, type JsonValue } from '../json-value.js';
+import type { CliIo } from '../cli.js';
+
+export interface CloudScheduleArgs {
+  command: 'schedule';
+  value: string;
+  cron: string | undefined;
+  every: string | undefined;
+  tz: string | undefined;
+  input: string | undefined;
+  name: string | undefined;
+  json: boolean;
+}
+
+/**
+ * `flows schedule <flow.yaml|flow.ts> [--cron "<expr>" | --every <n><s|m|h|d>]
+ *   [--tz <IANA>] [--input <json|file>] [--name <n>] [--json]`
+ *
+ * With neither `--cron` nor `--every`, the flow's own `schedule.*` handler
+ * supplies the cron, so a declared schedule and its hosted registration
+ * cannot drift.
+ */
+export function parseCloudScheduleArgs(args: readonly string[]): CloudScheduleArgs | undefined {
+  let value: string | undefined;
+  const flags: Record<'cron' | 'every' | 'tz' | 'input' | 'name', string | undefined> = {
+    cron: undefined, every: undefined, tz: undefined, input: undefined, name: undefined,
+  };
+  let json = false;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]!;
+    if (arg === '--json') {
+      if (json) return undefined;
+      json = true;
+      continue;
+    }
+    if (arg === '--cron' || arg === '--every' || arg === '--tz' || arg === '--input' || arg === '--name') {
+      const key = arg.slice(2) as keyof typeof flags;
+      const next = args[i + 1];
+      // A cron expression legitimately starts with `*`; only a flag-shaped value is refused.
+      if (flags[key] !== undefined || next === undefined || next.startsWith('--')) return undefined;
+      flags[key] = next;
+      i += 1;
+      continue;
+    }
+    if (arg.startsWith('-') || value !== undefined) return undefined;
+    value = arg;
+  }
+  if (value === undefined) return undefined;
+  if (flags.cron !== undefined && flags.every !== undefined) return undefined;
+  if (flags.input !== undefined && !isAuthoredFlowPath(value)) return undefined;
+  return { command: 'schedule', value, ...flags, json };
+}
+
+function describe(schedule: CloudSchedule): string {
+  const last = schedule.lastTriggeredAt === undefined ? ''
+    : ` last ${schedule.lastTriggeredAt}${schedule.lastTriggerStatus === undefined ? '' : ` (${schedule.lastTriggerStatus})`}`;
+  return `${schedule.id} ${schedule.status} ${JSON.stringify(schedule.name)} cron "${schedule.cronExpression}" tz ${schedule.timezone}${last}`;
+}
+
+export async function runCloudScheduleCli(args: CloudScheduleArgs, io: CliIo): Promise<0 | 1 | 2> {
+  try {
+    let input: JsonValue | undefined;
+    let inputPresent = false;
+    if (isAuthoredFlowPath(args.value)) {
+      try {
+        input = snapshotJsonValue(parseDirectInput(args.input), 'Cloud authored input');
+        inputPresent = true;
+      } catch (error) {
+        if (error instanceof DirectInputError) throw new CloudFlowError('invalid_input', error.message);
+        throw error;
+      }
+    }
+    const schedule = await scheduleInCloud({
+      flow: { path: args.value },
+      ...(args.cron === undefined ? {} : { cron: args.cron }),
+      ...(args.every === undefined ? {} : { every: args.every }),
+      ...(args.tz === undefined ? {} : { tz: args.tz }),
+      ...(args.name === undefined ? {} : { name: args.name }),
+      ...(inputPresent ? { input } : {}),
+    });
+    if (args.json) {
+      io.stdout(JSON.stringify({ ok: true, ...schedule }));
+      return 0;
+    }
+    io.stdout(`SCHEDULED ${describe(schedule)}`);
+    io.stdout('Each fire submits this exact source through the same admission as flows run --cloud; list with: flows schedules');
+    return 0;
+  } catch (error) {
+    return reportFailure(error, args.json, io);
+  }
+}
+
+export async function runCloudSchedulesCli({ json }: { json: boolean }, io: CliIo): Promise<0 | 1 | 2> {
+  try {
+    const schedules = await listCloudSchedules();
+    if (json) {
+      io.stdout(JSON.stringify({ ok: true, schedules }));
+      return 0;
+    }
+    if (schedules.length === 0) io.stdout('No workflow schedules in this workspace.');
+    for (const schedule of schedules) io.stdout(describe(schedule));
+    return 0;
+  } catch (error) {
+    return reportFailure(error, json, io);
+  }
+}
+
+export async function runCloudUnscheduleCli(
+  { scheduleId, json }: { scheduleId: string; json: boolean }, io: CliIo,
+): Promise<0 | 1 | 2> {
+  try {
+    await unscheduleInCloud(scheduleId);
+    io.stdout(json ? JSON.stringify({ ok: true, scheduleId, deleted: true }) : `UNSCHEDULED ${scheduleId}`);
+    return 0;
+  } catch (error) {
+    return reportFailure(error, json, io);
+  }
+}
+
+function reportFailure(error: unknown, json: boolean, io: CliIo): 1 | 2 {
+  const code = error instanceof CloudFlowError ? error.code : 'cloud_schedule_failed';
+  let message = error instanceof Error ? error.message : 'Cloud schedule failed.';
+  // The schedule routes take a browser session or a `cli:auth` token.
+  if (error instanceof CloudFlowError && error.status === 403) {
+    message += ' Scheduling needs an interactive `cli:auth` credential: run `agent-relay cloud login`.';
+  }
+  if (json) io.stdout(JSON.stringify({ ok: false, code, message }));
+  else io.stderr(`${code}: ${message}`);
+  return error instanceof CloudFlowError
+    && (['configuration', 'unsupported_source', 'invalid_input'].includes(error.code) || error.status === 403 || error.status === 401)
+    ? 2 : 1;
+}

package/src/cli/direct-run.ts

@@ -172,7 +172,7 @@ export async function runDirectFlow(
     // diagnostic carried up from `classifyOutcome` already names the step, its
     // exit code and its output tail; this branch is what lets it reach the
     // terminal. `resumeFlow` takes the same branch, through the same helper.
-    if (error instanceof AuthoredFlowExecutionError && error.code === 'step_failed') {
+    if (error instanceof AuthoredFlowExecutionError && (error.code === 'step_failed' || error.code === 'gate_failed')) {
       return authoredStepFailure('run', base, socketPath, error);
     }
     const runId = error instanceof AuthoredFlowExecutionError ? error.runId : undefined;

package/src/cli/run.ts

@@ -223,7 +223,7 @@ export async function resumeFlow(
     // leaving it on `protocolFailure` meant `flows run` printed the evidence
     // while `flows resume` still printed `protocol_error` and
     // `RUN <id> unknown` for the identical failure.
-    if (error instanceof AuthoredFlowExecutionError && error.code === 'step_failed') {
+    if (error instanceof AuthoredFlowExecutionError && (error.code === 'step_failed' || error.code === 'gate_failed')) {
       return authoredStepFailure('resume', base, socketPath, error, runId);
     }
     if (!(error instanceof JournalProtocolError) || error.code !== 'run_not_found') {
@@ -287,10 +287,12 @@ export function authoredStepFailure(
       completionReason: 'step_failed',
       diagnostics: [...base.diagnostics, {
         severity: 'failure',
-        kind: 'step_failed',
+        // A predicate gate that judged false is a run failure with its own
+        // name, so the report says which kind of check the body did not pass.
+        kind: error.code === 'gate_failed' ? 'gate_failed' : 'step_failed',
         // The `step_failed: ` prefix `AuthoredFlowExecutionError` adds is
         // redundant once the diagnostic is labelled `[step_failed]`.
-        message: error.message.replace(/^step_failed: /, ''),
+        message: error.message.replace(/^(?:step_failed|gate_failed): /, ''),
       }],
     },
   };

package/src/cli.ts

@@ -26,6 +26,7 @@ import { checkTypeScriptFlow } from './cli/check-typescript.js';
 import { runCloudCli } from './cli/cloud-run.js';
 import { runCloudSyncCli } from './cli/cloud-sync.js';
 import { parseCloudDeployArgs, runCloudDeployCli, runCloudDeploymentsCli, runCloudUndeployCli, type CloudDeployArgs } from './cli/cloud-deploy.js';
+import { parseCloudScheduleArgs, runCloudScheduleCli, runCloudSchedulesCli, runCloudUnscheduleCli, type CloudScheduleArgs } from './cli/cloud-schedule.js';
 import { isAuthoredFlowPath } from './direct-input.js';
 import { parseDeployArgs, runDeploy, type DeployArgs } from './cli/deploy.js';
 import { parseDigestReference } from './bundle-transport.js';
@@ -58,6 +59,9 @@ type ParsedArgs =
   | CloudDeployArgs
   | { command: 'deployments'; json: boolean }
   | { command: 'undeploy'; agentId: string; json: boolean }
+  | CloudScheduleArgs
+  | { command: 'schedules'; json: boolean }
+  | { command: 'unschedule'; scheduleId: string; json: boolean }
   | { command: 'check'; json: boolean; watch: boolean; value: string }
   | { command: 'run'; bucket: string | undefined; reuseFromRunId: string | undefined; localAgent: boolean; dataDir: string; input: string | undefined; json: boolean; spawn: boolean; noObserverLink: boolean; allowHumanInfluenced: boolean; value: string }
   | { command: 'resume'; localAgent: boolean; dataDir: string; json: boolean; spawn: boolean; noObserverLink: boolean; allowHumanInfluenced: boolean; value: string }
@@ -75,6 +79,9 @@ const USAGE = [
   'flows deploy <flow.ts> --repo <owner/name> --on <provider>[:key=value,...] [--on ...] --approver <handle> [--agents claude[,codex]] [--name <name>] [--draft] [--json]',
   'flows deployments [--json]',
   'flows undeploy [--json] <deployment-id>',
+  'flows schedule <flow.yaml|flow.ts> [--cron "<expr>" | --every <n><s|m|h|d>] [--tz <IANA>] [--input <inline-json-or-file>] [--name <name>] [--json]',
+  'flows schedules [--json]',
+  'flows unschedule [--json] <schedule-id>',
   'flows deploy <flow>@sha256:<digest> --to <file-bucket-uri>',
   'flows run <flow>@sha256:<digest> [--bucket <file-bucket-uri>] [--data-dir <dir>] [--json]',
   'flows check [--watch] [--json] <flow.ts|flow.yaml|spec.json>',
@@ -131,6 +138,9 @@ export async function runCli(
   if (parsed.command === 'cloud-deploy') return runCloudDeployCli(parsed, io);
   if (parsed.command === 'deployments') return runCloudDeploymentsCli(parsed, io);
   if (parsed.command === 'undeploy') return runCloudUndeployCli(parsed, io);
+  if (parsed.command === 'schedule') return runCloudScheduleCli(parsed, io);
+  if (parsed.command === 'schedules') return runCloudSchedulesCli(parsed, io);
+  if (parsed.command === 'unschedule') return runCloudUnscheduleCli(parsed, io);
   if (parsed.command === 'replay') return replayJournal(parsed, io);
   if (parsed.command === 'build') return runBuild(parsed, io);
   if (parsed.command === 'deploy') return runDeploy(parsed, io);
@@ -266,6 +276,7 @@ async function checkAuthoredFlowComposed(path: string): Promise<{ report: CheckR
   return {
     report: {
       ...mcp.report,
+      ...(triggers?.report.schedules === undefined ? {} : { schedules: triggers.report.schedules }),
       diagnostics: [...helper.report.diagnostics, ...mcp.report.diagnostics, ...triggerDiagnostics],
       ok: helper.report.ok && mcp.report.ok && triggerOk,
     },
@@ -440,6 +451,18 @@ function parseArgs(args: readonly string[]): ParsedArgs | undefined {
     const source = args.slice(1).find(a => !a.startsWith('-') && isAuthoredFlowPath(a));
     return source !== undefined ? parseCloudDeployArgs(args.slice(1)) : parseDeployArgs(args.slice(1));
   }
+  if (command === 'schedule') return parseCloudScheduleArgs(args.slice(1));
+  if (command === 'schedules') {
+    const rest = args.slice(1);
+    if (rest.length > 1 || (rest.length === 1 && rest[0] !== '--json')) return undefined;
+    return { command: 'schedules', json: rest.length === 1 };
+  }
+  if (command === 'unschedule') {
+    const rest = args.slice(1).filter(a => a !== '--json');
+    const json = args.length - 1 - rest.length;
+    if (json > 1 || rest.length !== 1 || rest[0]!.startsWith('-')) return undefined;
+    return { command: 'unschedule', scheduleId: rest[0]!, json: json === 1 };
+  }
   if (command === 'undeploy') {
     const rest = args.slice(1).filter(a => a !== '--json');
     const json = args.length - 1 - rest.length;
@@ -751,6 +774,15 @@ function emitCheckReport(report: CheckReport, json: boolean, io: CliIo): void {
     const vacuous = gate.acceptsAnyOutput === true ? ' [json_schema accepts any output]' : '';
     io.stdout(`GATE step "${gate.stepId}" ${gate.checks.join('+')} from data (kernel, journal-replayable)${vacuous}`);
   }
+  for (const schedule of report.schedules ?? []) {
+    const declared = schedule.cron !== undefined
+      ? `cron "${schedule.cron}"${schedule.tz === undefined ? '' : ` tz ${schedule.tz}`}`
+      : `every ${schedule.intervalMs}ms`;
+    const local = schedule.localUnsupported !== undefined
+      ? `Cloud only: ${schedule.localUnsupported}`
+      : `local: flows tick start --schedule-id ${schedule.scheduleId} --interval-ms ${schedule.intervalMs} --epoch-ms ${schedule.epochMs}`;
+    io.stdout(`SCHEDULE handler ${schedule.handler} ${declared} -> flows.tick schedule_id ${schedule.scheduleId} [${local}]`);
+  }
   for (const resolution of report.resolutions) {
     const config = resolution.source === 'project' && report.projectConfigPath !== undefined
       ? ` (${report.projectConfigPath})`

package/src/cloud-deploy.ts

@@ -21,7 +21,9 @@ export type FlowTriggerProvider = (typeof FLOW_TRIGGER_PROVIDERS)[number];
 
 /** Settings Cloud's launcher prefilter reads per provider (`flow-trigger-sources.ts`). */
 const PROVIDER_SETTINGS: Record<FlowTriggerProvider, readonly string[]> = {
-  github: ['repository', 'labels', 'contains'],
+  // `events`: `issues` (default) or `pull_request` — which GitHub records
+  // wake the listener (AgentWorkforce/cloud#3772).
+  github: ['repository', 'labels', 'contains', 'events'],
   slack: ['channel', 'contains'],
   linear: ['team', 'contains'],
   jira: ['project', 'contains'],
@@ -102,6 +104,15 @@ export function parseTriggerSource(value: string): FlowTriggerSource {
       if (!setting || setting.length > MAX_SETTING_LENGTH || key in settings) {
         throw new CloudFlowError('invalid_input', `Trigger setting "${key}" must be given once with a non-empty value.`);
       }
+      if (key === 'events') {
+        // Cloud's enum is lowercase; send it that way whatever the shell typed.
+        const events = setting.toLowerCase();
+        if (!['issues', 'pull_request'].includes(events)) {
+          throw new CloudFlowError('invalid_input', `github events must be "issues" or "pull_request", got "${setting}".`);
+        }
+        settings[key] = events;
+        continue;
+      }
       settings[key] = setting;
     }
   }