@parall/agent-core 1.37.0 → 1.38.0

package/src/gateway-lane-flow.ts

@@ -0,0 +1,235 @@
+import type { ParallClient } from '@parall/sdk';
+import type { DispatchAdapter, GatewayLogger } from './dispatch-adapter.js';
+import type { DispatchableMessage, MessageDispatchDecision } from './gateway-base.js';
+import { LedgerUnsupportedError } from './lane-ledger.js';
+import type { LaneLedger } from './lane-ledger.js';
+import type { ParallEvent } from './types.js';
+
+/**
+ * Lane-flow layer: the ledger-aware consumption protocols that sit between
+ * inbound routing and `runDispatch`. Split out of gateway-base.ts (already an
+ * oversized outlier) — the gateway keeps thin delegating methods so tests and
+ * call sites stay on the class surface.
+ */
+
+/** The slice of ParallAgentGateway the lane-flow functions operate on. */
+export interface LaneFlowHost {
+  laneLedger?: LaneLedger;
+  ledgerDisabled: boolean;
+  shuttingDown: boolean;
+  dispatchedMessages: Set<string>;
+  opts: {
+    client: ParallClient;
+    log?: GatewayLogger;
+    config: { org_id: string };
+    dispatchAdapter: DispatchAdapter;
+    agentUserId: string;
+  };
+  disableLedger(reason: string): void;
+  usesLaneLedger(event: ParallEvent): boolean;
+  emitDispatchReceived(event: ParallEvent): Promise<void>;
+  runDispatch(
+    event: ParallEvent,
+    sessionKey: string,
+    bodyForAgent: string,
+    earlierEvents?: ParallEvent[],
+    captureText?: string[],
+  ): Promise<boolean>;
+  tryClaimMessage(id: string): boolean;
+  buildMessageDispatchDecision(
+    chatId: string,
+    message: DispatchableMessage,
+  ): Promise<MessageDispatchDecision>;
+  handleInboundEvent(event: ParallEvent): Promise<boolean>;
+}
+
+/**
+ * Dispatch one group of same-lane message events under the ledger contract:
+ * claim (or reuse) the lane, run the dispatch, then complete when no local
+ * work remains for the lane. No legacy received/ack calls — the claim marks
+ * members received and complete/reply resolve them server-side.
+ */
+export async function dispatchLaneGroup(
+  host: LaneFlowHost,
+  opts: {
+    events: ParallEvent[];
+    sessionKey: string;
+    body: string;
+    earlier: ParallEvent[];
+    captureText?: string[];
+    hasMoreLocal: () => boolean;
+  },
+): Promise<'dispatched' | 'foreign' | 'shutdown'> {
+  const ledger = host.laneLedger!;
+  const event = opts.events[opts.events.length - 1];
+  let lane: Awaited<ReturnType<LaneLedger['ensureLane']>>;
+  try {
+    lane = await ledger.ensureLane(opts.events);
+  } catch (err) {
+    if (!(err instanceof LedgerUnsupportedError)) throw err;
+    // Old server: run this group through the legacy flow inline and let
+    // every later event take the legacy branch via the sticky flag.
+    host.disableLedger('claim endpoint missing');
+    await host.emitDispatchReceived(event);
+    const dispatched = await host.runDispatch(
+      event,
+      opts.sessionKey,
+      opts.body,
+      opts.earlier,
+      opts.captureText,
+    );
+    if (!dispatched) return 'shutdown';
+    for (const ev of opts.events) {
+      host.opts.client
+        .ackDispatch(host.opts.config.org_id, {
+          source_type: ev.ackSourceType ?? 'message',
+          source_id: ev.ackSourceId ?? ev.messageId,
+        })
+        .catch(() => {});
+    }
+    return 'dispatched';
+  }
+  if (!lane) {
+    // A healthy incumbent owns the resource. Free the in-memory dedupe
+    // entries so the post-complete re-drive can re-trigger these messages.
+    for (const ev of opts.events) {
+      host.dispatchedMessages.delete(ev.messageId);
+    }
+    return 'foreign';
+  }
+  let dispatched = false;
+  try {
+    dispatched = await host.runDispatch(
+      event,
+      opts.sessionKey,
+      opts.body,
+      opts.earlier,
+      opts.captureText,
+    );
+  } catch (err) {
+    // Failed turn: hand the members back so the retry (this pod or the
+    // next) re-claims immediately instead of waiting out the lease.
+    await ledger.release(lane.laneKey).catch(() => {});
+    throw err;
+  }
+  if (!dispatched) {
+    // Shutdown short-circuit — shutdown() releases all active lanes.
+    return 'shutdown';
+  }
+  const pendingInjections =
+    host.opts.dispatchAdapter.hasPendingInjections?.(opts.sessionKey) ?? false;
+  await ledger.completeIfIdle(lane.laneKey, pendingInjections || opts.hasMoreLocal());
+  return 'dispatched';
+}
+
+/**
+ * Consume one typed dispatch (task/comment/schedule/trigger/approval) under
+ * its typed-lane occupancy guard: claim the dsp:<id> lane (skip when another
+ * pod holds it or the WorkItem is already resolved), run the handler, ack on
+ * success (the doc's option (b): notification delivered, tracked elsewhere),
+ * then release the lane. Legacy run+ack flow when the ledger is unavailable.
+ */
+export async function consumeTypedDispatch(
+  host: LaneFlowHost,
+  ref: { dispatchEventId?: string; sourceType?: string; sourceId?: string },
+  run: (dispatchEventId?: string) => Promise<boolean>,
+  ack: (dispatchEventId?: string) => void,
+): Promise<void> {
+  if (!host.laneLedger || host.ledgerDisabled) {
+    if (await run(ref.dispatchEventId)) ack(ref.dispatchEventId);
+    return;
+  }
+  let lane: Awaited<ReturnType<LaneLedger['claimTyped']>>;
+  try {
+    lane = await host.laneLedger.claimTyped(ref);
+  } catch (err) {
+    if (err instanceof LedgerUnsupportedError) {
+      host.disableLedger('claim endpoint missing');
+      if (await run(ref.dispatchEventId)) ack(ref.dispatchEventId);
+      return;
+    }
+    throw err;
+  }
+  if (!lane) {
+    host.opts.log?.info(
+      `typed dispatch ${ref.dispatchEventId ?? `${ref.sourceType}:${ref.sourceId}`} not claimable (held elsewhere or already resolved) — skipping`,
+    );
+    return;
+  }
+  try {
+    if (await run(lane.typedDispatchEventId)) ack(lane.typedDispatchEventId);
+  } finally {
+    // Release the occupancy row. A buffered dispatch may outlive this guard
+    // (lane TTL) — acceptable at-least-once; the ledger's resolution paths
+    // still dedupe the persistent side effects.
+    await host.laneLedger.completeIfIdle(lane.laneKey, false).catch(() => {});
+  }
+}
+
+/**
+ * Shared consumption of a message WorkItem referenced by id — the ONE
+ * protocol for dispatch catch-up pages and post-complete re-drive hints
+ * (live first delivery stays on the message.new handler, which already has
+ * the payload). Owns: in-memory dedupe, source fetch (deleted source ⇒
+ * administrative ack), self-sender ack, decision routing, ledger-vs-legacy
+ * ack parity, and dedupe-entry cleanup on every non-dispatched path.
+ */
+export async function consumeMessageWorkItem(
+  host: LaneFlowHost,
+  item: { id: string; source_id: string; chat_id: string },
+): Promise<void> {
+  if (host.shuttingDown) return;
+  if (!host.tryClaimMessage(item.source_id)) return;
+  const ackItem = () => {
+    host.opts.client.ackDispatchByID(host.opts.config.org_id, item.id).catch(() => {});
+  };
+
+  let msg: Awaited<ReturnType<ParallClient['getMessage']>> | null = null;
+  try {
+    msg = await host.opts.client.getMessage(item.source_id);
+  } catch (err: unknown) {
+    const status = (err as { status?: number })?.status;
+    if (status !== 404) {
+      host.opts.log?.warn(
+        `message fetch failed for ${item.source_id}, leaving pending: ${String(err)}`,
+      );
+      host.dispatchedMessages.delete(item.source_id);
+      return;
+    }
+  }
+  if (!msg || msg.sender_id === host.opts.agentUserId) {
+    host.dispatchedMessages.delete(item.source_id);
+    ackItem();
+    return;
+  }
+
+  const decision = await host.buildMessageDispatchDecision(item.chat_id, msg);
+  if (decision.action === 'retry') {
+    host.dispatchedMessages.delete(item.source_id);
+    return;
+  }
+  if (decision.action === 'skip') {
+    host.dispatchedMessages.delete(item.source_id);
+    ackItem();
+    return;
+  }
+  decision.event.dispatchEventId = item.id;
+  const laneResolved = host.usesLaneLedger(decision.event);
+  try {
+    const dispatched = await host.handleInboundEvent(decision.event);
+    if (dispatched) {
+      // Ledger runs resolve server-side (reply cover / no_action sweep);
+      // when the ledger is not in effect the WorkItem still needs the
+      // legacy administrative ack — without it the row would sit pending
+      // forever on this path while catch-up would have acked it.
+      if (!laneResolved) ackItem();
+    } else {
+      host.dispatchedMessages.delete(item.source_id);
+    }
+  } catch (err) {
+    // Free the dedupe entry so a later re-drive / catch-up can retry —
+    // same cleanup contract as the other inbound handlers.
+    host.dispatchedMessages.delete(item.source_id);
+    throw err;
+  }
+}

