@llblab/pi-kit 0.37.0 → 0.38.0

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

@@ -2,21 +2,19 @@
 
 _This file owns unresolved project work only. Completed behavior belongs in `CHANGELOG.md`; durable contracts belong in `AGENTS.md` and `/docs`._
 
-## 0.58.1 publication checkpoint
-
-- [ ] Publish the independent Thread chat-action fix through the protected dev-to-main path, requiring fresh Ubuntu, Windows and both macOS shard checks at the exact candidate head and candidate/merged-tree equality. Keep the immutable Connect-only minor unchanged and verify its publication before issuing the hotfix tag.
-- [ ] Verify the hotfix GitHub Release and public npm latest, exact tag/gitHead identity, canonical notes, packed runtime/skills and provenance before closing this checkpoint. No live session reload or Telegram probes; controlled transport tests do not prove live client presence.
-
 ## Disposable Thread live acceptance
 
 - [ ] After separate operator authorization, use disposable Telegram tabs to check leader Settings review/Back, one confirmed cleanup of an inactive slotless binding, preservation of its replacement letter holder, and visible outcome/recovery copy. Native filesystem and injected-transport tests do not prove live Telegram/client or native Windows acceptance. Never use production history as the disposable fixture.
 - [ ] On separately authorized disposable routing tabs, verify pending-choice protection, Cancel after the view becomes unavailable, expiry notice in the owned leader Thread and no duplicate deletion after an unknown outcome. Local native journal/API-decoder fixtures are not live client acceptance.
 
-## Prompt-cache live confirmation
+## Typing authority during Telegram turns
+
+Live report on package 0.58.2 and Pi 1.4.0: every Telegram turn logged `sendChatAction: Telegram API call authority is unavailable` in a connected, long-lived session. The reporter's leader/follower role and refusal stage are not yet known. Prompt-cache acceptance is complete; this is a separate typing-indicator investigation.
 
-The prompt-cache report remains open for the reporter's offered live Anthropic capture after the published fix. Native request/transcript checks do not replace cache-hit or signed-thinking measurements.
+The native expired-loop diagnostic case is corrected: real typing loop/starter, direct API runtime and API client regressions cover mocked HTTP 200 after stop/same-target replacement, with unchanged session generation and transport epoch. A process-local ended-loop observation suppresses only the corresponding typed authority diagnostic; the request still rejects, active-owner refusals remain visible, and no callback crosses IPC. Real-client regressions retain the original HTTP/network failure when authority expires during error handling; a native follower caller rejects a delayed ACK after its local owner ends, without replay. Direct/follower and Classic/Threaded paths remain distinct from live acceptance. This does not establish the cause of the reporter's live failure or prove client typing.
 
-- [ ] Review the reporter's resume and mid-session tool-change results (versions, cache read/write counts and new thinking-drop events). Close the report if the live evidence confirms the fix, or narrow any residual failure into actionable follow-up. Do not reconstruct or claim recovery of previously lost thinking blocks.
+- [ ] Correlate the live report with the corrected native case using only redacted leader/follower role, timing around loop end/replacement and refusal-stage evidence if available. Do not infer transport loss or widen authority from the error string alone; isolate any distinct current-owner refusal before another runtime change.
+- [ ] After separately approved live validation, confirm client typing and absence of expired-loop API noise across Telegram turns and loop replacement. Preserve exact Thread targeting, independent Thread requests, best-effort presence and no unhealthy-status escalation; local native fixtures are not live acceptance.
 
 ## Stuck forwarded command after Thread re-creation
 
@@ -40,8 +38,8 @@ A target-scoped reply refusal cannot prove that a command made no prior effects.
 
 ## Passive-child cold-import follow-up
 
-The 0.57.8 tag validation failed `Child process sharing the agent dir does not poll while parent owns Telegram lock` even when that file ran alone: `Child process did not exit. stdout= stderr=` at its existing child deadline. The other seven process tests and the identical pre-merge tree passed. That historical failure has no child-stage trace, so cold import, startup and a retained runtime handle remain competing explanations. Bounded diagnostic sampling is exhausted; passing traces showed imports up to 4.37 seconds against the five-second non-Windows child budget and natural exit within 8–14 ms after the event-loop checkpoint. These traces do not identify the original cause. A later main-validation recurrence stopped after `eval` and `import-start`, with parent-clock `elapsedMs=5009` and no import-complete checkpoint. That trace locates this recurrence before import completion, not in natural exit or a retained post-checkpoint handle; the slow dependency/startup cause remains unknown. The independent tag-owned Release validation passed the same committed tree, which does not erase the failed main check. The initial hotfix candidate then showed the same pre-import-completion state on Ubuntu at `elapsedMs=5026`; the recurrence is not macOS-only. Slow dependency/startup cost remains unexplained, separate from the fixture's corrected startup/exit observation contract.
-- [ ] Validate the corrected phase-owned passive-child fixture in fresh complete platform CI before publication: bounded total startup, a strict post-readiness exit guard, unchanged no-poll/natural-exit assertions and no forced shutdown or retry. Controlled delayed-start/retained-work regressions and local native passes are not platform proof. For any genuine recurrence, preserve deadline and stage evidence before correcting runtime imports or budgets. Do not spend unchanged-head diagnostic samples or claim runner contention or the historical cause is proven.
+The 0.57.8 tag validation failed `Child process sharing the agent dir does not poll while parent owns Telegram lock` even when that file ran alone: `Child process did not exit. stdout= stderr=` at its existing child deadline. The other seven process tests and the identical pre-merge tree passed. That historical failure has no child-stage trace, so cold import, startup and a retained runtime handle remain competing explanations. Bounded diagnostic sampling is exhausted; passing traces showed imports up to 4.37 seconds against the five-second non-Windows child budget and natural exit within 8–14 ms after the event-loop checkpoint. These traces do not identify the original cause. A later main-validation recurrence stopped after `eval` and `import-start`, with parent-clock `elapsedMs=5009` and no import-complete checkpoint. That trace locates this recurrence before import completion, not in natural exit or a retained post-checkpoint handle; the slow dependency/startup cause remains unknown. The minor release's independent tag-owned validation passed the same committed tree, which does not erase that historical failed main check. The initial hotfix candidate then showed the same pre-import-completion state on Ubuntu at `elapsedMs=5026`; the recurrence is not macOS-only. Slow dependency/startup cost remains unexplained, separate from the fixture's corrected startup/exit observation contract.
+- [ ] On a genuinely failing cold-import trace under the phase-owned fixture, isolate dependency/startup cost using its actual overall/exit deadline and stage evidence before changing runtime imports or budgets. Preserve natural-exit/no-poll assertions and job budgets. Do not spend unchanged-head diagnostic samples or infer runner contention or the historical cause from passing runs.
 
 ## Windows Workspace-gate fixture timeout
 

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

