@parall/agent-core 1.45.0 → 1.47.0

package/dist/step-retry-queue.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Per-session FIFO retry queue for AgentStep writes.
+ *
+ * Step creation runs serially inside the dispatch drain loop, so a blocking
+ * retry there would stall healthy runtime work behind a degraded api link
+ * (the 2026-07-10 window: model calls fine, every fresh parall HTTPS
+ * handshake timing out). Instead, a failed write is parked here and retried
+ * in the background with backoff; while a session has parked items, new
+ * writes for that session are appended behind them so ledger order is
+ * preserved. All step requests carry an `idempotency_key`, which makes
+ * retries safe even when the original attempt landed server-side but its
+ * response was lost.
+ *
+ * In-memory only — a process restart drops parked items (the ledger hole is
+ * then no worse than the pre-queue behavior). Items are dropped, loudly, when
+ * they exceed `maxAgeMs` or the per-session cap.
+ */
+export type StepRetryQueueOpts = {
+    log?: {
+        warn: (msg: string) => void;
+    };
+    /** Transient failures worth retrying (timeouts, network, 5xx). */
+    isRetryable: (err: unknown) => boolean;
+    /** Session is dead (SESSION_NOT_LIVE / INVALID_TRANSITION) — drop its queue. */
+    isSessionStale: (err: unknown) => boolean;
+    /** Invoked once when a retry discovers a stale session. */
+    onSessionStale?: (sessionId: string, err: unknown) => void;
+    /** Drop an item once it has been parked this long. Default 10 minutes. */
+    maxAgeMs?: number;
+    /** Per-session cap; enqueue beyond it drops the NEW item. Default 200. */
+    maxQueueLength?: number;
+    /** Backoff schedule override (tests). Default 5s→10s→20s→40s→60s. */
+    retryDelaysMs?: number[];
+};
+/**
+ * How a session's queue reached quiescence: `drained` — every parked item
+ * settled (written, or dropped loudly by age/cap/non-retryable policy);
+ * `dropped` — the queue was discarded because the server considers the
+ * session terminal (stale 409, `agent.new_session`); `disposed` — the queue
+ * was shut down mid-wait.
+ */
+export type StepDrainOutcome = 'drained' | 'dropped' | 'disposed';
+export declare class StepRetryQueue {
+    private readonly opts;
+    private readonly queues;
+    private readonly timers;
+    private readonly drains;
+    private readonly drainWaiters;
+    private readonly retryDelays;
+    private disposed;
+    constructor(opts: StepRetryQueueOpts);
+    hasPending(sessionId: string): boolean;
+    pendingCount(sessionId: string): number;
+    enqueue(sessionId: string, label: string, exec: () => Promise<void>): void;
+    dropSession(sessionId: string): void;
+    /**
+     * Resolves when this session's queue reaches quiescence: every parked item
+     * settled (`drained` — including items dropped loudly by the age/cap/
+     * non-retryable policy), the queue was discarded because the server
+     * considers the session terminal (`dropped`), or the queue was disposed
+     * (`disposed`). Retries keep riding the normal backoff schedule while a
+     * caller waits — this only OBSERVES the queue, it never accelerates or
+     * abandons it.
+     */
+    awaitSessionDrained(sessionId: string): Promise<StepDrainOutcome>;
+    pendingTotal(): number;
+    /**
+     * One best-effort pass over every parked item — no backoff waits. Used at
+     * graceful shutdown: parked items are process-local (their WorkItems
+     * already resolved, so restart catch-up will NOT re-drive them), and the
+     * common shutdown (idle-stop, deploy) happens on a healthy network where
+     * the writes just succeed. A session whose head still fails retryably is
+     * skipped (its remaining items would fail the same way). A drain already in
+     * flight when flush arrives is JOINED (drain() returns the shared promise),
+     * so flush waits for its settle within the deadline instead of misreading
+     * "no progress" and giving up early. `deadlineMs` is a HARD cap: a write
+     * still in flight at the deadline is abandoned to the background (it is
+     * idempotent; dispose() right after clears any re-arm) and flush returns.
+     * Returns the number of items still parked.
+     */
+    flush(deadlineMs: number): Promise<number>;
+    /** Every tracked session is dead (server closed them all — new_session). */
+    dropAllSessions(): void;
+    dispose(): void;
+    private schedule;
+    private drain;
+    private drainOnce;
+    private rearm;
+    private resolveDrainWaiters;
+}
+//# sourceMappingURL=step-retry-queue.d.ts.map

