@relayflows/sdk 2.0.22 → 2.0.24

package/src/authored-source-authority.ts

@@ -46,7 +46,20 @@ function installPinnedSourceLoader(sources: Map<string, string>): void {
   pinnedSourceLoaderInstalled = true;
   // Node >=22.14 supports register and stripTypeScriptTypes. A loader thread
   // receives the captured bytes, never reopening mutable authored paths.
+  // The `stripTypeScriptTypes` call below makes Node emit
+  // `ExperimentalWarning: stripTypeScriptTypes …` on the child's inherited
+  // stderr, where a bootstrap that reads the CLI's stderr takes it for the
+  // error text. It is emitted on this loader thread, so a listener on the
+  // main thread cannot intercept it, and `--disable-warning` on the child
+  // would silence every ExperimentalWarning the authored body raises too.
+  // Dropping it by its own text, on this thread only, is the narrow form:
+  // Node's own printer still handles every other warning.
   const loader = `
+    const emitWarning = process.emitWarning.bind(process);
+    process.emitWarning = (warning, ...rest) => {
+      if (rest[0] === 'ExperimentalWarning' && String(warning).startsWith('stripTypeScriptTypes')) return;
+      emitWarning(warning, ...rest);
+    };
     import {stripTypeScriptTypes} from 'node:module';
     let sources;
     export function initialize(data){sources=new Map(data);}

package/src/authored-step-index.ts

@@ -0,0 +1,157 @@
+import type { JournalClient } from './journal-client.js';
+
+/**
+ * The root run's durable index of the child runs an authored body opened.
+ *
+ * An authored flow is not one kernel run: every `f.run`, `f.agent`, `f.llm`
+ * and lowered gate is its own single-step child run with its own
+ * `<dataDir>/runs/<runId>.sqlite3`. The only thing that ties a child back to
+ * the root id a caller (or Cloud) knows is an index — and until now that index
+ * existed only in the root's SUCCESS completion output
+ * (`authored-root.ts` `driveRoot`). A failed body took
+ * `terminalizeRootFailure`, which journals `{ error }` and nothing else, so a
+ * failed run named no child at all. A failed run is exactly when its children
+ * are worth reading.
+ *
+ * The completion output could not be made to carry it either: the root is
+ * lowered as `type: 'agent'`, and the kernel nulls a failed agent's `output`
+ * (`preserve_failure_output`, relayflowd-core/src/machine.rs), preserving only
+ * a 2,000-character render in `verification.detail`. So the index is written
+ * where a failure cannot erase it — appended to a stream on the ROOT run as
+ * each child is opened, using the same `journal.streamAppend` durability the
+ * executor already relies on for predicate verdicts.
+ *
+ * Each record is bounded on its own rather than the index being truncated as
+ * one blob: a hundredth child must not push the first one out of the record.
+ */
+export const AUTHORED_STEP_STREAM = 'authored-steps';
+
+/** Versioned so a reader can tell this record from a future one. */
+const RECORD_KIND = 'relayflows.authored-step.v1';
+
+/**
+ * Per-field cap. Step ids and run ids are short by construction; the cap
+ * exists so a hostile or buggy id cannot make one record unbounded.
+ */
+const FIELD_CHARS = 256;
+
+/**
+ * `admitted` and `completed` are kept distinct on purpose. `admitted` says
+ * only "this child run exists and here is where to read it" — it never
+ * carries a `completionReason`, because manufacturing one for an attempt
+ * that has not completed would turn an unfinished child into a false fact.
+ * `completed` is written only from a terminal `step.completed` the journal
+ * actually holds.
+ */
+export interface AuthoredStepRecord {
+  readonly index: typeof RECORD_KIND;
+  readonly step: string;
+  readonly runId: string;
+  readonly state: 'admitted' | 'completed';
+  /** Present only on `completed`. */
+  readonly completionReason?: string;
+  /**
+   * The kernel step the completion came from, when it is not the authored
+   * operation's own id. A child spec has two steps once a named gate is
+   * lowered, so the terminal failure can be `<step>.verify` rather than
+   * `<step>` — saying which is the difference between an index and a guess.
+   */
+  readonly kernelStep?: string;
+}
+
+/**
+ * Append one record, or do nothing when there is no root to append to.
+ *
+ * The undefined-root case is the non-durable executor seam (`executeAuthoredFlow`
+ * called without `rootRunId`), which has no root run and therefore nothing to
+ * index. It is not a silent fallback: there is no durable place for the record
+ * to go, and the caller already knows it opted out of one.
+ *
+ * Append failures propagate (AGENTS.md rule 4). Callers on a path that is
+ * already failing must surface the persistence error ALONGSIDE the original
+ * failure rather than letting it replace it — see `alsoRecord`.
+ */
+export async function recordAuthoredChild(
+  journal: JournalClient,
+  rootRunId: string | undefined,
+  record: Omit<AuthoredStepRecord, 'index'>,
+): Promise<void> {
+  if (rootRunId === undefined) return;
+  await journal.streamAppend(rootRunId, AUTHORED_STEP_STREAM, {
+    index: RECORD_KIND,
+    step: bound(record.step),
+    runId: bound(record.runId),
+    state: record.state,
+    ...(record.completionReason === undefined ? {} : { completionReason: bound(record.completionReason) }),
+    ...(record.kernelStep === undefined || record.kernelStep === record.step
+      ? {} : { kernelStep: bound(record.kernelStep) }),
+  });
+}
+
+/**
+ * Record a child on a path that is already throwing, keeping both facts.
+ *
+ * A failed append must not be relabelled as successful collection, and it must
+ * not replace the failure the caller is about to report. It returns the note
+ * to append to that failure's message instead.
+ */
+export async function alsoRecord(
+  journal: JournalClient,
+  rootRunId: string | undefined,
+  record: Omit<AuthoredStepRecord, 'index'>,
+): Promise<string> {
+  try {
+    await recordAuthoredChild(journal, rootRunId, record);
+    return '';
+  } catch (error) {
+    return `\nCould not persist the step index: ${error instanceof Error ? error.message : String(error)}`;
+  }
+}
+
+/**
+ * Fold the root's stream back into one record per authored step.
+ *
+ * A `completed` record supersedes the `admitted` one for the same step; first
+ * admission order is preserved so the index reads in the order the body ran.
+ * Records this version does not recognise are skipped rather than trusted.
+ */
+export async function readAuthoredStepIndex(
+  journal: JournalClient,
+  rootRunId: string,
+): Promise<AuthoredStepRecord[]> {
+  const index = new Map<string, AuthoredStepRecord>();
+  let offset = 0;
+  for (;;) {
+    const page = await journal.streamRead(rootRunId, AUTHORED_STEP_STREAM, offset, 1000);
+    for (const message of page.messages) {
+      // `stream.read` returns either the envelope or the bare message,
+      // matching how the executor reads predicate verdicts.
+      const raw = (message as { message?: unknown }).message ?? message;
+      if (!isAuthoredStepRecord(raw)) continue;
+      const previous = index.get(raw.step);
+      // An `admitted` record arriving after a `completed` one (a resumed body
+      // re-admitting the same child under its stable admission key) must not
+      // un-complete it.
+      if (previous?.state === 'completed' && raw.state === 'admitted') continue;
+      index.set(raw.step, raw);
+    }
+    if (page.messages.length === 0 || page.next_offset <= offset) break;
+    offset = page.next_offset;
+  }
+  return [...index.values()];
+}
+
+function isAuthoredStepRecord(value: unknown): value is AuthoredStepRecord {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false;
+  const record = value as Partial<AuthoredStepRecord>;
+  return record.index === RECORD_KIND
+    && typeof record.step === 'string' && record.step.length > 0
+    && typeof record.runId === 'string' && record.runId.length > 0
+    && (record.state === 'admitted' || record.state === 'completed')
+    && (record.completionReason === undefined || typeof record.completionReason === 'string')
+    && (record.kernelStep === undefined || typeof record.kernelStep === 'string');
+}
+
+function bound(value: string): string {
+  return value.length <= FIELD_CHARS ? value : `${value.slice(0, FIELD_CHARS)}…`;
+}

package/src/authored-step-output.ts

@@ -3,6 +3,21 @@ 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 { 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 } from './authored-step-index.js';
+
+/**
+ * What an authored operation needs in order to leave readable evidence:
+ * the root run its child index belongs to, and the data dir whose journals
+ * a reader would open. Both optional — the non-durable executor seam has no
+ * root, and a caller that did not name a data dir still gets the `flows
+ * replay <run-id>` hint, just without the on-disk path.
+ */
+export interface AuthoredStepContext {
+  readonly rootRunId?: string;
+  readonly dataDir?: string;
+}
 
 /**
  * Shared by every `f.*` verb that lowers to one kernel step run in isolation:
@@ -18,12 +33,23 @@ import type { AuthoredFlowJournalStep } from './authored-flow-executor.js';
  * terminal state. Given that, a single read from the start of this run's
  * (small, single-step) journal is enough — no polling here, and no run
  * outcome ever needs re-checking.
+ *
+ * A non-success completion used to throw `journal step "run-1" completed with
+ * retries_exhausted` and stop there, discarding the evidence it was holding:
+ * the kernel PRESERVES a failed deterministic step's `output`
+ * (`preserve_failure_output`, relayflowd-core/src/machine.rs), so
+ * `{exit_code, stdout_tail, stderr_tail}` — the answer to "which command
+ * failed and what did it print" — was in hand and dropped. Four different
+ * causes produced that one identical line. It now reads the same extractor
+ * `f.agent`/`f.llm` already reach through `classifyOutcome`, so both step
+ * families report one grammar instead of two divergent ones.
  */
 export async function readCompletedStepOutput(
   journal: JournalClient,
   runId: string,
   stepId: string,
   journalSteps: AuthoredFlowJournalStep[],
+  context: AuthoredStepContext = {},
 ): Promise<unknown> {
   const entries = (await journal.journalRead(runId, 1)).entries;
   const completed = entries.find((entry) => isStepCompleted(entry, stepId));
@@ -34,13 +60,29 @@ export async function readCompletedStepOutput(
   const reason = completed.payload.completionReason;
   journalSteps.push(Object.freeze({ id: stepId, runId, completionReason: reason }));
   if (reason !== 'success') {
-    throw new AuthoredFlowExecutionError(
-      'step_failed',
-      `journal step "${stepId}" completed with ${reason}`,
-      reason,
-      runId,
-    );
+    let message = `journal step "${stepId}" completed with ${reason}`;
+    let details: StepFailedDetails | undefined;
+    try {
+      details = await stepFailureDetails(journal, runId);
+    } catch (error) {
+      // Inspection must not erase the already known step failure; the two
+      // failures stay separately visible, as in classifyOutcome.
+      message += ` Could not inspect the failed step: ${errorMessage(error)}`;
+    }
+    if (details !== undefined) message += renderStepEvidence(details);
+    // Appended whatever inspection found — including nothing. A failure shape
+    // this reader does not recognise must still end with somewhere to go.
+    const where = inspectionHint(runId, details?.stepId ?? stepId, context.dataDir);
+    message += renderInspection(where);
+    message += await alsoRecord(journal, context.rootRunId, {
+      step: stepId, runId, state: 'completed', completionReason: reason,
+      ...(details?.stepId === undefined ? {} : { kernelStep: details.stepId }),
+    });
+    throw new AuthoredFlowExecutionError('step_failed', message, reason, runId, { ...details, ...where });
   }
+  await recordAuthoredChild(journal, context.rootRunId, {
+    step: stepId, runId, state: 'completed', completionReason: reason,
+  });
   return completed.payload.output;
 }
 
@@ -49,15 +91,21 @@ export async function readSuccessfulOutput(
   outcome: RunOutcome,
   stepId: string,
   journalSteps: AuthoredFlowJournalStep[],
+  context: AuthoredStepContext = {},
 ): Promise<string> {
-  const output = await readCompletedStepOutput(journal, outcome.run_id, stepId, journalSteps).catch(error => {
-    if (error instanceof AuthoredFlowExecutionError
-      && (error.completionReason === 'timeout' || error.completionReason === 'lease_expired')) {
-      throw new AuthoredFlowExecutionError('lease_exceeded',
-        `f.run step "${stepId}" exceeded its command timeout.`, error.completionReason, error.runId);
-    }
-    throw error;
-  });
+  const output = await readCompletedStepOutput(journal, outcome.run_id, stepId, journalSteps, context)
+    .catch(error => {
+      if (error instanceof AuthoredFlowExecutionError
+        && (error.completionReason === 'timeout' || error.completionReason === 'lease_expired')) {
+        // A timeout is still a failed command, and the evidence extracted for
+        // it is the same evidence. Re-labelling the error must not delete it.
+        throw new AuthoredFlowExecutionError('lease_exceeded',
+          `f.run step "${stepId}" exceeded its command timeout.`
+            + ` ${error.message.slice(`${error.code}: `.length)}`,
+          error.completionReason, error.runId, error.details);
+      }
+      throw error;
+    });
   if (!isRecord(output) || typeof output['stdout_tail'] !== 'string') {
     throw protocolViolation(outcome.run_id, `step "${stepId}" has no string stdout_tail`);
   }
@@ -102,6 +150,10 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
 function protocolViolation(runId: string, detail: string): AuthoredFlowExecutionError {
   return new AuthoredFlowExecutionError(
     'journal_protocol_violation',

package/src/authored-worker-step.ts

@@ -3,15 +3,17 @@ import { parseBudget } from './budget.js';
 import type { AgentOptions, AgentResult, LlmOptions, NamedGate } from '@relayflows/surface';
 import { compileSpec, toKernelSpec } from './compile.js';
 import { checkAuthoredFlow } from './cli/check.js';
-import { classifyOutcome, type RunLifecycleOptions } from './cli/run.js';
+import { classifyOutcome, type RunLifecycleOptions, type RunReport } from './cli/run.js';
 import type { PreflightDiagnostic } from './preflight.js';
 import { AuthoredFlowExecutionError } from './authored-flow-error.js';
 import type { JournalClient } from './journal-client.js';
 import { SPEC_SCHEMA_VERSION, type FlowSpec, type PermissionsSpec, type StepSpec } from './spec.js';
-import { isSurfaceCompletionReason, readCompletedStepOutput, readSuccessfulOutput } from './authored-step-output.js';
+import { isSurfaceCompletionReason, readCompletedStepOutput, readSuccessfulOutput, type AuthoredStepContext } from './authored-step-output.js';
 import type { AuthoredFlowJournalStep } from './authored-flow-executor.js';
 import { snapshotJsonValue } from './json-value.js';
 import { authoredChildAdmissionKey } from './authored-admission.js';
+import { alsoRecord, recordAuthoredChild } from './authored-step-index.js';
+import type { StepFailedDetails } from './failure-kinds.js';
 
 const WORKSPACE_PERMISSION_ANNOTATION = /:\s*(readonly|readwrite)\s*$/i;
 
@@ -22,6 +24,10 @@ export function authoredWorkerRunner(
   localAgentStream?: string, budget?: AuthoredBudget, headerBudget?: unknown,
   rootRunId?: string,
 ) {
+  const context: AuthoredStepContext = {
+    ...(rootRunId === undefined ? {} : { rootRunId }),
+    ...(waitOptions.dataDir === undefined ? {} : { dataDir: waitOptions.dataDir }),
+  };
   async function run(step: StepSpec): Promise<unknown> {
     const id = step.id;
     const authoring: FlowSpec = { version: SPEC_SCHEMA_VERSION, name: `${definition.name}/${id}`, steps: [step], ...(headerBudget === undefined ? {} : { budget: parseBudget(headerBudget) }) };
@@ -46,6 +52,10 @@ export function authoredWorkerRunner(
     }
     const spec = toKernelSpec(resolved);
     const consume = async (outcome: import('./protocol.js').RunOutcome) => {
+    // Written BEFORE the wait, not after it. An agent runs for as long as its
+    // lease allows; if this process dies mid-step, this record is the only
+    // thing that still names the child run holding the evidence.
+    await recordAuthoredChild(journal, rootRunId, { step: id, runId: outcome.run_id, state: 'admitted' });
     // Reuse the declarative CLI's own wait/classification (cli/run.ts) rather
     // than a hand-rolled poll: `step.completed` and the run's own terminal
     // state are appended as two SEPARATE actions (kernel/relayflowd-core/src/machine.rs
@@ -69,17 +79,38 @@ export function authoredWorkerRunner(
       );
     }
     if (execution.exitCode !== 0) {
+      // `execution.report.completionReason` is the RUN's reason (normally
+      // `step_failed`), not the step's. The step's terminal facts are the
+      // ones `classifyOutcome` already extracted with `stepFailureDetails`
+      // and assigned onto this diagnostic — read them from there rather than
+      // re-walking the journal or mislabelling the run reason as a step one.
+      const diagnostic = execution.report.diagnostics.at(-1);
+      const details = stepDetails(diagnostic);
       const reason = execution.report.completionReason;
+      let message = diagnostic?.message
+        ?? `flow "${definition.name}" step "${id}" did not complete successfully `
+          + `(status: ${execution.report.status ?? 'unknown'})`;
+      // Only a reason the journal actually recorded for a step is indexed;
+      // an unfinished or unreadable child is left as `admitted`, never given
+      // a manufactured completion.
+      if (isSurfaceCompletionReason(details?.completionReason)) {
+        journalSteps.push(Object.freeze({
+          id, runId: outcome.run_id, completionReason: details.completionReason,
+        }));
+        message += await alsoRecord(journal, rootRunId, {
+          step: id, runId: outcome.run_id, state: 'completed',
+          completionReason: details.completionReason,
+          ...(details.stepId === undefined ? {} : { kernelStep: details.stepId }),
+        });
+      }
       throw new AuthoredFlowExecutionError(
-        'step_failed',
-        execution.report.diagnostics.at(-1)?.message
-          ?? `flow "${definition.name}" step "${id}" did not complete successfully `
-            + `(status: ${execution.report.status ?? 'unknown'})`,
+        'step_failed', message,
         isSurfaceCompletionReason(reason) ? reason : undefined,
         outcome.run_id,
+        details,
       );
     }
-    return readCompletedStepOutput(journal, outcome.run_id, id, journalSteps);
+    return readCompletedStepOutput(journal, outcome.run_id, id, journalSteps, context);
     };
     const admissionKey = authoredChildAdmissionKey(rootRunId, id);
     return budget === undefined
@@ -173,11 +204,19 @@ export function authoredWorkerRunner(
   };
 }
 
-/** Deterministic commands execute inline under their per-invocation lease. */
+/**
+ * Deterministic commands execute inline under their per-invocation lease.
+ *
+ * `context` carries the root run (so each child is indexed on it) and the
+ * data dir (so a failure can name the journal on disk). It is the same object
+ * the worker runner builds; a failed `f.run` and a failed `f.agent` now report
+ * through one grammar.
+ */
 export function authoredDeterministicRunner(
   name: string, journal: JournalClient, journalSteps: AuthoredFlowJournalStep[], budget: AuthoredBudget,
-  rootRunId?: string,
+  context: AuthoredStepContext = {},
 ) {
+  const rootRunId = context.rootRunId;
   return async (id: string, command: string, terminal = false, leaseMs?: number, verification?: NamedGate): Promise<string> => {
     const spec = toKernelSpec(compileSpec({
       version: SPEC_SCHEMA_VERSION,
@@ -189,11 +228,45 @@ export function authoredDeterministicRunner(
       }],
     }));
     const admissionKey = authoredChildAdmissionKey(rootRunId, id);
-    if (terminal) return readSuccessfulOutput(
-      journal, await journal.runStart(spec, undefined, admissionKey), id, journalSteps,
-    );
-    return budget.execute(
-      journal, spec, outcome => readSuccessfulOutput(journal, outcome, id, journalSteps), admissionKey,
-    );
+    const consume = async (outcome: import('./protocol.js').RunOutcome): Promise<string> => {
+      await recordAuthoredChild(journal, rootRunId, { step: id, runId: outcome.run_id, state: 'admitted' });
+      return readSuccessfulOutput(journal, outcome, id, journalSteps, context);
+    };
+    if (terminal) return consume(await journal.runStart(spec, undefined, admissionKey));
+    return budget.execute(journal, spec, consume, admissionKey);
+  };
+}
+
+/**
+ * Lift the step-shaped fields off a run diagnostic.
+ *
+ * `RunDiagnostic extends StepFailedDetails`, so `classifyOutcome`'s
+ * `Object.assign(diagnostic, details)` leaves the extraction right there. The
+ * fields are picked explicitly rather than spread, so `severity`, `kind` and
+ * `message` — which describe the RUN, not the step — cannot leak into
+ * something typed as the step's evidence.
+ */
+function stepDetails(
+  diagnostic: RunReport['diagnostics'][number] | undefined,
+): StepFailedDetails | undefined {
+  if (diagnostic === undefined) return undefined;
+  // `RunDiagnostic` is the only member of this union that extends
+  // `StepFailedDetails`; the check-report shapes carry none of these fields,
+  // so reading them as optionals yields `undefined` and contributes nothing.
+  const found = diagnostic as Partial<StepFailedDetails>;
+  const details: StepFailedDetails = {
+    ...(found.stepId === undefined ? {} : { stepId: found.stepId }),
+    ...(found.stepType === undefined ? {} : { stepType: found.stepType }),
+    ...(found.completionReason === undefined ? {} : { completionReason: found.completionReason }),
+    ...(found.attempt === undefined ? {} : { attempt: found.attempt }),
+    ...(found.maxIterations === undefined ? {} : { maxIterations: found.maxIterations }),
+    ...(found.exitCode === undefined ? {} : { exitCode: found.exitCode }),
+    ...(found.stdoutTail === undefined ? {} : { stdoutTail: found.stdoutTail }),
+    ...(found.stderrTail === undefined ? {} : { stderrTail: found.stderrTail }),
+    ...(found.detail === undefined ? {} : { detail: found.detail }),
+    ...(found.transcriptPath === undefined ? {} : { transcriptPath: found.transcriptPath }),
+    ...(found.hint === undefined ? {} : { hint: found.hint }),
+    ...(found.journalPath === undefined ? {} : { journalPath: found.journalPath }),
   };
+  return Object.keys(details).length === 0 ? undefined : details;
 }

package/src/cli/check.ts

@@ -1,3 +1,6 @@
+import { communicationInstruction } from '../communication/spec.js';
+import { checkCommunicationEnvironment } from '../communication/preflight.js';
+import { agentEnvironment, brokerEnvironment } from '../communication/environment.js';
 import { accessSync, constants, readFileSync } from 'node:fs';
 import { dirname, isAbsolute, join, parse as parsePath, resolve } from 'node:path';
 import { spawnSync } from 'node:child_process';
@@ -159,6 +162,16 @@ export function checkAuthoredFlow(authoring: FlowSpec, path: string, projectConf
           config.directory,
         )
       : undefined;
+    if (flow?.steps.some(step => step.type === 'agent' && communicationInstruction(step.instruction))) {
+      try { checkCommunicationEnvironment(flow); }
+      catch (error) {
+        result.ok = false;
+        result.diagnostics.push({ severity: 'refusal', kind: 'probe_failed',
+          message: error instanceof Error ? error.message : 'Communication environment could not be checked.' });
+      }
+      result.diagnostics.push({ severity: 'warning', kind: 'budget_unmetered',
+        message: 'Managed communication sessions do not report token or dollar usage. Budget ceilings cannot bound their spend; communication.timeoutMs bounds their duration.' });
+    }
     return {
       report: {
         ok: result.ok,
@@ -169,7 +182,7 @@ export function checkAuthoredFlow(authoring: FlowSpec, path: string, projectConf
         diagnostics: result.diagnostics,
         requirements: safeRequirements(authoring, config.cli),
       },
-      ...(flow !== undefined ? { flow } : {}),
+      ...(result.ok && flow !== undefined ? { flow } : {}),
     };
   } catch (error) {
     const failure = error instanceof CheckFailure
@@ -375,7 +388,7 @@ function findConfig(start: string): string | undefined {
 function systemProbes(flowDirectory: string, config: ProjectConfig): PreflightProbes {
   return {
     helper: helperReady,
-    cli: (cli, source, model) => probeCli(cli, source === 'project' ? config.directory : flowDirectory, model),
+    cli: (cli, source, model, execution) => probeCli(cli, source === 'project' ? config.directory : flowDirectory, model, execution),
     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
@@ -416,12 +429,22 @@ function probeCli(
   cli: string,
   directory: string,
   model?: string,
+  execution?: 'managed',
 ): CliProbeResult {
   const executable = resolveExecutable(cli, directory);
   if (executable === undefined) return { exists: false, authenticated: false };
   const kind = cliAdapterKind(executable);
+  // Relay owns interactive CLI launch/injection. Its generic PTY path is not
+  // the headless wrapper protocol; do not demand that protocol from Gemini,
+  // Cursor, OpenCode, or other interactive tools. Never invent an auth pass.
+  if (execution === 'managed' && kind === 'relayflows-wrapper-v1') {
+    return { exists: true, supported: true, authenticated: 'unverified' };
+  }
+  const environment = execution === 'managed'
+    ? { ...brokerEnvironment(process.env), ...agentEnvironment(executable) } : process.env;
+  const probe = (invocation: CliInvocation) => runProbe(executable, directory, invocation, environment);
   const identification = adapterIdentification(kind);
-  const identified = runProbe(executable, directory, identification.invocation);
+  const identified = probe(identification.invocation);
   if (
     identified.status !== 0
     || (identification.expectedStdout !== undefined
@@ -435,7 +458,7 @@ function probeCli(
     return {
       exists: true,
       supported: true,
-      authenticated: runProbe(executable, directory, auth).status === 0,
+      authenticated: probe(auth).status === 0,
       authCommand,
     };
   }
@@ -445,7 +468,7 @@ function probeCli(
   // 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 (runProbe(executable, directory, scoped).status === 0) {
+  if (probe(scoped).status === 0) {
     return {
       exists: true,
       supported: true,
@@ -455,35 +478,70 @@ function probeCli(
       modelCommand,
     };
   }
-  const authStatus = runProbe(executable, directory, auth).status;
+  const authProbe = probe(auth);
+  const authenticated = authProbe.status === 0;
   return {
     exists: true,
     supported: true,
-    authenticated: authStatus === 0,
+    authenticated,
     modelAvailable: false,
     authCommand,
     modelCommand,
+    // Only on failure: on success there is nothing to explain, and the output
+    // is the most identity-bearing thing this function touches.
+    ...(authenticated
+      ? {}
+      : {
+        authExitCode: authProbe.status,
+        authFailureDetail: redactProbeOutput(
+          `${authProbe.stderr}${authProbe.stdout}`,
+        ).trim().slice(0, 500),
+      }),
   };
 }
 
+/**
+ * Redact anything that looks like a credential or an account identifier.
+ *
+ * `auth status` output is diagnostic, but it is also the one place an account
+ * email, org id or token fragment can appear. The point of surfacing it is to
+ * say WHY a probe failed, which survives redaction; leaking an identity into a
+ * refusal message that gets pasted into issues does not.
+ */
+function redactProbeOutput(text: string): string {
+  return text
+    .replace(/[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g, '<redacted-email>')
+    .replace(/\b(sk|pk|oat|rt)[-_][A-Za-z0-9._-]{8,}/gi, '<redacted-token>')
+    .replace(/\b[A-Fa-f0-9]{32,}\b/g, '<redacted-hex>');
+}
+
 function runProbe(
   executable: string,
   directory: string,
   invocation: CliInvocation,
-): { status: number | null; stdout: string } {
-  const env = { ...process.env };
+  environment: NodeJS.ProcessEnv = process.env,
+): { status: number | null; stdout: string; stderr: string } {
+  const env = { ...environment };
   delete env[MODEL_ENV];
   if (invocation.modelEnv !== undefined) env[MODEL_ENV] = invocation.modelEnv;
   const result = spawnSync(executable, invocation.args, {
     cwd: directory,
     encoding: 'utf8',
-    stdio: ['ignore', 'pipe', 'ignore'],
+    // stderr was 'ignore'. A failing `auth status` writes its reason there, so
+    // discarding it made every authentication refusal structurally
+    // undiagnosable: the refusal could say a probe exited non-zero and never
+    // what it said. Captured, then redacted at the point of use.
+    stdio: ['ignore', 'pipe', 'pipe'],
     timeout: invocation.timeoutMs,
     env,
   });
   const failure = classifySpawnFailure(result.error, result.signal, invocation.timeoutMs);
   if (failure !== undefined) throw failure;
-  return { status: result.status, stdout: result.stdout };
+  return {
+    status: result.status,
+    stdout: result.stdout,
+    stderr: result.stderr ?? '',
+  };
 }
 
 function resolveExecutable(command: string, directory: string): string | undefined {