@llblab/pi-telegram 0.36.6 → 0.36.8

package/AGENTS.md

@@ -81,7 +81,7 @@ Use the relevant local skill before non-trivial work in its domain. Keep skill o
 - A forwarding delivery id is stable across registration replacement and derives from envelope kind, source `update_id`, and stable recipient binding. Runtime instance and registration generation remain separate attempt fences. Persisted message ownership carries the stable binding so replay can rebind only to its current authenticated registration.
 - A queued receipt persists its acquiring runtime instance, OS pid/process-birth identity, session generation, acquisition id, and acquisition time. Only exact authority may settle or discard it. Same-process session replacement may reconstruct the claim and the original process may settle after transport ownership moves; a foreign process may neither replay nor settle it through generic removal or a copied acquisition id.
 - Startup and elapsed time are not owner-death proof; queued authority has no time lease. Dead-owner recovery groups the complete receipt and transactionally rechecks pid liveness plus process-birth identity: only an absent PID or mismatched stable Linux/macOS birth proof returns all sources to `pending`; a matching proof is `alive`, while Windows or inaccessible birth metadata is `unverifiable`, and both non-dead outcomes keep authority queued. The live-transfer contract is authenticated offer → exact-generation bounded payload staging → recipient CAS acceptance → exact receipt-and-owner ACK → donor removal → recipient readiness. The offer freezes donor settlement/recovery; controls rebuild local closures; negative/mismatched pre-acceptance ACK cancels only an unaccepted offer and retains donor work; a lost post-acceptance ACK cannot cancel recipient authority and leaves donor memory frozen for explicit reconciliation.
-- Execution failures persist bounded diagnostics and attempt state as `retry-wait`. Automatic retry continues indefinitely with exponential `1s → 2s → 4s → 8s → 16s → 32s → 60s` delay capped at 60 seconds; later independent updates continue draining, durable authority is never silently discarded, and legacy `failed` entries resume automatically at startup. Snapshot-plus-segment journals compact only after 256 unapplied revisions or 4 MiB; snapshot-first cleanup tolerates redundant segments, and empty authority may atomically rebind bot/profile identity.
+- Execution failures persist bounded diagnostics and attempt state as `retry-wait`. Automatic retry continues indefinitely with exponential `1s → 2s → 4s → 8s → 16s → 32s → 60s` delay capped at 60 seconds; later independent updates continue draining, durable authority is never silently discarded, and legacy `failed` entries resume automatically at startup. Snapshot-plus-segment journals compact only after 256 unapplied revisions or 4 MiB; snapshot-first cleanup tolerates redundant segments, and empty authority may atomically rebind bot/profile identity. Missing snapshots left by the retired broad temp cleanup rebuild only from a complete provably empty segment chain, while revisionless snapshots may recover from a validated later segment predecessor; otherwise the snapshot and segments move atomically under `tmp/telegram/recovery/` before a fresh journal is published and startup continues with informational recovery evidence.
 - An unresolved reaction delays only the exact governed queue item identified by chat/message sources, not unrelated queue work. Queue receipt publication follows in-memory append and precedes dispatch request; receipt-bearing turns remain queued until every exact source commits.
 - The detailed implementation and release gates live in [`docs/architecture.md`](./docs/architecture.md), [`docs/multi-instance-bus.md`](./docs/multi-instance-bus.md), and [`BACKLOG.md`](./BACKLOG.md).
 

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 > Each release keeps at most 8 outcome records of at most 512 characters.
 
+## 0.36.8: Durable Journal Recovery
+
+- `Durable Journal Recovery`: Restricts age cleanup to UUID-prefixed downloads, repairs missing or revisionless snapshots from validated segment evidence, and otherwise quarantines the snapshot plus segments before publishing a fresh journal, keeping `/telegram-connect` operational with informational recovery evidence instead of manual JSON repair.
+
+## 0.36.7: Context-Aware Proactive Controls
+
+- `Proactive Prompt Buttons`: Plans valid top-level `telegram_button` comments before local/autonomous assistant segments enter Rich or HTML proactive delivery, preserving the ordinary callback store and renderer path instead of silently hiding correct controls.
+- `Connection-Aware Agent Context`: Successful setup/connect and disconnect commands queue a hidden connection-state note for delivery with the next agent turn without triggering one. Connected system guidance and Telegram Skills now distinguish transport capability from user intent, reserving proactive Telegram controls for Telegram-originated turns or explicit requests.
+
 ## 0.36.6: Orphan Journal Guard
 
 - `Orphan Journal Guard`: Rejects a missing journal snapshot when immutable revision segments still exist, preventing later admission from replacing uncertain durable authority with a new revisionless snapshot while preserving snapshot-first compaction and fail-closed recovery.

package/README.md

@@ -8,7 +8,7 @@
 
 It is a **runtime adapter**, not a remote terminal. Start or supervise work in the Pi TUI, then continue from Telegram while away from the keyboard. Each Telegram destination follows a running Pi instance and sends prompts into that instance's currently active session; it is not permanently bound to one session file or session identity. The bridge preserves Pi session semantics instead of pretending Telegram is a PTY, shell, process launcher, or session browser. That boundary is the product: Telegram gets safe runtime handles, not raw terminal power.
 