package/dist/step-retry-queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"step-retry-queue.d.ts","sourceRoot":"","sources":["../src/step-retry-queue.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,GAAG,CAAC,EAAE;QAAE,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;KAAE,CAAC;IACtC,kEAAkE;IAClE,WAAW,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC;IACvC,gFAAgF;IAChF,cAAc,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC;IAC1C,2DAA2D;IAC3D,cAAc,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,KAAK,IAAI,CAAC;IAC3D,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,0EAA0E;IAC1E,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,qEAAqE;IACrE,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B,CAAC;AASF;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,SAAS,GAAG,UAAU,CAAC;AAgBlE,qBAAa,cAAc;IAgBb,OAAO,CAAC,QAAQ,CAAC,IAAI;IAfjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmC;IAC1D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqC;IAQ5D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoC;IAE3D,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAiE;IAC9F,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAW;IACvC,OAAO,CAAC,QAAQ,CAAS;gBAEI,IAAI,EAAE,kBAAkB;IAIrD,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAItC,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM;IAIvC,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI;IAe1E,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAYpC;;;;;;;;OAQG;IACH,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAYjE,YAAY,IAAI,MAAM;IAMtB;;;;;;;;;;;;;OAaG;IACG,KAAK,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAuBhD,4EAA4E;IAC5E,eAAe,IAAI,IAAI;IAIvB,OAAO,IAAI,IAAI;IAUf,OAAO,CAAC,QAAQ;IAchB,OAAO,CAAC,KAAK;YAeC,SAAS;IA4CvB,OAAO,CAAC,KAAK;IAkBb,OAAO,CAAC,mBAAmB;CAM5B"}

package/dist/step-retry-queue.js

