@relayflows/sdk 2.0.16 → 2.0.18

package/src/cli/cloud-schedule.ts

@@ -0,0 +1,160 @@
+import { CloudFlowError } from '../cloud-http.js';
+import { listCloudSchedules, scheduleInCloud, unscheduleInCloud, validateScheduleArgs, type CloudSchedule } from '../cloud-schedule.js';
+import { DirectInputError, isAuthoredFlowPath, parseDirectInput } from '../direct-input.js';
+import { snapshotJsonValue, type JsonValue } from '../json-value.js';
+import { cliConnectPrompt, ensureFlowConnections, harnessRemedy } from './cloud-connect-cli.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;
+  /** Refuse a missing integration instead of offering to connect it. */
+  noConnect: boolean;
+  json: boolean;
+}
+
+/**
+ * `flows schedule <flow.yaml|flow.ts> [--cron "<expr>" | --every <n><s|m|h|d>]
+ *   [--tz <IANA>] [--input <json|file>] [--name <n>] [--no-connect] [--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;
+  let noConnect = 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 === '--no-connect') {
+      if (noConnect) return undefined;
+      noConnect = 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, noConnect, 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> {
+  let harnesses: readonly string[] = [];
+  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;
+      }
+    }
+    validateScheduleArgs({
+      ...(args.cron === undefined ? {} : { cron: args.cron }),
+      ...(args.every === undefined ? {} : { every: args.every }),
+      ...(args.tz === undefined ? {} : { tz: args.tz }),
+    });
+    // Each fire runs the flow as this workspace, so what it needs connected
+    // is checked once here — after the arguments are known to be good, so a
+    // refused command never opens a browser first — and before the schedule exists.
+    const connections = await ensureFlowConnections({
+      path: args.value, prompt: cliConnectPrompt(io, { noConnect: args.noConnect, json: args.json }),
+    });
+    harnesses = connections?.requirements.harnesses ?? [];
+    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)}`);
+    for (const provider of connections?.outcome.connected ?? []) io.stdout(`  connected: ${provider}`);
+    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, harnesses);
+  }
+}
+
+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, harnesses: readonly string[] = []): 1 | 2 {
+  const code = error instanceof CloudFlowError ? error.code : 'cloud_schedule_failed';
+  let message = error instanceof Error ? error.message : 'Cloud schedule failed.';
+  message += harnessRemedy(error, harnesses);
+  // 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', 'integration_not_connected'].includes(error.code)
+      || error.status === 403 || error.status === 401)
+    ? 2 : 1;
+}

package/src/cli/direct-run.ts

@@ -8,6 +8,7 @@ import {
   AuthoredFlowExecutionError,
 } from '../authored-flow-executor.js';
 import { executeDurableAuthoredFlow } from '../authored-root.js';
+import { AuthoredHumanParked } from '../authored-flow-error.js';
 import { AuthoredFlowLoadError } from '../authored-flow-loader.js';
 import { DirectInputError, parseDirectInput } from '../direct-input.js';
 import { JournalClient } from '../journal-client.js';
@@ -15,6 +16,7 @@ import { inputFailureReport } from './check.js';
 import { checkAuthoredTriggers } from './check-triggers.js';
 import {
   authoredCompletion,
+  authoredHumanParked,
   authoredStepFailure,
   connect,
   emptyReport,
@@ -172,9 +174,12 @@ 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);
     }
+    if (error instanceof AuthoredHumanParked) {
+      return authoredHumanParked('run', base, socketPath, error, { dataDir, localAgent: options.localAgent === true });
+    }
     const runId = error instanceof AuthoredFlowExecutionError ? error.runId : undefined;
     return protocolFailure('run', base, socketPath, error, runId);
   } finally {

package/src/cli/run.ts

@@ -2,7 +2,8 @@ import { parseDigestReference } from '../bundle-transport.js';
 import { prepareDigestRun } from './run-digest.js';
 import { reuseSummary } from './reuse.js';
 import { resumeHelperEffect } from '../authored-helper-effect.js';
-import { AuthoredFlowExecutionError } from '../authored-flow-error.js';
+import { AuthoredFlowExecutionError, AuthoredHumanParked, type AuthoredHumanWait } from '../authored-flow-error.js';
+import { answerCommand, resumeCommand } from '../authored-human.js';
 import { join, resolve } from 'node:path';
 import type { ProgressEvent } from '../progress.js';
 import { toKernelSpec } from '../compile.js';
@@ -29,7 +30,7 @@ import {
 } from './check.js';
 
 export type RunExitCode = 0 | 1 | 2 | 3;
-export type RunCommand = 'run' | 'resume';
+export type RunCommand = 'run' | 'resume' | 'answer';
 
 export interface ParkedStep {
   id: string;
@@ -53,6 +54,12 @@ export interface RunReport {
   completedSteps?: number;
   reuse?: { fromRunId: string; reusedSteps: number; executedSteps: number };
   parkedStep?: ParkedStep;
+  /** The open `f.human` question a parked authored run is waiting on. */
+  humanWait?: AuthoredHumanWait;
+  /** `flows answer` only: the answer it recorded. */
+  answer?: { waitId: string; answer: boolean; note?: string };
+  /** The invocation that continues this run, when one is known. */
+  next?: string;
   projectConfigPath?: string;
   resolutions: CheckReport['resolutions'];
   diagnostics: Array<CheckReport['diagnostics'][number] | RunDiagnostic>;
