@relayflows/sdk 2.0.17 → 2.0.19

package/src/cli/cloud-deploy.ts

@@ -3,6 +3,8 @@ import {
   deployToCloud, listCloudDeployments, parseAgentHarnesses, parseRepository, parseTriggerSource, undeployFromCloud,
   type FlowTriggerSource,
 } from '../cloud-deploy.js';
+import { describeFlowRequirements } from '../flow-requirements.js';
+import { cliConnectPrompt, flowRequirementsForPath, harnessRemedy } from './cloud-connect-cli.js';
 import type { CliIo } from '../cli.js';
 
 export interface CloudDeployArgs {
@@ -14,12 +16,14 @@ export interface CloudDeployArgs {
   name: string | undefined;
   agents: string | undefined;
   draft: boolean;
+  /** Refuse a missing integration instead of offering to connect it. */
+  noConnect: boolean;
   json: boolean;
 }
 
 /**
  * `flows deploy <flow.ts> --repo <owner/name> --on <provider>[:k=v,…] [--on …]
- *   --approver <handle> [--name <n>] [--json]`
+ *   --approver <handle> [--name <n>] [--agents <list>] [--draft] [--no-connect] [--json]`
  *
  * Parsed here rather than in `parseDeployArgs` because the two `deploy` forms
  * share nothing but the word: the digest form copies a sealed bundle into a
@@ -32,6 +36,7 @@ export function parseCloudDeployArgs(args: readonly string[]): CloudDeployArgs |
   let name: string | undefined;
   let agents: string | undefined;
   let draft = false;
+  let noConnect = false;
   let json = false;
   const on: string[] = [];
   for (let i = 0; i < args.length; i++) {
@@ -46,6 +51,11 @@ export function parseCloudDeployArgs(args: readonly string[]): CloudDeployArgs |
       draft = true;
       continue;
     }
+    if (arg === '--no-connect') {
+      if (noConnect) return undefined;
+      noConnect = true;
+      continue;
+    }
     if (arg === '--agents') {
       const next = args[i + 1];
       if (agents !== undefined || next === undefined || next.startsWith('-')) return undefined;
@@ -68,7 +78,7 @@ export function parseCloudDeployArgs(args: readonly string[]): CloudDeployArgs |
     value = arg;
   }
   if (value === undefined || repo === undefined || on.length === 0) return undefined;
-  return { command: 'cloud-deploy', value, repo, on, approver, name, agents, draft, json };
+  return { command: 'cloud-deploy', value, repo, on, approver, name, agents, draft, noConnect, json };
 }
 
 function describeSource(source: FlowTriggerSource): string {
@@ -77,11 +87,19 @@ function describeSource(source: FlowTriggerSource): string {
 }
 
 export async function runCloudDeployCli(args: CloudDeployArgs, io: CliIo): Promise<0 | 1 | 2> {
+  const agents = args.agents === undefined ? undefined : parseAgentHarnessesOr(args.agents);
+  // What the source declares, so a harness refusal names the right remedy
+  // even when `--agents` was not given; the loader's own failure is reported
+  // by deployToCloud, not here.
+  let harnesses: readonly string[] = agents instanceof CloudFlowError ? [] : agents ?? [];
   try {
     if (args.approver === undefined) {
       throw new CloudFlowError('invalid_input',
         '--approver <handle> is required: every launched run receives it as input.approver for f.human.');
     }
+    if (agents instanceof CloudFlowError) throw agents;
+    const connect = cliConnectPrompt(io, { noConnect: args.noConnect, json: args.json });
+    if (agents === undefined) harnesses = (await flowRequirementsForPath(args.value))?.harnesses ?? [];
     const deployment = await deployToCloud({
       path: args.value,
       repository: parseRepository(args.repo),
@@ -89,7 +107,8 @@ export async function runCloudDeployCli(args: CloudDeployArgs, io: CliIo): Promi
       approver: args.approver,
       draft: args.draft,
       ...(args.name === undefined ? {} : { name: args.name }),
-      ...(args.agents === undefined ? {} : { agents: parseAgentHarnesses(args.agents) }),
+      ...(agents === undefined ? {} : { agents }),
+      ...(connect === undefined ? {} : { connect }),
     });
     if (args.json) {
       io.stdout(JSON.stringify({ ok: true, ...deployment }));
@@ -99,12 +118,24 @@ export async function runCloudDeployCli(args: CloudDeployArgs, io: CliIo): Promi
     io.stdout(`  flow: ${deployment.name} (${args.value}, sha256 ${deployment.sourceSha256.slice(0, 12)})`);
     io.stdout(`  repository: ${deployment.repository.owner}/${deployment.repository.name}`);
     for (const source of deployment.sources) io.stdout(`  on: ${describeSource(source)}`);
+    const requires = describeFlowRequirements(deployment.requirements);
+    if (requires) io.stdout(`  requires: ${requires}`);
+    for (const provider of deployment.connected) io.stdout(`  connected: ${provider}`);
     io.stdout(deployment.status === 'draft'
       ? 'Saved without activating; activate it from the Cloud dashboard, or redeploy without --draft.'
       : 'Each matching ticket launches a run of this source in a fresh branch; list with: flows deployments');
     return 0;
   } catch (error) {
-    return reportCloudFailure(error, args.json, io);
+    return reportCloudFailure(error, args.json, io, harnesses);
+  }
+}
+
+function parseAgentHarnessesOr(value: string): ReturnType<typeof parseAgentHarnesses> | CloudFlowError {
+  try {
+    return parseAgentHarnesses(value);
+  } catch (error) {
+    if (error instanceof CloudFlowError) return error;
+    throw error;
   }
 }
 
@@ -140,9 +171,11 @@ export async function runCloudUndeployCli({ agentId, json }: { agentId: string;
   }
 }
 
-function reportCloudFailure(error: unknown, json: boolean, io: CliIo): 1 | 2 {
+function reportCloudFailure(error: unknown, json: boolean, io: CliIo, harnesses: readonly string[] = []): 1 | 2 {
   const code = error instanceof CloudFlowError ? error.code : 'cloud_deploy_failed';
   let message = error instanceof Error ? error.message : 'Cloud deploy failed.';
+  // Cloud names the missing coding-agent credential on activation; say how it is connected.
+  message += harnessRemedy(error, harnesses);
   // The deploy routes take a browser session or a `cli:auth` token. A
   // deployment (CI) token gets 403 `session_required`; say what fixes it.
   if (error instanceof CloudFlowError && error.status === 403) {
@@ -152,6 +185,7 @@ function reportCloudFailure(error: unknown, json: boolean, io: CliIo): 1 | 2 {
   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)
+    && (['configuration', 'unsupported_source', 'invalid_input', 'integration_not_connected'].includes(error.code)
+      || error.status === 403 || error.status === 401)
     ? 2 : 1;
 }

package/src/cli/cloud-run.ts

@@ -2,26 +2,30 @@ import { CloudFlowError } from '../cloud-http.js';
 import { runInCloud, waitForCloudFlowRun, type RunInCloudOptions } from '../cloud-run.js';
 import { DirectInputError, isAuthoredFlowPath, parseDirectInput } from '../direct-input.js';
 import { snapshotJsonValue } from '../json-value.js';
+import { cliConnectPrompt, ensureFlowConnections, harnessRemedy } from './cloud-connect-cli.js';
 import type { CliIo } from '../cli.js';
 
 /** Presentation only: the central CLI parser owns argv; the SDK owns the lifecycle. */
 export async function runCloudCli(
-  { value: path, json, wait, input, syncCode }: {
-    value: string; json: boolean; wait: boolean; input: string | undefined; syncCode: boolean;
+  { value: path, json, wait, input, syncCode, noConnect = false }: {
+    value: string; json: boolean; wait: boolean; input: string | undefined; syncCode: boolean; noConnect?: boolean;
   },
   io: CliIo,
+  /**
+   * Cancellation, owned by the caller. `runCli` supplies either the embedder's
+   * signal or one it drives from SIGINT/SIGTERM itself, so no process-wide
+   * handler is installed here.
+   */
+  signal: AbortSignal,
 ): Promise<0 | 1 | 2> {
-  const controller = new AbortController();
-  const abort = (): void => controller.abort();
-  process.once('SIGINT', abort);
-  process.once('SIGTERM', abort);
   let runId: string | undefined;
   // Flips at the run submission. An interruption before it — during prepare,
   // packing or upload — admitted nothing and is safe to retry; only an
   // interrupted submission has unknown admission.
   let submitting = false;
+  let harnesses: readonly string[] = [];
   try {
-    const options: RunInCloudOptions = { signal: controller.signal, onSubmit: () => { submitting = true; } };
+    const options: RunInCloudOptions = { signal, onSubmit: () => { submitting = true; } };
     if (isAuthoredFlowPath(path)) {
       // Same parse as a local direct run, so a file-or-inline argument means
       // the same thing on both sides of `--cloud`.
@@ -32,6 +36,15 @@ export async function runCloudCli(
         throw error;
       }
     }
+    // After local validation, before anything is packed or uploaded: a helper
+    // the run would call against an unconnected integration is connected
+    // here, or refused here. A command that is going to be refused for its
+    // arguments must not first open a browser.
+    const connections = await ensureFlowConnections({
+      path, prompt: cliConnectPrompt(io, { noConnect, json }),
+    }, { signal });
+    harnesses = connections?.requirements.harnesses ?? [];
+    for (const provider of connections?.outcome.connected ?? []) if (!json) io.stdout(`CONNECTED ${provider}`);
     // The tree is the invoking directory, as with v1: the flow path is where
     // the body lives, not the boundary of what the run may read.
     if (syncCode) options.syncCode = { root: process.cwd() };
@@ -51,28 +64,26 @@ export async function runCloudCli(
       if (json) io.stdout(JSON.stringify({ ok: true, ...receipt }));
       return 0;
     }
-    const run = await waitForCloudFlowRun(receipt.runId, { signal: controller.signal });
+    const run = await waitForCloudFlowRun(receipt.runId, { signal });
     const ok = run.status === 'completed';
     if (json) io.stdout(JSON.stringify({ ok, ...receipt, ...run }));
     else io.stdout(`${run.status.toUpperCase()} ${run.runId} completionReason: ${'completionReason' in run ? run.completionReason : 'unavailable'}`);
     return ok ? 0 : 1;
   } catch (error) {
-    const code = controller.signal.aborted
+    const code = signal.aborted
       ? runId ? 'observation_aborted' : submitting ? 'admission_unknown' : 'submission_aborted'
       : error instanceof CloudFlowError ? error.code : 'cloud_run_failed';
-    const message = controller.signal.aborted
+    const message = signal.aborted
       ? runId ? 'Stopped observing; the hosted run has not been cancelled.'
         : submitting
           ? 'Submission interrupted before a receipt was received. Admission is unknown; Cloud may have started the run. Do not resubmit blindly.'
           : 'Interrupted before the run was submitted; nothing was admitted. Safe to run again.'
-      : error instanceof Error ? error.message : 'Cloud run failed.';
+      : (error instanceof Error ? error.message : 'Cloud run failed.') + harnessRemedy(error, harnesses);
     if (json) io.stdout(JSON.stringify({ ok: false, code, message, ...(runId ? { runId } : {}) }));
     else io.stderr(`${code}: ${message}${runId ? ` (run ${runId})` : ''}`);
     return error instanceof CloudFlowError
-      && (['configuration', 'unsupported_source', 'invalid_input', 'unsupported_storage_backend', 'sync_too_large', 'sync_unsupported'].includes(error.code)
+      && (['configuration', 'unsupported_source', 'invalid_input', 'unsupported_storage_backend', 'sync_too_large', 'sync_unsupported',
+        'integration_not_connected'].includes(error.code)
         || (runId === undefined && error.code === 'http_error' && [401, 403].includes(error.status ?? 0))) ? 2 : 1;
-  } finally {
-    process.off('SIGINT', abort);
-    process.off('SIGTERM', abort);
   }
 }

package/src/cli/cloud-schedule.ts

@@ -1,7 +1,8 @@
 import { CloudFlowError } from '../cloud-http.js';
-import { listCloudSchedules, scheduleInCloud, unscheduleInCloud, type CloudSchedule } from '../cloud-schedule.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 {
@@ -12,12 +13,14 @@ export interface CloudScheduleArgs {
   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>] [--json]`
+ *   [--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
@@ -29,6 +32,7 @@ export function parseCloudScheduleArgs(args: readonly string[]): CloudScheduleAr
     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') {
@@ -36,6 +40,11 @@ export function parseCloudScheduleArgs(args: readonly string[]): CloudScheduleAr
       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];
@@ -51,7 +60,7 @@ export function parseCloudScheduleArgs(args: readonly string[]): CloudScheduleAr
   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 };
+  return { command: 'schedule', value, ...flags, noConnect, json };
 }
 
 function describe(schedule: CloudSchedule): string {
@@ -61,6 +70,7 @@ function describe(schedule: CloudSchedule): string {
 }
 
 export async function runCloudScheduleCli(args: CloudScheduleArgs, io: CliIo): Promise<0 | 1 | 2> {
+  let harnesses: readonly string[] = [];
   try {
     let input: JsonValue | undefined;
     let inputPresent = false;
@@ -73,6 +83,18 @@ export async function runCloudScheduleCli(args: CloudScheduleArgs, io: CliIo): P
         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 }),
@@ -86,10 +108,11 @@ export async function runCloudScheduleCli(args: CloudScheduleArgs, io: CliIo): P
       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);
+    return reportFailure(error, args.json, io, harnesses);
   }
 }
 
@@ -120,9 +143,10 @@ export async function runCloudUnscheduleCli(
   }
 }
 
-function reportFailure(error: unknown, json: boolean, io: CliIo): 1 | 2 {
+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`.';
@@ -130,6 +154,7 @@ function reportFailure(error: unknown, json: boolean, io: CliIo): 1 | 2 {
   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)
+    && (['configuration', 'unsupported_source', 'invalid_input', 'integration_not_connected'].includes(error.code)
+      || error.status === 403 || error.status === 401)
     ? 2 : 1;
 }

package/src/cli/cloud-sync.ts

@@ -1,5 +1,7 @@
 import { CloudFlowError } from '../cloud-http.js';
-import { applyCloudPatch, downloadCloudPatch, patchedPaths } from '../cloud-sync.js';
+import {
+  applyCloudPatch, downloadCloudPatchSet, excludedPatchPaths, patchedPaths, type CloudPathPatch,
+} from '../cloud-sync.js';
 import type { CliIo } from '../cli.js';
 
 /**
@@ -7,23 +9,50 @@ import type { CliIo } from '../cli.js';
  * and apply it here. The patch is the sandbox's own `git diff` against the
  * uploaded baseline, so applying it reproduces exactly what the run's steps
  * wrote — no re-execution, no re-upload.
+ *
+ * The agent runtime's own bookkeeping inside that tree is dropped on the way
+ * in (`CLOUD_SYNC_PATCH_EXCLUDES`); `--dry-run` prints the patch instead of
+ * applying it, and a run that produced one patch per mounted path is shown but
+ * never applied, because no single `--dir` is the right destination for all of
+ * them.
  */
 export async function runCloudSyncCli(
-  { runId, json, root }: { runId: string; json: boolean; root: string },
+  { runId, json, root, dryRun }: { runId: string; json: boolean; root: string; dryRun: boolean },
   io: CliIo,
 ): Promise<0 | 1 | 2> {
   try {
-    const { patch, hasChanges } = await downloadCloudPatch(runId, {});
-    if (!hasChanges || !patch.trim()) {
+    const set = await downloadCloudPatchSet(runId, {});
+    // A single-tree run can answer `hasChanges: true` with an empty body. The
+    // multi-path branch already discounts those (`patch.trim() !== ''` in
+    // `downloadCloudPatchSet`), and so did `agent-relay cloud sync`, which this
+    // command replaces. Without the same guard an empty patch reaches `git
+    // apply`, which fails as `patch_conflict` instead of reporting NO CHANGES.
+    const hasChanges = set.kind === 'single' ? set.hasChanges && set.patch.trim() !== '' : set.hasChanges;
+    if (!hasChanges) {
       if (json) io.stdout(JSON.stringify({ ok: true, runId, hasChanges: false, applied: false }));
       else io.stdout(`NO CHANGES ${runId}`);
       return 0;
     }
-    applyCloudPatch(root, patch);
-    const files = patchedPaths(patch);
-    if (json) io.stdout(JSON.stringify({ ok: true, runId, hasChanges: true, applied: true, files }));
+    if (set.kind === 'multi-path') {
+      const changed = set.patches.filter(entry => entry.hasChanges && entry.patch.trim() !== '');
+      if (!dryRun) {
+        throw new CloudFlowError('sync_unsupported',
+          `Run ${runId} produced ${changed.length} path-scoped patch${changed.length === 1 ? '' : 'es'} `
+          + `(${changed.map(entry => entry.name).join(', ')}); flows sync applies single-tree runs only. `
+          + 'Inspect them with --dry-run, then apply each in its own repository.');
+      }
+      reportMultiPathDryRun(runId, changed, json, io);
+      return 0;
+    }
+    if (dryRun) {
+      reportDryRun(runId, set.patch, json, io);
+      return 0;
+    }
+    const { files, excluded } = applyCloudPatch(root, set.patch);
+    if (json) io.stdout(JSON.stringify({ ok: true, runId, hasChanges: true, applied: true, files, excluded }));
     else {
-      io.stdout(`APPLIED ${runId}: ${files.length} file${files.length === 1 ? '' : 's'}${files.length ? `\n  ${files.join('\n  ')}` : ''}`);
+      io.stdout(`APPLIED ${runId}: ${files.length} file${files.length === 1 ? '' : 's'}${indented(files)}`);
+      if (excluded.length) io.stdout(`SKIPPED agent runtime paths: ${excluded.length}${indented(excluded)}`);
       io.stdout('Applied to the working tree, uncommitted: review with git diff before keeping it.');
     }
     return 0;
@@ -35,3 +64,51 @@ export async function runCloudSyncCli(
     return error instanceof CloudFlowError && ['configuration', 'sync_unsupported', 'patch_conflict'].includes(error.code) ? 2 : 1;
   }
 }
+
+/** A single-tree patch, shown rather than applied. */
+function reportDryRun(runId: string, patch: string, json: boolean, io: CliIo): void {
+  const excluded = excludedPatchPaths(patch);
+  const files = patchedPaths(patch).filter(path => !excluded.includes(path));
+  if (json) {
+    // The patch travels in the payload, not on stdout beside it: a --json
+    // consumer parses one object, and a diff printed alongside it is not JSON.
+    io.stdout(JSON.stringify({
+      ok: true, runId, hasChanges: true, applied: false, dryRun: true, files, excluded, patch,
+    }));
+    return;
+  }
+  io.stdout(`DRY RUN ${runId}: ${files.length} file${files.length === 1 ? '' : 's'} would be written${indented(files)}`);
+  if (excluded.length) io.stdout(`Would skip agent runtime paths: ${excluded.length}${indented(excluded)}`);
+  emitPatch(patch, io);
+}
+
+/** Every changed path-scoped patch, shown; applying them is not this command's call. */
+function reportMultiPathDryRun(
+  runId: string, changed: readonly CloudPathPatch[], json: boolean, io: CliIo,
+): void {
+  if (json) {
+    io.stdout(JSON.stringify({
+      ok: true, runId, hasChanges: true, applied: false, dryRun: true, multiPath: true,
+      patches: changed.map(({ name, patch }) => {
+        const excluded = excludedPatchPaths(patch);
+        return { name, files: patchedPaths(patch).filter(path => !excluded.includes(path)), excluded, patch };
+      }),
+    }));
+    return;
+  }
+  io.stdout(`DRY RUN ${runId}: ${changed.length} path-scoped patch${changed.length === 1 ? '' : 'es'}`);
+  io.stdout('Each targets its own repository; apply them there, not with --dir.');
+  for (const { name, patch } of changed) {
+    io.stdout(`--- patch for path "${name}" ---`);
+    emitPatch(patch, io);
+  }
+}
+
+/** Write a diff through the line-oriented io without gaining or losing a newline. */
+function emitPatch(patch: string, io: CliIo): void {
+  for (const line of patch.replace(/\n$/u, '').split('\n')) io.stdout(line);
+}
+
+function indented(paths: readonly string[]): string {
+  return paths.length ? `\n  ${paths.join('\n  ')}` : '';
+}

package/src/cli/deploy.ts

@@ -4,19 +4,35 @@ import { BundleFailure, bucketDirectory, copyBundle, exists, parseDigestReferenc
   verifyDigest, writableBucket } from '../bundle-transport.js';
 import { checkRunnableBundle } from './bundle-preflight.js';
 
-export interface DeployArgs { command: 'deploy'; value: string; to: string }
+export interface DeployArgs { command: 'deploy'; value: string; to: string; json: boolean }
+
+/**
+ * `--json` is declared on the `deploy` verb, which both forms share, so the
+ * bundle form has to accept it too -- the hosted-listener parser already did,
+ * and help cannot tell a reader the flag belongs to only one of them.
+ */
 export function parseDeployArgs(args: readonly string[]): DeployArgs | undefined {
   let value: string | undefined;
   let to: string | undefined;
+  let json = false;
   for (let i = 0; i < args.length; i++) {
     const arg = args[i]!;
     if (arg === '--to') {
       if (to !== undefined || !args[i + 1] || args[i + 1]!.startsWith('-')) return undefined;
       to = args[++i];
+    } else if (arg === '--json') {
+      if (json) return undefined;
+      json = true;
     } else if (arg.startsWith('-') || value !== undefined) return undefined;
     else value = arg;
   }
-  return value && to && parseDigestReference(value) ? { command: 'deploy', value, to } : undefined;
+  return value && to && parseDigestReference(value) ? { command: 'deploy', value, to, json } : undefined;
+}
+
+/** One machine-readable object per outcome, or the text line it mirrors. */
+function emitDeployOutcome(status: 'deployed' | 'already-present', args: DeployArgs, io: CliIo): void {
+  if (args.json) io.stdout(JSON.stringify({ ok: true, bundle: args.value, to: args.to, status }));
+  else io.stdout(`${status === 'deployed' ? 'DEPLOYED' : 'SKIPPED (already-present)'} ${args.value} ${args.to}`);
 }
 export async function runDeploy(args: DeployArgs, io: CliIo): Promise<0 | 1 | 2> {
   let started = false;
@@ -29,6 +45,10 @@ export async function runDeploy(args: DeployArgs, io: CliIo): Promise<0 | 1 | 2>
     const checked = await checkRunnableBundle(source, ref.name);
     if (!checked.report.ok) {
       for (const diagnostic of checked.report.diagnostics) io.stderr(`${diagnostic.severity.toUpperCase()} [${diagnostic.kind}] ${diagnostic.message}`);
+      if (args.json) {
+        io.stdout(JSON.stringify({ ok: false, code: 'bundle_unrunnable', bundle: args.value, to: args.to,
+          diagnostics: checked.report.diagnostics }));
+      }
       return 2;
     }
     // `ok` may still carry warnings (e.g. `budget_unmetered`); report them.
@@ -39,18 +59,20 @@ export async function runDeploy(args: DeployArgs, io: CliIo): Promise<0 | 1 | 2>
     if (await exists(target)) {
       await verifyDigest(target, ref.digest);
       io.stderr(`deploy_noop: ${args.value}`);
-      io.stdout(`SKIPPED (already-present) ${args.value} ${args.to}`);
+      emitDeployOutcome('already-present', args, io);
       return 0;
     }
     await writableBucket(target);
     started = true;
     const copied = await copyBundle(source, target, ref.digest);
     if (!copied) io.stderr(`deploy_noop: ${args.value}`);
-    io.stdout(`${copied ? 'DEPLOYED' : 'SKIPPED (already-present)'} ${args.value} ${args.to}`);
+    emitDeployOutcome(copied ? 'deployed' : 'already-present', args, io);
     return 0;
   } catch (error) {
     const kind = started ? 'deploy_partial' : error instanceof BundleFailure ? error.kind : 'bucket_unreachable';
-    io.stderr(`${started ? 'FAILED' : 'REFUSED'} [${kind}] ${error instanceof Error ? error.message : String(error)}`);
+    const message = error instanceof Error ? error.message : String(error);
+    io.stderr(`${started ? 'FAILED' : 'REFUSED'} [${kind}] ${message}`);
+    if (args.json) io.stdout(JSON.stringify({ ok: false, code: kind, message, bundle: args.value, to: args.to }));
     return started ? 1 : 2;
   }
 }

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,
@@ -175,6 +177,9 @@ export async function runDirectFlow(
     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>;
@@ -226,6 +233,9 @@ export async function resumeFlow(
     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);
     }
@@ -298,6 +308,42 @@ export function authoredStepFailure(
   };
 }
 
+/**
+ * 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)}`,
+      }],
+    },
+  };
+}
+
 /**
  * An authored body that returned its own terminal verdict, reported as that verdict.
  *