telstore 0.1.8 → 0.1.9

package/README.md

@@ -28,6 +28,7 @@ npx telstore restore telstore-20260905-7f3a91
 | `telstore <file\|folder\|pattern>...` | Split each file and upload it. Prints the `backupId` you restore with. |
 | `telstore list` | The backups stored in the destination, newest first. |
 | `telstore restore <backup-id>...` | Download every chunk and reassemble the file. Several ids run one after another. |
+| `telstore verify <backup-id>...` | Check that every chunk of a backup is still in the chat. Downloads nothing. |
 | `telstore delete <backup-id>...` | Remove a backup's chunks and manifest from the chat, for good. Several ids are listed and confirmed once. |
 | `telstore status` | Account, destination, and unfinished uploads and restores. |
 | `telstore config` | Show or change settings. |
@@ -65,7 +66,7 @@ a prompt that does not echo.
 
 Every chunk goes up as a document captioned `📦 <backupId> · 3/12`, followed by a manifest
 carrying a summary card — file name, size, id, date and the restore command. `list` reads
-those cards straight out of the chat, one search and no downloads:
+those cards straight out of the chat, no downloads:
 
 ```
 Destination  https://web.telegram.org/k/#@my_backups
@@ -117,13 +118,44 @@ it, and the run ends with a line per file and a non-zero exit code:
   c.tar  telstore-20260905-9de447  (1 chunk)
 ```
 
+## Checking a backup is still there
+
+A backup is a set of messages in a chat, and messages can be deleted by hand. `list` reads
+the manifest's card and would happily show a backup whose chunks are long gone; `verify` asks
+the chat about every chunk the manifest names:
+
+```
+$ npx telstore verify telstore-20260905-7f3a91
+Backup telstore-20260905-7f3a91
+File   data.tar (21.4 GB, 12 chunks)
+In     https://web.telegram.org/k/#@my_backups
+
+12 chunks present, at the sizes the manifest records.
+This does not download them, so it cannot prove their contents.
+```
+
+It costs one request per hundred chunks and no bandwidth, so it is cheap enough to run on a
+schedule. What it proves is that a restore would find everything it needs — every chunk still
+there, under the file name telstore wrote, at the length the manifest records. It does not
+read the chunks, so it cannot speak for what is inside them; only a restore does that, and a
+restore checks every sha256 before it renames anything into place.
+
+A backup missing chunks is named line by line, and the exit code is 1:
+
+```
+Chunk 3/12 is gone: message 1042 is no longer in @my_backups.
+
+12 chunks checked, 1 damaged. This backup cannot be restored.
+```
+
 ## Several backups at once
 
-`restore` and `delete` take a list of ids the same way, over one connection, with a summary
-and a non-zero exit code if any of them failed:
+`restore`, `verify` and `delete` take a list of ids the same way, over one connection, with a
+summary and a non-zero exit code if any of them failed:
 
 ```bash
 npx telstore restore telstore-20260905-7f3a91 telstore-20260901-9de447
+npx telstore verify telstore-20260905-7f3a91 telstore-20260901-9de447
 npx telstore delete telstore-20260905-7f3a91 telstore-20260901-9de447
 ```
 
@@ -180,7 +212,8 @@ There is no expiry and no revocation: to end a session for good, terminate it un
   protects your login rather than your files.
 - A chunk cannot exceed 1950MB: Telegram accepts at most 4000 parts of 512KB per file.
 - Deleting a chunk message in the Telegram app destroys the backup, and keeping the
-  `backupId` is what saves you hunting for its manifest in the chat by hand.
+  `backupId` is what saves you hunting for its manifest in the chat by hand. `verify` is how
+  you find that out before you need the file rather than after.
 
 Settings and credentials live in `~/.telstore/config.json`, mode 600 — `apiId`, `apiHash` and
 the session at the top level (or a single `sealed` blob after `login --token`), everything

package/bin/telstore.js

@@ -134,6 +134,21 @@ async function main() {
       return
     }
 
