@llblab/pi-kit 0.21.0 → 0.21.2

package/node_modules/@llblab/pi-telegram/AGENTS.md

@@ -74,7 +74,7 @@ Use the relevant local skill before non-trivial work in its domain. Keep skill o
 - Threaded Mode has exactly one live leader per bot profile. Followers are real operator-started Pi processes and must authenticate/register over local IPC; Telegram never spawns hidden Pi processes. A live but unreachable owner does not authorize split-brain polling.
 - Local IPC is a trust boundary, not merely a private socket. Unknown, stale, mismatched-generation, or unauthorized requests must not inject prompts, callbacks, API sends, artifacts, liveness, or bindings. Follower registration identity may prepare a binding, but inbound generation authority is published only after successful preparation for the same generation and current context; pending or failed startup cannot append into a retained old journal. Readiness also binds the active Pi context and supplied session generation. Session refresh awaits binding preparation without re-registering; reusing a context object cannot carry readiness across a session-generation change. Registration requests capture session authority before asynchronous startup and fence every publication/finalization against the current attempt. Stop or supersession invalidates that attempt; obsolete cleanup cannot erase a newer registration or a refreshed context.
 - Protocol compatibility is independent from package version. Registration negotiates protocol version, runtime build, and canonical capabilities before target provisioning or live publication. `durable-follower-admission-v1` gates source forwarding; `queue-handoff-v1` independently gates semantic queue transfer for every participant and is advertised only with exact source/recipient journal-binding composition. `follower.register` and capability-gated restore-only `follower.restoreWorkspace` are bootstrap requests; other requests require exact live-registry generation authority, and `bus.ack` is response-only. `thread-display-mode-v1` gates follower display-setting requests; the leader owns their serialized profile preference and title application.
-- Long-lived timers, pollers, watchers, receivers, heartbeats, background delivery, and deferred dispatch are session-bound. Replacement stops stale activity and makes late work inert; teardown must recheck the captured session generation even when context identity is reused. Same-process handoff may preserve exact profile/target identity but never stale Pi context or cross-profile authority. Participating source observations must hold a reference for the actual read, including pending-mutation/count queries against a stopped worker's retained source; a scoped observation never restores receipt readiness or execution authority. A donor cancellation resumed after remote handoff awaits must also hold a source reference; only the existing exact journal CAS may cancel, never undo accepted recipient custody. Stable source keys do not certify captured callable lifetimes: snapshot prepared worker capabilities at construction and replace them on source-handle renewal without replaying unsettled input. Aborting a durable update generation does not release that `update_id`: replacement replay waits for its actual handler settlement, and effectful handlers use the shared execution fence immediately before commit and after awaited delegation. Admission also rechecks that fence after the default handler returns, before its outcome can settle custody; a stopped handler's ordinary return is not completion authority. Internal clones explicitly carry the hidden fence; reroute forwarding, thread-store mutation, cleanup, and Bot API boundaries retain the originating generation.
+- Long-lived timers, pollers, watchers, receivers, heartbeats, background delivery, and deferred dispatch are session-bound. Replacement stops stale activity and makes late work inert; teardown must recheck the captured session generation even when context identity is reused. Same-process handoff may preserve exact profile/target identity but never stale Pi context or cross-profile authority. Follower heartbeat response deadlines align with the eight-second leader stale-liveness window rather than the generic one-second local-RPC default; an ordinary multi-second Pi/TUI event-loop stall is not registration loss. Participating source observations must hold a reference for the actual read, including pending-mutation/count queries against a stopped worker's retained source; a scoped observation never restores receipt readiness or execution authority. A donor cancellation resumed after remote handoff awaits must also hold a source reference; only the existing exact journal CAS may cancel, never undo accepted recipient custody. Stable source keys do not certify captured callable lifetimes: snapshot prepared worker capabilities at construction and replace them on source-handle renewal without replaying unsettled input. Aborting a durable update generation does not release that `update_id`: replacement replay waits for its actual handler settlement, and effectful handlers use the shared execution fence immediately before commit and after awaited delegation. Admission also rechecks that fence after the default handler returns, before its outcome can settle custody; a stopped handler's ordinary return is not completion authority. Internal clones explicitly carry the hidden fence; reroute forwarding, thread-store mutation, cleanup, and Bot API boundaries retain the originating generation.
 - Runtime state is event-driven reconciliation of local assumptions against Telegram signals, not a complete bot read-model and not permission to query Telegram on every action. Destructive thread cleanup goes through `thread-reconciler` with current proof and leader fencing. Fresh Workspace Thread creation derives its initial Bot API title from the active display mode before issuance; the stable generated `threadName` remains separate from the acknowledged `displayTitle`.
 
 ### 4.3 Durable Admission And Settlement
@@ -95,7 +95,7 @@ Use the relevant local skill before non-trivial work in its domain. Keep skill o
 ### 4.4 Queue, Delivery, And User Surfaces
 
 - Queue lane/kind admission is explicit. Dispatch waits for active-turn, pending-dispatch, control, compaction, `ctx.isIdle()`, and Pi pending-message guards; a dispatched prompt stays queued until `agent_start` consumes it. The terminal `+N` suffix is a yellow count of executable prompts still waiting, excludes the dispatched head immediately, and never counts current agent work from any source. Each prompt is one object with one active lane and no reserved return slot. Normal and Priority are separate FIFO lanes: crossing lanes removes it from the source and appends it at the destination tail, while Keep/Skip and same-category emoji changes preserve lane position. Complete reaction sets independently derive Priority from recognized positive emoji and Skip from recognized negative emoji; both may coexist, suppressed turns retain durable receipts while waiting, and Skip settles them only when the prompt reaches dispatch before dropping it without inference. Suppressed turns remain visible at a struck-through physical ordinal without contributing to executable queue counters, while graceful session shutdown discards all remaining queue authority before clearing memory.