-Every completed intermediate commentary block from a Telegram-originated turn is delivered once as its own message before the existing final reply. Proactive push is enabled by default for local, autonomous, and unclassified extension follow-up work: `assistant.proactivePush` projects visible checkpoints and the final answer to the authorized Telegram target once and in order; set it explicitly to `false` to disable only that local/autonomous projection. Neither path mirrors local prompts, thinking, tool traffic, token deltas, or stale-generation work. The separate `Activity` setting defaults to `verbose` so new installations discover collapsed provider-exposed thinking and tool evidence immediately; operators can narrow it to one class or choose `quiet`. See [Outbound](docs/outbound.md#public-assistant-output) and the [configuration reference](docs/public-api.md#configuration-api).
+Every completed intermediate commentary block from a Telegram-originated turn is delivered once as its own message before the existing final reply. Proactive push is enabled by default for local, autonomous, and unclassified extension follow-up work: `assistant.proactivePush` projects visible checkpoints and the final answer to the authorized Telegram target once and in order, preserving assistant-authored `telegram_button` comments as interactive prompt buttons; set it explicitly to `false` to disable only that local/autonomous projection. Neither path mirrors local prompts, thinking, tool traffic, token deltas, or stale-generation work. The separate `Activity` setting defaults to `verbose` so new installations discover collapsed provider-exposed thinking and tool evidence immediately; operators can narrow it to one class or choose `quiet`. See [Outbound](docs/outbound.md#public-assistant-output) and the [configuration reference](docs/public-api.md#configuration-api).
 
 This repository is an actively maintained fork of [`badlogic/pi-telegram`](https://github.com/badlogic/pi-telegram). It started from upstream commit [`cb34008`](https://github.com/badlogic/pi-telegram/commit/cb34008460b6c1ca036d92322f69d87f626be0fc) and has since diverged substantially.
 
@@ -57,7 +57,7 @@ Paste the bot token. If `~/.pi/agent/telegram.json` already contains a saved tok
 
 The connected Pi instance owns Telegram polling. Use `/telegram-connect <name>` to activate a named profile. Each profile is a parallel bot runtime with isolated polling, diagnostics, Threaded Mode state, and local bus transport; the `default` profile keeps unsuffixed runtime paths. In classic mode each profile uses a singleton lock. When Telegram private-chat Threaded Mode is available, one live instance becomes the profile's leader and later visible Pi instances register as followers.
 
-After an unclean computer shutdown, `/telegram-connect` detects truncated or structurally invalid temporary ownership/routing files, quarantines only the damaged files under `tmp/telegram/recovery/`, and retries once. Saved `telegram.json` configuration and runtime diagnostics remain intact. Recovery never replaces a verifiable live owner; if safe automatic recovery cannot complete, the command gives one explicit Pi-restart instruction instead of requiring deletion of the whole `tmp/` directory.
+After an unclean computer shutdown, `/telegram-connect` detects truncated or structurally invalid temporary ownership/routing files, quarantines only the damaged files under `tmp/telegram/recovery/`, and retries once. A journal snapshot removed by older broad temp cleanup is rebuilt when its complete segment history proves an empty result, while a revisionless snapshot is repaired from the first surviving segment's exact predecessor when the reconstructed tail validates. Otherwise the snapshot and segments are quarantined as recovery evidence, a fresh journal is published, and startup continues with an informational diagnostic instead of requiring manual JSON repair. Saved `telegram.json` configuration and runtime diagnostics remain intact. Recovery never replaces a verifiable live owner; if safe automatic recovery cannot complete, the command gives one explicit Pi-restart instruction instead of requiring deletion of the whole `tmp/` directory.
 
 ### 4. Pair your Telegram account
 

package/docs/architecture.md

@@ -163,7 +163,7 @@ Telegram private-chat Threaded Mode is the public switch for multi-instance Tele
 
 Named Telegram profiles are orthogonal to Threaded Mode. The selected profile chooses the bot/session slice (`botToken`, `botId`, `botUsername`, `allowedUserId`, `lastUpdateId`) and scopes the `owners.json` slot, diagnostics logs, state files, thread/bus ownership, and leader/follower IPC endpoints; it must not change the Threaded Mode rules. Within one selected profile, leader/follower election, bus transport, thread provisioning, routing, ownership forwarding, cleanup, and runtime diagnostics behave exactly as they do for the `default` slot. A different selected profile is a parallel bot runtime: its owner slot, `tmp/telegram/state.<profile>.json`, `tmp/telegram/logs.<profile>.jsonl`, `tmp/telegram/logs.<profile>._prev.jsonl`, thread bindings, Unix sockets, and Windows named pipes are isolated from the default profile and other named profiles while shared bridge settings remain top-level/global.
 
-Profile reality follows three explicit storage classes. `telegram.json` shared settings and extension registries are process-global platform configuration; `profiles.default` and `profiles.<name>` bot/session fields plus observable transport/routing authority are profile-scoped; queues, active turns, ownership caches, menu state, and runtime controllers are session-local memory. Config persistence serializes cross-process writers and applies each recursive mutation delta to the latest disk snapshot, so named-profile offsets and unrelated global/profile updates do not stale-replace one another. Polling publishes only its monotonic `lastUpdateId` into the current config-store snapshot; it never persists the detached full config object captured at poll start, which would interpret newer Settings fields as deletions. Runtime profile switching follows stop-old/commit-new ordering: reload keeps the selected identity stable, old polling/lock/bus teardown finishes while all dynamic resolvers still point at the old profile, and only then may activation expose the new token, lock key, state path, target namespace, and IPC endpoint. Downloaded attachments use UUID-prefixed names in the shared Telegram scratch directory and are session artifacts rather than identity or routing authority, so cross-profile cleanup is limited to stale scratch files and cannot redirect live traffic.
+Profile reality follows three explicit storage classes. `telegram.json` shared settings and extension registries are process-global platform configuration; `profiles.default` and `profiles.<name>` bot/session fields plus observable transport/routing authority are profile-scoped; queues, active turns, ownership caches, menu state, and runtime controllers are session-local memory. Config persistence serializes cross-process writers and applies each recursive mutation delta to the latest disk snapshot, so named-profile offsets and unrelated global/profile updates do not stale-replace one another. Polling publishes only its monotonic `lastUpdateId` into the current config-store snapshot; it never persists the detached full config object captured at poll start, which would interpret newer Settings fields as deletions. Runtime profile switching follows stop-old/commit-new ordering: reload keeps the selected identity stable, old polling/lock/bus teardown finishes while all dynamic resolvers still point at the old profile, and only then may activation expose the new token, lock key, state path, target namespace, and IPC endpoint. Downloaded attachments use UUID-prefixed names in the shared Telegram scratch directory and are session artifacts rather than identity or routing authority, so cross-profile cleanup recognizes only those UUID-prefixed scratch files. It never age-deletes journals, ownership, state, logs, or other top-level runtime files and therefore cannot redirect live traffic or orphan immutable journal segments.
 
 When Threaded Mode is active, the current polling owner is also the Telegram bus leader. The leader owns the local bus endpoint (Unix-domain socket on Unix-like platforms, named pipe on native Windows), polls `getUpdates`, performs direct Bot API calls, records follower heartbeats, prunes stale followers, and provisions Telegram UI thread targets through live runtime/bus state. Follower liveness is intentionally fast because heartbeat traffic is local IPC: followers heartbeat every `1s`, the leader treats them as stale after `2s`, and the prune loop runs every `1s` so stopped followers are detected promptly while active forwarded updates/API calls still refresh liveness. Heartbeat pruning is silent liveness bookkeeping and does not send a Telegram-visible disconnected notice, because the common cause may be leader reload or IPC handoff rather than a dead follower. Pruning alone preserves the binding; when Thread cleanup is enabled, only a subsequent OS check that confirms the exact registered PID absent may create fenced cleanup intent, and that cleanup serializes ahead of replacement registration. Successful follower target reuse refreshes the binding's recovery timestamp. Absent follower bindings remain durable restoration hints until explicit stale, deleted, offline, or reconciliation evidence invalidates them; process absence and heartbeat pruning alone do not remove them. If an authenticated live follower carries an exact target that is absent from current bindings, the leader recovers it only behind a synchronous visibility probe: success activates it, explicit stale evidence provisions a replacement, and ambiguous failure rejects registration. A carried slot is restored only when it is not already occupied. `tmp/telegram/logs.jsonl` is a session-local redacted runtime evidence stream for race debugging; it resets on extension start and runtime scope changes, and must not become routing/provisioning authority. `tmp/telegram/state.json` is an extension+bot observable/debug snapshot aligned with status diagnostics: `source: "snapshot"` and `writtenAtMs` mark it as observational, not authoritative. All instances on one Telegram profile read the same snapshot, but only the active transport lock owner persists it; followers become writers only after promotion. Status-only persistence reloads current disk bindings before serialization, preventing a stale follower/status view from erasing newer leader-owned targets. Fresh capability observations may skip redundant startup probes, but stale snapshots re-probe before suppressing bus/thread behavior. Top-level `bot` mirrors bot-wide capabilities such as thread mode, `runtime` describes process role/status, `liveRoster` mirrors followers/current targets/reservations, `diagnostics` mirrors recent status/debug signals including the latest thread-reconciler phase/counts, `threads` stores current routeable bindings, TTL-bounded reservations explain short-lived slot collision guards, and TTL-pruned `pendingProvisions` protects in-flight topic creation slots from cleanup/allocation races. Fresh provisioning writes pending state before the Bot API create call, adds the returned target to the pending record, persists a `starting` binding, then promotes it to `active` and clears pending state. If final binding persistence fails after Telegram returns a thread id, the targeted pending provision remains as cleanup/retry evidence. Once targeted pending provisions expire, they are retained for `thread-reconciler` close/delete cleanup and pending scratchpad removal after a successful cleanup apply; untargeted expired pending records can prune without cleanup because no Telegram thread id exists. Runtime events coalesce status-snapshot writes so transient bus/API/update failures remain inspectable even when the operator has not opened `/telegram-status`. The bridge must not keep a durable `telegram-targets.json` target history; stale/offline/failed thread observations are pruned instead of reused. Previous-process leader bindings that still probe alive become reservations/collision guards, not routeable active threads, so a reloaded leader can take the next free slot without duplicating the same visible tab name. The thread chat is always the private bot DM with the paired owner (`allowedUserId`). In Telegram private-chat Threaded Mode, the leader creates/reuses its own thread before polling — it is a real bound instance, not a dispatcher. Followers authenticate bus envelopes with the leader-minted capability secret stored in the active lock entry. Bot capability monitoring does not probe through the bus until the process either owns that direct lock or has completed authenticated follower registration. Leader lock entries also carry a stable `leaderEpoch` minted on acquisition and preserved across heartbeat refreshes; leader-owned cleanup/provisioning plans stamp that epoch, and Thread Reconciler apply skips destructive work if leadership has moved on before side effects run. Followers own their own Pi session state, queue, active turns, previews, menus, and lifecycle hooks, but route allowlisted, target-scoped Telegram API calls through the leader. When a follower promotes after heartbeat loss, status/state diagnostics expose only the transient `electing` lifecycle phase; stable `leader`/`follower` identity stays in the bus role so diagnostics do not duplicate role state. The TUI status bar and `/telegram-status` report `leader` or `follower` role so a registered follower is not shown as generically disconnected. Terminal status identity and the `[telegram|thread:name]` prompt label use the same target-aware current-instance resolver: registered local metadata wins over a stale shared binding for the matching target, while the binding remains a fallback for partial metadata.
 
@@ -205,9 +205,9 @@ All inbound updates are gated by the configured authorized user id.
 
 Here, **durable** means recovery across ordinary process exit, crash, kill, and replacement after a successful atomic rename is visible to the filesystem. It does not promise survival across host, kernel, filesystem, storage-device, or power failure: journal and offset publication do not call `fsync`/`fdatasync`, and parent directories are not flushed. A host-level failure may therefore lose a recently acknowledged rename despite correct process-level ordering. Operators requiring that stronger boundary must place the agent directory on storage with an independently managed durability/backup policy; `0.28.0` must not be described as power-loss durable.
 
-The profile-scoped journal separates transport progress from semantic progress. Leader/classic snapshots live at `tmp/telegram/inbox[.<profile>].json`; follower paths add a stable target-binding hash. The selected post-v1 storage design is one revisioned compacted snapshot plus immutable atomic transaction segments beside it. Existing v1 files load as implicit revision `0`, while positive snapshot revisions are explicit. Immutable revision segments publish privately and atomically under the existing journal transaction lock; exact repeats are idempotent, while gaps and conflicting duplicate revisions fail closed. Each segment carries one complete mutation, and readers reconstruct ordered upserts, removals, and operator-disposition state only from revisions newer than the snapshot. Malformed or gapped segments, filename/revision disagreement, and foreign journal identity fail closed. After the initial snapshot, append, batch completion, queue receipt/owner/handoff, retry/terminal, recovery, and operator dispositions publish only changed upserts/removals and disposition replacement in one segment. This avoids rewriting retained raw updates during completion-heavy drains without splitting exact queue, failure, recovery, or disposition transactions.
+The profile-scoped journal separates transport progress from semantic progress. Leader/classic snapshots live at `tmp/telegram/inbox[.<profile>].json`; follower paths add a stable target-binding hash. The selected post-v1 storage design is one revisioned compacted snapshot plus immutable atomic transaction segments beside it. Existing v1 files load as implicit revision `0`, while positive snapshot revisions are explicit. Immutable revision segments publish privately and atomically under the existing journal transaction lock; exact repeats are idempotent, while gaps and conflicting duplicate revisions fail closed. Each segment carries one complete mutation, and readers reconstruct ordered upserts, removals, and operator-disposition state only from revisions newer than the snapshot. Malformed or gapped segments, filename/revision disagreement, and foreign journal identity fail closed. Compatibility recovery for the former broad temp-cleanup bug rebuilds a missing snapshot when its complete revision-1 segment chain removes known base authority before any upsert and reconstructs to an empty journal, and repairs a revisionless snapshot when the first surviving segment supplies its exact positive predecessor revision and the reconstructed tail validates. If repair fails, the transaction-locked loader atomically moves the snapshot when present plus its segment directory under `tmp/telegram/recovery/`, publishes a fresh empty private journal, records an informational recovery event with the quarantine path, and continues startup; no uncertain files are silently deleted. After the initial snapshot, append, batch completion, queue receipt/owner/handoff, retry/terminal, recovery, and operator dispositions publish only changed upserts/removals and disposition replacement in one segment. This avoids rewriting retained raw updates during completion-heavy drains without splitting exact queue, failure, recovery, or disposition transactions.
 
-Compaction runs under the journal transaction lock when either 256 unapplied segments or 4 MiB of segment bytes is reached. It publishes the complete private (`0600`) snapshot at revision `R` before best-effort deletion of segments `<= R`; failed cleanup leaves redundant segments that readers ignore. Interrupted cleanup therefore leaves either an older snapshot plus newer authoritative segments or a newer snapshot plus harmless redundant older segments. Revision gaps, conflicting duplicates, malformed segments, and identity mismatches fail closed. The logical reconstructed journal and aggregate unapplied segment bytes are independently bounded at 10,000 entries and 32 MiB as applicable; rejected growth publishes neither snapshot nor segment bytes. Compaction may temporarily require exactly one private complete snapshot of at most 32 MiB. Capacity pauses polling and authority files are never automatically deleted, reset, or quarantined.
+Compaction runs under the journal transaction lock when either 256 unapplied segments or 4 MiB of segment bytes is reached. It publishes the complete private (`0600`) snapshot at revision `R` before best-effort deletion of segments `<= R`; failed cleanup leaves redundant segments that readers ignore. Interrupted cleanup therefore leaves either an older snapshot plus newer authoritative segments or a newer snapshot plus harmless redundant older segments. Revision gaps, conflicting duplicates, malformed segments, and identity mismatches fail closed. The logical reconstructed journal and aggregate unapplied segment bytes are independently bounded at 10,000 entries and 32 MiB as applicable; rejected growth publishes neither snapshot nor segment bytes. Compaction may temporarily require exactly one private complete snapshot of at most 32 MiB. Capacity pauses polling and valid authority files are never automatically deleted, reset, or quarantined. Only a missing-snapshot history that cannot be reconstructed safely uses the explicit evidence-preserving quarantine-and-reset compatibility fallback above.
 
 `pending` entries remain immediately executable while raw interception, routing, or grouping is incomplete. Every execution failure becomes `retry-wait` with durable attempt count, next eligible time, failure class, bounded summary, and latest failure time. The `failed` state remains schema-compatible only for legacy candidate journals and is converted to automatic retry during lifecycle startup. `queued` entries carry exact prompt/control receipts plus the acquiring Pi runtime instance, OS pid/birth identity, session generation, acquisition id, and acquisition time. Queueing alone is never completion.
 

package/docs/outbound.md

@@ -12,7 +12,7 @@ Every completed `assistant-segment` with `placement: "intermediate"` from a Tele
 
 Proactive projection defaults on for local, autonomous, and unclassified extension follow-up Pi work. With `assistant.proactivePush` omitted or set to `true`, every completed public block—including visible commentary/checkpoints and the final answer—is projected to the instance's authorized target in source order; set it explicitly to `false` to opt out of only this local/autonomous projection. Both paths consume normalized complete Activity segments rather than raw token deltas, reasoning, or tool traffic.
 
-Projected blocks use `assistant.rendering` independently of voice policy. Rich mode sends native Rich Markdown and HTML mode keeps the established HTML renderer; projection does not synthesize voice or attach queued files merely because Rich rendering is active. Ordered admission revalidates the exact target, profile/token transport generation, leader epoch or follower registration generation, and session generation before each send. Active-turn final delivery waits for admitted commentary inside its existing background delivery task, preserving commentary-before-final order without blocking Pi lifecycle completion. A `commit-unknown` outcome never permits replay.
+Projected blocks use `assistant.rendering` independently of voice policy. Rich mode sends native Rich Markdown and HTML mode keeps the established HTML renderer; assistant-authored `telegram_button` comments are planned into prompt buttons before either renderer runs, while projection does not synthesize voice or attach queued files merely because Rich rendering is active. Ordered admission revalidates the exact target, profile/token transport generation, leader epoch or follower registration generation, and session generation before each send. Active-turn final delivery waits for admitted commentary inside its existing background delivery task, preserving commentary-before-final order without blocking Pi lifecycle completion. A `commit-unknown` outcome never permits replay.
 
 ## Technical Activity
 

package/docs/public-api.md

@@ -40,8 +40,8 @@ import {
 Stable commands inside Pi:
 
 - `/telegram-setup` — configure/update the bot token.
-- `/telegram-connect` — start polling here and acquire external Telegram control ownership. Accepted queue/reply state stays local if ownership later moves elsewhere.
-- `/telegram-disconnect` — after destructive confirmation, stop polling and release ownership without deleting or silencing accepted local queue state. In Threaded Mode it deletes this instance's current Telegram thread; a follower waits for its active leader to confirm generation-fenced cleanup before stopping. Graceful Pi `quit` performs the same teardown without prompting, while `reload`, `new`, `resume`, and `fork` preserve same-process handoff.
+- `/telegram-connect` — start polling here and acquire external Telegram control ownership. Accepted queue/reply state stays local if ownership later moves elsewhere. A successful command queues a hidden connection-state note for delivery with the agent's next turn without triggering one; it says Telegram is connected and that connectivity alone is not user intent.
+- `/telegram-disconnect` — after destructive confirmation, stop polling and release ownership without deleting or silencing accepted local queue state. A successful command queues the corresponding hidden, non-triggering disconnected context note; cancelled or failed disconnects do not publish a false state transition. In Threaded Mode it deletes this instance's current Telegram thread; a follower waits for its active leader to confirm generation-fenced cleanup before stopping. Graceful Pi `quit` performs the same teardown without prompting, while `reload`, `new`, `resume`, and `fork` preserve same-process handoff.
 - `/telegram-status` — show connection, polling, execution, queue, and recent event diagnostics; debug output separates poller and worker progress, durable automatic-retry state, exact foreign queued-owner identity, and negotiated protocol/build/capabilities.
 
 ### Telegram commands

package/index.ts

@@ -132,6 +132,22 @@ export default function (pi: Pi.ExtensionAPI) {
         getProfileName: configStore.getActiveProfileName,
         getBotToken: configStore.getBotToken,
         getBotId: getTelegramBotId,
+        onRecovery(event) {
+          recordRuntimeEvent(
+            "recovery",
+            event.kind === "repaired"
+              ? "Telegram update journal was repaired automatically."
+              : "Telegram update journal was reset after its damaged files were quarantined.",
+            {
+              phase: "journal-auto-recovery",
+              recoveryKind: event.kind,
+              journalPath: event.path,
+              revision: event.revision,
+              quarantinePath: event.quarantinePath,
+              reason: event.reason,
+            },
+          );
+        },
         getQueueRuntimeIdentity() {
           return {
             instanceId: telegramInstanceId,
@@ -539,6 +555,8 @@ export default function (pi: Pi.ExtensionAPI) {
         sendRichMessage,
         editMessage: editTelegramMessageText,
         getAssistantRenderingMode: configControls.getAssistantRenderingMode,
+        planButtonReply:
+          Outbound.createTelegramButtonReplyPlanner(buttonActionStore),
         execCommand: CommandTemplates.execCommandTemplate,
         getHandlers: configStore.getOutboundHandlers,
         recordRuntimeEvent,

package/lib/bindings.ts

@@ -514,6 +514,18 @@ export function registerTelegramCommandsAndTools({
       sendMarkdownReply(chatId, undefined, markdown, options),
     recordRuntimeEvent,
   });
+  const queueAgentConnectionContext = (connected: boolean): void => {
+    pi.sendMessage(
+      {
+        customType: "telegram-connection-state",
+        content: connected
+          ? Prompts.TELEGRAM_CONNECTED_CONTEXT_MESSAGE
+          : Prompts.TELEGRAM_DISCONNECTED_CONTEXT_MESSAGE,
+        display: false,
+      },
+      { deliverAs: "nextTurn" },
+    );
+  };
   Commands.registerTelegramBridgeCommands(pi, {
     promptForConfig: async (ctx, profileName) => {
       const nextProfileName = profileName ?? undefined;
@@ -581,8 +593,11 @@ export function registerTelegramCommandsAndTools({
         recordRuntimeEvent,
       });
       const completion = await runSetup(ctx);
-      if (profileName && completion.status === "success") {
-        ctx.ui.notify(`Profile "${profileName}" saved and connected.`, "info");
+      if (completion.status === "success") {
+        queueAgentConnectionContext(true);
+        if (profileName) {
+          ctx.ui.notify(`Profile "${profileName}" saved and connected.`, "info");
+        }
       }
     },
     getStatusLines,
@@ -599,6 +614,7 @@ export function registerTelegramCommandsAndTools({
     stopPolling: stopPolling ?? lockedPollingRuntime.stop,
     recoverPollingStart,
     getDisconnectThreadName,
+    queueAgentConnectionContext,
     updateStatus,
     getProfileNames: () =>
       Config.getTelegramProfileNames(configStore.getStoredConfig()),

package/lib/commands.ts

@@ -334,6 +334,7 @@ export interface TelegramBridgeCommandRegistrationDeps {
     error: unknown,
   ) => Promise<TelegramPollingStartRecoveryResult>;
   getDisconnectThreadName?: () => string | undefined;
+  queueAgentConnectionContext?: (connected: boolean) => void;
   updateStatus: (ctx: ExtensionCommandContext) => void;
   getProfileNames?: () => string[];
   activateDefaultProfileConfig?: (ctx: ExtensionCommandContext) => Promise<void>;
@@ -468,6 +469,9 @@ export function registerTelegramBridgeCommands(
       if (result?.message) {
         ctx.ui.notify(result.message, result.ok ? "info" : "warning");
       }
+      if (!result || result.ok) {
+        deps.queueAgentConnectionContext?.(true);
+      }
       deps.updateStatus(ctx);
     },
   });
@@ -490,6 +494,7 @@ export function registerTelegramBridgeCommands(
       try {
         const message = await deps.stopPolling();
         if (message) ctx.ui.notify(message, "info");
+        deps.queueAgentConnectionContext?.(false);
       } catch (error) {
         const detail = error instanceof Error ? error.message : String(error);
         ctx.ui.notify(

package/lib/journal.ts

@@ -17,7 +17,7 @@ import {
   unlinkSync,
   writeFileSync,
 } from "node:fs";
-import { dirname, join } from "node:path";
+import { basename, dirname, join } from "node:path";
 import { isDeepStrictEqual } from "node:util";
 
 import {
@@ -349,6 +349,14 @@ export type TelegramUpdateJournalPublicationBoundary =
   | "before-write"
   | "after-write-before-rename";
 
+export interface TelegramUpdateJournalRecoveryEvent {
+  kind: "repaired" | "reset";
+  path: string;
+  revision?: number;
+  quarantinePath?: string;
+  reason: string;
+}
+
 export interface TelegramUpdateJournalStoreOptions {
   path: string;
   profileName?: string;
@@ -356,6 +364,7 @@ export interface TelegramUpdateJournalStoreOptions {
   maxEntries?: number;
   maxBytes?: number;
   getNowMs?: () => number;
+  onRecovery?: (event: TelegramUpdateJournalRecoveryEvent) => void;
   queueRuntimeIdentity?: TelegramUpdateJournalQueueRuntimeIdentity;
   getQueueProcessLiveness?: (
     owner: TelegramUpdateJournalQueueProcessIdentity,
@@ -1472,6 +1481,7 @@ export interface TelegramUpdateJournalRuntimeBindingResolverDeps {
   getBotId: () => number | undefined;
   getJournalPath: (profileName?: string) => string;
   getQueueRuntimeIdentity?: () => TelegramUpdateJournalQueueRuntimeIdentity;
+  onRecovery?: (event: TelegramUpdateJournalRecoveryEvent) => void;
 }
 
 export function createTelegramUpdateJournalRuntimeBindingResolver(
@@ -1506,6 +1516,7 @@ export function createTelegramUpdateJournalRuntimeBindingResolver(
         ...(deps.getQueueRuntimeIdentity
           ? { queueRuntimeIdentity: deps.getQueueRuntimeIdentity() }
           : {}),
+        ...(deps.onRecovery ? { onRecovery: deps.onRecovery } : {}),
       }),
     };
   };
@@ -1546,6 +1557,7 @@ export function createTelegramUpdateJournalBindingRuntime(deps: {
       ...(includeQueueRuntimeIdentity && deps.base.getQueueRuntimeIdentity
         ? { getQueueRuntimeIdentity: deps.base.getQueueRuntimeIdentity }
         : {}),
+      ...(deps.base.onRecovery ? { onRecovery: deps.base.onRecovery } : {}),
       getJournalPath(profileName) {
         return deps.getFollowerJournalPath(bindingKey, profileName);
       },
@@ -1601,6 +1613,13 @@ export function createTelegramUpdateJournalStore(
   );
   const getNowMs = options.getNowMs ?? Date.now;
   const onPublicationBoundary = options.onPublicationBoundary;
+  const notifyRecovery = (event: TelegramUpdateJournalRecoveryEvent): void => {
+    try {
+      options.onRecovery?.(event);
+    } catch {
+      // Recovery diagnostics must not break recovered journal authority.
+    }
+  };
   const getQueueProcessLiveness =
     options.getQueueProcessLiveness ?? getTelegramProcessLiveness;
 
@@ -1742,8 +1761,9 @@ export function createTelegramUpdateJournalStore(
     entries: [],
   });
 
-  const readCurrent = (): ReadTelegramUpdateJournalResult => {
+  const readCurrentStrict = (): ReadTelegramUpdateJournalResult => {
     let source: string;
+    let recoveringMissingSnapshot = false;
     try {
       const size = statSync(path).size;
       if (size > maxBytes) {
@@ -1775,15 +1795,14 @@ export function createTelegramUpdateJournalStore(
           );
         }
         if (orphanedSegmentNames.length > 0) {
-          throw createJournalError(
-            "invalid",
-            path,
-            `is missing while ${segmentDirectory} retains revision segments`,
-          );
+          recoveringMissingSnapshot = true;
+          source = serializeJournalFile(emptyFile());
+        } else {
+          return { file: emptyFile(), exists: false, serializedBytes: 0 };
         }
-        return { file: emptyFile(), exists: false, serializedBytes: 0 };
+      } else {
+        throw createJournalError("io", path, "could not be read", error);
       }
-      throw createJournalError("io", path, "could not be read", error);
     }
     let parsed: unknown;
     try {
@@ -1808,6 +1827,9 @@ export function createTelegramUpdateJournalStore(
     segmentNames.sort();
     let revision = file.revision ?? 0;
     let unappliedSegmentBytes = 0;
+    let orphanRecoverySawUpsert = false;
+    let orphanRecoverySawBaseRemoval = false;
+    let orphanRecoveryUnsafe = false;
     for (const name of segmentNames) {
       const nameRevision = Number(name.slice(0, 16));
       if (nameRevision <= revision) continue;
@@ -1871,11 +1893,16 @@ export function createTelegramUpdateJournalStore(
         file.entries.map((entry) => [entry.updateId, entry]),
       );
       for (const updateId of segment.removedUpdateIds) {
+        if (recoveringMissingSnapshot && !entriesById.has(updateId)) {
+          orphanRecoverySawBaseRemoval = true;
+          if (orphanRecoverySawUpsert) orphanRecoveryUnsafe = true;
+        }
         entriesById.delete(updateId);
       }
       for (const entry of segment.upsertedEntries) {
         entriesById.set(entry.updateId, entry);
       }
+      if (segment.upsertedEntries.length > 0) orphanRecoverySawUpsert = true;
       file = parseJournalFile(
         {
           version: TELEGRAM_UPDATE_JOURNAL_VERSION,
@@ -1935,10 +1962,166 @@ export function createTelegramUpdateJournalStore(
       }
       return { file, exists: true, serializedBytes: reboundBytes };
     }
+    if (recoveringMissingSnapshot) {
+      if (
+        orphanRecoveryUnsafe ||
+        !orphanRecoverySawBaseRemoval ||
+        file.entries.length > 0
+      ) {
+        throw createJournalError(
+          "invalid",
+          path,
+          `is missing while ${segmentDirectory} retains revision segments`,
+        );
+      }
+      const recovered = serializeJournalFile(file);
+      const recoveredBytes = assertCapacity(file, recovered);
+      writeJournalFile(path, recovered, onPublicationBoundary);
+      notifyRecovery({
+        kind: "repaired",
+        path,
+        revision: file.revision,
+        reason: "Recovered a missing snapshot from a complete empty segment history.",
+      });
+      return { file, exists: true, serializedBytes: recoveredBytes };
+    }
     const serializedBytes = assertCapacity(file);
     return { file, exists: true, serializedBytes };
   };
 
+  const readCurrent = (): ReadTelegramUpdateJournalResult => {
+    try {
+      return readCurrentStrict();
+    } catch (error) {
+      if (
+        !(error instanceof TelegramUpdateJournalError) ||
+        error.code !== "invalid"
+      ) {
+        throw error;
+      }
+      let snapshotExists = false;
+      try {
+        statSync(path);
+        snapshotExists = true;
+      } catch (snapshotError) {
+        if ((snapshotError as { code?: unknown })?.code !== "ENOENT") throw error;
+      }
+      const segmentDirectory = getTelegramUpdateJournalSegmentDirectory(path);
+      let segmentNames: string[];
+      try {
+        segmentNames = readdirSync(segmentDirectory)
+          .filter((name) => /^\d{16}\.json$/u.test(name))
+          .sort();
+      } catch {
+        throw error;
+      }
+      if (segmentNames.length === 0) throw error;
+
+      if (snapshotExists) {
+        try {
+          const snapshot = parseJournalFile(
+            JSON.parse(readFileSync(path, "utf8")) as unknown,
+            path,
+          );
+          const firstSegmentPath = join(segmentDirectory, segmentNames[0]);
+          const firstSegment = parseJournalSegment(
+            JSON.parse(readFileSync(firstSegmentPath, "utf8")) as unknown,
+            firstSegmentPath,
+          );
+          if (
+            snapshot.revision === undefined &&
+            firstSegment.previousRevision > 0 &&
+            snapshot.profile === firstSegment.profile &&
+            identitiesMatch(snapshot.botIdentity, firstSegment.botIdentity)
+          ) {
+            writeJournalFile(
+              path,
+              serializeJournalFile({
+                ...snapshot,
+                revision: firstSegment.previousRevision,
+              }),
+              onPublicationBoundary,
+            );
+            const repaired = readCurrentStrict();
+            notifyRecovery({
+              kind: "repaired",
+              path,
+              revision: repaired.file.revision,
+              reason: `Recovered a revisionless snapshot from segment revision ${firstSegment.revision}.`,
+            });
+            return repaired;
+          }
+        } catch {
+          // Fall through to evidence-preserving quarantine and reset.
+        }
+      }
+
+      const recoveryDirectory = join(
+        dirname(path),
+        "recovery",
+        `${getNowMs()}-${process.pid}-${randomUUID()}`,
+      );
+      mkdirSync(recoveryDirectory, { recursive: true, mode: 0o700 });
+      const snapshotQuarantinePath = join(recoveryDirectory, basename(path));
+      const segmentQuarantinePath = join(
+        recoveryDirectory,
+        basename(segmentDirectory),
+      );
+      if (
+        snapshotExists &&
+        !renameTelegramPathWithRetry(path, snapshotQuarantinePath)
+      ) {
+        throw createJournalError(
+          "io",
+          path,
+          "could not quarantine an unrecoverable journal snapshot",
+          error,
+        );
+      }
+      if (!renameTelegramPathWithRetry(segmentDirectory, segmentQuarantinePath)) {
+        if (snapshotExists) {
+          renameTelegramPathWithRetry(snapshotQuarantinePath, path);
+        }
+        throw createJournalError(
+          "io",
+          segmentDirectory,
+          "could not quarantine an unrecoverable journal segment history",
+          error,
+        );
+      }
+      const reset = emptyFile();
+      const serialized = serializeJournalFile(reset);
+      const serializedBytes = assertCapacity(reset, serialized);
+      try {
+        writeJournalFile(path, serialized, onPublicationBoundary);
+      } catch (publicationError) {
+        const segmentsRestored = renameTelegramPathWithRetry(
+          segmentQuarantinePath,
+          segmentDirectory,
+        );
+        const snapshotRestored =
+          !snapshotExists ||
+          renameTelegramPathWithRetry(snapshotQuarantinePath, path);
+        if (!segmentsRestored || !snapshotRestored) {
+          throw createJournalError(
+            "io",
+            path,
+            "reset publication failed after journal evidence was quarantined",
+            publicationError,
+          );
+        }
+        throw publicationError;
+      }
+      notifyRecovery({
+        kind: "reset",
+        path,
+        quarantinePath: recoveryDirectory,
+        reason: error.message,
+      });
+      return { file: reset, exists: true, serializedBytes };
+    }
+  };
+
   const runMutation = <T>(operation: () => T): T => {
     try {
       return withTelegramFileTransaction(`${path}.transaction`, operation);

package/lib/outbound.ts

@@ -958,6 +958,10 @@ export function createTelegramAssistantOutputSender<
   ) => Promise<TelegramSentMessage>;
   editMessage: (body: TelegramEditMessageTextBody) => Promise<unknown>;
   getAssistantRenderingMode: () => "rich" | "html";
+  planButtonReply?: (markdown: string) => {
+    markdown: string;
+    replyMarkup?: TReplyMarkup;
+  };
   execCommand: TelegramOutboundTextReplyRuntimeDeps<TReplyMarkup>["execCommand"];
   getHandlers?: TelegramOutboundTextReplyRuntimeDeps<TReplyMarkup>["getHandlers"];
   recordRuntimeEvent?: TelegramOutboundTextReplyRuntimeDeps<TReplyMarkup>["recordRuntimeEvent"];
@@ -997,11 +1001,19 @@ export function createTelegramAssistantOutputSender<
       getHandlers: deps.getHandlers,
       recordRuntimeEvent: deps.recordRuntimeEvent,
     });
+    const buttonReply = deps.planButtonReply?.(event.text) ?? {
+      markdown: event.text,
+    };
     await outboundRuntime.sendMarkdownReply(
       target.chatId,
       undefined,
-      event.text,
-      { target },
+      buttonReply.markdown,
+      {
+        target,
+        ...(buttonReply.replyMarkup
+          ? { replyMarkup: buttonReply.replyMarkup }
+          : {}),
+      },
     );
   };
 }

package/lib/prompts.ts

@@ -7,9 +7,14 @@
 import type { BeforeAgentStartEvent } from "./pi.ts";
 import { TELEGRAM_PREFIX } from "./turns.ts";
 
+export const TELEGRAM_CONNECTED_CONTEXT_MESSAGE =
+  "Telegram session connected. Use Telegram features for Telegram-originated turns or explicit Telegram requests; connectivity alone is not user intent.";
+export const TELEGRAM_DISCONNECTED_CONTEXT_MESSAGE =
+  "Telegram session disconnected. Do not use Telegram delivery, actions, or Telegram-specific reply features unless the user reconnects it.";
+
 const LOCAL_SYSTEM_PROMPT_SUFFIX = `
 
-Telegram bridge available. Load the \`telegram-bridge\` Skill for Telegram delivery, actions, Threaded Mode, or diagnosis. Do not use Telegram from local/TUI prompts unless explicitly asked.`;
+${TELEGRAM_CONNECTED_CONTEXT_MESSAGE} Load the \`telegram-bridge\` Skill for Telegram-originated turns or explicit requests involving Telegram delivery, actions, Threaded Mode, or diagnosis. Do not use Telegram-specific features from unrelated local/TUI prompts.`;
 
 const TELEGRAM_TURN_SYSTEM_PROMPT_SUFFIX = `
 

package/lib/telegram-api.ts

@@ -37,6 +37,8 @@ function getTelegramApiTempDir(): string {
   return resolveTelegramTempDir();
 }
 const TELEGRAM_TEMP_FILE_MAX_AGE_MS = 24 * 60 * 60 * 1000;
+const TELEGRAM_TEMP_SCRATCH_FILE_PATTERN =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}-/u;
 const TELEGRAM_INBOUND_FILE_MAX_BYTES = getTelegramInboundFileByteLimitFromEnv(
   process.env,
   ["PI_TELEGRAM_INBOUND_FILE_MAX_BYTES", "TELEGRAM_MAX_FILE_SIZE_BYTES"],
@@ -1116,7 +1118,9 @@ export async function cleanupTelegramTempFiles(
     return 0;
   }
   for (const entry of entries) {
-    if (!entry.isFile()) continue;
+    if (!entry.isFile() || !TELEGRAM_TEMP_SCRATCH_FILE_PATTERN.test(entry.name)) {
+      continue;
+    }
     const path = join(tempDir, entry.name);
     try {
       const stats = await stat(path);

package/package.json

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

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

@@ -1,6 +1,6 @@
 ---
 name: generated-control-surface
-description: Proactively compiles current state, available capabilities, and user intent into contextual, evidence-backed, ephemeral prompt-button interfaces. Use on Telegram turns and other prompt-button transports whenever controls materially shorten likely feedback, without requiring an explicit user request; route reusable deterministic loops toward Generative Apps, omit decorative UI, and preserve domain ownership while fixed transport menus and callbacks remain with their runtime owners.
+description: Proactively compiles current state, available capabilities, and user intent into contextual, evidence-backed, ephemeral prompt-button interfaces. Use without an explicit button request on Telegram-originated turns when controls materially shorten likely feedback, or when a user explicitly requests controls on another prompt-button transport; connection or proactive projection alone is not activation intent. Route reusable deterministic loops toward Generative Apps, omit decorative UI, and preserve domain ownership while fixed transport menus and callbacks remain with their runtime owners.
 ---
 
 # Generated Control Surface
@@ -29,7 +29,7 @@ This Skill and `generative-apps` share one logical button-matrix and `label + pr
 
 When a generated surface reveals repeated stable interaction with bounded state and deterministic transitions, load the complementary `generative-apps` Skill and consider compiling that loop. A Generative App may retain ordinary model-mediated prompt buttons beside deterministic bound methods, so only the stable actions need bypass inference. Conversely, keep one-off, interpretive, changing, and context-heavy interaction here when a reusable script would add no concrete latency, token, cost, reliability, or UX value.
 
-On Telegram turns, evaluate this Skill proactively rather than waiting for the user to ask for buttons. Load and apply it when a likely next decision, approval, navigation step, inspection, or bounded action can be made materially easier through controls; its correct output may still contain zero buttons when the admission test fails.
+On Telegram-originated turns, evaluate this Skill proactively rather than waiting for the user to ask for buttons. A connected Telegram session, available button syntax, or proactive projection of local output is capability evidence, not activation intent: do not load this Skill for an unrelated local/TUI prompt merely because its answer may also appear in Telegram. Load and apply it when the current turn is Telegram-originated or the user explicitly requests a prompt-button surface and a likely next decision, approval, navigation step, inspection, or bounded action can be made materially easier through controls; its correct output may still contain zero buttons when the admission test fails.
 
 A control surface may expose:
 

package/skills/telegram-bridge/SKILL.md

@@ -7,6 +7,12 @@ description: Operates pi-telegram turns, replies, attachments, direct delivery,
 
 Use pi-telegram as a mobile companion surface for the current Pi session. Preserve the current Telegram target, ordinary reply ownership, durable queue semantics, and the boundary between agent intent and bridge transport.
 
+## Connection Awareness
+
+`Telegram session connected.` means this Pi instance currently has authorized Telegram transport, so Telegram tools and proactive projection may be available. It does not mean the current prompt came from Telegram and does not grant intent to add Telegram actions to unrelated local/TUI work. Use Telegram-specific reply features proactively only on a turn carrying structured Telegram origin; from local/TUI prompts, use them only when the user explicitly requests Telegram delivery or the established workflow is explicitly Telegram-mediated.
+
+`Telegram session disconnected.` revokes that availability. Do not attempt Telegram delivery, actions, buttons, or voice until a later connected context is present. Treat the newest connection-state context as authoritative.
+
 ## Turn Recognition
 
 Telegram-originated prompts carry structured context:
@@ -48,7 +54,7 @@ Use `telegram_attach` outside Telegram turns only when the user explicitly reque
 
 Before compiling assistant-authored controls, inspect already-loaded capability guidance for an advertised maintained Generative App or view/controller adapter. When that owner-provided view exists and the current intent concerns repeated interaction, load and follow the bundled `generative-apps` Skill and prefer binding or invoking the existing app over synthesizing one-shot prompt buttons. This routing guidance is not permission for the bridge to discover capability-specific apps, own their state, or hard-code their identities.
 
-Otherwise, on Telegram turns, proactively load `generated-control-surface` when a likely next decision or action may benefit from prompt buttons; do not wait for an explicit button request, and accept zero controls when its admission rules reject decorative or low-value UI.
+Otherwise, only on Telegram-originated turns, proactively load `generated-control-surface` when a likely next decision or action may benefit from prompt buttons; do not activate it merely because Telegram is connected or local output may be projected by proactive push. Do not wait for an explicit button request on a Telegram-originated turn, and accept zero controls when its admission rules reject decorative or low-value UI.
 
 `telegram_button` and `telegram_voice` are hidden top-level HTML comments, not tools. Emit them at column zero, outside lists, quotes, code blocks, and indentation.