@llblab/pi-telegram 0.55.1 → 0.56.1

package/dist/lib/queue.js

@@ -1,7 +1,7 @@
 /**
  * Telegram queue core contracts and pure planning helpers
  * Zones: telegram queue, pi agent lifecycle, scheduling
- * Owns queue item contracts, lane admission, pure queue mutations, and dispatch planning
+ * Owns queue item contracts, lane admission, mutations, dispatch planning, and protected Steer publication attempts
  */
 import { createHash } from "node:crypto";
 import { isPiStaleContextError } from "./pi.js";
@@ -18,16 +18,22 @@ export const TELEGRAM_QUEUE_LANE_CONTRACTS = [
         dispatchRank: 0,
         allowedKinds: ["control", "prompt"],
     },
+    {
+        lane: "steer",
+        admissionMode: "steer-queue",
+        dispatchRank: 1,
+        allowedKinds: ["prompt"],
+    },
     {
         lane: "priority",
         admissionMode: "priority-queue",
-        dispatchRank: 1,
+        dispatchRank: 2,
         allowedKinds: ["prompt"],
     },
     {
         lane: "default",
         admissionMode: "default-queue",
-        dispatchRank: 2,
+        dispatchRank: 3,
         allowedKinds: ["prompt"],
     },
 ];
