@llblab/pi-kit 0.10.4 → 0.10.6

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to `@llblab/pi-kit` are documented here.
 
+## 0.10.6 - 2026-09-12
+
+- `Guest Placeholder And Delivery`: Advances the exact Telegram pin to `0.45.6`, so the guest ACK rotates the globe placeholder in whole cycles and holds `🌏 Working on it...`, guest answers are still delivered when a companion extension suppresses the final assistant message, `429` retry waits are recorded as `api` runtime events, the Thread display settings card drops the manual `/name` hint, and empty-queue headings carry no trailing period. The package set, resource inventory, and explicit load order remain unchanged.
+
+## 0.10.5 - 2026-09-11
+
+- `State Flow Telegram Surface`: Advances the exact State Flow pin to `0.9.6`, so the submenu help line is exactly what State Flow records and when a new session resumes from the last committed point, and the state value (`off` or `#N`) renders in monospace. The package set, resource inventory, and explicit load order remain unchanged.
+
 ## 0.10.4 - 2026-09-11
 
 - `State Flow Telegram Surface`: Advances the exact State Flow pin to `0.9.5`, so the submenu help line opens directly with what State Flow records and when to start or stop it, without the former introductory prefix. The package set, resource inventory, and explicit load order remain unchanged.

package/README.md

