@llblab/pi-telegram 0.35.2 → 0.36.1

package/lib/queue.ts

@@ -34,7 +34,17 @@ export type TelegramQueueLane = "control" | "priority" | "default";
 export type TelegramQueueReactionDisposition =
   | { kind: "default" }
   | { kind: "priority"; emoji: string }
-  | { kind: "suppressed"; emoji: string };
+  | { kind: "suppressed"; emoji: string }
+  | {
+      kind: "priority-suppressed";
+      priorityEmoji: string;
+      suppressionEmoji: string;
+    }
+  | {
+      kind: "reaction-transition";
+      priorityEmoji?: string | null;
+      suppressionEmoji?: string | null;
+    };
 
 export interface TelegramQueueAdmissionReceipt {
   queueKind: TelegramQueueItemKind;
@@ -899,7 +909,7 @@ export function applyTelegramQueuePromptReactionDisposition<
   items: TelegramQueueItem<TContext>[],
   messageId: number,
   disposition: TelegramQueueReactionDisposition,
-  priorityLaneOrder?: number,
+  destinationLaneOrder?: number,
   scope?: TelegramQueueMessageScope,
 ): { items: TelegramQueueItem<TContext>[]; changed: boolean } {
   let nextItems = items;
@@ -911,17 +921,38 @@ export function applyTelegramQueuePromptReactionDisposition<
     ) {
       continue;
     }
-    const queueLane: TelegramQueueLane =
-      disposition.kind === "priority" ? "priority" : "default";
-    const laneOrder =
-      disposition.kind === "priority" ? priorityLaneOrder : item.queueOrder;
+    const isPriority = disposition.kind === "reaction-transition"
+      ? disposition.priorityEmoji === undefined
+        ? item.queueLane === "priority"
+        : disposition.priorityEmoji !== null
+      : disposition.kind === "priority" ||
+        disposition.kind === "priority-suppressed";
+    const queueLane: TelegramQueueLane = isPriority ? "priority" : "default";
+    const laneOrder = item.queueLane === queueLane
+      ? item.laneOrder
+      : destinationLaneOrder;
     if (laneOrder === undefined) {
-      throw new Error("Telegram priority reaction order is unavailable.");
+      throw new Error("Telegram destination lane order is unavailable.");
     }
-    const priorityEmoji =
-      disposition.kind === "priority" ? disposition.emoji : undefined;
+    const priorityEmoji = disposition.kind === "reaction-transition"
+      ? disposition.priorityEmoji === undefined
+        ? item.priorityEmoji
+        : disposition.priorityEmoji ?? undefined
+      : disposition.kind === "priority"
+        ? disposition.emoji
+        : disposition.kind === "priority-suppressed"
+          ? disposition.priorityEmoji
+          : undefined;
     const reactionSuppressionEmoji =
