@parall/parel-channel 1.51.0 → 1.52.0

package/dist/inbound.d.ts

@@ -1,26 +1,27 @@
 import type { AgentEvent, AgentEventEffect, ConnectorContext, ConnectorEffect, WebSocketFrame } from '@parel/plugin-sdk';
-/** Surface a violated isolation assumption as a log line, not silent
- * mis-serialization (see the chain doc above). */
-export declare function assertChainConnection(ctx: ConnectorContext): void;
-export declare function serialized<T>(fn: () => Promise<T>): Promise<T>;
+export declare function serialized<T>(ctx: ConnectorContext, fn: () => Promise<T>): Promise<T>;
 export declare function handleParallFrame(frame: WebSocketFrame, ctx: ConnectorContext): Promise<ConnectorEffect[]>;
 /**
- * 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 declare function handleParallTimer(timer: {
     key: string;
 }, ctx: ConnectorContext): Promise<ConnectorEffect[]>;
 /**
- * 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 declare function catchUpParall(ctx: ConnectorContext): Promise<ConnectorEffect[]>;
+export declare function handleParallOpen(ctx: ConnectorContext): Promise<ConnectorEffect[]>;
 /**
  * Agent execution events (parel E1+E2, plugin-sdk 0.9.0, opt-in via the
  * channel declaration's `observe: [turn, steps]`).

package/dist/inbound.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"inbound.d.ts","sourceRoot":"","sources":["../src/inbound.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,UAAU,EACV,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,cAAc,EACf,MAAM,mBAAmB,CAAC;AAkH3B;kDACkD;AAClD,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,gBAAgB,GAAG,IAAI,CASjE;AACD,wBAAgB,UAAU,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAO9D;AAED,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,cAAc,EACrB,GAAG,EAAE,gBAAgB,GACpB,OAAO,CAAC,eAAe,EAAE,CAAC,CAG5B;AAwCD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,EACtB,GAAG,EAAE,gBAAgB,GACpB,OAAO,CAAC,eAAe,EAAE,CAAC,CAE5B;AA8BD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAE/E;AAkrBD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,UAAU,EACjB,GAAG,EAAE,gBAAgB,GACpB,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAE7B"}
+{"version":3,"file":"inbound.d.ts","sourceRoot":"","sources":["../src/inbound.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,UAAU,EACV,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,cAAc,EACf,MAAM,mBAAmB,CAAC;AAyH3B,wBAAgB,UAAU,CAAC,CAAC,EAAE,GAAG,EAAE,gBAAgB,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAWrF;AAED,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,cAAc,EACrB,GAAG,EAAE,gBAAgB,GACpB,OAAO,CAAC,eAAe,EAAE,CAAC,CAE5B;AAoDD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,EACtB,GAAG,EAAE,gBAAgB,GACpB,OAAO,CAAC,eAAe,EAAE,CAAC,CAE5B;AAsCD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAElF;AAwnBD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,UAAU,EACjB,GAAG,EAAE,gBAAgB,GACpB,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAE7B"}

package/dist/inbound.js

@@ -1,45 +1,37 @@
 import { channelCapabilityEnv } from './channel-capability.js';
 import { buildChatPrompt } 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 { buildForkScopePrefix, bumpForkRetryAttempts, childConfirmed, childRefKnown, clearForkState, clearForkSubject, FORK_RETRY_DELAY_MS, FORK_RETRY_PREFIX, handleChildSpawnFailed, MAX_SPAWN_VERIFY_ATTEMPTS, noteMainTurnEvent, planForkDecision, recordSpawn, settleChildEvent, trackFollowUpAck, } from './fork.js';
-import { ackByIdEffect, claimDispatchSource, completeFencedEnvelopes, completeSourceEffect, conversationKey, createErrorStep, fetchMainSessionFresh, createInputStep, createTraceStep, createTypedInputStep, EMIT_TTL_MS, ensureChildSession, ensureSession, invalidateChildSession, invalidateSession, nextEnvelopeId, patchSession, readActiveEmit, reportingEnabled, SESSION_CACHE_KEY, TURN_ENVELOPE_KEY, writeActiveEmit, } from './session.js';
+import { ackByIdEffect, claimDispatchSource, completeFencedEnvelopes, completeSourceEffect, conversationKey, createErrorStep, createInputStep, createTraceStep, createTypedInputStep, EMIT_TTL_MS, ensureChildSession, ensureSession, invalidateChildSession, invalidateSession, nextEnvelopeId, patchSession, readActiveEmit, reportingEnabled, REQUEST_TIMEOUT_MS, TURN_ENVELOPE_KEY, writeActiveEmit, } from './session.js';
 import { isTypedEventType, planTypedDispatch } from './typed-dispatch.js';
 /**
- * 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.resolve();
-let chainConnectionId;
-/** Surface a violated isolation assumption as a log line, not silent
- * mis-serialization (see the chain doc above). */
-export function assertChainConnection(ctx) {
-    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(fn) {
-    const next = hookChain.then(fn, fn);
-    hookChain = next.then(() => undefined, () => undefined);
+const hookChains = new Map();
+export function serialized(ctx, fn) {
+    const chain = hookChains.get(ctx.connectionId) ?? Promise.resolve();
+    const next = chain.then(fn, fn);
+    hookChains.set(ctx.connectionId, next.then(() => undefined, () => undefined));
     return next;
 }
 export function handleParallFrame(frame, ctx) {
-    assertChainConnection(ctx);
-    return serialized(() => handleParallFrameInner(frame, ctx));
+    return serialized(ctx, () => handleParallFrameInner(frame, ctx));
 }
 async function handleParallFrameInner(frame, ctx) {
     let event;
@@ -69,27 +61,44 @@ async function handleParallFrameInner(frame, ctx) {
     }
     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, ctx) {
-    return serialized(() => handleParallTimerInner(timer, ctx));
+    return serialized(ctx, () => handleParallTimerInner(timer, ctx));
 }
 async function handleParallTimerInner(timer, ctx) {
+    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));
@@ -111,106 +120,25 @@ async function handleParallTimerInner(timer, ctx) {
         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) {
-    return serialized(() => catchUpParallInner(ctx));
-}
-async function catchUpParallInner(ctx) {
-    // 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));
-        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 = [];
-    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));
-            // 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 [];
-                });
-                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) {
+    return serialized(ctx, () => beginCatchUp(ctx));
 }
 /**
  * Turn-in-flight guard for redelivery (catch-up sweep AND repeated
@@ -284,15 +212,18 @@ async function effectsForDispatch(data, ctx) {
     // 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));
     const text = msg?.content?.text ?? '';
@@ -317,11 +248,11 @@ async function effectsForDispatch(data, ctx) {
     // 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({
@@ -410,12 +341,22 @@ async function effectsForDispatch(data, ctx) {
                     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'))
+            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 = {
@@ -518,6 +459,7 @@ async function effectsForDispatch(data, ctx) {
                         messageId: sourceId,
                         senderId,
                         text: stepText,
+                        threadRootId,
                     }),
                 ]);
                 if (results.includes('stale'))
@@ -525,13 +467,14 @@ async function effectsForDispatch(data, ctx) {
             }
             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',
@@ -575,32 +518,46 @@ async function effectsForDispatch(data, ctx) {
                 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
     // indicator's whole lifecycle rides on that.
@@ -712,60 +669,65 @@ async function effectsForTypedDispatch(data, ctx) {
 }
 /**
  * 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, chatId) {
     const cacheKey = `chatName:${chatId}`;
     const cached = await ctx.store?.get(cacheKey).catch(() => null);
+    let staleName;
     if (cached &&
         typeof cached === 'object' &&
         typeof cached.name === 'string') {
         const { name, at } = cached;
-        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;
     }
-    if (typeof cached === 'string') {
-        // Legacy plain-string row: serve it, upgrade to the timestamped shape.
-        void prefetchChatName(ctx, chatId, cacheKey).catch(() => { });
-        return cached || undefined;
+    else if (typeof cached === 'string') {
+        // Legacy plain-string row: refresh inline below, serve it as fallback.
+        staleName = 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(ctx, chatId, cacheKey) {
+/** Resolve + cache one chat's name; null when the lookup degrades. */
+async function fetchChatName(ctx, chatId, cacheKey) {
     try {
         const res = await fetch(`${parallApiUrl(ctx)}/api/v1/orgs/${parallOrgId(ctx)}/chats/${chatId}`, {
             headers: { Authorization: `Bearer ${requireAgk(ctx)}` },
             signal: AbortSignal.timeout(PROVIDER_LOOKUP_TIMEOUT_MS),
         });
         if (!res.ok)
-            return;
+            return null;
         const body = (await res.json().catch(() => 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;
     }
 }
 /**
@@ -786,7 +748,7 @@ async function prefetchChatName(ctx, chatId, cacheKey) {
  * missed trace step is a gap in the panel, nothing more.
  */
 export function handleParallAgentEvent(event, ctx) {
-    return serialized(() => handleParallAgentEventInner(event, ctx));
+    return serialized(ctx, () => handleParallAgentEventInner(event, ctx));
 }
 async function handleParallAgentEventInner(event, ctx) {
     // spawnChildSession's asynchronous error channel — not turn-scoped and

package/dist/index.js

@@ -1,6 +1,6 @@
 import { connectParall } from './connect.js';
 import { buildParallDelivery } from './delivery.js';
-import { catchUpParall, handleParallAgentEvent, handleParallFrame, handleParallTimer, } from './inbound.js';
+import { handleParallAgentEvent, handleParallFrame, handleParallOpen, handleParallTimer, } from './inbound.js';
 /**
  * Parall channel plugin for the parel runtime.
  *
@@ -17,7 +17,7 @@ import { catchUpParall, handleParallAgentEvent, handleParallFrame, handleParallT
  */
 const connector = {
     connect: connectParall,
-    onOpen: catchUpParall,
+    onOpen: handleParallOpen,
     onMessage: handleParallFrame,
     onTimer: handleParallTimer,
     onAgentEvent: handleParallAgentEvent,