@relayflows/sdk 2.0.35 → 2.0.37

package/src/authored-step-output.ts

@@ -1,11 +1,13 @@
 import { COMPLETION_REASONS, RUN_COMPLETION_REASONS, FLOW_COMPLETION_REASONS, type FlowCompletionReason } from '@relayflows/surface';
 import { AuthoredFlowExecutionError } from './authored-flow-error.js';
 import type { JournalClient } from './journal-client.js';
-import type { CompletionReason as ProtocolCompletionReason, RunCompletionReason as ProtocolRunCompletionReason, RunOutcome } from './protocol.js';
+import type { CompletionReason as ProtocolCompletionReason, RunCompletionReason as ProtocolRunCompletionReason, RunOutcome, RunStatus } from './protocol.js';
 import type { AuthoredFlowJournalStep } from './authored-flow-executor.js';
 import type { StepFailedDetails } from './failure-kinds.js';
 import { inspectionHint, renderInspection, renderStepEvidence, stepFailureDetails } from './cli/step-failure.js';
 import { alsoRecord, recordAuthoredChild, type AuthoredStepEdges } from './authored-step-index.js';
+import { readChildJournal, waitForTerminalChildRun } from './authored-child-run.js';
+import { settlingCompletion } from './step-settling.js';
 
 /**
  * What an authored operation needs in order to leave readable evidence:
@@ -19,6 +21,8 @@ export interface AuthoredStepContext {
   readonly dataDir?: string;
   /** The step's label and causal predecessors, carried on every record about it. */
   readonly stepEdges?: (step: string) => AuthoredStepEdges | undefined;
