pi-telegram-plus 0.0.2 → 0.0.3

package/README.md

@@ -1,10 +1,6 @@
 # pi-telegram-plus
 
-<p>
-  <a href="https://www.npmjs.com/package/pi-telegram-plus"><img src="https://img.shields.io/npm/v/pi-telegram-plus?style=flat-square&logo=npm" alt="npm" /></a>
-  <a href="https://github.com/jalyfeng/pi-telegram-plus"><img src="https://img.shields.io/github/license/jalyfeng/pi-telegram-plus?style=flat-square" alt="license" /></a>
-  <img src="https://img.shields.io/badge/node-%3E%3D22.19.0-339933?style=flat-square&logo=node.js" alt="node" />
-</p>
+## Overview
 
 **Full Telegram control of [pi coding agent](https://github.com/earendil-works/pi-coding-agent) — commands, interactive UI, model/session management, file transfer, and real-time streaming output, all from Telegram.**
 
@@ -19,27 +15,15 @@
 - **Multi-instance safe** — file-based polling lock prevents multiple pi instances from racing on the same bot token
 - **Automatic reconnection** — exponential backoff on transient failures
 - **Bot command menu sync** — automatically syncs available commands to Telegram's BotMenu (up to 100 commands)
+- **Authorized user** — the first Telegram user to message the bot is auto-authorized and persisted; all other users are rejected (reset by removing the binding and re-setting up)
+- **TUI status line** — a `telegram+` indicator in the pi status bar shows connection state (connected / active / awaiting pairing / disconnected / not configured / error)
+- **Typing indicator** — sends `typing` chat-action pulses while a turn is active so the Telegram chat shows the bot is working
 
 ### 🎮 Full Session Control
-All pi session lifecycle commands available via Telegram:
-
-| Command | Description |
-|---------|-------------|
-| `/new` | Start a new session |
-| `/fork` | Fork from a previous user message |
-| `/clone` | Clone at a previous user message |
-| `/tree` | Navigate session tree |
-| `/resume` | Resume a previous session |
-| `/compact` | Compact session context |
-| `/name` | Set or show session name |
-| `/session` | Show session statistics |
+All pi session lifecycle commands are available via Telegram — start, fork, clone, navigate, resume, compact, rename, and inspect sessions. See **Session Control Commands** in the Usage Guide.
 
 ### 🧠 Model & Authentication Management
-- `/model` — View available models / switch current model via interactive selection
-- `/scoped-models` — Toggle scoped model sets
-- `/thinking` — Adjust thinking level (off/minimal/low/medium/high/xhigh)
-- `/login` — OAuth or API key authentication with full interactive flow
-- `/logout` — Remove stored credentials
+Switch the current model, toggle scoped model sets, adjust the thinking level, and complete OAuth or API key authentication with full interactive flows — all from Telegram. See **Model & Authentication Commands** in the Usage Guide.
 
 ### 📨 Message Modes
 Two modes for handling incoming messages while the agent is running:
@@ -56,12 +40,31 @@ Full interactive UI components built on inline keyboards:
 - **InputSecret** — same as Input, but the prompt message is auto-deleted after reply to protect sensitive data
 - **Select** — paginated option list with Prev/Next navigation
 - **Editor** — multi-line text input prompt
+- **Custom (third-party)** — `ctx.ui.custom(factory)` dialogs from extensions like [`@capyup/pi-goal`](https://www.npmjs.com/package/@capyup/pi-goal) are bridged to inline buttons. See **Third-party Dialog Support** below.
+
+### 🧩 Third-party Dialog Support
+
+Third-party extensions that use `ctx.ui.custom(factory)` (such as [`@capyup/pi-goal`](https://www.npmjs.com/package/@capyup/pi-goal))
+are bridged to Telegram inline buttons so remote turns can interact with them:
+
+| Scenario | Telegram behavior |
+|----------|-------------------|
+| **pi-goal draft confirmation** (`propose_goal_draft` → `showProposalDialog`) | Shows ✅ Confirm / 💬 Continue chatting buttons. Confirm creates the goal; Continue lets the agent keep refining; `/stop` or timeout cancels. |
+| **pi-goal `goal_question`** (single question) | Shows the question text, option buttons (paginated if needed) as toggle buttons (☐/☑, multi-select), a ✏️ Type answer button for free-text entry, and Cancel. A ✓ Submit button appears once at least one option is selected (or a custom answer is given); the selected options are joined into a single string answer. Free-text entry finalizes immediately. |
+| **pi-goal `goal_questionnaire`** (multi-question) | Drives the opaque questionnaire component: cycles tabs to extract every question, then presents one question at a time with option buttons as multi-select toggles (☐/☑), ◀ Tab / Tab ▶ navigation between questions (no forced auto-advance on option pick), ✏️ Type for free-text entry, and Cancel. A ✓ Submit button only appears once every question is answered; before that the message shows a `Still to answer: …` placeholder. Per-question selections are joined into single-string answers. Falls back to a `cancelled` degrade only if the component lacks the expected `handleInput`/`render` API. |
+| **Unknown `custom()` components** | Auto-dismissed with a ⚠️ notification and a `cancelled` result, so the agent continues gracefully (never hangs or throws). |
+
+**Interactive modals are Telegram-only during a Telegram turn.** Interactive modals (confirm, select, input, editor, custom) are bridged to Telegram inline buttons for the remote user and are NOT also rendered in the local TUI. `ExtensionUIContext.custom` and the other modals expose no external cancel handle, so mirroring a modal into the TUI during a remote turn would leave the local TUI stuck at the dialog once the Telegram side resolves. Local TUI turns never enter the Telegram UI swap, so they keep using the real TUI UIContext and are completely unaffected. Persistent/stateful UI (goal widget, status line, working indicator, footer/header) is forwarded to the TUI base so the local TUI always shows accurate state. Editor operations (paste, set/get text) are no-ops during Telegram turns, so a remote turn never touches the local editor.
+
+> **Command-triggered turns are held to the end of the chain.** Commands like `/sisyphus` and `/goals` enqueue the agent turn fire-and-forget via `pi.sendUserMessage` and return immediately; the actual turn (and the `goal_question` / `goal_questionnaire` / `propose_goal_draft` dialogs it raises) runs afterward. The controller keeps the Telegram UI swap active across that enqueued turn and any pi-goal auto-continue chain (waiting for the agent to go idle through a small grace window), so every dialog in the chain bridges to Telegram instead of rendering to the local TUI. The hold is skipped when a local turn was already streaming, so it never hijacks an active local session.
 
 ### 🎨 Message Rendering
 - **Markdown → Telegram HTML** — Full conversion via `marked` (tables, code blocks, blockquotes, lists, inline formatting)
+- **Mobile-first table rendering** — box-drawing and card layouts with pseudo-table protection and header repetition across split chunks, so wide tables stay readable on phone screens
 - **Tool execution rendering** — Configurable level (`hidden` / `brief` / `full`) for tool call visibility
 - **Thinking rendering** — Configurable level (`hidden` / `brief` / `full`) for agent thinking blocks
 - **Output splitting** — Safe UTF-8-aware splitting at Telegram's 4096-byte limit
+- **Oversized code blocks** — automatically sent as downloadable files instead of being split across many `<pre>` messages
 - **Image output** — Automatically sends agent-generated images as Telegram photos
 
 ### 📎 File Attachments
@@ -78,19 +81,58 @@ Full interactive UI components built on inline keyboards:
 - Reports saved paths back to the user
 - Handles name sanitization and deduplication
 
-### ⚙️ Telegram-Specific Commands
+---
+
+## Usage Guide
+
+### Session Control Commands
+
+| Command | Description |
+|---------|-------------|
+| `/new` | Start a new session |
+| `/fork` | Fork from a previous user message |
+| `/clone` | Clone at a previous user message |
+| `/tree` | Navigate session tree |
+| `/resume` | Resume a previous session |
+| `/compact` | Compact session context |
+| `/name` | Set or show session name |
+| `/session` | Show session statistics |
+
+### Model & Authentication Commands
+
+- `/model` — View available models / switch current model via interactive selection
+- `/scoped-models` — Toggle scoped model sets
+- `/thinking` — Adjust thinking level (off/minimal/low/medium/high/xhigh)
+- `/login` — OAuth or API key authentication with full interactive flow
+- `/logout` — Remove stored credentials
+
+### Telegram Connection Commands
+
+**Global scope** (a single bot token shared across all workspaces):
+
+| Command | Description |
+|---------|-------------|
+| `/tg-global-setup` | Configure the global bot token and connect (first-time setup) |
+| `/tg-global-connect` | Enable / start the global bot connection |
+| `/tg-global-disconnect` | Disable / stop the global bot (keeps the token) |
+
+**Workspace scope** (per-directory bot token; overrides global when bound):
+
+| Command | Description |
+|---------|-------------|
+| `/tg-bind-cwd` | Bind the current directory to its own bot token |
+| `/tg-cwd-connect` | Enable the bot for the current directory |
+| `/tg-cwd-disconnect` | Disable the bot for the current directory |
+| `/tg-unbind-cwd` | Remove the current directory's bot binding |
+| `/tg-list` | List all bot bindings (global + workspace) |
+
+**Shared:**
 
 | Command | Description |
 |---------|-------------|
-| `/tg-setup` | Configure Telegram bot token (first-time setup) |
-| `/tg-connect` | Enable / start Telegram connection |
-| `/tg-disconnect` | Disable / stop connection (keeps token) |
 | `/tg-config` | Configure rendering levels and message mode |
-| `/tg-bind-cwd` | Bind a workspace directory to a separate bot token |
-| `/tg-unbind-cwd` | Remove workspace bot binding |
-| `/tg-list` | List all Telegram bot bindings |
 
-### 🔧 Utility Commands
+### Utility Commands
 
 | Command | Description |
 |---------|-------------|
@@ -111,213 +153,39 @@ Full interactive UI components built on inline keyboards:
 
 ---
 
-## Installation
-
-### Prerequisites
-
-- Node.js >= 22.19.0
-- [pi coding agent](https://github.com/earendil-works/pi-coding-agent) installed globally
-- A Telegram bot token from [@BotFather](https://t.me/BotFather)
-
-### Installation
-
-**Install via npm (recommended):**
-
-```bash
-pi install npm:pi-telegram-plus
-```
-
-**Or install from source:**
-
-```bash
-git clone https://github.com/jalyfeng/pi-telegram-plus.git
-cd pi-telegram-plus
-npm install
-pi packages add .
-```
-
-3. **Start pi and configure your Telegram bot:**
-
-```bash
-pi
-```
-
-Inside pi, run:
-
-```
-/tg-setup
-```
-
-Paste your bot token when prompted. The bot will connect automatically.
-
-> **Note:** On first message from any user, pi-telegram-plus automatically authorizes that user ID. Only that user can control the bot afterward.
-
----
-
-## Configuration
-
-### Per-Workspace Bot Tokens
-
-You can bind different bot tokens to different directories:
-
-```
-/tg-bind-cwd /path/to/project
-```
-
-This creates a workspace-specific binding in `~/.pi/agent/tg.json`. Workspace bindings take priority over the global configuration.
-
-### Rendering & Mode Settings
-
-Via interactive menu:
-
-```
-/tg-config
-```
-
-Or directly:
-
-```
-/tg-config tool brief       # Tool rendering: hidden | brief | full
-/tg-config thinking full    # Thinking rendering: hidden | brief | full
-/tg-config mode steer       # Message mode: queue | steer
-/tg-config retry 3          # API retry count: 0-10
-```
-
----
-
-## How It Works
-
-```
-┌─────────────────┐     Long Polling      ┌──────────────────────┐
-│   Telegram Bot   │ ◄──────────────────► │  pi-telegram-plus    │
-│  (api.telegram)  │     Callback Queries  │  (pi extension)      │
-└─────────────────┘                       │                      │
-        ▲                                 │  ┌────────────────┐  │
-        │ Messages / Files                │  │  Controller     │  │
-        │                                 │  │  ├─ handleMsg   │  │
-  ┌─────────┐                            │  │  ├─ handleCB    │  │
-  │  User    │                            │  │  └─ runPrompt   │  │
-  │ (Telegram)│                           │  │                  │  │
-  └─────────┘                            │  │  ┌─────────────┐ │  │
-        ▲                                │  │  │ TelegramUI  │ │  │
-        │ Streaming Output               │  │  │ (interactive)│ │  │
-        │ Live Tool/Thinking Events      │  │  └─────────────┘ │  │
-        │ File Attachments (tg_attach)   │  │                  │  │
-        └───────────────────────────────────┤  ┌─────────────┐ │  │
-                                          │  │  Renderer    │ │  │
-                                          │  │  (Markdown→  │ │  │
-                                          │  │   Telegram   │ │  │
-                                          │  │   HTML)      │ │  │
-                                          │  └─────────────┘ │  │
-                                          │         │         │  │
-                                          │         ▼         │  │
-                                          │  ┌─────────────┐  │  │
-                                          │  │ pi Agent    │  │  │
-                                          │  │ (session,   │  │  │
-                                          │  │ models,     │  │  │
-                                          │  │ tools, ...) │  │  │
-                                          │  └─────────────┘  │  │
-                                          └──────────────────────┘
-```
-
-### Architecture Overview
-
-- **`index.ts`** — Extension entry point. Wires all modules together and handles `session_start`/`session_shutdown` lifecycle events.
-- **`lib/telegram-api.ts`** — Raw Telegram Bot API client with retry logic and file upload/download.
-- **`lib/polling.ts`** — Long polling loop with multi-instance file lock. Re-reads config while holding the lock to prevent offset regressions.
-- **`lib/controller.ts`** — Message routing: slash commands, text prompts, media attachments, callback queries.
-- **`lib/telegram-ui.ts`** — Interactive UI layer: notify, confirm, input, select (pagination), editor.
-- **`lib/renderer.ts`** — Hooks into agent lifecycle events (`agent_start`, `tool_execution_*`, `message_end`) and streams rendered output to Telegram.
-- **`lib/markdown.ts`** — Custom `marked` renderer that converts Markdown to Telegram-compatible HTML.
-- **`lib/config.ts`** — Configuration persistence with file locking for concurrent-safe writes. Supports global + workspace scopes.
-- **`lib/attachments.ts`** — `tg_attach` tool registration and outbound attachment delivery.
-- **`lib/commands/`** — Command handler modules: model, session, auth (login/logout), lifecycle, settings, tg-config, telegram-commands.
-- **`lib/heartbeat.ts`** — Periodic typing indicator while processing.
-- **`lib/status.ts`** — TUI status line integration showing connection state.
-- **`lib/session-capture.ts`** — Monkeys patches `AgentSession.bindExtensions` to intercept session lifecycle and capture the active session reference.
-- **`lib/menu-commands.ts`** — Builds and syncs the Telegram BotMenu command list.
-- **`lib/callback-protocol.ts`** — Encodes/decodes inline button callback data.
-
----
-
-## Project Structure
-
-```
-pi-telegram-plus/
-├── index.ts                     # Extension entry point
-├── pi-host.d.ts                 # Type augmentation for @earendil-works/pi-ai
-├── package.json
-├── tsconfig.json
-├── vitest.config.ts
-├── .pi/
-│   └── settings.json            # pi package registration
-└── lib/
-    ├── types.ts                 # All TypeScript interfaces & types
-    ├── telegram-api.ts          # Telegram Bot HTTP API client
-    ├── polling.ts               # Long polling with multi-instance lock
-    ├── controller.ts            # Message router & prompt executor
-    ├── telegram-ui.ts           # Interactive UI (notify, confirm, input, select)
-    ├── renderer.ts              # Agent event → Telegram output renderer
-    ├── markdown.ts              # Markdown → Telegram HTML converter
-    ├── html.ts                  # HTML escaping utilities
-    ├── text-split.ts            # UTF-8-safe text splitter for 4096 byte limit
-    ├── command-parser.ts        # Slash command parser & bot-username normalizer
-    ├── config.ts                # Configuration store (global + workspace scopes)
-    ├── attachments.ts           # Outbound file attachment tool (tg_attach)
-    ├── heartbeat.ts             # Typing indicator pulse
-    ├── status.ts                # TUI status line formatter
-    ├── session-capture.ts       # Agent session capture & handler patching
-    ├── menu-commands.ts         # Telegram BotMenu sync
-    ├── callback-protocol.ts     # UI callback encoding/decoding
-    ├── commands/
-    │   ├── register.ts          # Command registry aggregator
-    │   ├── model.ts             # /model, /scoped-models, /thinking
-    │   ├── session.ts           # /new, /fork, /clone, /tree, /resume, /cd, /cwd, /name, /session
-    │   ├── auth.ts              # /login (OAuth + API key), /logout
-    │   ├── info.ts              # /copy, /export, /import, /share, /status, /changelog, /hotkeys, /debug
-    │   ├── lifecycle.ts         # /compact, /reload, /stop, /quit
-    │   ├── settings.ts          # /settings menu
-    │   ├── tg-config.ts         # /tg-config
-    │   └── telegram-commands.ts # /tg-setup, /tg-connect, /tg-disconnect, /tg-bind-cwd, /tg-list
-    └── __tests__/
-        ├── attachments.test.ts
-        ├── callback-protocol.test.ts
-        ├── config.test.ts
-        ├── controller.test.ts
-        ├── html.test.ts
-        ├── markdown.test.ts
-        ├── status.test.ts
-        └── text-split.test.ts
-```
+## Troubleshooting
 
----
+Common issues and diagnostic steps. The extension writes a structured JSON Lines log to `<agent dir>/logs/pi-telegram-plus-YYYY-MM-DD.log` (default `~/.pi/agent/logs/`). Set `PI_TELEGRAM_PLUS_LOG_LEVEL=debug|info|warn|error` to control verbosity. See [docs/logging.md](docs/logging.md) for the full logging design.
 
-## Development
+### The bot does not respond to my messages
+- Verify the bot token is correct: run `/tg-global-setup` (global) or `/tg-bind-cwd` (workspace) and re-paste the token from [@BotFather](https://t.me/BotFather).
+- Confirm the bot is connected: `/tg-list` should show the binding as enabled. If not, run `/tg-global-connect` or `/tg-cwd-connect`.
+- Make sure you are the authorized user. The **first** Telegram user to message the bot is auto-authorized; all others are rejected. To reset authorization, remove the binding and re-setup.
+- Check that no other pi instance is polling the same token. The file-based polling lock prevents races, but a stuck lock file can block a new instance — restart pi or remove the stale lock if needed.
 
-```bash
-# Type checking
-npm run typecheck
+### Messages arrive but the agent output is not streamed
+- Confirm pi has an active model and valid credentials: run `/model` and `/status` from Telegram.
+- If `tool` / `thinking` rendering is set to `hidden`, output may look silent. Run `/tg-config tool brief` and `/tg-config thinking brief` to surface activity.
+- Long single messages may exceed Telegram's 4096-byte limit; the extension splits them automatically, but if delivery still fails, check your network and the pi log for upstream API errors.
 
-# Run tests
-npm test
+### Interactive dialogs (Select / Confirm / Input / Editor) do not appear
+- Inline keyboards require a recent Telegram client; update your Telegram app.
+- Inline keyboards are removed once the pending dialog resolves or is cancelled (e.g. via `/stop` or timeout). Re-trigger the action to get a fresh keyboard.
+- For third-party `custom()` dialogs (pi-goal), ensure the producing extension is loaded (`/reload`) and that the component exposes the expected `handleInput`/`render` API. Unknown shapes are auto-dismissed as `cancelled`.
 
-# Watch mode
-npm run test:watch
-```
+### `/tg-global-*` or `/tg-bind-cwd` commands are missing
+- The extension must be registered as a pi package. Re-run `pi install npm:pi-telegram-plus` (or `pi packages add .` from source) and restart pi.
+- Run `/reload` to refresh command registration without a full restart.
 
----
-
-## Security
-
-- **No secrets in source code** — All bot tokens and API keys are read from `~/.pi/agent/tg.json` and `~/.pi/agent/auth.json` at runtime.
-- **File permissions** — Configuration files are created with `chmod 600` (owner-only access).
-- **Sensitive input protection** — API key inputs use `inputSecret` which automatically deletes the user's message after reading.
-- **Attachment path safety** — Outbound `tg_attach` blocks sensitive paths (`/etc`, `~/.ssh`, etc.).
-- **Polling lock** — File-based lock prevents multiple pi instances from polling the same bot token simultaneously.
-- **First-user authorization** — The first Telegram user to message the bot is automatically authorized; subsequent users are rejected.
-
----
+### File attachments fail to send or are rejected
+- Outbound `tg_attach` blocks sensitive paths (`/etc`, `~/.ssh`, etc.). Move the file to a non-sensitive location and retry.
+- Default upload size limit is 50 MB. Files exceeding it are rejected; reduce the file size or split the content.
+- For download failures (Telegram → working directory), check that the working directory is writable and that the filename was sanitized correctly. Saved paths are reported back in the chat.
 
-## License
+### Polling reconnects repeatedly or reports transient failures
+- The extension uses exponential backoff on transient errors. If failures persist, verify network reachability to `api.telegram.org` and that the bot token has not been revoked in BotFather.
+- A revoked/regenerated token will keep failing until you re-run `/tg-global-setup` with the new token.
 
-MIT
+### Configuration changes are not picked up
+- Per-workspace bindings live in `~/.pi/agent/tg.json`. After editing by hand, run `/reload` (or restart pi) so the extension re-reads config.
+- Workspace bindings override the global token. If the wrong bot responds, run `/tg-list` and `/tg-unbind-cwd` to clear the unintended override.

package/index.ts

@@ -1,8 +1,8 @@
 import { mkdir, writeFile } from "node:fs/promises";
-import { extname, resolve } from "node:path";
+import { extname, join, resolve } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { registerTelegramAttachmentTool } from "./lib/attachments.ts";
-import { readResolvedTelegramConfig, writeResolvedTelegramConfig } from "./lib/config.ts";
+import { readResolvedTelegramConfig, writeResolvedTelegramConfig, getAgentDir } from "./lib/config.ts";
 import { createTelegramController, type TelegramCommandHandler } from "./lib/controller.ts";
 import { createHeartbeat } from "./lib/heartbeat.ts";
 import { registerTelegramRenderer } from "./lib/renderer.ts";
@@ -11,11 +11,15 @@ import { createTelegramTransport, downloadTelegramFile, getTelegramBotUsername,
 import { createTelegramUiRuntime } from "./lib/telegram-ui.ts";
 import { formatTelegramStatusLine, clearTelegramStatus, TELEGRAM_STATUS_KEY } from "./lib/status.ts";
 import { createTelegramPollingRuntime } from "./lib/polling.ts";
+import { initLogger, log, type LogLevel } from "./lib/logger.ts";
+
 import { registerAllCommands } from "./lib/commands/register.ts";
 import { registerTelegramCommands } from "./lib/commands/telegram-commands.ts";
 import { syncTelegramCommands } from "./lib/menu-commands.ts";
 import type { ResolvedTelegramConfig, TelegramConfig, TelegramTurn } from "./lib/types.ts";
 
+const indexLog = log.child("index");
+
 type TelegramPlusRuntimeState = {
   dispose?: () => void;
 };
@@ -30,6 +34,14 @@ function getTelegramPlusRuntimeState(): TelegramPlusRuntimeState {
 
 export default function piTelegramPlus(pi: ExtensionAPI): void {
   installAgentSessionCapture();
+  // Initialize file logging first, before any subsystem can emit. Log directory
+  // lives under the pi agent cache dir alongside tg.json; level is overridable
+  // via PI_TELEGRAM_PLUS_LOG_LEVEL (debug/info/warn/error). See lib/logger.ts.
+  const envLevel = process.env.PI_TELEGRAM_PLUS_LOG_LEVEL?.toLowerCase();
+  const level: LogLevel = (envLevel === "debug" || envLevel === "info" || envLevel === "warn" || envLevel === "error")
+    ? envLevel
+    : "info";
+  initLogger({ dir: join(getAgentDir(), "logs"), level });
   const runtimeState = getTelegramPlusRuntimeState();
   runtimeState.dispose?.();
 
@@ -256,7 +268,7 @@ export default function piTelegramPlus(pi: ExtensionAPI): void {
       }
       const chatId = config.activeChatId;
       if (chatId !== undefined && config.botToken) {
-        transport.sendText(chatId, `<b>error</b>\nTelegram polling failed`).catch(() => undefined);
+        transport.sendText(chatId, `<b>error</b>\nTelegram polling failed`).catch(log.child("polling").swallow("error", "sendText polling-failure notice failed", { chatId }));
       } else {
         getActiveSession()?.extensionRunner.getUIContext().notify(`Telegram polling failed: ${message}`, "error");
       }
@@ -318,10 +330,10 @@ export default function piTelegramPlus(pi: ExtensionAPI): void {
           config = { ...config, botUsername };
           await persistCurrentConfig(config);
         }
-      } catch { /* non-critical */ }
+      } catch (err) { indexLog.debug("resolve botUsername on startup failed (non-critical)", { err }); }
     }
     if (config.botToken && isTelegramEnabled() && !polling.isActive()) polling.start();
-    try { await syncTelegramCommands(config.botToken, pi); } catch { /* non-critical */ }
+    try { await syncTelegramCommands(config.botToken, pi); } catch (err) { indexLog.debug("syncTelegramCommands on startup failed (non-critical)", { err }); }
     lastStatusError = undefined;
     heartbeat.startStatusHeartbeat(refreshStatus);
     refreshStatus();

package/lib/attachments.ts

@@ -3,6 +3,9 @@ import { basename, resolve } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import type { TelegramTransport, TelegramTurn } from "./types.ts";
+import { log } from "./logger.ts";
+
+const attachLog = log.child("attachments");
 
 const MAX_ATTACHMENTS_PER_TURN = 10;
 const DEFAULT_MAX_BYTES = 50 * 1024 * 1024;
@@ -58,7 +61,8 @@ async function sendTelegramAttachment(
         await transport.sendChatAction(chatId, "upload_photo");
         await transport.sendPhoto(chatId, attachment.path, attachment.fileName, true);
         return;
-      } catch {
+      } catch (err) {
+        attachLog.warn("sendPhoto failed; falling back to sendDocument", { chatId, fileName: attachment.fileName, err });
         await transport.sendChatAction(chatId, "upload_document");
         await transport.sendDocument(chatId, attachment.path, attachment.fileName);
         return;
@@ -125,7 +129,7 @@ export function registerTelegramAttachmentTool(
       for (const attachment of pendingAttachments) {
         await sendTelegramAttachment(chatId, attachment, deps.transport, maxBytes, async (message) => {
           failed.push(message);
-          await deps.transport.sendText(chatId, message).catch(() => undefined);
+          await deps.transport.sendText(chatId, message).catch(attachLog.swallow("warn", "sendText attachment error notice failed", { chatId }));
         });
       }
       return {
@@ -148,7 +152,7 @@ export async function sendQueuedTelegramAttachments(
   const maxBytes = outboundAttachmentLimit();
   for (const attachment of turn.queuedAttachments) {
     await sendTelegramAttachment(turn.chatId, attachment, transport, maxBytes, async (message) => {
-      await transport.sendText(turn.chatId, message).catch(() => undefined);
+      await transport.sendText(turn.chatId, message).catch(attachLog.swallow("warn", "sendText attachment error notice failed", { chatId: turn.chatId }));
     });
   }
 }

package/lib/commands/session.ts

@@ -5,6 +5,9 @@ import { SessionManager, type SessionEntry } from "@earendil-works/pi-coding-age
 import type { SessionNameDeps, CommandRegistry } from "./register.ts";
 import { escapeHtml } from "../html.ts";
 import type { CapturedAgentSession } from "../types.ts";
+import { log } from "../logger.ts";
+
+const sessionLog = log.child("session");
 
 function truncate(text: string, max: number): string {
   return text.length <= max ? text : text.slice(0, max - 1) + "…";
@@ -187,7 +190,7 @@ export function registerSessionCommands(
       if (!rawPath) return;
 
       const targetCwd = resolveTargetCwd(rawPath, ctx.cwd);
-      const info = await stat(targetCwd).catch(() => undefined);
+      const info = await stat(targetCwd).catch(sessionLog.swallow("debug", "stat target cwd failed (treated as not-a-directory)", { targetCwd }));
       if (!info?.isDirectory()) {
         ui.notify(`Not a directory: ${escapeHtml(targetCwd)}`, "error");
         return;

package/lib/commands/telegram-commands.ts

@@ -4,6 +4,9 @@ import { escapeHtml } from "../html.ts";
 import { getTelegramBotUsername } from "../telegram-api.ts";
 import type { ResolvedTelegramConfig, TelegramConfig, TelegramTransport } from "../types.ts";
 import type { TelegramPollingRuntime } from "../polling.ts";
+import { log } from "../logger.ts";
+
+const tgCmdLog = log.child("tg-commands");
 
 export type TelegramCommandDeps = {
   getConfig: () => TelegramConfig;
@@ -40,7 +43,7 @@ async function configureGlobalTelegramToken(
 ): Promise<boolean> {
   const token = await (ui.inputSecret?.("Telegram bot token") ?? ui.input("Telegram bot token"));
   if (!token) return false;
-  const botUsername = await getTelegramBotUsername(token).catch(() => undefined);
+  const botUsername = await getTelegramBotUsername(token).catch(tgCmdLog.swallow("warn", "getTelegramBotUsername failed during global token setup"));
   if (!deps.getResolvedConfig()) {
     deps.switchResolvedConfig({ store: { version: 2, global: {}, workspaces: [] }, scope: "global", config: {} });
   }
@@ -72,10 +75,10 @@ async function handleTgGlobalConnect(
     if (!deps.getConfig().botToken) {
       if (!(await configureGlobalTelegramToken(ui, deps))) return;
     } else {
-      const botUsername = deps.getConfig().botUsername ?? await getTelegramBotUsername(deps.getConfig().botToken!).catch(() => undefined);
+      const botUsername = deps.getConfig().botUsername ?? await getTelegramBotUsername(deps.getConfig().botToken!).catch(tgCmdLog.swallow("warn", "getTelegramBotUsername failed during global connect"));
       await globalConnectAndStart(deps, deps.getConfig().botToken!, botUsername);
     }
-  } catch { /* connection errors reported via polling onError */ }
+  } catch (err) { tgCmdLog.debug("global connect swallowed error (reported via polling onError)", { err }); }
   deps.clearStatusError();
   deps.startStatusHeartbeat();
   ui.notify("Telegram global bot connected.", "info");
@@ -128,7 +131,7 @@ export function registerTelegramCommands(
       const workspacePath = resolve(args.trim() || ctx.cwd || process.cwd());
       const token = await (ui.inputSecret?.(`Telegram bot token for ${workspacePath}`) ?? ui.input(`Telegram bot token for ${workspacePath}`));
       if (!token) return;
-      const botUsername = await getTelegramBotUsername(token).catch(() => undefined);
+      const botUsername = await getTelegramBotUsername(token).catch(tgCmdLog.swallow("warn", "getTelegramBotUsername failed during workspace token setup", { workspacePath }));
       await deps.getPolling().stop();
       deps.switchResolvedConfig(await bindWorkspaceTelegramConfig(workspacePath, {
         botToken: token,

package/lib/config.ts

@@ -3,6 +3,9 @@ import { chmod, mkdir, readFile, rm, rmdir, stat, writeFile } from "node:fs/prom
 import { homedir } from "node:os";
 import { join, relative, resolve } from "node:path";
 import type { ResolvedTelegramConfig, TelegramConfig, TelegramConfigStore, TelegramWorkspaceConfig } from "./types.ts";
+import { log } from "./logger.ts";
+
+const configLog = log.child("config");
 
 export function getAgentDir(): string {
   return process.env.PI_CODING_AGENT_DIR
@@ -33,7 +36,7 @@ async function withTelegramConfigLock<T>(run: () => Promise<T>): Promise<T> {
       if (code !== "EEXIST") throw error;
       const age = Date.now() - (await stat(lockPath).then((s) => s.mtimeMs).catch(() => Date.now()));
       if (age > 30_000 || Date.now() - started > 10_000) {
-        await rm(lockPath, { recursive: true, force: true }).catch(() => undefined);
+        await rm(lockPath, { recursive: true, force: true }).catch(configLog.swallow("warn", "rm stale config lock failed", { lockPath }));
         continue;
       }
       await sleep(50);
@@ -42,7 +45,7 @@ async function withTelegramConfigLock<T>(run: () => Promise<T>): Promise<T> {
   try {
     return await run();
   } finally {
-    await rmdir(lockPath).catch(() => undefined);
+    await rmdir(lockPath).catch(configLog.swallow("warn", "rmdir config lock failed on release", { lockPath }));
   }
 }
 
@@ -73,7 +76,7 @@ export async function writeTelegramConfigStore(store: TelegramConfigStore): Prom
     workspaces: store.workspaces ?? [],
   };
   await writeFile(path, JSON.stringify(normalized, null, 2) + "\n", { mode: 0o600 });
-  await chmod(path, 0o600).catch(() => undefined);
+  await chmod(path, 0o600).catch(configLog.swallow("warn", "chmod config file failed", { path }));
 }
 
 function normalizePath(path: string): string {