Reliability roadmap¶
Research dated 12 September 2026, against the v0.1.9-era implementation and pinned gotd v0.144.0. Reliability repairs were subsequently authorized. This document preserves the independently researched feature proposals; B/C features are not implied to have been implemented. See reliability for the repaired contract and verification scope.
Priorities: A (correctness and reliability) precedes B (everyday additions), then C (optional); D is deliberately excluded. Keep gotd, Cobra and SQLite. No feature-parity rewrite or dependency upgrade is required to implement the selected repairs.
Primary-source comparison
The comparator sample is deliberately small: gotd/cli for practical CLI workflows, Telethon for mature account APIs, and official TDLib for update/storage behavior. Their documentation is capability evidence, not proof their implementations are bug-free or that every feature belongs here.
| Source | Observed capability and relevant lesson |
|---|---|
| gotd/cli README, commit history | Current upstream documents explicit config paths, Saved Messages selectors, server history/search, context retrieval, archive/mute, drafts, timeout-bounded watching, and macOS Keychain sessions. Borrow bounded workflows and clear identities; do not copy account fan-out, credential embedding, or broad feature scope automatically. |
| Telethon 1.45 client reference, changelog | Iterators for dialogs/history, explicit permissions queries, logout, read acknowledgement, and catch-up are established client workflows. Its documented current version and recent layer updates support using it as a maintained comparator. No dependency migration is recommended. |
| TDLib, maintainer changelog | Provides ordered updates, network recovery and local storage as library responsibilities. The lesson is to test end-to-end durability; adopting TDLib would introduce a major integration/build change without solving the CLI's contract defects by itself. |
| gotd releases | The retrieved release index shows v0.161.0 and a v0.159.0 channel-difference concurrency limit. This is newer than the pinned v0.144.0. The index and package site's latest marker disagree, so treat v0.161.0 as the latest observed release, not a guarantee of the newest available tag. Select an upgrade only after a focused compatibility review. |
The pinned module was downloaded during ordinary test setup and inspected directly. Proposed core APIs below are already generated in v0.144.0 unless explicitly stated otherwise. Newer web documentation may include additional fields absent from that version; do not copy current examples blindly.
New everyday capabilities worth adding after repairs (class B)
Each row is a bounded proposal, not approval to implement. Cost includes adapter/CLI tests but not a rewrite. Remote reads may still update session bookkeeping and encounter waits; keep their source explicit.
| ID / gap | Concrete use case and evidence | API/dependency support, account safety, complexity and required tests |
|---|---|---|
| B1: bounded remote history/search/get | Find an older message without backfilling an entire chat. Existing show/list/search/get are local DB reads (read runners); absence from cache is not absence on Telegram. Telethon and gotd/cli expose server retrieval. | Add explicit source selection, sender/date/media filters, a continuation cursor and cache-coverage metadata; never silently change existing local semantics. messages.search, getHistory, getMessages/channels.getMessages are in v0.144.0. M. Cursor overlap/ties, empty pages, server truncation, denied/private peers, deleted result, account-bound cursors, limit and FLOOD_WAIT tests. No read acknowledgement hidden inside search. |
| B2: thread/context retrieval and complete topic targeting | Read the replies to one message or a channel discussion before responding; retrieve topic history without whole-chat scraping. Topic list/create/edit/pin and simple reply already exist, but no getReplies/discussion operation is exposed, and history loses reply metadata. | getReplies, getDiscussionMessage, forum APIs and InputReplyToMessage are already generated. M. Preserve separate broadcast/discussion peer IDs; never join a discussion automatically. Tests: pagination, root-only/empty/deleted roots, forum/general topic, topic-plus-reply routing, membership denial, service-message context. |
| B3: explicit resolve and Saved Messages target | Resolve one @username or self deterministically without first scanning dialogs; inspect the typed identity and then use it for an action. Username sends now share the write pipeline; a standalone resolve/self command is still absent. gotd/cli exposes resolve/self selectors. | Existing ContactsResolveUsername and InputPeerSelf; consolidate under the same target/fingerprint pipeline. S/M. Preserve zero-network dry-run: unresolved previews must say resolution pending. Test renamed/reassigned username between preview/execution, missing/min entities, explicit self, ambiguous titles and account changes. Do not silently infer a recipient. |
| B4: current-session logout | Revoke this CLI's authorization before retiring a machine. Account removal only deletes local files (accounts-remove); listing/terminating other sessions already exists. Telethon exposes logout separately. | auth.logOut exists in pinned gotd. S/M. Explicit account and confirmation; close the runtime, acknowledge remote result, then handle local cleanup. Tests: already revoked, remote error, ambiguous result, local cleanup failure, unrelated session preserved. Never report “revoked” after merely deleting a file. |
| B5: live permissions and full chat details | Explain why an action is disallowed before a user chooses moderation or sending; chats-info now fetches live peer-dialog metadata and basic rights, but full chat details and effective per-member rights remain incomplete. Telethon has get_permissions. | ChannelsGetParticipant, ChannelsGetFullChannel, MessagesGetFullChat, peer rights and slow-mode fields exist. M. Show freshness and distinguish permissions from guarantees; the server remains authoritative at write time. Tests: owner/admin/member/banned, basic group/channel/forum, lost access, expired restrictions, rights changing after inspection. |
| B6: archive/unarchive and mute/unmute | Triage noisy chats without leaving them. Custom folder membership already exists, but archive and notification settings are separate absent operations. gotd/cli documents both. | folders.editPeerFolders, account.updateNotifySettings in v0.144.0. S/M. Explicit per-peer writes, preserve unrelated notify settings, no account-wide change by default. Test archived/pinned behavior, mute-until timezone/expiry, no-op replay and default-versus-explicit notification settings. |
| B7: basic contact maintenance | Add/remove a known person's contact after explicit user intent. Existing contacts/sync-contacts are reading/caching; block/unblock already exist. No need for address-book harvesting. | contacts.addContact, ContactsDeleteContacts and current contact cache. S/M. Phone sharing is an explicit choice; use known typed user targets. Tests: duplicate/non-contact/deleted user, phone-sharing flag absent by default, failed refresh after success, dry-run and wrong-account protection. |
| B8: formatted text and consistent safe input | Send a readable code block or link; preserve incoming formatting in output. Existing text/stdin support should remain, but no entity formatting contract exists. | Telegram text entities, gotd entity types and message-building helpers. M. Plain text stays default; structured entities or one explicit parse mode, no automatic splitting/sending of arbitrarily long input. Tests: UTF-16 offsets, surrogate pairs, overlapping/invalid entities, length limits, captions, stdin bound and fingerprint differences. |
Real unread state, pin semantics, dialog pagination and full metadata are A repairs, not B feature expansion. B1 adds server-query usability beyond repairing existing pagination. B2 adds thread retrieval beyond repairing current reply flags.
Later / optional (class C)
| Proposal | Benefit, evidence and API support | Safety, complexity and tests before considering it |
|---|---|---|
| Draft save/list/delete | Compose on CLI and finish on phone. Missing; gotd/cli and Telethon expose drafts; pinned MessagesSaveDraft/GetAllDrafts support it. | Drafts synchronize to other devices and can overwrite user work. M. Explicit save, preserve reply/entities, conflict tests, deleted peer and no-send assurance. |
| One-off scheduled messages with list/cancel | Send a specifically approved message later; not a recurring automation engine. Missing; pinned SendMessage.ScheduleDate and scheduled-history/delete APIs support it. | Deferred writes require visible target/time and cancellation, stable IDs and no duplicate schedules. M. UTC/DST, past time, edit/cancel, ambiguity and delivery-vs-scheduling status. |
| Topic close/reopen and hide/unhide | Existing topic-edit exposes title/icon only although the dependency supports Closed/Hidden. Useful for forum administration, not required for ordinary messaging. | M. Explicit admin action, general-topic restrictions, absent versus false flag tests, insufficient rights and replay. |
| Session storage in OS credential vaults | Reduce plaintext session-key exposure; gotd/cli documents macOS Keychain. gotd's session.Storage permits alternate implementations; this needs an OS integration, not a new Telegram API. | M/L. Headless/keychain-locked cases, migration rollback, account namespacing, no-secret diagnostics, Linux/Windows strategy. Atomic protected files remain the baseline. |
| Transfer progress and bounded concurrency | Improve long album/download usability; current sequential/atomic paths already work. Telegram files and gotd uploader/downloader are the basis. | M. Progress only on stderr, cancellation, aggregate size/concurrency caps, waits and low-disk failure. Do not add range resume until file-reference/CDN/identity/atomicity behavior is demonstrated for the selected dependency. |
These are deliberately deferred, not hidden prerequisites for daily-use readiness. Native poll/sticker authoring, broad profile management and invite administration can remain in the official client until a concrete recurring need justifies their test and maintenance cost.
Do not build in this roadmap (class D)
- MCP implementation, CRM/customer management, Notion/Sedex integrations, or a new application: explicitly outside scope. Preserve a reusable internal operation boundary only.
- Mass unsolicited messaging, bulk contact import/phone enumeration, scraped member databases, automatic joining/inviting, account rotation, restriction evasion, or deliberate live flood-limit probes: incompatible with the authorized legitimate-use goal. Telegram's application guidance warns about abuse and account restrictions.
- Automatic resend of unknown outcomes, arbitrary raw-RPC command escape hatches, silent target inference, blanket admin grants, or unattended auto-replies driven by untrusted incoming messages: undermine the contract rather than improve it.
- Permanent preservation of expiring/view-once content, secret-chat history “recovery,” protected-content workarounds, or ghost/read-status evasion: unacceptable semantics. Secret chats require a separate end-to-end state model; ordinary cloud history APIs do not supply them.
- Calls/video conferencing, stories, games, Stars/payments/gifts, marketplace features, business-account tooling, and generalized bots/Mini Apps: large or sensitive scope with no demonstrated benefit here. Do not set paid-send/floodskip fields implicitly.
- AI training datasets, indiscriminate indexing/embeddings, bulk summarization or broad content ingestion: not authorized by an account owner's API access alone. Future AI use needs a separately established permitted scope; a CLI command's existence is not permission to feed its output to a model.
Account-safety and terms constraints
There is no universal user-account request rate that guarantees freedom from restriction. Honor the server's wait, report permission/auth failures, avoid repeated reconnect/auth attempts, and limit background work. Treat the local rate setting as a guardrail, never a Telegram-certified allowance. Do not add retry middleware that blindly retries an ambiguous final write.
Current API terms address consent, correct core behavior, read/status handling, expiry, and sponsored-message support for channel access. At the original review the CLI had no sponsored-message implementation. The later local reader adds a bounded human display surface, while existing headless surfaces remain an open scope question; retaining channel-reading support requires a deliberate compliant display/accounting design using the sponsored-message API, or a narrower supported mode. This is an A release-scope requirement to resolve, not a suggestion to build an advertising platform. Complexity M; test labeled output, empty responses, applicable client events and no fabricated view/click reporting. Cached inspection must not be marketed as an invisibility feature.
The content-licensing terms expressly restrict AI-related use and describe possible exceptions tied to explicit, ongoing consent from all relevant users within a specific context. Do not assume the present account owner can grant consent for everyone. This report makes no legal determination that a particular future agent workflow qualifies; it separates reliable programmatic CLI operation from permission for AI processing. No Telegram content was ingested during this analysis.
Execution order¶
- Complete A repairs and offline verification: peer/session identity, durable write outcomes, permissions/deletion semantics, recovery checkpoints, truthful reads, storage/privacy/waits.
- Review native OS CI and current-schema validation. Any live acceptance uses separately authorized test accounts and targets.
- Consider B1–B5 individually, with the evidence, account-safety implications, complexity and tests above. B6–B8 follow demonstrated demand.
- C remains optional. Do not implement D.
The comparison is evidence of API availability and useful workflows, not a claim that comparator implementations are bug-free or that local offline tests establish Telegram account safety.