@relayflows/sdk 2.0.42 → 2.0.44

package/src/authored-root.ts

@@ -1,3 +1,4 @@
+import { isReadInterruptionError } from './journal-read-policy.js';
 import { loadPinnedAuthoredSource } from './authored-source-authority.js';
 import { assertAuthoredRuntimeAvailable, runAuthoredInNode } from './authored-node-runner.js';
 import { createHash, randomUUID } from 'node:crypto';
@@ -5,7 +6,6 @@ import { readFile } from 'node:fs/promises';
 import { canonicalize } from './canonical.js';
 import { compileSpec, toKernelSpec } from './compile.js';
 import { executeAuthoredFlow, type AuthoredFlowExecutionResult, type AuthoredFlowSuspendedResult } from './authored-flow-executor.js';
-import { isDurableCompletionDetail, isLoweredCompletion } from './authored-completion.js';
 import { AUTHORED_ROOT_KIND } from './authored-verdict.js';
 import {
   loadAuthoredFlow,
@@ -19,9 +19,9 @@ import type { RunLifecycleOptions } from './cli/run.js';
 import { isLeaseLost, withWorkerLease } from './worker-lease.js';
 import { AuthoredFlowExecutionError, AuthoredHumanParked } from './authored-flow-error.js';
 import { readOpenHumanWaits, resumeCommand } from './authored-human.js';
-import { isSurfaceCompletionReason } from './authored-step-output.js';
 import { readSubscriptionPark } from './authored-subscription-park.js';
 import { localAgentCredentialEnvironment } from './local-agent-environment.js';
+import { completedResult, rootKernelStep, rootStepIfPresent } from './authored-root-readback.js';
 
 export type DurableAuthoredFlowResult =
   | (AuthoredFlowExecutionResult & { readonly rootRunId: string })
@@ -117,9 +117,10 @@ export async function executeDurableAuthoredFlow(
     });
     const outcome = await journal.runStart(spec, undefined, admissionKey);
     options.onAdmitted?.(outcome.run_id);
+    options.lifecycle?.onRunReceipt?.({ runId: outcome.run_id, flow: definition.name });
     if (outcome.status === 'completed') {
       dispatchWait.cancel();
-      return await completedRootResult(journal, outcome.run_id);
+      return await completedResult(journal, outcome, outcome.run_id);
     }
     assertRootCanDispatch(outcome);
     options.lifecycle?.onRunStarted?.({ runId: outcome.run_id, flow: definition.name });
@@ -166,9 +167,10 @@ export async function resumeDurableAuthoredFlow(
       workspace: [], streams: [{ stream, read_offset: 0 }],
     });
     const outcome = await journal.runResume(rootRunId);
+    options.lifecycle?.onRunReceipt?.({ runId: rootRunId, flow: metadata.flowName });
     if (outcome.status === 'completed') {
       dispatchWait.cancel();
-      return await completedRootResult(journal, rootRunId);
+      return await completedResult(journal, outcome, rootRunId);
     }
     assertRootCanDispatch(outcome);
     await assertNoOpenHumanWait(journal, outcome);
