telstore 0.1.7 → 0.1.8

package/README.md

@@ -29,7 +29,7 @@ npx telstore restore telstore-20260905-7f3a91
 | `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 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 backups. |
+| `telstore status` | Account, destination, and unfinished uploads and restores. |
 | `telstore config` | Show or change settings. |
 | `telstore token` | Print a session token for a machine you do not trust. |
 | `telstore logout` | Remove the locally stored session. |
@@ -143,7 +143,14 @@ After a batch, run telstore again with **only the files that are left**: the fin
 have had their records cleared, so repeating the whole command would upload them a second
 time as new backups. `npx telstore status` lists what is unfinished.
 
-**Restore keeps no state** — `Ctrl-C` mid-restore saves nothing, running again starts over.
+## Resuming a restore
+
+`Ctrl-C` mid-restore keeps the `<target>.partial` file rather than throwing it away. Running
+the same command again hashes each chunk-sized region of it against the manifest, in order,
+and carries on from the first one that does not match — nothing already on disk is trusted
+just because it is there. `npx telstore status` lists unfinished restores alongside
+unfinished uploads, with a resume command for each.
+
 And `delete` has **no undo**: Telegram is the only copy.
 
 ## Running on a machine you do not trust

package/bin/telstore.js

@@ -14,9 +14,9 @@ const SIGINT_EXIT_CODE = 130
 let currentCommand = null
 let currentBackupId = null
 
-// A batch clears each finished file's record as it goes, so by the time Ctrl-C lands these
-// are backups no second run should touch. Ctrl-C needs their names to say so.
-const finishedUploads = []
+// A batch clears each finished item's record as it goes, so by the time Ctrl-C lands these
+// are transfers no second run should touch. Ctrl-C needs their names to say so.
+const finished = []
 
 process.on('SIGINT', () => {
   // A passphrase prompt has stdin in raw mode, and process.exit skips readline's own cleanup.
@@ -24,7 +24,7 @@ process.on('SIGINT', () => {
   if (process.stdin.isTTY) process.stdin.setRawMode(false)
 
   process.stderr.write(
-    interruptMessage(currentCommand, { backupId: currentBackupId, done: finishedUploads }),
+    interruptMessage(currentCommand, { backupId: currentBackupId, done: finished }),
   )
   process.exit(SIGINT_EXIT_CODE)
 })
@@ -104,7 +104,7 @@ async function main() {
           currentBackupId = id
         },
         onFileDone: (file) => {
-          if (file.id) finishedUploads.push(file)
+          if (file.id) finished.push(file)
         },
       })
 
@@ -121,7 +121,14 @@ async function main() {
 
       const { runRestores } = await import('../src/commands/restore.js')
 
-      const { failed } = await runRestores(parsed.args, parsed.options)
+      const { failed } = await runRestores(parsed.args, parsed.options, {
+        onBackupId: (id) => {
+          currentBackupId = id
+        },
+        onRestoreDone: (item) => {
+          finished.push(item)
+        },
+      })
 
       if (failed > 0) process.exitCode = 1
       return

package/package.json

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

package/src/cli.js

@@ -36,7 +36,7 @@ Usage:
   npx telstore list                       List the backups stored in the destination
   npx telstore restore <backup-id>...     Download the chunks and reassemble the files
   npx telstore delete <backup-id>...      Remove backups' chunks and manifests from the chat
-  npx telstore status                     Show the account, the destination and unfinished backups
+  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
   npx telstore logout                     Remove the saved session
 
@@ -120,8 +120,38 @@ export function interruptMessage(command, { backupId, done = [] } = {}) {
     )
   }
 
+  // A restore keeps its .partial now, and the next run proves each chunk in it against the
+  // manifest before trusting a byte — so "running again starts over", which this said while
+  // there was nothing to resume from, would now be false.
   if (command === 'restore') {
-    return '\nStopped. Download progress is not saved, running again starts over.\n'
+    // Finished ids have been renamed to their real names and their records removed, so
+    // repeating the whole command line would meet an overwrite prompt and then download
+    // them again from nothing. Name them and ask for the rest, exactly as a batch upload does.
+    if (done.length > 0) {
+      const width = Math.max(...done.map((item) => basename(item.path).length))
+      const finished = done
+        .map((item) => `  ${basename(item.path).padEnd(width)}  ${item.id}`)
+        .join('\n')
+
+      return (
+        `\nStopped. These are finished and need no second run:\n${finished}\n` +
+        'Run telstore again with only the ids that are left — their .partial files are kept, ' +
+        'so those carry on where they stopped. "npx telstore status" shows what is unfinished.\n'
+      )
+    }
+
+    // With onBackupId firing only once the .partial is open, an id here means there is a
+    // file to carry on from. Without one, this run stopped before it wrote anything, and
+    // saying a .partial was kept would be the same lie this message was rewritten to stop
+    // telling — just from the other side.
+    if (!backupId) {
+      return '\nStopped before anything was written. Run the same command again to start.\n'
+    }
+
+    return (
+      `\nBackup ${backupId} kept its .partial file — run the same command again from this ` +
+      'directory to carry on, or "npx telstore status" to see what is left.\n'
+    )
   }
 
   // A delete has already destroyed messages for good by the time Ctrl-C lands, and the

package/src/commands/delete.js

@@ -1,3 +1,5 @@
+import { promises as fs } from 'node:fs'
+
 import { chatName, describeChat } from '../chat.js'
 import {
   DELETE_BATCH_SIZE,
@@ -13,7 +15,7 @@ import { manifestFileName, manifestMessageIds, parseManifestJson } from '../mani
 import { formatBytes, formatDuration } from '../progress.js'
 import { assertLoggedIn } from '../session.js'
 import { requireChat, resolveSettings } from '../settings.js'
-import { clearState, findStates } from '../state.js'
+import { clearRestore, clearState, findRestores, findStates } from '../state.js'
 
 // What list prints when a card cannot be read back. A manifest is text off a chat, and a
 // summary is not worth inventing: the numbers below only decorate a decision the backup id
@@ -223,6 +225,30 @@ export async function runDelete(backupId, options = {}, deps = {}) {
 
     if (record) await clearState(record.key, configDir)
 
+    // The chunks are gone from the chat, so a restore record pointing at this backup now
+    // names messages nobody can fetch: `status` would keep offering a resume command that
+    // can only fail. Dropped here rather than earlier for the same reason the upload record
+    // is — anything that throws above leaves the way back intact.
+    //
+    // The .partial itself stays. It is the user's data, sometimes gigabytes of it, and this
+    // command removes what was asked for and nothing else. But it can never be completed
+    // now, so it is named on the way out: that is the difference between a file they can
+    // reclaim and one they will never think to look for.
+    const stranded = []
+
+    for (const found of await findRestores(backupId, configDir)) {
+      await clearRestore(found.key, configDir)
+
+      const partial = `${found.record.target}.partial`
+
+      try {
+        await fs.stat(partial)
+        stranded.push(partial)
+      } catch {
+        // Nothing there to tell them about.
+      }
+    }
+
     if (manifestMessage) {
       log(
         `\nDone. Removed ${backupId} from ${chatName(chat)}: ` +
@@ -236,6 +262,13 @@ export async function runDelete(backupId, options = {}, deps = {}) {
       )
     }
 
+    for (const partial of stranded) {
+      log(
+        `${partial} is a half-finished restore of this backup. Nothing can finish it now — ` +
+          'delete it when you want the space back.',
+      )
+    }
+
     return {
       id: backupId,
       chunks: chunkIds.length,

package/src/commands/restore.js

@@ -11,9 +11,10 @@ import { askConfirm } from '../confirm.js'
 import { configFile, defaultConfigDir, loadConfig } from '../config.js'
 import { assertLoggedIn } from '../session.js'
 import { requireChat, resolveSettings } from '../settings.js'
-import { downloadToFile } from '../downloader.js'
+import { downloadToFile, hashRange } from '../downloader.js'
 import { parseManifest } from '../manifest.js'
 import { createProgress, formatBytes, formatDuration } from '../progress.js'
+import { clearRestore, pruneRestores, restoreKey, saveRestore } from '../state.js'
 
 // Anything past a minute of waiting needs saying out loud; below that the pause is shorter
 // than the time a user would spend wondering about it.
@@ -50,6 +51,29 @@ function safeOutName(name) {
   return base
 }
 
+// How many chunks at the front of a .partial already hold what the manifest says they
+// should. The evidence is the file, never a record: a record makes claims about a local
+// file anyone can edit between runs, and a claim that is wrong here renames a corrupt file
+// into place. Every chunk in the finished file was hashed against the manifest by the run
+// that renamed it, whether this run downloaded it or found it already there.
+async function scanPartial(handle, manifest, log) {
+  let done = 0
+
+  for (const chunk of manifest.chunks) {
+    const digest = await hashRange(handle.fd, chunk.i * manifest.chunkSize, chunk.size)
+
+    // Downloads run in order, so what is already present is a prefix. The first chunk that
+    // does not match is where this run starts, and reading past it would hash gigabytes
+    // nobody has written yet.
+    if (digest !== chunk.sha256) break
+
+    done += 1
+    log(`Chunk ${chunk.i + 1}/${manifest.chunks.length} already restored, skipping.`)
+  }
+
+  return done
+}
+
 export async function runRestore(backupId, options = {}, deps = {}) {
   const {
     connect = realConnect,
@@ -64,6 +88,7 @@ export async function runRestore(backupId, options = {}, deps = {}) {
     writeErr = (line) => process.stderr.write(line),
     log: writeLog = (line) => console.log(line),
     silent = false,
+    onBackupId = () => {},
   } = deps
 
   const config = await loadConfig(configDir)
@@ -112,6 +137,41 @@ export async function runRestore(backupId, options = {}, deps = {}) {
     const target = path.resolve(options.out ?? safeOutName(manifest.name))
     const partial = `${target}.partial`
 
+    const key = restoreKey(backupId, target)
+
+    // The record is a signpost for `status`, never evidence. The scan above proved every
+    // chunk it skipped against the manifest and would do so again if this file vanished, so
+    // a signpost that cannot be planted warns and gets out of the way. Deliberately the
+    // opposite of markChunkDone, where a failed write must be fatal because losing it
+    // strands chunks in a chat with nothing left pointing at them.
+    // A record that cannot be written warns once, not once per chunk: warn is the same
+    // stderr stream the progress bar owns with \r, and a warning for every one of ~30
+    // chunks on a real restore would tear through the bar as badly as the retry
+    // announcements above reason about at length.
+    let recordWarned = false
+
+    async function note(done) {
+      try {
+        await saveRestore(
+          key,
+          {
+            v: 1,
+            id: backupId,
+            target,
+            chat: String(chat),
+            size: manifest.size,
+            chunks: manifest.chunks.length,
+            done,
+          },
+          configDir,
+        )
+      } catch (err) {
+        if (recordWarned) return
+        recordWarned = true
+        warn(`\nWarning: could not record restore progress: ${err.message}\n`)
+      }
+    }
+
     // Only ENOENT means "no file yet". Treating a permission or I/O error as absence
     // would have telstore overwrite the user's file without asking.
     let exists = true
@@ -129,66 +189,120 @@ export async function runRestore(backupId, options = {}, deps = {}) {
     log(`Backup ${manifest.id}`)
     log(`File   ${target} (${formatBytes(manifest.size)}, ${manifest.chunks.length} chunks)\n`)
 
-    const handle = await fs.open(partial, 'w+')
+    let handle
+    let resuming = true
 
+    // r+ keeps whatever an earlier run left behind; w+ truncates it to zero, which is what
+    // made a kept .partial useless. Only ENOENT means "no file yet" — a permission error
+    // quietly becoming "start over" is how two hours of downloading disappear unexplained.
     try {
+      handle = await fs.open(partial, 'r+')
+    } catch (err) {
+      if (err.code !== 'ENOENT') throw err
+      handle = await fs.open(partial, 'w+')
+      resuming = false
+    }
+
+    // The message this id feeds says a .partial was kept, so naming the id is only honest
+    // once one actually exists — before this line, Ctrl-C would have nothing to carry on from.
+    onBackupId(backupId)
+
+    try {
+      // Extends a short .partial with zeros and cuts an over-long one, and touches no byte
+      // below manifest.size — so one path serves a fresh file and a resumed one alike.
       await handle.truncate(manifest.size)
 
-      // One bar for the whole restore. The label names the chunk in flight, but the bar, the
-      // byte counts, the speed and the ETA all describe the file, so the line runs 0% to 100%
-      // once instead of restarting at every chunk boundary — with 1800MB chunks, a per-chunk
-      // ETA answers a question nobody asked.
-      // warn is already the no-op when silent, and createProgress draws through nothing else.
-      const progress = createProgress({
-        total: manifest.size,
-        label: `Chunk 1/${manifest.chunks.length}`,
-        write: warn,
-      })
+      let done = 0
 
-      try {
-        for (const chunk of manifest.chunks) {
-          // Before getMessage, not after: the bar is then on screen from the first moment,
-          // and finish() below always has a line to close.
-          progress.setLabel(`Chunk ${chunk.i + 1}/${manifest.chunks.length}`)
+      if (resuming) {
+        // Hashing 1800MB takes about 9 seconds, so a large scan runs for minutes. Silence
+        // that long is the hang this project refuses everywhere: the heading lands before
+        // the first read and a line per chunk arrives as the scan advances.
+        log(`Checking what is already in ${partial}...`)
+        done = await scanPartial(handle, manifest, log)
+        if (done === 0) log(`Nothing in ${partial} matches this backup, starting over.`)
+        log('')
+      }
 
-          const message = await getMessage(client, chat, chunk.msgId)
+      await note(done)
 
-          if (!message) {
-            throw new Error(
-              `Missing chunk ${chunk.i + 1}/${manifest.chunks.length}: message ${chunk.msgId} is no longer in ${chat}. ` +
-                'This backup cannot be restored.',
-            )
-          }
+      // Housekeeping, the way runUpload prunes its own records. It removes signposts only:
+      // dropping one costs a line of `status` for a .partial that still resumes.
+      try {
+        await pruneRestores(configDir)
+      } catch (err) {
+        warn(`\nWarning: could not tidy old restore records: ${err.message}\n`)
+      }
 
-          const { sha256, size } = await downloadChunk(
-            client,
-            message,
-            handle,
-            chunk.i * manifest.chunkSize,
-            progress.advance,
-            {
-              retryOptions: { ...retryOptions, onRetry },
-              concurrency: settings.downloadConcurrency,
-            },
-          )
-
-          if (size !== chunk.size) {
-            throw new Error(
-              `Chunk ${chunk.i + 1} has ${size} bytes, the manifest records ${chunk.size} bytes — mismatch.`,
+      const pending = manifest.chunks.slice(done)
+
+      // A .partial holding every chunk is what a run that died between its last chunk and
+      // the rename leaves: no bar at all, rather than one springing into existence at 100%.
+      if (pending.length > 0) {
+        const present = manifest.chunks
+          .slice(0, done)
+          .reduce((sum, chunk) => sum + chunk.size, 0)
+
+        // One bar for the whole restore. The label names the chunk in flight, but the bar, the
+        // byte counts, the speed and the ETA all describe the file, so the line runs 0% to 100%
+        // once instead of restarting at every chunk boundary — with 1800MB chunks, a per-chunk
+        // ETA answers a question nobody asked. Chunks an earlier run left count towards the bar
+        // but not towards the speed, so an hour-old chunk cannot inflate the ETA of the rest.
+        // warn is already the no-op when silent, and createProgress draws through nothing else.
+        const progress = createProgress({
+          total: manifest.size,
+          done: present,
+          label: `Chunk ${pending[0].i + 1}/${manifest.chunks.length}`,
+          write: warn,
+        })
+
+        try {
+          for (const chunk of pending) {
+            // Before getMessage, not after: the bar is then on screen from the first moment,
+            // and finish() below always has a line to close.
+            progress.setLabel(`Chunk ${chunk.i + 1}/${manifest.chunks.length}`)
+
+            const message = await getMessage(client, chat, chunk.msgId)
+
+            if (!message) {
+              throw new Error(
+                `Missing chunk ${chunk.i + 1}/${manifest.chunks.length}: message ${chunk.msgId} is no longer in ${chat}. ` +
+                  'This backup cannot be restored.',
+              )
+            }
+
+            const { sha256, size } = await downloadChunk(
+              client,
+              message,
+              handle,
+              chunk.i * manifest.chunkSize,
+              progress.advance,
+              {
+                retryOptions: { ...retryOptions, onRetry },
+                concurrency: settings.downloadConcurrency,
+              },
             )
-          }
 
-          if (sha256 !== chunk.sha256) {
-            throw new Error(
-              `Chunk ${chunk.i + 1} has a sha256 that does not match the manifest. The download is kept at ${partial} for inspection.`,
-            )
+            if (size !== chunk.size) {
+              throw new Error(
+                `Chunk ${chunk.i + 1} has ${size} bytes, the manifest records ${chunk.size} bytes — mismatch.`,
+              )
+            }
+
+            if (sha256 !== chunk.sha256) {
+              throw new Error(
+                `Chunk ${chunk.i + 1} has a sha256 that does not match the manifest. The download is kept at ${partial} for inspection.`,
+              )
+            }
+
+            await note(chunk.i + 1)
           }
+        } finally {
+          // The bar owns a line that \r keeps returning to. Ending it here rather than after the
+          // loop means a chunk that fails mid-download still leaves the cursor on a fresh line,
+          // so "Error: ..." does not land on top of the bar.
+          progress.finish()
         }
-      } finally {
-        // The bar owns a line that \r keeps returning to. Ending it here rather than after the
-        // loop means a chunk that fails mid-download still leaves the cursor on a fresh line,
-        // so "Error: ..." does not land on top of the bar.
-        progress.finish()
       }
     } finally {
       await handle.close()
@@ -208,6 +322,13 @@ export async function runRestore(backupId, options = {}, deps = {}) {
 
     await fs.rename(partial, target)
 
+    // The restore is finished; the signpost has nothing left to point at.
+    try {
+      await clearRestore(key, configDir)
+    } catch (err) {
+      warn(`\nWarning: could not remove the restore record: ${err.message}\n`)
+    }
+
     log(`\nDone. Wrote ${formatBytes(manifest.size)} to ${target}`)
 
     return { path: target, size: manifest.size }
@@ -231,6 +352,8 @@ export async function runRestores(backupIds, options = {}, deps = {}) {
     writeErr = (line) => process.stderr.write(line),
     log: writeLog = (line) => console.log(line),
     silent = false,
+    onRestoreDone = () => {},
+    onBackupId = () => {},
   } = deps
 
   // One id must read exactly as it did before this existed: --out still works, the error still
@@ -289,12 +412,19 @@ export async function runRestores(backupIds, options = {}, deps = {}) {
       try {
         const { path: target, size } = await runRestore(backupId, options, perId)
         results.push({ id: backupId, path: target, size })
+        onRestoreDone({ id: backupId, path: target })
       } catch (err) {
         // A backup whose chunks are gone says nothing about the next one, and the summary at
         // the end would arrive an hour after the bar of the following id started scrolling
         // over it — so it is named here, and again down there, and carried out as exit code 1.
         results.push({ id: backupId, error: err.message })
         warn(`\n${backupId} failed: ${err.message}\n`)
+      } finally {
+        // Cleared whether this id finished, failed, or never got as far as opening a
+        // .partial: otherwise a Ctrl-C while the next id is still connecting, searching for
+        // its manifest, or blocked at the overwrite prompt would go on naming this one, as
+        // though there were a file to carry on from when there is none yet.
+        onBackupId(null)
       }
     }
   } finally {

package/src/commands/status.js

@@ -1,3 +1,5 @@
+import { promises as fs } from 'node:fs'
+
 import { countChunks } from '../chunking.js'
 import { describeChat } from '../chat.js'
 import { closeQuietly, connect as realConnect } from '../client.js'
@@ -5,7 +7,7 @@ import { configFile, defaultConfigDir, loadConfig } from '../config.js'
 import { formatBytes } from '../progress.js'
 import { assertLoggedIn } from '../session.js'
 import { resolveSettings } from '../settings.js'
-import { canResume, listStates } from '../state.js'
+import { canResume, listRestores, listStates } from '../state.js'
 
 const LABEL_WIDTH = 'Destination'.length + 2
 
@@ -52,6 +54,15 @@ const NO_RESUME = {
   unreadable: 'the record does not name a file that can be read',
 }
 
+// Why the .partial cannot be resumed from, in the same spirit as NO_RESUME above: an
+// EACCES or an ELOOP is not the same fact as the file being gone, and telling the user
+// their multi-gigabyte download vanished when it is sitting there, unreadable, sends them
+// looking for the wrong problem.
+const NO_PARTIAL_RESUME = {
+  missing: 'the partial download is no longer there',
+  unreadable: 'the partial download cannot be read',
+}
+
 // A command is printed only when it will really resume. Printing one regardless would be
 // telling the user to run something that quietly starts a second backup and abandons every
 // chunk this one already sent — and those chunks are then findable only by this id, which
@@ -73,6 +84,44 @@ async function resumeLines(key, state, destination, done) {
   return lines
 }
 
+// The record holds an absolute target, and printing it is what makes the pasted line
+// correct. Without --out, runRestore resolves the manifest's own name against the current
+// directory — a name status does not have (it is in a manifest on Telegram, and status
+// reaches Telegram only for the account line, where it deliberately tolerates failure) and
+// a directory status cannot assume. A command pasted from elsewhere would resolve to
+// another path, miss the .partial and start over, which is the failure resume exists to end.
+function restoreCommand(record, destination) {
+  const matches = destination !== null && record.chat === String(destination)
+  const chat = matches ? '' : ` --chat ${shellArg(record.chat)}`
+
+  return `npx telstore restore ${shellArg(record.id)} --out ${shellArg(record.target)}${chat}`
+}
+
+// The .partial is the whole reason a resume is possible, so its absence is the one thing
+// worth checking before offering a command that would silently start over.
+async function restoreResumeLine(record, destination) {
+  try {
+    await fs.stat(`${record.target}.partial`)
+  } catch (err) {
+    const reason = err.code === 'ENOENT' ? 'missing' : 'unreadable'
+
+    return field('Resume', `not possible: ${NO_PARTIAL_RESUME[reason]}.`)
+  }
+
+  return field('Resume', restoreCommand(record, destination))
+}
+
+// Only the kinds actually present are named. "N backups" fits an upload and not a restore:
+// there the backup is finished and sitting in the chat, and it is the restore that stopped.
+function unfinishedCount(uploads, restores) {
+  const parts = []
+
+  if (uploads > 0) parts.push(`${uploads} upload${uploads === 1 ? '' : 's'}`)
+  if (restores > 0) parts.push(`${restores} restore${restores === 1 ? '' : 's'}`)
+
+  return parts.length === 0 ? 'none' : parts.join(', ')
+}
+
 function describeAccount(me) {
   const name = [me.firstName, me.lastName].filter(Boolean).join(' ')
   const handle = me.username ? ` (@${me.username})` : ''
@@ -153,24 +202,42 @@ export async function runStatus(options = {}, deps = {}) {
     ),
   )
 
-  const states = await listStates(configDir)
+  const uploads = await listStates(configDir)
+  const restores = await listRestores(configDir)
 
-  if (states.length === 0) {
-    log(row('Unfinished', 'none'))
-    return
-  }
+  log(row('Unfinished', unfinishedCount(uploads.length, restores.length)))
 
-  log(row('Unfinished', `${states.length} backup${states.length === 1 ? '' : 's'}`))
+  if (uploads.length === 0 && restores.length === 0) return
 
-  // The destination is what decides whether the resume command needs a --chat. A row that
+  // The destination is what decides whether a resume command needs a --chat. A row that
   // failed to parse leaves nothing to compare against, which is not the same as a match.
   const destination = settings?.chat ?? null
 
-  for (const { key, state } of states) {
+  // Newest first, by when the record last changed — which is when that transfer last made
+  // progress, and the same ordering pruneStates already means by "recent".
+  const entries = [
+    ...uploads.map((entry) => ({ ...entry, kind: 'upload' })),
+    ...restores.map((entry) => ({ ...entry, kind: 'restore' })),
+  ].sort((a, b) => b.mtimeMs - a.mtimeMs)
+
+  for (const entry of entries) {
+    log('')
+
+    if (entry.kind === 'restore') {
+      const { record } = entry
+
+      log(`  ${record.id}`)
+      log(field('File', `${record.target}  (${formatBytes(record.size)})`))
+      log(field('Chunks', `${record.done ?? 0} of ${record.chunks ?? '?'} restored`))
+      log(field('Chat', describeChat(record.chat)))
+      log(await restoreResumeLine(record, destination))
+      continue
+    }
+
+    const { key, state } = entry
     const total = countChunks(state.size, state.chunkSize)
     const done = Object.keys(state.done ?? {}).length
 
-    log('')
     log(`  ${state.id}`)
     log(field('File', `${state.path}  (${formatBytes(state.size)})`))
     log(field('Chunks', `${done} of ${total} uploaded`))

package/src/downloader.js

@@ -43,7 +43,10 @@ async function readExactly(fd, length, position) {
 // the better check anyway: a slice written at the wrong offset, two slices overlapping, or
 // one silently skipped all show up here. It does not prove the bytes reached the platter —
 // this read may well be served from the page cache — it proves the assembly.
-async function hashRange(fd, offset, length) {
+//
+// Exported because a resumed restore asks the same question of a .partial left by an earlier
+// run. A second copy of it in restore.js is how two definitions of one check start to differ.
+export async function hashRange(fd, offset, length) {
   const hash = createHash('sha256')
 
   for (let at = 0; at < length; at += HASH_READ_SIZE) {

package/src/progress.js

@@ -1,6 +1,7 @@
 const UNITS = ['B', 'KB', 'MB', 'GB', 'TB']
 
 export function formatBytes(n) {
+  if (!Number.isFinite(n)) return '--'
   if (n < 1024) return `${n} B`
 
   let value = n

package/src/state.js

@@ -16,9 +16,53 @@ export function stateFile(key, configDir = defaultConfigDir()) {
   return path.join(stateDir(configDir), `${key}.json`)
 }
 
-export async function loadState(key, configDir = defaultConfigDir()) {
+// A restore's record is filed beside the uploads and must never compete with them for a
+// prune slot. Losing an upload record strands chunks in a chat where only the id can still
+// find them, which is why pruneStates reads each file back to name what it drops; losing a
+// restore record costs one line of `status` for a .partial that still resumes perfectly.
+// The name is what keeps them apart — an upload key is 40 hex characters and `r` is not
+// hex, so the two namespaces cannot collide.
+const RESTORE_PREFIX = 'restore-'
+
+// stateKey's trick does not transfer: a .partial changes size and mtime on every write, so
+// there is nothing there to key on. What holds still across runs is the backup being
+// restored and the path being written.
+export function restoreKey(backupId, absTarget) {
+  return createHash('sha1').update(`${backupId}:${absTarget}`).digest('hex')
+}
+
+export function restoreFile(key, configDir = defaultConfigDir()) {
+  return path.join(stateDir(configDir), `${RESTORE_PREFIX}${key}.json`)
+}
+
+// One reader for both kinds. A listing that forgets to filter hands `status` a restore
+// record as though it were an upload, canResume stats a path that is not in it, and the
+// report comes out wrong without anything failing — so there is one place that filters.
+async function recordNames(configDir, restores) {
+  let names
+  try {
+    names = await fs.readdir(stateDir(configDir))
+  } catch (err) {
+    if (err.code === 'ENOENT') return []
+    throw err
+  }
+
+  return names.filter(
+    (name) => name.endsWith('.json') && name.startsWith(RESTORE_PREFIX) === restores,
+  )
+}
+
+function keyOfName(name) {
+  const base = name.slice(0, -'.json'.length)
+
+  return base.startsWith(RESTORE_PREFIX) ? base.slice(RESTORE_PREFIX.length) : base
+}
+
+// Why loadState returns null rather than throwing, in one place both kinds can use: one
+// corrupt file must not hide the other records still waiting to be finished.
+async function readRecord(file) {
   try {
-    return JSON.parse(await fs.readFile(stateFile(key, configDir), 'utf8'))
+    return JSON.parse(await fs.readFile(file, 'utf8'))
   } catch (err) {
     if (err.code === 'ENOENT') return null
     if (err instanceof SyntaxError) return null
@@ -26,6 +70,32 @@ export async function loadState(key, configDir = defaultConfigDir()) {
   }
 }
 
+async function removeRecord(file) {
+  try {
+    await fs.unlink(file)
+  } catch (err) {
+    if (err.code !== 'ENOENT') throw err
+  }
+}
+
+// The mtime says when a record last made progress, which is the order `status` prints in —
+// nothing decides from it whether a record exists. Its content has already been read by the
+// time this runs, so a stat that fails must not drop the record or take the listing down:
+// an unknown time sorts last and nothing is hidden. The file can genuinely vanish between
+// the readdir and here, which is the case this exists for.
+async function recordMtime(file) {
+  try {
+    const { mtimeMs } = await fs.stat(file)
+    return mtimeMs
+  } catch {
+    return 0
+  }
+}
+
+export async function loadState(key, configDir = defaultConfigDir()) {
+  return await readRecord(stateFile(key, configDir))
+}
+
 export async function saveState(key, state, configDir = defaultConfigDir()) {
   await writeJsonAtomic(stateFile(key, configDir), state)
 }
@@ -37,11 +107,19 @@ export async function markChunkDone(key, state, i, entry, configDir = defaultCon
 }
 
 export async function clearState(key, configDir = defaultConfigDir()) {
-  try {
-    await fs.unlink(stateFile(key, configDir))
-  } catch (err) {
-    if (err.code !== 'ENOENT') throw err
-  }
+  await removeRecord(stateFile(key, configDir))
+}
+
+export async function loadRestore(key, configDir = defaultConfigDir()) {
+  return await readRecord(restoreFile(key, configDir))
+}
+
+export async function saveRestore(key, record, configDir = defaultConfigDir()) {
+  await writeJsonAtomic(restoreFile(key, configDir), record)
+}
+
+export async function clearRestore(key, configDir = defaultConfigDir()) {
+  await removeRecord(restoreFile(key, configDir))
 }
 
 // A state file is only useful while its backup can still be resumed, and nothing ever
@@ -54,24 +132,14 @@ export const MAX_STATES = 20
 // were dropped: the caller says their ids out loud, because after this the id is the only
 // way left to find those chunks in the chat.
 export async function pruneStates(configDir = defaultConfigDir(), keep = MAX_STATES) {
-  let names
-  try {
-    names = await fs.readdir(stateDir(configDir))
-  } catch (err) {
-    if (err.code === 'ENOENT') return []
-    throw err
-  }
-
   const files = []
 
-  for (const name of names) {
-    if (!name.endsWith('.json')) continue
-
+  for (const name of await recordNames(configDir, false)) {
     const file = path.join(stateDir(configDir), name)
 
     try {
       const stat = await fs.stat(file)
-      files.push({ key: name.slice(0, -'.json'.length), file, mtimeMs: stat.mtimeMs })
+      files.push({ key: keyOfName(name), file, mtimeMs: stat.mtimeMs })
     } catch (err) {
       // Gone between readdir and stat: nothing left to prune.
       if (err.code !== 'ENOENT') throw err
@@ -99,25 +167,19 @@ export async function pruneStates(configDir = defaultConfigDir(), keep = MAX_STA
 //
 // The key comes back alongside each record because canResume needs it, and the file name is
 // the only place it survives: the record's own path, size and mtime are exactly what a
-// rewritten file makes stale, so recomputing the key from them would always say yes.
+// rewritten file makes stale, so recomputing the key from them would always say yes. The
+// mtime comes back because it is when this backup last made progress, which is the order
+// status prints records in.
 export async function listStates(configDir = defaultConfigDir()) {
-  let names
-  try {
-    names = await fs.readdir(stateDir(configDir))
-  } catch (err) {
-    if (err.code === 'ENOENT') return []
-    throw err
-  }
-
   const states = []
 
-  for (const name of names) {
-    if (!name.endsWith('.json')) continue
-
-    const key = name.slice(0, -'.json'.length)
+  for (const name of await recordNames(configDir, false)) {
+    const key = keyOfName(name)
     const state = await loadState(key, configDir)
 
-    if (state) states.push({ key, state })
+    if (!state) continue
+
+    states.push({ key, state, mtimeMs: await recordMtime(path.join(stateDir(configDir), name)) })
   }
 
   return states
@@ -134,20 +196,10 @@ export async function listStates(configDir = defaultConfigDir()) {
 // cannot know which to drop, and that is the caller's decision to refuse, not ours to make
 // by picking one.
 export async function findStates(backupId, configDir = defaultConfigDir()) {
-  let names
-  try {
-    names = await fs.readdir(stateDir(configDir))
-  } catch (err) {
-    if (err.code === 'ENOENT') return []
-    throw err
-  }
-
   const found = []
 
-  for (const name of names) {
-    if (!name.endsWith('.json')) continue
-
-    const key = name.slice(0, -'.json'.length)
+  for (const name of await recordNames(configDir, false)) {
+    const key = keyOfName(name)
     const state = await loadState(key, configDir)
 
     if (state?.id === backupId) found.push({ key, file: stateFile(key, configDir), state })
@@ -180,3 +232,67 @@ export async function canResume(key, state) {
 
   return { ok: true }
 }
+
+export const MAX_RESTORES = 20
+
+// A record with no id or no target can neither be printed nor resumed from, so status has
+// nothing to do with it. Skipped rather than rendered with blanks: these files are
+// hand-editable, and a row that names nothing is worse than no row.
+export async function listRestores(configDir = defaultConfigDir()) {
+  const restores = []
+
+  for (const name of await recordNames(configDir, true)) {
+    const key = keyOfName(name)
+    const record = await loadRestore(key, configDir)
+
+    if (typeof record?.id !== 'string' || typeof record?.target !== 'string') continue
+
+    restores.push({ key, record, mtimeMs: await recordMtime(path.join(stateDir(configDir), name)) })
+  }
+
+  return restores
+}
+
+// Unlike pruneStates this returns nothing and reads nothing back. Dropping a restore record
+// strands no data — the .partial it points at still resumes, because the evidence for a
+// resume was never in the record — so there is nothing to announce and no reason to open
+// each file just to name it. It removes the signpost, never the .partial: a multi-gigabyte
+// file must not disappear as a side effect of starting an unrelated restore.
+export async function pruneRestores(configDir = defaultConfigDir(), keep = MAX_RESTORES) {
+  const files = []
+
+  for (const name of await recordNames(configDir, true)) {
+    const file = path.join(stateDir(configDir), name)
+
+    try {
+      const stat = await fs.stat(file)
+      files.push({ file, mtimeMs: stat.mtimeMs })
+    } catch (err) {
+      if (err.code !== 'ENOENT') throw err
+    }
+  }
+
+  files.sort((a, b) => b.mtimeMs - a.mtimeMs)
+
+  for (const { file } of files.slice(keep)) await removeRecord(file)
+}
+
+// What findStates is for uploads, and for the same reason: the file name hashes the target
+// path, which delete does not know — it has an id and nothing else. Matching the id inside
+// each file is the only way that cannot point at the wrong one.
+//
+// Every record claiming the id comes back, not the first. One backup restored to two places
+// is two records, and a delete that drops one of them leaves a signpost to chunks that are
+// no longer in the chat.
+export async function findRestores(backupId, configDir = defaultConfigDir()) {
+  const found = []
+
+  for (const name of await recordNames(configDir, true)) {
+    const key = keyOfName(name)
+    const record = await loadRestore(key, configDir)
+
+    if (record?.id === backupId) found.push({ key, file: restoreFile(key, configDir), record })
+  }
+
+  return found
+}