package/src/index.ts

@@ -1,5 +1,7 @@
 export * from './provider-config.js';
 export * from './types.js';
+export * from './lane-key.js';
+export type { LaneFlowHost } from './gateway-lane-flow.js';
 export * from './session-state.js';
 export * from './routing.js';
 export * from './event-format.js';

package/src/lane-key.ts

@@ -0,0 +1,67 @@
+import * as path from 'node:path';
+
+/**
+ * Canonical lane-key encoding — the SSOT shared by the bridge (writer of
+ * `$PRLL_CONTEXT_DIR/<lane-key>.json`) and the CLI (reader, keyed by the send
+ * target). Both sides MUST use this exact function: the lane key encodes the
+ * full lane identity `(target_uri, thread_root_id)` so a channel lane and a
+ * thread lane in the same chat never collide, and base64url keeps any
+ * target_uri (including typed `dsp:<id>` resources) filesystem-safe with no
+ * escaping ambiguity.
+ */
+export function laneKeyForTarget(targetUri: string, threadRootId?: string | null): string {
+  return Buffer.from(`${targetUri}\n${threadRootId ?? ''}`, 'utf8').toString('base64url');
+}
+
+/**
+ * PRLL_CONTEXT_DIR root under a per-agent stateDir. Owned here alongside the
+ * lane-key encoding so the whole context-dir contract has one home; runtime
+ * bridges import this instead of re-declaring the path.
+ */
+export function dispatchLaneContextDir(stateDir: string): string {
+  return path.join(stateDir, 'dispatch-lane-context');
+}
+
+/** Path of the bridge-owned dispatch context file for a lane. */
+export function laneContextFilePath(
+  contextDir: string,
+  targetUri: string,
+  threadRootId?: string | null,
+): string {
+  return path.join(contextDir, `${laneKeyForTarget(targetUri, threadRootId)}.json`);
+}
+
+/**
+ * Path of the CLI-owned reply-state sidecar for a lane. Separate file from the
+ * bridge-owned context (two writers, two files): the bridge rewrites the
+ * context file throughout the turn (step_id updates) and would clobber any
+ * CLI state stored inline.
+ */
+export function laneReplyStateFilePath(
+  contextDir: string,
+  targetUri: string,
+  threadRootId?: string | null,
+): string {
+  return path.join(contextDir, `${laneKeyForTarget(targetUri, threadRootId)}.reply-state.json`);
+}
+
+/** Shape of the bridge-written per-lane dispatch context file. */
+export type LaneDispatchContextFile = {
+  session_id: string | null;
+  step_id: string | null;
+  chat_id: string | null;
+  trigger_message_id: string | null;
+  no_reply: boolean;
+  /** WorkItem id of the trigger — basis of the `reply:<dsp>` effect key. */
+  dispatch_event_id: string | null;
+  /** Server-minted per-turn lane token; every dispatch-bound write carries it. */
+  lane: string | null;
+  target_uri: string | null;
+  thread_root_id: string | null;
+};
+
+/** Shape of the CLI-written reply-state sidecar. */
+export type LaneReplyStateFile = {
+  dispatch_event_id: string;
+  reply_committed: boolean;
+};

