@parall/parel-channel 1.50.1 → 1.52.0

package/dist/catchup.d.ts

@@ -0,0 +1,79 @@
+import type { ConnectorContext, ConnectorEffect } from '@parel/plugin-sdk';
+/**
+ * Incremental, timer-driven dispatch catch-up (execution-model v2 I4:
+ * lifecycle hooks are O(1); any O(backlog) work must be a durable, resumable,
+ * timer-driven job — parel channel-connector-execution-model.md §2).
+ *
+ * The 1.48.0 shape — onOpen sweeping up to 40×50 dispatches inline — cannot
+ * live under the v2 15s onOpen budget (a backlog would blow the budget, and
+ * under first-timeout-terminal semantics every timeout is an epoch rotation:
+ * the sweep would convert a reconnect into a rotation storm). Instead:
+ *
+ *   onOpen  → reset the sweep state, arm CATCHUP_TIMER_KEY at now  (O(1))
+ *   onTimer → one bounded round per firing:
+ *     round 0 (phase 'gen'): the New Session generation check — MUST precede
+ *       any dispatch replay (a rotation that happened while offline would
+ *       otherwise replay post-reset messages into pre-reset forks), plus the
+ *       forkDisabled revalidation-latch clear. Best-effort, same posture the
+ *       onOpen sweep had: a transient failure logs and the sweep proceeds
+ *       (the cached session id — the generation token — is never dropped).
+ *     sweep rounds: ONE page of GET /dispatch, items replayed FIFO through
+ *       the normal dispatch pipeline, then re-arm immediately while pages
+ *       remain. Cursor lives in ctx.store; it is an optimization, not a
+ *       correctness source — the per-source attempt fence (shouldSkipLiveRow)
+ *       makes any re-scan idempotent, so a mid-page bail or a crash simply
+ *       re-lists the same page and skips what already emitted.
+ *     drain: a pass that ends (no next_cursor) after emitting anything runs
+ *       one more pass from the top (rows the cursor walk missed, rows that
+ *       arrived mid-sweep); the job ends on the first CLEAN pass — no emits,
+ *       no item failures. Item failures keep the row pending server-side and
+ *       re-arm the next pass with exponential backoff instead of ending, so
+ *       a transiently unfetchable source is retried without a reconnect.
+ *
+ * FIFO across the live socket: while a sweep is in flight, dispatch.new
+ * frames are NOT processed inline (they would leapfrog the backlog into the
+ * shared main session out of order) — the frame handler just re-arms the
+ * timer (armCatchUpEffect) and lets the sweep list the row, which is already
+ * durable server-side. That re-arm doubles as the lost-timer self-heal: any
+ * new frame revives a stalled sweep. The re-arm honours an in-flight backoff
+ * (state.notBefore): a frame arriving while a round is backed off on a 5xx
+ * source re-arms at the remaining delay, not 0, so steady traffic against a
+ * failing source cannot tight-poll it.
+ *
+ * Runs identically under the v1 host (flag off): timers and effects work the
+ * same there, rounds serialize through the connection hook chain, and the
+ * bounded round size keeps each onTimer call small.
+ */
+export declare const CATCHUP_TIMER_KEY = "__parall_catchup__";
+/** The idempotent "make sure the sweep timer is armed" effect (setTimer is
+ * keyed — re-arming replaces). Also what the frame handler returns while a
+ * sweep is in flight. */
+export declare function armCatchUpEffect(ctx: ConnectorContext, delayMs?: number): ConnectorEffect;
+/**
+ * onOpen: O(1) by contract — reset the sweep to a fresh pass (a reconnect is
+ * the revalidation point, so the generation check must run again) and arm the
+ * timer. All real work happens in runCatchUpRound.
+ */
+export declare function beginCatchUp(ctx: ConnectorContext): Promise<ConnectorEffect[]>;
+/**
+ * The frame handler's FIFO gate: while a sweep is in flight (state present),
+ * a live dispatch.new must not leapfrog the backlog. Returns the delay (ms)
+ * the caller should re-arm the sweep timer with — honouring any in-flight
+ * backoff (notBefore) so a live frame cannot reset a backed-off round to fire
+ * immediately — or null when no sweep is in flight (process the frame inline).
+ * Also marks the pass dirty so the job runs another from-the-top pass before
+ * ending. The dirty mark is load-bearing, not just ordering hygiene: a server
+ * REDRIVE hint can point at a row BEHIND the sweep cursor (e.g. during the
+ * final re-check pass), and deferring the frame consumes that hint — without
+ * forcing one more full pass, the job could end cleanly with the row
+ * stranded until the next reconnect. Runs inside the serialized chain, so
+ * the read-modify-write cannot interleave with a round's own state write.
+ */
+export declare function deferToCatchUp(ctx: ConnectorContext): Promise<number | null>;
+/**
+ * One timer round. `planDispatch` is the normal inbound dispatch pipeline
+ * (inbound.ts effectsForDispatch), injected to keep this module's imports
+ * acyclic. Every path either re-arms the timer or deliberately ends the job.
+ */
+export declare function runCatchUpRound(ctx: ConnectorContext, planDispatch: (data: Record<string, unknown>) => Promise<ConnectorEffect[]>): Promise<ConnectorEffect[]>;
+//# sourceMappingURL=catchup.d.ts.map