@@ -223,9 +230,12 @@ 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 AuthoredHumanParked) {
+      return authoredHumanParked('resume', base, socketPath, error, { dataDir, localAgent: options.localAgent === true });
+    }
     if (!(error instanceof JournalProtocolError) || error.code !== 'run_not_found') {
       return protocolFailure('resume', base, socketPath, error, runId);
     }
@@ -287,10 +297,48 @@ 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): /, ''),
+      }],
+    },
+  };
+}
+
+/**
+ * An authored body parked on an unanswered `f.human`: exit 3, like every
+ * other park, but the diagnostic names the question, who it is for, and the
+ * exact `flows answer` invocation — the run is waiting on a person, not on a
+ * worker. Shared by `run` and `resume` so the two never drift.
+ */
+export function authoredHumanParked(
+  command: RunCommand,
+  base: CheckReport | RunReport,
+  socketPath: string,
+  error: AuthoredHumanParked,
+  where: { dataDir?: string; localAgent: boolean },
+): RunExecution {
+  const runId = error.runId!;
+  return {
+    exitCode: 3,
+    report: {
+      ...fromBase(command, base),
+      ok: false,
+      runId,
+      socketPath,
+      status: 'parked',
+      parkedStep: { id: 'authored-root', type: 'agent' },
+      humanWait: error.wait,
+      diagnostics: [...base.diagnostics, {
+        severity: 'parked',
+        kind: 'run_parked',
+        message: `Run "${runId}" is waiting for ${error.wait.to} to answer ${error.wait.waitId}: `
+          + `${JSON.stringify(error.wait.question)}\n`
+          + `Answer with: ${answerCommand(runId, error.wait.waitId, where.dataDir)}\n`
+          + `Then continue with: ${resumeCommand(runId, where.dataDir, where.localAgent)}`,
       }],
     },
   };

package/src/cli.ts

@@ -2,6 +2,7 @@
 import { addPlugin } from './cli/add.js';
 import { watchCheck } from './cli-watch.js';
 import { checkHelperBody } from './cli/check-helper-body.js';
+import { describeFlowRequirements } from './flow-requirements.js';
 
 import { renderProgress, type ProgressEvent } from './progress.js';
 import { realpathSync } from 'node:fs';
@@ -18,6 +19,7 @@ import {
   type RunProgress,
   type RunReport,
 } from './cli/run.js';
+import { answerFlow } from './cli/answer.js';
 import { checkAuthoredTriggers } from './cli/check-triggers.js';
 import { parseWebhookArgs, runServeWebhook } from './cli/serve-webhook.js';
 import { runDirectFlow } from './cli/direct-run.js';
@@ -26,6 +28,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';
@@ -53,14 +56,18 @@ type ParsedArgs =
   | 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 }
+  | { command: 'cloud-run'; value: string; json: boolean; wait: boolean; input: string | undefined; syncCode: boolean; noConnect: boolean }
   | { command: 'sync'; runId: string; json: boolean; root: string }
   | 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 }
