@parall/parel-channel 1.51.0 → 1.52.0

package/src/inbound.ts

@@ -7,6 +7,13 @@ import type {
 } from '@parel/plugin-sdk';
 import { channelCapabilityEnv } from './channel-capability.js';
 import { buildChatPrompt, type PromptAttachment } from './channel-prompt.js';
+import {
+  armCatchUpEffect,
+  beginCatchUp,
+  CATCHUP_TIMER_KEY,
+  deferToCatchUp,
+  runCatchUpRound,
+} from './catchup.js';
 import { parallApiUrl, parallOrgId, requireAgk, sandboxEnabled } from './connect.js';
 import { effectsForChannelDispatch, PROVIDER_LOOKUP_TIMEOUT_MS } from './inbound-channel.js';
 import {
@@ -33,7 +40,6 @@ import {
   completeSourceEffect,
   conversationKey,
   createErrorStep,
-  fetchMainSessionFresh,
   createInputStep,
   createTraceStep,
   createTypedInputStep,
@@ -47,7 +53,6 @@ import {
   readActiveEmit,
   reportingEnabled,
   REQUEST_TIMEOUT_MS,
-  SESSION_CACHE_KEY,
   TURN_ENVELOPE_KEY,
   writeActiveEmit,
 } from './session.js';
@@ -65,10 +70,10 @@ import { isTypedEventType, planTypedDispatch } from './typed-dispatch.js';
  * (broad-cover / no_action), the ledger lifecycle the chat activity
  * indicator rides on (parel-reply-contract-alignment.md; the old ack-on-emit
  * killed the indicator at turn start). Redelivery protection is the
- * per-source attempt fence in the durable store: on (re)connect, onOpen
- * sweeps `GET /dispatch` (the WS push has no replay), skips rows whose fence
- * is younger than EMIT_TTL_MS, and re-emits stale ones under a fresh
- * attempt-suffixed envelope id. FORK paths (deliverTo/spawn) keep their own
+ * per-source attempt fence in the durable store: the timer-driven catch-up
+ * job (catchup.ts — onOpen only arms it; the WS push has no replay) lists
+ * `GET /dispatch`, skips rows whose fence is younger than EMIT_TTL_MS, and
+ * re-emits stale ones under a fresh attempt-suffixed envelope id. FORK paths (deliverTo/spawn) keep their own
  * ack machinery — the pending ack doubles as spawn-failure recovery there —
  * so fork-handled rows still resolve as legacy_ack (indicator parity for
  * forked turns is a design follow-up, parel-reply-contract-alignment.md §6).
@@ -103,38 +108,32 @@ interface DispatchData {
 }
 
 /**
- * Connection-local hook serialization. The parel ConnectorHost dispatches
- * socket callbacks fire-and-forget (verified against connector-host.ts:
- * `onMessage: (data) => { this.handleMessage(data).catch(…) }`), so two
- * frames' async handling can interleave at await points inside one DO
- * isolate. Every read-then-write protocol here — the turnEnvelope marker,
+ * Connection-keyed hook serialization — a v1-host compatibility shim. The v1
+ * ConnectorHost dispatches socket callbacks fire-and-forget (verified against
+ * connector-host.ts: `onMessage: (data) => { this.handleMessage(data).catch(…) }`),
+ * so two frames' async handling can interleave at await points inside one
+ * isolate, and every read-then-write protocol here — the turnEnvelope marker,
  * fork planForkDecision→recordSpawn, pendingAck parking — assumes serial
- * execution, so ALL hook bodies run through this one promise chain. Same
- * connection ⇒ same DO isolate ⇒ same module instance, so a module-level
- * chain is exactly connection-scoped TODAY — if parel ever pools multiple
- * connections into one isolate, key this chain on ctx.connectionId before
- * anything else (cross-connection head-of-line blocking would be silent).
- * Failures don't break the chain.
+ * execution. Under the v2 execution model the HOST owns serialization (I1:
+ * one in-flight hook per connection, durable hook queue) and this chain is
+ * permanently length ≤1; it must stay until every connection runs v2
+ * (executionModelV2 flag), because deleting it on a v1 connection re-exposes
+ * the store read-modify-write races. Keyed by connectionId (not module
+ * global) so a pooled-isolate host can never cross-serialize two
+ * connections — the map is bounded by the isolate's connection count and is
+ * a discardable cache like every module global (v2 I4: correctness lives in
+ * host serialization + ctx.store). Failures don't break a chain.
  */
-let hookChain: Promise<unknown> = Promise.resolve();
-let chainConnectionId: string | undefined;
-/** Surface a violated isolation assumption as a log line, not silent
- * mis-serialization (see the chain doc above). */
-export function assertChainConnection(ctx: ConnectorContext): void {
-  if (chainConnectionId === undefined) {
-    chainConnectionId = ctx.connectionId;
-  } else if (chainConnectionId !== ctx.connectionId) {
-    console.warn(
-      `[parel-channel] hook chain saw a second connection (${chainConnectionId} → ${ctx.connectionId}) — the one-connection-per-isolate assumption broke; key the chain on connectionId`,
-    );
-    chainConnectionId = ctx.connectionId;
-  }
-}
-export function serialized<T>(fn: () => Promise<T>): Promise<T> {
-  const next = hookChain.then(fn, fn);
-  hookChain = next.then(
-    () => undefined,
-    () => undefined,
+const hookChains = new Map<string, Promise<unknown>>();
+export function serialized<T>(ctx: ConnectorContext, fn: () => Promise<T>): Promise<T> {
+  const chain = hookChains.get(ctx.connectionId) ?? Promise.resolve();
+  const next = chain.then(fn, fn);
+  hookChains.set(
+    ctx.connectionId,
+    next.then(
+      () => undefined,
+      () => undefined,
+    ),
   );
   return next;
 }
@@ -143,8 +142,7 @@ export function handleParallFrame(
   frame: WebSocketFrame,
   ctx: ConnectorContext,
 ): Promise<ConnectorEffect[]> {
-  assertChainConnection(ctx);
-  return serialized(() => handleParallFrameInner(frame, ctx));
+  return serialized(ctx, () => handleParallFrameInner(frame, ctx));
 }
 
 async function handleParallFrameInner(
@@ -175,34 +173,51 @@ async function handleParallFrameInner(
     return [];
   }
   if (event.type !== 'dispatch.new' || !event.data) return [];
+  // FIFO gate: while the incremental catch-up job is draining backlog, a live
+  // frame must not leapfrog it into the shared main session (cross-ordering
+  // would scramble session input order exactly like concurrent replay). The
+  // dispatch row is already durable server-side — deferToCatchUp marks the
+  // pass dirty (so the job's next from-the-top pass lists the row even when
+  // its cursor already moved past it — a redrive hint must survive being
+  // consumed here) and the re-arm doubles as the lost-timer self-heal: any
+  // live frame revives a stalled sweep.
+  const deferDelay = await deferToCatchUp(ctx);
+  if (deferDelay !== null) {
+    return [armCatchUpEffect(ctx, deferDelay)];
+  }
   try {
     return await effectsForDispatch(event.data, ctx);
   } catch (err) {
     // A transient fetch failure on one frame must not fail the frame handler —
-    // the dispatch stays pending and the onOpen sweep replays it on reconnect.
+    // the dispatch stays pending and the catch-up job replays it on reconnect.
     console.error('[parel-channel] dispatch handling failed', err);
     return [];
   }
 }
 
 /**
- * Fork retry timers (armed by child_spawn_failed): re-plan the stranded
+ * Timers: the incremental catch-up job's rounds (catchup.ts) and fork retry
+ * timers (armed by child_spawn_failed) — the latter re-plan the stranded
  * message through the normal dispatch pipeline. onTimer returns the FULL
- * effect union (unlike onAgentEvent), so the re-plan can emit/spawn/ack.
- * The parked row is cleared first — a re-plan that fails transiently leaves
- * the WorkItem in `received` for the reconnect sweep, same as any dispatch.
+ * effect union (unlike onAgentEvent), so both can emit/spawn/ack.
+ * The parked fork row is cleared first — a re-plan that fails transiently
+ * leaves the WorkItem in `received` for the catch-up job, same as any
+ * dispatch.
  */
 export function handleParallTimer(
   timer: { key: string },
   ctx: ConnectorContext,
 ): Promise<ConnectorEffect[]> {
-  return serialized(() => handleParallTimerInner(timer, ctx));
+  return serialized(ctx, () => handleParallTimerInner(timer, ctx));
 }
 
 async function handleParallTimerInner(
   timer: { key: string },
   ctx: ConnectorContext,
 ): Promise<ConnectorEffect[]> {
+  if (timer.key === CATCHUP_TIMER_KEY) {
+    return runCatchUpRound(ctx, (data) => effectsForDispatch(data, ctx));
+  }
   if (!timer.key.startsWith(FORK_RETRY_PREFIX)) return [];
   const parked = (await ctx.store?.get(timer.key).catch(() => null)) as DispatchData | null;
   if (!parked?.source_id) return [];
@@ -222,109 +237,26 @@ async function handleParallTimerInner(
     if (!rearmed) await ctx.store?.delete(timer.key).catch(() => {});
     return effects;
   } catch (err) {
+    // Transient re-plan failure (source fetch now throws on 5xx): drop the
+    // parked row like any non-rearmed outcome — the WorkItem stays received
+    // and the catch-up TTL re-emit self-heals, same as before the
+    // transient-throw contract.
     console.error('[parel-channel] fork retry re-plan failed', err);
+    await ctx.store?.delete(timer.key).catch(() => {});
     return [];
   }
 }
 
 /**
- * Sweep pending dispatches on (re)connect — the live WS push has no replay.
- * Paginates with the server cursor so a long outage's backlog is not silently
- * truncated (bounded to keep a pathological backlog from wedging onOpen; the
- * remainder is picked up on the next reconnect sweep).
+ * onOpen: O(1) by the v2 lifecycle contract (I4 — the 15s onOpen budget
+ * cannot hold an O(backlog) sweep, and under first-timeout-terminal a slow
+ * onOpen is an epoch-rotation storm). Resets the incremental catch-up job
+ * and arms its timer; all sweeping — the New Session generation check
+ * included — happens in bounded onTimer rounds (catchup.ts). The live WS
+ * push still has no replay: the job is the only redelivery path.
  */
-export function catchUpParall(ctx: ConnectorContext): Promise<ConnectorEffect[]> {
-  return serialized(() => catchUpParallInner(ctx));
-}
-
-async function catchUpParallInner(ctx: ConnectorContext): Promise<ConnectorEffect[]> {
-  // New Session generation check (must run before any dispatch replay): the
-  // `agent.new_session` WS push is not replayed, so a reset that happened
-  // while this connection was down would leave stale fork routing behind —
-  // post-reset messages would land in pre-reset children. The main ase_ IS
-  // the generation: New Session closes it and the next get-or-create mints a
-  // fresh id, so compare the cached id against the server's current one and
-  // purge fork state on rotation. Every missed-event scenario passes through
-  // onOpen (a live socket delivers the event; a dead one reconnects here).
-  // The cached id is never dropped before the fresh (bypass-cache) read
-  // succeeds — it is the only generation token, and losing it to a transient
-  // /sessions failure would silently skip the purge until the fork TTLs
-  // expire.
-  try {
-    const cachedMain = (await ctx.store?.get(SESSION_CACHE_KEY).catch(() => null)) as string | null;
-    if (cachedMain) {
-      const freshMain = await fetchMainSessionFresh(ctx);
-      if (freshMain && freshMain !== cachedMain) {
-        const refs = await clearForkState(ctx);
-        for (const ref of refs) {
-          await invalidateChildSession(ctx, ref);
-        }
-        console.warn('[parel-channel] main session rotated while offline — fork state purged');
-      }
-    }
-    // Capability revalidation: a parked forkDisabled latch reflects the
-    // binding shape at failure time; the fleet sweep converges bindings
-    // without restarting the connection, so a reconnect is the natural
-    // revalidation point. If forking is truly still disabled, the first
-    // spawn attempt re-parks the latch at the cost of one failed effect.
-    await ctx.store?.delete('forkDisabled').catch(() => {});
-  } catch (err) {
-    console.error('[parel-channel] new-session generation check failed', err);
-  }
-  const effects: ConnectorEffect[] = [];
-  try {
-    const apiUrl = parallApiUrl(ctx);
-    const agk = requireAgk(ctx);
-    const orgId = parallOrgId(ctx);
-    let cursor = '';
-    // Page bound is a wedge guard, not a coverage target. Unknown dispatch
-    // types stay pending (deliberately — see effectsForDispatch) and the
-    // list is FIFO, so the bound must comfortably exceed any realistic
-    // unsupported backlog or old rows could starve newer DMs out of the sweep.
-    // 40 pages ≈ 2000 dispatches per sweep; log when we hit the ceiling so a
-    // pathological backlog is visible instead of silent.
-    const maxPages = 40;
-    let page = 0;
-    for (; page < maxPages; page++) {
-      const url = `${apiUrl}/api/v1/orgs/${orgId}/dispatch?limit=50${cursor ? `&cursor=${encodeURIComponent(cursor)}` : ''}`;
-      const res = await fetch(url, {
-        headers: { Authorization: `Bearer ${agk}` },
-        signal: AbortSignal.timeout(10_000),
-      });
-      if (!res.ok) break;
-      const body = (await res.json().catch(() => null)) as {
-        data?: DispatchData[];
-        next_cursor?: string;
-      } | null;
-      // ALL dispatches replay SEQUENTIALLY, in page order (FIFO): every
-      // envelope feeds the agent's one main session, so cross-chat replay
-      // concurrency would scramble the session's input order AND race the
-      // agent-global turnEnvelope marker (a slower old dispatch could
-      // overwrite a newer one's marker and mis-arm the done-signal guard).
-      // Reconnect backlogs are small; serialization is the correctness
-      // posture, not a throughput concern. A failed dispatch resolves to []
-      // and stays pending for the next sweep.
-      for (const d of body?.data ?? []) {
-        const out = await effectsForDispatch(d, ctx).catch((err) => {
-          console.error('[parel-channel] catch-up dispatch failed', err);
-          return [] as ConnectorEffect[];
-        });
-        effects.push(...out);
-      }
-      if (!body?.next_cursor) break;
-      cursor = body.next_cursor;
-    }
-    if (page === maxPages) {
-      console.warn(
-        '[parel-channel] catch-up hit the page ceiling; remainder deferred to the next reconnect sweep',
-      );
-    }
-  } catch (err) {
-    // Catch-up is best-effort: keep whatever pages completed and never fail
-    // the connection open over it.
-    console.error('[parel-channel] dispatch catch-up failed', err);
-  }
-  return effects;
+export function handleParallOpen(ctx: ConnectorContext): Promise<ConnectorEffect[]> {
+  return serialized(ctx, () => beginCatchUp(ctx));
 }
 
 /**
@@ -406,15 +338,18 @@ async function effectsForDispatch(
   // Pull the source message text (global by-id read; ACL = chat membership).
   const m = await fetch(`${apiUrl}/api/v1/messages/${sourceId}`, {
     headers: { Authorization: `Bearer ${agk}` },
-    signal: AbortSignal.timeout(10_000),
+    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
   });
   if (!m.ok) {
     if (m.status === 404 || m.status === 403) {
       // Deleted message / lost chat access — permanently unusable, drop it.
       return [completeSourceEffect(ctx, sourceType, sourceId)];
     }
-    // Transient failure: keep pending, the catch-up sweep retries.
-    return [];
+    // Transient failure: keep pending — and THROW rather than return [], so
+    // the catch-up job can tell a starving row from a deliberately-pending
+    // one and re-arm with backoff (the live frame path catches at
+    // handleParallFrameInner; same visible outcome there).
+    throw new Error(`transient message fetch failure (${m.status})`);
   }
   const msg = (await m.json().catch(() => null)) as {
     content?: { text?: string };
@@ -450,11 +385,11 @@ async function effectsForDispatch(
   // Frame the message with its chat of origin: all chats share the agent's
   // one main session, so the model must see WHERE each message comes from or
   // it answers chat B inside chat A's train of thought. The name is cosmetic
-  // garnish and must never block the emit/ack hot path (the catch-up sweep is
-  // fully serialized — one slow lookup would stall the whole backlog): only
-  // the cached name is used, and a miss kicks off a fire-and-forget prefetch
-  // so the NEXT message from this chat gets the name. The id alone already
-  // marks the context switch.
+  // garnish resolved inline under the tight miss-path timeout (cached
+  // per-chat afterward; a degraded lookup frames id-only — the id alone
+  // already marks the context switch). See cachedChatName for why inline:
+  // the v2 capture window drops post-hook store writes, so a background
+  // prefetch could never persist its cache row.
   const chatName = await cachedChatName(ctx, chatId);
   const senderId = msg?.sender_id ? String(msg.sender_id) : undefined;
   const framedText = buildChatPrompt({
@@ -547,11 +482,21 @@ async function effectsForDispatch(
           messageId: sourceId,
           senderId,
           text: stepText,
+          threadRootId,
         }),
       ]);
       // A closed child ase_ (New Session closed the whole family) just drops
       // the cache; the next event rebuilds it.
-      if (results.includes('stale')) await invalidateChildSession(ctx, decision.childRef);
+      if (results.includes('stale')) {
+        await invalidateChildSession(ctx, decision.childRef);
+      } else {
+        // Child turns get the same message↔session linking as main: the CLI
+        // reads PRLL_SESSION_ID into its sends' agent_session_id, and the
+        // childEnvelope below shares this context object. A stale childAse
+        // must never be stamped — attribution must not point at a closed
+        // session (same rule as the main path's repair branch).
+        invocationContext.PRLL_SESSION_ID = childAse;
+      }
     }
     await receivedSettled;
     const childEnvelope = {
@@ -654,19 +599,21 @@ async function effectsForDispatch(
             messageId: sourceId,
             senderId,
             text: stepText,
+            threadRootId,
           }),
         ]);
         if (results.includes('stale')) await invalidateChildSession(ctx, decision.childRef);
       }
       await recordSpawn(ctx, subject, decision.childRef, { dispatchId, sourceId });
       await receivedSettled;
-      // Known gap: SpawnChildSessionEffect (#140) carries no invocation
-      // context, so the fork's OPENING turn runs without the capability env
-      // (lark-cli workspace ops would need a follow-up turn — those arrive
-      // as deliverTo envelopes, which inherit the full context). Channel
-      // replies are unaffected: channel_message dispatches always ride main.
-      // Fix belongs parel-side (context on spawnChildSession) — tracked as a
-      // parel ask.
+      // Known gap: SpawnChildSessionEffect (plugin-sdk 0.12) carries no
+      // invocation context, so the fork's OPENING turn runs without the
+      // capability env (lark-cli workspace ops would need a follow-up turn)
+      // AND without PRLL_SESSION_ID (its reply links via dispatch provenance
+      // instead) — deliverTo follow-ups inherit the full context, including
+      // the session stamp. Channel replies are unaffected: channel_message
+      // dispatches always ride main. Fix belongs parel-side (context on
+      // spawnChildSession) — tracked as a parel ask.
       return [
         {
           type: 'spawnChildSession',
@@ -712,32 +659,45 @@ async function effectsForDispatch(
           messageId: sourceId,
           senderId,
           text: stepText,
+          threadRootId,
         }),
       ]);
     const results = await report(sessionId);
     if (results.includes('stale')) {
       // The cached session was closed under us (e.g. New Session). The
       // get-or-create falls through terminal rows, so one rebuild + retry
-      // repairs reporting for this and every later dispatch.
+      // repairs reporting for this and every later dispatch. Attribution
+      // (PRLL_SESSION_ID + the fence) must never keep pointing at the closed
+      // session — clear it, and restore only from a successful fresh report.
       await invalidateSession(ctx);
+      sessionId = null;
       const fresh = await ensureSession(ctx);
-      if (fresh && fresh !== sessionId) {
-        await report(fresh);
-        sessionId = fresh;
+      if (fresh) {
+        const retry = await report(fresh);
+        if (!retry.includes('stale')) sessionId = fresh;
       }
     }
   }
+  // The CLI reads PRLL_SESSION_ID into the send's agent_session_id, giving
+  // the reply message its ase_ provenance (message ↔ session linking; the
+  // server validates ownership). Injected after the session resolves — the
+  // envelope's context object is still ours until the emit effect returns.
+  if (sessionId) {
+    invocationContext.PRLL_SESSION_ID = sessionId;
+  }
   await receivedSettled;
   // Arm the attempt fence BEFORE the emit effect is returned: turn events
   // complete a source only while `active:{source}` matches their envelope id
   // exactly, and the redelivery-skip window starts at this timestamp. Only
   // the main path writes it — fork paths keep their own ack machinery.
+  // The fence also carries this attempt's session (attribution for the
+  // turn-end ledger close — see ActiveEmit).
   // Deliberate ordering tradeoff: a crash between this write and the host
   // executing the emit leaves an armed fence for an un-emitted source, so
   // the reconnect sweep hides it until the TTL re-emit (≤30min delay). The
   // reverse order (fence after emit) would instead double-emit on a crash —
   // a duplicate agent turn. Delay heals; duplicates don't.
-  await writeActiveEmit(ctx, sourceType, sourceId, envelopeId);
+  await writeActiveEmit(ctx, sourceType, sourceId, envelopeId, sessionId ?? undefined);
 
   // No ack effect: the row stays 'received' until the reply (dispatch
   // _source) or the turn event (complete-sources) resolves it — the
@@ -859,55 +819,57 @@ async function effectsForTypedDispatch(
 
 /**
  * How long a cached chat name is served without revalidation. Chat renames
- * are rare and the frame is the model's cross-chat context anchor, so serve
- * stale-while-revalidate: past the TTL the cached name is still returned
- * immediately (never block the hot path) and a background refresh updates
- * the row for later messages.
+ * are rare and the frame is the model's cross-chat context anchor, so past
+ * the TTL the row is refreshed inline (bounded) and the old name serves as
+ * the fallback when the refresh degrades.
  */
 const CHAT_NAME_TTL_MS = 60 * 60 * 1000;
 
 /**
- * chat id → display name for prompt framing, NON-BLOCKING: returns only what
- * the durable store already holds; a miss fires a background prefetch (tight
- * timeout, any failure ignored) so later messages get the name. The first
- * message from a chat is framed id-only — acceptable, the id is the
- * correctness anchor and the name is garnish; a blocking lookup here would
- * sit on the emit/ack hot path and stall the fully-serialized catch-up sweep
- * one dispatch at a time. DMs have no name — the empty name is cached as a
- * "resolved, nameless" sentinel so they don't re-prefetch on every message.
- * Rows carry the fetch timestamp; past CHAT_NAME_TTL_MS the stale name is
- * served AND revalidated in the background, so a renamed chat converges
- * within one TTL window. (Pre-TTL rows were plain strings — served once and
- * upgraded by the same background refresh.)
+ * chat id → display name for prompt framing. Resolved INLINE on a miss or a
+ * TTL-stale row, under the tight miss-path timeout (3s): the v2 capture
+ * window drops any store write landing after the hook returns, so the old
+ * fire-and-forget prefetch would never persist its cache row — every message
+ * would re-prefetch and the name would never appear. Inline is bounded and
+ * self-limiting (per-chat cached after the first resolve; the catch-up job's
+ * round budget accounts for cold items). Failures degrade: a miss frames
+ * id-only (the id is the correctness anchor, the name is garnish), a stale
+ * row serves the old name. DMs have no name — the empty name is cached as a
+ * "resolved, nameless" sentinel so they don't re-fetch on every message.
+ * (Pre-TTL rows were plain strings — served once and upgraded by the same
+ * inline refresh.)
  */
 async function cachedChatName(ctx: ConnectorContext, chatId: string): Promise<string | undefined> {
   const cacheKey = `chatName:${chatId}`;
   const cached = await ctx.store?.get(cacheKey).catch(() => null);
+  let staleName: string | undefined;
   if (
     cached &&
     typeof cached === 'object' &&
     typeof (cached as { name?: unknown }).name === 'string'
   ) {
     const { name, at } = cached as { name: string; at?: number };
-    if (typeof at !== 'number' || ctx.now() - at > CHAT_NAME_TTL_MS) {
-      void prefetchChatName(ctx, chatId, cacheKey).catch(() => {});
+    if (typeof at === 'number' && ctx.now() - at <= CHAT_NAME_TTL_MS) {
+      return name || undefined;
     }
-    return name || undefined;
+    staleName = name || undefined;
+  } else if (typeof cached === 'string') {
+    // Legacy plain-string row: refresh inline below, serve it as fallback.
+    staleName = cached || undefined;
   }
-  if (typeof cached === 'string') {
-    // Legacy plain-string row: serve it, upgrade to the timestamped shape.
-    void prefetchChatName(ctx, chatId, cacheKey).catch(() => {});
-    return cached || undefined;
-  }
-  void prefetchChatName(ctx, chatId, cacheKey).catch(() => {});
-  return undefined;
+  const fetched = await fetchChatName(ctx, chatId, cacheKey);
+  // null means the lookup degraded (serve the stale name if we have one);
+  // undefined means resolved-and-nameless (DM sentinel / cleared name) and
+  // must NOT fall back to a stale name — `??` would conflate the two.
+  return fetched === null ? staleName : fetched;
 }
 
-async function prefetchChatName(
+/** Resolve + cache one chat's name; null when the lookup degrades. */
+async function fetchChatName(
   ctx: ConnectorContext,
   chatId: string,
   cacheKey: string,
-): Promise<void> {
+): Promise<string | undefined | null> {
   try {
     const res = await fetch(
       `${parallApiUrl(ctx)}/api/v1/orgs/${parallOrgId(ctx)}/chats/${chatId}`,
@@ -916,12 +878,14 @@ async function prefetchChatName(
         signal: AbortSignal.timeout(PROVIDER_LOOKUP_TIMEOUT_MS),
       },
     );
-    if (!res.ok) return;
+    if (!res.ok) return null;
     const body = (await res.json().catch(() => null)) as { name?: string } | null;
     const name = typeof body?.name === 'string' ? body.name : '';
     await ctx.store?.set(cacheKey, { name, at: ctx.now() }).catch(() => {});
+    return name || undefined;
   } catch {
-    // Cosmetic prefetch — the next message from this chat retries.
+    // Cosmetic lookup — the next message from this chat retries.
+    return null;
   }
 }
 
@@ -946,7 +910,7 @@ export function handleParallAgentEvent(
   event: AgentEvent,
   ctx: ConnectorContext,
 ): Promise<AgentEventEffect[]> {
-  return serialized(() => handleParallAgentEventInner(event, ctx));
+  return serialized(ctx, () => handleParallAgentEventInner(event, ctx));
 }
 
 async function handleParallAgentEventInner(

package/src/index.ts

@@ -2,9 +2,9 @@ import type { ChannelConnector } from '@parel/plugin-sdk';
 import { connectParall } from './connect.js';
 import { buildParallDelivery } from './delivery.js';
 import {
-  catchUpParall,
   handleParallAgentEvent,
   handleParallFrame,
+  handleParallOpen,
   handleParallTimer,
 } from './inbound.js';
 
@@ -24,7 +24,7 @@ import {
  */
 const connector: ChannelConnector = {
   connect: connectParall,
-  onOpen: catchUpParall,
+  onOpen: handleParallOpen,
   onMessage: handleParallFrame,
   onTimer: handleParallTimer,
   onAgentEvent: handleParallAgentEvent,