@relayflows/sdk 2.0.34 → 2.0.36

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;
@@ -122,6 +148,8 @@ export interface RunLifecycleOptions {
   onJournalEntry?: (entry: JournalEvent) => void;
   /** An authored root was admitted: its id is known before its body runs. */
   onRunStarted?: (run: { runId: string; flow: string; resumed?: boolean }) => void;
+  /** A declarative root returned its admission receipt, even if no watched entry arrived. */
+  onRunReceipt?: (run: { runId: string; flow: string }) => void;
   localAgent?: boolean;
   /** `--agent-capacity`: the local workers' concurrency; the default is `DEFAULT_LOCAL_AGENT_CAPACITY`. */
   agentCapacity?: number;
@@ -183,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');
@@ -191,6 +222,14 @@ async function executeCheckedFlow(
     }
     if (options.onJournalEntry !== undefined) client.on('entry', options.onJournalEntry);
     const outcome = await startWatched(client, spec, options);
+    // `run.start { watch: true }` is an event stream, not the source of the
+    // root identity. A short deterministic run can finish before its first
+    // watched entry is delivered (and an older daemon may refuse `watch`), so
+    // receipt consumers such as the Cloud mirror need the admitted id too.
+    // This stays separate from `onRunStarted`: opening the observer without a
+    // streamed journal would manufacture an empty projection and suppress its
+    // truthful "not projected" diagnostic.
+    options.onRunReceipt?.({ runId: outcome.run_id, flow: spec.name ?? 'flow' });
     const execution = await classifyOutcome(client, 'run', outcome, base, socketPath, { ...options, dataDir });
     if (options.reuseFromRunId !== undefined) {
       execution.report.reuse = await reuseSummary(client, outcome.run_id, options.reuseFromRunId);
@@ -261,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
@@ -301,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
@@ -308,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);
@@ -945,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,
@@ -1046,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
@@ -380,6 +381,9 @@ export async function runCli(
         observer?.onRunStarted(run);
         mirror?.onRunStarted(run);
       },
+      ...(mirror === undefined ? {} : {
+        onRunReceipt: (run: { runId: string }) => { mirror.onRunStarted(run); },
+      }),
     }),
     onWait: (progress: RunProgress) => {
       emitWait(progress, logged);
@@ -410,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);
@@ -434,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)
@@ -449,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/cloud-mirror-step.ts

@@ -152,6 +152,8 @@ export interface MirroredJournal {
   children: string[];
   /** Authored graph hints by step id, from an authored root's step index. */
   hints: Map<string, { label?: string; after?: string[] }>;
+  /** Authored completion receipts are durable evidence, not graph nodes. */
+  hidden: string[];
 }
 
 type Payload = Record<string, unknown>;
@@ -507,6 +509,7 @@ export function mirrorJournal(
     transcripts,
     children: index.children,
     hints: index.hints,
+    hidden: index.hidden,
   };
 }
 
@@ -522,7 +525,11 @@ export function mirrorJournal(
 function authoredIndex(
   events: readonly JournalEvent[],
   env: NodeJS.ProcessEnv,
-): { children: string[]; hints: Map<string, { label?: string; after?: string[] }> } {
+): {
+  children: string[];
+  hints: Map<string, { label?: string; after?: string[] }>;
+  hidden: string[];
+} {
   const messages: unknown[] = [];
   for (const event of events) {
     if (event.entry_type !== 'stream.appended') continue;
@@ -531,8 +538,15 @@ function authoredIndex(
   }
   const children: string[] = [];
   const hints = new Map<string, { label?: string; after?: string[] }>();
+  const hidden: string[] = [];
   for (const entry of foldAuthoredStepRecords(messages).values()) {
     if (/^[A-Za-z0-9][A-Za-z0-9_-]*$/u.test(entry.runId)) children.push(entry.runId);
+    // This is the executor's durable verdict receipt, not an authored unit of
+    // work. Only an entry in the authored root index can be hidden here, so a
+    // declarative step coincidentally named `complete-N` remains visible.
+    if (/(?:^|--)complete-[1-9][0-9]*$/.test(entry.step)) {
+      hidden.push(`${entry.runId}/${entry.step}`);
+    }
     const name = label(entry.label, env);
     const after = entry.after === undefined
       ? undefined
@@ -546,7 +560,7 @@ function authoredIndex(
       ...(after === undefined ? {} : { after }),
     });
   }
-  return { children, hints };
+  return { children, hints, hidden };
 }
 
 /**

package/src/cloud-mirror.ts

@@ -287,6 +287,7 @@ export function createRunMirror(options: RunMirrorOptions): RunMirror {
   const finals = new Map<string, { journalRunId: string; row: FinalStep }>();
   const transcripts = new Map<string, { stepName: string; attempts: Array<{ attempt: number; path: string }> }>();
   const hints = new Map<string, { label?: string; after?: string[] }>();
+  const hidden = new Set<string>();
   /** Live steps the cache cap dropped, by identity, so a capped view owns up to it. */
   const evicted = new Set<string>();
   /** Finished steps past the report cap, by identity. Counted, never sent. */
@@ -318,6 +319,7 @@ export function createRunMirror(options: RunMirrorOptions): RunMirror {
 
   const remember = (journalRunId: string, step: SnapshotStep, order: number): void => {
     const key = `${journalRunId}/${step.stepName}`;
+    if (hidden.has(key)) return;
     const existing = steps.get(key);
     const changed = existing === undefined || fingerprint(existing.step) !== fingerprint(step);
     steps.set(key, { step, order, changedAt: changed ? now() : existing!.changedAt });
@@ -365,19 +367,30 @@ export function createRunMirror(options: RunMirrorOptions): RunMirror {
         continue;
       }
       for (const child of folded.children) admit(child);
+      for (const key of folded.hidden) {
+        hidden.add(key);
+        steps.delete(key);
+        finals.delete(key);
+        transcripts.delete(key);
+      }
       for (const [key, hint] of folded.hints) {
         // Merge, never replace: a completion record can omit a label or an
         // edge the admission carried, and the view must not lose a step's
         // name between them.
         const existing = hints.get(key);
         hints.set(key, {
-          ...(hint.label ?? existing?.label ? { label: hint.label ?? existing?.label } : {}),
-          ...(hint.after ?? existing?.after ? { after: hint.after ?? existing?.after } : {}),
+          // The root's authored index is scanned before the child journal and
+          // carries causal edges across child runs. A child spec only knows
+          // its own single-step graph (`depends_on: []`), so it may fill a
+          // missing field but must never erase the root's richer answer.
+          ...(existing?.label ?? hint.label ? { label: existing?.label ?? hint.label } : {}),
+          ...(existing?.after ?? hint.after ? { after: existing?.after ?? hint.after } : {}),
         });
       }
       folded.steps.forEach((step, order) => remember(runId, step, order));
       for (const row of folded.finals) {
         const key = `${runId}/${row.stepName}`;
+        if (hidden.has(key)) continue;
         // The report cap bounds what this process holds, not just what it
         // sends: a run with ten thousand steps must not grow its own mirror.
         // Steps past it are counted by identity, so a step read twice is one

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(