@relayflows/sdk 2.0.35 → 2.0.36

package/src/cli/direct-run.ts

@@ -25,6 +25,7 @@ import {
   emptyReport,
   fromCheckReport,
   protocolFailure,
+  suspendedExecution,
   socketFor,
   type RunExecution,
   type RunLifecycleOptions,
@@ -92,6 +93,7 @@ export async function runDirectFlow(
       {
         dataDir,
         admissionKey: admissionIdentity,
+        onAdmitted: runId => { base.rootRunId = runId; },
         localAgentStream: localAgent?.stream,
         ...(localAgent === undefined ? {} : { workerCapacity }),
         lifecycle: {
@@ -102,6 +104,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 +144,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 +159,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)),

package/src/cli/run.ts

@@ -23,13 +23,15 @@ import {
 import type { ParkCause, RunFailureKind, RunWarningKind, StepFailedDetails } from '../failure-kinds.js';
 import { inspectionHint, renderInspection, renderStepEvidence, stepFailureDetails } from './step-failure.js';
 import { JournalClient, JournalProtocolError } from '../journal-client.js';
-import { attachLocalAgent } from '../local-agent.js';
+import { attachLocalAgent, declaredLocalAgentStreams } from '../local-agent.js';
 import { LlmWorker } from '../llm-worker.js';
 import { readAuthoredRootMetadata, resumeDurableAuthoredFlow, type AuthoredRootMetadata } from '../authored-root.js';
+import type { AuthoredFlowSuspendedResult } from '../authored-flow-executor.js';
 import type {
   RunCompletionReason,
   RunOutcome,
   RunStatus,
+  SubscriptionSnapshot,
 } from '../protocol.js';
 import type { StepType } from '../spec.js';
 import {
@@ -42,7 +44,7 @@ import {
   type CheckReport,
 } from './check.js';
 
-export type RunExitCode = 0 | 1 | 2 | 3;
+export type RunExitCode = 0 | 1 | 2 | 3 | 4;
 export type RunCommand = 'run' | 'resume' | 'answer';
 
 export interface ParkedStep {
@@ -52,7 +54,7 @@ export interface ParkedStep {
 
 export interface RunDiagnostic extends StepFailedDetails {
   severity: 'refusal' | 'failure' | 'parked' | 'warning' | 'declined';
-  kind: RunFailureKind | RunWarningKind | RunCompletionReason;
+  kind: RunFailureKind | RunWarningKind | RunCompletionReason | 'subscription_suspended';
   message: string;
 }
 
@@ -61,10 +63,14 @@ export interface RunReport {
   command: RunCommand;
   path?: string;
   runId?: string;
-  /** Authored root to resume/collect when runId identifies a failed child. */
+  /** Authored root owning subscriptions when runId names a failed child. */
   rootRunId?: string;
   socketPath?: string;
-  status?: RunStatus;
+  status?: RunStatus | 'suspended';
+  /** Cloud consumes this exact durable boundary before launching a resume. */
+  suspension?: AuthoredFlowSuspendedResult['suspension'] & { settleMs?: number; idleAtMs?: number };
+  /** Durable subscription projection for Cloud routing and cleanup. */
+  subscriptions?: SubscriptionSnapshot[];
   completionReason?: RunCompletionReason;
   /**
    * What the body passed to `done(reason, { detail })`, normalized: redacted,
@@ -103,6 +109,26 @@ export interface RunExecution {
   report: RunReport;
 }
 
+export function suspendedExecution(
+  command: RunCommand,
+  base: CheckReport | RunReport,
+  socketPath: string,
+  runId: string,
+  result: AuthoredFlowSuspendedResult & { readonly rootRunId: string },
+): RunExecution {
+  return {
+    exitCode: 4,
+    report: {
+      ...fromBase(command, base), ok: false, runId, socketPath, status: 'suspended',
+      suspension: result.suspension, completedSteps: result.journalSteps.length,
+      diagnostics: [...base.diagnostics, {
+        severity: 'warning', kind: 'subscription_suspended',
+        message: `Flow "${result.name}" suspended for ${result.suspension.kind}.`,
+      }],
+    },
+  };
+}
+
 export interface RunProgress {
   runId: string;
   stepId: string;
@@ -185,7 +211,10 @@ async function executeCheckedFlow(
     // Use the checked CLI/model and declared surfaces unchanged. The worker
     // advertises its existing pins; the daemon still owns surface matching.
     if (options.localAgent) {
-      localAgent = await attachLocalAgent(client, dataDir, options.onPtyReady, undefined, options.agentCapacity);
+      localAgent = await attachLocalAgent(
+        client, dataDir, options.onPtyReady, undefined, options.agentCapacity,
+        undefined, declaredLocalAgentStreams(spec),
+      );
     }
     if (options.localAgent && spec.steps.some(step => step.type === 'agent' && communicationInstruction(step.instruction))) {
       const { attachCommunicationWorkers } = await import('../communication/local.js');
@@ -271,6 +300,7 @@ export async function resumeFlow(
   try {
     authoredRoot = await readAuthoredRootMetadata(client, runId);
     if (authoredRoot !== undefined) {
+      base.rootRunId = runId;
       // Both worker-surface mismatches are refusals, not protocol failures.
       // They used to throw bare `Error`s, which landed on `protocol_error`
       // ("RUN <id> unknown") and told nobody what to do instead; and the
@@ -311,6 +341,9 @@ export async function resumeFlow(
         lifecycle: options,
       });
       if (result === undefined) throw new Error('authored root disappeared during resume');
+      if (result.state === 'suspended') {
+        return suspendedExecution('resume', base, socketPath, runId, result);
+      }
       return authoredCompletion('resume', base, socketPath, result, runId);
     }
     // resumeHelperEffect subsumes the old resumeSlackEffect: it handles the
@@ -318,9 +351,13 @@ export async function resumeFlow(
     // second call the earlier rebase left is a stale reference from before
     // the helper fanout renamed the API.
     if (options.localAgent) {
-      authoredAgent = await attachLocalAgent(client, dataDir, options.onPtyReady, undefined, options.agentCapacity);
       const entries = (await client.journalRead(runId, 1)).entries as Array<{ entry_type: string; payload?: { spec?: import('../spec.js').KernelRunSpec } }>;
       const spec = entries.find(entry => entry.entry_type === 'run.spawned')?.payload?.spec;
+      if (!spec) throw new Error('Cannot attach a local worker: the journaled run spec is missing');
+      authoredAgent = await attachLocalAgent(
+        client, dataDir, options.onPtyReady, undefined, options.agentCapacity,
+        undefined, declaredLocalAgentStreams(spec),
+      );
       if (spec?.steps.some(step => step.type === 'agent' && communicationInstruction(step.instruction))) {
         const { attachCommunicationWorkers } = await import('../communication/local.js');
         communicationWorkers = await attachCommunicationWorkers(spec, socketPath, dataDir);
@@ -955,7 +992,7 @@ async function inspectOutOfBandStep(
 }
 
 // Match kernel/relayflowd/src/server/client.rs: allow the lease sweep to dispatch a retry.
-const LEASE_SWEEP_GRACE_MS = 5_000;
+export const LEASE_SWEEP_GRACE_MS = 5_000;
 
 async function waitForRunningStep(
   client: JournalClient,
@@ -1056,7 +1093,7 @@ function throwIfCanceled(signal: AbortSignal | undefined, stepId: string): void
   if (signal?.aborted === true) throw new Error(`waiting for running step "${stepId}" was canceled`);
 }
 
-function delay(ms: number, signal?: AbortSignal): Promise<void> {
+export function delay(ms: number, signal?: AbortSignal): Promise<void> {
   return new Promise((resolveDelay, rejectDelay) => {
     const finish = (): void => {
       signal?.removeEventListener('abort', cancel);

package/src/cli/subscription-report.ts

@@ -0,0 +1,51 @@
+import { JournalClient } from '../journal-client.js';
+import type { SubscriptionInspectResult } from '../protocol.js';
+import type { RunExecution } from './run.js';
+
+/** One JSON emission boundary covers authored/declarative run and resume outcomes. */
+export async function withSubscriptionMetadata(
+  execution: RunExecution,
+  inspect: (socket: string, runId: string) => Promise<SubscriptionInspectResult> = inspectSubscriptions,
+): Promise<RunExecution> {
+  const { report } = execution;
+  const rootRunId = report.rootRunId ?? report.runId;
+  if (rootRunId === undefined || execution.exitCode === 2) {
+    return { ...execution, report: { ...report, subscriptions: [] } };
+  }
+  try {
+    if (report.socketPath === undefined) throw new Error('run report has no daemon socket');
+    const { subscriptions } = await inspect(report.socketPath, rootRunId);
+    let suspension = report.suspension;
+    if (suspension?.kind === 'event_wait') {
+      const state = subscriptions.find(item => item.subscriptionId === suspension!.subscriptionId);
+      if (state?.state !== 'active' || !Number.isSafeInteger(state.idleAtMs)
+        || !Number.isSafeInteger(state.settleMs) || !Number.isSafeInteger(state.deadlineAtMs)) {
+        throw new Error('event wait has no active durable timing snapshot');
+      }
+      suspension = { ...suspension, settleMs: state.settleMs,
+        idleAtMs: state.idleAtMs, deadlineAtMs: state.deadlineAtMs };
+    }
+    return { ...execution, report: { ...report, subscriptions,
+      ...(suspension === undefined ? {} : { suspension }) } };
+  } catch (error) {
+    // Missing authority is not an empty snapshot: Cloud must not close bindings
+    // or schedule timers from invented state. Preserve the run's diagnostic,
+    // but fail this report instead of presenting a usable suspension/success.
+    const { suspension: _suspension, subscriptions: _subscriptions, ...failed } = report;
+    return { exitCode: 1, report: { ...failed, ok: false, diagnostics: [
+      ...report.diagnostics, { severity: 'failure', kind: 'protocol_error',
+        message: `Cannot inspect durable subscriptions: ${error instanceof Error ? error.message : 'unknown error'}` },
+    ] } };
+  }
+}
+
+async function inspectSubscriptions(socket: string, runId: string): Promise<SubscriptionInspectResult> {
+  const client = new JournalClient(socket);
+  try {
+    await client.connect();
+    await client.hello('flows-subscription-report');
+    return await client.subscriptionInspect({ run_id: runId });
+  } finally {
+    client.close();
+  }
+}

package/src/cli-adapter.ts

@@ -10,10 +10,11 @@ import {
   registeredAdapters,
 } from './adapters/index.js';
 import type { CliAdapterKind } from './adapters/index.js';
-import type { CliInvocation, CliAdapterIdentification } from './adapters/base.js';
+import type { CliInvocation, CliAdapterIdentification, ModelProbeFailure } from './adapters/base.js';
 
 export type { CliAdapterKind } from './adapters/index.js';
-export type { CliInvocation, CliAdapterIdentification, HeadlessAdapter } from './adapters/base.js';
+export type { CliInvocation, CliAdapterIdentification, HeadlessAdapter, ModelProbeFailure,
+  ModelProbeFailureCause } from './adapters/base.js';
 
 export {
   WRAPPER_IDENTIFY_ARG,
@@ -73,6 +74,11 @@ export function modelReadinessProbe(kind: CliAdapterKind, model: string): CliInv
   return registeredAdapters()[kind].buildModelReadinessProbe(model);
 }
 
+/** Why a failed readiness probe failed, when the adapter recognises its output. */
+export function classifyModelProbeFailure(kind: CliAdapterKind, output: string): ModelProbeFailure | undefined {
+  return registeredAdapters()[kind].classifyModelProbeFailure?.(output);
+}
+
 /** Build the actual worker argv; this is shared contract, not probe-only lore. */
 export function agentExecution(
   kind: CliAdapterKind,

package/src/cli.ts

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { withSubscriptionMetadata } from './cli/subscription-report.js';
 import { addPlugin } from './cli/add.js';
 import { parsePluginArgs, runPluginCommand, type PluginArgs } from './cli/plugin.js';
 import { watchCheck } from './cli-watch.js';
@@ -77,7 +78,7 @@ export interface CliIo {
   tty?: boolean;
 }
 
-type CliExitCode = 0 | 1 | 2 | 3;
+type CliExitCode = 0 | 1 | 2 | 3 | 4;
 
 /**
  * Every shape `parseArgs` can produce. Exported for `cli-commands.ts`, whose
@@ -413,13 +414,14 @@ export async function runCli(
   // preflight) is worse than printing `Observer:` on a later line, so we
   // emit the run report immediately and finalize the observer link after.
   if (parsed.json) {
+    const reported = await withSubscriptionMetadata(execution);
     const observerUrl = await observerUrlFrom(observerMint, logged);
-    emitRunReport(execution, parsed.json, logged, observerUrl, await mirror?.receipt());
+    emitRunReport(reported, parsed.json, logged, observerUrl, await mirror?.receipt());
     // Last, and after the report: the run's own output is what the mirror
     // uploads, and a run's exit code has never waited on Cloud. The mirror
     // bounds itself and never rejects.
-    await mirror?.finish(execution.report);
-    return execution.exitCode;
+    await mirror?.finish(reported.report);
+    return reported.exitCode;
   }
   emitRunReport(execution, parsed.json, logged);
   await finalizeObserverLine(observerMint, logged);
@@ -437,6 +439,11 @@ export async function runCli(
 async function checkAuthoredFlowComposed(path: string): Promise<{ report: CheckReport }> {
   const helper = await checkHelperBody(path);
   if (!helper.report.ok) return helper;
+  // The activity checker loads the TypeScript compiler. YAML checks and
+  // unrelated CLI commands should not pay that startup cost on every run.
+  const { checkAuthoredActivities } = await import('./cli/check-activities.js');
+  const activities = await checkAuthoredActivities(path);
+  if (!activities.report.ok) return activities;
   const mcp = await checkTypeScriptFlow(path);
   const triggers = isAuthoredFlowPath(path)
     ? await checkAuthoredTriggers(path)
@@ -452,8 +459,8 @@ async function checkAuthoredFlowComposed(path: string): Promise<{ report: CheckR
       // The authored definition sees helper flags, body use and `cli:`
       // declarations; the compiled view underneath knows only its steps.
       ...(triggers?.report.requirements === undefined ? {} : { requirements: triggers.report.requirements }),
-      diagnostics: [...helper.report.diagnostics, ...mcp.report.diagnostics, ...triggerDiagnostics],
-      ok: helper.report.ok && mcp.report.ok && triggerOk,
+      diagnostics: [...helper.report.diagnostics, ...activities.report.diagnostics, ...mcp.report.diagnostics, ...triggerDiagnostics],
+      ok: helper.report.ok && activities.report.ok && mcp.report.ok && triggerOk,
     },
   };
 }

package/src/failure-kinds.ts

@@ -15,6 +15,7 @@ const PREFLIGHT_ENVIRONMENT_FAILURE_KINDS = [
   'mcp_unreachable',
   'budget_syntax_invalid',
   'cli_missing',
+  'cli_outdated',
   'cli_unauthenticated',
   'cli_unresolved',
   'cli_unsupported',
@@ -24,6 +25,7 @@ const PREFLIGHT_ENVIRONMENT_FAILURE_KINDS = [
   'memory_unreachable',
   'no_executor',
   'probe_failed',
+  'provider_usage_limited',
   'scope_syntax_invalid',
   'mount_unknown',
   'scope_ungrantable',

package/src/index.ts

@@ -173,6 +173,12 @@ export type {
   EffectRef,
   EventEmitParams,
   EventEmitResult,
+  SubscriptionCloseParams,
+  SubscriptionCloseResult,
+  SubscriptionNextParams,
+  SubscriptionNextResult,
+  SubscriptionOpenParams,
+  SubscriptionOpenResult,
   HelloParams,
   HelloResult,
   JournalReadParams,

package/src/journal-client.ts

@@ -13,7 +13,7 @@ import { EventEmitter } from 'node:events';
 export { walkJournal, JournalReadError, type JournalEvent, type JournalReadFailure } from './journal-reader.js';
 import { randomUUID } from 'node:crypto';
 import { createConnection, type Socket } from 'node:net';
-import type { VerbContract, EventSubmitParams } from './protocol.js';
+import type { VerbContract, EventEmitParams, EventSubmitParams } from './protocol.js';
 import {
   PROTOCOL_VERSION,
   type CompletionReason,
@@ -442,8 +442,17 @@ export class JournalClient extends EventEmitter {
     });
   }
 
-  eventEmit(runId: string, eventKey: string, payload: unknown): Promise<VerbContract['event.emit']['result']> {
-    return this.request('event.emit', { run_id: runId, event_key: eventKey, payload });
+  eventEmit(
+    runId: string,
+    eventKey: string,
+    payload: unknown,
+    options: Pick<EventEmitParams, 'delivery_id' | 'actor'> = {},
+  ): Promise<VerbContract['event.emit']['result']> {
+    return this.request('event.emit', { run_id: runId, event_key: eventKey, payload, ...options });
+  }
+
+  subscriptionPark(params: VerbContract['subscription.park']['params']): Promise<VerbContract['subscription.park']['result']> {
+    return this.request('subscription.park', params);
   }
 
   /**
@@ -457,6 +466,41 @@ export class JournalClient extends EventEmitter {
     return this.request('event.submit', { spec, event });
   }
 
+  /** Prepare a body subscription. Cloud must activate the returned request before a body can observe it. */
+  subscriptionOpen(params: VerbContract['subscription.open']['params']): Promise<VerbContract['subscription.open']['result']> {
+    return this.request('subscription.open', params, null);
+  }
+
+  /** Commit Cloud's durable binding receipt and ingress fence. */
+  subscriptionActivate(params: VerbContract['subscription.activate']['params']): Promise<VerbContract['subscription.activate']['result']> {
+    return this.request('subscription.activate', params, null);
+  }
+
+  /** Append to one activated subscription under its immutable router receipt. */
+  subscriptionDeliver(params: VerbContract['subscription.deliver']['params']): Promise<VerbContract['subscription.deliver']['result']> {
+    return this.request('subscription.deliver', params, null);
+  }
+
+  /** Read durable subscription state without changing timers or ingress. */
+  subscriptionInspect(params: VerbContract['subscription.inspect']['params']): Promise<VerbContract['subscription.inspect']['result']> {
+    return this.request('subscription.inspect', params);
+  }
+
+  /** Fence the exact activated receipt after router-side overflow. */
+  subscriptionFenceOverflow(params: VerbContract['subscription.fence_overflow']['params']): Promise<VerbContract['subscription.fence_overflow']['result']> {
+    return this.request('subscription.fence_overflow', params, null);
+  }
+
+  /** Return a durable wake, or an explicit suspension with no daemon-side sleep. */
+  subscriptionNext(params: VerbContract['subscription.next']['params']): Promise<VerbContract['subscription.next']['result']> {
+    return this.request('subscription.next', params, null);
+  }
+
+  /** Close a body subscription; the server refuses later external appends. */
+  subscriptionClose(params: VerbContract['subscription.close']['params']): Promise<VerbContract['subscription.close']['result']> {
+    return this.request('subscription.close', params, null);
+  }
+
   channelAppend(params: VerbContract['channel.append']['params']): Promise<VerbContract['channel.append']['result']> {
     return this.request('channel.append', params);
   }

package/src/journal-reader.ts

@@ -8,6 +8,8 @@ import { journalRecordOffset } from './journal-offset.js';
 // Journal version 1's closed vocabulary (relayflowd-core/src/entry.rs).
 const ENTRY_TYPES = new Set([
   'run.spawned', 'run.cancel.requested', 'event.received', 'subscription.registered',
+  'subscription.prepared', 'subscription.opened', 'subscription.closed',
+  'subscription.overflow.fenced', 'subscription.acknowledged',
   'subscription.matched', 'subscription.stale', 'step.routed', 'step.attempt.started',
   'step.completed', 'wait.event', 'wait.human', 'sleep.until', 'wait.completed',
   'stream.appended', 'memory.injected', 'channel.appended', 'channel.delivered',

package/src/local-agent.ts

@@ -2,6 +2,8 @@ import { onWorkerFailure } from './worker-lease.js';
 import { randomUUID } from 'node:crypto';
 import type { JournalClient } from './journal-client.js';
 import { AgentWorker } from './worker.js';
+import type { KernelRunSpec } from './spec.js';
+import { communicationInstruction } from './communication/spec.js';
 import { DEFAULT_LOCAL_AGENT_CAPACITY } from './worker-slots.js';
 
 /** A local worker for stream-only steps; no workspace recovery is claimed. */
@@ -12,13 +14,16 @@ export async function attachLocalAgent(
   requestedStream?: string,
   capacity: number = DEFAULT_LOCAL_AGENT_CAPACITY,
   runRoot?: string,
+  declaredStreams: readonly string[] = [],
 ): Promise<{
   stream: string;
   readonly failure: unknown;
   close(): Promise<void>;
 }> {
-  // A fresh, unconsumed stream has offset zero. The executor declares exactly
-  // this stream on its agent steps. No worktree revision is invented.
+  // This worker has consumed no messages: its read offsets are zero, including
+  // named declarative streams. The kernel retains ownership of dispatch pins
+  // and rejects a resume whose required offsets this worker does not hold.
+  // No worktree revision is invented.
   const stream = requestedStream ?? `local-agent-${randomUUID()}`;
   const worker = new AgentWorker(client, {
     workerId: stream,
@@ -27,7 +32,8 @@ export async function attachLocalAgent(
     // this same number (worker-slots.ts), so they never ask for more.
     capacity,
     dataDir, onPtyReady, runRoot,
-    pins: { workspace: [], streams: [{ stream, read_offset: 0 }] },
+    pins: { workspace: [], streams: [...new Set([stream, ...declaredStreams])]
+      .map(stream => ({ stream, read_offset: 0 })) },
   });
   let failure: unknown;
   // The cause travels with the close, so the flow's next request names it.
@@ -41,3 +47,11 @@ export async function attachLocalAgent(
     },
   };
 }
+
+/** Conversation workers own their streams and registration; do not steal their dispatches. */
+export function declaredLocalAgentStreams(spec: KernelRunSpec): string[] {
+  return [...new Set(spec.steps.flatMap(step =>
+    step.type === 'agent' && !communicationInstruction(step.instruction)
+      ? step.surfaces?.streams?.map(({ stream }) => stream) ?? []
+      : []))];
+}

package/src/preflight.ts

@@ -52,6 +52,12 @@ export interface CliProbeResult {
    * unauthenticated CLI.
    */
   authFailureDetail?: string;
+  /** Exit code of a FAILED model-scoped readiness probe. */
+  modelExitCode?: number | null;
+  /** Cause the adapter read from a failed readiness probe's output, if any. */
+  modelFailure?: import('./adapters/base.js').ModelProbeFailure;
+  /** Redacted output of a FAILED model-scoped readiness probe. */
+  modelFailureDetail?: string;
 }
 
 export type CliProbeFailureDetail =
@@ -603,17 +609,47 @@ function probeResolvedCli(
       message: `Step "${resolution.stepId}" declares CLI "${resolution.cli}", but "${command}" exited non-zero${exitCode}; authenticate it or repair that adapter's authentication probe.${detail}`,
     });
   } else if (resolution.model !== undefined && result.modelAvailable !== true) {
-    diagnostics.push({
-      severity: 'refusal',
-      kind: 'model_unavailable',
-      stepId: resolution.stepId,
-      cli: resolution.cli,
-      model: resolution.model,
-      message: describeEffectiveModel(resolution.stepId, resolution.model, resolution.cli, resolution.modelSource)
-        + `, but its model-scoped "${result.modelCommand ?? `${resolution.cli} auth status`}" probe exited non-zero;`
-        + ` verify the model name and this credential's access.`,
-    });
+    diagnostics.push(modelProbeRefusal(resolution as CliResolution & { model: string }, result));
+  }
+}
+
+// Only a probe whose output says the model is unknown (or the adapter gave no
+// output to read) is told to check the model name. An outdated CLI and a
+// usage-limited credential name a different remedy, and "verify the model
+// name" sends the author after a typo that is not there.
+function modelProbeRefusal(
+  resolution: CliResolution & { model: string },
+  result: CliProbeResult,
+): PreflightDiagnostic {
+  const { stepId, cli, model } = resolution;
+  const effective = describeEffectiveModel(stepId, model, cli, resolution.modelSource);
+  const command = `"${result.modelCommand ?? `${cli} auth status`}"`;
+  const exit = result.modelExitCode === undefined || result.modelExitCode === null ? '' : ` (exit ${result.modelExitCode})`;
+  const reported = result.modelFailureDetail === undefined ? '' : ` It reported: ${result.modelFailureDetail}`;
+  const base = { severity: 'refusal' as const, stepId, cli, model };
+  const cause = result.modelFailure?.cause;
+  if (cause === 'cli_outdated') {
+    const required = result.modelFailure?.requiredVersion;
+    return { ...base, kind: 'cli_outdated',
+      message: `${effective}, but this "${cli}" is too old to use that model`
+        + (required === undefined ? '' : `; version ${required} or newer is required`)
+        + `. Upgrade the CLI in the environment that runs this flow; the model name is not the problem.${reported}` };
+  }
+  if (cause === 'provider_usage_limited') {
+    return { ...base, kind: 'provider_usage_limited',
+      message: `${effective}, but the provider refused the model-scoped ${command} probe${exit} because this credential`
+        + ` has reached a usage or rate limit. Retry after the limit resets or use a credential with capacity;`
+        + ` the model name is not the problem.${reported}` };
   }
+  // A probe that printed nothing is judged on its exit code alone, which is
+  // how a wrapper refuses a model it cannot serve.
+  const unknownModel = cause === 'model_unknown' || result.modelFailureDetail === undefined;
+  return { ...base, kind: 'model_unavailable',
+    message: `${effective}, but its model-scoped ${command} probe exited non-zero${exit}`
+      + (unknownModel
+        ? `; verify the model name and this credential's access.`
+        : ` for a reason Relayflows does not recognise.`)
+      + reported };
 }
 
 function probeFailedMessage(