-      disposition.kind === "suppressed" ? disposition.emoji : undefined;
+      disposition.kind === "reaction-transition"
+        ? disposition.suppressionEmoji === undefined
+          ? item.reactionSuppressionEmoji
+          : disposition.suppressionEmoji ?? undefined
+        : disposition.kind === "suppressed"
+          ? disposition.emoji
+          : disposition.kind === "priority-suppressed"
+            ? disposition.suppressionEmoji
+            : undefined;
     if (
       item.queueLane === queueLane &&
       item.laneOrder === laneOrder &&
@@ -1984,7 +2015,6 @@ export interface TelegramSessionShutdownState<TQueueItem> {
   queuedTelegramItems: TQueueItem[];
   nextQueuedTelegramItemOrder: number;
   nextQueuedTelegramControlOrder: number;
-  nextPriorityReactionOrder: number;
   currentTelegramModel: undefined;
   activeTelegramToolExecutions: number;
   pendingTelegramModelSwitch: undefined;
@@ -1996,7 +2026,6 @@ export interface TelegramSessionShutdownState<TQueueItem> {
 export interface TelegramSessionRuntimeCounterState {
   nextQueuedTelegramItemOrder?: number;
   nextQueuedTelegramControlOrder?: number;
-  nextPriorityReactionOrder?: number;
 }
 
 export interface TelegramSessionRuntimeFlagState {
@@ -2104,8 +2133,7 @@ export interface TelegramQueueMutationRuntimeDeps<
   TContext,
 > extends TelegramQueueStore<TContext>, TelegramRuntimeEventRecorderPort {
   ctx: TContext;
-  getNextPriorityReactionOrder?: () => number;
-  incrementNextPriorityReactionOrder?: () => void;
+  allocateLaneOrder?: () => number;
   onItemsDiscarded?: (
     items: readonly TelegramQueueItem<TContext>[],
     ctx: TContext,
@@ -2116,8 +2144,7 @@ export interface TelegramQueueMutationRuntimeDeps<
 export interface TelegramQueueMutationControllerDeps<
   TContext,
 > extends TelegramQueueStore<TContext>, TelegramRuntimeEventRecorderPort {
-  getNextPriorityReactionOrder?: () => number;
-  incrementNextPriorityReactionOrder?: () => void;
+  allocateLaneOrder?: () => number;
   onItemsDiscarded?: (
     items: readonly TelegramQueueItem<TContext>[],
     ctx: TContext,
@@ -2227,7 +2254,6 @@ export function buildTelegramSessionShutdownState<
     queuedTelegramItems: [],
     nextQueuedTelegramItemOrder: 0,
     nextQueuedTelegramControlOrder: 0,
-    nextPriorityReactionOrder: 0,
     currentTelegramModel: undefined,
     activeTelegramToolExecutions: 0,
     pendingTelegramModelSwitch: undefined,
@@ -2492,24 +2518,40 @@ export function applyTelegramQueuePromptReactionDispositionRuntime<TContext>(
   deps: TelegramQueueMutationRuntimeDeps<TContext>,
   scope?: TelegramQueueMessageScope,
 ): boolean {
-  const priorityLaneOrder =
-    disposition.kind === "priority"
-      ? deps.getNextPriorityReactionOrder?.()
-      : undefined;
-  if (disposition.kind === "priority" && priorityLaneOrder === undefined) {
-    return false;
-  }
+  const queuedItems = deps.getQueuedItems();
+  const changesLane = queuedItems.some((item) => {
+    if (
+      !isPendingTelegramTurn(item) ||
+      !isTelegramQueueItemInMessageScope(item, scope) ||
+      !item.sourceMessageIds.includes(messageId)
+    ) {
+      return false;
+    }
+    const queueLane: TelegramQueueLane =
+      disposition.kind === "reaction-transition"
+        ? disposition.priorityEmoji === undefined
+          ? item.queueLane
+          : disposition.priorityEmoji === null
+            ? "default"
+            : "priority"
+        : disposition.kind === "priority" ||
+            disposition.kind === "priority-suppressed"
+          ? "priority"
+          : "default";
+    return item.queueLane !== queueLane;
+  });
+  const destinationLaneOrder = changesLane
+    ? deps.allocateLaneOrder?.()
+    : undefined;
+  if (changesLane && destinationLaneOrder === undefined) return false;
   const { changed, items } = applyTelegramQueuePromptReactionDisposition(
-    deps.getQueuedItems(),
+    queuedItems,
     messageId,
     disposition,
-    priorityLaneOrder,
+    destinationLaneOrder,
     scope,
   );
   if (!changed) return false;
-  if (disposition.kind === "priority") {
-    deps.incrementNextPriorityReactionOrder?.();
-  }
   commitReorderedTelegramQueueItemsRuntime(items, deps);
   return true;
 }
@@ -2931,18 +2973,33 @@ export function createTelegramQueueDispatchController<TContext = unknown>(
           { phase: "transport-generation" },
         );
       }
-      const dispatchableItems: TelegramQueueItem<TContext>[] = [];
-      const suppressedActiveItems: TelegramQueueItem<TContext>[] = [];
-      for (const item of activeItems) {
-        if (
-          item.kind === "prompt" &&
-          item.reactionSuppressionEmoji !== undefined
-        ) {
-          suppressedActiveItems.push(item);
-        } else {
-          dispatchableItems.push(item);
+      const canDispatch = deps.canDispatch(ctx);
+      let nextActiveIndex = 0;
+      if (canDispatch) {
+        while (nextActiveIndex < activeItems.length) {
+          const candidate = activeItems[nextActiveIndex];
+          if (
+            !candidate ||
+            candidate.kind !== "prompt" ||
+            candidate.reactionSuppressionEmoji === undefined
+          ) {
+            break;
+          }
+          if (deps.hasPendingInboundQueueMutationForItem?.(candidate)) {
+            deps.updateStatus(ctx);
+            return;
+          }
+          if (
+            deps.isQueueItemAdmissionReady &&
+            !deps.isQueueItemAdmissionReady(candidate)
+          ) {
+            deps.updateStatus(ctx);
+            return;
+          }
+          nextActiveIndex += 1;
         }
       }
+      const dispatchableItems = activeItems.slice(nextActiveIndex);
       const nextItem = dispatchableItems[0];
       if (
         nextItem &&
@@ -2961,12 +3018,11 @@ export function createTelegramQueueDispatchController<TContext = unknown>(
       }
       const dispatchPlan = planNextTelegramQueueAction(
         dispatchableItems,
-        deps.canDispatch(ctx),
+        canDispatch,
       );
-      if (dispatchPlan.kind !== "none") {
+      if (nextActiveIndex > 0 || dispatchPlan.kind !== "none") {
         deps.setQueuedItems([
           ...dispatchPlan.remainingItems,
-          ...suppressedActiveItems,
           ...protectedInactiveItems,
         ]);
       }

package/lib/routing.ts

@@ -590,6 +590,11 @@ export interface TelegramInboundRouteRuntimeDeps<
     ctx: TContext,
   ) => Promise<boolean>;
   buttonActionStore?: OutboundHandlers.TelegramButtonActionStore;
+  invokeBoundButtonAction?: (
+    action: OutboundHandlers.TelegramOutboundButtonAction,
+    query: TCallbackQuery,
+    ctx: TContext,
+  ) => Promise<false | "new" | "edit">;
   inboundHandlerRuntime: TelegramInboundHandlerRuntime<TContext>;
   threadStore?: Threads.TelegramTopicTargetStore;
   updateStatus: (ctx: TContext, error?: string) => void;
@@ -1566,6 +1571,16 @@ export function createTelegramInboundRouteRuntime<
         {
           resolveAction: deps.buttonActionStore.resolve,
           answerCallbackQuery: deps.answerCallbackQuery,
+          ...(deps.invokeBoundButtonAction
+            ? {
+                invokeBoundAction: (buttonQuery, action, context) =>
+                  deps.invokeBoundButtonAction!(
+                    action,
+                    buttonQuery as TCallbackQuery,
+                    context,
+                  ),
+              }
+            : {}),
           editMessageReplyMarkup: deps.editMessageReplyMarkup
             ? async (chatId, messageId, replyMarkup) => {
                 try {

package/lib/runtime.ts

@@ -10,7 +10,6 @@ const TELEGRAM_TYPING_IDLE_DRAIN_MAX_MS = 250;
 export interface TelegramRuntimeQueueCounters {
   nextQueuedTelegramItemOrder: number;
   nextQueuedTelegramControlOrder: number;
-  nextPriorityReactionOrder: number;
 }
 
 export interface TelegramRuntimeLifecycleFlags {
@@ -34,8 +33,6 @@ export interface TelegramRuntimeQueuePort {
   syncCounters: (counters: Partial<TelegramRuntimeQueueCounters>) => void;
   allocateItemOrder: () => number;
   allocateControlOrder: () => number;
-  getNextPriorityReactionOrder: () => number;
-  incrementNextPriorityReactionOrder: () => void;
 }
 
 export interface TelegramRuntimeLifecyclePort {
@@ -85,7 +82,6 @@ export function createTelegramBridgeRuntimeState(): TelegramBridgeRuntimeState {
   return {
     nextQueuedTelegramItemOrder: 0,
     nextQueuedTelegramControlOrder: 0,
-    nextPriorityReactionOrder: 0,
     activeTelegramToolExecutions: 0,
     telegramTurnDispatchPending: false,
     compactionInProgress: false,
@@ -104,10 +100,6 @@ export function createTelegramBridgeRuntime(
         syncTelegramQueueRuntimeCounters(state, counters),
       allocateItemOrder: () => allocateTelegramQueueItemOrder(state),
       allocateControlOrder: () => allocateTelegramQueueControlOrder(state),
-      getNextPriorityReactionOrder: () =>
-        getNextTelegramPriorityReactionOrder(state),
-      incrementNextPriorityReactionOrder: () =>
-        incrementNextTelegramPriorityReactionOrder(state),
     },
     lifecycle: {
       syncFlags: (flags) => syncTelegramLifecycleRuntimeFlags(state, flags),
@@ -159,9 +151,6 @@ export function syncTelegramQueueRuntimeCounters(
     state.nextQueuedTelegramControlOrder =
       counters.nextQueuedTelegramControlOrder;
   }
-  if (counters.nextPriorityReactionOrder !== undefined) {
-    state.nextPriorityReactionOrder = counters.nextPriorityReactionOrder;
-  }
 }
 
 export function allocateTelegramQueueItemOrder(
@@ -176,18 +165,6 @@ export function allocateTelegramQueueControlOrder(
   return state.nextQueuedTelegramControlOrder++;
 }
 
-export function getNextTelegramPriorityReactionOrder(
-  state: TelegramBridgeRuntimeState,
-): number {
-  return state.nextPriorityReactionOrder;
-}
-
-export function incrementNextTelegramPriorityReactionOrder(
-  state: TelegramBridgeRuntimeState,
-): void {
-  state.nextPriorityReactionOrder += 1;
-}
-
 export function syncTelegramLifecycleRuntimeFlags(
   state: TelegramBridgeRuntimeState,
   flags: Partial<TelegramRuntimeLifecycleFlags>,

package/lib/updates.ts

@@ -133,24 +133,61 @@ export function getTelegramQueueReactionDisposition(
     emojis,
     TELEGRAM_REMOVAL_REACTION_EMOJIS,
   );
-  if (suppressionEmoji) return { kind: "suppressed", emoji: suppressionEmoji };
   const priorityEmoji = getTelegramReactionEmoji(
     emojis,
     TELEGRAM_PRIORITY_REACTION_EMOJIS,
   );
+  if (suppressionEmoji && priorityEmoji) {
+    return {
+      kind: "priority-suppressed",
+      priorityEmoji,
+      suppressionEmoji,
+    };
+  }
+  if (suppressionEmoji) return { kind: "suppressed", emoji: suppressionEmoji };
   if (priorityEmoji) return { kind: "priority", emoji: priorityEmoji };
   return { kind: "default" };
 }
 
-function areTelegramQueueReactionDispositionsEqual(
-  left: TelegramQueueReactionDisposition,
-  right: TelegramQueueReactionDisposition,
-): boolean {
-  return (
-    left.kind === right.kind &&
-    (left.kind === "default" ||
-      (right.kind !== "default" && left.emoji === right.emoji))
+function getTelegramQueueReactionTransition(
+  oldReactions: TelegramReactionType[],
+  newReactions: TelegramReactionType[],
+): TelegramQueueReactionDisposition | undefined {
+  const oldEmojis = collectTelegramReactionEmojis(oldReactions);
+  const newEmojis = collectTelegramReactionEmojis(newReactions);
+  const oldPriorityEmoji = getTelegramReactionEmoji(
+    oldEmojis,
+    TELEGRAM_PRIORITY_REACTION_EMOJIS,
   );
+  const newPriorityEmoji = getTelegramReactionEmoji(
+    newEmojis,
+    TELEGRAM_PRIORITY_REACTION_EMOJIS,
+  );
+  const oldSuppressionEmoji = getTelegramReactionEmoji(
+    oldEmojis,
+    TELEGRAM_REMOVAL_REACTION_EMOJIS,
+  );
+  const newSuppressionEmoji = getTelegramReactionEmoji(
+    newEmojis,
+    TELEGRAM_REMOVAL_REACTION_EMOJIS,
+  );
+  if (
+    oldPriorityEmoji === newPriorityEmoji &&
+    oldSuppressionEmoji === newSuppressionEmoji
+  ) {
+    return undefined;
+  }
+  const transition: Extract<
+    TelegramQueueReactionDisposition,
+    { kind: "reaction-transition" }
+  > = { kind: "reaction-transition" };
+  if (oldPriorityEmoji !== newPriorityEmoji) {
+    transition.priorityEmoji = newPriorityEmoji ?? null;
+  }
+  if (oldSuppressionEmoji !== newSuppressionEmoji) {
+    transition.suppressionEmoji = newSuppressionEmoji ?? null;
+  }
+  return transition;
 }
 
 export function extractDeletedTelegramMessageIds(
@@ -849,6 +886,19 @@ export type TelegramMessageOwnershipRecorder = (
   input: TelegramMessageOwnershipRecorderInput,
 ) => void;
 
+interface TelegramUnauthorizedReplyOptions {
+  parseMode?: "HTML";
+  target?: { chatId: number; threadId?: number };
+}
+
+const TELEGRAM_UNAUTHORIZED_DENIAL_COPY = "Access denied.";
+
+function formatTelegramUnauthorizedDenial(format: "plain" | "html"): string {
+  return format === "html"
+    ? `🚫 <b>${TELEGRAM_UNAUTHORIZED_DENIAL_COPY}</b>`
+    : `🚫 ${TELEGRAM_UNAUTHORIZED_DENIAL_COPY}`;
+}
+
 export interface TelegramUpdateRuntimeDeps<
   TContext = unknown,
   TReactionUpdate extends TelegramMessageReactionUpdated =
@@ -890,7 +940,11 @@ export interface TelegramUpdateRuntimeDeps<
     callbackQueryId: string,
     text?: string,
   ) => Promise<void>;
-  answerGuestQuery: (guestQueryId: string, text?: string) => Promise<void>;
+  answerGuestQuery: (
+    guestQueryId: string,
+    text?: string,
+    options?: Pick<TelegramUnauthorizedReplyOptions, "parseMode">,
+  ) => Promise<void>;
   handleAuthorizedTelegramCallbackQuery: (
     query: TCallbackQuery,
     ctx: TContext,
@@ -899,7 +953,7 @@ export interface TelegramUpdateRuntimeDeps<
     chatId: number,
     replyToMessageId: number,
     text: string,
-    options?: { target?: { chatId: number; threadId?: number } },
+    options?: TelegramUnauthorizedReplyOptions,
   ) => Promise<number | undefined>;
   handleAuthorizedTelegramMessage: (
     message: TMessage,
@@ -959,7 +1013,11 @@ export interface TelegramUpdateRuntimeControllerDeps<
     callbackQueryId: string,
     text?: string,
   ) => Promise<void>;
-  answerGuestQuery: (guestQueryId: string, text?: string) => Promise<void>;
+  answerGuestQuery: (
+    guestQueryId: string,
+    text?: string,
+    options?: Pick<TelegramUnauthorizedReplyOptions, "parseMode">,
+  ) => Promise<void>;
   handleAuthorizedTelegramCallbackQuery: (
     query: TCallbackQuery,
     ctx: TContext,
@@ -968,7 +1026,7 @@ export interface TelegramUpdateRuntimeControllerDeps<
     chatId: number,
     replyToMessageId: number,
     text: string,
-    options?: { target?: { chatId: number; threadId?: number } },
+    options?: TelegramUnauthorizedReplyOptions,
   ) => Promise<number | undefined>;
   handleAuthorizedTelegramMessage: (
     message: TMessage,
@@ -1299,17 +1357,11 @@ export async function handleAuthorizedTelegramReactionUpdate<TContext>(
     typeof reactionUpdate.chat.id === "number"
       ? { chatId: reactionUpdate.chat.id }
       : undefined;
-  const oldDisposition = getTelegramQueueReactionDisposition(
+  const reactionTransition = getTelegramQueueReactionTransition(
     reactionUpdate.old_reaction,
-  );
-  const newDisposition = getTelegramQueueReactionDisposition(
     reactionUpdate.new_reaction,
   );
-  if (
-    areTelegramQueueReactionDispositionsEqual(oldDisposition, newDisposition)
-  ) {
-    return;
-  }
+  if (!reactionTransition) return;
   deps.assertExecutionCurrent?.();
   await deps.flushPendingMediaGroupMessage?.(reactionUpdate.message_id);
   deps.assertExecutionCurrent?.();
@@ -1317,7 +1369,7 @@ export async function handleAuthorizedTelegramReactionUpdate<TContext>(
   deps.assertExecutionCurrent?.();
   deps.applyQueuedTelegramTurnReactionByMessageId(
     reactionUpdate.message_id,
-    newDisposition,
+    reactionTransition,
     deps.ctx,
     reactionScope,
   );
@@ -1418,7 +1470,7 @@ export async function executeTelegramUpdatePlan<
           assertExecutionCurrent();
           await deps.answerCallbackQuery(
             callbackQueryId,
-            "This bot is not authorized for your account.",
+            formatTelegramUnauthorizedDenial("plain"),
           );
         }
         return;
@@ -1433,7 +1485,8 @@ export async function executeTelegramUpdatePlan<
         assertExecutionCurrent();
         await deps.answerGuestQuery(
           plan.guestMessage.guest_query_id,
-          "🚫 Access denied.",
+          formatTelegramUnauthorizedDenial("html"),
+          { parseMode: "HTML" },
         );
         return;
       }
@@ -1553,8 +1606,8 @@ export async function executeTelegramUpdatePlan<
         await deps.sendTextReply(
           replyTarget.chatId,
           replyTarget.messageId,
-          "This bot is not authorized for your account.",
-          { target: replyTarget },
+          formatTelegramUnauthorizedDenial("html"),
+          { parseMode: "HTML", target: replyTarget },
         );
       }
       return;

package/package.json

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

package/skills/generated-control-surface/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: generated-control-surface
-description: Proactively compiles current state, available capabilities, and user intent into contextual, evidence-backed, ephemeral prompt-button interfaces. Use on Telegram turns and other prompt-button transports whenever controls materially shorten likely feedback, without requiring an explicit user request, while omitting decorative UI and preserving domain ownership; fixed transport menus and callbacks remain with their runtime owners.
+description: Proactively compiles current state, available capabilities, and user intent into contextual, evidence-backed, ephemeral prompt-button interfaces. Use on Telegram turns and other prompt-button transports whenever controls materially shorten likely feedback, without requiring an explicit user request; route reusable deterministic loops toward Generative Apps, omit decorative UI, and preserve domain ownership while fixed transport menus and callbacks remain with their runtime owners.
 ---
 
 # Generated Control Surface
@@ -23,7 +23,11 @@ The primitive belongs to the Surface plane: it projects State, exposes Agency ca
 
 ## Scope
 
-Use this Skill only to synthesize a state-derived prompt-button surface. Operating or modifying an existing Telegram bridge menu, callback interface, fixed frontend, or runtime-owned control stays with that subsystem and does not route here merely because it contains buttons.
+Use this Skill only to synthesize a state-derived prompt-button surface. Operating or modifying an existing Telegram bridge menu, callback interface, fixed frontend, runtime-owned control, or installed Generative App stays with that subsystem and does not route here merely because it contains buttons.
+
+This Skill and `generative-apps` share one logical button-matrix and `label + prompt` interaction model while retaining different execution owners. On Telegram, the bridge runtime owns the full JSON/CML action notation: this Skill emits an ephemeral surface from current context, while a Generative App returns reusable views through its script ABI. Shared rendering does not justify a third button Skill or move transport grammar into either interaction Skill.
+
+When a generated surface reveals repeated stable interaction with bounded state and deterministic transitions, load the complementary `generative-apps` Skill and consider compiling that loop. A Generative App may retain ordinary model-mediated prompt buttons beside deterministic bound methods, so only the stable actions need bypass inference. Conversely, keep one-off, interpretive, changing, and context-heavy interaction here when a reusable script would add no concrete latency, token, cost, reliability, or UX value.
 
 On Telegram turns, evaluate this Skill proactively rather than waiting for the user to ask for buttons. Load and apply it when a likely next decision, approval, navigation step, inspection, or bounded action can be made materially easier through controls; its correct output may still contain zero buttons when the admission test fails.
 
@@ -80,7 +84,9 @@ A surface normally contains:
 
 Prefer 2–6 controls for feedback and decisions; navigation collections may use up to 12 when the additional entries remain scannable. Split larger sets by category or page instead of building a button wall. Do not add navigation controls when the surface is a one-step decision.
 
-Present compact metadata as stacked key-value rows that reuse status-surface grammar: a short bold label, a colon, and an inline-code value when the value is path-like, numeric, an identifier, or machine state. Prefer ``**Path:** `/home/llb` `` and ``**Entries:** `1–10 of 52` `` on separate lines over prose fragments joined by a middle dot or other decorative section separator.
+When a logical grid has no semantic column headings but Markdown table syntax requires a header row, use the grid's first data row as the syntactic header and render each remaining row once beneath it. Do not insert blank, dash-only, duplicate, or invented placeholder headings: they add a false row to the projected topology. Use ordinary semantic headings when the data actually has named columns.
+
+Present compact metadata as stacked key-value rows that reuse status-surface grammar: a short bold label, a colon, and an inline-code value when the value is path-like, numeric, an identifier, or machine state. In Telegram Rich Markdown, use an actual Markdown list or blank paragraph boundaries so soft line breaks cannot collapse several fields into one visual line. Prefer ``- **Path:** `/home/llb` `` and ``- **Entries:** `1–10 of 52` `` over prose fragments joined by a middle dot or other decorative section separator.
 
 ## Truth Modes
 
@@ -118,7 +124,7 @@ Re-check mutable targets immediately before execution. Access denial never autho
 
 ## Prompt Buttons
 
-Use the transport's canonical prompt-button syntax. For pi-telegram, one top-level `telegram_button` comment accepts one JSON object, double-quoted attributes, a JSON matrix, or Compact Matrix Literal (CML). CML uses `{value}` or `{label|prompt}`, trims atom boundaries, preserves other printable text literally, and decodes only `\|`, `\}`, and `\\`; use JSON for multiline prompts, styles, or metadata. A top-level cell becomes one full-width row, while a nested row groups one or more controls horizontally without a parser-level width cap. Prefer one layout comment for multiple controls instead of repeating the marker; `telegram_buttons` is a plural alias, not a different format.
+Use the transport's canonical prompt-button syntax. For pi-telegram, one top-level `telegram_button` comment accepts one JSON object, double-quoted attributes, an adaptive JSON/CML matrix, or positional Compact Matrix Literal (CML). One matrix or row may mix named JSON objects with positional cells, and commas are optional only between completed elements while JSON object internals remain strict. CML uses `{value}`, `{label|prompt}`, or `{label|prompt|selected_style}`; the optional third atom requires an explicit prompt and accepts only `primary`, `success`, or `danger`. It trims atom boundaries, preserves other printable text literally, and decodes only `\|`, `\}`, and `\\`. Prefer CML whenever the model authors the control and it can express the required surface; fall back to expanded JSON only for multiline prompts, non-positional metadata, or a concrete CML parse/render failure, never merely from implementation habit. Deterministic Generative App scripts may return ordinary JSON because their source payload does not consume model-output tokens; author and operate those adapters through the `generative-apps` Skill rather than growing a parallel app workflow here. A top-level cell becomes one full-width row, while a nested row groups one or more controls horizontally without a parser-level width cap. Prefer one layout comment for multiple controls instead of repeating the marker; `telegram_buttons` is a plural alias, not a different format.
 
 ### Semantic Row Composition
 
@@ -158,6 +164,8 @@ Preserve the ordinary admission test: proactively offer an interactive surface e
 - Keep trivial interaction state in the visible conversation. When state becomes too large, long-lived, or error-prone for reliable conversational reconstruction, persist a small human-auditable Markdown state artifact at a deterministic task-owned path and render from it. The artifact belongs to the underlying task or domain, not to this Skill as shadow application state.
 - When transition rules are non-trivial or correctness-sensitive, use a small deterministic state-transition owner—script, module, tool, or existing domain API—that validates `current state + admitted action → next state`; let the model compile the surface from its result instead of informally simulating every transition. Do not create code or files for a trivial one-step interaction.
 - Treat repeated clicks against current state, not stale button appearance. If an action is already consumed or unavailable, keep state unchanged and say so briefly. Preserve an occupied or selected button when spatial layout matters, using its label or selected style as the visual state; omit unavailable controls when layout does not matter. Transport-level disabled buttons are optional, not assumed.
+- Preserve tap-ahead on transports where existing controls remain actionable and rapid clicks queue separate turns. In a source-then-destination interaction, persist the source selection but do not regenerate the board, enumerate destinations, or duplicate controls between the two prompts; emit at most a minimal acknowledgement and let the already visible surface carry the destination click. Regenerate after the completed transition, invalid input, or evidence that the transport cannot preserve the intermediate surface.
+- Resolve coordinate selection by current state rather than rigid click parity. Clicking any currently selectable source selects or replaces the source and then waits; acknowledge a replacement tersely without regenerating the surface. Only a click that is not a selectable source becomes a destination attempt when a source is already selected, at which point the domain owner validates the transition. Without a selected source, a non-source coordinate is a no-op.
 
 ```html
 <!-- telegram_button {"label":"🔍 Inspect run","prompt":"Inspect Run run:example read-only, summarize its current status and latest material evidence, then regenerate relevant supervision controls."} -->