@@ -199,7 +201,7 @@ export async function readAuthoredRootMetadata(
   journal: JournalClient,
   runId: string,
 ): Promise<AuthoredRootMetadata | undefined> {
-  const step = await rootKernelStep(journal, runId).catch(() => undefined);
+  const step = await rootStepIfPresent(journal, runId);
   if (step === undefined || step.id !== 'authored-root' || !hasRootStream(step)) return undefined;
   if (typeof step.instruction !== 'string') {
     throw new Error('authored root journal has malformed authority metadata');
@@ -320,38 +322,43 @@ async function driveRoot(
 ): Promise<DurableAuthoredFlowResult> {
   try {
     const result = await withWorkerLease(peer, dispatch, async rootSignal => {
-      const callerSignal = options.lifecycle?.signal;
-      const signal = callerSignal === undefined ? rootSignal : AbortSignal.any([callerSignal, rootSignal]);
-      if (process.versions['bun'] !== undefined) {
-        return runAuthoredInNode(metadata, journal.socketPath, dispatch.run_id, {
-          dataDir: options.dataDir, localAgentStream: options.localAgentStream,
-          ...(options.agentEnvironment === undefined ? {} : {
-            agentEnvironment: localAgentCredentialEnvironment(options.agentEnvironment),
-          }),
-          ...(options.workerCapacity === undefined ? {} : { workerCapacity: options.workerCapacity }),
-          ...options.lifecycle, signal,
-        });
-      }
-      return await executeAuthoredFlow(
-        loaded.handle,
-        journal,
-        metadata.inputPresent ? metadata.input : undefined,
-        {
-          getDefinition: loaded.getDefinition,
-          dataDir: options.dataDir,
-          flowPath: metadata.flowPath,
-          localAgentStream: options.localAgentStream,
-          ...(options.agentEnvironment === undefined ? {} : { agentEnvironment: options.agentEnvironment }),
-          ...(options.workerCapacity === undefined ? {} : { workerCapacity: options.workerCapacity }),
-          rootRunId: dispatch.run_id,
-          extensions: loaded.extensions,
-          flowGraph: loaded.graph,
-          ...options.lifecycle,
-          signal: callerSignal === undefined
-            ? rootSignal
-            : AbortSignal.any([callerSignal, rootSignal]),
-        },
-      );
+      // A lost root lease must also stop body reads still inside their budget.
+      const releaseReads = journal.scopeReads?.(rootSignal) ?? (() => {});
+      try {
+        const callerSignal = options.lifecycle?.signal;
+        const signal = callerSignal === undefined ? rootSignal : AbortSignal.any([callerSignal, rootSignal]);
+        if (process.versions['bun'] !== undefined) {
+          // Awaited, so the read scope below covers the child's whole run.
+          return await runAuthoredInNode(metadata, journal.socketPath, dispatch.run_id, {
+            dataDir: options.dataDir, localAgentStream: options.localAgentStream,
+            ...(options.agentEnvironment === undefined ? {} : {
+              agentEnvironment: localAgentCredentialEnvironment(options.agentEnvironment),
+            }),
+            ...(options.workerCapacity === undefined ? {} : { workerCapacity: options.workerCapacity }),
+            ...options.lifecycle, signal,
+          });
+        }
+        return await executeAuthoredFlow(
+          loaded.handle,
+          journal,
+          metadata.inputPresent ? metadata.input : undefined,
+          {
+            getDefinition: loaded.getDefinition,
+            dataDir: options.dataDir,
+            flowPath: metadata.flowPath,
+            localAgentStream: options.localAgentStream,
+            ...(options.agentEnvironment === undefined ? {} : { agentEnvironment: options.agentEnvironment }),
+            ...(options.workerCapacity === undefined ? {} : { workerCapacity: options.workerCapacity }),
+            rootRunId: dispatch.run_id,
+            extensions: loaded.extensions,
+            flowGraph: loaded.graph,
+            ...options.lifecycle,
+            signal: callerSignal === undefined
+              ? rootSignal
+              : AbortSignal.any([callerSignal, rootSignal]),
+          },
+        );
+      } finally { releaseReads(); }
     });
     await peer.stepComplete(
       dispatch.run_id, dispatch.step_id, dispatch.attempt,
@@ -368,6 +375,20 @@ async function driveRoot(
     // A lost lease is owned by the kernel's retry path, not by this attempt's
     // terminalization or suspension handling.
     if (isLeaseLost(error)) throw error;
+    // A caller cancel is the caller's, not a body failure: reads aborted by it
+    // (including the Bun verifier's) leave the root resumable, never terminal.
+    const signal = options.lifecycle?.signal;
+    if (aborted(signal) && (error === signal!.reason || (error instanceof Error && error.name === 'AbortError'))) {
+      if (error instanceof Error) (error as Error & { rootRunId?: string }).rootRunId = dispatch.run_id;
+      throw error;
+    }
+    if (isReadInterruptionError(error)
+      || (error instanceof AuthoredFlowExecutionError && error.code === 'daemon_unresponsive')) {
+      const parked = new AuthoredFlowExecutionError('daemon_unresponsive',
+        `${error.message}. The run remains resumable. Continue with: ${resumeCommand(dispatch.run_id, options.dataDir, options.localAgentStream !== undefined)}.`);
+      parked.rootRunId = dispatch.run_id;
+      throw parked;
+    }
     if (error instanceof AuthoredFlowExecutionError
       && error.code === 'subscription_suspended'
       && error.suspension !== undefined) {
@@ -450,16 +471,6 @@ function rootSpec(metadata: AuthoredRootMetadata, stream: string) {
   }));
 }
 
-async function rootKernelStep(journal: JournalClient, runId: string): Promise<Record<string, unknown>> {
-  const entries = (await journal.journalRead(runId, 1)).entries as Array<Record<string, unknown>>;
-  const spawned = entries.find(entry => entry.entry_type === 'run.spawned');
-  const payload = spawned?.payload as { spec?: { steps?: unknown[] } } | undefined;
-  const step = payload?.spec?.steps?.[0];
-  if (typeof step !== 'object' || step === null || Array.isArray(step)) {
-    throw new Error('authored root journal has no root step');
-  }
-  return step as Record<string, unknown>;
-}
 
 function rootStreamFromMetadata(step: Record<string, unknown>): string {
   const surfaces = step.surfaces as { streams?: Array<{ stream?: unknown }> } | undefined;
@@ -543,44 +554,6 @@ function nextRootDispatch(peer: JournalClient, timeoutMs = 30_000): {
   return { promise, cancel };
 }
 
-async function completedRootResult(
-  journal: JournalClient,
-  rootRunId: string,
-): Promise<AuthoredFlowExecutionResult & { readonly rootRunId: string }> {
-  const entries = (await journal.journalRead(rootRunId, 1)).entries as Array<Record<string, unknown>>;
-  const completed = entries.slice().reverse().find(entry => entry.entry_type === 'step.completed'
-    && entry.step_id === 'authored-root'
-    && (entry.payload as { completionReason?: unknown } | undefined)?.completionReason === 'success');
-  const output = (completed?.payload as { output?: unknown } | undefined)?.output;
-  if (!isCompletedRootOutput(output)) {
-    throw new Error('completed authored root has no durable result');
-  }
-  // The stored detail, never a freshly computed one: redaction reads the
-  // CURRENT environment, so recomputing here would let a completed run report
-  // something its journal does not hold.
-  return Object.freeze({
-    name: output.name,
-    completionReason: output.completionReason,
-    ...(output.completionDetail === undefined ? {} : { completionDetail: output.completionDetail }),
-    journalSteps: Object.freeze(output.journalSteps.map(step => Object.freeze({ ...step }))),
-    rootRunId,
-  });
-}
-
-function isCompletedRootOutput(value: unknown): value is Omit<AuthoredFlowExecutionResult, 'rootRunId'> {
-  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false;
-  const output = value as Partial<AuthoredFlowExecutionResult>;
-  return typeof output.name === 'string'
-    && isLoweredCompletion(output.completionReason)
-    // A malformed detail fails the whole readback rather than being dropped:
-    // silently discarding it would report the verdict without the evidence
-    // the journal says it was recorded with.
-    && (output.completionDetail === undefined || isDurableCompletionDetail(output.completionDetail))
-    && Array.isArray(output.journalSteps)
-    && output.journalSteps.every(step => typeof step === 'object' && step !== null
-      && typeof step.id === 'string' && typeof step.runId === 'string'
-      && isSurfaceCompletionReason(step.completionReason));
-}
 
 function assertRootCanDispatch(outcome: RunOutcome): void {
   // The kernel reports `parked` after handing an agent lease to its worker;

package/src/authored-step-output.ts

@@ -23,6 +23,8 @@ export interface AuthoredStepContext {
   readonly stepEdges?: (step: string) => AuthoredStepEdges | undefined;
   /** Cancels the wait for an adopted child run that is not yet terminal. */
   readonly signal?: AbortSignal;
+  /** Sees the accepted completion's payload (its evidence, not only its output). */
+  readonly onCompleted?: (payload: Readonly<Record<string, unknown>>) => void;
 }
 
 /**
@@ -149,6 +151,7 @@ export async function readCompletedStepOutput(
   await recordAuthoredChild(journal, context.rootRunId, {
     step: stepId, runId, state: 'completed', completionReason: reason, ...edges,
   });
+  context.onCompleted?.(completed.payload as unknown as Readonly<Record<string, unknown>>);
   return completed.payload.output;
 }
 

package/src/authored-worker-step.ts

@@ -9,6 +9,7 @@ import { classifyOutcome, type RunLifecycleOptions, type RunReport } from './cli
 import type { PreflightDiagnostic } from './preflight.js';
 import { AuthoredFlowExecutionError } from './authored-flow-error.js';
 import { agentCwdDeclarationError, agentCwdTransportError } from './agent-cwd.js';
+import { agentResumeDeclarationError, agentResumeTransportError } from './agent-resume.js';
 import type { JournalClient } from './journal-client.js';
 import { SPEC_SCHEMA_VERSION, type FlowSpec, type PermissionsSpec, type StepSpec } from './spec.js';
 import { isSurfaceCompletionReason, readCompletedStepOutput, readRecordedOutcome, readSuccessfulOutput, type AuthoredStepContext, type RecordedRunOutcome } from './authored-step-output.js';
@@ -46,7 +47,7 @@ export function authoredWorkerRunner(
     ...(stepEdges === undefined ? {} : { stepEdges }),
     ...(waitOptions.signal === undefined ? {} : { signal: waitOptions.signal }),
   };
-  async function run(step: StepSpec): Promise<unknown> {
+  async function run(step: StepSpec, onCompleted?: AuthoredStepContext['onCompleted']): Promise<unknown> {
     const id = step.id;
     const authoring: FlowSpec = { version: SPEC_SCHEMA_VERSION, name: `${definition.name}/${id}`, steps: [step], ...(headerBudget === undefined ? {} : { budget: parseBudget(headerBudget) }) };
     // The kernel never resolves a `cli` on its own — every declarative
@@ -152,7 +153,8 @@ export function authoredWorkerRunner(
         details,
       );
     }
-    return readCompletedStepOutput(journal, outcome.run_id, id, journalSteps, context, execution.report.status);
+    return readCompletedStepOutput(journal, outcome.run_id, id, journalSteps,
+      onCompleted === undefined ? context : { ...context, onCompleted }, execution.report.status);
     };
     const admissionKey = authoredChildAdmissionKey(rootRunId, id);
     const admit = async () => budget === undefined
@@ -250,6 +252,11 @@ export function authoredWorkerRunner(
           `f.agent options.recoveryMode must be 'reset', 'inspect', or 'manual' (got ${JSON.stringify(options.recoveryMode)}).`,
         );
       }
+      const resumeProblem = options.resume === undefined ? undefined
+        : agentResumeDeclarationError(options.resume) ?? agentResumeTransportError(options.resume, options.transport);
+      if (resumeProblem !== undefined) {
+        throw new AuthoredFlowExecutionError('agent_cli_unresolved', `f.agent options.resume: ${resumeProblem}.`);
+      }
       const cwdTransport = agentCwdTransportError(declaredCwd, options.transport);
       if (cwdTransport !== undefined) {
         throw new AuthoredFlowExecutionError('agent_cli_unresolved', `f.agent options.${cwdTransport}.`);
@@ -263,6 +270,7 @@ export function authoredWorkerRunner(
             'f.agent timeout requires direct transport and maxIterations 1.');
         }
       }
+      let sessionId: string | undefined;
       const permissions = options.permissions;
       const permissionsSnapshot = permissions === undefined ? undefined
         : snapshotJsonValue(permissions, 'f.agent options.permissions') as unknown as PermissionsSpec;
@@ -275,12 +283,13 @@ export function authoredWorkerRunner(
         ...(options.cli === undefined ? {} : { cli: options.cli }),
         ...(options.model === undefined ? {} : { model: options.model }),
         ...(declaredCwd === undefined ? {} : { cwd: declaredCwd }),
+        ...(options.resume === undefined ? {} : { resume: options.resume }),
         ...(options.transport === undefined ? {} : { transport: options.transport }),
         ...(options.maxIterations === undefined ? {} : { maxIterations: options.maxIterations }),
         ...(options.transportRetries === undefined ? {} : { transportRetries: options.transportRetries }),
         ...(options.recoveryMode === undefined ? {} : { recoveryMode: options.recoveryMode }),
         ...(verification === undefined ? {} : { verification }),
-      });
+      }, (payload) => { sessionId = journaledSessionId(payload); });
       if (typeof output !== 'object' || output === null || Array.isArray(output)) {
         throw new AuthoredFlowExecutionError('journal_protocol_violation', `step "${id}" produced a non-object output`);
       }
@@ -294,7 +303,10 @@ export function authoredWorkerRunner(
       const journaled = 'artifacts' in output ? output.artifacts : undefined;
       const artifacts = Array.isArray(journaled) && journaled.every(entry => typeof entry === 'string')
         ? [...journaled] : [];
-      return { completionReason: 'success', summary: typeof stdout === 'string' ? stdout : JSON.stringify(output), artifacts };
+      return {
+        completionReason: 'success', summary: typeof stdout === 'string' ? stdout : JSON.stringify(output), artifacts,
+        ...(sessionId === undefined ? {} : { sessionId }),
+      };
     },
     async llm(id: string, prompt: string, options?: LlmOptions, verification?: NamedGate): Promise<unknown> {
       if (options !== undefined && (typeof options !== 'object' || options === null || options.output === undefined)) {
@@ -411,3 +423,16 @@ function stepDetails(
   };
   return Object.keys(details).length === 0 ? undefined : details;
 }
+
+/**
+ * The CLI session the worker journaled for an agent attempt
+ * (`trajectory_tail.transcript.result.session_id`). Evidence, so it is read on
+ * the JSON-answer path too, and offered only when it is a session id a later
+ * `resume` would accept (a bounded label never is one).
+ */
+function journaledSessionId(payload: Readonly<Record<string, unknown>>): string | undefined {
+  const field = (value: unknown, key: string): unknown =>
+    value !== null && typeof value === 'object' && !Array.isArray(value) ? (value as Record<string, unknown>)[key] : undefined;
+  const id = field(field(field(payload.trajectory_tail, 'transcript'), 'result'), 'session_id');
+  return typeof id === 'string' && agentResumeDeclarationError(id) === undefined ? id : undefined;
+}

package/src/cli/check-helper-body.ts

@@ -1,13 +1,19 @@
 import { loadAuthoredFlow } from '../authored-flow-loader.js';
 import { PluginError } from '../plugin-manifest.js';
 import { checkSlackHelpers } from '../slack-preflight.js';
-import { inputFailureReport, type CheckExecution } from './check.js';
+import { inputFailureReport, type CheckInvocation, type CheckExecution } from './check.js';
+
+import { helperCredentialDiagnostics } from './check-helper-surface.js';
 
 /** Imports the definition, but never executes arbitrary authored body code. */
-export async function checkHelperBody(path: string): Promise<CheckExecution> {
+export async function checkHelperBody(path: string, invocation: CheckInvocation = {}): Promise<CheckExecution> {
   try {
     const { handle, getDefinition } = await loadAuthoredFlow(path);
-    return { report: { ...checkSlackHelpers(getDefinition(handle)), path } };
+    const report = checkSlackHelpers(getDefinition(handle));
+    const diagnostics = invocation.warnUnresolvedHelperCredential === true
+      ? helperCredentialDiagnostics(report.diagnostics).diagnostics : report.diagnostics;
+    return { report: { ...report, path, diagnostics,
+      ok: !diagnostics.some(diagnostic => diagnostic.severity === 'refusal') } };
   } catch (error) {
     if (error instanceof PluginError) {
       return { report: inputFailureReport({ kind: error.code, message: error.message }, path) };

package/src/cli/check-helper-surface.ts

@@ -0,0 +1,43 @@
+import { helperProviders } from '@relayflows/surface/runtime';
+import type { PreflightDiagnostic } from '../preflight.js';
+import type { CheckWarningDiagnostic } from './check.js';
+
+const mountKinds = new Set([
+  'helper_slack.credential_missing', 'helper_slack.mount_required',
+  'helper_provider.mount_required', 'helper_mount_required',
+]);
+
+/** Restate local mount failures for inspection only; execution stays strict. */
+export function helperCredentialDiagnostics(diagnostics: readonly PreflightDiagnostic[]): {
+  diagnostics: Array<PreflightDiagnostic | CheckWarningDiagnostic>;
+  downgraded: boolean;
+} {
+  const result: Array<PreflightDiagnostic | CheckWarningDiagnostic> = [];
+  const seen = new Set<string>();
+  for (const diagnostic of diagnostics) {
+    const helper = diagnostic.severity === 'refusal' && mountKinds.has(diagnostic.kind)
+      ? helperProviders.find(({ namespace, provider }) =>
+        diagnostic.message.startsWith(`f.${namespace} requires `)
+        || diagnostic.message.startsWith(`${provider} helper requires `))
+      : undefined;
+    // Unknown diagnostic shapes remain refusals rather than silently passing.
+    if (helper === undefined) {
+      result.push(diagnostic);
+      continue;
+    }
+    if (seen.has(helper.provider)) continue;
+    seen.add(helper.provider);
+    // YAML execution (helper_mount_required) honours a mock only for Slack
+    // (yaml-helper-effect.ts helperReady); every other YAML helper needs a mount.
+    const mockSupported = diagnostic.kind !== 'helper_mount_required' || helper.provider === 'slack';
+    result.push({
+      severity: 'warning', kind: 'helper_credential_unresolved',
+      message: `f.${helper.namespace} needs a ${helper.provider} mount, which is not available locally. `
+        + 'flows schedule / flows deploy / flows run --cloud check the integration against your workspace at submit and refuse if Cloud cannot connect it. '
+        + `A local flows run needs a relayfile ${helper.provider} mount (a ${helper.provider}/ directory under RELAYFILE_MOUNT_PATH)`
+        + (mockSupported ? ` or ${helper.mockEnv}=1` : '')
+        + `, and refuses with [${diagnostic.kind}] without one.`,
+    });
+  }
+  return { diagnostics: result, downgraded: seen.size > 0 };
+}

package/src/cli/check-triggers.ts

@@ -7,16 +7,19 @@ import { scheduleLowering } from '../schedule-trigger.js';
 import { checkSlackHelpers } from '../slack-preflight.js';
 import { flowRequirements, mergeFlowExtensionRequirements } from '../flow-requirements.js';
 import { PluginError } from '../plugin-manifest.js';
-import { inputFailureReport, readProjectConfig, type CheckReport } from './check.js';
+import { inputFailureReport, readProjectConfig, type CheckInvocation, type CheckReport } from './check.js';
+
+import { helperCredentialDiagnostics } from './check-helper-surface.js';
 
 /**
  * Inspect an authored flow without running a handler or contacting the daemon.
  * Combines the two authored-only preflight paths that share a loaded flow: the
  * webhook-trigger check (E) and the f.slack helper check (B). Skipping either
  * turned this into a silent trapdoor -- a `.flow.ts` using `f.slack.post`
- * without a token would pass `flows check` and only crash at run.
+ * without a mount would silently pass inspection. Check may opt into a
+ * warning; local run keeps the default refusal before daemon attachment.
  */
-export async function checkAuthoredTriggers(path: string): Promise<{
+export async function checkAuthoredTriggers(path: string, invocation: CheckInvocation = {}): Promise<{
   report: CheckReport;
   loaded?: LoadedAuthoredFlow;
 }> {
@@ -33,8 +36,10 @@ export async function checkAuthoredTriggers(path: string): Promise<{
     // refused there, on the first real event.
     const providerDiagnostics = preflightProviderTriggers(triggers);
     const helperReport = checkSlackHelpers(definition);
+    const helperDiagnostics = invocation.warnUnresolvedHelperCredential === true
+      ? helperCredentialDiagnostics(helperReport.diagnostics).diagnostics : helperReport.diagnostics;
     const diagnostics = [
-      ...triggerDiagnostics, ...providerDiagnostics, ...helperReport.diagnostics,
+      ...triggerDiagnostics, ...providerDiagnostics, ...helperDiagnostics,
     ];
     // 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.

package/src/cli/check.ts

@@ -1,3 +1,4 @@
+import { validateSpecWithDaemon, type DaemonValidation, type DaemonValidationMode, type DaemonValidationDeps } from '../daemon-spec-validation.js';
 import { communicationInstruction } from '../communication/spec.js';
 import { rememberResolvedCliIdentities } from '../resolved-cli-identity.js';
 import { checkCommunicationEnvironment } from '../communication/preflight.js';
@@ -5,6 +6,7 @@ import { accessSync, constants, readFileSync } from 'node:fs';
 import { dirname, isAbsolute, join, parse as parsePath, resolve } from 'node:path';
 import { parse as parseYaml } from 'yaml';
 import { CompileError, compileSpec, kernelToAuthoring } from '../compile.js';
+import { helperCredentialDiagnostics } from './check-helper-surface.js';
 import { agentWorkerDiagnostics } from './check-worker-surface.js';
 import { helperReady } from '../yaml-helper-effect.js';
 import { flowRequirements, type FlowRequirements } from '../flow-requirements.js';
@@ -44,6 +46,7 @@ export interface ProjectConfig {
 }
 
 export interface CheckReport {
+  validation?: DaemonValidation;
   mcpTools?: Readonly<Record<string, readonly string[]>>;
   ok: boolean;
   path?: string;
@@ -125,6 +128,10 @@ type CliProbeOutcomeMap = Map<string, CliProbeOutcome>;
  * anything that depends on how the flow is about to be invoked opts in here.
  */
 export interface CheckInvocation {
+  /** Only flows check opts into reporting missing local helper mounts as warnings. */
+  warnUnresolvedHelperCredential?: boolean;
+  daemonValidation?: DaemonValidationMode;
+  daemonValidationDeps?: DaemonValidationDeps;
   /** Environment used only by provider executable/auth/model probes. */
   environment?: NodeJS.ProcessEnv;
   /**
@@ -159,7 +166,7 @@ export function checkFlow(path: string, invocation: CheckInvocation = {}): Check
       execution = checkAuthoredFlow(readFlow(source, absolutePath), path, undefined, invocation);
     } catch (error) {
       if (!(error instanceof CheckFailure)) throw error;
-      execution = { report: inputFailureReport(error, path) };
+      execution = { report: inputFailureReport(error, path, invocation) };
     }
     // The editor-schema hint is a documentation nudge, emitted for every
     // .flow.yaml without a first-line yaml-language-server comment.
@@ -172,14 +179,17 @@ export function checkFlow(path: string, invocation: CheckInvocation = {}): Check
     const failure = error instanceof CheckFailure
       ? error
       : new CheckFailure('invalid_spec', `Flow "${path}" could not be checked as a Relayflow spec.`);
-    return { report: inputFailureReport(failure, path) };
+    return { report: inputFailureReport(failure, path, invocation) };
   }
 }
 
 /** Requirements never turn a preflight refusal into an unrelated exception. */
 function safeRequirements(authoring: FlowSpec, projectCli: string | undefined): FlowRequirements | undefined {
   try {
-    return flowRequirements(authoring, projectCli === undefined ? {} : { projectCli });
+    let requirementsSpec = authoring;
+    try { requirementsSpec = compileSpec(authoring); }
+    catch { /* Preserve requirements from invalid authoring; preflight owns its refusal. */ }
+    return flowRequirements(requirementsSpec, projectCli === undefined ? {} : { projectCli });
   } catch {
     return undefined;
   }
@@ -220,7 +230,14 @@ export function checkAuthoredFlow(
       ...(config.modelRegistryPath !== undefined ? { modelRegistryPath: config.modelRegistryPath } : {}),
       probes,
     });
-    const flow = result.ok
+    // check may restate a missing local helper mount as a warning. When that is
+    // the only refusal, still compile the flow so the communication checks
+    // below run: they must not depend on whether a helper is mounted. The
+    // compiled flow is returned only when preflight itself admitted it.
+    const inspectOnly = !result.ok && invocation.warnUnresolvedHelperCredential === true
+      && !helperCredentialDiagnostics(result.diagnostics).diagnostics
+        .some(diagnostic => diagnostic.severity === 'refusal');
+    const flow = result.ok || inspectOnly
       ? bindResolvedCliPaths(
           compileSpec(authoring),
           result.resolutions,
@@ -246,14 +263,25 @@ export function checkAuthoredFlow(
     const workerSurface = invocation.warnUnresolvedAgentWorker === true
       ? agentWorkerDiagnostics(authoring)
       : [];
+    // A flow inspected past a missing helper mount is still a compiled spec the
+    // daemon must judge; skipping it would let a downgraded warning pass the gate.
+    const daemon = invocation.daemonValidation === undefined ? undefined
+      : (result.ok || inspectOnly) && flow !== undefined
+        ? validateSpecWithDaemon(flow, invocation.daemonValidation, invocation.daemonValidationDeps)
+        : { validation: { mode: 'local' as const, reason: 'not_reached' as const }, diagnostics: [] };
+    if (daemon?.diagnostics.some(d => d.severity === 'refusal')) result.ok = false;
+    const diagnostics = invocation.warnUnresolvedHelperCredential === true
+      ? helperCredentialDiagnostics(result.diagnostics).diagnostics : result.diagnostics;
     return {
       report: {
-        ok: result.ok,
+        ...(daemon === undefined ? {} : { validation: daemon.validation }),
+        ok: !diagnostics.some(diagnostic => diagnostic.severity === 'refusal')
+          && !(daemon?.diagnostics.some(diagnostic => diagnostic.severity === 'refusal') ?? false),
         path,
         ...(config.path !== undefined ? { projectConfigPath: config.path } : {}),
         gates: result.gates,
         resolutions: result.resolutions,
-        diagnostics: [...result.diagnostics, ...workerSurface],
+        diagnostics: [...diagnostics, ...workerSurface, ...(daemon?.diagnostics ?? [])],
         requirements: safeRequirements(authoring, config.cli),
       },
       ...(result.ok && flow !== undefined ? { flow } : {}),
@@ -262,7 +290,7 @@ export function checkAuthoredFlow(
     const failure = error instanceof CheckFailure
       ? error
       : new CheckFailure('invalid_spec', `Flow "${path}" could not be checked as a Relayflow spec.`);
-    return { report: inputFailureReport(failure, path) };
+    return { report: inputFailureReport(failure, path, invocation) };
   }
 }
 
@@ -335,8 +363,10 @@ export async function checkBuildableFlow(path: string): Promise<CheckExecution>
 export function inputFailureReport(
   failure: { kind: CheckFailureKind; message: string },
   path?: string,
+  invocation: CheckInvocation = {},
 ): CheckReport {
   return {
+    ...(invocation.daemonValidation === undefined ? {} : { validation: { mode: 'local' as const, reason: 'not_reached' as const } }),
     ok: false,
     ...(path !== undefined ? { path } : {}),
     gates: [],

package/src/cli/cloud-answer.ts

@@ -0,0 +1,40 @@
+import { cloudAnswerCommand } from '../authored-human.js';
+import { shellWord } from '../shell-word.js';
+import { answerCloudFlow, CloudAnswerError } from '../cloud-answer.js';
+import { CloudFlowError } from '../cloud-http.js';
+import { redact } from '../redact.js';
+import { safe } from './cloud-format.js';
+import type { CliIo } from '../cli.js';
+
+export async function runCloudAnswerCli(
+  args: { runId: string; answer: boolean; note?: string; source?: string; json: boolean },
+  io: CliIo,
+  signal: AbortSignal,
+): Promise<0 | 1 | 2> {
+  try {
+    const receipt = await answerCloudFlow(args.runId, args.answer, { ...args, signal });
+    if (args.json) io.stdout(JSON.stringify({ ok: true, ...receipt }));
+    else {
+      io.stdout(`ANSWERED ${receipt.resumedFrom} ${receipt.waitId} ${receipt.answer ? 'yes' : 'no'}`);
+      io.stdout(`RESUMED ${receipt.runId}${receipt.resumedByCloud ? ' (by Cloud)' : ''}`);
+    }
+    return 0;
+  } catch (error) {
+    const partial = error instanceof CloudAnswerError;
+    const cause = partial ? error.cause : error;
+    const code = partial ? 'cloud_answer_incomplete' : cause instanceof CloudFlowError ? cause.code : 'cloud_answer_failed';
+    const detail = partial && cause instanceof Error ? ` ${cause.message}` : '';
+    const message = safe(redact((error instanceof Error ? error.message : 'Cloud answer failed.') + detail, process.env));
+    const retry = partial ? cloudAnswerCommand(args.runId).replace(/yes\|no$/u, args.answer ? 'yes' : 'no')
+      + (args.source === undefined ? '' : ` --source ${shellWord(args.source)}`)
+      + (args.note === undefined ? '' : ` --note ${shellWord(args.note)}`) : undefined;
+    const next = retry === undefined ? undefined : safe(redact(retry, process.env));
+    if (args.json) io.stdout(JSON.stringify({ ok: false, code, message, runId: args.runId,
+      ...(partial ? { answerRecorded: error.answerRecorded, next } : {}) }));
+    else {
+      io.stderr(`${code}: ${message}`);
+      if (next) io.stderr(`After checking Cloud status, retry with: ${next}`);
+    }
+    return !partial && cause instanceof CloudFlowError && ['configuration', 'invalid_input', 'unsupported_source'].includes(cause.code) ? 2 : 1;
+  }
+}

package/src/cli/cloud-connect-cli.ts

@@ -3,6 +3,7 @@ import { dirname, resolve } from 'node:path';
 import { createInterface } from 'node:readline';
 import { parse as parseYaml } from 'yaml';
 import { loadAuthoredFlow } from '../authored-flow-loader.js';
+import { isAuthoredFlowPath } from '../direct-input.js';
 import { ensureIntegrationsConnected, type ConnectPrompt, type ConnectionsOutcome } from '../cloud-connect.js';
 import { CloudFlowError, cloudRequest, isCloudRecord, type CloudConnectionOptions } from '../cloud-http.js';
 import { CompileError, compileSpec, kernelToAuthoring } from '../compile.js';
@@ -35,7 +36,9 @@ export async function flowRequirementsForPath(
   const projectCli = context.projectCli ?? projectCliFor(path);
   const withCli = { ...context, ...(projectCli === undefined ? {} : { projectCli }) };
   try {
-    if (/\.flow\.ts$/iu.test(path)) {
+    // Every authored extension flows check accepts; skipping one would let a
+    // Cloud submission go out without its integration check.
+    if (isAuthoredFlowPath(path)) {
       const loaded = await loadAuthoredFlow(path);
       return flowRequirements(loaded.getDefinition(loaded.handle), withCli);
     }
@@ -77,11 +80,15 @@ export async function currentWorkspaceId(options: CloudConnectionOptions): Promi
  * contacted when the flow requires no integration, so a flow with no
  * helpers, sources or repository submits exactly as before; the derived
  * requirements still come back so a later harness refusal can name its remedy.
- * `undefined` only when the source does not load — the submission says why.
+ * `undefined` when the source does not load or is an authored extension Cloud
+ * does not submit — the submission says why.
  */
 export async function ensureFlowConnections(
   input: FlowConnectionsInput, options: CloudConnectionOptions = {},
 ): Promise<{ requirements: FlowRequirements; outcome: ConnectionsOutcome } | undefined> {
+  // Cloud submission accepts only .flow.ts among authored sources (cloud-run.ts
+  // prepareCloudSubmission); never prompt or connect for one it will refuse.
+  if (isAuthoredFlowPath(input.path) && !/\.flow\.ts$/iu.test(input.path)) return undefined;
   const requirements = await flowRequirementsForPath(input.path, input);
   if (requirements === undefined) return undefined;
   if (requirements.integrations.length === 0) return { requirements, outcome: { ready: [], connected: [] } };