@@ -4,6 +4,16 @@
 
 ## Unreleased
 
+## 0.58.3: Typing Cancellation Diagnostics
+
+- `Typing diagnostics`: Ended typing loops no longer log cancellation-only authority refusals as API failures. Real HTTP/network failures retain their provenance and diagnostics even if authority expires before settlement. Requests remain rejected and single-attempt; callbacks stay local. Native late-success/failure and follower-ACK regressions cover this case, not the cause of the live report.
+- `Prompt-cache acceptance`: Reporter-provided live Anthropic captures and connected-session measurements confirm the released fix across tool changes, resume, local/Telegram switches and reconnect, with no new thinking drops in the tested runs. The remaining live-confirmation gate is closed; connected wire capture and broader model/cache-expiry coverage remain outside this evidence. Already-lost thinking is not reconstructed.
+
+## 0.58.2: Flexible Assistant Action Markup
+
+- `HTML actions`: Complete button/voice comments activate by their delimiters and accepted payload regardless of whitespace or surrounding Markdown, including code fences. Adjacent same-line comments are independent; unfinished comments do not activate. Escape the opening delimiter as `<!--` for literal examples.
+- `In-body buttons`: Fenced `telegram_button` blocks tolerate horizontal indentation, whitespace before the exact name, and three or more backticks or tildes. Closures require the same marker and at least the opening length on a separate line. Enclosing fenced examples remain literal; incomplete blocks, malformed JSON/CML and invalid rows still register no callbacks.
+
 ## 0.58.1: Independent Thread Typing
 
 - `Typing`: A pending activity request in one Thread no longer silently suppresses another Thread's typing. Exact chat/Thread/action calls still coalesce with their own minimum interval, while real Telegram 429 cooldowns remain shared across the chat, including late failures after a faster peer completes. Authority checks, one-attempt typing and bounded gate storage remain intact.

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

@@ -4,7 +4,7 @@
  * Owns assistant-authored telegram_button extraction, button action storage, callback handling, and prompt-turn construction
  */
 import { randomUUID } from "node:crypto";
-import { getTelegramActionString as getTelegramButtonString, parseTelegramActionPayloadRows, parseTelegramButtonPayloadRows, replaceTelegramButtonFences, replaceTopLevelHtmlComments, } from "./outbound-markup.js";
+import { getTelegramActionString as getTelegramButtonString, parseTelegramActionPayloadRows, parseTelegramButtonPayloadRows, replaceTelegramButtonFences, replaceTelegramHtmlComments, } from "./outbound-markup.js";
 import { truncateTelegramQueueSummary, } from "./queue.js";
 const TELEGRAM_BUTTON_CALLBACK_PREFIX = "tgbtn";
 const TELEGRAM_BUTTON_ACTION_TTL_MS = 24 * 60 * 60 * 1000;
@@ -117,7 +117,23 @@ export function planTelegramButtonReply(markdown, deps) {
                 }),
             }));
     };
