pi-telegram-plus 0.0.1 → 0.0.3

package/lib/markdown.ts

@@ -11,7 +11,14 @@ interface TelegramRendererContext {
 
 function inlineFromTokens(this: TelegramRendererContext, tokens?: unknown[], fallback = ""): string {
   if (Array.isArray(tokens) && tokens.length > 0) {
-    return this.parser.parseInline(tokens as unknown[]);
+    // Temporarily disable \\n appending since this is inline context
+    const prev = _textAppendNewline;
+    _textAppendNewline = false;
+    try {
+      return this.parser.parseInline(tokens as unknown[]);
+    } finally {
+      _textAppendNewline = prev;
+    }
   }
   return escapeHtml(fallback);
 }
@@ -23,13 +30,258 @@ function blockFromTokens(this: TelegramRendererContext, tokens?: unknown[], fall
   return escapeHtml(fallback);
 }
 
+/**
+ * Calculate visible width of text in a monospace environment.
+ * ASCII = 1, CJK / fullwidth / emoji = 2.
+ */
+function visibleWidth(text: string): number {
+  let width = 0;
+  for (const char of text) {
+    const code = char.codePointAt(0)!;
+    if (code <= 0x1f || (code >= 0x7f && code <= 0x9f)) continue;
+    if (
+      (code >= 0x2e80 && code <= 0x9fff) ||   // CJK, Yi, Hangul syllables
+      (code >= 0xac00 && code <= 0xd7af) ||   // Hangul
+      (code >= 0xf900 && code <= 0xfaff) ||   // CJK compatibility
+      (code >= 0xfe30 && code <= 0xfe6f) ||   // CJK compat forms
+      (code >= 0xff01 && code <= 0xff60) ||   // fullwidth forms
+      (code >= 0xffe0 && code <= 0xffe6) ||   // fullwidth signs
+      (code >= 0x1f000 && code <= 0x1f9ff) || // emoji
+      code >= 0x20000                          // CJK extension B
+    ) {
+      width += 2;
+    } else {
+      width += 1;
+    }
+  }
+  return width;
+}
+
+/** Strip HTML tags for visible width calculation. */
+function stripHtmlTags(html: string): string {
+  return html.replace(/<[^>]+>/g, "");
+}
+
+/**
+ * Pad cell text (which may contain HTML tags) to the given visible width.
+ * Optionally wraps the whole cell in <b> for header styling.
+ */
+function padCell(text: string, width: number, bold = false): string {
+  const currentWidth = visibleWidth(stripHtmlTags(text));
+  const padding = Math.max(0, width - currentWidth);
+  // Only wrap in <b> if the text doesn't already start with <b>
+  const cell = bold && !text.startsWith("<b>") ? `<b>${text}</b>` : text;
+  return cell + " ".repeat(padding);
+}
+
+/** True if text contains only printable ASCII (width is unambiguous = 1/char). */
+function isAscii(text: string): boolean {
+  return /^[\x20-\x7e]*$/.test(text);
+}
+
+/** Collapse newlines inside a table cell so each row renders as one line. */
+function sanitizeCellHtml(html: string): string {
+  return html.replace(/\n+/g, " ").trim();
+}
+
+/** Wrap inline HTML in <b> unless it already starts with one (avoids <b><b>). */
+function wrapBold(html: string): string {
+  return html && !html.startsWith("<b>") ? `<b>${html}</b>` : html;
+}
+
+// ── Table strategies (mobile-first) ─────────────────────────────────────────
+// Telegram has no <table>; these three layouts trade off density vs. mobile
+// readability. See PR-1c plan: card (default) / box (narrow ASCII) / transpose (wide).
+
+/** Box-drawing grid in <pre> — plain text only (no inline tags inside <pre>). */
+function renderBoxTable(headerText: string[], rowsText: string[][], colWidths: number[]): string {
+  const lines: string[] = [];
+  lines.push(`┌─${colWidths.map((w) => "─".repeat(w)).join("─┬─")}─┐`);
+  lines.push(`│ ${headerText.map((h, i) => padCell(h, colWidths[i])).join(" │ ")} │`);
+  lines.push(`├─${colWidths.map((w) => "─".repeat(w)).join("─┼─")}─┤`);
+  for (const row of rowsText) {
+    const cells = colWidths.map((_, i) => padCell(i < row.length ? row[i] : "", colWidths[i]));
+    lines.push(`│ ${cells.join(" │ ")} │`);
+  }
+  lines.push(`└─${colWidths.map((w) => "─".repeat(w)).join("─┴─")}─┘`);
+  return `<pre>${lines.join("\n")}</pre>\n`;
+}
+
+/** Card-style: bold header row, bold first column (primary key), 2-space sep. */
+function renderCardTable(headerHtml: string[], rowsHtml: string[][]): string {
+  const lines: string[] = [];
+  lines.push(headerHtml.map((h) => wrapBold(h)).join("  "));
+  lines.push("──");
+  for (const row of rowsHtml) {
+    const cells = headerHtml.map((_, i) => (i < row.length ? row[i] : ""));
+    const first = cells[0] ? wrapBold(cells[0]) : "";
+    const rest = cells.slice(1).filter((c) => c.length > 0).join("  ");
+    lines.push([first, rest].filter(Boolean).join("  "));
+  }
+  return lines.join("\n") + "\n\n";
+}
+
+/** Transposed: each row becomes a block (first col = bold title, rest = H: v). */
+function renderTransposedTable(headerHtml: string[], rowsHtml: string[][]): string {
+  // Each data row becomes a block of `label: value` lines (all columns
+  // included, labels bolded), blocks separated by a blank line. No orphaned
+  // title / no indent / no heavy separator — the most mobile-readable layout
+  // for wide tables (many columns, few rows).
+  const blocks: string[] = [];
+  for (const row of rowsHtml) {
+    const cells = headerHtml.map((_, i) => (i < row.length ? row[i] : ""));
+    const lines: string[] = [];
+    for (let i = 0; i < headerHtml.length; i++) {
+      const label = wrapBold(headerHtml[i]) || `col${i + 1}`;
+      lines.push(`${label}: ${cells[i]}`);
+    }
+    blocks.push(lines.join("\n"));
+  }
+  return blocks.join("\n\n") + "\n\n";
+}
+
+// ── Pseudo-table protection ──────────────────────────────────────────────────
+// Detects aligned pipe text that looks like a markdown table but has no
+// `| --- |` separator row (e.g. raw `ls`/SQL/CSV-style output an agent pasted
+// as prose). marked would tokenize such text as a paragraph and the pipes /
+// column alignment would be lost in Telegram's proportional font. We wrap the
+// run in a fenced code block so it renders as <pre><code> (monospace, aligned).
+
+function isTableSeparator(line: string): boolean {
+  // A markdown table separator row: only spaces, dashes, colons, pipes; must
+  // contain at least one dash.
+  return /^\s*\|?[\s:|-]*\|?\s*$/.test(line) && line.includes("-");
+}
+
+/** A markdown table row/header line: starts with a pipe (our agent always emits `| ... |`). */
+function isTableRow(line: string): boolean {
+  return /^\s*\|/.test(line);
+}
+
+function isPseudoTableRow(line: string): boolean {
+  if (!line.includes("|")) return false;
+  const pipeCount = (line.match(/\|/g) || []).length;
+  if (pipeCount < 2) return false;
+  // Must have some real content (not a separator-only line).
+  return line.replace(/[\s|:-]/g, "").length > 0;
+}
+
+/** Count consecutive pseudo-table rows at `start`; 0 if it's a real table. */
+function pseudoTableRun(lines: string[], start: number, inRealTable: Uint8Array): number {
+  if (inRealTable[start]) return 0;
+  if (!isPseudoTableRow(lines[start])) return 0;
+  // If the next line is a markdown table separator, this is a real table —
+  // leave it for marked's table tokenizer.
+  if (start + 1 < lines.length && isTableSeparator(lines[start + 1])) return 0;
+  let n = 1;
+  while (start + n < lines.length && inRealTable[start + n] === 0 && isPseudoTableRow(lines[start + n])) n++;
+  return n >= 2 ? n : 0;
+}
+
+/**
+ * Mark every line that belongs to a real markdown table (header + separator +
+ * its consecutive data rows). These must be left for marked's table tokenizer;
+ * otherwise the data rows after the first would be mis-detected as a
+ * pseudo-table (their preceding line is a data row, not a separator).
+ */
+function markRealTableLines(lines: string[]): Uint8Array {
+  const flags = new Uint8Array(lines.length);
+  for (let i = 0; i + 1 < lines.length; i++) {
+    if (isTableRow(lines[i]) && isTableSeparator(lines[i + 1])) {
+      flags[i] = 1;        // header
+      flags[i + 1] = 1;     // separator
+      let j = i + 2;
+      while (j < lines.length && isTableRow(lines[j])) { flags[j] = 1; j++; }
+    }
+  }
+  return flags;
+}
+
+/**
+ * Wrap pseudo-table runs (outside code fences) in fenced code blocks.
+ * Code-fence state is tracked so content already inside ``` is untouched.
+ */
+function protectPseudoTables(md: string): string {
+  const lines = md.split("\n");
+  const inRealTable = markRealTableLines(lines);
+  const out: string[] = [];
+  let inFence = false;
+  let fenceChar = "";
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i];
+    const fence = /^\s*(`{3,}|~{3,})/.exec(line);
+    if (fence) {
+      const ch = fence[1][0];
+      if (!inFence) { inFence = true; fenceChar = ch; }
+      else if (ch === fenceChar) { inFence = false; fenceChar = ""; }
+      out.push(line);
+      i++;
+      continue;
+    }
+    if (inFence) { out.push(line); i++; continue; }
+    const run = pseudoTableRun(lines, i, inRealTable);
+    if (run > 1) {
+      out.push("```");
+      for (let j = i; j < i + run; j++) out.push(lines[j]);
+      out.push("```");
+      i += run;
+      continue;
+    }
+    out.push(line);
+    i++;
+  }
+  return out.join("\n");
+}
+
+/**
+ * Track list nesting depth for proper indentation.
+ * Resets per top-level markdownToTelegramHtml call.
+ */
+let _listDepth = 0;
+
+/**
+ * Flag: when true, the text renderer appends \\n after content.
+ * True during block-level parse (parser.parse), false during inline
+ * (parser.parseInline) so inline text tokens don't get spurious newlines.
+ */
+let _textAppendNewline = true;
+
 const renderer = {
-  heading(this: TelegramRendererContext, { tokens }: Tokens.Heading): string {
-    return `<b>${inlineFromTokens.call(this, tokens)}</b>\n`;
+  text(this: TelegramRendererContext, token: Tokens.Text | Tokens.Escape): string {
+    if ('tokens' in token && token.tokens && token.tokens.length > 0) {
+      // Text with nested inline tokens — parse inline (disable \\n for nested),
+      // then add \\n only if we are at block level
+      const prev = _textAppendNewline;
+      _textAppendNewline = false;
+      try {
+        return this.parser.parseInline(token.tokens as unknown[]) + (prev ? '\n' : '');
+      } finally {
+        _textAppendNewline = prev;
+      }
+    }
+    // Plain text / escape token
+    return escapeHtml(token.text) + (_textAppendNewline ? '\n' : '');
+  },
+
+  checkbox(this: TelegramRendererContext): string {
+    // Suppress default <input> rendering; custom [x]/[ ] marker is added by list renderer
+    return "";
+  },
+
+
+  heading(this: TelegramRendererContext, token: Tokens.Heading): string {
+    const content = inlineFromTokens.call(this, token.tokens);
+    // Telegram has a single font/size, so hierarchy is conveyed by bold + a
+    // blank line. Drop the pi-tui `###` prefix (noise on mobile) and <u>
+    // (which reads like a link). Uniform <b> + trailing blank line for all depths.
+    return `<b>${content}</b>\n\n`;
   },
 
   paragraph(this: TelegramRendererContext, { tokens }: Tokens.Paragraph): string {
-    return `${inlineFromTokens.call(this, tokens)}\n`;
+    // Double newline after each paragraph so mobile readers get visual
+    // breathing room between paragraphs (single \n reads as run-together).
+    return `${inlineFromTokens.call(this, tokens)}\n\n`;
   },
 
   strong(this: TelegramRendererContext, { tokens }: Tokens.Strong): string {
@@ -49,41 +301,150 @@ const renderer = {
   },
 
   code(this: TelegramRendererContext, { text, lang }: Tokens.Code): string {
-    const language = lang ? ` class="language-${escapeHtml(lang)}"` : "";
-    return `<pre><code${language}>${escapeHtml(text)}\n</code></pre>`;
+    // Drop the literal ``` fences (visual noise + wasted bytes) and emit the
+    // language as a Telegram-recognized `class="language-xxx"` attribute.
+    // Telegram validates the class value against [a-zA-Z][a-zA-Z0-9_-]*.
+    const codeContent = escapeHtml(text.replace(/\n+$/, ""));
+    const safeLang = (lang || "").trim().toLowerCase().replace(/[^a-z0-9_-]/g, "");
+    const langAttr = safeLang ? ` class="language-${safeLang}"` : "";
+    return `<pre><code${langAttr}>${codeContent}\n</code></pre>\n`;
   },
 
   table(this: TelegramRendererContext, token: Tokens.Table): string {
-    const rows: string[] = [];
-    if (token.header.length > 0) {
-      rows.push(token.header.map((c) => inlineFromTokens.call(this, c.tokens, c.text)).join(" | "));
-      rows.push(token.header.map(() => "---").join("-+-"));
+    const numCols = token.header.length;
+    if (numCols === 0) return "";
+
+    // Pre-render every cell to inline HTML (card / transpose strategies).
+    // Multi-line cell content is collapsed to a single line so each table
+    // row stays one visual line that wraps naturally on mobile.
+    const headerHtml = token.header.map((c) =>
+      sanitizeCellHtml(inlineFromTokens.call(this, c.tokens, c.text)));
+    const rowsHtml = token.rows.map((row) =>
+      row.map((c) => sanitizeCellHtml(inlineFromTokens.call(this, c.tokens, c.text))),
+    );
+    // Plain escaped text for box-drawing (Telegram rejects <b>/<code> nested
+    // inside <pre>, so box cells must be tag-free).
+    const headerText = token.header.map((c) => escapeHtml(c.text));
+    const rowsText = token.rows.map((row) => row.map((c) => escapeHtml(c.text)));
+
+    // Natural column widths for strategy selection + box layout.
+    const colWidths: number[] = [];
+    let allAscii = true;
+    for (let i = 0; i < numCols; i++) {
+      let maxW = Math.max(1, visibleWidth(stripHtmlTags(headerHtml[i])));
+      for (const row of rowsHtml) {
+        if (i < row.length) {
+          const w = visibleWidth(stripHtmlTags(row[i]));
+          if (w > maxW) maxW = w;
+          if (!isAscii(stripHtmlTags(row[i]))) allAscii = false;
+        }
+      }
+      if (!isAscii(stripHtmlTags(headerHtml[i]))) allAscii = false;
+      colWidths.push(maxW);
     }
-    for (const row of token.rows) {
-      rows.push(row.map((c) => inlineFromTokens.call(this, c.tokens, c.text)).join(" | "));
+    const naturalWidth = colWidths.reduce((a, b) => a + b, 0) + 3 * numCols + 1;
+
+    // T4: narrow 2-column all-ASCII table that fits a mobile screen -> box-drawing.
+    // ASCII width is unambiguous (1 char = 1 cell) in Telegram's monospace font,
+    // so the <pre> grid aligns reliably. Bound by total natural width (~40
+    // chars fits an iPhone portrait <pre>) so normal command/desc tables qualify;
+    // longer cells fall through to card which wraps naturally.
+    if (numCols === 2 && allAscii && naturalWidth <= 40) {
+      return renderBoxTable(headerText, rowsText, colWidths);
     }
-    return `<pre>${rows.join("\n")}</pre>\n`;
+    // T5: wide table -> transpose to vertical cards (one block per row), so a
+    //    many-column table never forces horizontal scroll on mobile.
+    if (numCols > 4 || naturalWidth > 60) {
+      return renderTransposedTable(headerHtml, rowsHtml);
+    }
+    // T1 default: card-style - bold header + bold first column (primary key),
+    // 2-space column separator, wraps naturally, never overflows.
+    return renderCardTable(headerHtml, rowsHtml);
   },
 
   list(this: TelegramRendererContext, token: Tokens.List): string {
-    const start = typeof token.start === "number" ? token.start : 1;
-    const lines = token.items.map((item, index) => {
-      const bullet = token.ordered ? `${start + index}. ` : "• ";
-      return bullet + blockFromTokens.call(this, item.tokens, item.text);
-    });
-    return lines.join("\n") + "\n";
+    _listDepth++;
+    try {
+      const start = typeof token.start === "number" ? token.start : 1;
+      // Cap indent growth at depth 2: deeper levels add no base indent of
+      // their own and switch to a `› ` bullet (unordered), so deep nesting
+      // grows only ~2 cols/level (parent continuation indent) instead of 4.
+      // Ordered lists keep their numbering at every depth.
+      const baseIndent = _listDepth <= 2
+        ? "  ".repeat(Math.max(0, _listDepth - 1))
+        : "";
+      const lines = token.items.map((item, index) => {
+        const bullet = token.ordered
+          ? `${start + index}. `
+          : (_listDepth >= 3 ? "› " : "- ");
+        const taskMarker = item.task ? `[${item.checked ? "x" : " "}] ` : "";
+        const marker = bullet + taskMarker;
+        const content = blockFromTokens.call(this, item.tokens, item.text);
+        const contentLines = content.trimEnd().split("\n");
+        const contIndent = " ".repeat(visibleWidth(marker));
+        return contentLines.map((line, i) => {
+          const prefix = i === 0 ? baseIndent + marker : baseIndent + contIndent;
+          return prefix + line;
+        }).join("\n");
+      });
+      return lines.join("\n") + "\n";
+    } finally {
+      _listDepth--;
+    }
   },
 
   listitem(this: TelegramRendererContext, token: Tokens.ListItem): string {
+    // Used when a list item contains block-level children (e.g. nested lists).
+    // blockFromTokens will re-enter `list` for nested lists via parser.parse().
     return blockFromTokens.call(this, token.tokens, token.text);
   },
 
   blockquote(this: TelegramRendererContext, { tokens }: Tokens.Blockquote): string {
-    return `<blockquote>${this.parser.parse(tokens as unknown[])}</blockquote>`;
+    const content = this.parser.parse(tokens as unknown[]).trim();
+    // Only wrap in <i> if content doesn't start with a block-level / inline-format
+    // tag. Wrapping `<b>`/`<pre>`/`<blockquote>` in `<i>` produces nesting that
+    // Telegram rejects (bad request), which forces a plain-text fallback for the
+    // ENTIRE message chunk — silently dropping all formatting.
+    const shouldItalic = !/^<blockquote|^<pre|^<ul|^<ol|^<table|^<b|^<i|^<a/i.test(content);
+    const wrapped = shouldItalic ? `<i>${content}</i>` : content;
+    return `<blockquote>${wrapped}</blockquote>\n`;
+  },
+
+  hr(this: TelegramRendererContext): string {
+    // Slim separator: 3 fullwidth dashes, no <pre> (avoids the heavy
+    // monospace block that eats a full line on mobile).
+    return "━━━\n\n";
+  },
+
+  image(this: TelegramRendererContext, { href, text, title }: Tokens.Image): string {
+    const alt = text || "image";
+    if (href) return `🖼 <a href="${escapeAttr(href)}">${escapeHtml(alt)}</a>`;
+    if (title) return `🖼 ${escapeHtml(alt)}: ${escapeHtml(title)}`;
+    return `🖼 ${escapeHtml(alt)}`;
+  },
+
+  // ── Inline / passthrough tokens previously left to marked's default ──
+  // marked's default renderers emit attributes/constructs Telegram's HTML
+  // parser rejects (`title=` on <a>, `<br>`, raw HTML, unescaped `&` in href),
+  // which causes the whole message chunk to fall back to plain text.
+  // Override each so the output is always valid Telegram HTML.
+
+  link(this: TelegramRendererContext, { href, tokens }: Tokens.Link): string {
+    const safeHref = escapeAttr(href);
+    if (!safeHref) return inlineFromTokens.call(this, tokens);
+    return `<a href="${safeHref}">${inlineFromTokens.call(this, tokens)}</a>`;
+  },
+
+  html(this: TelegramRendererContext, token: Tokens.HTML | Tokens.Tag): string {
+    // pi-tui renders raw HTML as plain text; mirror that here instead of
+    // letting it pass through and trip Telegram's parser.
+    const raw = "raw" in token && typeof token.raw === "string" ? token.raw : "";
+    return escapeHtml(raw.trim());
   },
 
-  image(this: TelegramRendererContext, { text, title }: Tokens.Image): string {
-    return title ? `[${text}: ${title}]` : `[${text}]`;
+  br(this: TelegramRendererContext): string {
+    // Telegram HTML has no <br>; a literal newline is the line break.
+    return "\n";
   },
 };
 
@@ -95,7 +456,15 @@ marked.use({ renderer });
  * formatting within the Telegram supported subset.
  */
 export function markdownToTelegramHtml(markdown: string): string {
-  return (marked.parse(markdown, { async: false }) as string).replace(/\n+$/, "");
+  _listDepth = 0;
+  _textAppendNewline = true;
+  // Pre-scan: wrap "pseudo-tables" (aligned pipe text that looks like a
+  // markdown table but lacks the `| --- |` separator row) in fenced code so
+  // marked renders them as <pre><code> — preserving column alignment in
+  // Telegram's monospace font instead of mangling pipes in a proportional-font
+  // paragraph. Real markdown tables (with a separator) are left for marked.
+  const protected_ = protectPseudoTables(markdown);
+  return (marked.parse(protected_, { async: false }) as string).replace(/\n+$/, "");
 }
 
 export function escapeAttr(text: string): string {

package/lib/menu-commands.ts

@@ -1,5 +1,8 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { setTelegramMyCommands } from "./telegram-api.ts";
+import { log } from "./logger.ts";
+
+const menuLog = log.child("menu-commands");
 
 const TELEGRAM_MENU_COMMANDS: Array<{ command: string; description: string }> = [
   // Keep the built-in pi commands in the same order as the TUI slash menu.
@@ -31,14 +34,15 @@ const TELEGRAM_MENU_COMMANDS: Array<{ command: string; description: string }> =
   { command: "thinking", description: "Show or change thinking level" },
   { command: "stop", description: "Stop the current agent turn" },
   { command: "debug", description: "Show debug information" },
+  { command: "status", description: "Show runtime snapshot (workspace, model, context, messages)" },
   // tg-* commands visible in the Telegram bot menu.
   // tg-bind-cwd / tg-unbind-cwd are workspace-management commands that
   // require local cwd context and do not belong in the bot command list.
-  { command: "tg-setup", description: "Configure Telegram bot token" },
-  { command: "tg-connect", description: "Enable/start Telegram connection" },
-  { command: "tg-disconnect", description: "Disable/stop Telegram connection" },
-  { command: "tg-config", description: "Configure Telegram message rendering" },
-  { command: "tg-list", description: "List Telegram bot bindings" },
+  { command: "tg_global_setup", description: "Configure global Telegram bot token" },
+  { command: "tg_global_connect", description: "Enable/start global Telegram bot" },
+  { command: "tg_global_disconnect", description: "Disable/stop global Telegram bot" },
+  { command: "tg_config", description: "Configure Telegram message rendering" },
+  { command: "tg_list", description: "List Telegram bot bindings" },
 ];
 
 const toTelegramCommandName = (name: string): string | undefined => {
@@ -68,5 +72,5 @@ export async function syncTelegramCommands(botToken: string | undefined, pi: Ext
   if (!botToken) return;
   try {
     await setTelegramMyCommands(botToken, buildTelegramMenuCommands(pi));
-  } catch { /* non-critical */ }
+  } catch (err) { menuLog.warn("syncTelegramCommands failed", { err }); }
 }

package/lib/polling.ts

@@ -4,6 +4,9 @@ import { join } from "node:path";
 import { getAgentDir } from "./config.ts";
 import { getTelegramUpdates } from "./telegram-api.ts";
 import type { TelegramConfig, TelegramUpdate } from "./types.ts";
+import { log } from "./logger.ts";
+
+const pollLog = log.child("polling");
 
 export type TelegramPollingRuntime = {
   start(): void;
@@ -42,7 +45,8 @@ function isPidAlive(pid: unknown): boolean {
   try {
     process.kill(pid, 0);
     return true;
-  } catch {
+  } catch (err) {
+    pollLog.debug("isPollingLockStale stat failed (treated as not stale)", { err });
     return false;
   }
 }
@@ -61,7 +65,8 @@ async function readPollingLockOwner(ownerPath: string): Promise<PollingLockOwner
       at: typeof owner.at === "string" ? owner.at : "",
       touchedAt: typeof owner.touchedAt === "string" ? owner.touchedAt : "",
     };
-  } catch {
+  } catch (err) {
+    pollLog.debug("readPollingLockOwner failed (treated as no owner)", { err });
     return undefined;
   }
 }
@@ -93,7 +98,7 @@ async function acquirePollingLock(token: string): Promise<{ owns: () => Promise<
 
   // Clean up stale lock if it exists.
   if (!await isPollingLockStale(lockPath)) return undefined;
-  await rm(lockPath, { recursive: true, force: true }).catch(() => undefined);
+  await rm(lockPath, { recursive: true, force: true }).catch(pollLog.swallow("debug", "rm stale polling lock failed", { lockPath }));
 
   // Create lock directory; if another process won, bail out.
   try {
@@ -110,7 +115,7 @@ async function acquirePollingLock(token: string): Promise<{ owns: () => Promise<
     await writeFile(tmpPath, ownerText(owner), { mode: 0o600, flag: "wx" });
   } catch (error) {
     // Another process's candidate won; clean up and bail.
-    await rm(tmpPath).catch(() => undefined);
+    await rm(tmpPath).catch(pollLog.swallow("debug", "rm polling candidate tmp failed", { tmpPath }));
     if ((error as NodeJS.ErrnoException).code === "EEXIST") return undefined;
     throw error;
   }
@@ -120,7 +125,7 @@ async function acquirePollingLock(token: string): Promise<{ owns: () => Promise<
     await nodeRename(tmpPath, ownerPath);
   } catch {
     // rename failed (e.g. cross-device or another process already wrote owner.json).
-    await rm(tmpPath).catch(() => undefined);
+    await rm(tmpPath).catch(pollLog.swallow("debug", "rm polling candidate tmp after rename failure", { tmpPath }));
     return undefined;
   }
 
@@ -129,7 +134,7 @@ async function acquirePollingLock(token: string): Promise<{ owns: () => Promise<
       const current = await readPollingLockOwner(ownerPath);
       if (current?.id !== owner.id) return;
       owner.touchedAt = new Date().toISOString();
-      await writeFile(ownerPath, ownerText(owner), { mode: 0o600 }).catch(() => undefined);
+      await writeFile(ownerPath, ownerText(owner), { mode: 0o600 }).catch(pollLog.swallow("warn", "polling lock touch write failed", { ownerPath }));
     })();
   }, POLL_LOCK_TOUCH_MS);
 
@@ -138,7 +143,7 @@ async function acquirePollingLock(token: string): Promise<{ owns: () => Promise<
     release: async () => {
       clearInterval(touch);
       const current = await readPollingLockOwner(ownerPath);
-      if (current?.id === owner.id) await rm(lockPath, { recursive: true, force: true }).catch(() => undefined);
+      if (current?.id === owner.id) await rm(lockPath, { recursive: true, force: true }).catch(pollLog.swallow("debug", "rm polling lock on release failed", { lockPath }));
     },
   };
 }
@@ -159,7 +164,7 @@ export function createTelegramPollingRuntime(deps: {
   const releasePollLock = async () => {
     const lock = pollLock;
     pollLock = undefined;
-    await lock?.release().catch(() => undefined);
+    await lock?.release().catch(pollLog.swallow("warn", "poll lock release failed"));
   };
 
   const ensurePollLock = async (token: string): Promise<boolean> => {