@@ -0,0 +1,259 @@
+/**
+ * Per-session FIFO retry queue for AgentStep writes.
+ *
+ * Step creation runs serially inside the dispatch drain loop, so a blocking
+ * retry there would stall healthy runtime work behind a degraded api link
+ * (the 2026-07-10 window: model calls fine, every fresh parall HTTPS
+ * handshake timing out). Instead, a failed write is parked here and retried
+ * in the background with backoff; while a session has parked items, new
+ * writes for that session are appended behind them so ledger order is
+ * preserved. All step requests carry an `idempotency_key`, which makes
+ * retries safe even when the original attempt landed server-side but its
+ * response was lost.
+ *
+ * In-memory only — a process restart drops parked items (the ledger hole is
+ * then no worse than the pre-queue behavior). Items are dropped, loudly, when
+ * they exceed `maxAgeMs` or the per-session cap.
+ */
+const DEFAULT_RETRY_DELAYS_MS = [5_000, 10_000, 20_000, 40_000, 60_000];
+async function raceWithDeadline(work, ms) {
+    let timer;
+    const timeout = new Promise((resolve) => {
+        timer = setTimeout(() => resolve('timeout'), Math.max(0, ms));
+    });
+    try {
+        return await Promise.race([work, timeout]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export class StepRetryQueue {
+    opts;
+    queues = new Map();
+    timers = new Map();
+    // Per-session in-flight drain promise. At most ONE drain may be active per
+    // session: a second one would re-run the same head and the two shift()
+    // calls would silently discard the next queued item. schedule() is a no-op
+    // while a drain is in flight; a concurrent drain() call JOINS the in-flight
+    // promise (flush must be able to await a background drain instead of
+    // misreading it as "no progress"); the drain's finally re-arms from live
+    // map state.
+    drains = new Map();
+    // Callers awaiting a session's quiescence (awaitSessionDrained).
+    drainWaiters = new Map();
+    retryDelays;
+    disposed = false;
+    constructor(opts) {
+        this.opts = opts;
+        this.retryDelays = opts.retryDelaysMs?.length ? opts.retryDelaysMs : DEFAULT_RETRY_DELAYS_MS;
+    }
+    hasPending(sessionId) {
+        return (this.queues.get(sessionId)?.length ?? 0) > 0;
+    }
+    pendingCount(sessionId) {
+        return this.queues.get(sessionId)?.length ?? 0;
+    }
+    enqueue(sessionId, label, exec) {
+        if (this.disposed)
+            return;
+        const queue = this.queues.get(sessionId) ?? [];
+        const cap = this.opts.maxQueueLength ?? 200;
+        if (queue.length >= cap) {
+            this.opts.log?.warn(`step retry queue full for session ${sessionId} (${cap}); dropping ${label} step permanently`);
+            return;
+        }
+        queue.push({ label, exec, enqueuedAt: Date.now(), attempts: 0 });
+        this.queues.set(sessionId, queue);
+        this.schedule(sessionId, this.retryDelays[0] ?? 5_000);
+    }
+    dropSession(sessionId) {
+        const queue = this.queues.get(sessionId);
+        if (queue?.length) {
+            this.opts.log?.warn(`dropping ${queue.length} queued step(s) for session ${sessionId}`);
+        }
+        this.queues.delete(sessionId);
+        const timer = this.timers.get(sessionId);
+        if (timer)
+            clearTimeout(timer);
+        this.timers.delete(sessionId);
+        this.resolveDrainWaiters(sessionId, 'dropped');
+    }
+    /**
+     * Resolves when this session's queue reaches quiescence: every parked item
+     * settled (`drained` — including items dropped loudly by the age/cap/
+     * non-retryable policy), the queue was discarded because the server
+     * considers the session terminal (`dropped`), or the queue was disposed
+     * (`disposed`). Retries keep riding the normal backoff schedule while a
+     * caller waits — this only OBSERVES the queue, it never accelerates or
+     * abandons it.
+     */
+    awaitSessionDrained(sessionId) {
+        if (this.disposed)
+            return Promise.resolve('disposed');
+        if (this.pendingCount(sessionId) === 0 && !this.drains.has(sessionId)) {
+            return Promise.resolve('drained');
+        }
+        return new Promise((resolve) => {
+            const waiters = this.drainWaiters.get(sessionId) ?? [];
+            waiters.push(resolve);
+            this.drainWaiters.set(sessionId, waiters);
+        });
+    }
+    pendingTotal() {
+        let total = 0;
+        for (const queue of this.queues.values())
+            total += queue.length;
+        return total;
+    }
+    /**
+     * One best-effort pass over every parked item — no backoff waits. Used at
+     * graceful shutdown: parked items are process-local (their WorkItems
+     * already resolved, so restart catch-up will NOT re-drive them), and the
+     * common shutdown (idle-stop, deploy) happens on a healthy network where
+     * the writes just succeed. A session whose head still fails retryably is
+     * skipped (its remaining items would fail the same way). A drain already in
+     * flight when flush arrives is JOINED (drain() returns the shared promise),
+     * so flush waits for its settle within the deadline instead of misreading
+     * "no progress" and giving up early. `deadlineMs` is a HARD cap: a write
+     * still in flight at the deadline is abandoned to the background (it is
+     * idempotent; dispose() right after clears any re-arm) and flush returns.
+     * Returns the number of items still parked.
+     */
+    async flush(deadlineMs) {
+        const deadline = Date.now() + deadlineMs;
+        const timeLeft = () => deadline - Date.now();
+        let timedOut = false;
+        for (const sessionId of [...this.queues.keys()]) {
+            while (!this.disposed && !timedOut && timeLeft() > 0) {
+                const before = this.pendingCount(sessionId);
+                if (before === 0)
+                    break;
+                const outcome = await raceWithDeadline(this.drain(sessionId).then(() => 'drained'), timeLeft());
+                if (outcome === 'timeout') {
+                    timedOut = true;
+                    break;
+                }
+                if (this.pendingCount(sessionId) >= before)
+                    break;
+            }
+            if (this.disposed || timedOut || timeLeft() <= 0)
+                break;
+        }
+        return this.pendingTotal();
+    }
+    /** Every tracked session is dead (server closed them all — new_session). */
+    dropAllSessions() {
+        for (const sessionId of [...this.queues.keys()])
+            this.dropSession(sessionId);
+    }
+    dispose() {
+        this.disposed = true;
+        for (const timer of this.timers.values())
+            clearTimeout(timer);
+        this.timers.clear();
+        this.queues.clear();
+        for (const sessionId of [...this.drainWaiters.keys()]) {
+            this.resolveDrainWaiters(sessionId, 'disposed');
+        }
+    }
+    schedule(sessionId, delayMs) {
+        // No timer while a drain is in flight — its finally re-arms from live
+        // state, so arming here would start a second concurrent drain.
+        if (this.disposed || this.timers.has(sessionId) || this.drains.has(sessionId))
+            return;
+        const timer = setTimeout(() => {
+            this.timers.delete(sessionId);
+            void this.drain(sessionId);
+        }, delayMs);
+        timer.unref?.();
+        this.timers.set(sessionId, timer);
+    }
+    // At most one drain per session; a concurrent call joins the in-flight
+    // promise so callers (flush) await the real settle instead of a no-op.
+    drain(sessionId) {
+        const inFlight = this.drains.get(sessionId);
+        if (inFlight)
+            return inFlight;
+        const run = (async () => {
+            try {
+                await this.drainOnce(sessionId);
+            }
+            finally {
+                this.drains.delete(sessionId);
+                this.rearm(sessionId);
+            }
+        })();
+        this.drains.set(sessionId, run);
+        return run;
+    }
+    async drainOnce(sessionId) {
+        const queue = this.queues.get(sessionId);
+        const head = queue?.[0];
+        if (!queue || !head) {
+            if (queue)
+                this.queues.delete(sessionId);
+            return;
+        }
+        const maxAgeMs = this.opts.maxAgeMs ?? 10 * 60_000;
+        if (Date.now() - head.enqueuedAt > maxAgeMs) {
+            this.opts.log?.warn(`giving up on ${head.label} step for session ${sessionId} after ${head.attempts} retries (parked > ${Math.round(maxAgeMs / 1000)}s); step permanently lost`);
+            queue.shift();
+            return;
+        }
+        head.attempts += 1;
+        try {
+            await head.exec();
+            // The session may have been dropped (or the queue replaced) while
+            // exec was in flight — only mutate the queue we started with if it
+            // is still the live one.
+            if (this.queues.get(sessionId) === queue)
+                queue.shift();
+        }
+        catch (err) {
+            if (this.opts.isSessionStale(err)) {
+                this.dropSession(sessionId);
+                this.opts.onSessionStale?.(sessionId, err);
+                return;
+            }
+            if (this.queues.get(sessionId) !== queue)
+                return;
+            if (!this.opts.isRetryable(err)) {
+                this.opts.log?.warn(`dropping ${head.label} step for session ${sessionId} (non-retryable): ${String(err)}`);
+                queue.shift();
+            }
+            // Retryable: keep the head in place for the next pass.
+        }
+    }
+    // Single re-arm point after a drain settles, reading LIVE map state (the
+    // queue may have been dropped, or grown, while exec was awaited). Also the
+    // single point that observes quiescence for awaitSessionDrained: it runs
+    // after EVERY drain settle, so an emptied (or already-dropped) queue always
+    // resolves its waiters here.
+    rearm(sessionId) {
+        const queue = this.queues.get(sessionId);
+        if (!queue || queue.length === 0) {
+            if (queue)
+                this.queues.delete(sessionId);
+            this.resolveDrainWaiters(sessionId, 'drained');
+            return;
+        }
+        const head = queue[0];
+        if (!head)
+            return;
+        // A fresh head (previous item succeeded or was dropped) drains quickly;
+        // a head that just failed a retryable attempt backs off by its attempts.
+        const delay = head.attempts === 0
+            ? Math.min(250, this.retryDelays[0] ?? 250)
+            : (this.retryDelays[Math.min(head.attempts, this.retryDelays.length - 1)] ?? 60_000);
+        this.schedule(sessionId, delay);
+    }
+    resolveDrainWaiters(sessionId, outcome) {
+        const waiters = this.drainWaiters.get(sessionId);
+        if (!waiters?.length)
+            return;
+        this.drainWaiters.delete(sessionId);
+        for (const resolve of waiters)
+            resolve(outcome);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parall/agent-core",
-  "version": "1.45.0",
+  "version": "1.47.0",
   "description": "Shared agent runtime orchestration helpers for Parall",
   "license": "MIT",
   "repository": {
@@ -35,7 +35,8 @@
     "@opentelemetry/sdk-logs": "^0.57.0",
     "@opentelemetry/sdk-metrics": "^1.30.0",
     "@opentelemetry/sdk-trace-node": "^1.30.0",
-    "@parall/sdk": "1.45.0"
+    "undici": "^7.24.8",
+    "@parall/sdk": "1.47.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/src/channel-capability.ts

@@ -24,6 +24,22 @@ import type { AgentCapability } from './platform-config.js';
 
 export const CAPABILITY_FEISHU_CLI = 'feishu-cli';
 
+// Slack's channel capability key (tier B): the affordance is the platform
+// verb `parall slack send`, not a vendor CLI — there is no `slack-cli` and
+// no PATH shim to reconcile. The key exists here so event-hint routing
+// (gateway-base) can map provider → capability without pattern-matching on
+// a `-cli` suffix slack will never have.
+export const CAPABILITY_SLACK_SEND = 'slack-send';
+
+// channelCapabilityKeyFor maps a channel provider to the capability key the
+// server declares for it in agents.capabilities[] — the SSOT for the
+// per-provider reply-affordance lookup. Unknown providers fall back to the
+// `<provider>-cli` convention (the tier-A shape).
+export function channelCapabilityKeyFor(provider: string): string {
+  if (provider === 'slack') return CAPABILITY_SLACK_SEND;
+  return `${provider}-cli`;
+}
+
 // Marker embedded in every generated pointer. channel-exec skips any PATH
 // candidate whose head carries it, so a pointer (or a stray copy of one) can
 // never be mistaken for the real vendor binary — self-recursion is

package/src/dispatch-adapter.ts

@@ -105,6 +105,16 @@ export interface DispatchAdapter {
   /** Dispatch a Parall event to the runtime and emit normalized runtime events. */
   dispatch(opts: DispatchOpts): AsyncIterable<RuntimeEvent>;
 
+  /**
+   * True when dispatch() presents `earlierEvents` to the model itself (e.g.
+   * OpenClaw maps them into native InboundHistory). The gateway then must
+   * NOT concatenate a buffered typed group's earlier bodies into
+   * bodyForAgent — the model would see every earlier member twice. Adapters
+   * without this flag (claude/codex) only persist earlier events as input
+   * steps, so the concatenated body is the model's only route to them.
+   */
+  earlierEventsInPrompt?: boolean;
+
   /**
    * Inject a user message into the running runtime mid-turn so it steers
    * immediately, rather than waiting for the current turn to complete.

package/src/event-format.ts

@@ -175,14 +175,34 @@ function buildSendMessageHint(event: ParallEvent): string {
   }
 
   if (event.type === 'channel_message') {
-    // Single-path routing (multi-channel-architecture-design §6): with the
-    // `<provider>-cli` capability granted, the vendor CLI on PATH is THE
-    // reply path; without it there is no outbound path at all — say so
-    // instead of pointing at the retired provider clip.
-    // channelCliCapable alone decides: only feishu mints exist today, so a
-    // live grant implies Feishu even when the cosmetic provider-label lookup
-    // failed (event.channelProvider undefined).
+    // Single-path routing (multi-channel-architecture-design §6/§8.2): with
+    // the channel capability granted, that provider's affordance is THE
+    // reply path — feishu (tier A) = the vendor CLI on PATH, slack (tier B)
+    // = the `parall slack send` platform verb; without a grant there is no
+    // outbound path at all — say so instead of pointing at a retired clip.
     if (event.channelCliCapable) {
+      if (event.channelProvider === 'slack') {
+        const channelArg = event.channelExternalConversationId
+          ? ` --channel "${event.channelExternalConversationId}"`
+          : ' --channel <conversation id from this event>';
+        // Anchor the reply onto THIS inbound message whenever its id is
+        // known: in channels --reply-to is REQUIRED (the send lands in that
+        // message's thread), in DMs it is accepted and harmless (linear).
+        const replyTo = event.channelExternalMessageId
+          ? ` --reply-to "${event.channelExternalMessageId}"`
+          : '';
+        return `\n<system-reminder>To reply, use the platform verb: \`parall slack send${channelArg}${replyTo} --text <your reply>\`. In channels --reply-to is REQUIRED (the reply lands in that message's thread); in DMs it is optional (DMs are linear). \`parall slack send\` is the ONLY outbound path — your plain text output is NOT delivered to the external conversation.</system-reminder>`;
+      }
+      if (!event.channelProvider) {
+        // Cosmetic provider-label miss (the connection lookup transiently
+        // failed): a live grant means outbound IS available, but naming one
+        // vendor's command here could point a Slack conversation at
+        // lark-cli (or vice versa). Stay vendor-neutral and defer to the
+        // capability declaration already in the system prompt.
+        return `\n<system-reminder>To reply, use the channel capability granted in your system prompt — for Feishu conversations that is \`lark-cli im\`, for Slack it is \`parall slack send\` (pass the message id from this event as --reply-to). That capability is the ONLY outbound path — your plain text output is NOT delivered to the external conversation.</system-reminder>`;
+      }
+      // Known non-slack provider → the tier-A vendor-CLI shape (feishu is
+      // the only tier-A channel today).
       const convRef = event.channelExternalConversationId
         ? `chat_id "${event.channelExternalConversationId}"`
         : 'the conversation id named in this event';

package/src/fork-session-finalizer.ts

@@ -0,0 +1,122 @@
+import type { SessionCloseOutcome, SessionCloseResult } from './session-lifecycle.js';
+import type { StepDrainOutcome } from './step-retry-queue.js';
+
+/**
+ * ForkSessionFinalizer — the application use case for NORMAL fork teardown.
+ *
+ * The gateway used to inline this as `dropSession() + closeSession() +
+ * delete binding`, which destroyed steps parked for retry (dropSession) and
+ * released ownership after one close attempt regardless of whether the close
+ * actually landed. The finalizer owns the ordered sequence instead:
+ *
+ *   seal step writes            (no new steps once finalization begins)
+ *     → drain pending/in-flight step writes (every parked step ACKed —
+ *       or settled by the queue's loud age/cap policy — before close)
+ *     → close the server session (structured outcome; ownership held
+ *       through `retrying` until the close reaches a terminal fate)
+ *     → release the session binding (the caller-supplied `release`)
+ *
+ * Invariants: normal finalization NEVER calls the destructive dropSession on
+ * the step queue; `closed` is never sent while step writes are pending; the
+ * binding is released only after the close reached a terminal fate. A
+ * server-terminal signal during drain or close (`stale`) means the session
+ * is already dead server-side: local state is cleaned and released without a
+ * close write. A permanent close failure is released too — but LOUDLY: the
+ * server-side session may remain non-closed until superseded; a durable fix
+ * is the #1879 outbox/turn-fence work, not silent retries here.
+ *
+ * `agent.new_session` is NOT this use case — the server has already closed
+ * every session, so the gateway's dropAllSessions() forced-reset semantics
+ * are correct there.
+ *
+ * Process-local, best-effort scope (same as the retry queue): a process exit
+ * mid-finalization loses whatever is still parked.
+ */
+
+export type ForkFinalizeOutcome = SessionCloseOutcome;
+
+export type ForkSessionFinalizerOpts = {
+  steps: {
+    seal(sessionId: string): void;
+    unseal(sessionId: string): void;
+    drainSession(sessionId: string): Promise<StepDrainOutcome>;
+  };
+  lifecycle: {
+    closeSession(sessionId: string): Promise<SessionCloseResult>;
+    dropSession(sessionId: string): void;
+  };
+  log?: { warn: (msg: string) => void; error?: (msg: string) => void };
+};
+
+export class ForkSessionFinalizer {
+  // Ownership ledger: a session being finalized has exactly one finalization
+  // in flight; a duplicate finalize() joins it (cleanupFork-style idempotence).
+  private readonly active = new Map<string, Promise<ForkFinalizeOutcome>>();
+
+  constructor(private readonly opts: ForkSessionFinalizerOpts) {}
+
+  /** True while this finalizer still owns the session's teardown. */
+  isFinalizing(sessionId: string): boolean {
+    return this.active.has(sessionId);
+  }
+
+  activeCount(): number {
+    return this.active.size;
+  }
+
+  /**
+   * Run the ordered teardown for one fork session. `release` is invoked
+   * exactly once, only when finalization reaches a terminal state — never
+   * while step writes are pending or a close retry is still owned here.
+   */
+  finalize(sessionId: string, release: () => void): Promise<ForkFinalizeOutcome> {
+    const existing = this.active.get(sessionId);
+    if (existing) return existing;
+    const run = this.run(sessionId, release).finally(() => {
+      this.active.delete(sessionId);
+    });
+    this.active.set(sessionId, run);
+    return run;
+  }
+
+  private async run(sessionId: string, release: () => void): Promise<ForkFinalizeOutcome> {
+    this.opts.steps.seal(sessionId);
+    try {
+      const drained = await this.opts.steps.drainSession(sessionId);
+      if (drained === 'dropped') {
+        // Server-terminal (stale 409 / new_session) — the session is already
+        // dead server-side; a close write would only 409. Clean up locally.
+        this.opts.lifecycle.dropSession(sessionId);
+        release();
+        return 'stale';
+      }
+      if (drained === 'disposed') {
+        // Shutdown raced the finalization; the gateway's flush/dispose path
+        // owns whatever remains.
+        release();
+        return 'disposed';
+      }
+
+      const close = await this.opts.lifecycle.closeSession(sessionId);
+      const terminal = close.outcome === 'retrying' ? await close.terminal : close.outcome;
+      if (terminal === 'permanent_failure') {
+        // Explicit failure policy: release local ownership, but never
+        // silently — the server-side session may sit non-closed until a new
+        // session supersedes it. Process-local retries are exhausted; the
+        // durable answer is the #1879 outbox/turn-fence work.
+        const msg =
+          `fork session ${sessionId} close failed permanently after retries; ` +
+          'releasing local ownership — the server-side session may remain ' +
+          'non-closed until superseded (tracked structurally in #1879)';
+        (this.opts.log?.error ?? this.opts.log?.warn)?.(msg);
+      }
+      release();
+      return terminal;
+    } finally {
+      // Reclaim the seal in every exit path — the sealed set must not grow
+      // on a daemon churning fork sessions. Late writes against the (now
+      // closed/stale) session are rejected server-side with a 409.
+      this.opts.steps.unseal(sessionId);
+    }
+  }
+}