@@ -14,8 +14,8 @@ Package links lead to the owning repositories for usage, documentation, issues,
 | [`@llblab/pi-clean-room`](https://github.com/llblab/pi-clean-room) | `0.1.1` | Isolated nested Pi TUI with explicitly selected extensions |
 | [`@llblab/pi-codex-usage`](https://github.com/llblab/pi-codex-usage) | `0.9.4` | Compact Codex/Spark subscription-limit status |
 | [`@llblab/pi-grow-loop`](https://github.com/llblab/pi-grow-loop) | `0.8.1` | Visible continuation scheduling and bounded worker Skills |
-| [`@llblab/pi-state-flow`](https://github.com/llblab/pi-state-flow) | `0.9.5` | Atomic scoped state cohorts with final-eligibility resolution |
-| [`@llblab/pi-telegram`](https://github.com/llblab/pi-telegram) | `0.45.5` | Telegram companion, queues, files, voice, controls, and Generative Apps guidance |
+| [`@llblab/pi-state-flow`](https://github.com/llblab/pi-state-flow) | `0.9.6` | Atomic scoped state cohorts with final-eligibility resolution |
+| [`@llblab/pi-telegram`](https://github.com/llblab/pi-telegram) | `0.45.6` | Telegram companion, queues, files, voice, controls, and Generative Apps guidance |
 | [`@llblab/skills`](https://github.com/llblab/skills) | `1.15.0` | Portable workflows for engineering, review, design, context maintenance, and other focused tasks |
 
 Versions are exact by design. An upstream release does not change an installed kit until this repository explicitly advances the dependency and publishes a new kit version. Runtime defects and package-specific feature requests belong in the linked repository; package selection and kit installation issues belong here.

package/node_modules/@llblab/pi-state-flow/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 > Each release keeps at most 8 outcome records of at most 512 characters.
 
+## 0.9.6: Monospaced state value in the submenu
+
+- `Interop`: The submenu help line now consists solely of the operator-specified sentence "Records the latest accepted state after every turn, so a new session resumes from the last committed point."; the trailing "Start it to keep memory live on this branch, stop it to pause." sentence was removed.
+- `Interop`: The submenu state line renders the live value in monospace — `off` or `#N` — while the section button keeps the same plain-text label.
+
 ## 0.9.5: Shorter submenu help line
 
 - `Interop`: The submenu help line now opens directly with "Records the latest accepted state after every turn…"; the "Durable memory for this conversation: State Flow" prefix was removed at the operator's request.

package/node_modules/@llblab/pi-state-flow/README.md

@@ -66,7 +66,7 @@ Stopping changes the current session/branch configuration, preserves semantic ch
 
 The compact status is an accent `state-flow` and dim `#<step>`. Detailed status distinguishes runtime config/meta from semantic materialization, reports scope keys, the selected temporal head and runtime revision, available hot offsets, per-scope retained patch tails, artifact counts, stale Markdown reasons, and pending publication. Retained tails may include inherited pre-origin records, so their counts are not active history depth. It labels global/CWD/session/effective state without dumping source bodies. Failed inspection means unavailable evidence, never a falsely clean count.
 
-When the optional `pi-telegram` extension is installed, State Flow appears exactly once in Telegram: the inline main menu places a `🌀 State Flow: #N` or `🌀 State Flow: off` section button directly before Settings, and that button's label carries the live status. The button opens a compact submenu whose header repeats the same state line, followed by a short explanation of what State Flow is; the only action is `Start` (or `Stop` while enabled), with the transport-owned `⬆️ Main menu` row above it. Starting while a run is active waits for that run to settle; stopping applies immediately. Registration fails open when the transport is absent, retries when the section registry becomes ready, and disposes on session shutdown; the `/state-flow-*` commands remain the authority and nothing changes for hosts without `pi-telegram`.
+When the optional `pi-telegram` extension is installed, State Flow appears exactly once in Telegram: the inline main menu places a `🌀 State Flow: #N` or `🌀 State Flow: off` section button directly before Settings, and that button's label carries the live status. The button opens a compact submenu whose header repeats the same state line with the live value in monospace, followed by a short explanation of what State Flow is; the only action is `Start` (or `Stop` while enabled), with the transport-owned `⬆️ Main menu` row above it. Starting while a run is active waits for that run to settle; stopping applies immediately. Registration fails open when the transport is absent, retries when the section registry becomes ready, and disposes on session shutdown; the `/state-flow-*` commands remain the authority and nothing changes for hosts without `pi-telegram`.
 
 ## State, scope, and time
 

package/node_modules/@llblab/pi-state-flow/lib/telegram.ts

@@ -75,12 +75,22 @@ export interface StateFlowTelegramAdapter {
 
 /** Main-menu section label doubles as the live status value: the spiral identity is constant, the value is not. */
 export function formatStateFlowSectionLabel(snapshot: StateFlowTelegramSnapshot): string {
-	return snapshot.enabled ? `🌀 State Flow: #${snapshot.step}` : "🌀 State Flow: off";
+	return `🌀 State Flow: ${stateFlowLabelValue(snapshot)}`;
+}
+
+/** Shared live value: plain in the button label, monospaced in the submenu state line. */
+function stateFlowLabelValue(snapshot: StateFlowTelegramSnapshot): string {
+	return snapshot.enabled ? `#${snapshot.step}` : "off";
+}
+
+/** Submenu state line: the same identity as the button label, with the live value in monospace. */
+function formatStateFlowSectionHeader(snapshot: StateFlowTelegramSnapshot): string {
+	return `<b>🌀 State Flow: <code>${stateFlowLabelValue(snapshot)}</code></b>`;
 }
 
 /** Short help under the state line: what State Flow is and why its action button exists. */
 const STATE_FLOW_SECTION_HELP =
-	"Records the latest accepted state after every turn, so a new session resumes from the last committed point. Start it to keep memory live on this branch, stop it to pause.";
+	"Records the latest accepted state after every turn, so a new session resumes from the last committed point.";
 
 /** The submenu header repeats the button's state line; the single action matches the current state. */
 export function buildStateFlowSectionView(
@@ -91,7 +101,7 @@ export function buildStateFlowSectionView(
 		? { text: "⏹ Stop", callback_data: callbackData("stop") }
 		: { text: "▶️ Start", callback_data: callbackData("start") };
 	return {
-		text: [`<b>${formatStateFlowSectionLabel(snapshot)}</b>`, "", STATE_FLOW_SECTION_HELP].join("\n"),
+		text: [formatStateFlowSectionHeader(snapshot), "", STATE_FLOW_SECTION_HELP].join("\n"),
 		parseMode: "html",
 		replyMarkup: { inline_keyboard: [[action]] },
 	};

package/node_modules/@llblab/pi-state-flow/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-state-flow",
-  "version": "0.9.5",
+  "version": "0.9.6",
   "private": false,
   "description": "Incremental scoped state/context compiler for Pi, inspired by SKILL.state",
   "keywords": [

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

@@ -4,6 +4,14 @@
 
 ## Unreleased
 
+## 0.45.6: Guest Placeholder And Delivery Hotfix
+
+- `Guest Placeholder`: The guest ACK answers with the first bold globe frame (`🌎 Working on it.`) and rotates `🌍`/`🌏` once per second with the dots growing every two seconds. Rotation now completes whole 6-frame cycles and stops only after the 20 s minimum, so a pending answer holds the cycle's final frame (`🌏 Working on it...`) instead of cutting mid-step; a 26 s safety bound stays clear of the ~28 s Telegram flood-control wall, and error backoff and pre-replacement cancellation are unchanged.
+- `Guest Answer Delivery`: The guest replacement now falls back to the run's latest completed assistant text when Pi's final assistant message is empty, so an answer preserved by a companion extension's fallback turn (for example State Flow's suppressed final:true patch turn) is still edited into the guest message instead of being skipped as "no editable text".
+- `Rate-Limit Visibility`: A `429` retry wait now records an `api` runtime event with the method, wait duration, attempt, and server `retry_after`, so a silent flood-control pause before the final guest replacement is visible in the runtime log instead of appearing only as a frozen frame.
+- `Thread Display Hint`: The Thread display settings card no longer carries the manual `/name Name` override hint; the current-value line, the three mode descriptions, and the live chooser are unchanged.
+- `Queue Empty Headings`: The default empty-queue line and every rotating refresh title drop the trailing period, so the fully bold queue headings read as headings; wording, emoji, rotation order, callbacks, and refresh behavior are unchanged.
+
 ## 0.45.5: Queue Refresh Icon Hotfix
 
 - `Queue Refresh Icon`: The queue menu's Refresh row now uses `🔄`, the canonical refresh glyph, reserving `🌀` for the State Flow Telegram identity. The button label is the only change; queue refresh behavior, callbacks, and the rotating empty-queue notices are unchanged.

package/node_modules/@llblab/pi-telegram/docs/ui-style.md

@@ -104,7 +104,7 @@ The menu may clear internal Skip but cannot remove a reaction created by the use
 
 ### Decorative Or Local-Example Emoji
 
-Some emoji are intentionally local examples or decorative variants, not global semantics. Empty-queue rotating messages (`🫙`, `🍃`, `🕳`, `🦗`, `🌙`, `🧘`, `🪐`, `🧺`, `🔭`, `🫧`, `🛸`) are copy flavor only and must not become controls. Example extension icons such as `🧪`, `🔧`, and `🗂` are documentation fixtures for companion extensions, not built-in pi-telegram meanings.
+Some emoji are intentionally local examples or decorative variants, not global semantics. Empty-queue rotating messages (`🫙`, `🍃`, `🕳`, `🦗`, `🌙`, `🧘`, `🪐`, `🧺`, `🔭`, `🫧`, `🛸`) are copy flavor only and must not become controls. The Guest Mode placeholder frames (`🌎`, `🌍`, `🌏` stepping every second with dots growing once every two seconds) are the same kind of decorative copy: they complete whole 6-frame cycles over at least a ~20 s rotation while a guest answer is pending and then hold the cycle's final frame (a 26 s safety bound caps slow streams), never become controls, and must not carry another meaning. Example extension icons such as `🧪`, `🔧`, and `🗂` are documentation fixtures for companion extensions, not built-in pi-telegram meanings.
 
 Thread UI rule: when a message heading, chooser, or status line is specifically about Telegram/Pi threads or target thread selection, start the heading with `🧵`. Button labels for concrete thread targets should stay clean (`threadName` or slot fallback) and should not add `🧵` to every target button unless the row would otherwise be ambiguous.
 
@@ -224,7 +224,7 @@ Message cards and standalone informational notices sent by the bot should start
 Rules:
 
 - Start with a bold heading or, for dialogs, a bold question.
-- Format standalone notices as one fully bold line: relevant emoji, one space, concise sentence, and terminal period. Menu or chooser headings use the same fully bold form but end in a colon when controls or detail follow.
+- Format standalone notices as one fully bold line: relevant emoji, one space, concise sentence, and terminal period. Menu or chooser headings use the same fully bold form but end in a colon when controls or detail follow. Empty-queue headings are the deliberate exception: fully bold, with no trailing period or colon.
 - Keep the emoji and complete sentence or heading inside the single bold span; do not bold only a fragment. A material name or phrase may receive nested italic emphasis without breaking the outer bold hierarchy—for example `<b>📡 Instance <i>Cedar</i> connected.</b>`.
 - Apply the same hierarchy to success, progress, empty, busy, unavailable, cancellation, and failure notices.
 - Callback alerts remain plain text because Telegram does not support rich text there, but still keep the relevant emoji and concise sentence.

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

@@ -823,6 +823,12 @@ interface TelegramLifecycleBindingDeps {
     Pi.AgentEndEvent["messages"][number],
     Keyboard.TelegramInlineKeyboardMarkup
   >["editGuestReply"];
+  stopGuestPlaceholder?: Queue.TelegramAgentEndHookRuntimeDeps<
+    Queue.PendingTelegramTurn,
+    Pi.ExtensionContext,
+    Pi.AgentEndEvent["messages"][number],
+    Keyboard.TelegramInlineKeyboardMarkup
+  >["stopGuestPlaceholder"];
   preparePreviewDelivery?: Queue.TelegramAgentEndRuntimeDeps<Queue.PendingTelegramTurn>["preparePreviewDelivery"];
   finalizeMarkdownPreview: Queue.TelegramAgentEndHookRuntimeDeps<
     Queue.PendingTelegramTurn,
@@ -876,6 +882,7 @@ export function registerTelegramLifecycleRuntimeHooks({
   deleteMessage,
   sendGuestReply,
   editGuestReply,
+  stopGuestPlaceholder,
   preparePreviewDelivery,
   finalizeMarkdownPreview,
   proactivePushTargetGetter,
@@ -1056,7 +1063,7 @@ export function registerTelegramLifecycleRuntimeHooks({
     updateStatus,
     getActiveTurn: activeTurnRuntime.get,
     loadConfig: configStore.load,
-    extractAssistant: Replies.extractLatestAssistantMessageText,
+    extractAssistant: Replies.extractRunAssistantMessage,
     getFoldQueuedPromptsIntoHistory:
       lifecycle.shouldFoldQueuedPromptsIntoHistory,
     resetRuntimeState: agentEndResetter,
@@ -1090,6 +1097,7 @@ export function registerTelegramLifecycleRuntimeHooks({
     answerGuestQuery,
     sendGuestReply,
     editGuestReply,
+    stopGuestPlaceholder,
     sendGuestAttachment,
     sendGuestVoiceReply,
     planOutboundReply: outboundReplyPlanner,

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

@@ -1429,7 +1429,7 @@ export async function handleTelegramNextCommand(deps: {
   deps.clearPendingModelSwitch();
   if (!deps.hasQueuedItems()) {
     await deps.sendTextReply(
-      formatTelegramInformationHeading("⌛", "Queue is empty."),
+      formatTelegramInformationHeading("⌛", "Queue is empty"),
       { parseMode: "HTML" },
     );
     return;

package/node_modules/@llblab/pi-telegram/lib/extension.ts

@@ -588,6 +588,12 @@ export default function (pi: Pi.ExtensionAPI) {
   const editGuestReply = Replies.createGuestMarkdownReplyEditor({
     editGuestInlineMessage: telegramApiRuntime.editGuestInlineMessage,
   });
+  // Rotate the guest placeholder frames until the final replacement stops them.
+  const guestPlaceholderRuntime =
+    Replies.createTelegramGuestPlaceholderRuntime({
+      editGuestInlineMessage: telegramApiRuntime.editGuestInlineMessage,
+      recordRuntimeEvent,
+    });
 
   const promptDispatchRuntime = Runtime.createTelegramPromptDispatchRuntime({
     lifecycle,
@@ -978,6 +984,7 @@ export default function (pi: Pi.ExtensionAPI) {
     deleteMessage: deleteTelegramMessage,
     answerGuestQuery,
     answerGuestQueryForInlineMessage,
+    startGuestPlaceholder: guestPlaceholderRuntime.start,
     sendTextReply,
     setMyCommands,
     validateThreadName(threadName) {
@@ -1508,6 +1515,7 @@ export default function (pi: Pi.ExtensionAPI) {
         },
         capabilityMonitor: telegramThreadCapabilityMonitor,
         queueWatchdog: queueDispatchWatchdogRuntime,
+        guestPlaceholder: { stopAll: guestPlaceholderRuntime.stopAll },
       },
     });
   const sessionLifecycleRuntime =
@@ -1828,6 +1836,7 @@ export default function (pi: Pi.ExtensionAPI) {
     deleteMessage: deleteTelegramMessage,
     sendGuestReply,
     editGuestReply,
+    stopGuestPlaceholder: guestPlaceholderRuntime.stop,
     finalizeMarkdownPreview,
     preparePreviewDelivery,
     proactivePushTargetGetter,

package/node_modules/@llblab/pi-telegram/lib/lifecycle.ts

@@ -265,6 +265,7 @@ export interface TelegramBridgeSessionServiceRuntime {
   inboundWorker: { onSessionShutdown(): Promise<void> };
   capabilityMonitor: { start(ctx: ExtensionContext): void; stop(): void };
   queueWatchdog: { start(ctx: ExtensionContext): void; stop(): void };
+  guestPlaceholder?: { stopAll(): void };
 }
 
 export interface TelegramBridgeSessionLifecycleAssemblyDeps<
@@ -320,6 +321,7 @@ export interface TelegramBridgeSessionLifecyclePorts<
     inboundWorker: TelegramBridgeSessionServiceRuntime["inboundWorker"];
     capabilityMonitor: TelegramBridgeSessionServiceRuntime["capabilityMonitor"];
     queueWatchdog: TelegramBridgeSessionServiceRuntime["queueWatchdog"];
+    guestPlaceholder?: TelegramBridgeSessionServiceRuntime["guestPlaceholder"];
   };
 }
 
@@ -347,6 +349,7 @@ export function createTelegramBridgeSessionLifecycleDeps<
       inboundWorker: ports.services.inboundWorker,
       capabilityMonitor: ports.services.capabilityMonitor,
       queueWatchdog: ports.services.queueWatchdog,
+      guestPlaceholder: ports.services.guestPlaceholder,
     },
   };
 }
@@ -383,6 +386,7 @@ export function createTelegramBridgeSessionLifecycleAssembly<
     },
     async onSessionShutdown(event, ctx) {
       if (!isSessionActive(ctx)) return;
+      deps.services.guestPlaceholder?.stopAll();
       await deps.services.delivery.onSessionShutdown();
       if (!isSessionActive(ctx)) return;
       deps.services.queueWatchdog.stop();

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

@@ -14,18 +14,18 @@ import * as Queue from "./queue.ts";
 const QUEUE_ITEM_PROMPT_HTML_LIMIT = 3600;
 const QUEUE_ITEM_PROMPT_TRUNCATION_SUFFIX = "\n… [truncated]";
 const EMPTY_QUEUE_REFRESH_TITLES = [
-  "<b>⌛ Queue is still empty.</b>",
-  "<b>🫙 Still nothing in queue.</b>",
-  "<b>🍃 Queue remains empty.</b>",
-  "<b>🕳 Nothing queued yet.</b>",
-  "<b>🦗 Queue crickets continue.</b>",
-  "<b>🌙 Queue is peacefully idle.</b>",
-  "<b>🧘 Nothing waiting. Very zen.</b>",
-  "<b>🪐 Queue orbit is clear.</b>",
-  "<b>🧺 Basket is empty.</b>",
-  "<b>🔭 No prompts on the horizon.</b>",
-  "<b>🫧 Queue bubbles: none.</b>",
-  "<b>🛸 No queued signals detected.</b>",
+  "<b>⌛ Queue is still empty</b>",
+  "<b>🫙 Still nothing in queue</b>",
+  "<b>🍃 Queue remains empty</b>",
+  "<b>🕳 Nothing queued yet</b>",
+  "<b>🦗 Queue crickets continue</b>",
+  "<b>🌙 Queue is peacefully idle</b>",
+  "<b>🧘 Nothing waiting. Very zen</b>",
+  "<b>🪐 Queue orbit is clear</b>",
+  "<b>🧺 Basket is empty</b>",
+  "<b>🔭 No prompts on the horizon</b>",
+  "<b>🫧 Queue bubbles: none</b>",
+  "<b>🛸 No queued signals detected</b>",
 ] as const;
 type TelegramQueueMenuReplyMarkup = TelegramInlineKeyboardMarkup;
 interface TelegramQueueMenuItem {
@@ -340,7 +340,7 @@ function getTelegramQueueMenuListText(
   emptyRefreshIndex?: number,
 ): string {
   if (items.length > 0) return "<b>⏳ Queue:</b>";
-  if (emptyRefreshIndex === undefined) return "<b>⌛ Queue is empty.</b>";
+  if (emptyRefreshIndex === undefined) return "<b>⌛ Queue is empty</b>";
   return EMPTY_QUEUE_REFRESH_TITLES[
     emptyRefreshIndex % EMPTY_QUEUE_REFRESH_TITLES.length
   ];

package/node_modules/@llblab/pi-telegram/lib/menu-settings.ts

@@ -184,7 +184,6 @@ export function buildThreadDisplaySettingsText(mode: TelegramThreadDisplayMode):
     "<code>-</code> <code>letters</code> (default): show the unique slot, such as <b><i>A</i></b> or <b><i>B</i></b>.",
     "<code>-</code> <code>names</code>: show the generated dictionary name for the slot, such as <b><i>Anchor</i></b> or <b><i>Briar</i></b>.",
     "<code>-</code> <code>directories</code>: show the directory, such as <b><i>extensions</i></b>; shared Workspaces keep slot suffixes, such as <b><i>extensions_a</i></b> and <b><i>extensions_c</i></b>.",
-    "A manual <code>/name Name</code> overrides this Thread display name until reset.",
   ].join("\n");
 }
 

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

@@ -1554,6 +1554,8 @@ export interface TelegramAgentEndRuntimeDeps<
   sendGuestReply?: (guestQueryId: string, markdown: string) => Promise<void>;
   /** Replaces the early guest ACK with the final text. */
   editGuestReply?: (inlineMessageId: string, markdown: string) => Promise<void>;
+  /** Cancels the animated guest placeholder before the final edit. */
+  stopGuestPlaceholder?: (inlineMessageId: string) => Promise<void>;
   sendGuestAttachment?: (
     turn: TTurn,
     attachment: QueuedAttachment,
@@ -1633,6 +1635,7 @@ export interface TelegramAgentEndHookRuntimeDeps<
   answerGuestQuery?: TelegramAgentEndRuntimeDeps<TTurn>["answerGuestQuery"];
   sendGuestReply?: TelegramAgentEndRuntimeDeps<TTurn>["sendGuestReply"];
   editGuestReply?: TelegramAgentEndRuntimeDeps<TTurn>["editGuestReply"];
+  stopGuestPlaceholder?: TelegramAgentEndRuntimeDeps<TTurn>["stopGuestPlaceholder"];
   sendGuestAttachment?: TelegramAgentEndRuntimeDeps<TTurn>["sendGuestAttachment"];
   sendGuestVoiceReply?: TelegramAgentEndRuntimeDeps<TTurn>["sendGuestVoiceReply"];
   planOutboundReply?: TelegramAgentEndRuntimeDeps<
@@ -1774,6 +1777,7 @@ export function createTelegramAgentEndHook<
         answerGuestQuery: deps.answerGuestQuery,
         sendGuestReply: deps.sendGuestReply,
         editGuestReply: deps.editGuestReply,
+        stopGuestPlaceholder: deps.stopGuestPlaceholder,
         sendGuestAttachment: deps.sendGuestAttachment,
         sendGuestVoiceReply: deps.sendGuestVoiceReply,
         planOutboundReply: deps.planOutboundReply,
@@ -1866,6 +1870,16 @@ export async function handleTelegramAgentEndRuntime<
     return;
   }
   if (turn.guestQueryId) {
+    if (turn.guestInlineMessageId && deps.stopGuestPlaceholder) {
+      try {
+        await deps.stopGuestPlaceholder(turn.guestInlineMessageId);
+      } catch (error) {
+        deps.recordRuntimeEvent?.("delivery", error, {
+          phase: "guest-placeholder-stop",
+          guestQueryId: turn.guestQueryId,
+        });
+      }
+    }
     if (turn.guestInlineMessageId && deps.editGuestReply) {
       const experimentText = assistant.errorMessage
         ? "Telegram bridge: Pi failed while processing the request."
@@ -1875,7 +1889,7 @@ export async function handleTelegramAgentEndRuntime<
           await deps.editGuestReply(turn.guestInlineMessageId, experimentText);
           deps.recordRuntimeEvent?.(
             "guest",
-            new Error("Guest ACK experiment edited the guest answer"),
+            new Error("Guest ACK edited the guest answer"),
             { phase: "guest-ack-edited", guestQueryId: turn.guestQueryId },
           );
         } catch (error) {
@@ -1887,7 +1901,7 @@ export async function handleTelegramAgentEndRuntime<
       } else {
         deps.recordRuntimeEvent?.(
           "delivery",
-          new Error("Guest ACK experiment turn produced no editable text"),
+          new Error("Guest ACK turn produced no editable text"),
           { phase: "guest-ack-edit-empty", guestQueryId: turn.guestQueryId },
         );
       }

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

@@ -1,7 +1,7 @@
 /**
  * Telegram reply delivery helpers
  * Zones: telegram outbound, native rich markdown, UI/compat rendering transport
- * Owns native assistant replies, rendered UI delivery, reply transport wiring, and plain text replies
+ * Owns native assistant replies, rendered UI delivery, guest placeholder rotation, reply transport wiring, and plain text replies
  */
 
 import { assertTelegramInlineKeyboardCallbackData } from "./keyboard.ts";
@@ -177,6 +177,47 @@ export function extractLatestAssistantMessageText(
   return {};
 }
 
+/**
+ * Extract the run's answer without trusting an empty final assistant message.
+ * A low-level run may end with a completed assistant message whose content was
+ * suppressed (a companion extension preserving an earlier draft, for example
+ * State Flow's fallback final:true patch turn). In that case the run's answer
+ * is the latest earlier completed assistant message that carries text;
+ * tool-use prefaces, errors, and aborts stay excluded.
+ */
+export function extractRunAssistantMessage(
+  messages: readonly unknown[],
+): {
+  text?: string;
+  stopReason?: string;
+  errorMessage?: string;
+} {
+  const latest = extractLatestAssistantMessageText(messages);
+  if (latest.text || latest.stopReason !== "stop") return latest;
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const message = messages[i];
+    if (!message || !isAssistantAgentMessage(message)) continue;
+    const rawStopReason = getAgentMessageField(message, "stopReason");
+    if (
+      rawStopReason === "toolUse" ||
+      rawStopReason === "error" ||
+      rawStopReason === "aborted"
+    ) {
+      continue;
+    }
+    const text = getAgentMessageText(message);
+    if (!text) continue;
+    const rawErrorMessage = getAgentMessageField(message, "errorMessage");
+    return {
+      text,
+      stopReason: typeof rawStopReason === "string" ? rawStopReason : undefined,
+      errorMessage:
+        typeof rawErrorMessage === "string" ? rawErrorMessage : undefined,
+    };
+  }
+  return latest;
+}
+
 export interface TelegramReplyOwnershipRecorder {
   record: (input: {
     chatId: number;
@@ -900,9 +941,9 @@ export function createGuestMarkdownReplySender(deps: {
 }
 
 /**
- * Guest reply editor: replaces an early Guest Mode answer (the temporary ACK
- * experiment) with native Rich Markdown content addressed by
- * `inline_message_id` instead of a chat/message pair.
+ * Guest reply editor: replaces the early Guest Mode placeholder ACK with
+ * native Rich Markdown content addressed by `inline_message_id` instead of a
+ * chat/message pair.
  */
 export function createGuestMarkdownReplyEditor(deps: {
   editGuestInlineMessage: (
@@ -917,3 +958,219 @@ export function createGuestMarkdownReplyEditor(deps: {
     });
   };
 }
+
+/**
+ * Guest Mode placeholder rotation: the early ACK is the first placeholder
+ * frame and the runtime steps the remaining frames once per interval, moving
+ * the globe every second while the trailing dots grow once every two seconds.
+ *
+ * Rotation completes whole six-frame cycles and only stops once at least
+ * `TELEGRAM_GUEST_PLACEHOLDER_MIN_MS` has elapsed, so a pending answer holds
+ * the finished cycle's last frame (`🌏 Working on it...`) instead of whatever
+ * step a hard time cap happens to cut. The `TELEGRAM_GUEST_PLACEHOLDER_MAX_MS`
+ * safety bound keeps the edit stream clear of the first flood-control
+ * rejections measured in live guest runs (+26.5 s at ~53 edits, +27.8 s at
+ * ~28 edits): rotation caps at 23 edits and never starts a frame after 26 s.
+ */
+
+export const TELEGRAM_GUEST_PLACEHOLDER_FRAME_MS = 1_000;
+
+export const TELEGRAM_GUEST_PLACEHOLDER_MIN_MS = 20_000;
+
+export const TELEGRAM_GUEST_PLACEHOLDER_MAX_MS = 26_000;
+
+export const TELEGRAM_GUEST_PLACEHOLDER_FRAMES = [
+  "<b>🌎 Working on it.</b>",
+  "<b>🌍 Working on it.</b>",
+  "<b>🌏 Working on it..</b>",
+  "<b>🌎 Working on it..</b>",
+  "<b>🌍 Working on it...</b>",
+  "<b>🌏 Working on it...</b>",
+] as const;
+
+export function buildTelegramGuestPlaceholderFrame(step: number): string {
+  const frames: readonly string[] = TELEGRAM_GUEST_PLACEHOLDER_FRAMES;
+  const index = ((step % frames.length) + frames.length) % frames.length;
+  return frames[index]!;
+}
+
+export interface TelegramGuestPlaceholderRuntimeDeps {
+  editGuestInlineMessage: (
+    inlineMessageId: string,
+    content: { text: string; parseMode: "HTML" },
+  ) => Promise<void>;
+  recordRuntimeEvent?: (
+    category: string,
+    error: unknown,
+    details?: Record<string, unknown>,
+  ) => void;
+  intervalMs?: number;
+  minMs?: number;
+  maxMs?: number;
+  now?: () => number;
+  setTimer?: (
+    callback: () => void,
+    ms: number,
+  ) => ReturnType<typeof setTimeout>;
+  clearTimer?: (timer: ReturnType<typeof setTimeout>) => void;
+}
+
+export interface TelegramGuestPlaceholderRuntime {
+  /** Starts the frame loop on an answered guest inline message. */
+  start: (inlineMessageId: string) => void;
+  /** Cancels the loop and waits for any in-flight frame edit before returning. */
+  stop: (inlineMessageId: string) => Promise<void>;
+  /** Cancels every loop without waiting for in-flight edits (session shutdown). */
+  stopAll: () => void;
+}
+
+interface TelegramGuestPlaceholderSession {
+  step: number;
+  stopped: boolean;
+  startedAtMs: number;
+  finished: boolean;
+  timer?: ReturnType<typeof setTimeout>;
+  inflight?: Promise<void>;
+}
+
+function getTelegramGuestPlaceholderRetryDelayMs(
+  error: unknown,
+  fallbackMs: number,
+): number {
+  const retryAfterSeconds = (
+    error as { retryAfterSeconds?: unknown } | undefined
+  )?.retryAfterSeconds;
+  return typeof retryAfterSeconds === "number" && retryAfterSeconds > 0
+    ? Math.max(fallbackMs, retryAfterSeconds * 1_000)
+    : fallbackMs;
+}
+
+export function createTelegramGuestPlaceholderRuntime(
+  deps: TelegramGuestPlaceholderRuntimeDeps,
+): TelegramGuestPlaceholderRuntime {
+  const intervalMs = deps.intervalMs ?? TELEGRAM_GUEST_PLACEHOLDER_FRAME_MS;
+  const minMs = deps.minMs ?? TELEGRAM_GUEST_PLACEHOLDER_MIN_MS;
+  const maxMs = deps.maxMs ?? TELEGRAM_GUEST_PLACEHOLDER_MAX_MS;
+  const now = deps.now ?? Date.now;
+  const setTimer =
+    deps.setTimer ??
+    ((callback: () => void, ms: number): ReturnType<typeof setTimeout> =>
+      setTimeout(callback, ms));
+  const clearTimer =
+    deps.clearTimer ??
+    ((timer: ReturnType<typeof setTimeout>): void => clearTimeout(timer));
+  const sessions = new Map<string, TelegramGuestPlaceholderSession>();
+
+  const finishRotation = (
+    session: TelegramGuestPlaceholderSession,
+    elapsedMs: number,
+  ): void => {
+    if (session.finished) return;
+    session.finished = true;
+    deps.recordRuntimeEvent?.(
+      "guest",
+      "Guest placeholder rotation reached its bound",
+      {
+        phase: "guest-placeholder-capped",
+        minMs,
+        maxMs,
+        elapsedMs,
+        step: session.step,
+      },
+    );
+  };
+
+  const scheduleFrame = (
+    inlineMessageId: string,
+    session: TelegramGuestPlaceholderSession,
+    delayMs: number,
+  ): void => {
+    if (session.stopped) return;
+    const elapsedMs = now() - session.startedAtMs;
+    const frameCount = TELEGRAM_GUEST_PLACEHOLDER_FRAMES.length;
+    const cycleComplete =
+      session.step > 0 && session.step % frameCount === frameCount - 1;
+    if (cycleComplete && elapsedMs >= minMs) {
+      finishRotation(session, elapsedMs);
+      return;
+    }
+    if (elapsedMs + delayMs > maxMs) {
+      finishRotation(session, elapsedMs);
+      return;
+    }
+    const timer = setTimer(() => {
+      session.timer = undefined;
+      runFrame(inlineMessageId, session);
+    }, delayMs);
+    timer.unref?.();
+    session.timer = timer;
+  };
+
+  const runFrame = (
+    inlineMessageId: string,
+    session: TelegramGuestPlaceholderSession,
+  ): void => {
+    if (session.stopped) return;
+    session.step += 1;
+    let nextDelayMs = intervalMs;
+    session.inflight = (async () => {
+      try {
+        await deps.editGuestInlineMessage(inlineMessageId, {
+          text: buildTelegramGuestPlaceholderFrame(session.step),
+          parseMode: "HTML",
+        });
+      } catch (error) {
+        nextDelayMs = getTelegramGuestPlaceholderRetryDelayMs(error, intervalMs);
+        deps.recordRuntimeEvent?.("guest", error, {
+          phase: "guest-placeholder-edit",
+          retryAfterMs: nextDelayMs,
+        });
+      } finally {
+        session.inflight = undefined;
+        scheduleFrame(inlineMessageId, session, nextDelayMs);
+      }
+    })();
+  };
+
+  const stop = async (inlineMessageId: string): Promise<void> => {
+    const session = sessions.get(inlineMessageId);
+    if (!session) return;
+    sessions.delete(inlineMessageId);
+    session.stopped = true;
+    if (session.timer !== undefined) {
+      clearTimer(session.timer);
+      session.timer = undefined;
+    }
+    try {
+      await session.inflight;
+    } catch {
+      // Frame failures are reported as runtime events; stopping stays fail-open.
+    }
+  };
+
+  return {
+    start(inlineMessageId) {
+      const existing = sessions.get(inlineMessageId);
+      if (existing) {
+        existing.stopped = true;
+        if (existing.timer !== undefined) clearTimer(existing.timer);
+      }
+      const session: TelegramGuestPlaceholderSession = {
+        step: 0,
+        stopped: false,
+        startedAtMs: now(),
+        finished: false,
+      };
+      sessions.set(inlineMessageId, session);
+      scheduleFrame(inlineMessageId, session, intervalMs);
+    },
+    stop,
+    stopAll() {
+      for (const session of sessions.values()) {
+        session.stopped = true;
+        if (session.timer !== undefined) clearTimer(session.timer);
+      }
+      sessions.clear();
+    },
+  };
+}

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

@@ -16,6 +16,7 @@ import * as Model from "./model.ts";
 import * as OutboundHandlers from "./outbound.ts";
 import * as PromptTemplates from "./prompt-templates.ts";
 import * as Queue from "./queue.ts";
+import * as Replies from "./replies.ts";
 import type { TelegramBridgeRuntime } from "./runtime.ts";
 import type { TelegramSectionRegistry } from "./sections.ts";
 import * as TextGroups from "./text-groups.ts";
@@ -665,6 +666,8 @@ export interface TelegramInboundRouteRuntimeDeps<
     text: string,
     options?: { parseMode?: "HTML" },
   ) => Promise<string | undefined>;
+  /** Starts the animated placeholder on an answered guest inline message. */
+  startGuestPlaceholder?: (inlineMessageId: string) => void;
   sendTextReply: (
     chatId: number,
     replyToMessageId: number,
@@ -2662,8 +2665,10 @@ export function createTelegramInboundRouteRuntime<
     assertExecutionCurrent();
   };
   // Answer the guest query immediately so the agent-end edit can replace the
-  // early ACK once the turn settles. See BACKLOG.md for live acceptance.
-  const TELEGRAM_GUEST_ACK_HTML = "<b>⚙️ Received. Working on it…</b>";
+  // early ACK once the turn settles. The ACK is the first placeholder frame and
+  // the loop rotates through the remaining frames until the replacement.
+  const TELEGRAM_GUEST_ACK_HTML =
+    Replies.buildTelegramGuestPlaceholderFrame(0);
   const handleAuthorizedTelegramGuestMessage = async (
     guestMessage: Updates.TelegramGuestMessage & { from: TelegramUser },
     ctx: TContext,
@@ -2679,9 +2684,12 @@ export function createTelegramInboundRouteRuntime<
           TELEGRAM_GUEST_ACK_HTML,
           { parseMode: "HTML" },
         );
+        if (guestInlineMessageId) {
+          deps.startGuestPlaceholder?.(guestInlineMessageId);
+        }
         deps.recordRuntimeEvent?.(
           "guest",
-          new Error("Guest ACK experiment answered the guest query"),
+          new Error("Guest ACK answered the guest query"),
           {
             phase: "guest-ack-sent",
             guestQueryId: guestMessage.guest_query_id,

package/node_modules/@llblab/pi-telegram/lib/telegram-api.ts

@@ -374,6 +374,13 @@ interface TelegramApiResponse<T> {
   parameters?: { retry_after?: number };
 }
 
+export interface TelegramApiRetryWait {
+  method: string;
+  delayMs: number;
+  attempt: number;
+  retryAfterSeconds?: number;
+}
+
 export interface TelegramApiCallOptions {
   signal?: AbortSignal;
   maxAttempts?: number;
@@ -381,6 +388,8 @@ export interface TelegramApiCallOptions {
   retrySafety?: "safe" | "non-idempotent";
   retryBaseDelayMs?: number;
   sleep?: (ms: number) => Promise<void>;
+  /** Observability hook fired before a 429 retry wait, never for 5xx waits. */
+  onRetryWait?: (wait: TelegramApiRetryWait) => void;
 }
 
 interface TelegramGetFileResult {
@@ -434,6 +443,7 @@ export interface TelegramAnswerGuestQueryOptions {
 export interface TelegramEditGuestInlineMessageContent {
   text?: string;
   richMessage?: TelegramInputRichMessage;
+  parseMode?: "HTML";
 }
 
 export interface TelegramAnswerCallbackQueryOptions {
@@ -1380,7 +1390,25 @@ async function callTelegramWithRetry<TResponse>(
       isTelegramApiMethodRetrySafe(method));
   const maxAttempts = Math.max(1, options?.maxAttempts ?? 3);
   const retryBaseDelayMs = options?.retryBaseDelayMs ?? 500;
-  const waitBeforeRetry = async (ms: number): Promise<void> => {
+  const waitBeforeRetry = async (
+    error: unknown,
+    attempt: number,
+  ): Promise<void> => {
+    const ms = getTelegramRetryDelayMs(error, attempt, retryBaseDelayMs);
+    if (
+      !options?.signal?.aborted &&
+      error instanceof TelegramApiHttpError &&
+      error.status === 429
+    ) {
+      options?.onRetryWait?.({
+        method,
+        delayMs: ms,
+        attempt,
+        ...(error.retryAfterSeconds !== undefined
+          ? { retryAfterSeconds: error.retryAfterSeconds }
+          : {}),
+      });
+    }
     if (options?.sleep) await options.sleep(ms);
     else await sleepTelegramRetry(ms, options?.signal);
     throwIfTelegramApiCallAborted(options?.signal);
@@ -1406,9 +1434,7 @@ async function callTelegramWithRetry<TResponse>(
       if (!retrySafe) {
         if (error instanceof TelegramApiHttpError && error.status === 429) {
           if (attempt >= maxAttempts - 1) throw error;
-          await waitBeforeRetry(
-            getTelegramRetryDelayMs(error, attempt, retryBaseDelayMs),
-          );
+          await waitBeforeRetry(error, attempt);
           continue;
         }
         if (
@@ -1423,9 +1449,7 @@ async function callTelegramWithRetry<TResponse>(
         throw error;
       }
       if (attempt >= maxAttempts - 1 || !retryable) throw error;
-      await waitBeforeRetry(
-        getTelegramRetryDelayMs(error, attempt, retryBaseDelayMs),
-      );
+      await waitBeforeRetry(error, attempt);
     }
   }
 }
@@ -2095,6 +2119,7 @@ export function createTelegramBridgeApiRuntime(
         ...(content.richMessage
           ? { rich_message: content.richMessage }
           : { text: content.text }),
+        ...(content.parseMode ? { parse_mode: content.parseMode } : {}),
       });
     },
     prepareTempDir: () =>
@@ -2117,6 +2142,7 @@ export function createTelegramApiClient(
   options: TelegramAnswerCallbackQueryOptions & { now?: () => number } = {},
 ): TelegramApiClient {
   const now = options.now ?? Date.now;
+  const recordRuntimeEvent = options.recordRuntimeEvent;
   const draftRetryNotBeforeByTarget = new Map<string, number>();
   return {
     call: async <TResponse>(
@@ -2140,9 +2166,31 @@ export function createTelegramApiClient(
       }
       try {
         // A draft is a replaceable snapshot, not a body to replay after backoff.
-        return await callTelegram<TResponse>(
-          token, method, body, isDraft ? { ...options, maxAttempts: 1 } : options,
-        );
+        const retryWaitOptions: TelegramApiCallOptions = recordRuntimeEvent
+          ? {
+              onRetryWait: (wait) => {
+                recordRuntimeEvent(
+                  "api",
+                  new Error(
+                    `Telegram API rate limit: waiting ${wait.delayMs} ms before retrying ${wait.method}`,
+                  ),
+                  {
+                    phase: "retry-wait",
+                    method: wait.method,
+                    waitMs: wait.delayMs,
+                    attempt: wait.attempt,
+                    ...(wait.retryAfterSeconds !== undefined
+                      ? { retryAfterSeconds: wait.retryAfterSeconds }
+                      : {}),
+                  },
+                );
+              },
+            }
+          : {};
+        return await callTelegram<TResponse>(token, method, body, {
+          ...(isDraft ? { ...options, maxAttempts: 1 } : options),
+          ...retryWaitOptions,
+        });
       } catch (error) {
         if (draftKey && isRetryableTelegramApiError(error)) {
           draftRetryNotBeforeByTarget.set(draftKey, Math.max(

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-kit",
-  "version": "0.10.4",
+  "version": "0.10.6",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -44,8 +44,8 @@
     "@llblab/pi-clean-room": "0.1.1",
     "@llblab/pi-codex-usage": "0.9.4",
     "@llblab/pi-grow-loop": "0.8.1",
-    "@llblab/pi-state-flow": "0.9.5",
-    "@llblab/pi-telegram": "0.45.5",
+    "@llblab/pi-state-flow": "0.9.6",
+    "@llblab/pi-telegram": "0.45.6",
     "@llblab/skills": "1.15.0"
   },
   "bundledDependencies": [