-- `/stop`, `/abort`, `/next`, and `/continue` respectively reset+abort, abort while preserving queue, force the next turn, and enqueue a control-lane continuation. Abort-history folding applies only to Telegram-owned active turns.
+- `/stop`, `/abort`, `/next`, and `/continue` respectively reset+abort, abort while preserving queue, force the next turn, and enqueue a control-lane continuation. Abort-history folding applies only to Telegram-owned active turns. A busy `/next` marks only its exact active Telegram turn: terminal abort settlement attempts one explicit abort notice before the exact selected queued prompt receives its dispatch notice. Notice failure is diagnostic and cannot block dispatch; a later `/abort` or `/stop` cancels both pending transition notices before taking ownership. Target command adapters must forward these transition ports. A successful dispatch notice keeps the queued prompt's one reply-header claim across agent start, so later messages in that turn never repeat it.
 - Telegram extension side effects must not hold Pi's core lifecycle hostage after semantic completion. Preserve ordering in extension-owned background work, record failures, and fence target/profile/transport/session authority.
 - Complete assistant/guest model answers use Telegram-native Rich Markdown. Harness-owned menus, status, diagnostics, thinking, and tool evidence remain explicit HTML/plain or their documented native surface. Before Telegram preview or final delivery, strip every assistant-authored HTML comment regardless of Markdown position while keeping action activation top-level-only; a comment-only result sends no text message. Preserve literal code outside comments and structurally safe chunking; never split invalid markup.
 - `preview` owns streaming lifecycle only, not assistant rendering. Finalization waits for active preview flushes and must not issue pre/post-final draft-clear calls that create transient Telegram draft UI. Turns that already answer as one atomic reply (voice replies, Guest Mode queries) never stream previews.

package/node_modules/@llblab/pi-telegram/CHANGELOG.md

@@ -4,6 +4,11 @@
 
 ## Unreleased
 
+## 0.51.1: Queue transitions and follower heartbeat stability
+
+- `/next lifecycle notices`: Target command composition now forwards request, exact-turn marker, and cancellation ports. Busy `/next` orders abort then selected-prompt dispatch notices; failures cannot block dispatch, and `/abort`/`/stop` cancel stale notices. A successful dispatch notice keeps first-reply ownership through agent start, so later answer messages do not repeat the queued-prompt reply. Rapid ordinary messages remain distinct turns.
+- `Follower heartbeat stability`: Follower heartbeats now use a dedicated eight-second response deadline aligned with leader stale-liveness policy instead of the generic one-second local-RPC default. Ordinary multi-second TUI/event-loop stalls therefore retain registration and stable `follower` status rather than destroying the socket, producing leader EPIPE noise, and entering repeated reconnect cycles.
+
 ## 0.51.0: Safe Workspace rotation and follower readiness
 
 - `Workspace slot rotation`: Fresh allocation reclaims the oldest proven inactive slot only at full A–Z pressure. Exact grouped receipts may be journal-CAS discarded only after complete source inspection proves every process-birth owner dead. Live/unknown owners, partial groups, handoffs and unrelated work stay protected. Fresh protection precedes Thread/history deletion and slot reuse. Pi sessions/files/memory/journals remain; restore-only never evicts; ambiguous deletion never replays.

package/node_modules/@llblab/pi-telegram/dist/lib/bindings.d.ts

