@animalabs/agent-framework 0.21.1 → 0.22.1

package/src/gate/event-gate.ts

@@ -88,6 +88,11 @@ interface PendingEvent {
    *  newer ambient chatter when a batched wake picks its provenance — the same
    *  rule the framework applies to the turn's speech locus. */
   addressed: boolean;
+  /** The REGISTERED (composite) channel id the event arrived on, resolved by
+   *  the host at enqueue time. Differs from `channelId` for push events,
+   *  whose `channelId` is the adapter's raw id (a bare Discord snowflake for a
+   *  DM) — unroutable. Absent when the host could not resolve one. */
+  routeChannelId?: string;
 }
 
 /**
@@ -106,6 +111,15 @@ export interface WakeProvenance {
   counterparty?: string;
   /** True when the chosen event was `chat:addressed`. */
   addressed?: boolean;
+  /** Speech locus for the wake: the routable channel of the chosen event,
+   *  set ONLY when that event addressed the agent (mention / reply / DM) and
+   *  the host resolved its registered channel. A batched wake used to carry
+   *  no locus at all, so its reply fell back to the process-global
+   *  most-recent-inbound channel — which any ambient message elsewhere,
+   *  arriving a second after the DM that caused the wake, could retarget
+   *  (2026-09-30: a DM reply published into a guild channel). Ambient-only
+   *  batches still set nothing and keep the legacy fallback. */
+  routeChannelId?: string;
   /** Timestamp (ms) of the chosen event, so a consumer coalescing several
    *  requests can order by event recency, not by flush order. */
   at?: number;
@@ -190,7 +204,14 @@ export function wakeProvenance(events: PendingEvent[]): WakeProvenance | undefin
   let newest: PendingEvent | undefined;
   let newestAddressed: PendingEvent | undefined;
   for (const e of events) {
-    if (!e.channelId && !e.authorId) continue;
+    // A resolved route counts as naming a channel only for an ADDRESSED
+    // event: a push whose origin declares only `mcplChannelId` (no raw
+    // channel id, no author) is still a routable addressed message, and
+    // skipping it would leave its wake on the most-recent-inbound fallback.
+    // An ambient one stays out: the route is never reported for it, so as
+    // the pick it would carry no telemetry at all and hide an earlier event
+    // that names its channel and author.
+    if (!e.channelId && !e.authorId && !(e.addressed && e.routeChannelId)) continue;
     if (!newest || e.timestamp >= newest.timestamp) newest = e;
     if (e.addressed && (!newestAddressed || e.timestamp >= newestAddressed.timestamp)) newestAddressed = e;
   }
@@ -204,10 +225,20 @@ export function wakeProvenance(events: PendingEvent[]): WakeProvenance | undefin
     ...(channelId ? { channelId } : {}),
     ...(pick.authorId ? { counterparty: `${ns}:user:${pick.authorId}` } : {}),
     ...(pick.addressed ? { addressed: true } : {}),
+    ...(pick.addressed && pick.routeChannelId ? { routeChannelId: pick.routeChannelId } : {}),
     at: pick.timestamp,
   };
 }
 