package/src/lane-ledger.ts

@@ -0,0 +1,370 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { ApiError } from '@parall/sdk';
+import type { ParallClient } from '@parall/sdk';
+import type { GatewayLogger } from './dispatch-adapter.js';
+import { laneContextFilePath, laneKeyForTarget } from './lane-key.js';
+import type { ParallEvent } from './types.js';
+
+/** One claimed lane the bridge currently occupies. */
+export type ActiveLane = {
+  laneKey: string;
+  lane: string;
+  targetUri: string;
+  threadRootId?: string;
+  /** source_id (message id) → WorkItem id for members folded into this lane. */
+  folded: Map<string, string>;
+  /** WorkItem id, set for typed lanes (resource = dsp:<id>, single member). */
+  typedDispatchEventId?: string;
+  /** Lease expiry (ms epoch) and TTL from the claim — renewal pacing state. */
+  leaseUntilMs?: number;
+  leaseTtlMs?: number;
+};
+
+/**
+ * Thrown when the server predates the dispatch ledger (claim endpoint 404s
+ * during a rolling deploy). The gateway falls back to the legacy
+ * received/ack flow for the rest of its lifetime.
+ */
+export class LedgerUnsupportedError extends Error {}
+
+export type LaneGroupOutcome = 'claimed' | 'foreign';
+
+function isStaleLane(err: unknown): boolean {
+  return err instanceof ApiError && err.status === 409 && err.code === 'STALE_LANE';
+}
+
+function isNotFound(err: unknown): boolean {
+  return err instanceof ApiError && err.status === 404;
+}
+
+/**
+ * A pre-ledger server (or an edge that doesn't know the route) answers the
+ * claim endpoint with an UNSTRUCTURED 404 — no app error code. Our own
+ * handlers always attach a code, so a coded 404 is a semantic answer, not a
+ * missing endpoint. Transient edge 404s during rolling deploys are further
+ * contained by the reconnect re-probe (ledgerDisabled resets on hello).
+ */
+function isEndpointMissing(err: unknown): boolean {
+  return err instanceof ApiError && err.status === 404 && !err.code;
+}
+
+/**
+ * LaneLedger is the bridge-side client of the server dispatch ledger
+ * (docs/engineering-design/agent-dispatch-idempotency-design.md): it claims
+ * lane occupancy just-in-time before a message dispatch, folds mid-turn
+ * same-target messages via steer, completes (no_action sweep + release) when
+ * the local queue for a lane runs dry, and releases leftovers on shutdown.
+ *
+ * It is also the single writer of the per-lane dispatch context files under
+ * PRLL_CONTEXT_DIR (`<lane-key>.json`) that the CLI reads to derive dispatch
+ * effect keys. The CLI's reply-state sidecar lives next to it and is never
+ * touched here (two writers, two files).
+ */
+export class LaneLedger {
+  private readonly lanes = new Map<string, ActiveLane>();
+
+  constructor(
+    private readonly opts: {
+      client: ParallClient;
+      orgId: string;
+      contextDir: string;
+      log?: GatewayLogger;
+    },
+  ) {}
+
+  get contextDir(): string {
+    return this.opts.contextDir;
+  }
+
+  /** Only chat message events ride the lane ledger; typed events stay on the legacy ack path. */
+  handles(event: ParallEvent): boolean {
+    return event.type === 'message' && event.targetId.startsWith('cht_');
+  }
+
+  laneKeyFor(event: ParallEvent): string {
+    if (event.type !== 'message' && event.dispatchEventId) {
+      return laneKeyForTarget(`dsp:${event.dispatchEventId}`);
+    }
+    return laneKeyForTarget(`prll://${event.targetId}`, event.threadRootId);
+  }
+
+  getForEvent(event: ParallEvent): ActiveLane | undefined {
+    return this.lanes.get(this.laneKeyFor(event));
+  }
+
+  laneContextPath(lane: ActiveLane): string {
+    return laneContextFilePath(this.opts.contextDir, lane.targetUri, lane.threadRootId);
+  }
+
+  /**
+   * Claim (or reuse) the lane for a group of same-lane message events and
+   * fold every group member into it. Returns 'foreign' when a healthy
+   * incumbent (another pod) holds the resource — the caller must not
+   * dispatch; the events stay pending server-side and re-drive after the
+   * incumbent completes.
+   */
+  async ensureLane(events: ParallEvent[]): Promise<ActiveLane | null> {
+    const trigger = events[events.length - 1];
+    const laneKey = this.laneKeyFor(trigger);
+    let lane = this.lanes.get(laneKey);
+    if (!lane) {
+      const targetUri = `prll://${trigger.targetId}`;
+      let res;
+      try {
+        res = await this.opts.client.claimDispatch(this.opts.orgId, {
+          target_uri: targetUri,
+          thread_root_id: trigger.threadRootId,
+          limit: 100,
+        });
+      } catch (err) {
+        if (isEndpointMissing(err)) throw new LedgerUnsupportedError('claim endpoint unavailable');
+        throw err;
+      }
+      if (!res.claimed || !res.lane) {
+        this.opts.log?.info(
+          `lane for ${targetUri} held by a healthy incumbent — leaving events pending for re-drive`,
+        );
+        return null;
+      }
+      const leaseUntilMs = Date.parse(res.lease_until ?? '');
+      lane = {
+        laneKey,
+        lane: res.lane,
+        targetUri,
+        threadRootId: trigger.threadRootId,
+        folded: new Map(),
+        ...(Number.isNaN(leaseUntilMs)
+          ? {}
+          : { leaseUntilMs, leaseTtlMs: Math.max(leaseUntilMs - Date.now(), 60_000) }),
+      };
+      for (const ev of res.events ?? []) {
+        lane.folded.set(ev.source_id, ev.id);
+      }
+      this.lanes.set(laneKey, lane);
+    }
+
+    // Fold group members the claim didn't cover (they arrived after the
+    // claim, or this group reuses an already-active lane). Fail closed on ANY
+    // fold failure: an un-folded message dispatched now would not be covered
+    // by this lane's reply/complete, so its still-live WorkItem would re-drive
+    // later and the model would handle it twice. Releasing hands the folded
+    // members back to pending immediately; the re-drive / live hint path
+    // re-delivers the whole group under a fresh claim.
+    for (const ev of events) {
+      if (lane.folded.has(ev.messageId)) continue;
+      try {
+        const res = await this.opts.client.steerDispatch(this.opts.orgId, {
+          lane: lane.lane,
+          target_uri: lane.targetUri,
+          thread_root_id: lane.threadRootId,
+          ...(ev.dispatchEventId
+            ? { dispatch_event_id: ev.dispatchEventId }
+            : { source_type: 'message', source_id: ev.messageId }),
+        });
+        lane.folded.set(ev.messageId, res.dispatch_event_id);
+      } catch (err) {
+        if (isStaleLane(err)) {
+          // We lost the lane mid-group — drop local state; the takeover
+          // owner (or the next claim) picks the members up.
+          this.lanes.delete(laneKey);
+          return null;
+        }
+        this.opts.log?.warn(
+          `steer fold failed for ${ev.messageId} — failing closed, releasing lane: ${String(err)}`,
+        );
+        await this.release(laneKey);
+        return null;
+      }
+    }
+    return lane;
+  }
+
+  /**
+   * Fold a live mid-turn message into its active lane BEFORE injecting it
+   * into the running turn. Injection without a successful fold is forbidden —
+   * an un-folded injected message would be re-driven after complete and the
+   * model would handle it twice.
+   */
+  async steerLive(event: ParallEvent): Promise<boolean> {
+    const laneKey = this.laneKeyFor(event);
+    const lane = this.lanes.get(laneKey);
+    if (!lane) return false;
+    if (lane.folded.has(event.messageId)) return true;
+    try {
+      const res = await this.opts.client.steerDispatch(this.opts.orgId, {
+        lane: lane.lane,
+        target_uri: lane.targetUri,
+        thread_root_id: lane.threadRootId,
+        ...(event.dispatchEventId
+          ? { dispatch_event_id: event.dispatchEventId }
+          : { source_type: 'message', source_id: event.messageId }),
+      });
+      lane.folded.set(event.messageId, res.dispatch_event_id);
+      return true;
+    } catch (err) {
+      if (isStaleLane(err)) {
+        this.lanes.delete(laneKey);
+      } else {
+        this.opts.log?.warn(`live steer failed for ${event.messageId}: ${String(err)}`);
+      }
+      return false;
+    }
+  }
+
+  /**
+   * Complete the lane when no local work remains for it: the server sweeps
+   * still-leased members as no_action, releases the occupancy row, and
+   * re-drives any same-target pending work. A STALE_LANE answer means a
+   * takeover already owns the resource — local state is dropped either way.
+   */
+  async completeIfIdle(laneKey: string, hasMoreLocal: boolean): Promise<void> {
+    const lane = this.lanes.get(laneKey);
+    if (!lane || hasMoreLocal) return;
+    this.lanes.delete(laneKey);
+    this.removeLaneContext(lane);
+    try {
+      const res = await this.opts.client.completeDispatch(this.opts.orgId, {
+        lane: lane.lane,
+        target_uri: lane.targetUri,
+        thread_root_id: lane.threadRootId,
+      });
+      if (res.swept_no_action > 0 || res.redriven) {
+        this.opts.log?.info(
+          `lane complete for ${lane.targetUri}: swept ${res.swept_no_action} no_action, redriven=${res.redriven}`,
+        );
+      }
+    } catch (err) {
+      if (isStaleLane(err)) {
+        this.opts.log?.info(`lane complete skipped for ${lane.targetUri} — taken over`);
+        return;
+      }
+      // Lease expiry recovers the members; complete is not retried here.
+      this.opts.log?.warn(`lane complete failed for ${lane.targetUri}: ${String(err)}`);
+    }
+  }
+
+  /**
+   * Long-turn keepalive: renew the lane's lease on runtime activity, throttled
+   * so a chatty turn doesn't spam the server. Without this, a legitimately
+   * long turn (> lane TTL) would be dethroned mid-flight and every subsequent
+   * write misfired with STALE_LANE — the design doc's "long turns renew via
+   * step writes". Fire-and-forget: a failed renewal is surfaced by the next
+   * write's incumbency check anyway.
+   */
+  maybeRenew(lane: ActiveLane): void {
+    const now = Date.now();
+    // Server-driven pacing: renew once less than half the lease TTL remains.
+    // Hardcoding a client-side rhythm would silently break every published
+    // runtime image the day the server shortens its lane TTL.
+    const ttl = lane.leaseTtlMs ?? 10 * 60_000;
+    const until = lane.leaseUntilMs ?? now; // unknown lease → renew now
+    if (until - now > ttl / 2) return;
+    lane.leaseUntilMs = now + ttl; // optimistic; corrected by the response
+    void this.opts.client
+      .heartbeatDispatchLane(this.opts.orgId, {
+        lane: lane.lane,
+        target_uri: lane.targetUri,
+        thread_root_id: lane.threadRootId,
+      })
+      .then((res) => {
+        const until = Date.parse(res?.lease_until ?? '');
+        if (!Number.isNaN(until)) lane.leaseUntilMs = until;
+      })
+      .catch((err) => {
+        if (isStaleLane(err)) {
+          this.lanes.delete(lane.laneKey);
+          this.opts.log?.warn(`lane ${lane.targetUri} was taken over during the turn`);
+          return;
+        }
+        this.opts.log?.warn(`lane heartbeat failed for ${lane.targetUri}: ${String(err)}`);
+      });
+  }
+
+  /**
+   * Release a lane's unresolved members back to pending (dispatch error /
+   * shutdown) so the next pod re-claims immediately instead of waiting out
+   * the lease.
+   */
+  async release(laneKey: string): Promise<void> {
+    const lane = this.lanes.get(laneKey);
+    if (!lane) return;
+    this.lanes.delete(laneKey);
+    this.removeLaneContext(lane);
+    try {
+      await this.opts.client.releaseDispatchLane(this.opts.orgId, lane.lane);
+    } catch (err) {
+      this.opts.log?.warn(`lane release failed for ${lane.targetUri}: ${String(err)}`);
+    }
+  }
+
+  async releaseAll(): Promise<void> {
+    const keys = [...this.lanes.keys()];
+    for (const key of keys) {
+      await this.release(key);
+    }
+  }
+
+  /** True when any lane is currently active (used by shutdown logging). */
+  get activeCount(): number {
+    return this.lanes.size;
+  }
+
+  /**
+   * Claim the single-member lane of one typed WorkItem (resource = dsp:<id>),
+   * by WorkItem id or by source identity (the live task.assigned event has no
+   * WorkItem id). Returns null when a healthy incumbent (another pod) holds
+   * it or the WorkItem is already resolved — the caller must skip processing.
+   */
+  async claimTyped(ref: {
+    dispatchEventId?: string;
+    sourceType?: string;
+    sourceId?: string;
+  }): Promise<ActiveLane | null> {
+    let res;
+    try {
+      res = await this.opts.client.claimDispatch(this.opts.orgId, {
+        dispatch_event_id: ref.dispatchEventId,
+        source_type: ref.dispatchEventId ? undefined : ref.sourceType,
+        source_id: ref.dispatchEventId ? undefined : ref.sourceId,
+      });
+    } catch (err) {
+      if (isEndpointMissing(err)) throw new LedgerUnsupportedError('claim endpoint unavailable');
+      throw err;
+    }
+    if (!res.claimed || !res.lane || !res.events?.length) return null;
+    const workItem = res.events[0];
+    const targetUri = `dsp:${workItem.id}`;
+    const leaseUntilMs = Date.parse(res.lease_until ?? '');
+    const lane: ActiveLane = {
+      laneKey: laneKeyForTarget(targetUri),
+      lane: res.lane,
+      targetUri,
+      folded: new Map([[workItem.source_id, workItem.id]]),
+      typedDispatchEventId: workItem.id,
+      ...(Number.isNaN(leaseUntilMs)
+        ? {}
+        : { leaseUntilMs, leaseTtlMs: Math.max(leaseUntilMs - Date.now(), 60_000) }),
+    };
+    this.lanes.set(lane.laneKey, lane);
+    return lane;
+  }
+
+  /**
+   * Remove the per-lane context file (and its CLI sidecar) when the lane
+   * ends. A leftover file would make a later cross-context send to the same
+   * target bind a dead lane token and misfire with STALE_LANE instead of
+   * taking the plain non-ledger path.
+   */
+  private removeLaneContext(lane: ActiveLane): void {
+    const contextPath = this.laneContextPath(lane);
+    for (const p of [contextPath, contextPath.replace(/\.json$/, '.reply-state.json')]) {
+      try {
+        fs.rmSync(p, { force: true });
+      } catch {
+        // Best-effort: a stale file only re-surfaces as a server-side
+        // STALE_LANE, never as a wrong write.
+      }
+    }
+  }
+}

package/src/types.ts

@@ -84,6 +84,8 @@ export type ParallEvent = {
     | 'external_trigger_run'
     | 'channel_message';
   ackSourceId?: string;
+  /** WorkItem id, when known (dispatch catch-up / re-drive hints carry it; live message.new does not). */
+  dispatchEventId?: string;
   /** Unread message count in the target chat since agent's last interaction. */
   unreadCount?: number;
   /** Channel cursor: the last message ID the agent read. */