@relayflows/sdk 2.0.35 → 2.0.36

package/src/adapters/claude.ts

@@ -2,7 +2,9 @@ import type {
   CliAdapterIdentification,
   CliInvocation,
   HeadlessAdapter,
+  ModelProbeFailure,
 } from './base.js';
+import { providerUsageLimited } from './usage-limit.js';
 
 const MODEL_PROBE_PROMPT = 'Reply with exactly RELAYFLOWS_MODEL_READY and nothing else.';
 
@@ -30,6 +32,19 @@ export const claudeAdapter: HeadlessAdapter = {
     };
   },
 
+  classifyModelProbeFailure(output: string): ModelProbeFailure | undefined {
+    // Checked first: an older Claude Code also prints its own
+    // `unrecognized_model` catalog warning for a model newer than it, which
+    // must not read as the model being unknown to the provider.
+    const outdated = /does not support this model; version (\S+) or newer is required/.exec(output);
+    if (outdated !== null) return { cause: 'cli_outdated', requiredVersion: outdated[1]! };
+    if (providerUsageLimited(output)) return { cause: 'provider_usage_limited' };
+    if (/issue with the selected model|not_found_error|may not exist or you may not have access/i.test(output)) {
+      return { cause: 'model_unknown' };
+    }
+    return undefined;
+  },
+
   buildAgentInvocation(instruction: string, model?: string): CliInvocation {
     return {
       args: [

package/src/adapters/codex.ts

@@ -2,7 +2,9 @@ import type {
   CliAdapterIdentification,
   CliInvocation,
   HeadlessAdapter,
+  ModelProbeFailure,
 } from './base.js';
+import { providerUsageLimited } from './usage-limit.js';
 
 const MODEL_PROBE_PROMPT = 'Reply with exactly RELAYFLOWS_MODEL_READY and nothing else.';
 
@@ -29,6 +31,10 @@ export const codexAdapter: HeadlessAdapter = {
     };
   },
 
+  classifyModelProbeFailure(output: string): ModelProbeFailure | undefined {
+    return providerUsageLimited(output) ? { cause: 'provider_usage_limited' } : undefined;
+  },
+
   buildAgentInvocation(instruction: string, model?: string): CliInvocation {
     return {
       args: [

package/src/adapters/usage-limit.ts

@@ -0,0 +1,17 @@
+/**
+ * Provider refusals that mean "this credential is out of capacity right now",
+ * not "this model does not exist". Shared by raw provider adapters because the
+ * wording overlaps (HTTP 429, `rate_limit_error`, subscription usage windows).
+ */
+const USAGE_LIMITED = [
+  /usage limit/i,
+  /hit your (?:usage )?limit/i,
+  /(?:5-hour|weekly|session) limit reached/i,
+  /rate_limit_error/,
+  /API Error: 429\b/,
+  /credit balance is too low/i,
+];
+
+export function providerUsageLimited(output: string): boolean {
+  return USAGE_LIMITED.some(pattern => pattern.test(output));
+}

package/src/authored-activity.ts

@@ -0,0 +1,251 @@
+import type {
+  Activity,
+  ActivityDuration,
+  ActivityOptions,
+  EventFrame,
+  TriggerSource,
+  WebhookTriggerSource,
+  Wake,
+} from '@relayflows/surface';
+import type { SubscriptionNextResult } from './protocol.js';
+import { AuthoredFlowExecutionError, type AuthoredFlowSuspension } from './authored-flow-error.js';
+import { JournalClient } from './journal-client.js';
+
+type CloseReason = 'closed' | 'run_completed' | 'canceled';
+
+interface OpenActivity {
+  readonly activity: Activity;
+  close(reason: CloseReason): Promise<void>;
+}
+
+/** Owns body-local cursors that must close before the authored root completes. */
+export class AuthoredActivities {
+  private readonly activities: OpenActivity[] = [];
+
+  constructor(
+    private readonly journal: JournalClient,
+    private readonly runId: string | undefined,
+  ) {}
+
+  open(source: TriggerSource, options: ActivityOptions): Activity {
+    if (source?.kind !== 'webhook') {
+      throw new AuthoredFlowExecutionError('unsupported_header',
+        'f.on() requires an event source; schedule triggers start runs and cannot be awaited inside a body');
+    }
+    if (this.runId === undefined) {
+      throw new AuthoredFlowExecutionError('journal_protocol_violation', 'f.on() requires a durable authored root run');
+    }
+    const id = `activity-${this.activities.length + 1}`;
+    const activity = new JournalActivity(this.journal, this.runId, id, source, normalizeOptions(options));
+    this.activities.push(activity);
+    return activity.activity;
+  }
+
+  async closeAll(reason: Exclude<CloseReason, 'closed'>): Promise<void> {
+    for (const activity of this.activities) await activity.close(reason);
+  }
+}
+
+class JournalActivity implements OpenActivity {
+  readonly activity: Activity;
+  private readonly openPromise: Promise<void>;
+  private closed = false;
+  private nextSequence = 0;
+  private acknowledgeWaitId: string | undefined;
+
+  constructor(
+    private readonly journal: JournalClient,
+    private readonly runId: string,
+    private readonly subscriptionId: string,
+    private readonly source: WebhookTriggerSource,
+    private readonly options: NormalizedActivityOptions,
+  ) {
+    this.activity = Object.freeze({
+      next: () => this.next(),
+      close: () => this.close('closed'),
+    });
+    // Opening starts at f.on(), rather than at the first next(), so frames
+    // arriving while the body reads state or runs another step are inside the
+    // router's binding window. next()/close() await this same handshake.
+    this.openPromise = this.openNow();
+    void this.openPromise.catch(() => undefined);
+  }
+
+  async close(reason: CloseReason): Promise<void> {
+    if (this.closed) return;
+    try {
+      await this.ensureOpen();
+    } catch (error) {
+      // Failure cleanup has no active binding to close before activation.
+      // Re-throwing this handoff would disguise a real body failure as a
+      // normal suspension. Root termination fences any later activation.
+      if (reason !== 'closed' && error instanceof AuthoredFlowExecutionError
+        && error.code === 'subscription_suspended' && error.suspension?.kind === 'activation') return;
+      throw error;
+    }
+    await this.journal.subscriptionClose({
+      run_id: this.runId,
+      subscription_id: this.subscriptionId,
+      completion_reason: reason,
+    });
+    this.closed = true;
+  }
+
+  private async next(): Promise<Wake> {
+    if (this.closed) throw new AuthoredFlowExecutionError('activity_closed', 'activity is already closed');
+    await this.ensureOpen();
+    const result = await this.journal.subscriptionNext({
+      run_id: this.runId,
+      subscription_id: this.subscriptionId,
+      sequence: this.nextSequence,
+      ...(this.acknowledgeWaitId === undefined ? {} : { acknowledge_wait_id: this.acknowledgeWaitId }),
+    });
+    if (result.kind === 'suspended') {
+      throw suspended({
+        kind: 'event_wait', subscriptionId: result.subscription_id,
+        stream: result.stream, deadlineAtMs: result.deadline_at_ms,
+      }, this.runId);
+    }
+    const wake = decodeWake(result);
+    if (wake.kind === 'deadline' || wake.kind === 'overflow') {
+      this.closed = true;
+    } else {
+      this.acknowledgeWaitId = receiptId(result) ?? `${this.subscriptionId}/next/${this.nextSequence}`;
+      this.nextSequence += 1;
+    }
+    return wake;
+  }
+
+  private async ensureOpen(): Promise<void> {
+    await this.openPromise;
+  }
+
+  private async openNow(): Promise<void> {
+    const result = await this.journal.subscriptionOpen({
+      run_id: this.runId,
+      subscription_id: this.subscriptionId,
+      event_types: [this.source.name],
+      ...(this.source.filter === undefined ? {} : { pattern: this.source.filter }),
+      settle_ms: this.options.settleMs,
+      idle_ms: this.options.idleMs,
+      deadline_ms: this.options.deadlineMs,
+      include_self: this.options.includeSelf,
+    });
+    if (result.state === 'prepared') {
+      throw suspended({
+        kind: 'activation', subscriptionId: result.subscription_id,
+        eventTypes: Object.freeze([...result.event_types]),
+        ...(result.pattern === undefined ? {} : { pattern: Object.freeze({ ...result.pattern }) }),
+        stream: result.stream, settleMs: result.settle_ms, idleMs: result.idle_ms,
+        deadlineAtMs: result.deadline_at_ms, includeSelf: result.include_self,
+      }, this.runId);
+    }
+  }
+}
+
+function suspended(value: AuthoredFlowSuspension, runId: string): AuthoredFlowExecutionError {
+  return new AuthoredFlowExecutionError(
+    'subscription_suspended',
+    `subscription ${value.subscriptionId} is durably suspended for ${value.kind}`,
+    undefined,
+    runId,
+    undefined,
+    value,
+  );
+}
+
+function receiptId(result: SubscriptionNextResult): string | undefined {
+  const receipt = (result as { acknowledge_wait_id?: unknown }).acknowledge_wait_id;
+  return typeof receipt === 'string' && receipt.length > 0 ? receipt : undefined;
+}
+
+interface NormalizedActivityOptions {
+  readonly settleMs: number;
+  readonly idleMs: number;
+  readonly deadlineMs: number;
+  readonly includeSelf: boolean;
+}
+
+function normalizeOptions(options: ActivityOptions): NormalizedActivityOptions {
+  if (typeof options !== 'object' || options === null || Array.isArray(options)) {
+    throw unboundedSubscription('f.on() requires idle and deadline bounds');
+  }
+  const value = options as unknown as Record<string, unknown>;
+  const allowed = new Set(['settle', 'idle', 'deadline', 'includeSelf']);
+  for (const key of Object.keys(value)) {
+    if (!allowed.has(key)) throw new AuthoredFlowExecutionError('unbounded_subscription', `f.on() has unknown option ${JSON.stringify(key)}`);
+  }
+  if (!Object.hasOwn(value, 'idle') || !Object.hasOwn(value, 'deadline')) {
+    throw unboundedSubscription('f.on() requires both idle and deadline bounds');
+  }
+  if (value['includeSelf'] !== undefined && typeof value['includeSelf'] !== 'boolean') {
+    throw new AuthoredFlowExecutionError('unbounded_subscription', 'f.on() includeSelf must be a boolean');
+  }
+  return Object.freeze({
+    settleMs: parseDuration(value['settle'] as ActivityDuration | undefined, 'settle', true),
+    idleMs: parseDuration(value['idle'] as ActivityDuration, 'idle', false),
+    deadlineMs: parseDuration(value['deadline'] as ActivityDuration, 'deadline', false),
+    includeSelf: value['includeSelf'] === true,
+  });
+}
+
+function parseDuration(value: ActivityDuration | undefined, field: string, zeroAllowed: boolean): number {
+  if (value === undefined && zeroAllowed) return 0;
+  let milliseconds: number;
+  if (typeof value === 'number') milliseconds = value;
+  else if (typeof value === 'string') {
+    const match = /^(\d+(?:\.\d+)?)(ms|s|m|h|d)$/.exec(value);
+    const units: Record<string, number> = { ms: 1, s: 1_000, m: 60_000, h: 3_600_000, d: 86_400_000 };
+    const unit = match?.[2];
+    milliseconds = match === null || unit === undefined ? NaN : Math.round(Number(match[1]) * units[unit]!);
+  } else milliseconds = NaN;
+  if (!Number.isSafeInteger(milliseconds) || milliseconds < 0 || (!zeroAllowed && milliseconds === 0)) {
+    throw new AuthoredFlowExecutionError(
+      'unbounded_subscription',
+      `f.on() ${field} must be ${zeroAllowed ? 'a non-negative' : 'a positive'} whole number of milliseconds or a duration such as "72h"`,
+    );
+  }
+  return milliseconds;
+}
+
+function unboundedSubscription(message: string): AuthoredFlowExecutionError {
+  return new AuthoredFlowExecutionError('unbounded_subscription', message);
+}
+
+/** Decode the wire result at the journal boundary so malformed wakes fail closed. */
+export function decodeWake(value: SubscriptionNextResult): Wake {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return invalidWake();
+  if (value.kind === 'idle') return Object.freeze({ kind: 'idle' });
+  if (value.kind === 'events') {
+    if (!Array.isArray(value.events) || !isOffset(value.offset) || !value.events.every(isEventFrame)) return invalidWake();
+    return Object.freeze({ kind: 'events', events: Object.freeze([...value.events]) as readonly EventFrame[], offset: value.offset });
+  }
+  if (value.kind === 'deadline') {
+    if (value.pending !== null && !isPending(value.pending)) return invalidWake();
+    return Object.freeze({ kind: 'deadline', pending: value.pending === null ? null : Object.freeze({ ...value.pending }) });
+  }
+  if (value.kind === 'overflow') {
+    if (!isOffset(value.retained) || !isOffset(value.bytes) || !isOffset(value.from)) return invalidWake();
+    return Object.freeze({ kind: 'overflow', retained: value.retained, bytes: value.bytes, from: value.from });
+  }
+  return invalidWake();
+}
+
+function isEventFrame(value: unknown): value is EventFrame {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+    && typeof (value as { type?: unknown }).type === 'string';
+}
+
+function isPending(value: unknown): value is { from: number; to: number } {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+    && isOffset((value as { from?: unknown }).from)
+    && isOffset((value as { to?: unknown }).to);
+}
+
+function isOffset(value: unknown): value is number {
+  return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+}
+
+function invalidWake(): never {
+  throw new AuthoredFlowExecutionError('journal_protocol_violation', 'subscription.next returned an invalid wake result');
+}

package/src/authored-child-run.ts

@@ -0,0 +1,138 @@
+import { delay, LEASE_SWEEP_GRACE_MS } from './cli/run.js';
+import type { JournalClient } from './journal-client.js';
+import type { RunGetResult, RunStatus } from './protocol.js';
+
+/** One `journal.read` page; the kernel caps an unbounded read at 100 entries. */
+const PAGE = 1_000;
+const POLL_MS = 50;
+// A run between two of its own actions can report `running` with nothing in
+// flight for a moment (a wait just completed, the next attempt not yet
+// journaled). The same bound `classifyOutcome` gives that window (#179).
+const MAX_IDLE_POLLS = 40;
+
+/**
+ * Every entry of a child run's journal, paged.
+ *
+ * A single unbounded read returns the first 100 entries only, and a reader
+ * that needs the LAST completion of a step cannot stop at a page boundary.
+ * A short page is the end of the journal.
+ */
+export async function readChildJournal(journal: JournalClient, runId: string): Promise<unknown[]> {
+  const all: unknown[] = [];
+  let fromSeq = 1;
+  while (true) {
+    const { entries } = await journal.journalRead(runId, fromSeq, PAGE);
+    all.push(...entries);
+    if (entries.length < PAGE) return all;
+    const last = entries.at(-1) as { seq?: unknown } | undefined;
+    if (typeof last?.seq !== 'number' || !Number.isSafeInteger(last.seq) || last.seq < fromSeq) {
+      throw new Error(`invalid journal sequence reading child run "${runId}"`);
+    }
+    fromSeq = last.seq + 1;
+  }
+}
+
+/**
+ * Wait until an authored operation's child run is terminal, and say whether
+ * it got there.
+ *
+ * A child adopted through its admission key is not necessarily finished: on
+ * `flows resume` of a root whose daemon survived, `run.start` returns the
+ * existing child's CURRENT outcome without driving it, so the child may still
+ * be executing an attempt, or sleeping out a retry backoff, on the request
+ * that originally started it. Reading its journal then judges a history that
+ * is still being written.
+ *
+ * The wait is read-only on purpose: it never resumes the child. The kernel
+ * drives a deterministic attempt inline on the request that started it, and a
+ * second driver would presume that attempt dead and run the command again.
+ *
+ * Bounded by the child's own journaled deadlines, never a fixed one: a running
+ * attempt by its lease (renewed as the lease renews) plus the kernel's
+ * lease-sweep grace, a backoff by the `sleep.until` it journaled (once that
+ * wake has passed, by the settling window). With nothing in flight, only the
+ * short settling window above; a child parked on a worker
+ * returns at once. Either way the caller gets the status and decides.
+ */
+export async function waitForTerminalChildRun(
+  journal: JournalClient,
+  runId: string,
+  signal?: AbortSignal,
+): Promise<RunStatus> {
+  let idlePolls = 0;
+  while (true) {
+    if (signal?.aborted === true) throw new Error(`waiting for child run "${runId}" was canceled`);
+    const snapshot = await journal.runGet(runId);
+    if (snapshot.status === 'completed' || snapshot.status === 'failed') return snapshot.status;
+    const inFlight = await inFlightDeadline(journal, runId, snapshot);
+    if (inFlight === 'parked') return snapshot.status;
+    const remainingMs = inFlight === undefined ? 0 : inFlight.deadlineMs + inFlight.graceMs - Date.now();
+    if (inFlight !== undefined && remainingMs > 0) {
+      idlePolls = 0;
+      await delay(Math.min(POLL_MS, remainingMs), signal);
+      continue;
+    }
+    // Only a lease past its sweep grace is proof nothing is running the
+    // attempt. An elapsed retry wake is the kernel's normal transition to the
+    // next attempt — its driver may be folding the timer right now — so it is
+    // re-polled inside the settling window like any other in-between state.
+    if (inFlight?.what === 'lease') {
+      throw new Error(`child run "${runId}" step "${inFlight.stepId}" passed its lease`
+        + ` (${inFlight.deadlineMs}) without reaching a terminal state`);
+    }
+    if (idlePolls >= MAX_IDLE_POLLS) return snapshot.status;
+    idlePolls += 1;
+    await delay(POLL_MS, signal);
+  }
+}
+
+interface InFlight {
+  stepId: string;
+  what: 'lease' | 'retry backoff';
+  deadlineMs: number;
+  graceMs: number;
+}
+
+/**
+ * What the child is waiting on, and until when; `parked` when it is waiting
+ * on nothing this process can wait out.
+ *
+ * A worker-typed (`agent`/`llm`) step that is runnable, or whose retry
+ * backoff has elapsed, with no attempt running, needs a worker — or the
+ * `run.resume` a caller like `classifyOutcome` issues — to move. That is the
+ * park `classifyOutcome` reports, and waiting on it would only delay the same
+ * answer. A deterministic step in that state is the kernel between two of its
+ * own actions, which the caller's settling window covers.
+ */
+async function inFlightDeadline(
+  journal: JournalClient,
+  runId: string,
+  snapshot: RunGetResult,
+): Promise<InFlight | 'parked' | undefined> {
+  const steps = Object.entries(snapshot.steps);
+  const running = steps.find(([, step]) => step.state === 'running' && step.lease_deadline_ms !== undefined);
+  if (running !== undefined) {
+    return {
+      stepId: running[0], what: 'lease', deadlineMs: running[1].lease_deadline_ms!, graceMs: LEASE_SWEEP_GRACE_MS,
+    };
+  }
+  const worker = ([, step]: [string, { type: string }]) => step.type !== 'deterministic';
+  if (steps.some(entry => worker(entry) && entry[1].state === 'runnable')) return 'parked';
+  const backoff = steps.find(([, step]) => step.state === 'backoff');
+  if (backoff === undefined) return undefined;
+  const wakeAtMs = (await readChildJournal(journal, runId))
+    .map(entry => retryWake(entry, backoff[0]))
+    .filter((value): value is number => value !== undefined)
+    .at(-1);
+  if (wakeAtMs === undefined) return undefined;
+  if (wakeAtMs <= Date.now()) return worker(backoff) ? 'parked' : undefined;
+  return { stepId: backoff[0], what: 'retry backoff', deadlineMs: wakeAtMs, graceMs: 0 };
+}
+
+function retryWake(entry: unknown, stepId: string): number | undefined {
+  if (typeof entry !== 'object' || entry === null) return undefined;
+  const { entry_type: type, step_id: step, payload } = entry as Record<string, unknown>;
+  if (type !== 'sleep.until' || step !== stepId || typeof payload !== 'object' || payload === null) return undefined;
+  const wakeAtMs = (payload as Record<string, unknown>)['wake_at_ms'];
+  return typeof wakeAtMs === 'number' && Number.isFinite(wakeAtMs) ? wakeAtMs : undefined;
+}

package/src/authored-flow-error.ts

@@ -11,6 +11,10 @@ export type AuthoredFlowExecutionErrorCode =
   | 'helper_slack.credential_missing'
   | 'helper_slack.mount_required'
   | 'budget_syntax_invalid'
+  /** The step's CLI is too old for its model — an environment refusal, not a spec error. */
+  | 'cli_outdated'
+  /** The step's credential hit a provider usage/rate limit during preflight. */
+  | 'provider_usage_limited'
   | 'agent_cli_unresolved'
   | 'agent_parked'
   | 'llm_cli_unresolved'
@@ -39,6 +43,9 @@ export type AuthoredFlowExecutionErrorCode =
   | 'unsettled_derived_work'
   | 'unsupported_promise_lifecycle'
   | 'unsupported_workspace_permission'
+  | 'unbounded_subscription'
+  | 'activity_closed'
+  | 'subscription_suspended'
   | 'unawaited_step'
   | 'unsupported_verb';
 
@@ -76,12 +83,38 @@ export class AuthoredFlowExecutionError extends Error {
      * Node-child error frame — can forward it instead of dropping it.
      */
     readonly details?: StepFailedDetails,
+    readonly suspension?: AuthoredFlowSuspension,
   ) {
     super(`${code}: ${message}`);
     this.name = 'AuthoredFlowExecutionError';
   }
 }
 
+/** Serialized into the CLI report so Cloud can atomically finish activation or wait for a wake. */
+export type AuthoredFlowSuspension =
+  /**
+   * Exact durable `subscription.prepared` facts Cloud must persist before it
+   * fences provider ingress and invokes `subscription.activate`. Binding
+   * generation and ingress cursor are Cloud-assigned receipts, deliberately
+   * absent from the authored request.
+   */
+  | {
+    readonly kind: 'activation';
+    readonly subscriptionId: string;
+    readonly eventTypes: readonly string[];
+    readonly pattern?: Readonly<Record<string, unknown>>;
+    readonly stream: string;
+    readonly settleMs: number;
+    readonly idleMs: number;
+    readonly deadlineAtMs: number;
+    readonly includeSelf: boolean;
+  }
+  | {
+    readonly kind: 'event_wait';
+    readonly subscriptionId: string;
+    readonly stream: string;
+    readonly deadlineAtMs: number;
+  };
 /** The question an authored body parked on, as the kernel journals it. */
 export interface AuthoredHumanWait {
   readonly waitId: string;

package/src/authored-flow-executor.ts

@@ -43,6 +43,7 @@ import type { LoadedAuthoredFlowNode } from './authored-flow-loader.js';
 import type { RunLifecycleOptions } from './cli/run.js';
 import {
   AuthoredFlowExecutionError,
+  type AuthoredFlowSuspension,
   AuthoredHumanParked,
   type AuthoredFlowExecutionErrorCode,
 } from './authored-flow-error.js';
@@ -54,6 +55,7 @@ import {
   verifyAuthoredOperations,
 } from './authored-flow-operation.js';
 import { AuthoredFlowLifecycle } from './authored-flow-lifecycle.js';
+import { AuthoredActivities } from './authored-activity.js';
 import { displayLabel, type AuthoredStepEdges } from './authored-step-index.js';
 import { JournalClient } from './journal-client.js';
 import { PluginError } from './plugin-manifest.js';
@@ -105,6 +107,7 @@ export interface AuthoredExecutionRuntime {
 }
 
 export interface AuthoredFlowExecutionResult {
+  readonly state?: undefined;
   readonly executionRuntime?: AuthoredExecutionRuntime;
   readonly rootRunId?: string;
   readonly name: string;
@@ -118,6 +121,14 @@ export interface AuthoredFlowExecutionResult {
   readonly journalSteps: readonly AuthoredFlowJournalStep[];
 }
 
+/** A body reached a durable event boundary and released its worker lease. */
+export interface AuthoredFlowSuspendedResult {
+  readonly state: 'suspended';
+  readonly name: string;
+  readonly suspension: AuthoredFlowSuspension;
+  readonly journalSteps: readonly AuthoredFlowJournalStep[];
+}
+
 // The authoring SURFACE stays wide: `done()` accepts every
 // `FlowCompletionReason` and refuses the kernel-owned ones at runtime with a
 // diagnostic that names the alternative. The RESULT is narrow, because `done()`
@@ -273,6 +284,7 @@ export async function executeAuthoredFlow<Input = undefined>(
   const journalSteps: AuthoredFlowJournalStep[] = [];
   const authoredSteps: AuthoredFlowOperation<unknown>[] = [];
   const lifecycle = new AuthoredFlowLifecycle();
+  const activities = new AuthoredActivities(journal, options.rootRunId);
   const edgeOverrides = new Map<string, AuthoredStepEdges>();
   const stepEdges = (step: string): AuthoredStepEdges | undefined => {
     const overridden = edgeOverrides.get(step);
@@ -300,6 +312,7 @@ export async function executeAuthoredFlow<Input = undefined>(
     definition.name, journal, journalSteps, budget, {
       ...(options.rootRunId === undefined ? {} : { rootRunId: options.rootRunId }),
       ...(options.dataDir === undefined ? {} : { dataDir: options.dataDir }),
+      ...(options.signal === undefined ? {} : { signal: options.signal }),
       stepEdges,
     },
   );
@@ -567,6 +580,17 @@ export async function executeAuthoredFlow<Input = undefined>(
       );
       return trackStep(authoredSteps, agentOp);
     },
+    on(source, activityOptions) {
+      assertOperationAllowed('on', definition.name, requestedCompletion);
+      // Activity ids are root-scoped (`activity-N`); a child's own counter would collide.
+      if ((options.dispatchDepth ?? 0) > 0) {
+        throw new AuthoredFlowExecutionError(
+          'dispatch_invalid',
+          `child flow "${definition.name}" cannot call f.on in this release; activities are root-scoped`,
+        );
+      }
+      return activities.open(source, activityOptions);
+    },
     /**
      * `f.human` (docs/SURFACE.md §1, §7). The question is not a child run: it
      * is the ROOT attempt parking on the kernel's `wait.human`. The body
@@ -794,6 +818,11 @@ export async function executeAuthoredFlow<Input = undefined>(
     try {
       worker.stop(bodyFailure);
       await stopAuthoredOperations(authoredSteps, bodyFailure);
+      // A durable wait hands execution back to the control plane. Its
+      // subscriptions must keep receiving events while no body is running.
+      const parked = bodyFailure instanceof AuthoredFlowExecutionError
+        && (bodyFailure.code === 'subscription_suspended' || bodyFailure.code === 'human_parked');
+      if (!parked) await activities.closeAll('canceled');
     } finally {
       lifecycle.close();
     }
@@ -821,6 +850,7 @@ export async function executeAuthoredFlow<Input = undefined>(
     try {
       worker.stop(missingCompletion);
       await stopAuthoredOperations(authoredSteps, missingCompletion);
+      await activities.closeAll('canceled');
     } finally {
       lifecycle.close();
     }
@@ -828,6 +858,16 @@ export async function executeAuthoredFlow<Input = undefined>(
   }
   try {
     await verifyAuthoredOperations(definition.name, authoredSteps, lifecycle);
+  } catch (error) {
+    try {
+      await activities.closeAll('canceled');
+    } finally {
+      lifecycle.close();
+    }
+    throw error;
+  }
+  try {
+    await activities.closeAll('run_completed');
   } finally {
     lifecycle.close();
   }

package/src/authored-mcp.ts

@@ -140,13 +140,13 @@ export async function runMcpEffect(
     childRunId = outcome.run_id;
     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 McpStepError(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;
   } finally {
     clearTimeout(timer);

package/src/authored-node-entry.ts

@@ -94,7 +94,9 @@ try {
     // the only one that saw the child's classification.
     ...(error instanceof AuthoredFlowExecutionError ? { code: error.code,
       completionReason: error.completionReason, runId: error.runId,
-      details: error.details, parkCause: error.parkCause } : {}),
+      details: error.details,
+      parkCause: error.parkCause,
+      ...(error.suspension === undefined ? {} : { suspension: error.suspension }) } : {}),
     ...(error instanceof AuthoredHumanParked ? { wait: error.wait } : {}) });
   process.exitCode = 1;
 } finally {