@@ -34,6 +34,7 @@ export interface TelegramQueueBindingRuntime<TContext> {
     mutation: Queue.TelegramQueueMutationController<TContext>;
     dispatchNext: (ctx: TContext) => void;
     requestNextDispatchAnnouncement: () => void;
+    cancelNextDispatchAnnouncement: () => void;
     watchdog: Queue.TelegramQueueDispatchWatchdogRuntime<TContext>;
 }
 export declare function createTelegramQueueBindingRuntime<TContext>(deps: {
@@ -58,6 +59,7 @@ export declare function createTelegramQueueBindingRuntime<TContext>(deps: {
     updateStatus: (ctx: TContext, error?: string) => void;
     sendTextReply: Queue.TelegramQueueDispatchRuntimeDeps<TContext>["sendTextReply"];
     sendUserMessage: Queue.TelegramQueueDispatchRuntimeDeps<TContext>["sendUserMessage"];
+    reconcileNextDispatchAnnouncementReplyOwnership?: (item: Queue.PendingTelegramTurn) => void;
     recordRuntimeEvent?: TelegramRuntimeEventRecorder;
 }): TelegramQueueBindingRuntime<TContext>;
 export interface TelegramGenerativeAppLiveSurfaceBinding {

package/node_modules/@llblab/pi-telegram/dist/lib/bindings.js

@@ -79,6 +79,7 @@ export function createTelegramQueueBindingRuntime(deps) {
         },
         updateStatus: deps.updateStatus,
         sendTextReply: deps.sendTextReply,
+        reconcileNextDispatchAnnouncementReplyOwnership: deps.reconcileNextDispatchAnnouncementReplyOwnership,
         recordRuntimeEvent: deps.recordRuntimeEvent,
         ...deps.promptDispatch,
         sendUserMessage: deps.sendUserMessage,
@@ -87,6 +88,7 @@ export function createTelegramQueueBindingRuntime(deps) {
         mutation,
         dispatchNext: dispatch.dispatchNext,
         requestNextDispatchAnnouncement: dispatch.requestNextDispatchAnnouncement,
+        cancelNextDispatchAnnouncement: dispatch.cancelNextDispatchAnnouncement,
         watchdog: Queue.createTelegramQueueDispatchWatchdogRuntime({
             hasQueuedItems: deps.store.hasQueuedItems,
             dispatchNextQueuedTelegramTurn: dispatch.dispatchNext,

package/node_modules/@llblab/pi-telegram/dist/lib/bus-follower.d.ts

@@ -8,7 +8,7 @@
 import * as Sync from "./sync.ts";
 import * as Threads from "./threads.ts";
 import { type TelegramUpdateJournalStoreOptions } from "./journal.ts";
-import type { TelegramLockEntry, TelegramLockState } from "./locks.ts";
+import { type TelegramLockEntry, type TelegramLockState } from "./locks.ts";
 import type { TelegramQueueHandoffPayload, TelegramQueueHandoffStageResult } from "./queue.ts";
 import type { TelegramTarget } from "./target.ts";
 import { type TelegramBusAgentMessage, type TelegramBusAgentTargetSelector, type TelegramBusEnvelope, type TelegramBusForwardOwnership, type TelegramBusProtocolIdentity, type TelegramBusSocketPathSource } from "./bus.ts";
@@ -18,6 +18,7 @@ export declare const TELEGRAM_BUS_FOLLOWER_PROMOTION_GRACE_MS = 2500;
 export declare const TELEGRAM_FOLLOWER_SESSION_HANDOFF_TTL_MS = 30000;
 export declare const TELEGRAM_BUS_FOLLOWER_CLIENT_TIMEOUT_MS = 30000;
 export declare const TELEGRAM_BUS_FOLLOWER_REGISTRATION_WAIT_MS = 30000;
+export declare const TELEGRAM_BUS_FOLLOWER_HEARTBEAT_TIMEOUT_MS = 8000;
 export declare const TELEGRAM_BUS_FOLLOWER_REGISTRATION_RETRY_ATTEMPTS: number;
 export declare const TELEGRAM_BUS_FOLLOWER_REGISTRATION_RETRY_DELAY_MS: number;
 export interface TelegramFollowerSessionHandoff {
@@ -170,6 +171,7 @@ export interface TelegramBusFollowerRegistrationRuntimeDeps<TContext extends {
     registrationRetryAttempts?: number;
     registrationRetryDelayMs?: number;
     heartbeatMs?: number;
+    heartbeatTimeoutMs?: number;
     recordRuntimeEvent?: (category: string, error: unknown, details?: Record<string, unknown>) => void;
     onHeartbeatFailure?: (error: unknown, ctx: TContext) => Promise<void> | void;
     onRegistered?: (ctx: TContext) => Promise<void> | void;

package/node_modules/@llblab/pi-telegram/dist/lib/bus-follower.js

@@ -9,6 +9,7 @@ import { basename } from "node:path";
 import * as Sync from "./sync.js";
 import * as Threads from "./threads.js";
 import { parseTelegramUpdateJournalQueueOwner } from "./journal.js";
+import { TELEGRAM_BUS_LEADER_STALE_HEARTBEAT_MS, } from "./locks.js";
 import { isTelegramApiMethodRetrySafe, TelegramApiCommitUnknownError, TelegramApiStaleTargetError, } from "./telegram-api.js";
 import { createTelegramBusFollowerDeliveryIdentity, createTelegramBusFollowerTargetController, createTelegramBusForeignOwnedUpdateForwarder, createTelegramBusLocalServer, createTelegramBusRequestIdFactory, createUnauthorizedBusAck, getTelegramBusProtocolCompatibility, getTelegramBusSocketPath, hasTelegramBusCapability, isTelegramBusEnvelopeAuthorized, resolveTelegramBusSocketPath, sendTelegramBusLocalEnvelope, TELEGRAM_BUS_CAPABILITY_WORKSPACE_THREAD_RENAME, TELEGRAM_BUS_CAPABILITY_THREAD_DISPLAY_MODE, TELEGRAM_BUS_CAPABILITY_DIRECTORY_DISPLAY_FORMAT, } from "./bus.js";
 import { getTelegramBusTransportRetryPolicy, TELEGRAM_BUS_REGISTRATION_RETRY, } from "./bus-transport.js";
@@ -17,6 +18,7 @@ export const TELEGRAM_BUS_FOLLOWER_PROMOTION_GRACE_MS = 2_500;
 export const TELEGRAM_FOLLOWER_SESSION_HANDOFF_TTL_MS = 30_000;
 export const TELEGRAM_BUS_FOLLOWER_CLIENT_TIMEOUT_MS = 30_000;
 export const TELEGRAM_BUS_FOLLOWER_REGISTRATION_WAIT_MS = 30_000;
+export const TELEGRAM_BUS_FOLLOWER_HEARTBEAT_TIMEOUT_MS = TELEGRAM_BUS_LEADER_STALE_HEARTBEAT_MS;
 export const TELEGRAM_BUS_FOLLOWER_REGISTRATION_RETRY_ATTEMPTS = TELEGRAM_BUS_REGISTRATION_RETRY.attempts;
 export const TELEGRAM_BUS_FOLLOWER_REGISTRATION_RETRY_DELAY_MS = TELEGRAM_BUS_REGISTRATION_RETRY.delayMs;
 const TELEGRAM_FOLLOWER_SESSION_HANDOFF_KEY = "__piTelegramFollowerSessionHandoff";
@@ -920,6 +922,9 @@ export function createTelegramBusFollowerRegistrationRuntime(deps) {
     const getNowMs = deps.getNowMs ?? Date.now;
     const getPid = deps.getPid ?? (() => process.pid);
     const heartbeatMs = deps.heartbeatMs ?? 1000;
+    const heartbeatTimeoutMs = deps.heartbeatTimeoutMs ??
+        deps.timeoutMs ??
+        TELEGRAM_BUS_FOLLOWER_HEARTBEAT_TIMEOUT_MS;
     const registrationTimeoutMs = deps.registrationTimeoutMs ?? deps.timeoutMs ?? 30000;
     const registrationRetryAttempts = deps.registrationRetryAttempts ??
         TELEGRAM_BUS_FOLLOWER_REGISTRATION_RETRY_ATTEMPTS;
@@ -979,7 +984,7 @@ export function createTelegramBusFollowerRegistrationRuntime(deps) {
         try {
             const response = await sendTelegramBusLocalEnvelope({
                 socketPath: leaderSocketPath,
-                timeoutMs: deps.timeoutMs,
+                timeoutMs: heartbeatTimeoutMs,
                 retry: getTelegramBusTransportRetryPolicy({
                     endpoint: leaderSocketPath,
                     operation: "operation",

package/node_modules/@llblab/pi-telegram/dist/lib/commands.d.ts

@@ -210,6 +210,7 @@ export interface TelegramCommandActionDeps<TMessage, TContext> {
 export interface TelegramStopCommandDeps {
     hasAbortHandler: () => boolean;
     clearPendingModelSwitch: () => void;
+    cancelNextTransitionAnnouncements?: () => void;
     clearQueuedTelegramItems: () => number;
     setFoldQueuedPromptsIntoHistory: (fold: boolean) => void;
     abortCurrentTurn: () => void;
@@ -392,6 +393,8 @@ export interface TelegramCommandRuntimeDeps<TMessage extends TelegramCommandRunt
     isContextActive?: (ctx: TContext) => boolean;
     dispatchNextQueuedTelegramTurn: (ctx: TContext) => void;
     requestNextDispatchAnnouncement?: () => void;
+    markActiveTurnNextAbortAnnouncement?: () => boolean;
+    cancelNextTransitionAnnouncements?: () => void;
     requestDeferredDispatchNextQueuedTelegramTurn?: (dispatch: (ctx: TContext) => void) => void;
     startTypingLoop?: (ctx: TContext, chatId?: number, options?: {
         target?: {
@@ -504,6 +507,7 @@ export declare function handleTelegramAbortCommand(deps: {
     hasAbortHandler: () => boolean;
     hasActiveTelegramTurn: () => boolean;
     clearPendingModelSwitch: () => void;
+    cancelNextTransitionAnnouncements?: () => void;
     abortCurrentTurn: () => void;
     setFoldQueuedPromptsIntoHistory: (fold: boolean) => void;
     updateStatus: () => void;
@@ -519,6 +523,7 @@ export declare function handleTelegramNextCommand(deps: {
     abortCurrentTurn: () => void;
     dispatchNextQueuedTurn: () => void;
     requestNextDispatchAnnouncement?: () => void;
+    markActiveTurnNextAbortAnnouncement?: () => boolean;
     clearFoldForDispatch: () => void;
     updateStatus: () => void;
     sendTextReply: (text: string, options?: {

package/node_modules/@llblab/pi-telegram/dist/lib/commands.js

@@ -631,6 +631,7 @@ function formatTelegramQueuedTurnCount(count) {
 }
 export async function handleTelegramStopCommand(deps) {
     deps.clearPendingModelSwitch();
+    deps.cancelNextTransitionAnnouncements?.();
     const clearedCount = deps.clearQueuedTelegramItems();
     deps.setFoldQueuedPromptsIntoHistory(false);
     if (!deps.hasAbortHandler()) {
@@ -651,6 +652,7 @@ export async function handleTelegramStopCommand(deps) {
 }
 export async function handleTelegramAbortCommand(deps) {
     deps.clearPendingModelSwitch();
+    deps.cancelNextTransitionAnnouncements?.();
     if (!deps.hasAbortHandler()) {
         await deps.sendTextReply(formatTelegramInformationHeading("💤", "No active turn."), { parseMode: "HTML" });
         return;
@@ -669,6 +671,7 @@ export async function handleTelegramNextCommand(deps) {
     if (!deps.isIdle() && deps.hasAbortHandler()) {
         deps.clearFoldForDispatch();
         deps.requestNextDispatchAnnouncement?.();
+        deps.markActiveTurnNextAbortAnnouncement?.();
         deps.abortCurrentTurn();
         deps.updateStatus();
         return;
@@ -934,6 +937,9 @@ export function createTelegramCommandHandlerTargetRuntime(deps) {
         updateStatus: deps.updateStatus,
         isContextActive: deps.isContextActive,
         dispatchNextQueuedTelegramTurn: deps.dispatchNextQueuedTelegramTurn,
+        requestNextDispatchAnnouncement: deps.requestNextDispatchAnnouncement,
+        markActiveTurnNextAbortAnnouncement: deps.markActiveTurnNextAbortAnnouncement,
+        cancelNextTransitionAnnouncements: deps.cancelNextTransitionAnnouncements,
         startTypingLoop: deps.startTypingLoop,
         stopTypingLoop: deps.stopTypingLoop,
         enqueueContinueTurn: deps.enqueueContinueTurn,
@@ -1039,6 +1045,7 @@ async function handleTelegramCommandRuntime(commandName, message, ctx, deps, com
             await handleTelegramStopCommand({
                 hasAbortHandler: deps.hasAbortHandler,
                 clearPendingModelSwitch: deps.clearPendingModelSwitch,
+                cancelNextTransitionAnnouncements: deps.cancelNextTransitionAnnouncements,
                 clearQueuedTelegramItems: () => deps.clearQueuedTelegramItems(commandCtx),
                 setFoldQueuedPromptsIntoHistory: deps.setFoldQueuedPromptsIntoHistory,
                 abortCurrentTurn: deps.abortCurrentTurn,
@@ -1085,6 +1092,7 @@ async function handleTelegramCommandRuntime(commandName, message, ctx, deps, com
                 hasAbortHandler: deps.hasAbortHandler,
                 hasActiveTelegramTurn: deps.hasActiveTelegramTurn,
                 clearPendingModelSwitch: deps.clearPendingModelSwitch,
+                cancelNextTransitionAnnouncements: deps.cancelNextTransitionAnnouncements,
                 abortCurrentTurn: deps.abortCurrentTurn,
                 setFoldQueuedPromptsIntoHistory: deps.setFoldQueuedPromptsIntoHistory,
                 updateStatus: updateStatusFor(commandCtx),
@@ -1100,6 +1108,7 @@ async function handleTelegramCommandRuntime(commandName, message, ctx, deps, com
                 abortCurrentTurn: deps.abortCurrentTurn,
                 dispatchNextQueuedTurn: () => deps.dispatchNextQueuedTelegramTurn(commandCtx),
                 requestNextDispatchAnnouncement: deps.requestNextDispatchAnnouncement,
+                markActiveTurnNextAbortAnnouncement: deps.markActiveTurnNextAbortAnnouncement,
                 clearFoldForDispatch: () => deps.setFoldQueuedPromptsIntoHistory(false),
                 updateStatus: updateStatusFor(commandCtx),
                 sendTextReply: sendReplyFor(nextMessage),

package/node_modules/@llblab/pi-telegram/dist/lib/extension.js

@@ -642,7 +642,7 @@ export default function (pi) {
             editMessageText: editTelegramMessageText,
         },
     });
-    const { mutation: queueMutationRuntime, dispatchNext: dispatchNextQueuedTelegramTurn, requestNextDispatchAnnouncement, watchdog: queueDispatchWatchdogRuntime, } = Bindings.createTelegramQueueBindingRuntime({
+    const { mutation: queueMutationRuntime, dispatchNext: dispatchNextQueuedTelegramTurn, requestNextDispatchAnnouncement, cancelNextDispatchAnnouncement, watchdog: queueDispatchWatchdogRuntime, } = Bindings.createTelegramQueueBindingRuntime({
         store: telegramQueueStore,
         queue,
         lifecycle,
@@ -656,6 +656,9 @@ export default function (pi) {
         updateStatus,
         sendTextReply,
         sendUserMessage,
+        reconcileNextDispatchAnnouncementReplyOwnership(item) {
+            Replies.preserveTransportReplyDedupOnNextReset(item.chatId, item.replyToMessageId, item.target);
+        },
         recordRuntimeEvent,
     });
     const { finalizeMarkdownPreview, preparePreviewDelivery } = Outbound.createTelegramOutboundTextPreviewRuntime({
@@ -887,6 +890,7 @@ export default function (pi) {
         isContextActive: telegramSessionContextStore.isCurrent,
         dispatchNextQueuedTelegramTurn,
         requestNextDispatchAnnouncement,
+        cancelNextDispatchAnnouncement,
         requestDeferredDispatchNextQueuedTelegramTurn: deferredQueueDispatchRuntime.request,
         hasDeferredDispatchContext: deferredQueueDispatchRuntime.isBound,
         startTypingLoop: promptDispatchRuntime.startTypingLoop,

package/node_modules/@llblab/pi-telegram/dist/lib/queue.d.ts

@@ -84,6 +84,8 @@ export interface PendingTelegramTurn extends TelegramQueueItemBase {
     historyText: string;
     priorityEmoji?: string;
     reactionSuppressionEmoji?: string;
+    /** Emit the explicit aborted-turn notice when /next settles this active turn. */
+    announceNextAbortOnEnd?: boolean;
     /** Turn should preferably be delivered as voice (mirror mode + user sent voice) */
     voiceReplyPreferred?: boolean;
     /** Turn must be delivered as voice (voice mode) */
@@ -165,6 +167,8 @@ export interface TelegramActiveTurnStore<TTurn extends PendingTelegramTurn = Pen
     has: () => boolean;
     set: (turn: TTurn) => void;
     clear: () => void;
+    markNextAbortAnnouncement: () => boolean;
+    clearNextAbortAnnouncement: () => boolean;
     getChatId: () => number | undefined;
     getTarget: () => TelegramQueueTarget | undefined;
     getReplyToMessageId: () => number | undefined;
@@ -391,6 +395,7 @@ export interface TelegramAgentEndPlan {
     kind: "no-turn" | "aborted" | "error" | "text" | "attachments-only" | "empty";
     shouldClearPreview: boolean;
     shouldDispatchNext: boolean;
+    shouldSendAbortMessage: boolean;
     shouldSendErrorMessage: boolean;
     shouldSendAttachmentNotice: boolean;
 }
@@ -517,6 +522,7 @@ export declare function buildTelegramAgentEndPlan(options: {
     hasFinalText: boolean;
     hasQueuedAttachments: boolean;
     foldQueuedPromptsIntoHistory: boolean;
+    announceNextAbortOnEnd?: boolean;
 }): TelegramAgentEndPlan;
 export declare function createTelegramAgentEndHook<TTurn extends PendingTelegramTurn, TContext, TMessage, TReplyMarkup = unknown>(deps: TelegramAgentEndHookRuntimeDeps<TTurn, TContext, TMessage, TReplyMarkup>): (event: TelegramAgentEndHookEvent<TMessage>, ctx: TContext, assistantOverride?: TelegramAgentEndAssistantResult) => Promise<void>;
 export declare function handleTelegramAgentEndRuntime<TTurn extends PendingTelegramTurn, TReplyMarkup = unknown>(deps: TelegramAgentEndRuntimeDeps<TTurn, TReplyMarkup>): Promise<void>;
@@ -759,6 +765,7 @@ export interface TelegramQueueDispatchControllerDeps<TContext = unknown> extends
     }>["item"], ctx: TContext) => boolean;
     sendUserMessage: TelegramDispatchRuntimeDeps<TContext>["sendUserMessage"];
     onPromptDispatchFailure: (ctx: TContext, message: string) => void;
+    reconcileNextDispatchAnnouncementReplyOwnership?: (item: PendingTelegramTurn) => void;
     isQueueItemTransportActive?: (item: TelegramQueueItem<TContext>) => boolean;
     hasPendingInboundQueueMutationForItem?: (item: TelegramQueueItem<TContext>) => boolean;
     isQueueItemAdmissionReady?: (item: TelegramQueueItem<TContext>) => boolean;
@@ -768,6 +775,7 @@ export interface TelegramQueueDispatchControllerDeps<TContext = unknown> extends
 export interface TelegramQueueDispatchController<TContext = unknown> {
     dispatchNext: (ctx: TContext) => void;
     requestNextDispatchAnnouncement: () => void;
+    cancelNextDispatchAnnouncement: () => void;
 }
 export declare function executeTelegramQueueDispatchPlan<TContext = unknown>(plan: TelegramQueueDispatchAction<TContext>, deps: TelegramDispatchRuntimeDeps<TContext>): void;
 export type TelegramQueueDispatchRuntimeDeps<TContext = unknown> = Omit<TelegramQueueDispatchControllerDeps<TContext>, "canDispatch"> & TelegramDispatchReadinessDeps<TContext>;

package/node_modules/@llblab/pi-telegram/dist/lib/queue.js

@@ -168,6 +168,18 @@ export function createTelegramActiveTurnStore() {
         clear: () => {
             activeTurn = undefined;
         },
+        markNextAbortAnnouncement: () => {
+            if (!activeTurn)
+                return false;
+            activeTurn.announceNextAbortOnEnd = true;
+            return true;
+        },
+        clearNextAbortAnnouncement: () => {
+            if (!activeTurn?.announceNextAbortOnEnd)
+                return false;
+            delete activeTurn.announceNextAbortOnEnd;
+            return true;
+        },
         getChatId: () => activeTurn?.chatId,
         getTarget: () => activeTurn?.target ? { ...activeTurn.target } : undefined,
         getReplyToMessageId: () => activeTurn?.replyToMessageId,
@@ -815,6 +827,7 @@ export function buildTelegramAgentEndPlan(options) {
             kind: "no-turn",
             shouldClearPreview: false,
             shouldDispatchNext,
+            shouldSendAbortMessage: false,
             shouldSendErrorMessage: false,
             shouldSendAttachmentNotice: false,
         };
@@ -824,6 +837,7 @@ export function buildTelegramAgentEndPlan(options) {
             kind: "aborted",
             shouldClearPreview: true,
             shouldDispatchNext,
+            shouldSendAbortMessage: options.announceNextAbortOnEnd === true,
             shouldSendErrorMessage: false,
             shouldSendAttachmentNotice: false,
         };
@@ -833,6 +847,7 @@ export function buildTelegramAgentEndPlan(options) {
             kind: "error",
             shouldClearPreview: true,
             shouldDispatchNext,
+            shouldSendAbortMessage: false,
             shouldSendErrorMessage: true,
             shouldSendAttachmentNotice: false,
         };
@@ -842,6 +857,7 @@ export function buildTelegramAgentEndPlan(options) {
             kind: "text",
             shouldClearPreview: false,
             shouldDispatchNext,
+            shouldSendAbortMessage: false,
             shouldSendErrorMessage: false,
             shouldSendAttachmentNotice: false,
         };
@@ -851,6 +867,7 @@ export function buildTelegramAgentEndPlan(options) {
             kind: "attachments-only",
             shouldClearPreview: true,
             shouldDispatchNext,
+            shouldSendAbortMessage: false,
             shouldSendErrorMessage: false,
             shouldSendAttachmentNotice: true,
         };
@@ -859,6 +876,7 @@ export function buildTelegramAgentEndPlan(options) {
         kind: "empty",
         shouldClearPreview: true,
         shouldDispatchNext,
+        shouldSendAbortMessage: false,
         shouldSendErrorMessage: false,
         shouldSendAttachmentNotice: false,
     };
@@ -991,6 +1009,7 @@ export async function handleTelegramAgentEndRuntime(deps) {
         hasFinalText: !!finalText || hasOutboundArtifacts,
         hasQueuedAttachments: (turn?.queuedAttachments.length ?? 0) > 0,
         foldQueuedPromptsIntoHistory: deps.foldQueuedPromptsIntoHistory,
+        announceNextAbortOnEnd: turn?.announceNextAbortOnEnd === true,
     });
     if (!turn) {
         if (endPlan.shouldDispatchNext)
@@ -1116,17 +1135,26 @@ export async function handleTelegramAgentEndRuntime(deps) {
             if (!isDeliveryActive())
                 return;
         }
-        if (endPlan.shouldSendErrorMessage) {
+        if (endPlan.shouldSendAbortMessage || endPlan.shouldSendErrorMessage) {
             const errorMessage = assistant.errorMessage ||
                 "Telegram bridge: Pi failed while processing the request.";
-            const isOperationAborted = errorMessage.trim().replace(/\.$/, "") ===
-                "This operation was aborted";
-            await deps.sendTextReply(turn.chatId, turn.replyToMessageId, isOperationAborted
-                ? "<b>⏹️ This operation was aborted.</b>"
-                : errorMessage, {
-                target: turn.target,
-                ...(isOperationAborted ? { parseMode: "HTML" } : {}),
-            });
+            const isOperationAborted = endPlan.shouldSendAbortMessage ||
+                errorMessage.trim().replace(/\.$/, "") === "This operation was aborted";
+            try {
+                await deps.sendTextReply(turn.chatId, turn.replyToMessageId, isOperationAborted
+                    ? "<b>⏹️ This operation was aborted.</b>"
+                    : errorMessage, {
+                    target: turn.target,
+                    ...(isOperationAborted ? { parseMode: "HTML" } : {}),
+                });
+            }
+            catch (error) {
+                if (!isOperationAborted)
+                    throw error;
+                deps.recordRuntimeEvent?.("dispatch", error, {
+                    phase: "next-abort-announcement",
+                });
+            }
             if (!isDeliveryActive())
                 return;
             if (endPlan.shouldDispatchNext)
@@ -1267,7 +1295,7 @@ export async function handleTelegramAgentEndRuntime(deps) {
             deps.dispatchNextQueuedTelegramTurn();
     };
     if (deps.scheduleActiveTurnDelivery &&
-        (endPlan.kind === "text" || endPlan.kind === "attachments-only" || endPlan.shouldSendErrorMessage || endPlan.shouldClearPreview)) {
+        (endPlan.kind === "text" || endPlan.kind === "attachments-only" || endPlan.shouldSendAbortMessage || endPlan.shouldSendErrorMessage || endPlan.shouldClearPreview)) {
         deps.scheduleActiveTurnDelivery(deliverActiveTurn);
         return;
     }
@@ -1765,6 +1793,7 @@ export function createTelegramQueueDispatchRuntime(deps) {
         commitPromptDispatch: deps.commitPromptDispatch,
         sendUserMessage: deps.sendUserMessage,
         onPromptDispatchFailure: deps.onPromptDispatchFailure,
+        reconcileNextDispatchAnnouncementReplyOwnership: deps.reconcileNextDispatchAnnouncementReplyOwnership,
         isQueueItemTransportActive: deps.isQueueItemTransportActive,
         hasPendingInboundQueueMutationForItem: deps.hasPendingInboundQueueMutationForItem,
         isQueueItemAdmissionReady: deps.isQueueItemAdmissionReady,
@@ -1776,12 +1805,19 @@ export function createTelegramQueueDispatchRuntime(deps) {
 export function createTelegramQueueDispatchController(deps) {
     let controlDispatchPending = false;
     let nextDispatchAnnouncementRequested = false;
+    let nextDispatchAnnouncementGeneration = 0;
     let nextDispatchAnnouncementAnchor;
     const controller = {
         requestNextDispatchAnnouncement: () => {
+            nextDispatchAnnouncementGeneration += 1;
             nextDispatchAnnouncementRequested = true;
             nextDispatchAnnouncementAnchor = undefined;
         },
+        cancelNextDispatchAnnouncement: () => {
+            nextDispatchAnnouncementGeneration += 1;
+            nextDispatchAnnouncementRequested = false;
+            nextDispatchAnnouncementAnchor = undefined;
+        },
         dispatchNext: (ctx) => {
             if (deps.hasDispatchContext && !deps.hasDispatchContext())
                 return;
@@ -1972,11 +2008,22 @@ export function createTelegramQueueDispatchController(deps) {
             if (dispatchPlan.kind === "prompt" && nextDispatchAnnouncementRequested) {
                 nextDispatchAnnouncementRequested = false;
                 controlDispatchPending = true;
+                const announcementGeneration = nextDispatchAnnouncementGeneration;
                 const dispatchGeneration = deps.getDispatchGeneration?.();
                 deps.updateStatus(ctx);
                 void deps.sendTextReply(dispatchPlan.item.chatId, dispatchPlan.item.replyToMessageId, "<b>⏩ Dispatching next queued turn.</b>", { target: dispatchPlan.item.target }).catch((error) => {
-                    deps.recordRuntimeEvent?.("dispatch", error, { phase: "next-announcement" });
+                    deps.recordRuntimeEvent?.("dispatch", error, {
+                        phase: "next-announcement",
+                    });
                 }).finally(() => {
+                    try {
+                        deps.reconcileNextDispatchAnnouncementReplyOwnership?.(dispatchPlan.item);
+                    }
+                    catch (error) {
+                        deps.recordRuntimeEvent?.("dispatch", error, {
+                            phase: "next-announcement-reply-ownership",
+                        });
+                    }
                     controlDispatchPending = false;
                     if (deps.hasDispatchContext && !deps.hasDispatchContext())
                         return;
@@ -1984,6 +2031,11 @@ export function createTelegramQueueDispatchController(deps) {
                         deps.isDispatchGenerationActive &&
                         !deps.isDispatchGenerationActive(dispatchGeneration))
                         return;
+                    if (announcementGeneration !== nextDispatchAnnouncementGeneration) {
+                        if (nextDispatchAnnouncementRequested)
+                            controller.dispatchNext(ctx);
+                        return;
+                    }
                     executePlan();
                 });
                 return;

package/node_modules/@llblab/pi-telegram/dist/lib/replies.d.ts

@@ -23,6 +23,10 @@ export interface ReplyDedupRuntime {
 }
 export declare function createReplyDedupRuntime(): ReplyDedupRuntime;
 export declare function resetTransportReplyDedup(): void;
+/** Keeps a successfully published transition notice as the first reply of the
+ * next agent turn. The following agent-start reset consumes this one-shot
+ * preservation, so later messages in that turn do not repeat the reply header. */
+export declare function preserveTransportReplyDedupOnNextReset(chatId: number, messageId: number, target?: TelegramTarget): void;
 export declare function buildTelegramReplyParameters(chatId: number, messageId: number | undefined, target?: TelegramTarget): TelegramReplyParameters | undefined;
 export declare function withTelegramReplyParameters<T>(chatId: number, messageId: number | undefined, target: TelegramTarget | undefined, send: (parameters: TelegramReplyParameters | undefined) => Promise<T>): Promise<T>;
 export declare function isAssistantAgentMessage(message: unknown): boolean;

package/node_modules/@llblab/pi-telegram/dist/lib/replies.js

@@ -31,6 +31,7 @@ export function createReplyDedupRuntime() {
 }
 // --- Transport-level dedup ---
 const lastRepliedToMessageIdByTarget = new Map();
+const replyDedupPreservedOnNextReset = new Map();
 let replyDedupGeneration = 0;
 function getReplyDedupTargetKey(chatId, target) {
     const threadId = target?.threadId;
@@ -41,6 +42,19 @@ function getReplyDedupTargetKey(chatId, target) {
 export function resetTransportReplyDedup() {
     replyDedupGeneration += 1;
     lastRepliedToMessageIdByTarget.clear();
+    for (const [key, messageId] of replyDedupPreservedOnNextReset) {
+        lastRepliedToMessageIdByTarget.set(key, messageId);
+    }
+    replyDedupPreservedOnNextReset.clear();
+}
+/** Keeps a successfully published transition notice as the first reply of the
+ * next agent turn. The following agent-start reset consumes this one-shot
+ * preservation, so later messages in that turn do not repeat the reply header. */
+export function preserveTransportReplyDedupOnNextReset(chatId, messageId, target) {
+    const key = getReplyDedupTargetKey(chatId, target);
+    if (lastRepliedToMessageIdByTarget.get(key) !== messageId)
+        return;
+    replyDedupPreservedOnNextReset.set(key, messageId);
 }
 export function buildTelegramReplyParameters(chatId, messageId, target) {
     if (messageId === undefined || messageId <= 0)

package/node_modules/@llblab/pi-telegram/dist/lib/routing.d.ts

@@ -122,6 +122,7 @@ export interface TelegramInboundRouteRuntimeDeps<TMessage extends TelegramRouted
     isContextActive?: (ctx: TContext) => boolean;
     dispatchNextQueuedTelegramTurn: (ctx: TContext) => void;
     requestNextDispatchAnnouncement?: () => void;
+    cancelNextDispatchAnnouncement?: () => void;
     requestDeferredDispatchNextQueuedTelegramTurn?: (dispatch: (ctx: TContext) => void) => void;
     hasDeferredDispatchContext?: () => boolean;
     startTypingLoop?: (ctx: TContext, chatId?: number, options?: {

package/node_modules/@llblab/pi-telegram/dist/lib/routing.js

@@ -1418,6 +1418,10 @@ export function createTelegramInboundRouteRuntime(deps) {
         isContextActive: deps.isContextActive,
         dispatchNextQueuedTelegramTurn: deps.dispatchNextQueuedTelegramTurn,
         requestNextDispatchAnnouncement: deps.requestNextDispatchAnnouncement,
+        cancelNextTransitionAnnouncements: () => {
+            deps.activeTurnRuntime.clearNextAbortAnnouncement();
+            deps.cancelNextDispatchAnnouncement?.();
+        },
         requestDeferredDispatchNextQueuedTelegramTurn: deps.requestDeferredDispatchNextQueuedTelegramTurn,
         startTypingLoop: deps.startTypingLoop,
         stopTypingLoop: deps.stopTypingLoop,
@@ -1476,6 +1480,7 @@ export function createTelegramInboundRouteRuntime(deps) {
         },
         getPromptTemplateCommands,
         sendTextReply: deps.sendTextReply,
+        markActiveTurnNextAbortAnnouncement: deps.activeTurnRuntime.markNextAbortAnnouncement,
         getActiveTurnReply: () => {
             const activeTurn = deps.activeTurnRuntime.get();
             if (!activeTurn)

package/node_modules/@llblab/pi-telegram/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-telegram",
-  "version": "0.51.0",
+  "version": "0.51.1",
   "private": false,
   "publishConfig": {
     "access": "public"

package/node_modules/@llblab/pi-telegram/docs/architecture.md

@@ -518,7 +518,7 @@ Immediate controls:
 - `/start` opens the main inline application menu.
 - `/model`, `/thinking`, `/queue`, and `/settings` are hidden shortcuts to menu sections.
 - `/compact` opens an inline confirmation dialog and then runs compaction when the bridge is idle.
-- `/next` dispatches the next queued turn, aborting Pi first when needed. Active-turn settlement delivers its abort notice to the interrupted prompt before queue dispatch continues. The queue owner then emits `Dispatching next queued turn.` against the exact selected prompt's chat/thread/reply id before its one model dispatch; skipped, inactive, pending-mutation, and admission-blocked candidates never receive it. The `/next` command itself is never a lifecycle-notice reply target. Aborted pending assistant text is not projected as a second reply, while already completed intermediate output remains visible.
+- `/next` dispatches the next queued turn, aborting Pi first when needed. Target-bound command composition must forward the announcement request, exact-turn marker, superseding cancellation, and deferred-dispatch ports rather than silently dropping them. Active-turn settlement attempts its abort notice against the interrupted prompt before queue dispatch continues; definite or ambiguous notice failure is recorded but cannot block the selected turn. The queue owner then emits `Dispatching next queued turn.` against the exact selected prompt's chat/thread/reply id before its one model dispatch; skipped, inactive, pending-mutation, and admission-blocked candidates never receive it. A successful dispatch notice carries its reply-dedup anchor through the following agent-start reset, so later messages in that turn do not repeat the queued-prompt reply header. A later `/abort` or `/stop` cancels both pending `/next` notices before taking ownership, preventing duplicate abort results and stale future dispatch announcements. The `/next` command itself is never a lifecycle-notice reply target. Aborted pending assistant text is not projected as a second reply, while already completed intermediate output remains visible.
 - `/abort` aborts active work while preserving queued items. Abort-history preservation is enabled only for Telegram-owned active turns; later local/non-Telegram agent starts clear stale abort-history mode so the next Telegram prompt appends instead of absorbing old queued turns as history.
 - `/stop` aborts and clears waiting Telegram queue items.
 

package/node_modules/@llblab/pi-telegram/docs/multi-instance-bus.md

@@ -485,7 +485,7 @@ All files containing routing, chat ids, thread ids, or process details use priva
 
 ### Follower heartbeat is missed
 
-- Leader tolerates up to 15 seconds without a follower heartbeat before pruning it from the live registry, so short local event-loop or IPC stalls do not create false routing gaps. A follower response deadline defers its final timeout through one socket poll phase: an acknowledgement already buffered while the Pi/TUI event loop was blocked wins, while a genuinely silent peer still fails in the same event-loop turn. Heartbeat pruning remains liveness bookkeeping. One leader generation owns at most one prune operation; stop makes late endpoint, policy, and cleanup settlement inert, while durable-profile mutation serialization prevents replacement registration from crossing confirmed-dead cleanup.
+- Leader tolerates up to 15 seconds without a follower heartbeat before pruning it from the live registry, so short local event-loop or IPC stalls do not create false routing gaps. Follower heartbeat requests use a dedicated eight-second response deadline aligned with leader stale-liveness policy rather than the generic one-second local-RPC default. The deadline also defers its final timeout through one socket poll phase: an acknowledgement already buffered while the Pi/TUI event loop was blocked wins, while a genuinely silent peer still fails in the same event-loop turn. Heartbeat pruning remains liveness bookkeeping. One leader generation owns at most one prune operation; stop makes late endpoint, policy, and cleanup settlement inert, while durable-profile mutation serialization prevents replacement registration from crossing confirmed-dead cleanup.
 - A missed heartbeat does not delete, close, mark offline, or send a disconnected notice for the follower's Telegram thread binding because the common cause may be leader reload, IPC handoff, or transient reconnect rather than a dead follower.
 - After removal from live routing, the current leader retains at most 26 volatile preservation observations with exact registered PID, generation, target, profile and leader epoch. The existing prune loop rechecks alive/unverifiable PIDs and retries non-destructive publication only after fresh explicit absence and a known disabled-cleanup policy. Missing identity or overflow stays protected. Observations never answer heartbeat/API/forwarding requests, launch processes, or authorize deletion. Enabling cleanup cancels deferred preservation rather than promoting it into destructive work; the existing first-prune cleanup path is not retried by this mechanism.
 - Registry registration invalidates overlapping instance/profile-owner/target observations, even if that replacement is removed before the next prune. Admitted same-instance provisioning cancels the old observation before its store writes can precede live registration. Profile/epoch drift, registry clear and leader stop invalidate it; late old completion cannot erase a replacement runtime's observation. No observation survives leader restart, reconstructs a PID from an opaque instance ID, or invents legacy inactivity.

package/node_modules/@llblab/pi-telegram/docs/public-api.md

@@ -53,7 +53,7 @@ Stable commands inside the paired Telegram DM:
 - `/start` — pair when needed and open the main application menu.
 - `/new` — after idle and empty-queue checks, request a new Pi session in the current classic chat or Thread. The bridge acknowledges the callback, deletes its confirmation, completes and removes the exact durable update, then dispatches one runtime-armed typed action through the internal `/telegram-internal` Pi gateway using `pi.sendUserMessage(..., { expandPromptTemplates: true })`. Manual invocation reports that the gateway cannot be run manually; the armed handler receives a real `ExtensionCommandContext` and calls `ctx.newSession()`; one discriminated durable intent preserves either exact classic Profile/CWD/session/chat continuity or the Thread binding with slot/name re-key. The successor CAS-claims that intent before sending one terminal result. Busy, identity-mismatch, and unavailable-host paths fail closed.
 - `/compact` — open confirmation and compact when idle.
-- `/next` — abort active work first when needed, let the interrupted prompt receive its abort notice, then reply `Dispatching next queued turn.` to the exact queued prompt selected for the next model turn. The command itself is never the lifecycle-notice reply target, and aborted pending assistant text is suppressed.
+- `/next` — abort active work first when needed, attempt the interrupted prompt's abort notice, then reply `Dispatching next queued turn.` to the exact queued prompt selected for the next model turn. That dispatch notice owns the turn's one reply header; later answer messages do not reply to the same prompt again. Abort-notice failure is diagnostic and cannot block dispatch. A later `/abort` or `/stop` cancels both pending transition notices before taking ownership. The `/next` command itself is never the lifecycle-notice reply target, and aborted pending assistant text is suppressed.
 - `/continue` — enqueue a priority `continue` prompt.
 - `/abort` — abort active work and keep the queue; abort-history is scoped to Telegram-owned active turns.
 - `/stop` — abort active Telegram-owned work and clear waiting Telegram queue items.