+  | { command: 'answer'; dataDir: string; json: boolean; spawn: boolean; note: string | undefined; by: string | undefined; runId: string; waitId: string; answer: boolean }
   | { command: 'observer'; dataDir: string }
   | { command: 'hn-monitor'; sub: 'start'; dataDir: string; specPath: string; pollIntervalMs: number | undefined }
   | { command: 'tick'; sub: 'start'; dataDir: string; specPath: string; scheduleId: string;
@@ -72,20 +79,24 @@ const USAGE = [
   'flows add <helper-name|@flows/helper-name>',
   'flows build [--out <dir>] <flow.yaml|flow.ts>',
   'flows build --verify <bundle-dir>',
-  'flows deploy <flow.ts> --repo <owner/name> --on <provider>[:key=value,...] [--on ...] --approver <handle> [--agents claude[,codex]] [--name <name>] [--draft] [--json]',
+  'flows deploy <flow.ts> --repo <owner/name> --on <provider>[:key=value,...] [--on ...] --approver <handle> [--agents claude[,codex]] [--name <name>] [--draft] [--no-connect] [--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>] [--no-connect] [--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>',
   'flows serve-webhook --data-dir <dir> --port <p> [--allow <name>[,<name>]]',
   '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] <flow.yaml|spec.json>',
-  'flows run --cloud [--json] [--wait] [--sync-code] <flow.ts> --input <inline-json-or-file>',
+  '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 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>',
+  'flows answer [--json] [--no-spawn] [--data-dir <dir>] [--note <text>] [--by <identity>] <run-id> <wait-id> <yes|no>',
   'flows replay [--allow-human-influenced] [--json] [--data-dir <dir>] <run-id> [--at <step-id>]',
   'flows observer [--data-dir <dir>]',
   'flows hn-monitor start [--data-dir <dir>] [--poll-interval-ms <n>] <spec.json>',
@@ -131,7 +142,19 @@ 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 === 'answer') {
+    const execution = await answerFlow(parsed.runId, parsed.waitId, parsed.answer, parsed.dataDir, {
+      ...(parsed.note === undefined ? {} : { note: parsed.note }),
+      ...(parsed.by === undefined ? {} : { answeredBy: parsed.by }),
+      daemon: { spawn: parsed.spawn && spawnAllowedByEnv() },
+    });
+    emitRunReport(execution, parsed.json, io);
+    return execution.exitCode;
+  }
   if (parsed.command === 'build') return runBuild(parsed, io);
   if (parsed.command === 'deploy') return runDeploy(parsed, io);
 
@@ -266,6 +289,10 @@ async function checkAuthoredFlowComposed(path: string): Promise<{ report: CheckR
   return {
     report: {
       ...mcp.report,
+      ...(triggers?.report.schedules === undefined ? {} : { schedules: triggers.report.schedules }),
+      // The authored definition sees helper flags, body use and `cli:`
+      // declarations; the compiled view underneath knows only its steps.
+      ...(triggers?.report.requirements === undefined ? {} : { requirements: triggers.report.requirements }),
       diagnostics: [...helper.report.diagnostics, ...mcp.report.diagnostics, ...triggerDiagnostics],
       ok: helper.report.ok && mcp.report.ok && triggerOk,
     },
@@ -440,6 +467,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;
@@ -456,6 +495,7 @@ function parseArgs(args: readonly string[]): ParsedArgs | undefined {
   if (command === 'tick') return parseTickArgs(args.slice(1));
   if (command === 'observer') return parseObserverArgs(args.slice(1));
   if (command === 'sync') return parseSyncArgs(args.slice(1));
+  if (command === 'answer') return parseAnswerArgs(args.slice(1));
   if (command !== 'check' && command !== 'run' && command !== 'resume') return undefined;
 
   let json = false;
@@ -463,6 +503,7 @@ function parseArgs(args: readonly string[]): ParsedArgs | undefined {
   let cloud = false;
   let wait = false;
   let syncCode = false;
+  let noConnect = false;
   let localAgent = false;
   let allowHumanInfluenced = false;
   let dataDir = DEFAULT_DATA_DIR;
@@ -476,11 +517,13 @@ function parseArgs(args: readonly string[]): ParsedArgs | undefined {
   const positionals: string[] = [];
   for (let index = 1; index < args.length; index += 1) {
     const argument = args[index]!;
-    if (argument === '--cloud' || argument === '--wait' || argument === '--sync-code') {
-      if (command !== 'run' || (argument === '--cloud' ? cloud : argument === '--wait' ? wait : syncCode)) return undefined;
+    if (argument === '--cloud' || argument === '--wait' || argument === '--sync-code' || argument === '--no-connect') {
+      if (command !== 'run') return undefined;
+      if (argument === '--cloud' ? cloud : argument === '--wait' ? wait : argument === '--sync-code' ? syncCode : noConnect) return undefined;
       if (argument === '--cloud') cloud = true;
       else if (argument === '--wait') wait = true;
-      else syncCode = true;
+      else if (argument === '--sync-code') syncCode = true;
+      else noConnect = true;
       continue;
     }
     if (argument === '--allow-human-influenced') {
@@ -560,9 +603,9 @@ function parseArgs(args: readonly string[]): ParsedArgs | undefined {
     // the source, so it is accepted exactly where a local run accepts it.
     if (allowHumanInfluenced || sawDataDir || !spawn || localAgent || noObserverLink || reuseFromRunId !== undefined) return undefined;
     if (sawInput && !isAuthoredFlowPath(positionals[0]!)) return undefined;
-    return { command: 'cloud-run', value: positionals[0]!, json, wait, input, syncCode };
+    return { command: 'cloud-run', value: positionals[0]!, json, wait, input, syncCode, noConnect };
   }
-  if (wait || syncCode) return undefined;
+  if (wait || syncCode || noConnect) return undefined;
   if (reuseFromRunId !== undefined && isAuthoredFlowPath(positionals[0]!)) return undefined;
 
   if (command === 'run' && input !== undefined && !isAuthoredFlowPath(positionals[0]!)) return undefined;
@@ -573,6 +616,66 @@ function parseArgs(args: readonly string[]): ParsedArgs | undefined {
       : { command, localAgent, dataDir, json, spawn, noObserverLink, allowHumanInfluenced, value: positionals[0]! };
 }
 
+/**
+ * `flows answer [--json] [--no-spawn] [--data-dir <dir>] [--note <text>] [--by <identity>] <run-id> <wait-id> <yes|no>`.
+ * The answer is a literal `yes`/`no` (also `true`/`false`) so a shell cannot
+ * hand the kernel an ambiguous word as a decision. `--by` records who answered
+ * when the invoker is relaying a person's decision (Cloud's answer route runs
+ * this inside the resumed sandbox with the caller's identity); it defaults to
+ * the OS user.
+ */
+function parseAnswerArgs(rest: readonly string[]): ParsedArgs | undefined {
+  let json = false;
+  let spawn = true;
+  let dataDir = DEFAULT_DATA_DIR;
+  let sawDataDir = false;
+  let note: string | undefined;
+  let by: string | undefined;
+  const positionals: string[] = [];
+  for (let index = 0; index < rest.length; index += 1) {
+    const argument = rest[index]!;
+    if (argument === '--json') {
+      if (json) return undefined;
+      json = true;
+      continue;
+    }
+    if (argument === '--no-spawn') {
+      if (!spawn) return undefined;
+      spawn = false;
+      continue;
+    }
+    if (argument === '--by') {
+      const value = rest[index + 1];
+      if (by !== undefined || value === undefined || value.startsWith('-') || value.trim() === '') return undefined;
+      by = value;
+      index += 1;
+      continue;
+    }
+    if (argument === '--data-dir') {
+      const value = rest[index + 1];
+      if (sawDataDir || value === undefined || value.startsWith('-')) return undefined;
+      dataDir = value;
+      sawDataDir = true;
+      index += 1;
+      continue;
+    }
+    if (argument === '--note') {
+      const value = rest[index + 1];
+      if (note !== undefined || value === undefined || value.startsWith('--')) return undefined;
+      note = value;
+      index += 1;
+      continue;
+    }
+    if (argument.startsWith('-')) return undefined;
+    positionals.push(argument);
+  }
+  if (positionals.length !== 3) return undefined;
+  const [runId, waitId, word] = positionals as [string, string, string];
+  const answer = word === 'yes' || word === 'true' ? true : word === 'no' || word === 'false' ? false : undefined;
+  if (answer === undefined) return undefined;
+  return { command: 'answer', dataDir, json, spawn, note, by, runId, waitId, answer };
+}
+
 function parseHnMonitorArgs(rest: readonly string[]): ParsedArgs | undefined {
   const sub = rest[0];
   if (sub !== 'start') return undefined;
@@ -751,6 +854,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})`
@@ -758,6 +870,10 @@ function emitCheckReport(report: CheckReport, json: boolean, io: CliIo): void {
     const model = resolution.model === undefined ? '' : ` model "${resolution.model}"`;
     io.stdout(`RESOLVED step "${resolution.stepId}" cli "${resolution.cli}"${model} from ${resolution.source}${config}`);
   }
+  // What the workspace must have connected before this flow can run there;
+  // the hosted verbs check the same list against Cloud before submitting.
+  const requires = report.requirements === undefined ? '' : describeFlowRequirements(report.requirements);
+  if (requires) io.stdout(`REQUIRES ${requires}`);
   if (report.ok) io.stdout(`CHECK PASSED ${report.path ?? ''}`.trimEnd());
 }
 
@@ -778,6 +894,15 @@ function emitRunReport(
     return;
   }
   if (report.runId === undefined) return;
+  if (report.answer !== undefined) {
+    io.stdout(`ANSWERED ${report.runId} ${report.answer.waitId} ${report.answer.answer ? 'yes' : 'no'}`
+      + (report.answer.note === undefined ? '' : ` (${report.answer.note})`));
+    if (report.next !== undefined) io.stdout(`Continue with: ${report.next}`);
+    return;
+  }
+  // A refused answer changed nothing about the run, so there is no run
+  // outcome to summarize; the refusal above is the whole report.
+  if (report.command === 'answer') return;
   const completed = report.completedSteps === undefined ? '' : ` (${report.completedSteps} ${report.completedSteps === 1 ? 'step' : 'steps'})`;
   const reason = report.completionReason === undefined
     ? ''