package/dist/catchup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catchup.d.ts","sourceRoot":"","sources":["../src/catchup.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAK3E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAEH,eAAO,MAAM,iBAAiB,uBAAuB,CAAC;AA0FtD;;yBAEyB;AACzB,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,gBAAgB,EAAE,OAAO,SAAI,GAAG,eAAe,CAEpF;AAED;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAGpF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,cAAc,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAOlF;AAqCD;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,GAAG,EAAE,gBAAgB,EACrB,YAAY,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,eAAe,EAAE,CAAC,GAC1E,OAAO,CAAC,eAAe,EAAE,CAAC,CAgH5B"}

package/dist/catchup.js

@@ -0,0 +1,296 @@
+import { parallApiUrl, parallOrgId, requireAgk } from './connect.js';
+import { clearForkState, FORK_DISABLED_KEY } from './fork.js';
+import { fetchMainSessionFresh, invalidateChildSession, SESSION_CACHE_KEY } from './session.js';
+/**
+ * Incremental, timer-driven dispatch catch-up (execution-model v2 I4:
+ * lifecycle hooks are O(1); any O(backlog) work must be a durable, resumable,
+ * timer-driven job — parel channel-connector-execution-model.md §2).
+ *
+ * The 1.48.0 shape — onOpen sweeping up to 40×50 dispatches inline — cannot
+ * live under the v2 15s onOpen budget (a backlog would blow the budget, and
+ * under first-timeout-terminal semantics every timeout is an epoch rotation:
+ * the sweep would convert a reconnect into a rotation storm). Instead:
+ *
+ *   onOpen  → reset the sweep state, arm CATCHUP_TIMER_KEY at now  (O(1))
+ *   onTimer → one bounded round per firing:
+ *     round 0 (phase 'gen'): the New Session generation check — MUST precede
+ *       any dispatch replay (a rotation that happened while offline would
+ *       otherwise replay post-reset messages into pre-reset forks), plus the
+ *       forkDisabled revalidation-latch clear. Best-effort, same posture the
+ *       onOpen sweep had: a transient failure logs and the sweep proceeds
+ *       (the cached session id — the generation token — is never dropped).
+ *     sweep rounds: ONE page of GET /dispatch, items replayed FIFO through
+ *       the normal dispatch pipeline, then re-arm immediately while pages
+ *       remain. Cursor lives in ctx.store; it is an optimization, not a
+ *       correctness source — the per-source attempt fence (shouldSkipLiveRow)
+ *       makes any re-scan idempotent, so a mid-page bail or a crash simply
+ *       re-lists the same page and skips what already emitted.
+ *     drain: a pass that ends (no next_cursor) after emitting anything runs
+ *       one more pass from the top (rows the cursor walk missed, rows that
+ *       arrived mid-sweep); the job ends on the first CLEAN pass — no emits,
+ *       no item failures. Item failures keep the row pending server-side and
+ *       re-arm the next pass with exponential backoff instead of ending, so
+ *       a transiently unfetchable source is retried without a reconnect.
+ *
+ * FIFO across the live socket: while a sweep is in flight, dispatch.new
+ * frames are NOT processed inline (they would leapfrog the backlog into the
+ * shared main session out of order) — the frame handler just re-arms the
+ * timer (armCatchUpEffect) and lets the sweep list the row, which is already
+ * durable server-side. That re-arm doubles as the lost-timer self-heal: any
+ * new frame revives a stalled sweep. The re-arm honours an in-flight backoff
+ * (state.notBefore): a frame arriving while a round is backed off on a 5xx
+ * source re-arms at the remaining delay, not 0, so steady traffic against a
+ * failing source cannot tight-poll it.
+ *
+ * Runs identically under the v1 host (flag off): timers and effects work the
+ * same there, rounds serialize through the connection hook chain, and the
+ * bounded round size keeps each onTimer call small.
+ */
+export const CATCHUP_TIMER_KEY = '__parall_catchup__';
+/** Store key — deliberately OUTSIDE the `fork` prefix family so the
+ * agent.new_session purge (clearForkState) never wipes sweep state. */
+const CATCHUP_STATE_KEY = 'catchup';
+/** One page per round; page size == round item bound so a clean round always
+ * advances the cursor. Small on purpose: each item can fan out several inline
+ * fetches and 1-2 effects, and the round's effects execute while the v2
+ * execution slot is held — a big page would occupy it for the whole replay. */
+const CATCHUP_PAGE_LIMIT = 10;
+/** Soft wall-clock bound per round, checked BETWEEN items (an in-flight item
+ * finishes). 4s: the binding constraint is the LEGACY (flag-off) host, whose
+ * hook budget is 5s and whose timeout discards the round's effects — re-arm
+ * included — rather than cancelling the work; staying under it keeps the
+ * common case safe on both hosts (v2's onTimer budget is 60s). A single
+ * pathological item can still blow past any bound (its own fetch caps are
+ * the 5s REQUEST_TIMEOUT_MS); the self-heal for a discarded re-arm is the
+ * frame handler's defer path (any live frame re-arms the timer) plus the
+ * next reconnect's beginCatchUp. */
+const ROUND_SOFT_BUDGET_MS = 4_000;
+/** Timeout for the job's OWN fetches (dispatch page list, generation check).
+ * Tighter than REQUEST_TIMEOUT_MS: on the v1 host these run inside a 5s
+ * onTimer budget whose expiry discards the round's effects AFTER the due
+ * timer row was already deleted — a single stalled request at the full 5s
+ * cap would strand the job with no timer. 3s leaves re-arm margin. */
+const CATCHUP_FETCH_TIMEOUT_MS = 3_000;
+const BACKOFF_BASE_MS = 5_000;
+const BACKOFF_MAX_MS = 5 * 60 * 1000;
+/** Frozen so the store-less fallback (memoryState, written by reference in
+ * beginCatchUp) cannot be mutated into a corrupted shared template — every
+ * transition already builds a new object via spread. */
+const FRESH_STATE = Object.freeze({
+    phase: 'gen',
+    cursor: '',
+    dirty: false,
+    sawFailure: false,
+    failures: 0,
+    notBefore: 0,
+});
+/** In-memory fallback for store-less contexts (SDK test mocks) — a module
+ * global is a discardable cache, never correctness (v2 I4), which is exactly
+ * the durability class a fallback may have. */
+const memoryState = new Map();
+async function readState(ctx) {
+    if (!ctx.store)
+        return memoryState.get(ctx.connectionId) ?? null;
+    const raw = (await ctx.store.get(CATCHUP_STATE_KEY).catch(() => null));
+    return raw && (raw.phase === 'gen' || raw.phase === 'sweep') ? raw : null;
+}
+async function writeState(ctx, state) {
+    if (!ctx.store) {
+        memoryState.set(ctx.connectionId, state);
+        return;
+    }
+    await ctx.store.set(CATCHUP_STATE_KEY, state).catch(() => { });
+}
+async function clearState(ctx) {
+    if (!ctx.store) {
+        memoryState.delete(ctx.connectionId);
+        return;
+    }
+    await ctx.store.delete(CATCHUP_STATE_KEY).catch(() => { });
+}
+/** The idempotent "make sure the sweep timer is armed" effect (setTimer is
+ * keyed — re-arming replaces). Also what the frame handler returns while a
+ * sweep is in flight. */
+export function armCatchUpEffect(ctx, delayMs = 0) {
+    return { type: 'setTimer', key: CATCHUP_TIMER_KEY, at: ctx.now() + delayMs };
+}
+/**
+ * onOpen: O(1) by contract — reset the sweep to a fresh pass (a reconnect is
+ * the revalidation point, so the generation check must run again) and arm the
+ * timer. All real work happens in runCatchUpRound.
+ */
+export async function beginCatchUp(ctx) {
+    await writeState(ctx, FRESH_STATE);
+    return [armCatchUpEffect(ctx)];
+}
+/**
+ * The frame handler's FIFO gate: while a sweep is in flight (state present),
+ * a live dispatch.new must not leapfrog the backlog. Returns the delay (ms)
+ * the caller should re-arm the sweep timer with — honouring any in-flight
+ * backoff (notBefore) so a live frame cannot reset a backed-off round to fire
+ * immediately — or null when no sweep is in flight (process the frame inline).
+ * Also marks the pass dirty so the job runs another from-the-top pass before
+ * ending. The dirty mark is load-bearing, not just ordering hygiene: a server
+ * REDRIVE hint can point at a row BEHIND the sweep cursor (e.g. during the
+ * final re-check pass), and deferring the frame consumes that hint — without
+ * forcing one more full pass, the job could end cleanly with the row
+ * stranded until the next reconnect. Runs inside the serialized chain, so
+ * the read-modify-write cannot interleave with a round's own state write.
+ */
+export async function deferToCatchUp(ctx) {
+    const state = await readState(ctx);
+    if (!state)
+        return null;
+    if (!state.dirty)
+        await writeState(ctx, { ...state, dirty: true });
+    // Honour an in-flight backoff: re-arming the keyed timer at delay 0 would
+    // overwrite a backoffDelay-armed round and tight-poll a failing source.
+    return Math.max(0, state.notBefore - ctx.now());
+}
+function backoffDelay(failures) {
+    return Math.min(BACKOFF_BASE_MS * 2 ** Math.max(0, failures - 1), BACKOFF_MAX_MS);
+}
+/**
+ * New Session generation check — verbatim semantics of the 1.48.0 onOpen
+ * preamble (see the session.ts fetchMainSessionFresh doc): the
+ * `agent.new_session` WS push is not replayed, so a reset that happened while
+ * disconnected leaves stale fork routing that would deliver post-reset
+ * messages into pre-reset children. The main ase_ id IS the generation token.
+ */
+async function runGenerationCheck(ctx) {
+    try {
+        const cachedMain = (await ctx.store?.get(SESSION_CACHE_KEY).catch(() => null));
+        if (cachedMain) {
+            const freshMain = await fetchMainSessionFresh(ctx, { timeoutMs: CATCHUP_FETCH_TIMEOUT_MS });
+            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(FORK_DISABLED_KEY).catch(() => { });
+    }
+    catch (err) {
+        console.error('[parel-channel] new-session generation check failed', err);
+    }
+}
+/**
+ * One timer round. `planDispatch` is the normal inbound dispatch pipeline
+ * (inbound.ts effectsForDispatch), injected to keep this module's imports
+ * acyclic. Every path either re-arms the timer or deliberately ends the job.
+ */
+export async function runCatchUpRound(ctx, planDispatch) {
+    // A missing state row (timer armed by a deferred frame racing the sweep's
+    // clean finish, or state lost) starts a fresh sweep — over-sweeping is
+    // idempotent (fences), under-sweeping loses messages.
+    const state = (await readState(ctx)) ?? FRESH_STATE;
+    if (state.phase === 'gen') {
+        await runGenerationCheck(ctx);
+        await writeState(ctx, { ...FRESH_STATE, phase: 'sweep' });
+        return [armCatchUpEffect(ctx)];
+    }
+    const roundStart = ctx.now();
+    let body = null;
+    try {
+        const apiUrl = parallApiUrl(ctx);
+        const agk = requireAgk(ctx);
+        const orgId = parallOrgId(ctx);
+        const url = `${apiUrl}/api/v1/orgs/${orgId}/dispatch?limit=${CATCHUP_PAGE_LIMIT}${state.cursor ? `&cursor=${encodeURIComponent(state.cursor)}` : ''}`;
+        const res = await fetch(url, {
+            headers: { Authorization: `Bearer ${agk}` },
+            signal: AbortSignal.timeout(CATCHUP_FETCH_TIMEOUT_MS),
+        });
+        if (res.ok) {
+            body = (await res.json().catch(() => null));
+        }
+    }
+    catch {
+        // fall through to the transient-failure backoff below
+    }
+    if (!body) {
+        const failures = state.failures + 1;
+        const delay = backoffDelay(failures);
+        // Persist notBefore so a live frame's defer re-arm honours the backoff
+        // instead of resetting it to fire now (tight-polling the failing API).
+        await writeState(ctx, { ...state, failures, notBefore: ctx.now() + delay });
+        console.error(`[parel-channel] catch-up page fetch failed (attempt ${failures})`);
+        return [armCatchUpEffect(ctx, delay)];
+    }
+    // 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. Transient item failures THROW (the pipeline's
+    // transient-vs-deliberate contract: a 5xx/timeout on a source fetch
+    // throws; deliberate pendings — unknown types, fence skips, disabled
+    // deployments — return []): the row stays pending server-side and the
+    // failure flag re-arms the next pass with backoff instead of ending the
+    // job with the row stranded on a healthy long-lived socket.
+    const rows = body.data ?? [];
+    const effects = [];
+    let dirty = state.dirty;
+    let sawFailure = state.sawFailure;
+    let processed = 0;
+    for (const d of rows) {
+        if (ctx.now() - roundStart > ROUND_SOFT_BUDGET_MS)
+            break;
+        const out = await planDispatch(d).catch((err) => {
+            console.error('[parel-channel] catch-up dispatch failed', err);
+            sawFailure = true;
+            dirty = true;
+            return [];
+        });
+        // Only MAIN-path emits drive the drain re-check: they arm a fence, so
+        // the follow-up pass skips them and the job converges. Fork-owned
+        // outputs (spawnChildSession / deliverTo emits) never write a fence —
+        // counting them would re-check forever, and their fast re-plan would
+        // race the fork verification cadence — their loss recovery belongs to
+        // the fork machinery (parked acks, retry timer), not this job.
+        if (out.some((e) => e.type === 'emitEvent' && !e.deliverTo)) {
+            dirty = true;
+        }
+        effects.push(...out);
+        processed++;
+    }
+    if (processed < rows.length) {
+        // Soft budget hit mid-page: keep the cursor (the refetch re-lists this
+        // page; already-emitted rows fence-skip) and continue immediately. The
+        // failure streak is NOT reset mid-pass — only a failure-free pass end
+        // clears it, or a persistent 5xx in a multi-page backlog would compute
+        // a streak of 1 forever and rescan at the base delay instead of backing
+        // off. The re-arm timer leads the effect list: v2 replays effects in
+        // order and a dead-lettered earlier effect must not also cost the job
+        // its progression timer (setTimer is host-owned/idempotent — order is
+        // free on v1).
+        // Progress this round → no backoff: clear notBefore so a lingering value
+        // from an earlier failed round can't make a defer honour a stale backoff.
+        await writeState(ctx, { ...state, dirty, sawFailure, notBefore: 0 });
+        return [armCatchUpEffect(ctx), ...effects];
+    }
+    if (body.next_cursor) {
+        await writeState(ctx, { ...state, cursor: body.next_cursor, dirty, sawFailure, notBefore: 0 });
+        return [armCatchUpEffect(ctx), ...effects];
+    }
+    // Pass complete. Clean pass (nothing emitted, nothing failed) ends the job;
+    // a dirty pass runs another full pass from the top — the re-check that
+    // makes the cursor an optimization instead of a correctness source.
+    if (!dirty) {
+        await clearState(ctx);
+        return effects;
+    }
+    const failures = sawFailure ? state.failures + 1 : 0;
+    const delay = sawFailure ? backoffDelay(failures) : 0;
+    await writeState(ctx, {
+        ...FRESH_STATE,
+        phase: 'sweep',
+        failures,
+        notBefore: delay > 0 ? ctx.now() + delay : 0,
+    });
+    return [armCatchUpEffect(ctx, delay), ...effects];
+}

package/dist/connect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"connect.d.ts","sourceRoot":"","sources":["../src/connect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAE1E;;;;;;;;;GASG;AACH,wBAAsB,aAAa,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,cAAc,CAAC,CAyBlF;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,gBAAgB,GAAG,MAAM,CAE1D;AAED,wBAAgB,WAAW,CAAC,GAAG,EAAE,gBAAgB,GAAG,MAAM,CAEzD;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,gBAAgB,GAAG,MAAM,CAE3D;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAE7D;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,gBAAgB,GAAG,MAAM,CAMxD"}
+{"version":3,"file":"connect.d.ts","sourceRoot":"","sources":["../src/connect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAE1E;;;;;;;;;GASG;AACH,wBAAsB,aAAa,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,cAAc,CAAC,CA2BlF;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,gBAAgB,GAAG,MAAM,CAE1D;AAED,wBAAgB,WAAW,CAAC,GAAG,EAAE,gBAAgB,GAAG,MAAM,CAEzD;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,gBAAgB,GAAG,MAAM,CAE3D;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAE7D;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,gBAAgB,GAAG,MAAM,CAMxD"}

package/dist/connect.js

@@ -12,11 +12,13 @@ export async function connectParall(ctx) {
     const apiUrl = parallApiUrl(ctx);
     const agk = requireAgk(ctx);
     // connect() runs on every (re)connect — fail fast rather than hang the host's
-    // reconnect loop on a wedged ticket endpoint.
+    // reconnect loop on a wedged ticket endpoint. 5s: the v2 connect budget is
+    // 15s and first-timeout rotates the epoch, so the single mint fetch must
+    // leave ample margin (session.ts REQUEST_TIMEOUT_MS rationale).
     const res = await fetch(`${apiUrl}/api/v1/ws/ticket`, {
         method: 'POST',
         headers: { Authorization: `Bearer ${agk}` },
-        signal: AbortSignal.timeout(10_000),
+        signal: AbortSignal.timeout(5_000),
     });
     if (!res.ok) {
         throw new Error(`parel-channel: ws ticket failed (${res.status})`);

package/dist/fork.d.ts

@@ -6,6 +6,8 @@ type ChildSpawnFailedEvent = Extract<AgentEvent, {
 /** Delay before a failed spawn's messages are re-driven through onTimer. */
 export declare const FORK_RETRY_DELAY_MS = 15000;
 export declare const FORK_RETRY_PREFIX = "forkRetry:";
+/** Exported for the catch-up job's reconnect revalidation (catchup.ts). */
+export declare const FORK_DISABLED_KEY = "forkDisabled";
 export interface PendingAck {
     dispatchId: string;
     sourceId: string;
@@ -85,6 +87,11 @@ export declare function clearForkSubject(ctx: ConnectorContext, subject: string,
 /**
  * Bump-and-park a fork retry ledger row (also the spawn-verification
  * coordinate onTimer re-plans). Returns the attempt count INCLUDING this one.
+ * Attempts count VERIFICATION ROUNDS on the retry timer's cadence, so a bump
+ * younger than FORK_RETRY_DELAY_MS is a fast replay (catch-up re-check pass,
+ * rapid reconnect double-sweep) and keeps the prior count — without the
+ * floor, back-to-back replays would burn through MAX_SPAWN_VERIFY_ATTEMPTS
+ * in milliseconds and black-hole a child that was starting up fine.
  */
 export declare function bumpForkRetryAttempts(ctx: ConnectorContext, retryKey: string, data: Record<string, unknown>): Promise<number>;
 /** Give up re-verifying a spawn after this many timer rounds. */

package/dist/fork.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fork.d.ts","sourceRoot":"","sources":["../src/fork.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAEtE,qEAAqE;AACrE,KAAK,qBAAqB,GAAG,OAAO,CAAC,UAAU,EAAE;IAAE,IAAI,EAAE,oBAAoB,CAAA;CAAE,CAAC,CAAC;AA+CjF,4EAA4E;AAC5E,eAAO,MAAM,mBAAmB,QAAS,CAAC;AAS1C,eAAO,MAAM,iBAAiB,eAAe,CAAC;AAW9C,MAAM,WAAW,UAAU;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,EAAE,EAAE,MAAM,CAAC;IACX;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,UAAU,EAAE,CAAC;IAC3B,gFAAgF;IAChF,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;2CAEuC;IACvC,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,MAAM,YAAY,GACpB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE;AAClB;oEACoE;GAClE;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,GAC1D;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAMxC;;;;;;;;;GASG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,gBAAgB,EACrB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,YAAY,CAAC,CAwCvB;AAED;;sEAEsE;AACtE,wBAAsB,WAAW,CAC/B,GAAG,EAAE,gBAAgB,EACrB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,UAAU,GAClB,OAAO,CAAC,IAAI,CAAC,CAQf;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,gBAAgB,EACrB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,UAAU,GACd,OAAO,CAAC,OAAO,CAAC,CASlB;AAED;;;+EAG+E;AAC/E,wBAAsB,aAAa,CAAC,GAAG,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAO7F;AAED,0EAA0E;AAC1E,wBAAsB,cAAc,CAClC,GAAG,EAAE,gBAAgB,EACrB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,OAAO,CAAC,CAGlB;AAED,8EAA8E;AAC9E,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,gBAAgB,EACrB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAMf;AAED;;;GAGG;AACH,wBAAsB,qBAAqB,CACzC,GAAG,EAAE,gBAAgB,EACrB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,OAAO,CAAC,MAAM,CAAC,CAOjB;AAED,iEAAiE;AACjE,eAAO,MAAM,yBAAyB,IAAI,CAAC;AAE3C;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAoB7E;AAED;;;GAGG;AACH,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,gBAAgB,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAc/F;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,gBAAgB,EACrB,KAAK,EAAE,UAAU,GAChB,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,UAAU,EAAE,CAAA;CAAE,GAAG,IAAI,CAAC,CA+BhE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,sBAAsB,CAC1C,GAAG,EAAE,gBAAgB,EACrB,KAAK,EAAE,qBAAqB,GAC3B,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,UAAU,EAAE,CAAA;CAAE,CAAC,CA2B3E;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,CAYnF"}
+{"version":3,"file":"fork.d.ts","sourceRoot":"","sources":["../src/fork.ts"],"names":[],"mappings":"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"}

package/dist/fork.js

@@ -47,7 +47,8 @@ const MAX_PENDING_FOLLOWUPS = 20;
 const MAX_ACK_ATTEMPTS = 3;
 const MAIN_TURN_KEY = 'forkMainTurn';
 export const FORK_RETRY_PREFIX = 'forkRetry:';
-const FORK_DISABLED_KEY = 'forkDisabled';
+/** Exported for the catch-up job's reconnect revalidation (catchup.ts). */
+export const FORK_DISABLED_KEY = 'forkDisabled';
 const childKey = (subject) => `forkChild:${subject}`;
 const childSubjectKey = (childRef) => `forkChildSubject:${childRef}`;
 function isLive(at, ttl, now) {
@@ -159,11 +160,22 @@ export async function clearForkSubject(ctx, subject, childRef) {
 /**
  * Bump-and-park a fork retry ledger row (also the spawn-verification
  * coordinate onTimer re-plans). Returns the attempt count INCLUDING this one.
+ * Attempts count VERIFICATION ROUNDS on the retry timer's cadence, so a bump
+ * younger than FORK_RETRY_DELAY_MS is a fast replay (catch-up re-check pass,
+ * rapid reconnect double-sweep) and keeps the prior count — without the
+ * floor, back-to-back replays would burn through MAX_SPAWN_VERIFY_ATTEMPTS
+ * in milliseconds and black-hole a child that was starting up fine.
  */
 export async function bumpForkRetryAttempts(ctx, retryKey, data) {
     const prior = (await ctx.store?.get(retryKey).catch(() => null));
+    const now = ctx.now();
+    if (typeof prior?.attempts === 'number' &&
+        typeof prior.at === 'number' &&
+        now - prior.at < FORK_RETRY_DELAY_MS) {
+        return prior.attempts;
+    }
     const attempts = (prior?.attempts ?? 0) + 1;
-    await ctx.store?.set(retryKey, { ...data, attempts }).catch(() => { });
+    await ctx.store?.set(retryKey, { ...data, attempts, at: now }).catch(() => { });
     return attempts;
 }
 /** Give up re-verifying a spawn after this many timer rounds. */

package/dist/inbound-channel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"inbound-channel.d.ts","sourceRoot":"","sources":["../src/inbound-channel.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAkB3E;;;;GAIG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,OAAQ,CAAC;AAEhD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,yBAAyB,CAC7C,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,gBAAgB,GACpB,OAAO,CAAC,eAAe,EAAE,CAAC,CAkK5B"}
+{"version":3,"file":"inbound-channel.d.ts","sourceRoot":"","sources":["../src/inbound-channel.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAkB3E;;;;GAIG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,OAAQ,CAAC;AAEhD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,yBAAyB,CAC7C,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,gBAAgB,GACpB,OAAO,CAAC,eAAe,EAAE,CAAC,CAwL5B"}

package/dist/inbound-channel.js

@@ -43,7 +43,10 @@ export async function effectsForChannelDispatch(sourceId, ctx) {
             // takes) — permanently unusable, drop it.
             return [completeSourceEffect(ctx, 'channel_message', sourceId)];
         }
-        return []; // transient: keep pending, the catch-up sweep retries
+        // Transient: keep pending — THROW so the catch-up job counts the row as
+        // starving and re-arms with backoff (transient-vs-deliberate contract,
+        // see inbound.ts message path).
+        throw new Error(`transient channel message fetch failure (${m.status})`);
     }
     const msg = (await m.json().catch(() => null));
     const conversationId = msg?.conversation_id ? String(msg.conversation_id) : undefined;
@@ -63,7 +66,7 @@ export async function effectsForChannelDispatch(sourceId, ctx) {
         if (c.status === 404 || c.status === 403) {
             return [completeSourceEffect(ctx, 'channel_message', sourceId)];
         }
-        return [];
+        throw new Error(`transient channel conversation fetch failure (${c.status})`);
     }
     const conv = (await c.json().catch(() => null));
     // Provider (= clip alias) for prompt labeling + the reply hint.
@@ -82,6 +85,7 @@ export async function effectsForChannelDispatch(sourceId, ctx) {
     const receivedSettled = claimDispatchSource(ctx, 'channel_message', sourceId);
     const priorEmit = await readActiveEmit(ctx, 'channel_message', sourceId);
     const envelopeId = nextEnvelopeId('channel_message', sourceId, priorEmit);
+    let mappingEffect = null;
     let sessionId = await ensureSession(ctx);
     if (sessionId) {
         await ctx.store?.set(TURN_ENVELOPE_KEY, envelopeId).catch(() => { });
@@ -100,23 +104,41 @@ export async function effectsForChannelDispatch(sourceId, ctx) {
         ]);
         const results = await report(sessionId);
         if (results.includes('stale')) {
+            // Same stale-repair contract as the chat path — and the same
+            // attribution rule: never leave sessionId pointing at the closed
+            // session (it feeds the fence below).
             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;
             }
         }
         // Record the durable chv_ ↔ ase_ mapping (ops drill-down from a
-        // conversation into its session; last-write-wins on the server). Only on
-        // change — the store remembers what was last pushed — and fully
-        // fire-and-forget: pure bookkeeping must never add latency to the
-        // emit/ack path (a lost attempt is retried on the next message because
-        // the store memo only updates on success).
-        void recordConversationSession(ctx, conversationId, sessionId).catch(() => { });
+        // conversation into its session; last-write-wins on the server) as a
+        // FETCH EFFECT: host-executed, so it costs the hook budget nothing on
+        // the v1 host (a stalled PATCH awaited in-hook could blow the 5s budget
+        // and cost the emit), and the v2 outbox replays it with the idempotency
+        // key. The memo is written up front (inside the capture window): a
+        // dropped effect leaves the mapping stale until the session id next
+        // rotates — acceptable for an ops-observability pointer. Skipped when
+        // the stale repair above dropped the session — the next message records
+        // the fresh one.
+        if (sessionId) {
+            const mappedKey = `convSession:${conversationId}`;
+            const mapped = await ctx.store?.get(mappedKey).catch(() => null);
+            if (mapped !== sessionId) {
+                await ctx.store?.set(mappedKey, sessionId).catch(() => { });
+                mappingEffect = conversationSessionEffect(ctx, conversationId, sessionId);
+            }
+        }
     }
     await receivedSettled;
-    await writeActiveEmit(ctx, 'channel_message', sourceId, envelopeId);
+    // Fence carries this attempt's session for turn-end attribution (see
+    // ActiveEmit) — same contract as the chat-message path.
+    await writeActiveEmit(ctx, 'channel_message', sourceId, envelopeId, sessionId ?? undefined);
     // Live capability grant → this turn's lark-cli auth env (mint gate = the
     // no-drift revocation point) + the hint teaching the single reply path.
     const capabilityEnv = await channelCapabilityEnv(ctx);
@@ -169,8 +191,29 @@ export async function effectsForChannelDispatch(sourceId, ctx) {
         },
         // No ack effect — see the message path (inbound.ts): the row stays
         // received until complete-sources closes it.
+        ...(mappingEffect ? [mappingEffect] : []),
     ];
 }
+/**
+ * The chv_ → ase_ mapping push as a host-executed fetch effect (idempotent
+ * last-write-wins PATCH; the key dedupes v2 outbox replays of this exact
+ * pairing).
+ */
+function conversationSessionEffect(ctx, conversationId, sessionId) {
+    return {
+        type: 'fetch',
+        request: {
+            url: `${parallApiUrl(ctx)}/api/v1/orgs/${parallOrgId(ctx)}/channel-conversations/${conversationId}/session`,
+            method: 'PATCH',
+            headers: {
+                Authorization: `Bearer ${requireAgk(ctx)}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({ agent_session_id: sessionId }),
+        },
+        idempotencyKey: `convmap:${conversationId}:${sessionId}`,
+    };
+}
 /**
  * connection id → provider alias, cached in the durable store (stable
  * mapping; avoids one connection fetch per inbound message). Cache hits are
@@ -196,29 +239,3 @@ async function resolveChannelProvider(ctx, connectionId, get) {
         return undefined;
     }
 }
-/** Push the chv_ → ase_ pointer when it changed; warn-only on failure. */
-async function recordConversationSession(ctx, conversationId, sessionId) {
-    const mappedKey = `convSession:${conversationId}`;
-    const mapped = await ctx.store?.get(mappedKey).catch(() => null);
-    if (mapped === sessionId)
-        return;
-    try {
-        const res = await fetch(`${parallApiUrl(ctx)}/api/v1/orgs/${parallOrgId(ctx)}/channel-conversations/${conversationId}/session`, {
-            method: 'PATCH',
-            headers: {
-                Authorization: `Bearer ${requireAgk(ctx)}`,
-                'Content-Type': 'application/json',
-            },
-            body: JSON.stringify({ agent_session_id: sessionId }),
-            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
-        });
-        if (!res.ok) {
-            console.warn(`[parel-channel] conversation session mapping failed (${res.status})`);
-            return;
-        }
-        await ctx.store?.set(mappedKey, sessionId).catch(() => { });
-    }
-    catch (err) {
-        console.warn('[parel-channel] conversation session mapping failed', err);
-    }
-}