+    case 'verify': {
+      if (!parsed.args[0]) {
+        throw new Error('Missing backup id. Example: npx telstore verify telstore-20260905-7f3a91')
+      }
+
+      const { runVerifies } = await import('../src/commands/verify.js')
+
+      const { failed } = await runVerifies(parsed.args, parsed.options)
+
+      // A backup that is damaged, and one telstore could not look up at all, both mean the
+      // run did not find what it was asked to check. Whatever runs telstore learns that here.
+      if (failed > 0) process.exitCode = 1
+      return
+    }
+
     case 'delete': {
       if (!parsed.args[0]) {
         throw new Error('Missing backup id. Example: npx telstore delete telstore-20260905-7f3a91')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "telstore",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "Split large files into chunks and store them on Telegram",
   "keywords": [
     "telegram",

package/src/cli.js

@@ -6,6 +6,7 @@ const SUBCOMMANDS = new Set([
   'logout',
   'list',
   'restore',
+  'verify',
   'delete',
   'status',
   'config',
@@ -21,6 +22,7 @@ const OPTIONS = {
   out: { type: 'string' },
   note: { type: 'string' },
   limit: { type: 'string' },
+  search: { type: 'string' },
   verbose: { type: 'boolean' },
   unset: { type: 'boolean' },
   yes: { type: 'boolean' },
@@ -34,7 +36,9 @@ Usage:
   npx telstore login                      Log in to Telegram, only needed once
   npx telstore <file|folder|pattern>...   Split files and upload them to Telegram
   npx telstore list                       List the backups stored in the destination
+  npx telstore list --search <text>       List only the backups that text appears in
   npx telstore restore <backup-id>...     Download the chunks and reassemble the files
+  npx telstore verify <backup-id>...      Check that a backup's chunks are all still in the chat
   npx telstore delete <backup-id>...      Remove backups' chunks and manifests from the chat
   npx telstore status                     Show the account, the destination and unfinished uploads and restores
   npx telstore config                     Show every setting and where its value comes from
@@ -50,8 +54,10 @@ backup. A folder means the files one level inside it, and a pattern means the na
 one file is listed and confirmed before the first byte goes out. Run telstore again with only
 the files that are left to carry on after an interruption.
 
-restore and delete take several ids the same way: one connection, one line each, and an exit
-code that reports any that failed. delete shows everything it is about to destroy and asks once.
+restore, verify and delete take several ids the same way: one connection, one line each, and
+an exit code that reports any that failed. delete shows everything it is about to destroy and
+asks once. verify downloads nothing: it asks the chat whether every chunk message is still
+there at the length the manifest records, which is what restore would need.
 
 Settings:
   npx telstore config <name>              Print one setting's value
@@ -80,6 +86,12 @@ Options apply to one run and are never saved. Use config to change a setting for
                               shell hands the words after the first to telstore as more files
                               to upload.
   --limit <n>                 How many backups list shows this run.
+  --search <text>             List only the backups whose file name, note, backup id or
+                              creation day contains this text. Telegram's own index does
+                              the looking, so the whole chat is reached without reading it
+                              message by message — but it matches whole words only:
+                              "projex" finds projex.zip and "proj" finds nothing. A term
+                              with spaces has to be quoted, as --note does.
   --token                     Log in by pasting a session token. It takes no value on
                               purpose: a token written on the command line would sit in
                               "ps" for the whole life of the command, and stay in that

package/src/client.js

@@ -1,8 +1,10 @@
 import { Api, TelegramClient } from 'teleproto'
 import { Logger } from 'teleproto/extensions/index.js'
 import { LogLevel } from 'teleproto/extensions/Logger.js'
+import { returnBigInt } from 'teleproto/Helpers.js'
 import { StringSession } from 'teleproto/sessions/index.js'
 
+import { MANIFEST_TAG } from './caption.js'
 import { manifestFileName } from './manifest.js'
 import { withRetry } from './retry.js'
 import { assertLoggedIn, unlockConfig } from './session.js'
@@ -23,6 +25,26 @@ export function documentFileName(message) {
   return named?.fileName ?? null
 }
 
+// Telegram records a document's length as a BigInteger, and comparing that to the plain
+// number a manifest carries with === is false for every size there is.
+export function documentSize(message) {
+  const size = message?.media?.document?.size
+
+  return size === undefined || size === null ? null : returnBigInt(size).toJSNumber()
+}
+
+// The flat shape both readers of a chat hand back. The raw message is kept alongside it
+// because downloading needs it whole.
+function toDocument(message) {
+  return {
+    id: message.id,
+    fileName: documentFileName(message),
+    caption: message.message ?? '',
+    date: message.date,
+    message,
+  }
+}
+
 // The one place telstore searches a chat. Both callers want documents and nothing else,
 // and getMessages is preferred over a raw Api.messages.Search because it handles offsets,
 // hashes and pagination itself, so we don't hand-build easily mistyped fields. The raw
@@ -34,13 +56,93 @@ export async function searchDocuments(client, peer, { search, limit }) {
     limit,
   })
 
-  return messages.map((message) => ({
-    id: message.id,
-    fileName: documentFileName(message),
-    caption: message.message ?? '',
-    date: message.date,
-    message,
-  }))
+  return messages.map(toDocument)
+}
+
+// The paging both readers share. It is ours rather than iterMessages', for the reasons
+// deleteMessages does not use teleproto's: every page then carries the retry policy and the
+// stall deadline, and a page that fails is retried by itself instead of restarting from the
+// newest message. offsetId is the id of the last message of the page before, and Telegram
+// answers with the messages older than it — a reader that forgot to advance it would fetch
+// the newest page over and over and never reach an older backup.
+//
+// A generator because the caller stops when it has what it wants: a chat of ten thousand
+// chunks costs one request to list the backups at the top of it.
+export const DOCUMENT_PAGE_SIZE = 100
+
+async function* iterMessagePages(client, peer, { search, what, options }) {
+  const {
+    pageSize = DOCUMENT_PAGE_SIZE,
+    max = Infinity,
+    retryOptions = {},
+    stallMs = DEFAULT_STALL_MS,
+  } = options
+
+  let offsetId = 0
+  let read = 0
+
+  while (read < max) {
+    const limit = Math.min(pageSize, max - read)
+
+    const messages = await withRetry(
+      () =>
+        withStallTimeout(
+          client.getMessages(peer, {
+            ...(search === undefined ? {} : { search }),
+            filter: new Api.InputMessagesFilterDocument(),
+            limit,
+            offsetId,
+          }),
+          stallMs,
+          () =>
+            `Telegram stopped answering while reading the ${what} older than message ` +
+            `${offsetId}: nothing back for ${Math.round(stallMs / 1000)}s.`,
+        ),
+      retryOptions,
+    )
+
+    if (!messages || messages.length === 0) return
+
+    for (const message of messages) yield toDocument(message)
+
+    read += messages.length
+    offsetId = messages[messages.length - 1].id
+
+    // A short page is the end of the results. Asking again would cost a request to be told
+    // the same thing.
+    if (messages.length < limit) return
+  }
+}
+
+// What `list` reads the chat with. searchDocuments asks Telegram's text index a question;
+// this asks for the documents themselves, newest first, which is the only answer that was
+// right every time it was measured — a chat's text index can come back empty while the chat
+// is full of backups, and did for a whole day in a channel that had just been created
+// (docs/design/captions.md carries the measurements).
+export async function* iterDocuments(client, peer, options = {}) {
+  yield* iterMessagePages(client, peer, { what: 'documents', options })
+}
+
+// What `list --search` reads the chat with, and the one place that knows how to ask the index
+// for backups. Two things about the query are load-bearing, both measured against a real chat
+// on 2026-09-08 (docs/design/captions.md carries the numbers):
+//
+// The tag is ANDed in because a term alone brings the backup's chunk messages back too — a
+// chunk caption carries the id — and on a backup of a few hundred chunks those would fill
+// every page before a single manifest appeared. `#telstore` rides on the manifest alone, so
+// the results come back manifests only: searching one backup id returned 1 manifest and 1
+// chunk, and the same id with the tag returned the manifest by itself.
+//
+// The tag goes *after* the term, never before. A query that starts with the hash is read as
+// a hashtag lookup and stops ANDing the rest: "#telstore projex" came back empty while
+// "projex #telstore" returned the one manifest. Leading it would turn every search into
+// "no backups found", which is the sentence this project must never say wrongly.
+export async function* iterManifestSearch(client, peer, term, options = {}) {
+  yield* iterMessagePages(client, peer, {
+    search: `${term} ${MANIFEST_TAG}`,
+    what: 'search results',
+    options,
+  })
 }
 
 // How telstore finds a backup's manifest, in one place because restore and delete must not
@@ -70,11 +172,15 @@ export async function readMessageBytes(client, message) {
 //
 // Telegram does not complain about an id that is no longer there, so sending a batch twice
 // costs nothing: a delete interrupted halfway is finished by running it again.
-export const DELETE_BATCH_SIZE = 100
+//
+// The hundred is Telegram's own limit on how many message ids one request may name, and it
+// is the same limit whether the request removes them or asks about them — so getDocuments
+// below counts in the same batches rather than keeping a second opinion about one number.
+export const MESSAGE_BATCH_SIZE = 100
 
 export async function deleteMessages(client, peer, ids, options = {}) {
   const {
-    batchSize = DELETE_BATCH_SIZE,
+    batchSize = MESSAGE_BATCH_SIZE,
     retryOptions = {},
     stallMs = DEFAULT_STALL_MS,
     onBatch,
@@ -110,6 +216,53 @@ export async function deleteMessages(client, peer, ids, options = {}) {
   return deleted
 }
 
+// What verify asks the chat, and the read-only mirror of deleteMessages above: our own
+// batching, one request in flight at a time, under the same retry policy and the same stall
+// deadline as every other network wait in telstore.
+//
+// The answer is a Map rather than a list because the question is "which of these are still
+// there". Telegram reports a message that is gone as MessageEmpty — an object carrying the
+// id it was asked about — so anything that is not a real message is left out here, where the
+// shape is understood, rather than passed on to a caller that would read an empty as a chunk
+// still sitting in the chat.
+export async function getDocuments(client, peer, ids, options = {}) {
+  const {
+    batchSize = MESSAGE_BATCH_SIZE,
+    retryOptions = {},
+    stallMs = DEFAULT_STALL_MS,
+    onBatch,
+  } = options
+
+  const found = new Map()
+
+  for (let start = 0; start < ids.length; start += batchSize) {
+    const batch = ids.slice(start, start + batchSize)
+
+    const messages = await withRetry(
+      () =>
+        withStallTimeout(
+          client.getMessages(peer, { ids: batch }),
+          stallMs,
+          () =>
+            `Telegram stopped answering while looking up messages ${start + 1}-` +
+            `${start + batch.length} of ${ids.length}: nothing back for ` +
+            `${Math.round(stallMs / 1000)}s.`,
+        ),
+      retryOptions,
+    )
+
+    for (const message of messages ?? []) {
+      if (!message || message instanceof Api.MessageEmpty) continue
+
+      found.set(message.id, message)
+    }
+
+    onBatch?.(Math.min(start + batch.length, ids.length), ids.length)
+  }
+
+  return found
+}
+
 // Every command ends by putting the connection down, and a failure there must never
 // swallow the real error already on its way up. Commands that print progress hand in an
 // onWarn to say so; the quieter ones let it pass, because a connection that will not

package/src/commands/delete.js

@@ -2,7 +2,7 @@ import { promises as fs } from 'node:fs'
 
 import { chatName, describeChat } from '../chat.js'
 import {
-  DELETE_BATCH_SIZE,
+  MESSAGE_BATCH_SIZE,
   closeQuietly,
   connect as realConnect,
   deleteMessages as realDeleteMessages,
@@ -181,7 +181,7 @@ export async function runDelete(backupId, options = {}, deps = {}) {
       throw new Error('Cancelled on request.')
     }
 
-    const loud = chunkIds.length > DELETE_BATCH_SIZE
+    const loud = chunkIds.length > MESSAGE_BATCH_SIZE
     let removed = 0
 
     try {

package/src/commands/list.js

@@ -1,11 +1,13 @@
-import { MANIFEST_TAG, parseManifestCaption } from '../caption.js'
+import { parseManifestCaption } from '../caption.js'
 import { chatName, describeChat } from '../chat.js'
 import {
   closeQuietly,
   connect as realConnect,
-  searchDocuments,
+  iterDocuments,
+  iterManifestSearch,
 } from '../client.js'
 import { configFile, defaultConfigDir, loadConfig } from '../config.js'
+import { MANIFEST_SUFFIX } from '../manifest.js'
 import { assertLoggedIn } from '../session.js'
 import { requireChat, resolveSettings } from '../settings.js'
 
@@ -30,15 +32,48 @@ function shorten(note) {
   return note.length > NOTE_WIDTH ? `${note.slice(0, NOTE_WIDTH - 1)}…` : note
 }
 
-// Telegram indexes the tag the manifest caption carries, so one search returns one hit
-// per backup instead of one per chunk. What comes back is still whatever the server
-// decided to match, which is why the caller filters on the file name afterwards.
-async function realSearchManifests(client, peer, limit) {
-  return await searchDocuments(client, peer, { search: MANIFEST_TAG, limit })
+// What list has to read through depends on how big the backups are, not how many there are:
+// it walks from the newest message down and stops the moment it has --limit manifests, so the
+// three thousandth backup in a chat costs nothing because it is never reached. What costs is
+// the chunks in between — one message each — which is why the ceiling is a budget per backup
+// asked for rather than one number for every chat.
+//
+// 60 documents per backup covers a backup of about 105GB at the default chunk size. A fixed
+// 1000 was both too tight and too loose at once: twenty backups of 100GB need 1140 documents
+// and got 1000 of them, while `--limit 5` never needed more than 300.
+export const DOCUMENTS_PER_BACKUP = 60
+
+// A search result is already a manifest, so it buys far more backups per document read. Its
+// budget only has to cover what matchesTerm throws away — measured 2026-09-08, a term like
+// "2026-09" comes back matching everything and is then cut down to the month asked for.
+export const RESULTS_PER_BACKUP = 20
+
+// --limit takes any whole number, so the budget needs an end of its own: without one,
+// `--limit 100000` would ask for six million documents and sixty thousand requests.
+export const MAX_LIST_DOCUMENTS = 10000
+
+export function documentBudget(limit, perBackup) {
+  return Math.min(limit * perBackup, MAX_LIST_DOCUMENTS)
 }
 
+// Stopping at the ceiling used to leave the reader standing there: "there may be older backups
+// further back" is true and offers nothing to do about it. --search reaches them without
+// reading the chunks in between, which is the whole reason it exists.
+const DEEPER_HINT =
+  '"npx telstore list --search <text>" reaches older ones without reading every chunk ' +
+  'in between.'
+
+// Telegram matches whole words and nothing shorter: measured 2026-09-08, "projex" found
+// projex.zip while "proj", "pro" and "pr" each found nothing at all. That is the one way a
+// search can come back empty over a backup that is plainly there, so the empty answer says
+// it, and points at the listing that never asks the index.
+const SEARCH_MISS_HELP =
+  'Telegram matches whole words: "projex" finds projex.zip, "proj" does not. ' +
+  'Run "npx telstore list" without --search to see every backup without going through ' +
+  'the search index.'
+
 function backupIdFromFileName(fileName) {
-  return fileName.replace(/\.manifest\.json$/, '')
+  return fileName.slice(0, -MANIFEST_SUFFIX.length)
 }
 
 function utcDay(unixSeconds) {
@@ -74,6 +109,76 @@ function toRow(message) {
   }
 }
 
+// A search term is a question about one run, and an empty one is not a question: answering
+// it with every backup would look exactly like a search that matched everything.
+function parseSearchTerm(raw) {
+  if (raw === undefined || raw === null) return null
+
+  const term = String(raw).trim()
+
+  if (term === '') {
+    throw new Error(
+      '--search is empty. Write the word to look for, or leave the flag off — "list" ' +
+        'without it shows every backup.',
+    )
+  }
+
+  return term
+}
+
+// The four fields a person remembers about a backup, and the whole of what --search compares
+// against. The note is matched entire rather than the 40 characters the table has room for:
+// a word that fell off the end of the column is still a word they typed. A card that cannot
+// be read back leaves only what the message itself knows.
+function searchableFields(message) {
+  const id = backupIdFromFileName(message.fileName)
+  const card = parseManifestCaption(message.caption)
+
+  if (!card) return [id, utcDay(message.date)]
+
+  return [id, card.name, card.note ?? '', card.createdAt.slice(0, 10)]
+}
+
+// Telegram decides what comes back; this decides what is true. The index answers a term the
+// way it wants to — measured 2026-09-08, "2026-09" returned every document in the chat — so
+// a hit is shown only if the term really is in one of the fields above. Without this pass a
+// search for a month would list backups from every other month, which is the plausible wrong
+// answer this project exists to refuse.
+function matchesTerm(message, term) {
+  return searchableFields(message).some((field) => field.toLowerCase().includes(term))
+}
+
+// A walk of one page is over in about the time it takes to notice — 165ms against a real
+// chat — and that is the usual case, so nothing is drawn for the first stretch: a line that
+// appears and is wiped in the same breath is a flicker, not information. Past that the read
+// is long enough that silence reads as the hang this project refuses everywhere else.
+//
+// \r only moves the cursor home, so every line is padded to the widest one drawn and the last
+// write wipes the row: the table that follows must never land on half a progress line.
+const NOTICE_QUIET_MS = 400
+const NOTICE_INTERVAL_MS = 200
+
+function createWalkNotice({ write, now, quietMs = NOTICE_QUIET_MS, intervalMs = NOTICE_INTERVAL_MS }) {
+  const startedAt = now()
+  let lastDrawnAt = 0
+  let widest = 0
+
+  return {
+    tick(text) {
+      if (now() - startedAt < quietMs) return
+      if (lastDrawnAt !== 0 && now() - lastDrawnAt < intervalMs) return
+
+      lastDrawnAt = now()
+      widest = Math.max(widest, text.length)
+      write(`\r${text.padEnd(widest)}`)
+    },
+    clear() {
+      if (widest === 0) return
+      write(`\r${' '.repeat(widest)}\r`)
+    },
+  }
+}
+
 function renderTable(rows) {
   // Most people never write a note, and a column of dashes tells them nothing they did not
   // already know while costing every other column the width it takes.
@@ -102,12 +207,21 @@ export async function runList(options = {}, deps = {}) {
     configDir = defaultConfigDir(),
     connect = realConnect,
     disconnect = (client) => client.destroy(),
-    searchManifests = realSearchManifests,
+    readDocuments = iterDocuments,
+    searchManifests = iterManifestSearch,
     log = (line) => console.log(line),
+    // The notice is drawn on stderr, and only onto a terminal: unlike an upload's progress
+    // bar, `list` is a command people pipe into grep, and a carriage return in a log file is
+    // rubbish. Null means draw nothing at all.
+    writeProgress = process.stderr.isTTY ? (text) => process.stderr.write(text) : null,
+    now = () => Date.now(),
   } = deps
 
   const config = await loadConfig(configDir)
   const { values: settings } = resolveSettings(options, config, { file: configFile(configDir) })
+  // Before the login gate: a bad term is the user's own typing, and telling them to log in
+  // first would send them off after the wrong thing.
+  const term = parseSearchTerm(options.search)
   // Ask about the login before the destination: telling someone who has never logged in
   // to pick a chat sends them off after the wrong thing.
   assertLoggedIn(config)
@@ -115,29 +229,99 @@ export async function runList(options = {}, deps = {}) {
 
   const client = await connect(config, { verbose: settings.verbose })
 
-  let found
+  // Walked rather than searched, unless a term was given. Telegram's text index can answer
+  // nothing at all about a chat that is full of backups — it did for a whole day in a channel
+  // that had just been created — and "No backups found" is a sentence someone acts on. The
+  // documents themselves were right every time they were asked for.
+  //
+  // --search is the one place worth paying the index for: a term matches a backup that may be
+  // ten thousand messages back, and walking to it would cost a request per hundred documents
+  // in between, every time, for as long as the chat keeps growing. So the search narrows and
+  // matchesTerm decides — the index is asked where to look, never what is true.
+  const found = []
+  let read = 0
+
+  const unit = term ? 'search results' : 'documents'
+  const budget = documentBudget(settings.limit, term ? RESULTS_PER_BACKUP : DOCUMENTS_PER_BACKUP)
+
+  const results = term
+    ? searchManifests(client, chat, term, { max: budget })
+    : readDocuments(client, chat, { max: budget })
+
+  const wanted = term === null ? null : term.toLowerCase()
+  const notice = writeProgress ? createWalkNotice({ write: writeProgress, now }) : null
+
   try {
-    found = await searchManifests(client, chat, settings.limit)
+    for await (const document of results) {
+      read += 1
+
+      notice?.tick(
+        `Reading ${chatName(chat)}… ${read} ${unit}, ${found.length} backup` +
+          `${found.length === 1 ? '' : 's'}`,
+      )
+
+      if (!document.fileName?.endsWith(MANIFEST_SUFFIX)) continue
+      if (wanted !== null && !matchesTerm(document, wanted)) continue
+
+      found.push(document)
+
+      // Everything past here is older than the twentieth newest backup, and nobody asked
+      // for it. In a chat of ten thousand chunks this is the difference between one
+      // request and ten.
+      if (found.length >= settings.limit) break
+    }
   } finally {
+    notice?.clear()
     await closeQuietly(client, disconnect)
   }
 
+  // The one thing either reader cannot see is what lies past its own ceiling, so anything it
+  // says about the whole chat has to stop at the edge of what it read.
+  const capped = found.length < settings.limit && read >= budget
+
   log(`Destination  ${describeChat(chat)}`)
+  if (term) log(`Search       ${JSON.stringify(term)}`)
   log('')
 
-  const rows = found
-    .filter((message) => message.fileName?.endsWith('.manifest.json'))
-    .map(toRow)
+  const rows = found.map(toRow)
 
   if (rows.length === 0) {
-    log(`No backups found in ${chatName(chat)}. Upload one with: npx telstore <file>`)
+    if (term) {
+      log(
+        capped
+          ? `No backups matching ${JSON.stringify(term)} in the newest ${budget} ` +
+              `${unit} from ${chatName(chat)}. There may be older ones further back.`
+          : `No backups matching ${JSON.stringify(term)} in ${chatName(chat)}.`,
+      )
+      log(SEARCH_MISS_HELP)
+      return rows
+    }
+
+    log(
+      capped
+        ? `No backups in the newest ${budget} ${unit} of ${chatName(chat)}. ` +
+            `There may be older ones further back. ${DEEPER_HINT}`
+        : `No backups found in ${chatName(chat)}. Upload one with: npx telstore <file>`,
+    )
     return rows
   }
 
   for (const line of renderTable(rows)) log(line)
 
   log('')
-  log(`${rows.length} backup${rows.length === 1 ? '' : 's'}. Restore with: npx telstore restore <backup-id>`)
+  log(
+    `${rows.length} backup${rows.length === 1 ? '' : 's'}` +
+      `${term ? ` matching ${JSON.stringify(term)}` : ''}. ` +
+      'Restore with: npx telstore restore <backup-id>',
+  )
+
+  if (capped) {
+    log(
+      `Read the newest ${budget} ${unit} in ${chatName(chat)} to find them — ` +
+        `there may be older ${term ? 'matches' : 'backups'} further back.` +
+        `${term ? '' : ` ${DEEPER_HINT}`}`,
+    )
+  }
 
   return rows
 }

package/src/commands/verify.js

@@ -0,0 +1,298 @@
+import { chatName, describeChat } from '../chat.js'
+import {
+  MESSAGE_BATCH_SIZE,
+  closeQuietly,
+  connect as realConnect,
+  documentFileName,
+  documentSize,
+  findManifestMessage,
+  getDocuments as realGetDocuments,
+  readMessageBytes as realReadMessageBytes,
+} from '../client.js'
+import { configFile, defaultConfigDir, loadConfig } from '../config.js'
+import { chunkFileName, manifestFileName, parseManifest } from '../manifest.js'
+import { formatBytes, formatDuration } from '../progress.js'
+import { assertLoggedIn } from '../session.js'
+import { requireChat, resolveSettings } from '../settings.js'
+
+// parseManifest guarantees every number in a manifest, but not the file name — it is
+// decoration, and nothing verifies differently because of it. It is still text off a chat.
+function describeName(name) {
+  return typeof name === 'string' && name.trim() !== '' ? name : '—'
+}
+
+function plural(n, word) {
+  return `${n} ${word}${n === 1 ? '' : 's'}`
+}
+
+// What is wrong with one chunk, or null when nothing is. The first failing check wins: a
+// chunk is damaged or it is not, and listing three complaints about one message would make
+// "2 damaged" mean something other than two chunks.
+//
+// Every question here is one the chat can answer without sending a byte of the file. What
+// this cannot ask is whether the bytes inside are the bytes that went up — only downloading
+// them answers that, which is why the closing line says so rather than leaving it implied.
+function inspect(chunk, message, { backupId, total, chat }) {
+  const at = `Chunk ${chunk.i + 1}/${total}`
+
+  if (!message) {
+    return `${at} is gone: message ${chunk.msgId} is no longer in ${chatName(chat)}.`
+  }
+
+  const size = documentSize(message)
+
+  if (size === null) {
+    return `${at} is message ${chunk.msgId}, which has no file attached.`
+  }
+
+  const wanted = chunkFileName(backupId, chunk.i)
+  const fileName = documentFileName(message)
+
+  if (fileName !== wanted) {
+    return fileName === null
+      ? `${at} is message ${chunk.msgId}, whose file carries no name; the manifest expects ` +
+          `"${wanted}".`
+      : `${at} is message ${chunk.msgId}, which carries the file name ` +
+          `${JSON.stringify(fileName)} rather than "${wanted}".`
+  }
+
+  if (size !== chunk.size) {
+    return `${at} is ${size} bytes in the chat, the manifest records ${chunk.size}.`
+  }
+
+  return null
+}
+
+export async function runVerify(backupId, options = {}, deps = {}) {
+  const {
+    connect = realConnect,
+    disconnect = (client) => client.destroy(),
+    configDir = defaultConfigDir(),
+    searchManifest = findManifestMessage,
+    readMessageBytes = realReadMessageBytes,
+    getDocuments = realGetDocuments,
+    retryOptions = {},
+    writeErr = (line) => process.stderr.write(line),
+    log: writeLog = (line) => console.log(line),
+    silent = false,
+  } = deps
+
+  const config = await loadConfig(configDir)
+  const { values: settings } = resolveSettings(options, config, { file: configFile(configDir) })
+  // Ask about the login before the destination, as list does: telling someone who has never
+  // logged in to pick a chat sends them off after the wrong thing.
+  assertLoggedIn(config)
+  const chat = requireChat(settings)
+
+  const log = silent ? () => {} : writeLog
+  const warn = silent ? () => {} : writeErr
+
+  // Upload and restore stay quiet until the third retry so a handful of -503s do not bury
+  // the progress bar. There is no bar here to bury — this command sends a handful of small
+  // requests and prints one verdict — so a wait long enough to notice is announced at once.
+  function onRetry(err, attempt, delayMs) {
+    warn(
+      `\nTemporary error (${err.message}), retry ${attempt} in ` +
+        `${formatDuration(delayMs / 1000)}.\n`,
+    )
+  }
+
+  const client = await connect(config, { verbose: settings.verbose })
+
+  try {
+    const manifestMessage = await searchManifest(client, chat, backupId)
+
+    if (!manifestMessage) {
+      throw new Error(
+        `No backup ${backupId} found in ${chatName(chat)}. Check the id with ` +
+          '"npx telstore list", or use --chat to point at the right chat.',
+      )
+    }
+
+    // The full layout checks, not the lenient path delete takes. delete reads a manifest to
+    // destroy what it names, so a broken one is exactly what somebody is there to remove;
+    // verify reads it to answer whether restore would work, and restore would refuse this
+    // one. Saying so in parseManifest's own words keeps one description of one fault.
+    const manifest = parseManifest(await readMessageBytes(client, manifestMessage))
+
+    // The same refusal delete makes, for the same reason from the other side: the manifest
+    // was found by the file name telstore wrote, so a body naming another backup is a file
+    // that was renamed or replaced, and its message ids describe somebody else's chunks.
+    // Reporting those as this backup's health is the one wrong answer this command can give.
+    if (manifest.id !== undefined && manifest.id !== backupId) {
+      throw new Error(
+        `The manifest named ${manifestFileName(backupId)} describes backup ` +
+          `${JSON.stringify(manifest.id)}, not ${backupId}. Its message ids point at another ` +
+          `backup's chunks, so telstore cannot say whether ${backupId} is still there.`,
+      )
+    }
+
+    const total = manifest.chunks.length
+
+    log(`Backup ${backupId}`)
+    log(
+      `File   ${describeName(manifest.name)} ` +
+        `(${formatBytes(manifest.size)}, ${plural(total, 'chunk')})`,
+    )
+    log(`In     ${describeChat(chat)}`)
+    log('')
+
+    // A backup at the 10000-chunk ceiling is a hundred requests, sent one at a time. Silence
+    // for that long reads as a hang, which is the one thing no wait in this project may look
+    // like — and below a single request there is no progress worth a line.
+    const loud = total > MESSAGE_BATCH_SIZE
+
+    const found = await getDocuments(
+      client,
+      chat,
+      manifest.chunks.map((chunk) => chunk.msgId),
+      {
+        retryOptions: { ...retryOptions, onRetry },
+        onBatch: (done, all) => {
+          if (loud) warn(`\rChecking chunk messages ${done}/${all}…`)
+        },
+      },
+    )
+
+    if (loud) warn('\n')
+
+    const damaged = []
+
+    for (const chunk of manifest.chunks) {
+      const fault = inspect(chunk, found.get(chunk.msgId), { backupId, total, chat })
+
+      if (fault) {
+        damaged.push(fault)
+        log(fault)
+      }
+    }
+
+    if (damaged.length > 0) {
+      log('')
+      log(
+        `${plural(total, 'chunk')} checked, ${damaged.length} damaged. ` +
+          'This backup cannot be restored.',
+      )
+    } else {
+      log(
+        `${plural(total, 'chunk')} present, at the ` +
+          `${total === 1 ? 'size' : 'sizes'} the manifest records.`,
+      )
+      log('This does not download them, so it cannot prove their contents.')
+      log('')
+      log(`Restore with: npx telstore restore ${backupId}`)
+    }
+
+    return { id: backupId, name: manifest.name, chunks: total, damaged }
+  } finally {
+    await closeQuietly(client, disconnect)
+  }
+}
+
+// A backup is a failure whether telstore could not look it up or looked and found it broken.
+// The command worked either way — but "did the run find everything it was asked to check"
+// is the question the exit code answers, and both answers to that are no.
+function isFailure(result) {
+  return Boolean(result.error) || result.damaged.length > 0
+}
+
+// The same shape as runDeletes and runRestores, minus the question: verify removes nothing,
+// so there is nothing to authorise. What is knowable before the connection is refused up
+// front; what only the chat can answer is per id, named when it happens and again at the end.
+export async function runVerifies(backupIds, options = {}, deps = {}) {
+  const {
+    connect = realConnect,
+    disconnect = (client) => client.destroy(),
+    configDir = defaultConfigDir(),
+    writeErr = (line) => process.stderr.write(line),
+    log: writeLog = (line) => console.log(line),
+    silent = false,
+  } = deps
+
+  // One id keeps its own wording and its own thrown error. A summary about one backup only
+  // repeats the lines above it.
+  if (backupIds.length === 1) {
+    const result = await runVerify(backupIds[0], options, deps)
+    return { results: [result], failed: isFailure(result) ? 1 : 0 }
+  }
+
+  const duplicate = backupIds.find((id, index) => backupIds.indexOf(id) !== index)
+
+  if (duplicate) {
+    throw new Error(
+      `${duplicate} is named twice. Checking one backup twice asks the chat the same ` +
+        'question again — name it once.',
+    )
+  }
+
+  const config = await loadConfig(configDir)
+
+  assertLoggedIn(config)
+
+  const { values: settings } = resolveSettings(options, config, { file: configFile(configDir) })
+  const chat = requireChat(settings)
+
+  const log = silent ? () => {} : writeLog
+  const warn = silent ? () => {} : writeErr
+
+  let shared = null
+  const perId = {
+    ...deps,
+    connect: async (theirConfig, connectOptions) =>
+      (shared ??= await connect(theirConfig, connectOptions)),
+    disconnect: async () => {},
+  }
+
+  const results = []
+
+  try {
+    await perId.connect(config, { verbose: settings.verbose })
+
+    for (const [index, backupId] of backupIds.entries()) {
+      if (index > 0) log('')
+      log(`[${index + 1}/${backupIds.length}] ${backupId}`)
+
+      try {
+        results.push(await runVerify(backupId, options, perId))
+      } catch (err) {
+        // Unlike delete, an id nothing knows about does not stop the run: nothing here is
+        // destroyed, and the other ids are exactly the ones somebody is checking on.
+        results.push({ id: backupId, error: err.message, damaged: [] })
+        warn(`\n${backupId} failed: ${err.message}\n`)
+      }
+    }
+  } finally {
+    if (shared) {
+      await closeQuietly(shared, disconnect, (err) =>
+        warn(`\nWarning: could not close the Telegram connection: ${err.message}\n`),
+      )
+    }
+  }
+
+  const failed = results.filter(isFailure).length
+
+  log('')
+  for (const line of summaryLines(results, failed)) log(line)
+
+  return { results, failed }
+}
+
+// Every id gets a line whether it checked out or not: one missing from this list would be a
+// backup nobody could tell the state of, which is the whole reason this command exists.
+function summaryLines(results, failed) {
+  const width = Math.max(...results.map((result) => result.id.length))
+
+  return [
+    `${results.length} backups: ${results.length - failed} verified, ${failed} failed.`,
+    '',
+    ...results.map((result) => {
+      const id = result.id.padEnd(width)
+
+      if (result.error) return `  ${id}  failed: ${result.error}`
+
+      return result.damaged.length > 0
+        ? `  ${id}  ${plural(result.damaged.length, 'chunk')} damaged`
+        : `  ${id}  ${plural(result.chunks, 'chunk')} present`
+    }),
+  ]
+}

package/src/manifest.js

@@ -15,8 +15,13 @@ export function chunkFileName(id, i) {
   return `${id}.part${String(i + 1).padStart(4, '0')}`
 }
 
+// The suffix telstore has written on every manifest since version 1, and what `list` picks
+// a manifest out of a chat by. One definition, because a reader that disagrees with the
+// writer by one character finds nothing at all.
+export const MANIFEST_SUFFIX = '.manifest.json'
+
 export function manifestFileName(id) {
-  return `${id}.manifest.json`
+  return `${id}${MANIFEST_SUFFIX}`
 }
 
 export function buildManifest({