+  /** Cancels the wait for an adopted child run that is not yet terminal. */
+  readonly signal?: AbortSignal;
 }
 
 /**
@@ -27,12 +31,26 @@ export interface AuthoredStepContext {
  * clean success before handing the raw `output` back for verb-specific
  * extraction (a plain string for `f.run`, an `AgentResult` for `f.agent`).
  *
- * Callers are responsible for having already waited for the run to reach a
- * terminal state — `f.run`'s caller relies on `runStart`'s own immediate
- * response (the kernel drives a deterministic step to completion inline, no
- * race); `f.agent`'s caller relies on `classifyOutcome` (cli/run.ts) having
- * already polled to one. Given that, a single read from the start of this
- * run's small journal is enough, and no polling happens here.
+ * The run must be terminal before it is judged. Usually it already is —
+ * `f.run`'s `runStart` drives a deterministic step to completion inline, and
+ * `f.agent`'s caller has polled one with `classifyOutcome` (cli/run.ts). But a
+ * child ADOPTED through its admission key on resume is returned as it stands,
+ * possibly mid-attempt or mid-backoff on the request that first started it,
+ * so unless the step has already settled as a failure, a run that neither
+ * the caller's own kernel answer (`knownStatus`) nor a journaled
+ * `run.completed` shows terminal is waited out first (`waitForTerminalChildRun`, bounded by
+ * the child's own lease and backoff). A success is never read off a child
+ * whose run is not terminal. A child that cannot settle — parked on a worker
+ * nobody attached — reports its latest attempt that ran to a failed result,
+ * or is refused.
+ *
+ * The step's verdict is its TERMINAL completion. A retried attempt journals a
+ * `step.completed` too — `disposition: retry` (crash recovery's `crashed`, a
+ * `worker_error`, a failed gate with iterations left) — and it precedes the
+ * attempt that settled the step. Taking the first `step.completed` read that
+ * retried attempt's failure as the step's, and failed a child that completed
+ * `success`. Only the last completion whose disposition is not `retry` or
+ * `park` is read, recorded and indexed.
  *
  * What is NOT delegated to the caller is the run's verdict. A child spec has
  * more than one step whenever the author declared a `.gate()`, and that gate
@@ -56,15 +74,63 @@ export async function readCompletedStepOutput(
   stepId: string,
   journalSteps: AuthoredFlowJournalStep[],
   context: AuthoredStepContext = {},
+  // `suspended` (an Event Await boundary, `RunReport.status`) is not terminal:
+  // it is judged exactly like a run still in flight.
+  knownStatus?: RunStatus | 'suspended',
 ): Promise<unknown> {
-  const entries = (await journal.journalRead(runId, 1)).entries;
-  const completed = entries.find((entry) => isStepCompleted(entry, stepId));
-  if (!isStepCompleted(completed, stepId)) {
-    throw protocolViolation(runId, `journal has no step.completed for "${stepId}"`);
+  let entries = await readChildJournal(journal, runId);
+  let completed = terminalCompletion(entries, stepId);
+  // A success is never accepted before the child RUN is terminal: a declared
+  // gate lowers to a dependent step (`lowerNamedGates`) that may not even have
+  // started when the producer's success is journaled, and the run's verdict,
+  // not the producer's, is the operation's. Only a settled FAILURE is final
+  // on its own — the step has no attempt left.
+  // `knownStatus` is the kernel's own answer the caller already holds (the
+  // `run.start` receipt, or the outcome `classifyOutcome` polled to): a
+  // terminal one is as authoritative as a journaled `run.completed`.
+  const settledFailure = completed !== undefined && completed.payload.completionReason !== 'success';
+  const terminal = knownStatus === 'completed' || knownStatus === 'failed'
+    || entries.some(entry => runCompletionReason(entry) !== undefined);
+  if (!terminal && !settledFailure) {
+    const status = await waitForTerminalChildRun(journal, runId, context.signal);
+    entries = await readChildJournal(journal, runId);
+    completed = terminalCompletion(entries, stepId);
+    if (status !== 'completed' && status !== 'failed') {
+      if (completed?.payload.completionReason === 'success') {
+        throw protocolViolation(runId,
+          `child run for step "${stepId}" is not terminal (status: ${status}); its verdict is still pending`);
+      }
+      if (completed === undefined) {
+        // Nothing will settle the step from here: the child is parked on a
+        // worker the caller did not keep attached (a helper drives exactly
+        // one attempt, and the retry dispatched after it dies with its
+        // connection). The latest attempt that ran to a result — not one the
+        // kernel recorded as dead (`completed_by: kernel`,
+        // machine/recovery.rs) — is then why the step stands where it does,
+        // and is reported as that: never as a success, never silently.
+        const attempts = entries.filter((entry): entry is StepCompletedEntry => isStepCompleted(entry, stepId));
+        const latest = attempts.filter(entry => entry.payload.completed_by !== 'kernel').at(-1) ?? attempts.at(-1);
+        if (latest === undefined || latest.payload.completionReason === 'success') {
+          throw protocolViolation(runId, `child run for step "${stepId}" is not terminal (status: ${status})`);
+        }
+        completed = latest;
+      }
+    }
+  }
+  const runReason = entries.map(runCompletionReason).find((value) => value !== undefined);
+  const edges = context.stepEdges?.(stepId);
+  if (completed === undefined) {
+    // Canceled or out of budget while the step was between attempts: the run
+    // settled with no terminal completion for the step. That is the run's
+    // failure to report, not a malformed journal.
+    if (runReason !== undefined && runReason !== 'success') {
+      throw await stepFailure(journal, runId, stepId, runReason, context, edges,
+        `journal run for step "${stepId}" completed with ${runReason}`);
+    }
+    throw protocolViolation(runId, `journal has no terminal step.completed for "${stepId}"`);
   }
 
   const reason = completed.payload.completionReason;
-  const edges = context.stepEdges?.(stepId);
   journalSteps.push(Object.freeze({ id: stepId, runId, completionReason: reason, ...edges }));
   if (reason !== 'success') {
     throw await stepFailure(journal, runId, stepId, reason, context, edges,
@@ -76,7 +142,6 @@ export async function readCompletedStepOutput(
   // verdict. Reading only the producer's entry let a failed gate resolve as
   // though the command had passed — the `|| true` invisibility this module's
   // recording policy exists to remove, reappearing one layer up.
-  const runReason = entries.map(runCompletionReason).find((value) => value !== undefined);
   if (runReason !== undefined && runReason !== 'success') {
     throw await stepFailure(journal, runId, stepId, runReason, context, edges,
       `journal run for step "${stepId}" completed with ${runReason}`);
@@ -130,7 +195,7 @@ export async function readSuccessfulOutput(
   journalSteps: AuthoredFlowJournalStep[],
   context: AuthoredStepContext = {},
 ): Promise<string> {
-  const output = await readCompletedStepOutput(journal, outcome.run_id, stepId, journalSteps, context)
+  const output = await readCompletedStepOutput(journal, outcome.run_id, stepId, journalSteps, context, outcome.status)
     .catch(relabelCommandTimeout(stepId));
   if (!isRecord(output) || typeof output['stdout_tail'] !== 'string') {
     throw protocolViolation(outcome.run_id, `step "${stepId}" has no string stdout_tail`);
@@ -166,7 +231,7 @@ export async function readRecordedOutcome(
   journalSteps: AuthoredFlowJournalStep[],
   context: AuthoredStepContext = {},
 ): Promise<RecordedRunOutcome> {
-  const envelope = await readCompletedStepOutput(journal, outcome.run_id, stepId, journalSteps, context)
+  const envelope = await readCompletedStepOutput(journal, outcome.run_id, stepId, journalSteps, context, outcome.status)
     .catch(relabelCommandTimeout(stepId));
   const exitCode = isRecord(envelope) ? envelope['exit_code'] : undefined;
   if (!isRecord(envelope) || typeof envelope['stdout_tail'] !== 'string'
@@ -204,10 +269,18 @@ interface StepCompletedEntry {
   step_id: string;
   payload: {
     completionReason: ProtocolCompletionReason;
+    disposition?: unknown;
+    completed_by?: unknown;
     output: unknown;
   };
 }
 
+/** The step's LAST settling completion, when it is well formed. */
+function terminalCompletion(entries: readonly unknown[], stepId: string): StepCompletedEntry | undefined {
+  const settling = settlingCompletion(entries, stepId);
+  return isStepCompleted(settling, stepId) ? settling : undefined;
+}
+
 function isStepCompleted(value: unknown, stepId: string): value is StepCompletedEntry {
   if (!isRecord(value) || value['entry_type'] !== 'step.completed' || value['step_id'] !== stepId) {
     return false;

package/src/authored-subscription-park.ts

@@ -0,0 +1,46 @@
+import type { AuthoredFlowSuspension } from './authored-flow-error.js';
+import type { JournalClient } from './journal-client.js';
+
+/** Recover the handoff report without starting a worker on a still-open wait. */
+export async function readSubscriptionPark(
+  journal: JournalClient, runId: string,
+): Promise<AuthoredFlowSuspension | undefined> {
+  const open = new Map<string, { subscription_id: string; phase: 'activation' | 'event_wait' }>();
+  const prepared = new Map<string, Record<string, unknown>>();
+  let from = 1;
+  for (;;) {
+    const { entries } = await journal.journalRead(runId, from, 500);
+    for (const raw of entries) {
+      const entry = raw as { seq: number; entry_type: string; step_id?: string; payload: Record<string, unknown> };
+      from = entry.seq + 1;
+      const p = entry.payload;
+      if (entry.entry_type === 'subscription.prepared') prepared.set(String(p['subscription_id']), p);
+      if (entry.entry_type === 'wait.event' && entry.step_id === 'authored-root'
+        && typeof p['event_key'] === 'string' && p['event_key'].startsWith('subscription.park:')) {
+        const park = JSON.parse(p['event_key'].slice('subscription.park:'.length)) as Record<string, unknown>;
+        if (typeof park['subscription_id'] !== 'string'
+          || (park['phase'] !== 'activation' && park['phase'] !== 'event_wait')) {
+          throw new Error('malformed durable subscription park');
+        }
+        open.set(String(p['wait_id']), { subscription_id: park['subscription_id'], phase: park['phase'] });
+      }
+      if (entry.entry_type === 'wait.completed') open.delete(String(p['wait_id']));
+    }
+    if (entries.length < 500) break;
+  }
+  const park = [...open.values()].at(-1);
+  if (park === undefined) return undefined;
+  const p = prepared.get(park.subscription_id);
+  if (p === undefined || typeof p['stream'] !== 'string' || typeof p['deadline_at_ms'] !== 'number') {
+    throw new Error('subscription park has no prepared boundary');
+  }
+  const common = { subscriptionId: park.subscription_id, stream: p['stream'], deadlineAtMs: p['deadline_at_ms'] };
+  if (park.phase === 'event_wait') return { kind: 'event_wait', ...common };
+  if (!Array.isArray(p['event_types']) || !p['event_types'].every(v => typeof v === 'string')
+    || typeof p['settle_ms'] !== 'number' || typeof p['idle_ms'] !== 'number' || typeof p['include_self'] !== 'boolean') {
+    throw new Error('subscription park has malformed prepared facts');
+  }
+  return { kind: 'activation', ...common, eventTypes: p['event_types'], settleMs: p['settle_ms'],
+    idleMs: p['idle_ms'], includeSelf: p['include_self'],
+    ...(p['pattern'] === undefined || p['pattern'] === null ? {} : { pattern: p['pattern'] as Record<string, unknown> }) };
+}

package/src/authored-verdict.ts

@@ -67,7 +67,8 @@ export function authoredVerdictOf(events: readonly JournalEvent[]): AuthoredVerd
   return Object.freeze({ reason, ...(detail === undefined ? {} : { detail }) });
 }
 
-function declaresAuthoredRoot(spawned: JournalEvent): boolean {
+/** Whether a journal's spawned spec is a real authored root, not a step merely named `authored-root`. */
+export function declaresAuthoredRoot(spawned: JournalEvent): boolean {
   const spec = record(record(spawned.payload)?.['spec']);
   const steps = spec?.['steps'];
   if (!Array.isArray(steps)) return false;

package/src/authored-worker-step.ts

@@ -27,6 +27,7 @@ export function authoredWorkerRunner(
   localAgentStream?: string, budget?: AuthoredBudget, headerBudget?: unknown,
   rootRunId?: string, workerCapacity?: number, stepEdges?: AuthoredStepContext['stepEdges'],
   sharedSlots?: AuthoredWorkerSlots,
+  agentEnvironment?: NodeJS.ProcessEnv,
 ) {
   // Sized to the attached local workers, so concurrent calls wait here for a
   // slot instead of being admitted and parked for want of a free worker.
@@ -36,11 +37,12 @@ export function authoredWorkerRunner(
     agent: slots.agent.scope(),
     llm: slots.llm.scope(),
   };
-  const check = authoredPreflight(flowPath);
+  const check = authoredPreflight(flowPath, agentEnvironment);
   const context: AuthoredStepContext = {
     ...(rootRunId === undefined ? {} : { rootRunId }),
     ...(waitOptions.dataDir === undefined ? {} : { dataDir: waitOptions.dataDir }),
     ...(stepEdges === undefined ? {} : { stepEdges }),
+    ...(waitOptions.signal === undefined ? {} : { signal: waitOptions.signal }),
   };
   async function run(step: StepSpec): Promise<unknown> {
     const id = step.id;
@@ -56,8 +58,12 @@ export function authoredWorkerRunner(
         (diagnostic): diagnostic is PreflightDiagnostic & { severity: 'refusal' } =>
           diagnostic.severity === 'refusal',
       );
+      // Environment refusals keep their own kind: folding a usage limit or an
+      // outdated CLI into `*_cli_unresolved` reported them as `invalid_spec`,
+      // telling the author to fix a flow that was never wrong.
       throw new AuthoredFlowExecutionError(
-        refusal?.kind === 'budget_syntax_invalid' ? refusal.kind
+        refusal?.kind === 'budget_syntax_invalid' || refusal?.kind === 'cli_outdated'
+          || refusal?.kind === 'provider_usage_limited' ? refusal.kind
           : step.type === 'llm' ? 'llm_cli_unresolved' : 'agent_cli_unresolved',
         refusal?.message
           ?? `flow "${definition.name}" step "${id}": no CLI could be resolved for f.${step.type} `
@@ -135,7 +141,7 @@ export function authoredWorkerRunner(
         details,
       );
     }
-    return readCompletedStepOutput(journal, outcome.run_id, id, journalSteps, context);
+    return readCompletedStepOutput(journal, outcome.run_id, id, journalSteps, context, execution.report.status);
     };
     const admissionKey = authoredChildAdmissionKey(rootRunId, id);
     const admit = async () => budget === undefined

package/src/cli/check-activities.ts

@@ -0,0 +1,144 @@
+import { readFile } from 'node:fs/promises';
+import ts from 'typescript';
+import { inputFailureReport, type CheckExecution } from './check.js';
+
+/**
+ * Fail closed on body-level `f.on` calls that visibly omit an end bound.
+ * Dynamic options cannot be proved at check time and are refused here too;
+ * runtime validation covers JS callers and values assembled at runtime.
+ */
+export async function checkAuthoredActivities(path: string): Promise<CheckExecution> {
+  try {
+    const source = await readFile(path, 'utf8');
+    const file = ts.createSourceFile(path, source, ts.ScriptTarget.Latest, true);
+    let diagnostic: string | undefined;
+    const visit = (node: ts.Node, context: ContextNames): void => {
+      if (diagnostic !== undefined) return;
+      if (ts.isCallExpression(node) && isContextOn(node.expression, context)) {
+        const options = node.arguments[1];
+        if (options === undefined || !ts.isObjectLiteralExpression(options)) {
+          diagnostic = 'body-level f.on() requires literal idle and deadline bounds (unbounded_subscription)';
+          return;
+        }
+        const keys = new Set(options.properties.flatMap((property) => {
+          if (!ts.isPropertyAssignment(property) && !ts.isShorthandPropertyAssignment(property)) return [];
+          return ts.isIdentifier(property.name) || ts.isStringLiteral(property.name) ? [property.name.text] : [];
+        }));
+        if (!keys.has('idle') || !keys.has('deadline')) {
+          diagnostic = 'body-level f.on() requires both idle and deadline bounds (unbounded_subscription)';
+          return;
+        }
+      }
+      // A nested function that rebinds a context name is not the flow context.
+      const inner = ts.isFunctionLike(node) ? shadow(context, node.parameters) : context;
+      ts.forEachChild(node, (child) => visit(child, inner));
+    };
+    for (const body of authoredBodies(file)) {
+      if (body.body !== undefined) visit(body.body, contextNames(body));
+    }
+    if (diagnostic !== undefined) {
+      return { report: inputFailureReport({ kind: 'invalid_spec', message: diagnostic }, path) };
+    }
+    return { report: { ok: true, path, gates: [], resolutions: [], diagnostics: [] } };
+  } catch (error) {
+    return { report: inputFailureReport({ kind: 'invalid_spec',
+      message: error instanceof Error ? error.message : 'Cannot inspect body-level activities' }, path) };
+  }
+}
+
+interface ContextNames {
+  /** Identifiers bound to a body's flow context, e.g. `f` or `ctx`. */
+  readonly objects: Set<string>;
+  /** Local names bound to a destructured `on`, e.g. `({ on }) => on(...)`. */
+  readonly on: Set<string>;
+}
+
+type BodyFunction = ts.ArrowFunction | ts.FunctionExpression | ts.FunctionDeclaration;
+
+/**
+ * Every authored body in this file: the last function argument of a
+ * `flow(...)` call, each trigger handler registered with `.on(trigger, body)`
+ * on a flow handle, and the default export, inline or named by an identifier
+ * declared in the same file. Only these bodies are checked.
+ */
+function authoredBodies(file: ts.SourceFile): Set<BodyFunction> {
+  const functions = new Map<string, BodyFunction>();
+  const handles = new Set<string>();
+  const isFlowHandle = (node: ts.Expression): boolean => {
+    if (ts.isIdentifier(node)) return handles.has(node.text);
+    if (!ts.isCallExpression(node)) return false;
+    if (ts.isIdentifier(node.expression)) return node.expression.text === 'flow';
+    return ts.isPropertyAccessExpression(node.expression) && node.expression.name.text === 'on'
+      && isFlowHandle(node.expression.expression);
+  };
+  const bodies = new Set<BodyFunction>();
+  const references: string[] = [];
+  const addBody = (node: ts.Node | undefined): void => {
+    if (node === undefined) return;
+    if (ts.isArrowFunction(node) || ts.isFunctionExpression(node) || ts.isFunctionDeclaration(node)) bodies.add(node);
+    else if (ts.isIdentifier(node)) references.push(node.text);
+  };
+  const visit = (node: ts.Node): void => {
+    if (ts.isFunctionDeclaration(node) && node.name !== undefined) functions.set(node.name.text, node);
+    if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.initializer !== undefined
+      && (ts.isArrowFunction(node.initializer) || ts.isFunctionExpression(node.initializer))) {
+      functions.set(node.name.text, node.initializer);
+    }
+    if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.initializer !== undefined
+      && isFlowHandle(node.initializer)) {
+      handles.add(node.name.text);
+    }
+    if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === 'flow') {
+      addBody(node.arguments[node.arguments.length - 1]);
+    }
+    if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression)
+      && node.expression.name.text === 'on' && isFlowHandle(node.expression.expression)) {
+      addBody(node.arguments[1]);
+    }
+    if (ts.isExportAssignment(node) && !node.isExportEquals) addBody(node.expression);
+    if (ts.isFunctionDeclaration(node) && node.modifiers?.some(m => m.kind === ts.SyntaxKind.DefaultKeyword)) addBody(node);
+    ts.forEachChild(node, visit);
+  };
+  visit(file);
+  for (const name of references) {
+    const body = functions.get(name);
+    if (body !== undefined) bodies.add(body);
+  }
+  return bodies;
+}
+
+function contextNames(body: BodyFunction): ContextNames {
+  const names: ContextNames = { objects: new Set(), on: new Set() };
+  const parameter = body.parameters[0]?.name;
+  if (parameter === undefined) return names;
+  if (ts.isIdentifier(parameter)) names.objects.add(parameter.text);
+  else if (ts.isObjectBindingPattern(parameter)) {
+    for (const element of parameter.elements) {
+      const key = element.propertyName ?? element.name;
+      if (ts.isIdentifier(key) && key.text === 'on' && ts.isIdentifier(element.name)) names.on.add(element.name.text);
+    }
+  }
+  return names;
+}
+
+function shadow(context: ContextNames, parameters: ts.NodeArray<ts.ParameterDeclaration>): ContextNames {
+  const bound = new Set<string>();
+  const collect = (name: ts.BindingName): void => {
+    if (ts.isIdentifier(name)) bound.add(name.text);
+    else for (const element of name.elements) if (!ts.isOmittedExpression(element)) collect(element.name);
+  };
+  for (const parameter of parameters) collect(parameter.name);
+  if (bound.size === 0) return context;
+  return {
+    objects: new Set([...context.objects].filter(name => !bound.has(name))),
+    on: new Set([...context.on].filter(name => !bound.has(name))),
+  };
+}
+
+function isContextOn(expression: ts.LeftHandSideExpression, context: ContextNames): boolean {
+  if (ts.isIdentifier(expression)) return context.on.has(expression.text);
+  return ts.isPropertyAccessExpression(expression)
+    && ts.isIdentifier(expression.expression)
+    && context.objects.has(expression.expression.text)
+    && expression.name.text === 'on';
+}