-    const withRichButtons = replaceTelegramButtonFences(markdown, (payload, closed) => {
+    const footerKeyboard = [];
+    const stripped = replaceTelegramHtmlComments(markdown, (comment) => {
+        const command = "telegram_button";
+        const normalizedContent = comment.content
+            .replace(/^\s+/, "")
+            .replace(/^!/, "");
+        if (!normalizedContent.startsWith(command))
+            return comment.raw;
+        const payloadRows = parseTelegramActionPayloadRows(comment, command);
+        if (!payloadRows)
+            return "";
+        const rows = buildRows(payloadRows, false);
+        if (rows)
+            footerKeyboard.push(...rows);
+        return "";
+    });
+    const withRichButtons = replaceTelegramButtonFences(stripped, (payload, closed) => {
         if (!closed)
             return "";
         const payloadRows = parseTelegramButtonPayloadRows(payload);
@@ -133,22 +149,8 @@ export function planTelegramButtonReply(markdown, deps) {
         }
         return `\n${rows.map(renderTelegramRichButtonRow).join("\n\n")}\n`;
     });
-    const stripped = replaceTopLevelHtmlComments(withRichButtons, (comment) => {
-        const command = "telegram_button";
-        const normalizedContent = comment.content
-            .replace(/^\s+/, "")
-            .replace(/^!/, "");
-        if (!normalizedContent.startsWith(command))
-            return comment.raw;
-        const payloadRows = parseTelegramActionPayloadRows(comment, command);
-        if (!payloadRows)
-            return "";
-        const rows = buildRows(payloadRows, false);
-        if (rows)
-            keyboard.push(...rows);
-        return "";
-    });
-    const visibleMarkdown = normalizeMarkdownAfterButtonExtraction(stripped);
+    keyboard.push(...footerKeyboard);
+    const visibleMarkdown = normalizeMarkdownAfterButtonExtraction(withRichButtons);
     return {
         markdown: keyboard.length > 0 && !visibleMarkdown
             ? DEFAULT_TELEGRAM_BUTTON_REPLY_MARKDOWN

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

@@ -1,22 +1,22 @@
 /**
  * Telegram outbound markup parsing helpers
  * Zones: telegram outbound, assistant markup
- * Owns top-level assistant action comment extraction, attribute parsing, and markup stripping shared by voice and outbound delivery
+ * Owns delimiter-based assistant action comment extraction, attribute parsing, and markup stripping shared by voice and outbound delivery
  */
-export interface TelegramTopLevelHtmlComment {
+export interface TelegramHtmlComment {
     raw: string;
     content: string;
     start: number;
     end: number;
 }
-export declare function collectTopLevelHtmlComments(markdown: string): {
-    comments: TelegramTopLevelHtmlComment[];
+export declare function collectTelegramHtmlComments(markdown: string): {
+    comments: TelegramHtmlComment[];
     openCommentStart?: number;
 };
 export declare function replaceTelegramButtonFences(markdown: string, replace: (payload: string, closed: boolean) => string): string;
-export declare function replaceTopLevelHtmlComments(markdown: string, replacer: (comment: TelegramTopLevelHtmlComment) => string): string;
+export declare function replaceTelegramHtmlComments(markdown: string, replacer: (comment: TelegramHtmlComment) => string): string;
 export declare function parseTelegramButtonPayloadRows(source: string): Record<string, unknown>[][] | undefined;
-export declare function parseTelegramActionPayloadRows(comment: TelegramTopLevelHtmlComment, command: string): Record<string, unknown>[][] | undefined;
+export declare function parseTelegramActionPayloadRows(comment: TelegramHtmlComment, command: string): Record<string, unknown>[][] | undefined;
 export declare function stripTelegramCommentMarkupForPreview(markdown: string): string;
 export declare function stripTelegramCommentMarkupForDelivery(markdown: string): string;
 export interface TelegramVoiceReplyItem {

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

@@ -1,7 +1,7 @@
 /**
  * Telegram outbound markup parsing helpers
  * Zones: telegram outbound, assistant markup
- * Owns top-level assistant action comment extraction, attribute parsing, and markup stripping shared by voice and outbound delivery
+ * Owns delimiter-based assistant action comment extraction, attribute parsing, and markup stripping shared by voice and outbound delivery
  */
 import { isWireRecord as isTelegramActionPayload } from "./wire.js";
 function getMarkdownLineEnd(markdown, offset) {
@@ -12,7 +12,7 @@ function getMarkdownLineText(markdown, offset, end) {
     return markdown.slice(offset, end).replace(/\r?\n$/, "");
 }
 function getTopLevelOpeningFence(line) {
-    const match = line.match(/^(?: {0,3})(`{3,}|~{3,})/);
+    const match = line.match(/^[ \t]*(`{3,}|~{3,})/);
     const sequence = match?.[1];
     if (!sequence)
         return undefined;
@@ -22,43 +22,26 @@ function getTopLevelOpeningFence(line) {
     };
 }
 function isTopLevelClosingFence(line, fence) {
-    const match = line.match(/^(?: {0,3})(`{3,}|~{3,})([ \t]*)$/);
+    const match = line.match(/^[ \t]*(`{3,}|~{3,})[ \t]*$/);
     const sequence = match?.[1];
     return (!!sequence &&
         sequence[0] === fence.marker &&
         sequence.length >= fence.length);
 }
-export function collectTopLevelHtmlComments(markdown) {
+export function collectTelegramHtmlComments(markdown) {
     const comments = [];
     let offset = 0;
-    let fence;
     while (offset < markdown.length) {
-        const lineEnd = getMarkdownLineEnd(markdown, offset);
-        const line = getMarkdownLineText(markdown, offset, lineEnd);
-        if (fence) {
-            if (isTopLevelClosingFence(line, fence))
-                fence = undefined;
-            offset = lineEnd;
-            continue;
-        }
-        const nextFence = getTopLevelOpeningFence(line);
-        if (nextFence) {
-            fence = nextFence;
-            offset = lineEnd;
-            continue;
-        }
-        if (line.startsWith("<!--")) {
-            const closeIndex = markdown.indexOf("-->", offset + 4);
-            if (closeIndex === -1)
-                return { comments, openCommentStart: offset };
-            const end = closeIndex + 3;
-            const raw = markdown.slice(offset, end);
-            const content = raw.slice(4, -3);
-            comments.push({ raw, content, start: offset, end });
-            offset = getMarkdownLineEnd(markdown, end);
-            continue;
-        }
-        offset = lineEnd;
+        const start = markdown.indexOf("<!--", offset);
+        if (start === -1)
+            break;
+        const closeIndex = markdown.indexOf("-->", start + 4);
+        if (closeIndex === -1)
+            return { comments, openCommentStart: start };
+        const end = closeIndex + 3;
+        const raw = markdown.slice(start, end);
+        comments.push({ raw, content: raw.slice(4, -3), start, end });
+        offset = end;
     }
     return { comments };
 }
@@ -92,7 +75,7 @@ export function replaceTelegramButtonFences(markdown, replace) {
         }
         else {
             fence = getTopLevelOpeningFence(line);
-            if (fence && /^```telegram_button[ \t]*$/.test(line)) {
+            if (fence && /^[ \t]*(?:`{3,}|~{3,})[ \t]*telegram_button[ \t]*$/.test(line)) {
                 actionStart = offset;
                 contentStart = end;
             }
@@ -105,8 +88,8 @@ export function replaceTelegramButtonFences(markdown, replace) {
     }
     return result + markdown.slice(copied);
 }
-export function replaceTopLevelHtmlComments(markdown, replacer) {
-    const { comments } = collectTopLevelHtmlComments(markdown);
+export function replaceTelegramHtmlComments(markdown, replacer) {
+    const { comments } = collectTelegramHtmlComments(markdown);
     if (comments.length === 0)
         return markdown;
     let result = "";
@@ -118,34 +101,9 @@ export function replaceTopLevelHtmlComments(markdown, replacer) {
     }
     return result + markdown.slice(offset);
 }
-function findTopLevelOpenOrPartialHtmlCommentIndex(markdown) {
-    const { openCommentStart } = collectTopLevelHtmlComments(markdown);
-    if (openCommentStart !== undefined)
-        return openCommentStart;
-    let offset = 0;
-    let fence;
-    while (offset < markdown.length) {
-        const lineEnd = getMarkdownLineEnd(markdown, offset);
-        const line = getMarkdownLineText(markdown, offset, lineEnd);
-        const isLastLine = lineEnd >= markdown.length;
-        if (fence) {
-            if (isTopLevelClosingFence(line, fence))
-                fence = undefined;
-            offset = lineEnd;
-            continue;
-        }
-        const nextFence = getTopLevelOpeningFence(line);
-        if (nextFence) {
-            fence = nextFence;
-            offset = lineEnd;
-            continue;
-        }
-        if (isLastLine && (line === "<" || line === "<!" || line === "<!-")) {
-            return offset;
-        }
-        offset = lineEnd;
-    }
-    return -1;
+function findOpenOrPartialHtmlCommentIndex(markdown) {
+    const start = markdown.indexOf("<!--");
+    return start >= 0 ? start : (markdown.match(/<(?:!-?)?$/u)?.index ?? -1);
 }
 function parseTolerantTelegramAttributes(source, names) {
     const attributes = {};
@@ -592,7 +550,7 @@ function stripTelegramHtmlCommentBlocks(markdown) {
 }
 export function stripTelegramCommentMarkupForPreview(markdown) {
     const withoutClosedBlocks = stripTelegramHtmlCommentBlocks(replaceTelegramButtonFences(markdown, () => ""));
-    const openBlockIndex = findTopLevelOpenOrPartialHtmlCommentIndex(withoutClosedBlocks);
+    const openBlockIndex = findOpenOrPartialHtmlCommentIndex(withoutClosedBlocks);
     const previewMarkdown = openBlockIndex >= 0
         ? withoutClosedBlocks.slice(0, openBlockIndex)
         : withoutClosedBlocks;
@@ -600,7 +558,7 @@ export function stripTelegramCommentMarkupForPreview(markdown) {
 }
 export function stripTelegramCommentMarkupForDelivery(markdown) {
     const withoutClosedBlocks = stripTelegramHtmlCommentBlocks(markdown);
-    const openBlockIndex = findTopLevelOpenOrPartialHtmlCommentIndex(withoutClosedBlocks);
+    const openBlockIndex = findOpenOrPartialHtmlCommentIndex(withoutClosedBlocks);
     const deliveryMarkdown = openBlockIndex >= 0
         ? withoutClosedBlocks.slice(0, openBlockIndex)
         : withoutClosedBlocks;
@@ -617,7 +575,7 @@ export function planTelegramVoiceReply(markdown) {
     const voiceReplies = [];
     let lang;
     let rate;
-    const stripped = replaceTopLevelHtmlComments(markdown, (comment) => {
+    const stripped = replaceTelegramHtmlComments(markdown, (comment) => {
         const command = "telegram_voice";
         const normalizedContent = comment.content
             .replace(/^\s+/, "")

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

@@ -412,10 +412,10 @@ export function createTelegramOutboundReplyPlanner(store, getRenderingMode = ()
             rendering: getRenderingMode(),
             ...(options?.binding ? { binding: options.binding } : {}),
         });
-        // Button replies can also contain <!-- telegram_voice --> markup
-        const voiceReply = planTelegramVoiceReply(buttonReply.markdown);
+        // Extract voice from the original text before button-fence rendering consumes it.
+        const voiceReply = planTelegramVoiceReply(markdown);
         return {
-            markdown: voiceReply.markdown,
+            markdown: stripTelegramCommentMarkupForDelivery(buttonReply.markdown),
             ...(buttonReply.replyMarkup
                 ? { replyMarkup: buttonReply.replyMarkup }
                 : {}),

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

@@ -9,7 +9,7 @@ export declare const TELEGRAM_DISCONNECTED_CONTEXT_MESSAGE = "Telegram session d
 export declare const TELEGRAM_ATTACH_PROMPT_SNIPPET = "Queue files for the active Telegram reply; outside Telegram turns, send files directly to Telegram.";
 export declare const TELEGRAM_ATTACH_PROMPT_GUIDELINES: readonly ["When handling a [telegram] message and the user asked for a file or generated artifact, call telegram_attach with the local path instead of only mentioning the path in text.", "When a local/TUI user explicitly asks to send a generated file to Telegram, telegram_attach can deliver it to the paired/default Telegram chat even without an active Telegram turn.", "For an explicit thread target, provide chat_id plus thread_id; registered multi-instance followers default to their assigned thread target."];
 export declare const TELEGRAM_MESSAGE_PROMPT_SNIPPET = "Send direct Telegram Markdown text when the user explicitly asks for Telegram delivery to a concrete chat, channel, or live Pi Thread outside the normal reply flow.";
-export declare const TELEGRAM_MESSAGE_PROMPT_GUIDELINES: readonly ["Use telegram_message only when the user explicitly asks to send a message to Telegram from the local/TUI side, or names a concrete Telegram delivery target.", "For an explicitly requested channel post, pass its exact numeric id or public @username as chat_id; no local channel registry is required, and Telegram remains the authority on the bot's posting permission.", "For an explicitly requested channel media post, pass one local .jpg/.jpeg/.png/.webp photo or .mp4 video as media; the text becomes its caption (max 1024 characters), and albums or other media types are rejected.", "For a live Pi thread target, provide thread as its case-insensitive name or numeric id; the bridge sends visibly and admits one attributed turn to that live instance. Unknown, ambiguous, same, or offline targets fail before sending.", "Add buttons by embedding the same top-level telegram_button HTML comments used in normal Telegram replies; Telegram does not support standalone buttons.", "During an active Telegram turn, omit telegram_message for the current target and answer normally; use thread only when the user requests delivery to a different live Pi thread."];
+export declare const TELEGRAM_MESSAGE_PROMPT_GUIDELINES: readonly ["Use telegram_message only when the user explicitly asks to send a message to Telegram from the local/TUI side, or names a concrete Telegram delivery target.", "For an explicitly requested channel post, pass its exact numeric id or public @username as chat_id; no local channel registry is required, and Telegram remains the authority on the bot's posting permission.", "For an explicitly requested channel media post, pass one local .jpg/.jpeg/.png/.webp photo or .mp4 video as media; the text becomes its caption (max 1024 characters), and albums or other media types are rejected.", "For a live Pi thread target, provide thread as its case-insensitive name or numeric id; the bridge sends visibly and admits one attributed turn to that live instance. Unknown, ambiguous, same, or offline targets fail before sending.", "Add buttons by embedding the same telegram_button HTML comments used in normal Telegram replies; Telegram does not support standalone buttons.", "During an active Telegram turn, omit telegram_message for the current target and answer normally; use thread only when the user requests delivery to a different live Pi thread."];
 export interface TelegramModelContextAvailabilityMemory {
     suspended: boolean;
     toolNames: Set<string>;

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

@@ -24,7 +24,7 @@ export const TELEGRAM_MESSAGE_PROMPT_GUIDELINES = [
     "For an explicitly requested channel post, pass its exact numeric id or public @username as chat_id; no local channel registry is required, and Telegram remains the authority on the bot's posting permission.",
     "For an explicitly requested channel media post, pass one local .jpg/.jpeg/.png/.webp photo or .mp4 video as media; the text becomes its caption (max 1024 characters), and albums or other media types are rejected.",
     "For a live Pi thread target, provide thread as its case-insensitive name or numeric id; the bridge sends visibly and admits one attributed turn to that live instance. Unknown, ambiguous, same, or offline targets fail before sending.",
-    "Add buttons by embedding the same top-level telegram_button HTML comments used in normal Telegram replies; Telegram does not support standalone buttons.",
+    "Add buttons by embedding the same telegram_button HTML comments used in normal Telegram replies; Telegram does not support standalone buttons.",
     "During an active Telegram turn, omit telegram_message for the current target and answer normally; use thread only when the user requests delivery to a different live Pi thread.",
 ];
 const TELEGRAM_TOOL_METADATA_LINES = Object.fromEntries([

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

@@ -119,6 +119,7 @@ export interface TelegramTypingLoopStarterDeps<TContext> extends TelegramRuntime
     sendTypingAction: (chatId: number, options?: {
         message_thread_id?: number;
         assertAuthority?: () => void;
+        isCancelled?: () => boolean;
     }) => Promise<unknown>;
     updateStatus: (ctx: TContext, error?: string) => void;
     isContextActive?: (ctx: TContext) => boolean;

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

@@ -236,6 +236,7 @@ export function createTelegramTypingLoopStarter(deps) {
                 try {
                     await deps.sendTypingAction(targetChatId, {
                         ...actionOptions,
+                        isCancelled: () => !active,
                         // This stays process-local; adapters recheck it before HTTP/IPC issuance, not just loop ticks.
                         assertAuthority() {
                             if (!active || !canContinue())

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

@@ -304,10 +304,10 @@ export interface TelegramApiCallOptions {
 }
 export declare class TelegramApiAuthorityError extends Error {
     readonly requestIssued: boolean;
-    constructor(requestIssued: boolean);
+    constructor(requestIssued: boolean, options?: ErrorOptions);
 }
 /** Recheck caller authority, classifying refusal by whether a Bot API request was already issued. */
-export declare function assertTelegramApiCallAuthority(assertAuthority: (() => void) | undefined, requestIssued: boolean): void;
+export declare function assertTelegramApiCallAuthority(assertAuthority: (() => void) | undefined, requestIssued: boolean, errorOptions?: ErrorOptions): void;
 export interface TelegramFileDownloadOptions {
     signal?: AbortSignal;
     maxFileSizeBytes?: number;
@@ -444,6 +444,8 @@ export interface TelegramBridgeApiRuntimeDeps {
 /** Typing issuance guard is local authority, never Bot API body or IPC data. */
 export interface TelegramTypingActionOptions extends Pick<TelegramApiCallOptions, "assertAuthority"> {
     message_thread_id?: number;
+    /** Diagnostic observation only: an ended loop does not grant issuance, success or retry. */
+    isCancelled?: () => boolean;
 }
 export interface TelegramBridgeApiRuntime extends Pick<TelegramApiClient, "call" | "callMultipart"> {
     downloadFile: (fileId: string, suggestedName: string, source?: TelegramAttachmentSource) => Promise<string>;

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

@@ -43,19 +43,19 @@ const TELEGRAM_NETWORK_FAMILY_VALUES = new Set([
 ]);
 export class TelegramApiAuthorityError extends Error {
     requestIssued;
-    constructor(requestIssued) {
-        super("Telegram API call authority is unavailable.");
+    constructor(requestIssued, options) {
+        super("Telegram API call authority is unavailable.", options);
         this.name = "TelegramApiAuthorityError";
         this.requestIssued = requestIssued;
     }
 }
 /** Recheck caller authority, classifying refusal by whether a Bot API request was already issued. */
-export function assertTelegramApiCallAuthority(assertAuthority, requestIssued) {
+export function assertTelegramApiCallAuthority(assertAuthority, requestIssued, errorOptions) {
     try {
         assertAuthority?.();
     }
     catch {
-        throw new TelegramApiAuthorityError(requestIssued);
+        throw new TelegramApiAuthorityError(requestIssued, errorOptions);
     }
 }
 function parseTelegramApiTargetInteger(value) {
@@ -765,7 +765,7 @@ async function callTelegramWithRetry(method, request, options) {
             // Authority refusal is never a transport failure, retry grant or acknowledged success.
             if (error instanceof TelegramApiAuthorityError)
                 throw error;
-            assertTelegramApiCallAuthority(assertAuthority, requestIssued);
+            assertTelegramApiCallAuthority(assertAuthority, requestIssued, { cause: error });
             const retryable = isRetryableTelegramApiError(error) &&
                 !(options?.retryRateLimit === false &&
                     error instanceof TelegramApiHttpError &&
@@ -1120,7 +1120,10 @@ export function createTelegramBridgeApiRuntime(deps) {
                     }));
                     return true;
                 }
-                deps.recordRuntimeEvent("api", error, withTelegramTransportDiagnostics(error, { method }));
+                const diagnosticError = error instanceof TelegramApiAuthorityError && Object.hasOwn(error, "cause")
+                    ? error.cause : error;
+                if (!options?.isExpectedError?.(error))
+                    deps.recordRuntimeEvent("api", diagnosticError, withTelegramTransportDiagnostics(diagnosticError, { method }));
                 throw error;
             })
                 .finally(() => {
@@ -1194,13 +1197,21 @@ export function createTelegramBridgeApiRuntime(deps) {
                 ? { message_thread_id: options.message_thread_id }
                 : {}),
         }),
-        sendTypingAction: createTelegramChatActionSender((chatId, action, options) => callRecorded("sendChatAction", {
-            chat_id: chatId,
-            action,
-            ...(options?.message_thread_id !== undefined
-                ? { message_thread_id: options.message_thread_id }
-                : {}),
-        }, { assertAuthority: options?.assertAuthority }), "typing"),
+        sendTypingAction: createTelegramChatActionSender((chatId, action, options) => {
+            const isCancelled = options?.isCancelled;
+            return callRecorded("sendChatAction", {
+                chat_id: chatId,
+                action,
+                ...(options?.message_thread_id !== undefined
+                    ? { message_thread_id: options.message_thread_id }
+                    : {}),
+            }, {
+                assertAuthority: options?.assertAuthority,
+                ...(isCancelled ? {
+                    isExpectedError: (error) => error instanceof TelegramApiAuthorityError && !Object.hasOwn(error, "cause") && isCancelled() === true,
+                } : {}),
+            });
+        }, "typing"),
         sendRecordVoiceAction: createTelegramChatActionSender((chatId, action, options) => callRecorded("sendChatAction", {
             chat_id: chatId,
             action,

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

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

package/node_modules/@llblab/pi-telegram/dist/skills/telegram-bridge/SKILL.md

@@ -16,12 +16,12 @@ Use Telegram as a mobile companion to the current Pi session. Preserve the exact
 | Explicitly send from local/TUI to Telegram | `telegram_message` or `telegram_attach` |
 | Explicitly send to a different live Thread | `telegram_message(thread=...)` |
 | Add buttons | Hidden comment for footer; `telegram_button` fence for in-body rows |
-| Add explicit voice | Top-level hidden action comment |
+| Add explicit voice | Hidden action comment |
 | Build a repeated deterministic interaction | Follow `generative-apps` |
 
 A connected Telegram session proves capability, not user intent. Use Telegram features on Telegram-originated turns or explicit Telegram delivery requests only. Never call `telegram_message` for the current active target.
 
-For direct delivery, Thread routing, configuration, or diagnosis, read only the applicable reference listed under [Conditional References](#conditional-references).
+For delivery, Thread routing, configuration or diagnosis, read the applicable reference under [Conditional References](#conditional-references).
 
 ## Turn Context
 
@@ -40,7 +40,7 @@ Reply in concise, phone-width Telegram Rich Markdown. Use `$...$` and `$$...$$`
 
 ## Assistant Actions
 
-`telegram_button` and `telegram_voice` are markup, not tools. Emit action comments at column zero outside lists, quotes, code, and indentation. Comments create footer buttons or voice artifacts. For buttons between paragraphs, use a column-zero triple-backtick `telegram_button` block. Both button wrappers accept the same singleton JSON/CML cell or mixed matrix; the wrapper determines placement. Telegram removes every assistant-authored HTML comment from previews and final replies regardless of owner or Markdown position; only recognized top-level wrappers activate actions; comment-only output sends no text message.
+`telegram_button` and `telegram_voice` are markup, not tools. Complete comments activate regardless of surrounding Markdown. Escape `<!--` as `&lt;!--` for literal examples; backticks and backslashes do not disable actions. Comments create footer buttons or voice artifacts. In-body fences: ≥3 backticks/tildes, optional indentation/whitespace, exact `telegram_button`; separate same-marker closure, no shorter. Both wrappers accept a singleton JSON/CML cell or mixed matrix; the wrapper determines placement. Telegram removes every assistant-authored HTML comment from previews and final replies regardless of owner or Markdown position; only complete recognized comments or valid button fences activate actions; comment-only output sends no text message.
 
 ### Shared Encoding Rule
 
@@ -61,7 +61,7 @@ Every enabled button has a self-contained prompt and an optional selection style
 - `{label|prompt|selected_style}` and `{|prompt|selected_style}` accept `primary`, `success`, or `danger`.
 - Fourth-position `1`/`true` disables, `0`/`false` enables; omission means enabled. JSON uses boolean `disabled`. `{|Next||1}` omits label/style; `{Next|||1}` omits prompt/style; `{|||1}` is blank (Telegram receives a non-breaking space). Prefer meaningful labels and retain a useful enabled action. Enabled CML requires a prompt. Disabled controls stay visible but have no callback, queued prompt, or bound-method invocation.
 - Both wrappers concatenate rows from adjacent JSON/CML cells or matrices, with optional commas. Cells are vertical; horizontal peers require a nested row: `[[{A|a}{B|b}]]`.
-- Prefer one matrix per related group. Fenced blocks stay in place in Rich mode; HTML compatibility moves them to the footer. Native rows allow eight buttons. Malformed/oversized/unclosed blocks activate nothing; drafts hide them. Outer code fences and quoted/indented examples remain literal.
+- Prefer one matrix per related group. Fenced blocks stay in place in Rich mode; HTML compatibility moves them to the footer. Native rows allow eight buttons. Malformed/oversized/unclosed blocks activate nothing; drafts hide them. Enclosing code fences and quoted/list-prefixed button fences remain literal.
 - Both placements share prompt/app routing. In-body clicks acknowledge without recoloring; selected-style highlighting remains footer-only.
 
 A single in-body button (the four-backtick wrapper below makes this a literal example):
@@ -124,6 +124,6 @@ Before replying:
 
 - Use the ordinary path for the current target and direct tools only for explicit other delivery.
 - Attach requested files rather than only mentioning them.
-- Keep action comments and button fences top-level, complete, and canonical: CML first, JSON when necessary; either syntax may coexist within one matrix.
+- Keep comments complete and button fences top-level and canonical: CML first, JSON when necessary; either syntax may coexist within one matrix.
 - Give every enabled button a self-contained prompt; preserve confirmation for dangerous actions.
 - Expose no secret or hidden reasoning.

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

@@ -106,7 +106,7 @@ Only the live cleanup origin uses the approved historical-protection reduction.
 - `preview` / `replies` / `rendering`: throttled native Rich Markdown draft delivery, native final reply delivery, reply parameters, transport-limit chunking, and remaining Telegram HTML rendering (bold, italic, strikethrough, spoilers, code, links) for bridge-owned UI/compatibility surfaces.
 - `delivery`: public extension operational-view delivery, active-turn/instance/aggregate/authorized target policy, logical chunk handles, per-target ordering, runtime generation fencing, and the process-local runtime membrane. Its bridge adapter composes the established UI/compat reply renderer with narrow bus-aware Telegram API and ownership ports; it never exposes bot clients or Pi contexts.
 - `activity`: public normalized Pi lifecycle registration, activity/source identity, assistant segment and reasoning normalization, executed-tool events, non-blocking per-handler queues, delivery contexts, compatibility adapters, and shutdown fencing. Internal publication/command-work and handler drain notifications share the lifecycle-owned captured-session/transport observer with companion queues and API target counters; bindings/root wire those neutral ports into routing's existing leader cleanup scheduler, never into deletion authority. Routing retains busy/unproven-idle delivery hints without early admission, preserves ordinary timers, and lets semantic settlement or post-settlement output drain request fresh checks. The same domain extends assistant-output observation for connected companion projection: eligible completed local/autonomous public segments retain source order and deduplicate event identity. `bindings` assembles observation, authority, sender, and failure-projection ports; routing owns exact delivery authority, outbound composes established transformations and reply delivery, and Bot API domains implement transport. No separate proactive state-machine domain exists.
-- `outbound-markup`: top-level assistant action comment/fence parsing, shared JSON/CML grammar, attribute parsing, voice reply planning, and preview/delivery stripping.
+- `outbound-markup`: delimiter-based assistant action comments, top-level button fence parsing, shared JSON/CML grammar, attribute parsing, voice reply planning, and preview/delivery stripping.
 - `outbound`: outbound text transformations, voice/button artifact delivery, and generated callback actions.
 - `generative-apps`: managed deterministic application identity, canonical installation and explicit replacement, content-addressed module loading, state timelines, cross-process transition serialization, bounded executable-plus-argv adaptation, `telegram_bind`, and pre-model-queue `app::method` invocation. It does not own Telegram transport, arbitrary shell execution, or the external application adapted by one Generative App.
 - `outbound-attachments`: `telegram_attach`, queued outbound files, stat/limit checks, ordinary photo/document delivery, and narrow single-artifact Rich Message planning/sending for probe-confirmed photo/video/audio formats. It owns known-failure fallback eligibility and ambiguous-send no-replay classification through structural error contracts without importing Bot API helpers.
@@ -685,7 +685,7 @@ Native typing during compaction follows connected-instance activity rather than
 - Thread-targeted typing is sent only to the concrete thread. Aggregate `All` mirroring is intentionally omitted because duplicating every keepalive multiplies shared-chat flood pressure. Compaction completion, failure, or timeout stops only a loop actually started by the compaction observer; a pre-existing agent-owned loop remains active. Ownership is sticky across a repeated compaction start, whose shared-loop start reports `false` for the observer's own running loop. Authority loss and shutdown still stop the keyed loop.
 - Pi `ui_prompt_start` pauses typing while an extension-owned local prompt waits for the operator; `ui_prompt_end` emits the matching Activity boundary and resumes typing whenever agent or compaction work remains unsettled.
 
-At every connected instance `agent_start`, the lifecycle binding starts Telegram's native `…typing` indicator in that instance's assigned target, whether the run came from Telegram, the local TUI, or an autonomous continuation such as Grow Loop. Terminal `Active` remains Telegram-turn-specific; the native indicator answers the separate question of whether the instance is doing agent work. Streaming keepalives reuse a valid typing owner with the same session generation, transport and target rather than revoking its pending HTTP/IPC action. Fresh context wrappers may reuse that owner within a proven generation; without generation evidence, context identity must match. Explicit queue dispatch and Telegram prompt handoff still replace the owner. Queue dispatch carries the queued turn's exact target into typing before `agent_start`, rather than reducing it to a chat ID. In Threaded Mode, missing or invalid Thread targets are refused before starting a loop or invoking the API; mode changes also invalidate a captured Classic chat-only loop. A rejected start never replaces an existing valid Thread loop. The starter also requires the captured Pi context and session generation to remain current at start, queued send, tick and late failure boundaries, even if the transport epoch is unchanged; replacing a context object in place cannot revive old activity. Message activity hooks capture generation across awaited preview work, and agent-start bindings recheck it before post-await activity/typing, so an obsolete finally or continuation cannot acquire replacement ownership. The typing sender carries its captured loop/context/generation/transport assertion as process-local call authority: direct API issuance rechecks it after queued work, and the follower caller rechecks it after registration waits and immediately before socket issuance without putting callbacks in IPC data. Automatic typing uses one HTTP attempt with no transport-family fallback or delayed replay, including forwarded calls; a future keepalive is a fresh owner-checked attempt. An already issued HTTP/RPC cannot be retroactively unsent. Each loop refreshes its exact target every three seconds and keeps one action in flight. The leader API runtime coalesces identical chat/thread/action calls for two seconds, admits different Threads independently, and shares a real Telegram 429 `retry_after` fence across every Thread key in that chat. A pending-request count retains that shared state until every concurrent action settles, so completion of a faster peer cannot orphan a late 429; expired gates prune opportunistically and each gate family retains at most 256 active keys. Suppression never schedules a delayed retry. A failed typing action remains a structured diagnostic but cannot project `error` onto an otherwise healthy connected/leader/follower status. Assistant message start/update hooks still re-arm typing during Telegram-owned turns so transient provider/model errors do not leave a continuing run without activity feedback, and agent/session completion stops it.
+At every connected instance `agent_start`, the lifecycle binding starts Telegram's native `…typing` indicator in that instance's assigned target, whether the run came from Telegram, the local TUI, or an autonomous continuation such as Grow Loop. Terminal `Active` remains Telegram-turn-specific; the native indicator answers the separate question of whether the instance is doing agent work. Streaming keepalives reuse a valid typing owner with the same session generation, transport and target rather than revoking its pending HTTP/IPC action. Fresh context wrappers may reuse that owner within a proven generation; without generation evidence, context identity must match. Explicit queue dispatch and Telegram prompt handoff still replace the owner. Queue dispatch carries the queued turn's exact target into typing before `agent_start`, rather than reducing it to a chat ID. In Threaded Mode, missing or invalid Thread targets are refused before starting a loop or invoking the API; mode changes also invalidate a captured Classic chat-only loop. A rejected start never replaces an existing valid Thread loop. The starter also requires the captured Pi context and session generation to remain current at start, queued send, tick and late failure boundaries, even if the transport epoch is unchanged; replacing a context object in place cannot revive old activity. Message activity hooks capture generation across awaited preview work, and agent-start bindings recheck it before post-await activity/typing, so an obsolete finally or continuation cannot acquire replacement ownership. The typing sender carries its captured loop/context/generation/transport assertion as process-local call authority: direct API issuance rechecks it after queued work, and the follower caller rechecks it after registration waits and immediately before socket issuance without putting callbacks in IPC data. Automatic typing uses one HTTP attempt with no transport-family fallback or delayed replay, including forwarded calls; a future keepalive is a fresh owner-checked attempt. An already issued HTTP/RPC cannot be retroactively unsent. An ended loop supplies a process-local cancellation observation: only a typed API authority refusal with no underlying failure and paired with that proof is omitted from API failure logs, while the call still rejects without success or retry. If authority expires while handling a real HTTP/network failure, the authority error retains that failure as its cause and the API recorder logs the original failure. Active-owner refusals and HTTP/network failures keep their diagnostics; the cancellation observation never crosses IPC. Each loop refreshes its exact target every three seconds and keeps one action in flight. The leader API runtime coalesces identical chat/thread/action calls for two seconds, admits different Threads independently, and shares a real Telegram 429 `retry_after` fence across every Thread key in that chat. A pending-request count retains that shared state until every concurrent action settles, so completion of a faster peer cannot orphan a late 429; expired gates prune opportunistically and each gate family retains at most 256 active keys. Suppression never schedules a delayed retry. A failed typing action remains a structured diagnostic but cannot project `error` onto an otherwise healthy connected/leader/follower status. Assistant message start/update hooks still re-arm typing during Telegram-owned turns so transient provider/model errors do not leave a continuing run without activity feedback, and agent/session completion stops it.
 
 ### Rendering And Delivery
 
@@ -714,14 +714,14 @@ Outbound files staged during an active Telegram turn are delivered after that tu
 
 The channel-post journal records only this agent path's own publication intent. `prepare` is exact and idempotent; `beginPublication` durably changes one prepared operation to outcome-unknown before any future non-idempotent send; only `confirmPublished` records the returned numeric channel/message identity. A retry never regains issuance from outcome-unknown or published state. The store validates profile and token fingerprint, refuses malformed/duplicate/over-capacity state, and lists newest retained records without claiming Telegram history. The public-`@username` direct-leader sender now uses the tool-call ID to prepare and begin this journal transition before `sendRichMessage`, then records the returned numeric channel/message identity plus bounded username/title observed by `getChat`. Retained outcome-unknown state refuses automatic replay. Bounded agent-facing listing is available locally. Exact edit/delete journal transitions fence each tool-call mutation as outcome-unknown before direct-leader `editMessageText` or `deleteMessage`, and require the same mutation ID to confirm edited or deleted state. Numeric-channel publication requires explicit `channel: true`; direct-leader `getChat` must prove the exact negative ID and channel type before issuance, and the send response must preserve that identity. Cross-process regressions prove one winner for concurrent publication/edit/delete issuance and no restart regrant. Reads fail closed before parsing links, foreign/loose files, unsupported no-follow platforms, identity races, or oversized input. No legacy post schema is migrated: absent state starts empty and unknown versions/fields fail closed. The 0.44 downgrade checker leaves this inert journal untouched because old code cannot issue its effects. Only an explicit successful list returns retained authored Markdown. Channel publication/list/mutation failures and runtime events use fixed messages without retained content, token, path, or arbitrary transport detail. Production-helper regressions model a lost successful caller ACK and an ambiguous send response: the same operation returns retained success or refuses outcome-unknown without a second transport call. The retry uses a freshly opened replacement store, proving durable behavior across helper replacement/restart. A native entrypoint regression disconnects/reconnects direct ownership and proves both retained success and ambiguous outcome avoid a second `sendRichMessage`. Sender-rights and live rollout evidence remain separate 0.45.0 work. Channel media posts upload one local `.jpg`/`.jpeg`/`.png`/`.webp` photo or `.mp4` video through the multipart transport with `text` as the HTML caption; kind, byte size (photo ≤ 10 MiB, video ≤ 50 MiB), and 1024 visible caption characters are validated before issuance, and unsupported types or albums are rejected rather than downgraded to links. The journal binds the inspected kind/file name/byte size/SHA-256 media identity and caption, so duplicate requests and lost acknowledgements never re-upload. A media-post edit replaces the caption through `editMessageCaption` with the same Markdown-to-HTML rendering, where `||spoiler||` now renders as `<tg-spoiler>`.
 
-Assistant-authored final-message actions use hidden top-level comments, with an additional fenced wrapper for in-body buttons:
+Assistant-authored final-message actions use hidden HTML comments, with an additional fenced wrapper for in-body buttons:
 
 - `telegram_voice` accepts one positional compact action cell or JSON object and creates one voice artifact through configured outbound handlers, programmatic voice handlers, or registered synthesis providers.
 - `telegram_button` accepts a JSON object, adaptive JSON/CML matrix, or positional Compact Matrix Literal. Named JSON objects and positional cells may coexist, with commas optional only between completed matrix or row elements. Each top-level cell creates one full-width row, while a nested row groups buttons horizontally without an artificial parser-width cap; every callback enqueues its configured prompt text as a normal Telegram prompt turn. The JSON-first grammar, positional trim/escape rules, atomic rejection, and renderer-owned width policy are specified in [Adaptive Button Literal](./compact-matrix-literal.md).
 
-Standalone column-zero triple-backtick `telegram_button` blocks reuse the same cell/matrix grammar and callback store, including adjacent complete cells and matrices whose normalized rows concatenate in source order, and compile to native Rich Markdown button rows between paragraphs. Rendering validates each complete block before registering any callbacks, escapes label text, preserves disabled cells, and leaves larger enclosing fences literal. Previews hide complete and unfinished action fences. HTML mode projects those controls into the footer. In-body callbacks acknowledge without rewriting the Rich message; selected-style highlighting remains footer-only.
+Standalone `telegram_button` fenced blocks reuse the same cell/matrix grammar and callback store, including adjacent complete cells and matrices whose normalized rows concatenate in source order, and compile to native Rich Markdown button rows between paragraphs. Rendering validates each complete block before registering any callbacks, escapes label text, preserves disabled cells, and leaves enclosing fenced examples literal. Opening and closing lines allow spaces/tabs; openings accept three or more backticks or tildes, optional whitespace before the exact `telegram_button` name, and trailing whitespace. Closures must use the same marker and at least the opening length, with no other text. Previews hide complete and unfinished action fences. HTML mode projects those controls into the footer. In-body callbacks acknowledge without rewriting the Rich message; selected-style highlighting remains footer-only.
 
-Action recognition remains restricted to top-level column-zero comments and exact-name button fences so nested examples cannot trigger voice, buttons, or callbacks. The Telegram surface independently strips every complete assistant-authored HTML comment from previews and final delivery regardless of Markdown position or comment owner; an unclosed comment is withheld through the remaining tail, and a comment-only result sends no text message. Pi's terminal transcript and model context remain unchanged.
+Complete HTML action comments activate solely by their delimiters and accepted payload, independent of whitespace, adjacent text, lists, quotes or code fences. Same-line comments are independent. Escape the opening delimiter as `&lt;!--` to show a literal example; backticks and backslashes do not disable an action comment. Exact-name button fences retain their separate top-level recognition rules. The Telegram surface independently strips every complete assistant-authored HTML comment from previews and final delivery regardless of Markdown position or comment owner; an unclosed comment is withheld through the remaining tail, and a comment-only result sends no text message. Pi's terminal transcript and model context remain unchanged.
 
 Unknown callback data outside owned prefixes is forwarded as `[callback] <data>` only after built-in and extension handlers decline it.
 

package/node_modules/@llblab/pi-telegram/docs/compact-matrix-literal.md

@@ -154,7 +154,7 @@ For `telegram_button` hidden comments and fenced blocks:
 - Nested rows become horizontal keyboard rows; horizontal intent still requires the explicit nested array.
 - Invalid payloads are stripped with their recognized action comment and register no callbacks.
 
-The wrapper selects placement without changing cell semantics. A hidden `telegram_button` HTML comment builds the footer keyboard. A standalone column-zero fenced block opened by exactly three backticks plus `telegram_button` renders rows between paragraphs in Native Rich Markdown. A singleton JSON/CML object needs no array in either wrapper. Fenced content must be one complete group sequence without trailing envelope text; any invalid group rejects the entire block before callback registration. Larger outer fences and ordinary code blocks remain literal examples; unclosed action fences are withheld. Native Rich rows support at most eight buttons and must fit one message chunk; these are renderer constraints, not grammar limits. HTML compatibility places fenced controls in the footer. See [Outbound](./outbound.md) for delivery and callback behavior.
+The wrapper selects placement without changing cell semantics. A hidden `telegram_button` HTML comment builds the footer keyboard. A standalone fenced block opened by at least three backticks or tildes plus the exact name `telegram_button` renders rows between paragraphs in Native Rich Markdown. Delimiter lines accept horizontal indentation, optional whitespace before the name, and trailing spaces/tabs. Close on a separate line using the same marker and at least the opening length, with no other text. Enclosing code fences keep button-block examples literal. A singleton JSON/CML object needs no array in either wrapper. Fenced content must be one complete group sequence without trailing envelope text; any invalid group rejects the entire block before callback registration. Larger outer fences and ordinary code blocks remain literal examples; unclosed action fences are withheld. Native Rich rows support at most eight buttons and must fit one message chunk; these are renderer constraints, not grammar limits. HTML compatibility places fenced controls in the footer. See [Outbound](./outbound.md) for delivery and callback behavior.
 
 ````markdown
 Description.