@relayflows/sdk 2.0.35 → 2.0.36

package/src/authored-node-runner.ts

@@ -18,6 +18,7 @@ import type {
 } from './failure-kinds.js';
 import { HUMAN_WAIT_ID } from './authored-human.js';
 import { assertAuthoredPromiseHooks } from './authored-runtime-capability.js';
+import { settlingCompletion } from './step-settling.js';
 
 let embeddedSource: string | undefined;
 /** Installed by the standalone build; never fetched or resolved from a workspace. */
@@ -144,7 +145,8 @@ export async function runAuthoredInNode(
               } else if (typeof message.code === 'string') {
                 const authored = new AuthoredFlowExecutionError(message.code as AuthoredFlowExecutionErrorCode,
                   message.message, message.completionReason, message.runId,
-                  stepFailedFrame(message.details));
+                  stepFailedFrame(message.details),
+                  isSuspension(message.suspension) ? message.suspension : undefined);
                 // Validated, not trusted, like `details`: an unrecognised cause
                 // is dropped so the boundary says nothing about workers rather
                 // than acting on a value this frame could have invented.
@@ -172,6 +174,35 @@ export async function runAuthoredInNode(
   } finally { await rm(directory, { recursive: true, force: true }); }
 }
 
+function isSuspension(value: unknown): value is import('./authored-flow-error.js').AuthoredFlowSuspension {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false;
+  const record = value as Record<string, unknown>;
+  const common = typeof record['subscriptionId'] === 'string' && record['subscriptionId'].length > 0
+    && typeof record['stream'] === 'string' && record['stream'].length > 0
+    && Number.isSafeInteger(record['deadlineAtMs']) && (record['deadlineAtMs'] as number) >= 0;
+  if (!common) return false;
+  if (record['kind'] === 'event_wait') return true;
+  return record['kind'] === 'activation'
+    && Array.isArray(record['eventTypes']) && record['eventTypes'].length > 0
+    && record['eventTypes'].every(type => typeof type === 'string' && type.length > 0)
+    && (record['pattern'] === undefined || isJsonRecord(record['pattern']))
+    && Number.isSafeInteger(record['settleMs']) && (record['settleMs'] as number) >= 0
+    && Number.isSafeInteger(record['idleMs']) && (record['idleMs'] as number) > 0
+    && typeof record['includeSelf'] === 'boolean';
+}
+
+function isJsonRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+    && Object.values(value).every(isJsonValue);
+}
+
+function isJsonValue(value: unknown): boolean {
+  return value === null || typeof value === 'boolean' || typeof value === 'string'
+    || (typeof value === 'number' && Number.isFinite(value))
+    || (Array.isArray(value) && value.every(isJsonValue))
+    || isJsonRecord(value);
+}
+
 /** A park signal from the child names the question the parent must journal. */
 function isHumanWaitFrame(value: unknown): value is AuthoredHumanWait {
   const wait = value as Partial<AuthoredHumanWait> | null;
@@ -342,15 +373,17 @@ export async function verifyAuthoredNodeResult(
       // step a child spec may carry, and it must have completed too.
       const lowered = spec?.steps ?? [];
       const specShape = lowered.length === 1 || (lowered.length === 2 && lowered[1]?.id === `${claimed.id}.gate`);
-      const completed = entries.filter(entry => entry.entry_type === 'step.completed' && entry.step_id === claimed.id);
-      const gateCompleted = lowered.length === 2
-        ? entries.filter(entry => entry.entry_type === 'step.completed' && entry.step_id === `${claimed.id}.gate`) : [];
+      // Judged against the step's SETTLING completion, the same one the
+      // authored reader returned: a retried attempt (`disposition: retry`,
+      // e.g. crash recovery's `crashed`) journals a completion of its own
+      // ahead of it, so neither a count nor the first entry is the verdict.
+      const completed = settlingCompletion(entries, claimed.id);
+      const gateCompleted = lowered.length === 2 ? settlingCompletion(entries, `${claimed.id}.gate`) : undefined;
       const terminalFacts = entries.filter(entry => entry.entry_type === 'run.completed');
       if (spec?.name !== `${metadata.flowName}/${claimed.id}` || !specShape
-        || step?.id !== claimed.id || completed.length !== 1
-        || completed[0]?.payload?.completionReason !== 'success'
-        || (lowered.length === 2 && (gateCompleted.length !== 1 || gateCompleted[0]?.payload?.completionReason !== 'success'))
-        || terminalFacts.length !== 1 || terminalFacts[0]?.payload?.completionReason !== 'success') invalid(`evidence ${claimed.id} spec=${spec?.name} step=${step?.id} completed=${completed.length}`);
+        || step?.id !== claimed.id || completed?.payload?.completionReason !== 'success'
+        || (lowered.length === 2 && gateCompleted?.payload?.completionReason !== 'success')
+        || terminalFacts.length !== 1 || terminalFacts[0]?.payload?.completionReason !== 'success') invalid(`evidence ${claimed.id} spec=${spec?.name} step=${step?.id} completed=${completed?.payload?.completionReason}`);
       if (claimed === terminal) {
         // The claimed verdict must match the marker the journal actually
         // recorded, so an IPC frame cannot claim `success` over a run whose

package/src/authored-plugin-effect.ts

@@ -125,13 +125,13 @@ export async function runPluginEffect(
       if (dispatchExpired) await cancelChildRun();
       if (outcome.status !== 'completed') await completed;
       if (diagnostic !== undefined) {
-        try { await readCompletedStepOutput(journal, outcome.run_id, id, journalSteps); }
+        try { await readCompletedStepOutput(journal, outcome.run_id, id, journalSteps, {}, outcome.status); }
         catch (error) {
           if (!(error instanceof AuthoredFlowExecutionError) || error.code !== 'step_failed') throw error;
           throw new PluginStepError(diagnostic, outcome.run_id);
         }
       }
-      const receipt = await readCompletedStepOutput(journal, outcome.run_id, id, journalSteps) as { output: unknown };
+      const receipt = await readCompletedStepOutput(journal, outcome.run_id, id, journalSteps, {}, outcome.status) as { output: unknown };
       return receipt.output;
     }, admissionKey), deadline]);
   } finally {

package/src/authored-root.ts

@@ -4,7 +4,7 @@ import { createHash, randomUUID } from 'node:crypto';
 import { readFile } from 'node:fs/promises';
 import { canonicalize } from './canonical.js';
 import { compileSpec, toKernelSpec } from './compile.js';
-import { executeAuthoredFlow, type AuthoredFlowExecutionResult } from './authored-flow-executor.js';
+import { executeAuthoredFlow, type AuthoredFlowExecutionResult, type AuthoredFlowSuspendedResult } from './authored-flow-executor.js';
 import { isDurableCompletionDetail, isLoweredCompletion } from './authored-completion.js';
 import { AUTHORED_ROOT_KIND } from './authored-verdict.js';
 import {
@@ -20,6 +20,11 @@ import { withWorkerLease } from './worker-lease.js';
 import { AuthoredFlowExecutionError, AuthoredHumanParked } from './authored-flow-error.js';
 import { readOpenHumanWaits } from './authored-human.js';
 import { isSurfaceCompletionReason } from './authored-step-output.js';
+import { readSubscriptionPark } from './authored-subscription-park.js';
+
+export type DurableAuthoredFlowResult =
+  | (AuthoredFlowExecutionResult & { readonly rootRunId: string })
+  | (AuthoredFlowSuspendedResult & { readonly rootRunId: string });
 
 /**
  * Taken from the projection module rather than spelled twice: `flows status`
@@ -55,6 +60,8 @@ export interface AuthoredRootSourceAuthority {
 }
 
 export interface DurableAuthoredOptions {
+  /** Preserve root authority even if a child later fails or parks. */
+  readonly onAdmitted?: (runId: string) => void;
   readonly dataDir: string;
   readonly admissionKey?: string;
   readonly localAgentStream?: string;
@@ -69,7 +76,7 @@ export async function executeDurableAuthoredFlow(
   journal: JournalClient,
   input: unknown,
   options: DurableAuthoredOptions,
-): Promise<AuthoredFlowExecutionResult & { readonly rootRunId: string }> {
+): Promise<DurableAuthoredFlowResult> {
   assertAuthoredRuntimeAvailable();
   const source = await readFile(loaded.sourcePath);
   const sources = await Promise.all(loaded.graph.map(async node => Object.freeze({
@@ -106,6 +113,7 @@ export async function executeDurableAuthoredFlow(
       workspace: [], streams: [{ stream, read_offset: 0 }],
     });
     const outcome = await journal.runStart(spec, undefined, admissionKey);
+    options.onAdmitted?.(outcome.run_id);
     if (outcome.status === 'completed') {
       dispatchWait.cancel();
       return await completedRootResult(journal, outcome.run_id);
@@ -119,6 +127,9 @@ export async function executeDurableAuthoredFlow(
     // redelivers only when the former worker connection is gone.
     const resumed = await journal.runResume(outcome.run_id);
     await assertNoOpenHumanWait(journal, resumed);
+    const parked = await readSubscriptionPark(journal, outcome.run_id);
+    if (parked !== undefined) return { state: 'suspended', name: metadata.flowName,
+      suspension: parked, journalSteps: [], rootRunId: outcome.run_id };
     const dispatch = await dispatchWait.promise;
     return await driveRoot(loaded, metadata, journal, peer, dispatch, options);
   } finally {
@@ -132,7 +143,7 @@ export async function resumeDurableAuthoredFlow(
   rootRunId: string,
   journal: JournalClient,
   options: Omit<DurableAuthoredOptions, 'admissionKey'>,
-): Promise<(AuthoredFlowExecutionResult & { readonly rootRunId: string }) | undefined> {
+): Promise<DurableAuthoredFlowResult | undefined> {
   const metadata = await readAuthoredRootMetadata(journal, rootRunId);
   if (metadata === undefined) return undefined;
   assertAuthoredRuntimeAvailable();
@@ -159,6 +170,9 @@ export async function resumeDurableAuthoredFlow(
     assertRootCanDispatch(outcome);
     await assertNoOpenHumanWait(journal, outcome);
     options.lifecycle?.onRunStarted?.({ runId: rootRunId, flow: metadata.flowName, resumed: true });
+    const parked = await readSubscriptionPark(journal, rootRunId);
+    if (parked !== undefined) return { state: 'suspended', name: metadata.flowName,
+      suspension: parked, journalSteps: [], rootRunId };
     const dispatch = await dispatchWait.promise;
     return await driveRoot(loaded, metadata, journal, peer, dispatch, options);
   } finally {
@@ -204,7 +218,7 @@ async function driveRoot(
   peer: JournalClient,
   dispatch: StepDispatchEvent,
   options: Omit<DurableAuthoredOptions, 'admissionKey'>,
-): Promise<AuthoredFlowExecutionResult & { readonly rootRunId: string }> {
+): Promise<DurableAuthoredFlowResult> {
   try {
     const result = await withWorkerLease(peer, dispatch, async rootSignal => {
       const callerSignal = options.lifecycle?.signal;
@@ -248,6 +262,15 @@ async function driveRoot(
     );
     return Object.freeze({ ...result, rootRunId: dispatch.run_id });
   } catch (error) {
+    if (error instanceof AuthoredFlowExecutionError
+      && error.code === 'subscription_suspended'
+      && error.suspension !== undefined) {
+      await peer.subscriptionPark({ run_id: dispatch.run_id, step_id: dispatch.step_id,
+        attempt: dispatch.attempt, idempotency_key: dispatch.idempotency_key,
+        subscription_id: error.suspension.subscriptionId, phase: error.suspension.kind });
+      return Object.freeze({ state: 'suspended' as const, name: metadata.flowName,
+        suspension: error.suspension, journalSteps: Object.freeze([]), rootRunId: dispatch.run_id });
+    }
     if (error instanceof AuthoredHumanParked) {
       // Not a failure: the body reached a question nobody has answered. Park
       // THIS attempt on the kernel's `wait.human` under the body's own wait

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-worker-step.ts

@@ -41,6 +41,7 @@ export function authoredWorkerRunner(
     ...(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 +57,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 +140,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/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';
 
@@ -117,7 +117,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 +130,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 +145,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