@qwen-code/channel-qqbot 0.26.0 → 0.26.1

package/dist/QQChannel.d.ts

@@ -65,6 +65,14 @@ export declare class QQChannel extends ChannelBase {
     private inboundReplyContext;
     /** msg_seq counter per user messageId, for multi-block streaming. */
     private msgSeqMap;
+    /**
+     * Anchored sends currently in flight, keyed by the msgId whose msg_seq
+     * counter they hold (refcounted: two sessions may send under one msgId).
+     * Covers sends that own no streamState entry — the terminal send in
+     * onResponseComplete and the stale-entry branch — which flushingSessions
+     * (session-keyed) cannot see.
+     */
+    private inFlightMsgSeqSends;
     /** Periodic cleanup timer for expired replyMsgId entries. */
     private replyMsgIdCleanupTimer;
     /** 5-minute TTL for replyMsgId entries and seenMessages dedup. */
@@ -75,8 +83,18 @@ export declare class QQChannel extends ChannelBase {
     private maxFlushRetries;
     /** Retry delay for subsequent attempts (backoff beyond first retry). */
     private static readonly IDLE_FLUSH_BACKOFF_MS;
+    /**
+     * Foreground ceiling for the completion-path final segment when
+     * maxFlushRetries is the documented "unlimited" (<= 0). The fire-and-forget
+     * flush paths may retry forever because no caller awaits them, but a
+     * completion send is awaited inside the turn's try, so its readiness to give
+     * up decides when that turn's finally runs and the session lock is released.
+     */
+    private static readonly FINAL_SEGMENT_ROUTE_ATTEMPTS;
     /** Max buffer length before forcing an immediate flush. */
     private static readonly MAX_BUFFER_LENGTH;
+    /** Purge records kept in the rescue file, oldest dropped first. */
+    private static readonly MAX_PURGE_RECORDS;
     /** Per-group bot OPENID map for multi-group support. */
     private botOpenIdByGroup;
     /** Dedup set for unexpected senderOpenId format warnings (key: `${chatId}:${senderOpenId}`). */
@@ -122,6 +140,29 @@ export declare class QQChannel extends ChannelBase {
      *   - flushedSessions tracks already-sent sessions to skip final fullText
      */
     private streamState;
+    /**
+     * Per-session reply msgId anchor, kept across idle-flush buffer windows.
+     * Set deterministically in onPromptStart from the triggering message's
+     * id (the same event.id setReplyMsgId stores) and released when the
+     * response completes, fails permanently, or the session dies. Entries
+     * carry a timestamp so readers (onResponseChunk / onResponseComplete)
+     * can drop anchors past the 5-minute TTL and fall back to the active
+     * send path — a slow turn must never keep sending chunks with an
+     * expired msg_id. Because it outlives individual streamState entries, a
+     * concurrent message in the same chat that overwrites the chat-level
+     * replyMsgId entry mid-stream cannot re-parent this session's later
+     * chunks onto its own msg_id (see PR #6457 review).
+     */
+    private sessionReplyMsgId;
+    /**
+     * Monotonic turn counter per session, bumped on every onPromptStart.
+     * streamState entries carry the turn they were created in; when a new
+     * prompt starts on a session whose previous turn left a streamState entry
+     * behind (deferred send still settling), onResponseChunk uses this counter
+     * to detect and drop the stale entry so the new turn's chunks cannot be
+     * appended to the old turn's buffer or delivered under its msgId.
+     */
+    private turnCounter;
     private flushingSessions;
     private pendingStreamDelete;
     private _reconnectId;
@@ -139,6 +180,56 @@ export declare class QQChannel extends ChannelBase {
      * finally, even on error/cancel), independent of streaming config.
      */
     private activePromptSessions;
+    /**
+     * Side buffer for chunks arriving while a previous turn's deferred flush
+     * chain still owns the session's streamState entry (the stale parked
+     * early-return in onResponseChunk). Each entry records the turn that owns
+     * its text, so a teardown can tell a live turn's stashed HEAD — which must
+     * still be delivered — from a superseded turn's leftovers, which are
+     * discarded with a log. The chunks are prepended to the owning turn's next
+     * state entry once the chain settles and frees the entry, so the HEAD of a
+     * reply is never silently dropped during the chain's settle window (up to
+     * ~10s under rate-limit backoff). A teardown may only drop an entry whose
+     * turn is not the live turn. The consumption sites are onResponseChunk
+     * (the next turn's first chunk folds the stash in), onResponseComplete (the
+     * owning turn's completion prepends the sealed `pre`), and onPromptEnd's two
+     * branches: a cancelled turn merges the stash into its residual buffer, or —
+     * when a parked chain can still deliver it — hands it to
+     * deliverCancelledStash instead.
+     * `pre` seals the portion accumulated before the most recent
+     * responseBoundary: the bridge accumulates every textChunk and only a
+     * boundary clears that collection, so at completion only that sealed
+     * portion is missing from fullText — the post-boundary remainder is already
+     * there and must not be prepended a second time. It is absent until a
+     * boundary fires for the entry. Entries are cleared when the session dies
+     * or the channel disconnects.
+     */
+    private streamOrphanBuffer;
+    /**
+     * The turn whose onResponseComplete has already run, per session. The
+     * completion that prepends a turn's stash cannot run a second time, so a
+     * stash tagged with that turn has no guaranteed consumer, and
+     * handOffSealedPre delivers its text directly instead of writing it. Dropped
+     * when a new turn starts, on session death, and on disconnect; onPromptEnd's
+     * terminal teardown drops it unless a chain still holds the session's flush
+     * marker, and a flush chain's terminal settle drops it when it still owns the
+     * generation (deleteTurnGenerationIfOwned). A teardown that finds a live
+     * marker keeps the record so that chain's handOffSealedPre can still read it;
+     * because that teardown also clears the marker, the chain's own .finally
+     * returns on its ownership check and the record is instead dropped by the
+     * next onPromptStart, onSessionDied, or disconnect.
+     */
+    private completedTurns;
+    /**
+     * Bridge-side `responseBoundary` observer. ChannelBase's own listener returns
+     * early while a cancel is pending, so onResponseBoundary can miss a boundary
+     * even though the bridge still cleared its chunk collection — the stash's
+     * `pre` would then never be sealed and the diverted head would be absent from
+     * both state.buffer and fullText. Observing the bridge event directly (the
+     * same emit the bridge's clearChunks listens to) is ungated.
+     */
+    private _bridgeBoundarySeal;
+    private bridgeBoundarySealAttached;
     private readonly qqStatePath;
     /**
      * Path to the global sessions.json managed by start.ts.
@@ -147,8 +238,42 @@ export declare class QQChannel extends ChannelBase {
     private readonly globalSessionsPath;
     /** Backup of sessions.json so conversations survive daemon restarts. */
     private readonly sessionsBackupPath;
+    /**
+     * Append-only rescue log of the routes the orphan purge deletes, written
+     * immediately before the first deletion when `purgeLegacySessions` is on, so
+     * an operator can restore a legacy conversation by hand.
+     */
+    private readonly sessionsPurgedPath;
     constructor(name: string, config: ChannelConfig & Record<string, unknown>, bridge: ChannelAgentBridge, options?: ChannelBaseOptions);
     private handleCronTextChunk;
+    /**
+     * Flush `entry`'s accumulated cron text through the delivery ladder: one
+     * send plus its two bounded retries. A successful attempt deletes the
+     * entry when its buffer is empty, or re-arms the normal flush when a chunk
+     * arrived while the send was in flight.
+     */
+    private flushCronEntry;
+    /**
+     * Terminal failure of a cron flush. Text that arrived while the failed send
+     * was in flight was never attempted, so it must not be dropped with the
+     * entry: re-arm the normal flush for that residual, exactly like the success
+     * tail. An entry that no longer owns the session was already replaced, so its
+     * successor's text is left alone, and an entry with an empty residual has
+     * nothing left to deliver — both go.
+     */
+    private dropCronEntryOrRearm;
+    /**
+     * Tail of a successful cron send. If the entry still owns the session and
+     * a chunk arrived while the send was in flight, arm the normal flush for
+     * that residual; otherwise drop the entry once its buffer is empty.
+     */
+    private settleCronFlushSuccess;
+    /**
+     * Arm the normal 2s idle flush (immediate at the buffer length limit) for
+     * `entry`, unless one is already armed. The callback re-checks that the
+     * entry still owns the session before flushing.
+     */
+    private armCronFlush;
     /**
      * Public gate for external cron/scheduler integration.
      * Wraps a cron message flow to activate `_inCronFlow` so that
@@ -167,13 +292,24 @@ export declare class QQChannel extends ChannelBase {
     handleInbound(envelope: Envelope): Promise<void>;
     sendMessage(chatId: string, text: string): Promise<void>;
     protected sendThreadMessage(chatId: string, _threadId: string | undefined, text: string, sourceLabel?: string): Promise<void>;
+    /**
+     * The reply context a session's next response would carry: the inbound
+     * message the turn is answering, resolved through the turn-scoped
+     * activePrompts entry. Read by sendResponseMessage and captured once by
+     * deliverCancelledStash, which re-attempts a delivery after that entry may
+     * already belong to a successor turn.
+     */
+    private resolveResponseReplyContext;
     protected sendResponseMessage(chatId: string, text: string, sessionId: string, sourceLabel?: string): Promise<void>;
     private sendMessageWithReplyContext;
     /**
      * Resolve API routing: handles disposed check, token refresh, chatId validation,
-     * sandbox detection, and C2C/group path selection. Returns null if any guard fails.
+     * sandbox detection, and C2C/group path selection. When a guard fails it
+     * returns `{ block }` naming whether a retry could help, instead of a route.
      */
     private resolveRoute;
+    /** The chat type recorded for a chat, if any (see resolveRoute). */
+    private chatTypeFor;
     disconnect(): void;
     /**
      * QQ Bot API V2 does not provide a typing indicator endpoint, but these
@@ -181,9 +317,68 @@ export declare class QQChannel extends ChannelBase {
      * discriminator (see activePromptSessions). ChannelBase always pairs the
      * two calls per prompt turn (onPromptEnd runs in the prompt path's
      * finally, even on error/cancel).
+     *
+     * Set the per-session reply anchor deterministically from the triggering
+     * message's id (ChannelBase passes envelope.messageId, which for QQ is
+     * event.id — the same value setReplyMsgId stores in the chat-level entry).
+     * This replaces the previous opportunistic capture on the first chunk,
+     * which had a blind spot: a slow model turn could pass the chat entry's
+     * 5-minute TTL before its first chunk, and the capture would then pick up
+     * the msgId of a NEWER message in the same chat (another user's turn).
+     * Anchoring at prompt start is immune — the anchor always refers to the
+     * message that actually triggered this session's turn.
+     *
+     * Proactive turns (loop/webhook/cron) have no triggering message; their
+     * replies must go out as active messages, so clear any stale anchor.
      */
-    protected onPromptStart(_chatId: string, sessionId: string, _messageId?: string): void;
-    protected onPromptEnd(_chatId: string, sessionId: string, _messageId?: string): void;
+    protected onPromptStart(_chatId: string, sessionId: string, messageId?: string): void;
+    /**
+     * ChannelBase invokes this unconditionally in a finally block — including
+     * when the prompt was cancelled, in which case onResponseComplete is
+     * skipped. That makes it the one reliable release point for per-session
+     * streaming state: without it a cancelled turn would leave its reply
+     * anchor in sessionReplyMsgId (and the next prompt on the same session
+     * would overwrite it only at its own start, leaking the stale entry's
+     * msg_seq orphan meanwhile).
+     *
+     * Deferred completions are exempt: when onResponseComplete parked the
+     * session in pendingStreamDelete, a final flush is still in flight and
+     * its promise chain owns the streamState lifecycle (it re-flushes the
+     * residual buffer, then releases the anchor). Clearing state here would
+     * trip the .then() identity guard and silently drop the residual buffer.
+     */
+    protected onPromptEnd(chatId: string, sessionId: string, _messageId?: string): void;
+    /**
+     * Deliver a cancelled turn's stashed HEAD on its OWN anchor. The session is
+     * parked in pendingStreamDelete while a predecessor turn's deferred chain
+     * settles, so ChannelBase skips onResponseComplete and onPromptEnd's park
+     * early-return would otherwise leave this turn's stash for the next turn to
+     * discard as superseded. Fire-and-forget — onPromptEnd is sync — and never
+     * rejects, so a failed delivery cannot become an unhandled rejection. The
+     * park flag and the predecessor's streamState entry/buffer are deliberately
+     * untouched: that chain still owns them and must settle and release its own
+     * anchor, and this text must not go out under the predecessor's msgId.
+     *
+     * This is the only delivery for a stash that onPromptEnd already deleted from
+     * streamOrphanBuffer (or a sealed head handOffSealedPre cleared from
+     * sealedPre), so a transient failure must not drop the text. RATE_LIMITED is
+     * the one code the flush path classifies as transient, and no copy survives
+     * for a later turn, so the send is re-attempted here under the same
+     * maxFlushRetries bound flushAndTrack uses (<= 0 means unlimited). A
+     * re-attempt is not routed through streamState/idleFlush: the turn is over,
+     * so a state entry for it would be dropped as stale by the next prompt, and
+     * the entry-less in-flight guard below would be lost. Every attempt
+     * reuses the anchor, the attribution label and the reply context captured
+     * before the first one.
+     *
+     * A send also fails to reach the wire without throwing when its route cannot
+     * be resolved; sendMessageWithReplyContext reports that as transient (token
+     * refresh failure) or permanent (disposed / unusable chatId / no chat type),
+     * and the second class is dropped with a log immediately rather than spun on
+     * the backoff forever. Permanent DeliveryErrors and exhaustion drop with a
+     * log, as the other paths do.
+     */
+    private deliverCancelledStash;
     protected onResponseChunk(chatId: string, chunk: string, sessionId: string, segment?: ChannelOutputSegmentContext): void;
     private idleFlush;
     /**
@@ -192,10 +387,233 @@ export declare class QQChannel extends ChannelBase {
      * on failure) logic to eliminate duplication.
      */
     private flushAndTrack;
+    /**
+     * Drop the session's turn-generation records — the turn counter and the
+     * completion record completedTurns — only when they still belong to the
+     * settling turn. A successor turn that started while this chain was in flight
+     * bumped the counter and cleared the completion record already (see
+     * onPromptStart); deleting them here would reset the successor's stale-state
+     * detection to 0 and let a stale completion record alias onto its turn.
+     *
+     * The counter is kept while this session still has a prompt in flight. A
+     * settle can run in the microtask window between onResponseComplete parking
+     * the session and ChannelBase's onPromptEnd (which clears the active marker
+     * first), and onPromptEnd then recognises the turn's own re-stashed sealed
+     * head by comparing the stash's turn against this counter — as does the
+     * parked-stash service before its early return. Deleting the counter here
+     * makes that gate read 0 and discard the head as superseded: the reply's
+     * opening reaches no wire, no buffer and no stash while the turn reports
+     * completed. The completion record still goes: it is turn-scoped, and a
+     * later prompt reusing the number must not alias it. onPromptEnd,
+     * onPromptStart and onSessionDied all still delete the counter once the
+     * prompt is over, so it stays bounded by the live sessions and can never be
+     * inherited by a successor turn.
+     */
+    private deleteTurnGenerationIfOwned;
     onToolCall(_chatId: string, event: ToolCallEvent): void;
     protected onResponseBoundary(_chatId: string, sessionId: string): void;
     protected onResponseComplete(chatId: string, fullText: string, sessionId: string, segment?: ChannelOutputSegmentContext): Promise<void>;
+    /**
+     * A stash's sealed head has no other copy — the bridge cleared it from its
+     * collection at the boundary — so a delivery that fails after the entry was
+     * consumed must report the loss (length and error) instead of dropping it
+     * silently. Delete-before-send is deliberate: it stops a chunk arriving
+     * mid-send from draining the same stash twice.
+     */
+    private logLostSealedHead;
+    /**
+     * Act on the route class a completion-path send reports. A blocked send never
+     * reached the wire but throws nothing, so without this the final segment is
+     * indistinguishable from a delivered one: the sealed head's loss log is
+     * bypassed and the turn is reported delivered. A transient block (token
+     * refresh failure) can clear on a later attempt, so it is re-attempted; a
+     * permanent block, or exhaustion, reports the sealed head this path consumed
+     * instead of dropping it silently. Exhaustion is bounded by maxFlushRetries
+     * when that is positive, and by FINAL_SEGMENT_ROUTE_ATTEMPTS when
+     * maxFlushRetries is the documented "unlimited" (<= 0): this send is awaited
+     * inside the turn, so unlike the fire-and-forget flush paths it cannot be
+     * allowed to retry forever — the turn's finally (and with it the session's
+     * turn lock) would never run. The caller holds the msg_seq counter across the
+     * whole call and releases the anchor only after it returns, so a re-attempt
+     * cannot restart at seq 1 (QQ dedupes on msg_id + msg_seq).
+     */
+    private sendFinalSegmentChecked;
     private streamBufferLimit;
+    /**
+     * Build a fresh streamState entry for a session's first chunk, resolving
+     * the session's reply anchor (TTL-checked) and the segment's reply context.
+     * Shared by onResponseChunk's fresh-entry path and onPromptEnd's delivery
+     * of a cancelled turn's stashed head.
+     */
+    private createStreamState;
+    /**
+     * Report the tail a capped divert episode accumulated after its first
+     * overflow line. See the cap branch in onResponseChunk: the first drop is
+     * logged immediately so the loss is visible, later chunks only count, and
+     * this emits the cumulative total once per episode when the stash leaves
+     * the side buffer. `capDropped` counts characters, not fields: the sealed
+     * pre's own trim is a subset of the text trim and is not charged again.
+     */
+    private reportOrphanStashCap;
+    /**
+     * Drop a side-buffer entry that cannot be delivered (it belongs to a
+     * superseded turn, or a fresh turn is starting and can never own it) and
+     * log the discarded text so the loss is observable.
+     */
+    private dropOrphanStash;
+    /**
+     * The seal a failed payload needs when a boundary cleared the bridge's
+     * collection while the send was in flight: the payload's whole text is now
+     * absent from fullText, so it is sealed outright rather than only by the seal
+     * the send carried, which may cover just a prefix. `residual` is the text the
+     * boundary stripped from the live turn, captured by the boundary hooks ('' =
+     * nothing), and is appended after the payload — no string comparison against
+     * the carried seal, so a residual whose text repeats it still counts.
+     */
+    private sealClearedPayload;
+    /**
+     * Put a transiently-failed payload back on `current` in the order the seal
+     * states it in.
+     *
+     * With no stash merged during this flight the payload predates whatever
+     * accumulated while it was in flight — chunks sent to state.buffer by the
+     * bridge's fallback path, or a residual that arrived mid-send — so the plain
+     * prepend (`payload + buffer`) is correct and is what the non-widened case
+     * has always done.
+     *
+     * After onPromptEnd merged a stash while this send was flight, the buffer is
+     * `[stashed head][chunks that arrived since]`: the merge prepends the head,
+     * and every later writer appends. That head is OLDER than the failed payload
+     * (it is the seal's leading segment — see handOffSealedPre, "the older
+     * first"), so the payload belongs BETWEEN the two portions and the
+     * reconstruction is `head + payload + newer`. Reconstructing it is the whole
+     * reason `staleStashPrefix` exists: the failed payload's text may repeat
+     * either portion of the buffer, the newer text may itself begin with the
+     * payload's text, and the payload may even be empty, so no boundary can be
+     * found by comparing text. A `startsWith`/dedup test against the buffer would
+     * strip the newer text's own leading characters — dropping real reply text —
+     * so the split uses the recorded length alone and never compares strings.
+     * The marker is consumed here — the payload is folded in and the next flight
+     * must not reorder against it again (flushAndTrack also resets it).
+     *
+     * A boundary that sealed a residual of its own while the send was in flight
+     * does not change that order: captureBoundaryClear records the residual and
+     * marks the re-seal, but the residual is only the text that accumulated
+     * since the boundary — it never contains the in-flight payload, and it does
+     * not know that the head prepended in front of it is older. A plain prepend
+     * would therefore read `head + payload + newer` as `payload + head + newer`.
+     * The reconstruction above stays the same; resealOnRebuffer's boundary arm
+     * extends the widened seal to match it.
+     */
+    private rebufferAfterStashMerge;
+    /**
+     * The seal owed for `payload` when a boundary cleared the bridge's collection
+     * while its send was in flight. onPromptEnd's stash merge may have widened the
+     * seal during this flight; the undelivered window is then the reconstruction
+     * rebufferAfterStashMerge builds (the OLDER stashed head, then this payload,
+     * then whatever accumulated since), read lazily so the non-widened path never
+     * consumes the stash marker. Otherwise the plain payload-plus-residual seal
+     * stands. Shared by the transient re-buffer arms (resealOnRebuffer) and the
+     * permanent handoff: all describe the same window, so they must not drift.
+     */
+    private sealForClearedWindow;
+    /**
+     * Re-seal a failed payload that a transient re-buffer puts back on `current`:
+     * a boundary that cleared the bridge's collection while the send was in
+     * flight removed the payload's whole text from fullText, so the entire
+     * payload is sealed, plus the residual the boundary captured (flagged
+     * deterministically, not by comparing seal text). Only a chain that still
+     * owns the live turn may write the seal — a superseded entry's payload is
+     * abandoned with its failure and must not be injected into a successor's
+     * reply. `carriedSeal` is the backstop for a re-seal whose boundary marker
+     * was missed, but it is skipped when the seal was widened during this flight
+     * (sealWidenedInFlight — onPromptEnd's stash merge already folded the carried
+     * head in as the widened seal's suffix, so prepending it again would seal it
+     * twice). Shared by the parked and non-parked re-buffer arms, and by the
+     * permanent handoff through sealForClearedWindow; they must stay identical
+     * because they encode the same rule.
+     */
+    private resealOnRebuffer;
+    /**
+     * Carry a widened, boundary-cleared re-buffer into the seal the NEXT flight
+     * captures, so the knowledge survives the per-flight resets and a permanent
+     * failure on a retry re-stashes the whole window instead of the stale
+     * residual.
+     *
+     * resealOnRebuffer writes exactly this for a live turn, but its live-turn
+     * gate skips a superseded entry — whose re-buffer would otherwise keep the
+     * residual the boundary overwrote ('AC') while `current.buffer` already holds
+     * the reconstruction ('APC'). The retry flight then starts with `sealedPre`
+     * 'AC' and, because flushAndTrack resets sealWidenedInFlight /
+     * boundaryClearedInFlight at every flight start, its permanent arm can no
+     * longer rebuild the window: the payload 'P' is on no wire and in no seal and
+     * the entry is deleted. Recording the reconstruction on the entry hands the
+     * retry flight the one value it needs: its success path still clears it
+     * without delivering, and only a give-up re-stashes it (or delivers it), the
+     * same handoff the widened permanent arm performs.
+     *
+     * Gated on the boundary marker AND the widening, not on the buffer alone: a
+     * widened re-buffer with NO boundary leaves the newer text in the bridge's
+     * collection, so welding it into the seal would deliver it twice. The value
+     * is the reconstruction `rebufferAfterStashMerge` just wrote to
+     * `current.buffer` — no seal/buffer text comparison anywhere.
+     */
+    private carryWidenedWindowIntoSeal;
+    /**
+     * Whether a settling flush chain still owns the session: its entry is the
+     * live streamState entry, or the chain still holds the flush marker. The
+     * marker is cleared only by `.finally()` after the settle arms, so this stays
+     * true while those arms hand state off; a session torn down by onSessionDied
+     * (or replaced outright) owns neither, and its chain must not write shared
+     * per-session state.
+     */
+    private ownsSession;
+    /**
+     * Whether this entry is still the turn that owns the session's counter. A
+     * superseded entry's text is abandoned with its failure and must not be
+     * sealed into a successor's reply.
+     */
+    private ownsLiveTurn;
+    /**
+     * Hand a doomed entry's sealed pre-boundary head to whatever can still
+     * deliver it, before the entry carrying the only copy is dropped. The
+     * boundary cleared the bridge's chunk collection, so this text is absent
+     * from fullText: dropping it truncates the reply's opening with no log.
+     *
+     * A later settle of this turn (onResponseComplete has not run yet), or a
+     * successor turn that owns the counter now, can still prepend it — re-stash,
+     * merging into an existing stash. A fresh entry is tagged with the turn that
+     * owns the counter, never the doomed one: every consumer gates on the entry
+     * turn matching the live turn, so a doomed tag is dropped as superseded by
+     * the successor's first chunk and the head is lost anyway. The merge branch
+     * keeps the existing entry's turn, which a stash always carries as the turn
+     * that wrote it. `pre` carries the sealed head alone and is never widened to
+     * the whole dropped buffer: the post-boundary text is still in fullText and
+     * prepending it again would deliver it twice.
+     *
+     * Otherwise the turn is already over — completion returned and parked the
+     * session, or the caller is the park-consuming exhaustion branch, which
+     * clears the flag before reaching here — and this turn still owns the
+     * counter, so the block that drops the entry also drops the counter and a
+     * stash would be discarded as superseded. Deliver the sealed head on this
+     * turn's own anchor instead — the same path onPromptEnd already uses for a
+     * parked cancelled turn's HEAD. The same delivery is taken when the turn
+     * being tagged has already run its completion (see completedTurns): its
+     * completion is the reader that would prepend the stash, it will not run
+     * again, and a stash it cannot consume is dropped by the next onPromptStart.
+     *
+     * `turnIsOver` defaults to the park flag, which is still armed at the four
+     * sites that reach here while it is; the pending-exhaustion branch has
+     * already consumed it, so it passes the fact explicitly.
+     *
+     * `carriedSeal` is the seal a permanently-failed send captured when it
+     * started (flushAndTrack). A later boundary can re-seal the same state's
+     * residual while that send is in flight, overwriting `sealedPre`; the failed
+     * send carried the older head, which then has no other copy. Both are
+     * recovered here — the older first, since the seal always covers a later
+     * buffer window.
+     */
+    private handOffSealedPre;
     onSessionDied(sessionId: string): void;
     private serializeQQState;
     /** Debounced state persistence with atomic write. */
@@ -211,6 +629,41 @@ export declare class QQChannel extends ChannelBase {
      * No-op if not attached or if cron is disabled.
      */
     private detachCronHandler;
+    /**
+     * Attach the ungated `responseBoundary` observer to the current bridge.
+     * No-op if already attached.
+     */
+    private attachBridgeBoundarySeal;
+    /** Detach the boundary observer. No-op if not attached. */
+    private detachBridgeBoundarySeal;
+    /**
+     * Seal the pre-boundary portion of a stashed head. Called from both the
+     * adapter hook and the bridge's own boundary event: ChannelBase suppresses
+     * the hook while a cancel is pending, but the bridge clears its chunk
+     * collection on every boundary it emits, so only the ungated observer can
+     * guarantee `pre` is set before the turn completes.
+     */
+    private sealOrphanStash;
+    /**
+     * A boundary clears the bridge's chunk collection. Seal the live turn's
+     * buffer-resident prefix for the completion path, and record on the
+     * entry whose flush is in flight what its re-buffer must re-seal: the payload
+     * the boundary stripped from fullText, always, plus that residual when the
+     * flushed entry is the live turn's own. Called by the adapter hook and by the
+     * ungated bridge observer — the observer is the only signal when ChannelBase
+     * suppresses the hook (cancel pending) — and both run on a normal boundary,
+     * where the assignments are idempotent. Keyed off the in-flight marker rather
+     * than streamState, so a successor turn replacing the entry cannot hide the
+     * chain whose payload is still in the air.
+     */
+    private captureBoundaryClear;
+    /**
+     * The residual text a boundary captured for this entry, or '' when it
+     * recorded none. The text lives in `sealedPre`, written by
+     * captureBoundaryClear in the same call that sets the marker, so it is always
+     * a real residual and never the seal the failed payload carried.
+     */
+    private capturedResidual;
     /** Flush pending state writes immediately (called on disconnect). */
     private flushQQState;
     /**
@@ -240,6 +693,123 @@ export declare class QQChannel extends ChannelBase {
      * Keep this while old persisted files may still exist.
      */
     private fixRestoredSessions;
+    /**
+     * Purge orphaned session mappings left over from older scope eras:
+     * `<channel>:__single__` keys (single-scope era, see PR #6457) and this
+     * channel's own three-part user-scope keys.
+     *
+     * `<channel>:__single__` is the live routing key under an explicit 'single'
+     * sessionScope, so it is an orphan only under any other scope. There it can
+     * never be routed to again and is dead weight in the router maps and the
+     * persisted sessions file — and worse, restore re-attaches it via
+     * bridge.loadSession on every restart, silently resetting continuity.
+     *
+     * User-scope keys (`<channel>:<sender>:<chat>`) are unroutable under every
+     * scope other than 'user' (including 'single'): SessionRouter's
+     * thread/chat_thread routing key is `<channel>:<chatId>` and its 'single'
+     * key is `<channel>:__single__`, while resolve() is a bare map lookup with
+     * no shape fallback. This channel's own user-scope entries are therefore
+     * purged under every recognized non-'user' scope; an unrecognized scope
+     * fails closed (see knownScope below). A sibling channel's are left alone,
+     * decided by target ownership, never by key prefix. The purge runs after
+     * restore, so on the first boot those keys are still re-attached once by
+     * bridge.loadSession and then released here; afterwards they are gone from
+     * the persisted file.
+     *
+     * The destructive half is opt-in via `purgeLegacySessions` (default false):
+     * the default scope changing is not the operator asking to delete persisted
+     * conversations. With it off, the doomed routes are only counted and
+     * reported, and nothing is released. With it on, before the first deletion
+     * the doomed routes are appended to `<name>-sessions-purged.json` in the
+     * channel state directory so an operator can restore a legacy conversation
+     * by hand; if that write fails, nothing is deleted. Each record carries the
+     * route's `cwd` when the router's persisted route store still has it, so a
+     * restored route resolves to the same workspace. The file accumulates purge
+     * records and is never read back automatically.
+     *
+     * Runs AFTER restoreSessions(): SessionRouter exposes no public API to drop
+     * persisted entries before restore (readPersistedEntries/deleteByKey are
+     * private), and rewriting the persist file from here would be fragile and
+     * race-prone. The orphan is therefore re-attached by bridge.loadSession
+     * during restore and then released here — both the router mapping and the
+     * daemon-side session (see bridge.discardSession below) are torn down.
+     */
+    private purgeSingleScopeOrphans;
+    /**
+     * Resolve a session's reply anchor, returning both the raw entry and the
+     * msgId only while the entry is still inside REPLY_MSG_ID_TTL_MS. Callers
+     * that just need a usable anchor take `.msgId`; callers that must tell an
+     * absent anchor from an expired one (the final-segment fallback logs the
+     * expired case) branch on `.entry`. One site, so the freshness rule cannot
+     * drift between the flush, cancelled-stash, completion and create paths.
+     */
+    private resolveSessionReplyAnchor;
+    /**
+     * Release a session's reply anchor, cascading to msgSeqMap when the
+     * anchored msgId is no longer referenced by any live session or by the
+     * chat's current replyMsgId entry. Idempotent — safe to call on sessions
+     * that never held an anchor. This is the single release path for
+     * sessionReplyMsgId so every release point (flush completion, permanent
+     * delivery failure, retry exhaustion, onResponseComplete, onSessionDied,
+     * onPromptEnd, group removal) also cleans up msg_seq counters whose msgId
+     * can never be used again — otherwise they accumulate forever in memory
+     * and in the persisted QQ state.
+     *
+     * When expectedMsgId is given, the map entry is only removed if it still
+     * points at that msgId. A deferred send chain may settle after the next
+     * prompt on the same session has already overwritten the anchor with a new
+     * msgId; releasing by sessionId alone would delete the *successor's* anchor
+     * (the exact defect this parameter guards). The msgSeqMap cascade still
+     * runs for expectedMsgId so the superseded turn's counter cannot orphan.
+     */
+    private releaseSessionReplyAnchor;
+    /**
+     * Whether a msgId's msg_seq counter is still needed: another session is
+     * anchored to it, the chat-level replyMsgId entry still points at it, a
+     * streamState entry holds it with a pending residual or an in-flight flush,
+     * an anchored send under it is in flight (including the entry-less sends
+     * flushingSessions cannot see), or the replyContextByMessageId routing map
+     * still names it. The single predicate for every msgSeqMap reclamation site,
+     * so the release veto and the TTL/teardown reclaimers cannot disagree and
+     * drop a counter under a live send. It errs toward retaining: a counter that
+     * survives too long only makes a later send under the same msgId start at a
+     * higher msg_seq, which QQ accepts, while reclaiming it early loses the tail
+     * (QQ dedupes on msg_id + msg_seq).
+     */
+    private isMsgSeqStillInUse;
+    /**
+     * Drop a msgId's msg_seq counter once no holder remains. Derived,
+     * not decided per call site: a release site that vetoes reclamation while a
+     * holder still exists never gets a second chance once that holder later
+     * disappears, so every site routes through isMsgSeqStillInUse and the sweep
+     * re-checks the counter map itself. Returns whether the counter was dropped;
+     * the drop is persisted so a cold restart cannot resurrect it.
+     */
+    private reclaimMsgSeq;
+    /**
+     * Safety net that reclaims a msg_seq counter once its last holder is gone:
+     * the iteration domain is the counter map itself, so a
+     * counter whose only *naming* entry (session anchor, chat anchor,
+     * replyContextByMessageId routing entry, stream entry) was already deleted
+     * is still visited. It cannot make orphaning impossible — a counter can
+     * outlive its last holder between two 60s ticks — but it guarantees the
+     * counter is dropped on the next tick instead of leaking forever. Deleting
+     * from a Map while iterating its keys is safe. Returns whether anything was
+     * reclaimed.
+     */
+    private reclaimOrphanMsgSeqCounters;
+    /** Mark an anchored send under msgId in flight for the release guard. */
+    private beginMsgSeqSend;
+    /** Clear the matching beginMsgSeqSend once the send has settled. */
+    private endMsgSeqSend;
+    /** Whether any live session is still anchored to this msgId. */
+    private isMsgIdAnchoredBySession;
+    /**
+     * Set replyMsgId for a chat, replacing any previous entry. The previous
+     * msgId's msg_seq counter is deliberately NOT dropped here (see the NOTE
+     * below): it is left to the TTL sweep, which reclaims it only once no
+     * holder remains.
+     */
     private setReplyMsgId;
     private deleteReplyContext;
     /**