@@ -59,7 +65,8 @@ function parseQueuePayloadReceipt(value, kind) {
 /** Data decoder shared by authenticated IPC and cold storage; decoding grants no admission. */
 export function parseTelegramQueueHandoffPayload(value) {
     if (!isQueuePayloadRecord(value) ||
-        (value.kind !== "prompt" && value.kind !== "control"))
+        (value.kind !== "prompt" && value.kind !== "control") ||
+        value.steerAttempted !== undefined || value.steerPacketTail !== undefined || value.steerPacketSourceOrders !== undefined)
         return undefined;
     const target = isQueuePayloadRecord(value.target) &&
         typeof value.target.chatId === "number"
@@ -88,6 +95,7 @@ export function parseTelegramQueueHandoffPayload(value) {
             typeof value.guestInlineMessageId !== "string") ||
         !Number.isSafeInteger(value.queueOrder) ||
         (value.queueLane !== "control" &&
+            value.queueLane !== "steer" &&
             value.queueLane !== "priority" &&
             value.queueLane !== "default") ||
         !Number.isSafeInteger(value.laneOrder) ||
@@ -123,6 +131,7 @@ export function parseTelegramQueueHandoffPayload(value) {
             : undefined;
     }
     if (value.queueLane === "control" ||
+        (value.queueLane === "steer" && (value.guestQueryId !== undefined || value.guestInlineMessageId !== undefined)) ||
         !Array.isArray(value.sourceMessageIds) ||
         value.sourceMessageIds.some((id) => !Number.isSafeInteger(id)) ||
         !Array.isArray(value.queuedAttachments) ||
@@ -282,7 +291,8 @@ function isTelegramQueueItemSkipped(item) {
     return item.kind === "prompt" && Boolean(item.reactionSuppressionEmoji);
 }
 export function countExecutableTelegramQueueItems(items) {
-    return items.filter((item) => !isTelegramQueueItemSkipped(item)).length;
+    return items.filter((item) => !isTelegramQueueItemSkipped(item) &&
+        !(item.kind === "prompt" && item.steerAttempted)).length;
 }
 export function createTelegramQueueItemCountGetter(store) {
     return () => countExecutableTelegramQueueItems(store.getQueuedItems());
@@ -349,7 +359,7 @@ export function partitionTelegramQueueItemsForHistory(items) {
     const historyTurns = [];
     const remainingItems = [];
     for (const item of items) {
-        if (isPendingTelegramTurn(item)) {
+        if (isPendingTelegramTurn(item) && item.queueLane !== "steer" && !item.steerAttempted) {
             historyTurns.push(item);
             continue;
         }
@@ -417,7 +427,7 @@ export function createTelegramQueueHandoff(input) {
     }
     const handoff = {
         handoffToken: input.handoffToken,
-        payload: createTelegramQueueHandoffPayload(input.item),
+        payload: createTelegramQueueHandoffPayload(input.item, { steerSupported: input.steerSupported }),
     };
     if (Buffer.byteLength(JSON.stringify(handoff)) >
         TELEGRAM_QUEUE_HANDOFF_PAYLOAD_MAX_BYTES) {
@@ -425,8 +435,17 @@ export function createTelegramQueueHandoff(input) {
     }
     return handoff;
 }
-export function createTelegramQueueHandoffPayload(item) {
+export function createTelegramQueueHandoffPayload(item, options = {}) {
     assertTelegramQueueItemAdmissionValid(item);
+    if (item.kind === "prompt" && (item.steerAttempted || item.steerPacketTail !== undefined || item.steerPacketSourceOrders !== undefined)) {
+        throw new Error("Attempted Steer work cannot be transferred.");
+    }
+    if (item.queueLane === "steer" && (item.guestQueryId !== undefined || item.guestInlineMessageId !== undefined)) {
+        throw new Error("Guest prompts cannot use Steer queue transfer.");
+    }
+    if (item.queueLane === "steer" && options.steerSupported !== true) {
+        throw new Error("Steer queue transfer requires compatible lane support.");
+    }
     if (!item.admissionReceipts?.length) {
         throw new Error("Telegram queue handoff requires durable admission receipts.");
     }
@@ -639,6 +658,7 @@ export function removeTelegramQueueItemsByMessageIds(items, messageIds, scope) {
     const removedItems = [];
     for (const item of items) {
         const shouldRemove = isPendingTelegramTurn(item) &&
+            !item.steerAttempted &&
             isTelegramQueueItemInMessageScope(item, scope) &&
             item.sourceMessageIds.some((messageId) => deletedMessageIds.has(messageId));
         (shouldRemove ? removedItems : nextItems).push(item);
@@ -665,9 +685,15 @@ function removeTelegramQueuedGuestPromptByOrder(items, queueOrder) {
     };
 }
 export function applyTelegramQueuePromptReactionDisposition(items, messageId, disposition, destinationLaneOrder, scope) {
+    if (disposition.kind === "reaction-transition" &&
+        disposition.promptLane !== undefined &&
+        !["steer", "priority", "default"].includes(disposition.promptLane)) {
+        throw new Error("Telegram prompt lane selection is invalid.");
+    }
     let nextItems = items;
     for (const [index, item] of items.entries()) {
         if (!isPendingTelegramTurn(item) ||
+            item.steerAttempted ||
             item.queueLane === "control" ||
             !isTelegramQueueItemInMessageScope(item, scope) ||
             !item.sourceMessageIds.includes(messageId)) {
@@ -679,7 +705,12 @@ export function applyTelegramQueuePromptReactionDisposition(items, messageId, di
                 : disposition.priorityEmoji !== null
             : disposition.kind === "priority" ||
                 disposition.kind === "priority-suppressed";
-        const queueLane = isPriority ? "priority" : "default";
+        const queueLane = disposition.kind === "reaction-transition"
+            ? (disposition.promptLane ??
+                (disposition.priorityEmoji === undefined
+                    ? item.queueLane
+                    : isPriority ? "priority" : "default"))
+            : isPriority ? "priority" : "default";
         const laneOrder = item.queueLane === queueLane ? item.laneOrder : destinationLaneOrder;
         if (laneOrder === undefined) {
             throw new Error("Telegram destination lane order is unavailable.");
@@ -728,12 +759,13 @@ export function consumeDispatchedTelegramPrompt(items, hasPendingDispatch) {
     if (!nextItem || !isPendingTelegramTurn(nextItem)) {
         return { activeTurn: undefined, remainingItems: items };
     }
+    if (nextItem.steerPacketTail !== undefined) {
+        const packet = [nextItem, ...nextItem.steerPacketTail];
+        const originals = new Set(packet);
+        return { activeTurn: projectTelegramSteerPacketTurn(packet), remainingItems: items.filter(item => !originals.has(item)) };
+    }
     return { activeTurn: nextItem, remainingItems: items.slice(1) };
 }
-export function formatQueuedTelegramItemsStatus(items) {
-    const count = countExecutableTelegramQueueItems(items);
-    return count === 0 ? "" : ` +${count}`;
-}
 export function truncateTelegramQueueSummary(text, maxWords = 5, maxLength = 40) {
     const normalized = text.replace(/\s+/g, " ").trim();
     if (!normalized)
@@ -789,6 +821,170 @@ export function createTelegramControlItemBuilder(deps) {
         laneOrder: deps.allocateControlOrder(),
     });
 }
+/** Plan a fixed ready prefix; publication/settlement remain with the Queue effect shell. */
+export function planTelegramSteerPacket(items, options) {
+    if (options.blocked)
+        return { kind: "none" };
+    const ordered = [...items].sort(compareTelegramQueueItems);
+    if (ordered.some((item) => item.queueLane === "control" && options.isItemReady(item))) {
+        return { kind: "none" };
+    }
+    const packet = [];
+    for (const item of ordered) {
+        if (item.queueLane !== "steer" || !isPendingTelegramTurn(item))
+            continue;
+        if (item.steerAttempted || !options.isItemReady(item) || item.guestQueryId !== undefined || item.guestInlineMessageId !== undefined)
+            break;
+        if (item.reactionSuppressionEmoji) {
+            if (packet.length === 0)
+                return { kind: "skip", item };
+            break;
+        }
+        const first = packet[0];
+        if (first && !isSameTelegramPromptNamespace(first, item))
+            break;
+        if (options.canAppend && !options.canAppend(packet, item))
+            break;
+        packet.push(item);
+    }
+    return packet.length > 0 ? { kind: "packet", items: packet } : { kind: "none" };
+}
+function buildTelegramSteerPacketContent(packet, idleTask = false) {
+    const content = packet.flatMap((item, index) => [
+        ...(index > 0 ? [{ type: "text", text: "\n\n" }] : []), ...item.content,
+    ]);
+    // Ordinary idle prompts must retain origin detection by before_agent_start.
+    return idleTask ? [{ type: "text", text: "[telegram]\n" }, ...content] : content;
+}
+function createTelegramSteerPacketBudget(idleTask = false) {
+    let packetBytes = idleTask ? 64 : 0;
+    return (packet, item) => {
+        const bytes = Buffer.byteLength(JSON.stringify(item.content)) +
+            (packet.length > 0 ? Buffer.byteLength("\n\n") : 0) + 64;
+        if (packetBytes + bytes > TELEGRAM_QUEUE_HANDOFF_PAYLOAD_MAX_BYTES)
+            return false;
+        packetBytes += bytes;
+        return true;
+    };
+}
+export function isTelegramSteerItemWithinIdleCapacity(item) {
+    return createTelegramSteerPacketBudget(true)([], item);
+}
+function projectTelegramSteerPacketTurn(packet) {
+    const first = packet[0];
+    if (!first)
+        throw new Error("Steer packet cannot be empty.");
+    const projected = {
+        ...first,
+        content: buildTelegramSteerPacketContent(packet, true),
+        historyText: packet.map(item => item.historyText).join("\n\n"),
+        sourceMessageIds: [...new Set(packet.flatMap(item => item.sourceMessageIds))],
+        queuedAttachments: packet.flatMap(item => item.queuedAttachments),
+        admissionReceipts: packet.flatMap(item => item.admissionReceipts ?? []),
+        voiceReplyPreferred: packet.some(item => item.voiceReplyPreferred === true),
+        voiceReplyRequired: packet.some(item => item.voiceReplyRequired === true),
+        steerPacketSourceOrders: packet.map(item => item.queueOrder),
+    };
+    delete projected.steerPacketTail;
+    return projected;
+}
+function isSameTelegramPromptNamespace(left, right) {
+    return left.chatId === right.chatId &&
+        left.target?.chatId === right.target?.chatId &&
+        left.target?.threadId === right.target?.threadId &&
+        left.transportStamp?.profile === right.transportStamp?.profile &&
+        left.transportStamp?.generation === right.transportStamp?.generation;
+}
+/** One publication attempt; journal ACK is source disposition, never SDK/model-use confirmation. */
+export function createTelegramSteerBoundaryRuntime(deps) {
+    const updateStatus = (ctx) => {
+        try {
+            if (deps.isContextCurrent(ctx))
+                deps.updateStatus(ctx);
+        }
+        catch (error) {
+            if (!isPiStaleContextError(error)) {
+                try {
+                    deps.recordRuntimeEvent?.("queue", error, { phase: "steer-status" });
+                }
+                catch { /* Diagnostic failure cannot replay input. */ }
+            }
+        }
+    };
+    const report = (error, phase, ctx) => {
+        try {
+            deps.recordRuntimeEvent?.("queue", error, { phase });
+        }
+        catch { /* Diagnostics cannot replay input. */ }
+        updateStatus(ctx);
+    };
+    return {
+        onTurnEnd(event, ctx) {
+            const generation = deps.getGeneration();
+            const current = () => deps.isContextCurrent(ctx) && generation === deps.getGeneration();
+            const blocked = () => !current() || event.outcome !== "completed" || deps.isBlocked(ctx);
+            try {
+                if (blocked())
+                    return;
+                const matchesActive = (item) => {
+                    const active = deps.getActiveTurn();
+                    return item.kind !== "prompt" || !active || isSameTelegramPromptNamespace(active, item);
+                };
+                const ready = (item) => deps.isItemReady(item, ctx) && matchesActive(item);
+                // Skipped heads settle under the same exact owner before recapturing a fresh packet.
+                const budget = deps.getQueuedItems().length;
+                for (let index = 0; index <= budget; index++) {
+                    const plan = planTelegramSteerPacket(deps.getQueuedItems(), {
+                        blocked: blocked(), isItemReady: ready, canAppend: createTelegramSteerPacketBudget(),
+                    });
+                    if (plan.kind === "none")
+                        return;
+                    if (plan.kind === "skip") {
+                        if (blocked() || !deps.discardItem(plan.item, ctx))
+                            return;
+                        if (!current())
+                            return;
+                        deps.setQueuedItems(deps.getQueuedItems().filter(item => item !== plan.item));
+                        continue;
+                    }
+                    const packet = plan.items;
+                    const content = buildTelegramSteerPacketContent(packet);
+                    const draft = {
+                        type: "custom_message", customType: "telegram-steer", content, display: true,
+                        details: { boundaryTurnIndex: event.turnIndex, queueOrders: packet.map(item => item.queueOrder) },
+                    };
+                    if (packet.some(item => !ready(item)) ||
+                        packet.some(item => !deps.getQueuedItems().includes(item)) || blocked())
+                        return;
+                    // Keep the same Queue objects/receipts: a refused prefix cannot become a new attempt.
+                    for (const item of packet)
+                        item.steerAttempted = true;
+                    if (!deps.commitPacket(packet, ctx)) {
+                        report(new Error("Steer packet receipt settlement is unconfirmed."), "steer-settlement-unconfirmed", ctx);
+                        return;
+                    }
+                    if (blocked() || packet.some(item => !matchesActive(item) ||
+                        !deps.isItemCurrent(item, ctx) || !deps.getQueuedItems().includes(item))) {
+                        report(new Error("Steer packet authority changed before publication."), "steer-publication-refused", ctx);
+                        return;
+                    }
+                    const selected = new Set(packet);
+                    deps.setQueuedItems(deps.getQueuedItems().filter(item => !selected.has(item)));
+                    updateStatus(ctx);
+                    if (!current() || deps.isBlocked(ctx)) {
+                        report(new Error("Steer publication was refused after source disposition."), "steer-publication-refused", ctx);
+                        return;
+                    }
+                    return { entries: [draft], continue: true };
+                }
+            }
+            catch (error) {
+                report(error, "steer-attempt-failed", ctx);
+            }
+            return undefined;
+        },
+    };
+}
 export function planNextTelegramQueueAction(items, canDispatch) {
     if (!canDispatch || items.length === 0) {
         return { kind: "none", remainingItems: items };
@@ -799,6 +995,11 @@ export function planNextTelegramQueueAction(items, canDispatch) {
     }
     assertTelegramQueueItemAdmissionValid(firstItem);
     if (isPendingTelegramTurn(firstItem)) {
+        if (firstItem.steerAttempted)
+            return { kind: "none", remainingItems: items };
+        // Steer needs whole-packet idle/boundary dispatch, never this single-prompt fallback.
+        if (firstItem.queueLane === "steer")
+            return { kind: "none", remainingItems: items };
         return { kind: "prompt", item: firstItem, remainingItems: items };
     }
     return { kind: "control", item: firstItem, remainingItems };
@@ -1697,7 +1898,12 @@ export function removeTelegramQueueItemsByMessageIdsRuntime(messageIds, deps, sc
     return removedCount;
 }
 function removeTelegramQueuedGuestPromptByOrderRuntime(queueOrder, deps) {
-    const { items, removedItems, removedCount } = removeTelegramQueuedGuestPromptByOrder(deps.getQueuedItems(), queueOrder);
+    const queuedItems = deps.getQueuedItems();
+    const head = queuedItems[0];
+    // agent_start must consume the issued guest, not adopt the next waiting reply owner.
+    if (deps.hasPendingDispatch?.() && head?.queueOrder === queueOrder)
+        return false;
+    const { items, removedItems, removedCount } = removeTelegramQueuedGuestPromptByOrder(queuedItems, queueOrder);
     if (removedCount === 0)
         return false;
     // A menu Skip means permanent discard, so settle durable admission before
@@ -1709,6 +1915,10 @@ function removeTelegramQueuedGuestPromptByOrderRuntime(queueOrder, deps) {
 }
 export function applyTelegramQueuePromptReactionDispositionRuntime(messageId, disposition, deps, scope) {
     const queuedItems = deps.getQueuedItems();
+    const head = queuedItems[0];
+    if (deps.hasPendingDispatch?.() && head?.kind === "prompt" &&
+        isTelegramQueueItemInMessageScope(head, scope) && head.sourceMessageIds.includes(messageId))
+        return false;
     const suppression = disposition.kind === "reaction-transition"
         ? disposition.suppressionEmoji
         : disposition.kind === "suppressed"
@@ -1736,17 +1946,16 @@ export function applyTelegramQueuePromptReactionDispositionRuntime(messageId, di
     }
     const changesLane = queuedItems.some((item) => {
         if (!isPendingTelegramTurn(item) ||
+            item.steerAttempted ||
             item.queueLane === "control" ||
             !isTelegramQueueItemInMessageScope(item, scope) ||
             !item.sourceMessageIds.includes(messageId)) {
             return false;
         }
         const queueLane = disposition.kind === "reaction-transition"
-            ? disposition.priorityEmoji === undefined
+            ? (disposition.promptLane ?? (disposition.priorityEmoji === undefined
                 ? item.queueLane
-                : disposition.priorityEmoji === null
-                    ? "default"
-                    : "priority"
+                : disposition.priorityEmoji === null ? "default" : "priority"))
             : disposition.kind === "priority" ||
                 disposition.kind === "priority-suppressed"
                 ? "priority"
@@ -1779,6 +1988,8 @@ export async function enqueueTelegramPromptTurnRuntime(messages, deps) {
     const remainingItems = deps.getQueuedItems().filter((item, index) => {
         if ((pendingDispatch && index === 0) ||
             !isPendingTelegramTurn(item) ||
+            item.steerAttempted ||
+            item.queueLane === "steer" ||
             !historyOrders.has(item.queueOrder))
             return true;
         historyTurns.push(item);
@@ -1957,6 +2168,8 @@ export function executeTelegramQueueDispatchPlan(plan, deps) {
         deps.executeControlItem(plan.item);
         return;
     }
+    if (plan.kind === "steer")
+        throw new Error("Steer packet requires dedicated Queue dispatch.");
     deps.onPromptDispatchStart(plan.item.chatId, plan.item.target);
     try {
         if (deps.commitPromptDispatch && !deps.commitPromptDispatch(plan.item)) {
@@ -1990,6 +2203,7 @@ export function createTelegramQueueDispatchRuntime(deps) {
         sendUserMessage: deps.sendUserMessage,
         onPromptDispatchFailure: deps.onPromptDispatchFailure,
         reconcileNextDispatchAnnouncementReplyOwnership: deps.reconcileNextDispatchAnnouncementReplyOwnership,
+        steerDispatch: deps.steerDispatch,
         isQueueItemTransportActive: deps.isQueueItemTransportActive,
         hasPendingInboundQueueMutationForItem: deps.hasPendingInboundQueueMutationForItem,
         isQueueItemAdmissionReady: deps.isQueueItemAdmissionReady,
@@ -2027,6 +2241,11 @@ export function createTelegramQueueDispatchController(deps) {
             const retainedItems = [];
             let droppedInactiveItemCount = 0;
             for (const item of queuedItems) {
+                if (item.kind === "prompt" && item.steerAttempted) {
+                    protectedInactiveItems.push(item);
+                    retainedItems.push(item);
+                    continue;
+                }
                 if (!deps.isQueueItemTransportActive ||
                     deps.isQueueItemTransportActive(item)) {
                     activeItems.push(item);
@@ -2116,19 +2335,34 @@ export function createTelegramQueueDispatchController(deps) {
                 return;
             }
             const dispatchBasisItems = deps.getQueuedItems();
-            const dispatchPlan = planNextTelegramQueueAction(dispatchableItems, canDispatch);
+            let dispatchPlan = planNextTelegramQueueAction(dispatchableItems, canDispatch);
+            if (canDispatch && nextItem?.kind === "prompt" && nextItem.queueLane === "steer" &&
+                deps.steerDispatch && deps.steerDispatch.isContextCurrent?.(ctx) !== false &&
+                deps.steerDispatch.canSubmit?.(ctx) !== false) {
+                const packetPlan = planTelegramSteerPacket(deps.getQueuedItems(), {
+                    blocked: false,
+                    isItemReady: item => deps.isQueueItemTransportActive?.(item) !== false &&
+                        deps.hasPendingInboundQueueMutationForItem?.(item) !== true &&
+                        deps.isQueueItemAdmissionReady?.(item) !== false,
+                    canAppend: createTelegramSteerPacketBudget(true),
+                });
+                if (packetPlan.kind === "packet" && packetPlan.items[0] === nextItem) {
+                    dispatchPlan = { kind: "steer", item: nextItem, packet: packetPlan.items, remainingItems: dispatchableItems };
+                }
+            }
             const commitDispatchPlan = () => {
                 if (dispatchPlan.kind === "none")
                     return true;
                 const currentItems = deps.getQueuedItems();
-                if (dispatchPlan.kind === "prompt") {
+                if (dispatchPlan.kind === "prompt" || dispatchPlan.kind === "steer") {
+                    const inputs = dispatchPlan.kind === "steer" ? dispatchPlan.packet : [dispatchPlan.item];
                     const queueDrifted = currentItems.length !== dispatchBasisItems.length ||
                         currentItems.some((item, index) => item !== dispatchBasisItems[index]);
                     const dispatchEligibilityDrifted = !deps.canDispatch(ctx) ||
-                        deps.hasPendingInboundQueueMutationForItem?.(dispatchPlan.item) ===
-                            true ||
-                        deps.isQueueItemAdmissionReady?.(dispatchPlan.item) === false ||
-                        deps.isQueueItemTransportActive?.(dispatchPlan.item) === false;
+                        (dispatchPlan.kind === "steer" && (deps.steerDispatch?.isContextCurrent?.(ctx) === false ||
+                            deps.steerDispatch?.canSubmit?.(ctx) === false)) ||
+                        inputs.some(item => deps.hasPendingInboundQueueMutationForItem?.(item) === true ||
+                            deps.isQueueItemAdmissionReady?.(item) === false || deps.isQueueItemTransportActive?.(item) === false);
                     if (queueDrifted || dispatchEligibilityDrifted) {
                         const selectedItemRetained = currentItems.includes(dispatchPlan.item);
                         const selectedTransportActive = deps.isQueueItemTransportActive?.(dispatchPlan.item) !== false;
@@ -2156,6 +2390,60 @@ export function createTelegramQueueDispatchController(deps) {
             const executePlan = () => {
                 if (!commitDispatchPlan())
                     return;
+                if (dispatchPlan.kind === "steer") {
+                    const { packet, item: first } = dispatchPlan;
+                    const content = buildTelegramSteerPacketContent(packet, true);
+                    const generation = deps.getDispatchGeneration?.();
+                    const current = () => {
+                        try {
+                            return (!deps.hasDispatchContext || deps.hasDispatchContext()) &&
+                                (generation === undefined || deps.isDispatchGenerationActive?.(generation) !== false) &&
+                                deps.steerDispatch?.isContextCurrent?.(ctx) !== false;
+                        }
+                        catch {
+                            return false;
+                        }
+                    };
+                    const refuse = (message) => {
+                        deps.recordRuntimeEvent?.("dispatch", new Error(message), { phase: "steer-idle-attempt" });
+                        if (current())
+                            deps.onPromptDispatchFailure(ctx, message);
+                    };
+                    controlDispatchPending = true;
+                    try {
+                        for (const item of packet)
+                            item.steerAttempted = true;
+                        if (deps.steerDispatch?.commitPacket(packet, ctx) !== true) {
+                            refuse("Steer packet receipt settlement is unconfirmed.");
+                            return;
+                        }
+                        const sourceChanged = packet.some(item => !deps.getQueuedItems().includes(item) ||
+                            deps.isQueueItemTransportActive?.(item) === false || deps.hasPendingInboundQueueMutationForItem?.(item) === true);
+                        const readyControl = deps.getQueuedItems().some(item => item.queueLane === "control" &&
+                            deps.isQueueItemTransportActive?.(item) !== false && deps.isQueueItemAdmissionReady?.(item) !== false);
+                        if (!current() || deps.steerDispatch?.canSubmit?.(ctx) === false || !deps.canDispatch(ctx) || sourceChanged || readyControl) {
+                            refuse("Steer packet lost idle readiness before submission.");
+                            return;
+                        }
+                        first.steerPacketTail = packet.slice(1);
+                        // Pin the original head, retaining every original until agent_start consumes the packet.
+                        deps.setQueuedItems([first, ...deps.getQueuedItems().filter(item => item !== first)]);
+                        deps.onPromptDispatchStart(ctx, first.chatId, first.target);
+                        if (!current() || deps.steerDispatch?.canSubmit?.(ctx) === false || packet.some(item => !deps.getQueuedItems().includes(item) ||
+                            deps.isQueueItemTransportActive?.(item) === false || deps.hasPendingInboundQueueMutationForItem?.(item) === true)) {
+                            refuse("Steer packet authority changed before submission.");
+                            return;
+                        }
+                        deps.sendUserMessage(content);
+                    }
+                    catch (error) {
+                        refuse(getTelegramQueueErrorMessage(error));
+                    }
+                    finally {
+                        controlDispatchPending = false;
+                    }
+                    return;
+                }
                 executeTelegramQueueDispatchPlan(dispatchPlan, {
                     executeControlItem: (item) => {
                         controlDispatchPending = true;
@@ -2203,7 +2491,7 @@ export function createTelegramQueueDispatchController(deps) {
                     },
                 });
             };
-            if (dispatchPlan.kind === "prompt" && nextDispatchAnnouncementRequested) {
+            if ((dispatchPlan.kind === "prompt" || dispatchPlan.kind === "steer") && nextDispatchAnnouncementRequested) {
                 nextDispatchAnnouncementRequested = false;
                 controlDispatchPending = true;
                 const announcementGeneration = nextDispatchAnnouncementGeneration;

package/dist/lib/routing.d.ts

@@ -113,6 +113,8 @@ export declare function createTelegramLiveRebindCoordinator(input: {
     operationId: string;
     /** Body-free copy of the authenticated saved command reference: correlation only, never authority, an ACK or a cleanup permit. */
     selectedCommandReference(): TelegramLiveRebindSelectedCommandReference | undefined;
+    /** Observe only an already-issued leader command; never prepares, relocates or executes input. */
+    observeCommandCompletion(): "unknown" | "released" | undefined;
     advance(): Promise<"protected" | "unknown" | "released">;
 };
 /** One admitted Restore attempt through recipient readiness, never source dispatch or cleanup. */
@@ -212,6 +214,8 @@ export interface TelegramInboundRouteRuntimeDeps<TMessage extends TelegramRouted
     /** Quiet period after the last cancelled input before one cleanup attempt; defaults to 0 ms. */
     temporaryThreadCleanupDelayMs?: number;
     /** Live-rebind cleanup attempt pacing; the bounded window ends in `not-issued`, never a time-based deletion. */
+    /** Bounded ACK observation inside the original chooser admission, independent from menu/reply delivery. */
+    liveRebindCommandCompletionTimeoutMs?: number;
     liveRebindCleanupSchedule?: {
         delaysMs: readonly number[];
         intervalMs: number;

package/dist/lib/routing.js

@@ -584,6 +584,20 @@ export function createTelegramLiveRebindCoordinator(input) {
                 }
                 : undefined;
         },
+        /** Observe only an already-issued leader command; never prepares, relocates or executes input. */
+        observeCommandCompletion() {
+            if (!continuationIssued || !leader?.complete)
+                return undefined;
+            if (!current())
+                return "unknown";
+            try {
+                return observeCommandCompletion();
+            }
+            catch (error) {
+                input.recordRuntimeEvent?.("telegram", error, { phase: "live-rebind-command-observation" });
+                return "unknown";
+            }
+        },
         async advance() {
             if (advancing || !current())
                 return "protected";
@@ -3100,7 +3114,7 @@ export function createTelegramInboundRouteRuntime(deps) {
                 Bus.isSameTelegramBusFollowerRegistration(live, follower) &&
                 [
                     ...Bus.TELEGRAM_BUS_LIVE_REBIND_CAPABILITIES,
-                    ...(heldSelected ? Bus.TELEGRAM_BUS_HELD_COMMAND_CAPABILITIES : []),
+                    ...(heldSelected ? Bus.getTelegramBusHeldCommandCapabilities(heldSelected.name) : []),
                 ].every((cap) => Bus.hasTelegramBusCapability(live.protocol, cap)) &&
                 !!live.target &&
                 live.target.chatId === binding.target.chatId &&
@@ -3653,6 +3667,7 @@ export function createTelegramInboundRouteRuntime(deps) {
         return {
             operationId: request.operationId,
             selectedCommandReference: () => coordinator?.selectedCommandReference(),
+            observeCommandCompletion: () => coordinator?.observeCommandCompletion(),
             async advance() {
                 if (!coordinator) {
                     if (!current() || !getRecipient())
@@ -6184,6 +6199,52 @@ export function createTelegramInboundRouteRuntime(deps) {
                 const operationId = selection.coordinator.operationId;
                 if (current())
                     outcome = await selection.coordinator.advance();
+                const completionTimeoutMs = deps.liveRebindCommandCompletionTimeoutMs ?? 0;
+                if (outcome === "unknown" && !selection.commandCompletionWaited && selection.record.owner?.kind === "leader" &&
+                    (selection.helpCommand || selection.menuCommand || selection.abortCommand || selection.nextCommand || selection.stopCommand) &&
+                    Number.isFinite(completionTimeoutMs) && completionTimeoutMs > 0 &&
+                    selection.coordinator.observeCommandCompletion() !== undefined) {
+                    selection.commandCompletionWaited = true;
+                    const coordinator = selection.coordinator;
+                    const signal = Updates.getTelegramUpdateExecutionFence(query)?.signal;
+                    outcome = await new Promise((resolve) => {
+                        let settled = false;
+                        const subscriptions = [];
+                        const finish = (result) => {
+                            if (settled)
+                                return;
+                            settled = true;
+                            clearTimeout(timer);
+                            for (const unsubscribe of subscriptions)
+                                unsubscribe();
+                            signal?.removeEventListener("abort", abort);
+                            resolve(result);
+                        };
+                        const abort = () => finish("unknown");
+                        const observe = () => {
+                            if (settled)
+                                return;
+                            if (!current()) {
+                                finish("unknown");
+                                return;
+                            }
+                            if (coordinator.observeCommandCompletion() === "released")
+                                finish("released");
+                        };
+                        const timer = setTimeout(abort, completionTimeoutMs);
+                        timer.unref?.();
+                        for (const message of selection.messages) {
+                            const unsubscribe = Updates.subscribeTelegramDeferredSourceCompletion(message, observe);
+                            if (unsubscribe)
+                                subscriptions.push(unsubscribe);
+                        }
+                        signal?.addEventListener("abort", abort, { once: true });
+                        if (signal?.aborted || !current())
+                            abort();
+                        else if (coordinator.observeCommandCompletion() === "released")
+                            finish("released");
+                    });
+                }
                 // Cleanup readiness follows the canonical released row, not source disposal: a detached command ACK may
                 // still be pending while every attempt samples current work afresh.
                 const row = outcome === "protected"

package/dist/lib/status.d.ts

@@ -6,7 +6,7 @@
  */
 /** UI copy is allowlisted; raw exception text belongs only in redacted diagnostics. */
 export declare function formatTelegramConnectionFailure(error: unknown): string;
-export type TelegramStatusQueueLane = "control" | "priority" | "default";
+export type TelegramStatusQueueLane = "control" | "steer" | "priority" | "default";
 export interface TelegramUsageStats {
     totalInput: number;
     totalOutput: number;
@@ -345,7 +345,6 @@ export interface TelegramBridgeStatusRuntimeDeps<TQueueItem extends {
     hasPendingModelSwitch: () => boolean;
     getQueuedItems: () => TQueueItem[];
     getQueuedItemCount?: (items: TQueueItem[]) => number;
-    formatQueuedStatus: (items: TQueueItem[]) => string;
     getRecentRuntimeEvents: () => TelegramRuntimeEvent[];
     getRuntimeLockState?: () => string;
     getBusRole?: () => TelegramBridgeBusRole | undefined;