+/**
+ * Default route-channel resolution when the host supplies none: a
+ * channel-incoming event's channel id is already the registered composite id;
+ * a push event's is the adapter's raw id, which only the host can map.
+ */
+function defaultRouteChannel(info: GateEventInfo): string | undefined {
+  return info.eventType === 'mcpl:channel-incoming' && info.channelId ? info.channelId : undefined;
+}
+
 /** Compact, log-friendly serialization of a GateBehavior. */
 function formatBehavior(b: import('./types.js').GateBehavior): string {
   if (typeof b === 'string') return b;
@@ -587,6 +618,7 @@ export class EventGate {
   ) => unknown;
   private requestInferenceFn: (agentName: string, reason: string, source: string, provenance?: WakeProvenance) => void;
   private getAgentNamesFn: () => string[];
+  private resolveRouteChannelFn: (info: GateEventInfo) => string | undefined;
   /** Clock injection — keeps the new rate_limit / passive_sample paths
    *  testable without monkey-patching Date.now globally. */
   private now: () => number;
@@ -608,6 +640,10 @@ export class EventGate {
     now?: () => number;
     /** Per-event timeout (ms) for the optional gate.js script. Default 50. */
     scriptTimeoutMs?: number;
+    /** Map an event to the registered channel it arrived on (the host knows
+     *  how push-event origins compose into channel ids). Default: a
+     *  channel-incoming event's own channel id; nothing for push events. */
+    resolveRouteChannel?: (info: GateEventInfo) => string | undefined;
   }) {
     this.configPath = opts.configPath;
     this.privilegedUsersPath = opts.privilegedUsersPath;
@@ -615,6 +651,7 @@ export class EventGate {
     this.addMessageFn = opts.addMessage;
     this.requestInferenceFn = opts.requestInference;
     this.getAgentNamesFn = opts.getAgentNames;
+    this.resolveRouteChannelFn = opts.resolveRouteChannel ?? defaultRouteChannel;
     this.now = opts.now ?? (() => Date.now());
     this.loadPrivileged();
 
@@ -1432,6 +1469,15 @@ export class EventGate {
   // Debounce
   // =========================================================================
 
+  /** Registered channel for an event; a resolver fault never breaks gating. */
+  private routeChannelFor(info: GateEventInfo): string | undefined {
+    try {
+      return this.resolveRouteChannelFn(info) || undefined;
+    } catch {
+      return undefined;
+    }
+  }
+
   private handleDebounce(policy: GatePolicy, info: GateEventInfo): void {
     const debounceMs = (policy.behavior as { debounce: number }).debounce;
 
@@ -1451,6 +1497,7 @@ export class EventGate {
       authorId: this.extractAuthorId(info.metadata) ?? undefined,
       serverId: info.serverId || undefined,
       addressed: Array.isArray(info.tags) && info.tags.includes('chat:addressed'),
+      routeChannelId: this.routeChannelFor(info),
     };
 
     const existing = this.debounceTimers.get(policy.name);
@@ -1514,7 +1561,10 @@ export class EventGate {
     if (referenced.length > 0) {
       const byChannel = new Map<string, { count: number; oldest: number; label?: string }>();
       for (const e of referenced) {
-        const key = e.channelId ?? '(unknown channel)';
+        // The registered id when known, so this line names the channel the
+        // same way routing notices and send tools do (a push event's own
+        // channelId is the adapter's raw id).
+        const key = e.routeChannelId ?? e.channelId ?? '(unknown channel)';
         const entry = byChannel.get(key) ?? { count: 0, oldest: e.timestamp, label: e.channelLabel };
         entry.count += 1;
         entry.oldest = Math.min(entry.oldest, e.timestamp);
@@ -1541,11 +1591,13 @@ export class EventGate {
       policies: policyNames,
     });
 
-    // Provenance of the batched wake (telemetry: who/where woke the agent):
-    // the newest ADDRESSED event first, else the newest event naming a
-    // channel or an author; channel + author + addressed from that ONE
-    // event. It does not set the turn's speech locus — the framework keeps
-    // its own routing rule for that.
+    // Provenance of the batched wake (who/where woke the agent): the newest
+    // ADDRESSED event first, else the newest event naming a channel or an
+    // author; channel + author + addressed from that ONE event. When that
+    // event addressed the agent and its registered channel is known,
+    // `routeChannelId` names the turn's speech locus too — the reply goes
+    // back to whoever addressed the agent, not to whichever channel last saw
+    // any traffic. Ambient-only batches carry telemetry only.
     const provenance = wakeProvenance(events);
     for (const agentName of this.getAgentNamesFn()) {
       this.requestInferenceFn(agentName, 'gate:debounce', 'gate', provenance);

package/src/index.ts

@@ -8,6 +8,7 @@ export { Agent } from './agent.js';
 export type { StartStreamResult } from './agent.js';
 export { ProcessQueueImpl } from './queue.js';
 export { ModuleRegistry } from './module-registry.js';
+export { ShutdownTimeoutError, DEFAULT_SHUTDOWN_TIMEOUT_MS } from './shutdown.js';
 export { formatZonedDateTime, formatZonedTime, isValidTimeZone, resolveTimeZone } from './timezone.js';
 export { REFUSAL_REACTIONS, REFUSAL_REACTION_FALLBACK, REFUSAL_REACTION_BASELINE } from './refusal-reactions.js';
 
@@ -91,7 +92,7 @@ export type { McplServerConfig } from './mcpl/index.js';
 // health probes, protocol harnesses — can dial an MCPL server exactly the
 // way the framework host does, over stdio or WebSocket)
 export { McplServerConnection } from './mcpl/index.js';
-export type { McplHostCapabilities } from './mcpl/index.js';
+export type { McplHostCapabilities, McplConnectionCloseInfo } from './mcpl/index.js';
 
 // MCPL tool lifecycle (RFC-007) and tool classes (RFC-008): the types a host
 // needs to write McplServerConfig.toolLifecycle policy and class tables, and
@@ -107,7 +108,9 @@ export type {
 } from './mcpl/index.js';
 
 // Per-channel conversation routing
+/** @deprecated Per-channel conversation routing is deprecated and will be removed (anima-research/agent-framework#235). */
 export { ConversationRouter, DEFAULT_CLOSURE_PROMPT } from './mcpl/index.js';
+/** @deprecated Per-channel conversation routing is deprecated and will be removed (anima-research/agent-framework#235). */
 export type {
   ConversationRouterConfig,
   ConversationBinding,
@@ -140,9 +143,22 @@ export type {
 } from './recovery/discord-awareness-outbox.js';
 // Live operator surgery (rollback / suppress) and its durable action log
 export { OperatorLog, OperatorActionError, defaultOperatorLogPath } from './operator-log.js';
-export type { OperatorLogEntry, OperatorLogInput, OperatorRequester } from './operator-log.js';
+export type {
+  OperatorLogEntry,
+  OperatorLogInput,
+  OperatorRequester,
+  SurgeryMarkerReceipt,
+} from './operator-log.js';
 export { createOfflineRecoveryBranch } from './recovery/offline-branch.js';
 export type {
   OfflineRecoveryBranchOptions,
   OfflineRecoveryBranchResult,
 } from './recovery/offline-branch.js';
+
+export * from "./tool-presentation.js";
+export {
+  SILENT_HEARTBEAT_SEPARATOR,
+  silentHeartbeatOf,
+  type SilentHeartbeatStamp,
+  type SilentHeartbeatTick,
+} from './silent-heartbeat.js';

package/src/mcpl/channel-registry.ts

@@ -37,7 +37,8 @@ import type { McplServerRegistry } from './server-registry.js';
 import type { FeatureSetManager } from './feature-set-manager.js';
 import type { ToolDefinition, ToolResult, ProcessEvent } from '../types/index.js';
 import { expandCoreTags } from './tags.js';
-import { validateCoalescedContent } from './push-coalescer.js';
+import { EmptyContentError, validateCoalescedContent } from './push-coalescer.js';
+import { isVisiblyEmptyContent } from './visible-content.js';
 import { CapabilityGrant } from './capability-grant.js';
 
 // ============================================================================
@@ -915,18 +916,38 @@ export class ChannelRegistry {
       // ACCEPTED from here down: semantic processing only for admitted
       // messages. §16.3 core-tag closure, then content conversion.
       const coalesced = message.coalesce !== undefined && !!this.handleCoalescedIncoming;
+      // Only a coalescing retraction may be empty (pure withdrawal, RFC-006
+      // §6; the coalescer appends nothing for it). Any other message that
+      // shows the model nothing would wake it with no visible cause.
+      const emptyAllowed = coalesced && (message.coalesce as { retract?: unknown } | null)?.retract === true;
+      const rejectEmpty = () => {
+        console.error(`[channel-incoming-rejected] server=${serverId} channel=${message.channelId} messageId=${message.messageId} reason=empty-content`);
+        this.emitTraceFn({
+          type: 'mcpl:channel-incoming-rejected',
+          serverId,
+          channelId: message.channelId,
+          messageId: message.messageId,
+          reason: 'empty-content',
+        });
+        results.push({ messageId: message.messageId, accepted: false, reason: 'empty_content' });
+      };
       if (coalesced) {
         // RFC-006 §13: malformed content on a coalesced item is that item's
         // failure, not the batch's — check the shape before converting.
         try {
-          validateCoalescedContent(message.content);
+          validateCoalescedContent(message.content, undefined, { allowEmpty: emptyAllowed });
         } catch (error) {
-          results.push({ messageId: message.messageId, accepted: false, reason: 'coalesce_invalid' });
+          if (error instanceof EmptyContentError) rejectEmpty();
+          else results.push({ messageId: message.messageId, accepted: false, reason: 'coalesce_invalid' });
           continue;
         }
       }
       if (message.tags) message.tags = expandCoreTags(message.tags);
       const convertedContent: ContentBlock[] = message.content.map(convertBlock);
+      if (!emptyAllowed && isVisiblyEmptyContent(convertedContent)) {
+        rejectEmpty();
+        continue;
+      }
 
       // Track default publish channel (most recent ACCEPTED incoming) —
       // deliberately after §14.5 validation: a rejected message from an

package/src/mcpl/conversation-router.ts

@@ -27,6 +27,11 @@
  * a restarted host must NOT reuse generation 1's agent name, or it would
  * reopen the previous engagement's Chronicle namespace and re-seed the
  * template context on top of the old history.
+ *
+ * DEPRECATED (anima-research/agent-framework#235): per-channel conversation
+ * routing is being retired. Behavior is unchanged for now; the framework
+ * logs one `[deprecated]` line when it is configured. Removal is a
+ * follow-up.
  */
 
 import type { ContextStrategy } from '@animalabs/context-manager';
@@ -49,6 +54,20 @@ export type TriggerRule = 'always' | 'mention';
  * inferring on every message of a four-human group DM is a firehose). */
 export type ChannelKind = 'dm' | 'groupDm' | 'channel';
 
+/** Logged once by the framework when `FrameworkConfig.conversations` is set. */
+export const CONVERSATION_ROUTING_DEPRECATION_NOTICE =
+  'Per-channel conversation routing (FrameworkConfig.conversations) is deprecated and will ' +
+  'be removed in a future release. Its \'mention\' bind/trigger rule reads ' +
+  'metadata.mentioned, which not every channel server sets (discord-mcpl does not), so on ' +
+  'such channels an @-mention neither binds a fork nor triggers a bound one. Routing still ' +
+  'works for now. See anima-research/agent-framework#235.';
+
+/**
+ * @deprecated Per-channel conversation routing is deprecated and will be
+ * removed (anima-research/agent-framework#235). Its 'mention' bind/trigger
+ * rule reads `metadata.mentioned`, which not every channel server sets.
+ * Behavior is unchanged for now.
+ */
 export interface ConversationRouterConfig {
   /** Agent whose context seeds new forks (the "trunk"/warm checkpoint). */
   templateAgent: string;
@@ -61,7 +80,15 @@ export interface ConversationRouterConfig {
    * Defaults: dm 'always', groupDm 'mention', channel 'mention'. */
   trigger?: { dm?: TriggerRule; groupDm?: TriggerRule; channel?: TriggerRule };
 
-  /** Idle time before a binding expires and the fork is closed. Default 12h. */
+  /**
+   * Idle time before a binding expires and the fork is closed. Default 12h.
+   *
+   * Expiry is checked at most about once a minute, so the sweep usually
+   * notices an expired binding up to ~60s after the TTL elapses. That is the
+   * usual extra delay, not a deadline for closing the fork: the closure turn
+   * can be delayed further (e.g. while the host is quiesced, it stays queued
+   * until resume).
+   */
   idleTtlMs?: number;
 
   /** Final system-initiated user message sent to a fork on expiry. */
@@ -116,6 +143,12 @@ export const DEFAULT_CLOSURE_PROMPT =
 // ConversationRouter
 // ============================================================================
 
+/**
+ * @deprecated Per-channel conversation routing is deprecated and will be
+ * removed (anima-research/agent-framework#235). Behavior is unchanged for
+ * now; the framework logs one `[deprecated]` line when it constructs a
+ * router from `FrameworkConfig.conversations`.
+ */
 export class ConversationRouter {
   private config: ConversationRouterConfig;
 

package/src/mcpl/feature-set-manager.ts

@@ -128,6 +128,16 @@ export class FeatureSetManager {
   /** Per-server state, keyed by server ID. */
   private servers = new Map<string, ServerState>();
 
+  /**
+   * @param emitTrace Receives an `mcpl:feature-set-disabled` trace beside
+   *   each §6.4 disablement's console line, so hosts that keep per-server
+   *   logs from the trace bus see a set that config enabled but derivation
+   *   turned off. Omit for scratch derivations (nothing is installed).
+   */
+  constructor(
+    private readonly emitTrace?: (event: { type: string; [key: string]: unknown }) => void,
+  ) {}
+
   /**
    * Initialize a server's feature set state from its capabilities and host config.
    *
@@ -201,28 +211,43 @@ export class FeatureSetManager {
     // resolution so it can only remove: nothing a declaration or a config
     // says can supply a capability the grant lacks.
     if (grant) {
+      // Named only when the operator listed it: with enabledFeatureSets
+      // omitted every declared set is selected, which is no surprise.
+      const explicitSelection = config?.enabledFeatureSets !== undefined;
+      const disable = (
+        name: string,
+        reason: 'invalid_uses' | 'missing_capabilities',
+        detail: string,
+        extra: { unrecognized?: string[]; missing?: string[] },
+      ): void => {
+        const selectedByConfig = state.enabled.delete(name);
+        const note = explicitSelection && selectedByConfig ? ' — overrides enabledFeatureSets' : '';
+        console.error(`[mcpl] ${serverId}/${name} disabled: ${detail}${note}`);
+        this.emitTrace?.({
+          type: 'mcpl:feature-set-disabled',
+          serverId,
+          featureSet: name,
+          reason,
+          selectedByConfig,
+          ...extra,
+        });
+      };
       for (const [name, decl] of Object.entries(declared)) {
         const uses = (decl as { uses?: unknown }).uses;
         if (!Array.isArray(uses) || uses.length === 0) {
-          if (state.enabled.delete(name) || true) {
-            console.error(`[mcpl] ${serverId}/${name} disabled: invalid_uses (§6.4 — uses absent or empty)`);
-          }
+          disable(name, 'invalid_uses', 'invalid_uses (§6.4 — uses absent or empty)', { unrecognized: [] });
           continue;
         }
         const unknown = uses.filter((u) => typeof u !== 'string' || !isKnownCapabilityPath(u));
         if (unknown.length > 0) {
-          state.enabled.delete(name);
-          console.error(
-            `[mcpl] ${serverId}/${name} disabled: invalid_uses (§6.4 — unrecognized: ${unknown.join(', ')})`,
-          );
+          disable(name, 'invalid_uses', `invalid_uses (§6.4 — unrecognized: ${unknown.join(', ')})`, {
+            unrecognized: unknown.map((u) => (typeof u === 'string' ? u : JSON.stringify(u))),
+          });
           continue;
         }
         const missing = (uses as string[]).filter((u) => !grant.has(u));
         if (missing.length > 0) {
-          state.enabled.delete(name);
-          console.error(
-            `[mcpl] ${serverId}/${name} disabled: missing capabilities ${missing.join(', ')} (§6.4)`,
-          );
+          disable(name, 'missing_capabilities', `missing capabilities ${missing.join(', ')} (§6.4)`, { missing });
         }
       }
     }

package/src/mcpl/index.ts

@@ -107,6 +107,8 @@ export {
 
 // Server connection and registry
 export { McplServerConnection } from './server-connection.js';
+export type { McplConnectionCloseInfo } from './server-connection.js';
+export type { TransportCloseInfo } from './transport.js';
 export { McplServerRegistry, type McplCapabilityQuery } from './server-registry.js';
 
 // Feature set management (permission layer)
@@ -158,7 +160,9 @@ export { InferenceRouter } from './inference-router.js';
 export { ChannelRegistry } from './channel-registry.js';
 
 // Per-channel conversation routing (fork-per-channel agents)
+/** @deprecated Per-channel conversation routing is deprecated and will be removed (anima-research/agent-framework#235). */
 export { ConversationRouter, DEFAULT_CLOSURE_PROMPT } from './conversation-router.js';
+/** @deprecated Per-channel conversation routing is deprecated and will be removed (anima-research/agent-framework#235). */
 export type {
   ConversationRouterConfig,
   ConversationBinding,

package/src/mcpl/prose-stream-router.ts

@@ -19,8 +19,13 @@
  * emits NOTHING — the delivery path will bounce/retain it; a stream consumer
  * must never see text that delivery would refuse to send.
  *
- * Two modes, mirroring proseRouting:
- *  - explicit: parse `>>` prefixes; initial target null (suppressed).
+ * Three modes, mirroring proseRouting:
+ *  - explicit: parse `>>` prefixes. A fresh turn's stream starts suppressed;
+ *              one that resumes a turn starts at the turn's destination, and
+ *              each round's end returns the stream to it (retarget).
+ *  - hybrid:   parse `>>>` envelopes, with the frozen turn locus as the
+ *              fallback. An envelope with no target, or `>>>skip_reply`,
+ *              holds back what follows until a later `>>>` names a target.
  *  - locus:    NO prefix parsing (locus mode's `>>` lines are plain text);
  *              everything streams to the frozen turn locus.
  */
@@ -30,7 +35,10 @@ export interface RoutedDelta {
   delta: string;
 }
 
-type State = 'line-start' | 'hybrid-indent' | 'maybe-prefix' | 'prefix-gap' | 'prefix-token' | 'after-token' | 'body';
+type State = 'line-start' | 'indent' | 'maybe-prefix' | 'prefix-gap' | 'prefix-token' | 'after-token' | 'body';
+
+/** Whitespace as the delivery path reads it (`trimStart()`, `\s`, `\S`). */
+const isSpace = (ch: string): boolean => /\s/.test(ch);
 
 export class ProseStreamRouter {
   private target: string | null;
@@ -44,7 +52,9 @@ export class ProseStreamRouter {
     private opts: {
       /** explicit parses `>>`; hybrid parses `>>>` while retaining locus fallback. */
       mode: 'explicit' | 'hybrid' | 'locus';
-      /** Initial destination: the frozen turn locus (locus mode) or null. */
+      /** Initial destination: the frozen turn locus (locus and hybrid mode); in
+       *  explicit mode, null on a fresh turn, or the turn's destination on a
+       *  stream that resumes one. */
       initialTarget: string | null;
       /** Resolve a `>>spec` to a channelId, or null (unresolved/ambiguous). */
       resolve: (spec: string) => string | null;
@@ -59,6 +69,17 @@ export class ProseStreamRouter {
     return this.accumulated;
   }
 
+  /**
+   * Point the stream at a destination decided outside it. Explicit mode does
+   * this at each round's end, with the turn's destination: a private round's
+   * prefixes, a `>>skip_reply` envelope and a target that didn't resolve all
+   * leave that destination as it was, though the stream followed them while
+   * the round was written.
+   */
+  retarget(target: string | null): void {
+    this.target = target;
+  }
+
   /**
    * Drop everything routed so far and return to the constructed state.
    *
@@ -82,23 +103,38 @@ export class ProseStreamRouter {
     return coalesce(out);
   }
 
-  /** End of stream: flush any held line-start text (it can no longer become a
-   *  complete prefix; an unterminated `>>tok` at EOF is routing metadata with
-   *  no body — dropped, matching delivery which would deliver empty body). */
-  finish(): RoutedDelta[] {
+  /**
+   * The end of a segment: one round's text, which delivery parses on its
+   * own. The pending line's decision is made now. Held line-start text can
+   * no longer become a prefix, so it is body. A prefix whose target is
+   * written but has no body takes effect, as delivery reads `>>#chan` with
+   * nothing after it. The next segment starts a new line.
+   */
+  endSegment(): RoutedDelta[] {
     const out: RoutedDelta[] = [];
-    if (this.state === 'hybrid-indent') this.emit(this.held, out);
+    if (this.state === 'indent') this.emit(this.held, out);
     if (this.state === 'maybe-prefix') {
-      const full = this.opts.mode === 'hybrid' ? '>>>' : '>>';
-      const arrows = this.opts.mode === 'hybrid' ? this.held.trimStart() : this.held;
-      if (arrows !== full) this.emit(this.held, out);
+      // Hybrid's `>>>` with nothing after it is an envelope with no target:
+      // delivery bounces it and holds back what follows. Anything else held
+      // is text to delivery, explicit's bare `>>` included.
+      const arrows = this.held.trimStart();
+      if (this.opts.mode === 'hybrid' && arrows === '>>>') this.target = null;
+      else this.emit(this.held, out);
     }
-    // prefix-token / after-token at EOF: prefix without body — nothing to emit.
+    // Hybrid's `>>>` and a gap with nothing after it: no target either.
+    if (this.state === 'prefix-gap') this.target = null;
+    if (this.state === 'prefix-token') this.applyTarget();
     this.held = '';
-    this.state = 'line-start';
+    this.token = '';
+    if (this.opts.mode !== 'locus') this.state = 'line-start';
     return coalesce(out);
   }
 
+  /** End of stream: the last segment ends. */
+  finish(): RoutedDelta[] {
+    return this.endSegment();
+  }
+
   private step(ch: string, out: RoutedDelta[]): void {
     switch (this.state) {
       case 'body':
@@ -111,8 +147,11 @@ export class ProseStreamRouter {
         return;
 
       case 'line-start':
-        if (this.opts.mode === 'hybrid' && (ch === ' ' || ch === '\t')) {
-          this.state = 'hybrid-indent';
+        // Indentation before a prefix is held until the line's decision: the
+        // delivery path reads an indented `>>` (explicit) or `>>>` (hybrid)
+        // line as a prefix too, after any leading whitespace.
+        if (ch !== '\n' && isSpace(ch)) {
+          this.state = 'indent';
           this.held = ch;
           return;
         }
@@ -121,8 +160,8 @@ export class ProseStreamRouter {
         this.step(ch, out);
         return;
 
-      case 'hybrid-indent':
-        if (ch === ' ' || ch === '\t') { this.held += ch; return; }
+      case 'indent':
+        if (ch !== '\n' && isSpace(ch)) { this.held += ch; return; }
         if (ch === '>') { this.held += ch; this.state = 'maybe-prefix'; return; }
         this.emit(this.held, out);
         this.held = '';
@@ -132,7 +171,7 @@ export class ProseStreamRouter {
 
       case 'maybe-prefix': {
         const prefix = this.opts.mode === 'hybrid' ? '>>>' : '>>';
-        const arrows = this.opts.mode === 'hybrid' ? this.held.trimStart() : this.held;
+        const arrows = this.held.trimStart();
         if (ch === '>' && arrows.length < prefix.length) {
           this.held += '>';
           return;
@@ -143,11 +182,22 @@ export class ProseStreamRouter {
             this.state = 'prefix-gap';
             return;
           }
-          if (ch === '\n' || ch === ' ' || ch === '\t') {
-            if (this.opts.mode === 'explicit') this.emit(this.held, out);
+          if (isSpace(ch)) {
+            if (this.opts.mode === 'explicit') {
+              // `>>` and then whitespace is a quoted arrow: body text, since
+              // delivery's prefix needs a target right after the arrows.
+              this.emit(this.held, out);
+            } else {
+              // `>>>` and then whitespace other than a space or tab (a
+              // newline included) is an envelope with no target. Delivery
+              // bounces it and holds back what follows until a later `>>>`
+              // names a target.
+              this.target = null;
+            }
+            // The whitespace itself is body, a newline included.
             this.held = '';
-            this.state = ch === '\n' ? 'line-start' : 'body';
-            if (ch !== '\n') this.step(ch, out);
+            this.state = 'body';
+            this.step(ch, out);
             return;
           }
           this.state = 'prefix-token';
@@ -165,6 +215,9 @@ export class ProseStreamRouter {
       case 'prefix-gap':
         if (ch === ' ' || ch === '\t') return;
         if (ch === '\n') { this.target = null; this.state = 'line-start'; return; }
+        // Other whitespace can't start hybrid's target (`[ \t]*\S+`): an
+        // envelope with no target, as above.
+        if (isSpace(ch)) { this.target = null; this.state = 'body'; return; }
         this.state = 'prefix-token';
         this.token = ch;
         return;
@@ -172,6 +225,9 @@ export class ProseStreamRouter {
       case 'prefix-token':
         if (ch === ' ' || ch === '\t') { this.applyTarget(); this.state = 'after-token'; this.sawBang = false; return; }
         if (ch === '\n') { this.applyTarget(); this.state = 'line-start'; return; }
+        // Any other whitespace ends the token too (`\S+`), and starts the
+        // body: the grammar's gap after a token is spaces and tabs only.
+        if (isSpace(ch)) { this.applyTarget(); this.state = 'body'; this.step(ch, out); return; }
         this.token += ch;
         return;