package/src/cli/check.ts

@@ -123,6 +123,8 @@ type CliProbeOutcomeMap = Map<string, CliProbeOutcome>;
  * anything that depends on how the flow is about to be invoked opts in here.
  */
 export interface CheckInvocation {
+  /** Environment used only by provider executable/auth/model probes. */
+  environment?: NodeJS.ProcessEnv;
   /**
    * Report `agent_worker_unresolved` when the spec has `agent` steps.
    *
@@ -202,7 +204,7 @@ export function checkAuthoredFlow(
       : projectConfigOrOptions as ProjectConfig | undefined;
     const effectiveProbeCache = cliProbeCache ?? options?.probeCache;
     const config = projectConfig ?? readProjectConfig(dirname(absolutePath));
-    const probes = systemProbes(dirname(absolutePath), config);
+    const probes = systemProbes(dirname(absolutePath), config, invocation.environment);
     const result = preflight(authoring, {
       ...(effectiveProbeCache === undefined ? {} : { cliProbeCache: effectiveProbeCache }),
       projectCli: config.cli,
@@ -450,10 +452,11 @@ function findConfig(start: string): string | undefined {
   }
 }
 
-function systemProbes(flowDirectory: string, config: ProjectConfig): PreflightProbes {
+function systemProbes(flowDirectory: string, config: ProjectConfig, environment?: NodeJS.ProcessEnv): PreflightProbes {
   return {
     helper: helperReady,
-    cli: (cli, source, model, execution) => probeCli(cli, source === 'project' ? config.directory : flowDirectory, model, execution),
+    cli: (cli, source, model, execution) => probeCli(cli,
+      source === 'project' ? config.directory : flowDirectory, model, execution, environment),
     executor: (trigger) => config.executors.includes(trigger.executor),
     // A deterministic step runs in the daemon's working directory — the
     // directory `flows run` was invoked from, or Cloud's code mount — not in

package/src/cli/cli-probe.ts

@@ -2,8 +2,8 @@ import { accessSync, constants } from 'node:fs';
 import { isAbsolute, resolve } from 'node:path';
 import { execFile, spawnSync } from 'node:child_process';
 import { agentEnvironment, brokerEnvironment } from '../communication/environment.js';
-import { adapterIdentification, authenticationProbe, cliAdapterKind, displayInvocation,
-  modelReadinessProbe, type CliInvocation } from '../cli-adapter.js';
+import { adapterIdentification, authenticationProbe, classifyModelProbeFailure, cliAdapterKind,
+  displayInvocation, modelReadinessProbe, type CliInvocation } from '../cli-adapter.js';
 import { MODEL_ENV } from '../worker-cli.js';
 import { CliProbeError, type CliProbeResult } from '../preflight.js';
 
@@ -27,8 +27,8 @@ export async function probeCliAsync(...args: Parameters<typeof probeSequence>):
   return next.value;
 }
 
-export function resolveExecutable(command: string, directory: string): string | undefined {
-  return driveSync(executableSequence(command, directory));
+export function resolveExecutable(command: string, directory: string, environment: NodeJS.ProcessEnv = process.env): string | undefined {
+  return driveSync(executableSequence(command, directory, environment));
 }
 
 function driveSync<T>(sequence: Generator<ProbeRequest, T, ProbeOutput>): T {
@@ -79,8 +79,9 @@ function* probeSequence(
   directory: string,
   model?: string,
   execution?: 'managed',
+  sourceEnvironment: NodeJS.ProcessEnv = process.env,
 ): Generator<ProbeRequest, CliProbeResult, ProbeOutput> {
-  const executable = yield* executableSequence(cli, directory);
+  const executable = yield* executableSequence(cli, directory, sourceEnvironment);
   if (executable === undefined) return { exists: false, authenticated: false };
   const kind = cliAdapterKind(executable);
   // Relay owns interactive CLI launch/injection. Its generic PTY path is not
@@ -90,7 +91,8 @@ function* probeSequence(
     return { exists: true, supported: true, authenticated: 'unverified' };
   }
   const environment = execution === 'managed'
-    ? { ...brokerEnvironment(process.env), ...agentEnvironment(executable) } : process.env;
+    ? { ...brokerEnvironment(sourceEnvironment), ...agentEnvironment(executable, sourceEnvironment) }
+    : sourceEnvironment;
   const probe = (invocation: CliInvocation): ProbeRequest => ({ executable, directory, invocation, environment });
   const identification = adapterIdentification(kind);
   const identified = yield probe(identification.invocation);
@@ -117,7 +119,8 @@ function* probeSequence(
   // A successful real provider round trip (or identified wrapper probe)
   // proves both auth and exact-model access. On failure, run the adapter's
   // actual auth command solely to classify auth vs model access truthfully.
-  if ((yield probe(scoped)).status === 0) {
+  const scopedProbe = yield probe(scoped);
+  if (scopedProbe.status === 0) {
     return {
       exists: true,
       supported: true,
@@ -129,6 +132,14 @@ function* probeSequence(
   }
   const authProbe = yield probe(auth);
   const authenticated = authProbe.status === 0;
+  // The scoped probe's own output is the only evidence of WHY it failed. A
+  // usage-limited credential or an outdated CLI exits non-zero exactly like an
+  // unknown model; discarding the output made all three "verify the model
+  // name". Classified on the raw text, surfaced redacted — stdout first,
+  // because Claude Code prints the provider's API error there and its own
+  // catalog warnings on stderr.
+  const failure = classifyModelProbeFailure(kind, `${scopedProbe.stdout}\n${scopedProbe.stderr}`);
+  const modelDetail = redactProbeOutput(scopedProbe.stdout.trim() || scopedProbe.stderr.trim()).slice(0, 500);
   return {
     exists: true,
     supported: true,
@@ -136,6 +147,9 @@ function* probeSequence(
     modelAvailable: false,
     authCommand,
     modelCommand,
+    modelExitCode: scopedProbe.status,
+    ...(failure === undefined ? {} : { modelFailure: failure }),
+    ...(modelDetail.length > 0 ? { modelFailureDetail: modelDetail } : {}),
     // Only on failure: on success there is nothing to explain, and the output
     // is the most identity-bearing thing this function touches.
     ...(authenticated
@@ -164,7 +178,7 @@ function redactProbeOutput(text: string): string {
     .replace(/\b[A-Fa-f0-9]{32,}\b/g, '<redacted-hex>');
 }
 
-function* executableSequence(command: string, directory: string): Generator<ProbeRequest, string | undefined, ProbeOutput> {
+function* executableSequence(command: string, directory: string, environment: NodeJS.ProcessEnv): Generator<ProbeRequest, string | undefined, ProbeOutput> {
   if (command.includes('/') || isAbsolute(command)) {
     const path = isAbsolute(command) ? command : resolve(directory, command);
     try {
@@ -175,7 +189,7 @@ function* executableSequence(command: string, directory: string): Generator<Prob
     }
   }
   const result = yield { executable: 'which', directory: process.cwd(),
-    invocation: { args: [command], timeoutMs: 5_000 }, environment: process.env };
+    invocation: { args: [command], timeoutMs: 5_000 }, environment };
   return result.status === 0 ? result.stdout.trim() : undefined;
 }
 

package/src/cli/direct-run.ts

@@ -6,6 +6,7 @@ import { McpPreflightError } from './check-typescript.js';
 import { attachLocalAgent } from '../local-agent.js';
 import { LlmWorker } from '../llm-worker.js';
 import { DEFAULT_LOCAL_AGENT_CAPACITY } from '../worker-slots.js';
+import { localAgentEnvironment } from '../local-agent-environment.js';
 import {
   AuthoredFlowExecutionError,
 } from '../authored-flow-executor.js';
@@ -25,6 +26,7 @@ import {
   emptyReport,
   fromCheckReport,
   protocolFailure,
+  suspendedExecution,
   socketFor,
   type RunExecution,
   type RunLifecycleOptions,
@@ -37,6 +39,9 @@ export async function runDirectFlow(
   dataDir: string,
   options: RunLifecycleOptions = {},
 ): Promise<RunExecution> {
+  // Consume and close the agent-only descriptor before authored source is
+  // imported by trigger preflight. Authored code never receives this object.
+  const agentEnvironment = localAgentEnvironment();
   let input: unknown;
   try {
     input = parseDirectInput(inputArgument);
@@ -77,13 +82,14 @@ export async function runDirectFlow(
     if (options.localAgent) {
       localAgent = await attachLocalAgent(
         client, dataDir, options.onPtyReady, authoredLocalAgentStream(admissionIdentity), workerCapacity,
+        undefined, [], agentEnvironment,
       );
       // A session owns one worker registration. Keep the workspace-free LLM
       // worker on its own connection so it cannot replace the agent worker.
       llmClient = new JournalClient(socketPath);
       await llmClient.connect();
       await llmClient.hello('flows-local-llm');
-      localLlm = new LlmWorker(llmClient, `${localAgent.stream}-llm`, workerCapacity);
+      localLlm = new LlmWorker(llmClient, `${localAgent.stream}-llm`, workerCapacity, agentEnvironment);
       localLlm.on('error', onWorkerFailure('local-llm', error => { llmFailure = error; client.close(); }));
       await localLlm.attach();
     }
@@ -92,8 +98,10 @@ export async function runDirectFlow(
       {
         dataDir,
         admissionKey: admissionIdentity,
+        onAdmitted: runId => { base.rootRunId = runId; },
         localAgentStream: localAgent?.stream,
         ...(localAgent === undefined ? {} : { workerCapacity }),
+        ...(agentEnvironment === undefined ? {} : { agentEnvironment }),
         lifecycle: {
           onProgress: options.onProgress,
           ...(options.onRunStarted !== undefined ? { onRunStarted: options.onRunStarted } : {}),
@@ -102,6 +110,9 @@ export async function runDirectFlow(
         },
       },
     );
+    if (result.state === 'suspended') {
+      return suspendedExecution('run', base, socketPath, result.rootRunId, result);
+    }
     const terminal = result.journalSteps.at(-1);
     if (terminal === undefined) {
       return protocolFailure('run', base, socketPath, new Error(
@@ -139,6 +150,8 @@ export async function runDirectFlow(
         && (error.code === 'helper_slack.credential_missing'
           || error.code === 'helper_slack.mount_required'
           || error.code === 'budget_syntax_invalid'
+          || error.code === 'cli_outdated'
+          || error.code === 'provider_usage_limited'
           || error.code === 'unsupported_promise_lifecycle'
           || error.code === 'unsupported_header'
           || error.code === 'agent_cli_unresolved'
@@ -152,6 +165,8 @@ export async function runDirectFlow(
               error.code === 'helper_slack.credential_missing'
               || error.code === 'helper_slack.mount_required'
               || error.code === 'budget_syntax_invalid'
+              || error.code === 'cli_outdated'
+              || error.code === 'provider_usage_limited'
             ) ? error.code : 'invalid_spec',
             message: error.message,
           }, path)),