From 1a495f5ed3f8a55222d406152c833882264dc377 Mon Sep 17 00:00:00 2001
From: Christophe Besson <cbesson@gmail.com>
Date: Tue, 8 Sep 2026 22:54:16 +0200
Subject: feat(hub): client-side transfer leases and the transfers panel
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Steps 5 and 6 of ~/next/improve-downloads.md. The node has handed out slots
since step 2 and nothing asked for one; now the client does, and the panel shows
what is happening.

`transport.openTransfer()` returns a Lease: `acquire()` resolves when the node
grants, `release()` gives it back exactly once, and nothing else in the client
speaks to the node about slots. Whether a node hands out slots is read from the
handshake ack rather than guessed from a timeout — "no answer yet" and "this
node will never answer" are indistinguishable in time, and guessing wrong either
stalls every download or defeats the cap.

Two things exist only because a queue can lie: a watchdog re-asks when a pushed
grant does not arrive (the node is idempotent on `tr`, so asking again is free),
and a grant for a transfer the page has forgotten is handed straight back rather
than held until the node's deadline.

The slot is asked for **after** there is somewhere to write, and that ordering
is load-bearing: opening a target takes thirty seconds of streamed-download
timeouts, or as long as somebody leaves a Save As dialog open, and a grant not
taken up in time is revoked. Moving it earlier looked better and broke three
downloads into one. Pinned by a test.

The panel groups by state — running, waiting, finished — rather than re-sorting a
flat list, so a row moves only when its own state does. The ETA is withheld until
the speed window holds real measurement: a figure from the first two chunks
swings between four seconds and an hour, and people plan around the first number
they see. One live region announces state changes and not progress.

Three silent paths closed on the way: a download refused for want of a user
gesture (a browser grants one file picker per gesture, and downloading three
files is one gesture) now falls back to the streamed path, which needs none; a
click with no connection says so instead of doing nothing at all; and a queued
transfer counts as busy, so a transport is never closed under one that is
waiting for a grant that could then never arrive.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HCGdheDLxGReuKHga3BtST
---
 packages/meshbay-hub/tests/test_transfers.py | 213 +++++++++++++++++++++++++++
 1 file changed, 213 insertions(+)

(limited to 'packages/meshbay-hub/tests/test_transfers.py')

diff --git a/packages/meshbay-hub/tests/test_transfers.py b/packages/meshbay-hub/tests/test_transfers.py
index 3316615..e805afc 100644
--- a/packages/meshbay-hub/tests/test_transfers.py
+++ b/packages/meshbay-hub/tests/test_transfers.py
@@ -222,3 +222,216 @@ def test_a_folder_name_carries_no_trailing_slash():
     assert "dir-row" in row, "the anchor no longer lands on the directory row"
     assert "${d}/" not in row, "the folder name is rendered with a trailing slash"
     assert "${d}" in row
+
+
+# ── Transfer slots, client side ─────────────────────────────────────────────
+#
+# A queue can lie in two directions, and both are worse than no queue: a
+# transfer that shows "waiting" on a node that already granted it, and a slot
+# the page holds after it has stopped using it. Everything below is one of
+# those two.
+
+def _lease_stub():
+    """A Lease as the store sees it, driveable from the test."""
+    return """
+class L {
+  constructor() {
+    this.state = 'queued'; this.ahead = 2; this.closed = false;
+    this.released = []; this.tr = 'tr1';
+    this._wait = new Promise(r => { this._go = r; });
+  }
+  acquire() { return this._wait; }
+  release(reason) { if (!this.closed) { this.closed = true; this.released.push(reason); } }
+  grant() { this.state = 'granted'; if (this._onState) this._onState(this); this._go(); }
+  push(state, ahead) { this.state = state; this.ahead = ahead; if (this._onState) this._onState(this); }
+}
+"""
+
+
+def test_a_transfer_waiting_for_a_slot_is_queued_not_running(tmp_path):
+    out = _run(_lease_stub() + """
+      const t = new TransferStore();
+      const lease = new L();
+      t.start({ kind: 'download', name: 'f', total: 10, lease,
+                run: async () => { say('ran'); } });
+      say(t.list()[0].status, t.list()[0].ahead);
+      await new Promise(r => setTimeout(r, 0));
+      say('still:' + t.list()[0].status);
+    """, tmp_path)
+    assert out[:2] == ["queued", 2]
+    assert "ran" not in out, "the work started before the slot was granted"
+    assert out[-1] == "still:queued"
+
+
+def test_the_grant_starts_the_work(tmp_path):
+    out = _run(_lease_stub() + """
+      const t = new TransferStore();
+      const lease = new L();
+      t.start({ kind: 'download', name: 'f', total: 10, lease,
+                run: async () => { say('ran:' + t.list()[0].status); } });
+      lease.grant();
+      await new Promise(r => setTimeout(r, 10));
+      say('after:' + t.list()[0].status);
+    """, tmp_path)
+    assert out[0] == "ran:running"
+    assert out[1] == "after:done"
+
+
+def test_the_slot_comes_back_however_the_transfer_ends(tmp_path):
+    """A slot not returned is a member who cannot transfer again until the node
+    times it out — so this must hold for a throw as much as for a success."""
+    out = _run(_lease_stub() + """
+      for (const mode of ['ok', 'throw']) {
+        const t = new TransferStore();
+        const lease = new L();
+        t.start({ kind: 'download', name: 'f', total: 10, lease,
+                  run: async () => { if (mode === 'throw') throw new Error('x'); } });
+        lease.grant();
+        await new Promise(r => setTimeout(r, 10));
+        say(mode + ':' + lease.released.join(',') + ':' + t.list()[0].status);
+      }
+    """, tmp_path)
+    assert out == ["ok:done:done", "throw:done:failed"]
+
+
+def test_cancelling_while_queued_gives_the_slot_back(tmp_path):
+    """The transfer somebody is most likely to give up on is the one that has
+    not started. Its queue entry has to go, or the node grants a slot to a
+    transfer that will never use it."""
+    out = _run(_lease_stub() + """
+      const t = new TransferStore();
+      const lease = new L();
+      const id = t.start({ kind: 'download', name: 'f', total: 10, lease,
+                           run: async () => { say('ran'); } });
+      t.cancel(id);
+      say(t.list()[0].status, lease.released.join(','));
+      lease.grant();
+      await new Promise(r => setTimeout(r, 10));
+      say('ran?', out.includes('ran'));
+    """, tmp_path)
+    assert out[0] == "cancelled"
+    assert out[1] == "cancelled"
+    assert out[-1] is False, "a cancelled transfer ran anyway once granted"
+
+
+def test_a_queue_position_update_reaches_the_view(tmp_path):
+    out = _run(_lease_stub() + """
+      const t = new TransferStore();
+      const lease = new L();
+      const seen = [];
+      t.subscribe(items => seen.push(items[0].ahead));
+      t.start({ kind: 'download', name: 'f', total: 10, lease, run: async () => {} });
+      lease.push('queued', 1);
+      lease.push('queued', 0);
+      say(seen.join('>'));
+    """, tmp_path)
+    assert out[0].endswith("1>0"), "the widget never learns it is moving up"
+
+
+def test_a_transport_with_a_queued_transfer_is_not_closed(tmp_path):
+    """Closing it would leave the transfer waiting for a grant that can never
+    arrive — waiting for ever, with nothing left to answer."""
+    out = _run(_lease_stub() + """
+      const t = new TransferStore();
+      const lease = new L();
+      let closed = false;
+      const transport = { close() { closed = true; } };
+      t.start({ kind: 'download', name: 'f', total: 10, transport, lease,
+                run: async () => {} });
+      t.releaseWhenIdle(transport);
+      say('closed while queued:', closed);
+      lease.grant();
+      await new Promise(r => setTimeout(r, 10));
+      say('closed after:', closed);
+    """, tmp_path)
+    assert out[1] is False
+    assert out[3] is True
+
+
+def test_clearing_finished_keeps_what_is_waiting(tmp_path):
+    out = _run(_lease_stub() + """
+      const t = new TransferStore();
+      const lease = new L();
+      t.start({ kind: 'download', name: 'waiting', total: 1, lease, run: async () => {} });
+      t.start({ kind: 'download', name: 'done', total: 1, run: async () => {} });
+      await new Promise(r => setTimeout(r, 10));
+      t.clearFinished();
+      say(t.list().map(i => i.name + ':' + i.status).join(','));
+    """, tmp_path)
+    assert out[0] == "waiting:queued"
+
+
+def test_asking_for_a_slot_on_a_dead_channel_does_not_throw(tmp_path):
+    """
+    The transport reconnects on its own and re-asks for every live lease when it
+    does, so a closed channel at the moment a transfer starts is a wait, not a
+    failure. `_fetchChunkResilient` has always treated it that way — and before
+    leases existed a chunk request was the first thing to touch the channel, so
+    a download begun on a briefly dead connection simply retried.
+
+    Asking for a slot first made `_send` the first contact. It threw
+    "DataChannel not open (state: closed)" straight out of `downloadEntry`,
+    where nothing catches it: a download that used to recover became an error
+    with no row in the widget to show it. Found live, by downloading a file
+    just after a connection dropped.
+    """
+    module = tmp_path / "transport_lease.mjs"
+    # The real Lease, lifted out as text — the class is not exported, and a
+    # second copy of it here would agree with whatever it was copied from.
+    src = (STATIC / "transport.js").read_text()
+    # From the constant the class depends on, not from the class: lifting only
+    # the class left LEASE_WATCHDOG_MS undefined, which the class reads the
+    # first time it arms its watchdog.
+    start = src.index("const LEASE_WATCHDOG_MS")
+    end = src.index("\nclass MeshBayTransport")
+    module.write_text(src[start:end] + "\nexport { Lease };\n")
+
+    script = tmp_path / "case.mjs"
+    script.write_text(f"""
+import {{ Lease }} from '{module.as_posix()}';
+const out = [];
+const transport = {{
+  supportsTransferSlots: true,
+  _leases: new Map(),
+  _send() {{ throw new Error('DataChannel not open (state: closed)'); }},
+}};
+let threw = null;
+const lease = new Lease(transport, 'tr1', 'download', 10, 1, null);
+try {{ lease._request(); }} catch (e) {{ threw = e.message; }}
+out.push(threw);
+// And releasing one must be just as safe: a lease not released is a member who
+// cannot start another transfer until the node times it out.
+try {{ lease.release('cancelled'); out.push('release ok'); }}
+catch (e) {{ out.push('release threw: ' + e.message); }}
+clearTimeout(lease._watchdog);
+console.log(JSON.stringify(out));
+""")
+    proc = subprocess.run(["node", str(script)], capture_output=True, text=True)
+    assert proc.returncode == 0, proc.stderr
+    out = json.loads(proc.stdout)
+    assert out[0] is None, f"asking for a slot threw: {out[0]}"
+    assert out[1] == "release ok"
+
+
+def test_the_slot_is_asked_for_after_there_is_somewhere_to_write():
+    """
+    A granted slot has to be taken up within the node's acceptance deadline, so
+    it must not be asked for until the download can actually start.
+
+    Asking first reads better — the widget could draw a row while the target is
+    being chosen — and is wrong: opening a target takes thirty seconds of
+    streamed-download timeouts, or as long as somebody leaves a Save As dialog
+    open. The node revokes the grant, passes it to the next in the queue
+    (`transfer: reclaimed … (not_taken_up)` in its log), and the download then
+    fetches under a `tr` that is no longer granted. Three downloads started, one
+    arrived.
+
+    Source-reading, because the ordering is the whole property and it has no
+    behaviour of its own to drive: what matters is which call comes first.
+    """
+    src = (STATIC / "file-utils.js").read_text()
+    fn = src[src.index("async function downloadEntry"):]
+    fn = fn[:fn.index("\n}\n")]
+    assert fn.index("_openDownloadTarget") < fn.index("openTransfer"), (
+        "downloadEntry asks for a transfer slot before it has anywhere to "
+        "write — the grant expires before the download can use it")
-- 
cgit v1.2.3


From 77615ddb5fead3e74751a94847d3bcc99fc0a96d Mon Sep 17 00:00:00 2001
From: Christophe Besson <cbesson@gmail.com>
Date: Tue, 8 Sep 2026 23:43:46 +0200
Subject: fix(hub): the transfers row exists from the click
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Clicking Download produced nothing — no row, no icon, no panel — for as long as
it took to open somewhere to write, and then several rows at once. The streamed
path waits for the worker twice; a Save As dialog waits for a person. The row
was created after that, so the slowest part of a download happened with nothing
on screen to say it had begun.

The store gains a `prepare` step, distinct from `run`, and the order is now:
row, then target, then slot.

That last part is why the obvious fix was wrong. Taking the slot first would let
the row appear immediately, and it was tried this morning: a granted slot has to
be taken up within the node's deadline, opening a target can outlast it, and
three downloads became one. (The diagnosis at the time blamed that ordering for
revocations which were in fact a missing `touch()` call — the revert was right
for the wrong reason.) `makeLease` is called after `prepare` succeeds, never
before.

Three behaviours fall out, each with a test:

  - a dismissed dialog leaves nothing behind. `prepare` returning false drops
    the row: nothing started, so nothing should remain on screen to explain it;
  - the row takes the name the file was actually saved under, once known;
  - a refusal above the memory ceiling fails the row that is already there,
    rather than creating one to kill it.

`preparing` counts as live everywhere — badge, cancel, clearFinished, and
`_busy`, since closing a transport under a preparing transfer strands it exactly
as under a queued one. Six places asked "is this finished?" and were drifting
apart; there is one definition now.

Two mistakes in the tests, worth the note: one counted positions in an output
array by hand and was one out, which reads exactly like a failing assertion
about the code — the values are tagged now, not indexed. And
test_zip_size_limit.py's stub did not run `prepare`, so it no longer reached the
size check the file is about; it now behaves like the real store.

819 hub, 1169 node, 0 failed.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HCGdheDLxGReuKHga3BtST
---
 packages/meshbay-hub/src/meshbay_hub/static/app.js |  23 +++-
 .../src/meshbay_hub/static/file-utils.js           | 111 +++++++++-----------
 .../src/meshbay_hub/static/locales/de.js           |   1 +
 .../src/meshbay_hub/static/locales/en.js           |   1 +
 .../src/meshbay_hub/static/locales/es.js           |   1 +
 .../src/meshbay_hub/static/locales/fr.js           |   1 +
 .../src/meshbay_hub/static/locales/it.js           |   1 +
 .../src/meshbay_hub/static/locales/ja.js           |   1 +
 .../src/meshbay_hub/static/locales/nl.js           |   1 +
 .../src/meshbay_hub/static/locales/pl.js           |   1 +
 .../src/meshbay_hub/static/locales/pt-BR.js        |   1 +
 .../src/meshbay_hub/static/locales/zh-CN.js        |   1 +
 .../src/meshbay_hub/static/transfers.js            |  90 ++++++++++++----
 packages/meshbay-hub/tests/test_transfers.py       | 116 +++++++++++++++++++++
 packages/meshbay-hub/tests/test_zip_size_limit.py  |  17 ++-
 15 files changed, 280 insertions(+), 87 deletions(-)

(limited to 'packages/meshbay-hub/tests/test_transfers.py')

diff --git a/packages/meshbay-hub/src/meshbay_hub/static/app.js b/packages/meshbay-hub/src/meshbay_hub/static/app.js
index ff066cf..6f4bb92 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/app.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/app.js
@@ -157,9 +157,11 @@ function TransferWidget() {
   }, [open]);
 
   const running = items.filter(i => i.status === 'running');
-  const waiting = items.filter(i => i.status === 'queued');
+  const waiting = items.filter(
+    i => i.status === 'queued' || i.status === 'preparing');
   const finished = items.filter(
-    i => i.status !== 'running' && i.status !== 'queued');
+    i => i.status !== 'running' && i.status !== 'queued'
+      && i.status !== 'preparing');
   const active = running.length + waiting.length;
 
   // Grouped, and in this order: what is moving, what is waiting, what is over.
@@ -240,7 +242,8 @@ function TransferRow({ it }) {
           ? html`<a class="transfer-name" href="#" title=${it.name}
               onClick=${(e) => { e.preventDefault(); transfers.open(it.id); }}>${it.name}</a>`
           : html`<span class="transfer-name" title=${it.name}>${it.name}</span>`}
-        ${(it.status === 'running' || it.status === 'queued') && html`
+        ${(it.status === 'running' || it.status === 'queued'
+           || it.status === 'preparing') && html`
           <button class="transfer-cancel"
             aria-label=${t('transfers.cancel_one', { name: it.name })}
             title=${t('transfers.cancel')}
@@ -249,7 +252,19 @@ function TransferRow({ it }) {
           </button>
         `}
       </div>
-      ${it.status === 'queued'
+      ${it.status === 'preparing'
+        ? html`
+          ${/* Not a progress bar at 0%: nothing is wrong and nothing is
+                stalled, the download is still finding somewhere to write. The
+                row exists from the click precisely so this state is visible
+                instead of being an empty panel. */''}
+          <div class="dl-progress dl-waiting"></div>
+          <div class="transfer-meta">
+            <span>${t('transfers.preparing')}</span>
+            <span>${formatSize(it.total)}</span>
+          </div>
+        `
+        : it.status === 'queued'
         ? html`
           <div class="dl-progress dl-waiting"></div>
           <div class="transfer-meta">
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/file-utils.js b/packages/meshbay-hub/src/meshbay_hub/static/file-utils.js
index 61002d6..3475f81 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/file-utils.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/file-utils.js
@@ -321,47 +321,34 @@ async function pipelinedDownload(transport, gekKey, fileId, totalChunks, onChunk
  * download button — both just want "get this entry to disk".
  */
 async function downloadEntry(transfers, transport, gek, entry) {
-  // The target FIRST, then the slot — and that order is load-bearing.
-  //
-  // Asking for the slot first looks better (the widget could draw a row while
-  // the target is being chosen) and is wrong: a granted slot has to be taken up
-  // within the node's acceptance deadline, and opening a target can take thirty
-  // seconds of streamed-download timeouts, or as long as somebody leaves a Save
-  // As dialog open. The node then revokes the grant and passes it to the next
-  // in the queue — `transfer: reclaimed … (not_taken_up)` in its log — and this
-  // download starts fetching under a `tr` that is no longer granted.
-  //
-  // Measured, not reasoned: three downloads started, one arrived, and the
-  // node's log named the reason. Do not move this again without moving the
-  // deadline, and the deadline exists so a client that dies between asking and
-  // starting does not hold a slot nobody can use.
-  let target;
-  try {
-    target = await _openDownloadTarget(entry.name, entry.size);
-  } catch (err) {
-    // The refusal belongs in the transfers panel, not in a console nobody
-    // opens: that is where someone who just clicked Download is looking, and a
-    // failed row naming the reason is the whole point of refusing rather than
-    // filling the tab. Started only to be failed, deliberately.
-    transfers.start({
-      kind: 'download', name: entry.name, total: entry.size, transport,
-      run: async () => { throw err; },
-    });
-    return;
-  }
-  if (target === false) return;          // the picker was dismissed
-
-  const openRef = { url: null };
   const totalChunks = Math.ceil(entry.size / CHUNK_SIZE);
+  const openRef = { url: null };
+  let target = null;
+
   transfers.start({
-    kind: 'download', name: (target && target.name) || entry.name,
-    total: entry.size, transport,
-    // Asked for here, once there is somewhere to write: see the note above.
-    lease: transport.openTransfer({
+    kind: 'download', name: entry.name, total: entry.size, transport,
+
+    // The row exists from the click. Opening a target is what takes the time —
+    // the streamed path waits for the worker (twice), a Save As dialog waits
+    // for a person — and doing it before the row meant three clicks produced no
+    // panel at all and then several rows at once.
+    prepare: async () => {
+      target = await _openDownloadTarget(entry.name, entry.size);
+      // Dismissed: nothing was started, so nothing is left on screen.
+      if (target === false) return false;
+      return target ? { name: target.name } : true;
+    },
+
+    // After the target, never before: a granted slot has to be taken up within
+    // the node's deadline, and opening a target can outlast it. See §8.1 of
+    // ~/next/improve-downloads.md — the other order was tried and cost two of
+    // three downloads.
+    makeLease: () => transport.openTransfer({
       kind: 'download', bytes: entry.size, chunks: totalChunks }),
-    open: target
-      ? (target.open || null)
-      : () => { if (openRef.url) window.open(openRef.url, '_blank'); },
+
+    open: () => (target && target.open) ? target.open()
+      : (openRef.url ? window.open(openRef.url, '_blank') : undefined),
+
     run: async ({ signal, onProgress, lease }) => {
       let done = 0;
       const onChunk = (bytes) => { done += bytes; onProgress(done, entry.size); };
@@ -435,38 +422,36 @@ async function downloadDirectory(transfers, transport, gek, entries, dir, { setE
   // totalBytes decides how this is delivered, but it is not the archive's
   // size — headers and the central directory come on top — so it is not
   // announced as a Content-Length that the download would then miss.
-  let target;
-  try {
-    target = await _openDownloadTarget(suggested, totalBytes, {
-      types: [{ description: 'ZIP archive',
-                accept: { 'application/zip': ['.zip'] } }],
-    }, 0);
-  } catch (err) {
-    // Reported beside the folder that was clicked, like zip_too_large just
-    // above — this function is called in a loop over a selection, and the
-    // sibling folders must still download.
-    setError(err.message);
-    return;
-  }
-  if (target === false) return;
-  if (!target && !confirm(t('group.zip_no_stream', {
-    size: formatSize(totalBytes), name: suggested,
-  }))) {
-    return;
-  }
   const zipOpenRef = { url: null };
+  let target = null;
 
   transfers.start({
-    kind: 'download', name: (target && target.name) || suggested,
-    total: totalBytes, transport,
+    kind: 'download', name: suggested, total: totalBytes, transport,
+
+    // Same order as downloadEntry: the row first, then the target, then the
+    // slot. A folder of forty files is exactly where the wait is longest.
+    prepare: async () => {
+      target = await _openDownloadTarget(suggested, totalBytes, {
+        types: [{ description: 'ZIP archive',
+                  accept: { 'application/zip': ['.zip'] } }],
+      }, 0);
+      if (target === false) return false;
+      if (!target && !confirm(t('group.zip_no_stream', {
+        size: formatSize(totalBytes), name: suggested,
+      }))) {
+        return false;
+      }
+      return target ? { name: target.name } : true;
+    },
+
     // **One** lease for the archive, not one per file. Dozens of leases for a
     // folder would deadlock against the member's own cap: the job cannot finish
     // until it holds them all, and it can never hold more than two.
-    lease: transport.openTransfer({
+    makeLease: () => transport.openTransfer({
       kind: 'download', bytes: totalBytes, chunks: files.length }),
-    open: target
-      ? (target.open || null)
-      : () => { if (zipOpenRef.url) window.open(zipOpenRef.url, '_blank'); },
+
+    open: () => (target && target.open) ? target.open()
+      : (zipOpenRef.url ? window.open(zipOpenRef.url, '_blank') : undefined),
     run: async ({ signal, onProgress, lease }) => {
       const writable = target ? target.writable : null;
       const parts = writable ? null : [];
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/locales/de.js b/packages/meshbay-hub/src/meshbay_hub/static/locales/de.js
index f5c0c78..1458cf2 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/locales/de.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/locales/de.js
@@ -578,6 +578,7 @@ export default {
   'transfers.open': 'Öffnen',
   'transfers.done': 'Abgeschlossen',
   'transfers.cancelled': 'Abgebrochen',
+  'transfers.preparing': 'Wird vorbereitet…',
   'transfers.waiting_own_slots': 'Wartet — Ihre Plätze sind belegt',
   'transfers.waiting_node': 'Wartet — {n} davor',
   'transfers.summary': '{running} laufend · {waiting} wartend',
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/locales/en.js b/packages/meshbay-hub/src/meshbay_hub/static/locales/en.js
index e3ed844..b0430c0 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/locales/en.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/locales/en.js
@@ -694,6 +694,7 @@ export default {
   'transfers.open': 'Open',
   'transfers.done': 'Finished',
   'transfers.cancelled': 'Cancelled',
+  'transfers.preparing': 'Preparing…',
   'transfers.waiting_own_slots': 'Waiting — your slots are busy',
   'transfers.waiting_node': 'Waiting — {n} ahead',
   'transfers.summary': '{running} running · {waiting} waiting',
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/locales/es.js b/packages/meshbay-hub/src/meshbay_hub/static/locales/es.js
index c509599..adfb1cc 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/locales/es.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/locales/es.js
@@ -574,6 +574,7 @@ export default {
   'transfers.open': 'Abrir',
   'transfers.done': 'Terminada',
   'transfers.cancelled': 'Cancelada',
+  'transfers.preparing': 'Preparando…',
   'transfers.waiting_own_slots': 'En espera — sus espacios están ocupados',
   'transfers.waiting_node': 'En espera — {n} por delante',
   'transfers.summary': '{running} en curso · {waiting} en espera',
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/locales/fr.js b/packages/meshbay-hub/src/meshbay_hub/static/locales/fr.js
index 49a1071..b409927 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/locales/fr.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/locales/fr.js
@@ -577,6 +577,7 @@ export default {
   'transfers.open': 'Ouvrir',
   'transfers.done': 'Terminé',
   'transfers.cancelled': 'Annulé',
+  'transfers.preparing': 'Préparation…',
   'transfers.waiting_own_slots': 'En attente — vos slots sont occupés',
   'transfers.waiting_node': 'En attente — {n} devant',
   'transfers.summary': '{running} en cours · {waiting} en attente',
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/locales/it.js b/packages/meshbay-hub/src/meshbay_hub/static/locales/it.js
index 8f1ef1e..7e6246e 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/locales/it.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/locales/it.js
@@ -577,6 +577,7 @@ export default {
   'transfers.open': 'Apri',
   'transfers.done': 'Completato',
   'transfers.cancelled': 'Annullato',
+  'transfers.preparing': 'Preparazione…',
   'transfers.waiting_own_slots': 'In attesa — i suoi posti sono occupati',
   'transfers.waiting_node': 'In attesa — {n} prima',
   'transfers.summary': '{running} in corso · {waiting} in attesa',
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/locales/ja.js b/packages/meshbay-hub/src/meshbay_hub/static/locales/ja.js
index 7ea9789..a74eec9 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/locales/ja.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/locales/ja.js
@@ -569,6 +569,7 @@ export default {
   'transfers.open': '開く',
   'transfers.done': '完了',
   'transfers.cancelled': 'キャンセル済み',
+  'transfers.preparing': '準備中…',
   'transfers.waiting_own_slots': '待機中 — 自分の枠がすべて使用中です',
   'transfers.waiting_node': '待機中 — 前に {n} 件',
   'transfers.summary': '実行中 {running} · 待機中 {waiting}',
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/locales/nl.js b/packages/meshbay-hub/src/meshbay_hub/static/locales/nl.js
index 74cd269..a7d64f7 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/locales/nl.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/locales/nl.js
@@ -578,6 +578,7 @@ export default {
   'transfers.open': 'Openen',
   'transfers.done': 'Voltooid',
   'transfers.cancelled': 'Geannuleerd',
+  'transfers.preparing': 'Voorbereiden…',
   'transfers.waiting_own_slots': 'Wacht — uw plaatsen zijn bezet',
   'transfers.waiting_node': 'Wacht — {n} ervoor',
   'transfers.summary': '{running} bezig · {waiting} wachtend',
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/locales/pl.js b/packages/meshbay-hub/src/meshbay_hub/static/locales/pl.js
index 584e5f2..5bd34fb 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/locales/pl.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/locales/pl.js
@@ -590,6 +590,7 @@ export default {
   'transfers.open': 'Otwórz',
   'transfers.done': 'Zakończony',
   'transfers.cancelled': 'Anulowany',
+  'transfers.preparing': 'Przygotowywanie…',
   'transfers.waiting_own_slots': 'Oczekiwanie — Twoje miejsca są zajęte',
   'transfers.waiting_node': 'Oczekiwanie — {n} przed',
   'transfers.summary': '{running} w toku · {waiting} oczekuje',
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/locales/pt-BR.js b/packages/meshbay-hub/src/meshbay_hub/static/locales/pt-BR.js
index b034117..102ec92 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/locales/pt-BR.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/locales/pt-BR.js
@@ -576,6 +576,7 @@ export default {
   'transfers.open': 'Abrir',
   'transfers.done': 'Concluída',
   'transfers.cancelled': 'Cancelada',
+  'transfers.preparing': 'Preparando…',
   'transfers.waiting_own_slots': 'Aguardando — seus espaços estão ocupados',
   'transfers.waiting_node': 'Aguardando — {n} na frente',
   'transfers.summary': '{running} em andamento · {waiting} aguardando',
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/locales/zh-CN.js b/packages/meshbay-hub/src/meshbay_hub/static/locales/zh-CN.js
index ffe2cb0..6b64785 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/locales/zh-CN.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/locales/zh-CN.js
@@ -557,6 +557,7 @@ export default {
   'transfers.open': '打开',
   'transfers.done': '已完成',
   'transfers.cancelled': '已取消',
+  'transfers.preparing': '准备中…',
   'transfers.waiting_own_slots': '等待中 — 您的通道已占满',
   'transfers.waiting_node': '等待中 — 前面还有 {n} 个',
   'transfers.summary': '进行中 {running} · 等待中 {waiting}',
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/transfers.js b/packages/meshbay-hub/src/meshbay_hub/static/transfers.js
index 46f75a2..d3b164d 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/transfers.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/transfers.js
@@ -22,6 +22,12 @@
 
 const SPEED_WINDOW_MS = 5000;
 
+/** Not finished: still preparing, waiting for a slot, or transferring. One
+ *  definition, because six places ask and they were drifting apart. */
+function _live(status) {
+  return status === 'preparing' || status === 'queued' || status === 'running';
+}
+
 function _abortError() {
   const err = new Error('Cancelled');
   err.name = 'AbortError';
@@ -84,8 +90,7 @@ export class TransferStore {
 
   /** Running or waiting for a slot — what the nav badge counts. */
   get pending() {
-    return this._items.filter(
-      it => it.status === 'running' || it.status === 'queued').length;
+    return this._items.filter(it => _live(it.status)).length;
   }
 
   _speed(it) {
@@ -104,8 +109,28 @@ export class TransferStore {
    * `run` receives `{ signal, onProgress }`. It must poll `signal.aborted` — a
    * cancel that only sets a flag nobody reads is a button that lies.
    */
+  /**
+   * Start a transfer.
+   *
+   * `run` receives `{ signal, onProgress, lease }`. It must poll
+   * `signal.aborted` — a cancel that only sets a flag nobody reads is a button
+   * that lies.
+   *
+   * `prepare` is optional and runs before anything else, with the row already
+   * on screen. It is where a download opens its target, which can take tens of
+   * seconds — the streamed path waits for the worker, twice, and a Save As
+   * dialog waits for a person. Doing that *before* creating the row meant three
+   * clicks produced no panel at all, not even the icon, and then several rows
+   * at once. Returning `false` drops the row again, which is what a dismissed
+   * dialog should look like: nothing, rather than a cancelled transfer nobody
+   * started.
+   *
+   * `makeLease` is called after `prepare` succeeds, never before. A granted
+   * slot must be taken up within the node's deadline, so it is asked for once
+   * there is somewhere to write — see file-utils.js's downloadEntry.
+   */
   start({ kind, name, total = 0, transport = null, run, open = null,
-          lease = null }) {
+          lease = null, prepare = null, makeLease = null }) {
     const item = {
       id: _nextId++,
       kind, name, total, transport, open, lease,
@@ -114,7 +139,8 @@ export class TransferStore {
       // 'running'. Two different things are true of it — nothing is moving, and
       // nothing is wrong — and a status that conflates them is what makes a
       // queue look like a hang.
-      status: lease && lease.state !== 'granted' ? 'queued' : 'running',
+      status: prepare ? 'preparing'
+        : (lease && lease.state !== 'granted' ? 'queued' : 'running'),
       ahead: (lease && lease.ahead) || 0,
       error: '',
       samples: [{ t: this._now(), done: 0 }],
@@ -155,17 +181,32 @@ export class TransferStore {
     // appear to move — the widget showing "3 ahead" for ever while the node
     // quietly worked through the queue. Nothing about that looks wrong from
     // either side, which is why it needs a test rather than a reading.
-    if (item.lease) {
-      item.lease._onState = (lease) => {
-        if (item.status !== 'queued' && item.status !== 'running') return;
-        item.ahead = lease.ahead;
-        item.status = lease.state === 'granted' ? 'running' : 'queued';
-        this._emit();
-      };
-    }
+    if (item.lease) this._watchLease(item);
 
     const promise = Promise.resolve()
       .then(async () => {
+        if (prepare) {
+          const ready = await prepare();
+          if (item.signal.aborted) throw _abortError();
+          if (ready === false) {
+            // Dismissed. Not a failure and not a cancellation: nothing was ever
+            // started, so nothing should be left on screen to explain.
+            this._drop(item.id);
+            return undefined;
+          }
+          if (ready && ready.name) item.name = ready.name;
+          item.status = 'running';
+          this._emit();
+        }
+        if (makeLease && !item.lease) {
+          item.lease = makeLease();
+          this._watchLease(item);
+          if (item.lease.state !== 'granted') {
+            item.status = 'queued';
+            item.ahead = item.lease.ahead || 0;
+            this._emit();
+          }
+        }
         if (item.lease) {
           await item.lease.acquire();
           if (item.signal.aborted) throw _abortError();
@@ -191,6 +232,21 @@ export class TransferStore {
     return item.id;
   }
 
+  _watchLease(item) {
+    item.lease._onState = (lease) => {
+      if (item.status !== 'queued' && item.status !== 'running') return;
+      item.ahead = lease.ahead;
+      item.status = lease.state === 'granted' ? 'running' : 'queued';
+      this._emit();
+    };
+  }
+
+  /** Remove a row entirely. Only for a transfer that never started. */
+  _drop(id) {
+    this._items = this._items.filter(it => it.id !== id);
+    this._emit();
+  }
+
   /**
    * Hand a finished download to the browser to display.
    *
@@ -209,7 +265,7 @@ export class TransferStore {
     // 'queued' too: a transfer waiting for a slot is exactly the one somebody
     // is most likely to give up on, and its queue entry has to go with it or
     // the node grants a slot to a transfer that will never use it.
-    if (!item || (item.status !== 'running' && item.status !== 'queued')) return;
+    if (!item || !_live(item.status)) return;
     item.signal.aborted = true;
     if (item.lease) item.lease.release('cancelled');
     // Marked at once. The work stops when it next looks, but a cancelled
@@ -221,14 +277,13 @@ export class TransferStore {
 
   cancelAll() {
     for (const it of this._items) {
-      if (it.status === 'running' || it.status === 'queued') this.cancel(it.id);
+      if (_live(it.status)) this.cancel(it.id);
     }
   }
 
   /** Drop everything finished, keeping what is still running or waiting. */
   clearFinished() {
-    this._items = this._items.filter(
-      it => it.status === 'running' || it.status === 'queued');
+    this._items = this._items.filter(it => _live(it.status));
     this._emit();
   }
 
@@ -237,8 +292,7 @@ export class TransferStore {
     // slot can never be granted one, and the transfer would sit at "waiting"
     // for ever with nothing left to answer it.
     return this._items.some(
-      it => it.transport === transport
-        && (it.status === 'running' || it.status === 'queued'));
+      it => it.transport === transport && _live(it.status));
   }
 
   /**
diff --git a/packages/meshbay-hub/tests/test_transfers.py b/packages/meshbay-hub/tests/test_transfers.py
index e805afc..7e21409 100644
--- a/packages/meshbay-hub/tests/test_transfers.py
+++ b/packages/meshbay-hub/tests/test_transfers.py
@@ -435,3 +435,119 @@ def test_the_slot_is_asked_for_after_there_is_somewhere_to_write():
     assert fn.index("_openDownloadTarget") < fn.index("openTransfer"), (
         "downloadEntry asks for a transfer slot before it has anywhere to "
         "write — the grant expires before the download can use it")
+
+
+# ── the row exists from the click ───────────────────────────────────────────
+
+def test_the_row_appears_before_the_target_is_open(tmp_path):
+    """
+    Opening a target is the slow part — the streamed path waits for the worker
+    twice, a Save As dialog waits for a person — and the row used to be created
+    only after it returned. Three clicks produced no panel at all, not even the
+    icon, and then several rows at once.
+    """
+    out = _run("""
+      const t = new TransferStore();
+      let release;
+      const opened = new Promise(r => { release = r; });
+      t.start({ kind: 'download', name: 'film.mkv', total: 10,
+                prepare: async () => { await opened; return { name: 'saved.mkv' }; },
+                run: async () => { say('ran'); } });
+      const shot = (when) => say(when + '=' + t.list().length + ':'
+        + t.list().map(i => i.status + '/' + i.name).join(','));
+      shot('click');
+      release();
+      await new Promise(r => setTimeout(r, 10));
+      shot('after');
+    """, tmp_path)
+    # Tagged, not indexed. An earlier version counted pushes by hand and was one
+    # out, which reads exactly like a failing assertion about the code.
+    seen = dict(line.split("=", 1) for line in out
+                if isinstance(line, str) and "=" in line)
+    assert {"click", "after"} <= set(seen), f"probe produced: {out}"
+    assert seen["click"] == "1:preparing/film.mkv", (
+        f"no row, or the wrong one, at the moment of the click: {seen['click']}")
+    assert seen["after"] == "1:done/saved.mkv", (
+        f"the row must keep the name it was saved under: {seen['after']}")
+
+
+def test_a_dismissed_dialog_leaves_nothing_behind(tmp_path):
+    """Dismissing a Save As dialog is not a failure and not a cancellation:
+    nothing was started, so nothing should be left on screen explaining it."""
+    out = _run("""
+      const t = new TransferStore();
+      t.start({ kind: 'download', name: 'film.mkv', total: 10,
+                prepare: async () => false,
+                run: async () => { say('ran'); } });
+      say('at click:', t.list().length);
+      await new Promise(r => setTimeout(r, 10));
+      say('after:', t.list().length, out.includes('ran'));
+    """, tmp_path)
+    assert out[1] == 1
+    assert out[3] == 0, "a dismissed dialog left a row behind"
+    assert out[4] is False
+
+
+def test_the_slot_is_only_asked_for_once_there_is_somewhere_to_write(tmp_path):
+    """
+    A granted slot must be taken up within the node's deadline, and opening a
+    target can outlast it. Asking first cost two of three downloads.
+    """
+    out = _run("""
+      const t = new TransferStore();
+      let release;
+      const opened = new Promise(r => { release = r; });
+      let asked = false;
+      t.start({ kind: 'download', name: 'f', total: 10,
+                prepare: async () => { await opened; return true; },
+                makeLease: () => { asked = true; return {
+                  state: 'granted', ahead: 0, tr: 'x',
+                  acquire: () => Promise.resolve(), release: () => {} }; },
+                run: async () => {} });
+      say('while preparing, asked?', asked);
+      release();
+      await new Promise(r => setTimeout(r, 10));
+      say('after preparing, asked?', asked, t.list()[0].status);
+    """, tmp_path)
+    assert out[1] is False, "the slot was taken before there was a target"
+    assert out[3] is True
+    assert out[4] == "done"
+
+
+def test_a_target_that_cannot_be_opened_fails_the_row_it_already_has(tmp_path):
+    """The refusal above the memory ceiling lands in the panel, on the row that
+    is already there, rather than in a console nobody opens."""
+    out = _run("""
+      const t = new TransferStore();
+      t.start({ kind: 'download', name: 'film.mkv', total: 10,
+                prepare: async () => { throw new Error('too large for memory'); },
+                run: async () => { say('ran'); } });
+      await new Promise(r => setTimeout(r, 10));
+      const it = t.list()[0];
+      say(it.status, it.error, out.includes('ran'));
+    """, tmp_path)
+    assert out[0] == "failed"
+    assert "too large" in out[1]
+    assert out[2] is False
+
+
+def test_a_transport_is_not_closed_under_a_preparing_transfer(tmp_path):
+    """It has no lease yet and has moved no bytes, but closing its transport
+    would strand it exactly like a queued one."""
+    out = _run("""
+      const t = new TransferStore();
+      let release;
+      const opened = new Promise(r => { release = r; });
+      let closed = false;
+      const transport = { close() { closed = true; } };
+      t.start({ kind: 'download', name: 'f', total: 10, transport,
+                prepare: async () => { await opened; return true; },
+                run: async () => {} });
+      t.releaseWhenIdle(transport);
+      say('closed while preparing:', closed);
+      release();
+      await new Promise(r => setTimeout(r, 10));
+      say('closed after:', closed);
+    """, tmp_path)
+    assert out[1] is False
+    assert out[3] is True
diff --git a/packages/meshbay-hub/tests/test_zip_size_limit.py b/packages/meshbay-hub/tests/test_zip_size_limit.py
index e970c55..28e3a0c 100644
--- a/packages/meshbay-hub/tests/test_zip_size_limit.py
+++ b/packages/meshbay-hub/tests/test_zip_size_limit.py
@@ -60,7 +60,7 @@ globalThis.localStorage = {{
 // Node 22 defines `navigator` itself, so it is left alone; `window` is what
 // platform.js reaches for to decide it is not running in the desktop app.
 globalThis.window = globalThis;
-const out = {{ errors: [], started: 0, asked: 0 }};
+const out = {{ errors: [], started: 0, asked: 0, dropped: 0 }};
 // Reached only once the size check has passed: with no File System Access API
 // under Node, downloadDirectory falls through to its build-in-memory path and
 // asks first. Answering yes is what lets the at-the-limit case get as far as
@@ -80,7 +80,18 @@ if ({picker_js}) {{
 
 const M = await import('{(sandbox / "file-utils.js").as_posix()}');
 
-const transfers = {{ start: () => {{ out.started += 1; }} }};
+// Faithful enough to the real store: it runs `prepare` and honours what it
+// returns. The target is opened there now — the row exists from the click and
+// the slow part happens behind it — so a stub that only counts calls would
+// never reach the size check this file is about.
+const transfers = {{ start: (opts) => {{
+  out.started += 1;
+  if (!opts.prepare) return;
+  Promise.resolve()
+    .then(() => opts.prepare())
+    .then((ready) => {{ if (ready === false) {{ out.started -= 1; out.dropped += 1; }} }})
+    .catch((e) => {{ out.started -= 1; out.errors.push(e.message); }});
+}} }};
 // A transport hands out transfer slots now (transfers.py's leases). The stub
 // grants at once, which is what a node with no caps does: what this file is
 // about is the archive limit, not the queue.
@@ -100,6 +111,8 @@ await M.downloadDirectory(transfers, transport, null, entries, 'album', {{
   setError: (m) => out.errors.push(m),
 }});
 
+// `prepare` runs on a microtask, so let it.
+await new Promise(r => setTimeout(r, 10));
 out.limit = M.ZIP_MAX_BYTES;
 console.log(JSON.stringify(out));
 """, encoding="utf-8")
-- 
cgit v1.2.3


From d6c4808d9a3ef6bc740cda7892508f15ee9ea030 Mon Sep 17 00:00:00 2001
From: Christophe Besson <cbesson@gmail.com>
Date: Wed, 9 Sep 2026 01:54:10 +0200
Subject: fix(spa): one save dialog per batch, not one per file
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Selecting four files on Chrome produced a Save As dialog for the first, then
one for the second only after that file had finished, while the last two timed
out; on a later attempt the three remaining transfers appeared frozen.

Two things were going on. Opening the target inside `prepare` had removed the
accidental serialisation that `for (…) await downloadFile(e)` used to provide,
so `_openTargetInTurn` now queues the openings — but a queue whose head is an
unanswered dialog is a head-of-line block, which is what the "freeze" was.

The code already recovered from a picker with no gesture behind it by streaming
instead, on the `SecurityError` Chrome throws. That branch was never reached:
Chrome does not throw, it shows the dialog anyway and waits for a human. So
anything that has to wait its turn is now marked `batched`, and a batched
opening prefers the streamed path whatever the download mode says. The first
file of a batch — the one actually holding the gesture — still gets its dialog,
so the preference is honoured where it can be. For the rest there is no gesture
left to spend and nothing is lost by streaming: the file still lands on disk,
in the browser's own download folder. Only the choice of folder goes, and it
was not on offer. If the worker does not answer, a batched download falls back
to the dialog rather than failing.

Also logs which path led to a dialog. A dialog is the one outcome nobody can
diagnose after the fact — it looks the same whether it was asked for or fallen
back to — and the report this fixes needed three test cycles to narrow. The two
harnesses that lift `_openDownloadTarget` as text now route console.info to
stderr, since they parse stdout as JSON.

Measured against the deployed hub in Chrome 152: the streamed path serves the
hidden iframe in 2-3 ms on a normal load, after a hard reload (via the
`mbdl-claim` recovery already in `_claimController`), and twice in the same
document. Hub suite 824 passed.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HCGdheDLxGReuKHga3BtST
---
 .../src/meshbay_hub/static/file-utils.js           | 58 +++++++++++++++++--
 packages/meshbay-hub/tests/test_downloads.py       | 66 +++++++++++++++++++++-
 packages/meshbay-hub/tests/test_memory_ceiling.py  | 53 ++++++++++++++++-
 packages/meshbay-hub/tests/test_transfers.py       |  4 +-
 packages/meshbay-hub/tests/test_zip_size_limit.py  |  4 ++
 5 files changed, 177 insertions(+), 8 deletions(-)

(limited to 'packages/meshbay-hub/tests/test_transfers.py')

diff --git a/packages/meshbay-hub/src/meshbay_hub/static/file-utils.js b/packages/meshbay-hub/src/meshbay_hub/static/file-utils.js
index 3475f81..065079b 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/file-utils.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/file-utils.js
@@ -98,7 +98,7 @@ class TooLargeForMemoryError extends Error {
  * bare `return null` appears in this function.
  */
 async function _openDownloadTarget(filename, size = 0, pickerOpts = {},
-                                   swSize = size) {
+                                   swSize = size, { batched = false } = {}) {
   // "Collect it in the page", or a refusal when that would be too much.
   const _memoryFloor = () => {
     if (size > MEMORY_CEILING) throw new TooLargeForMemoryError(filename, size);
@@ -144,7 +144,18 @@ async function _openDownloadTarget(filename, size = 0, pickerOpts = {},
   // this block left nothing but the in-memory floor. A preference must not cost
   // a capability.
   const canPick = typeof window.showSaveFilePicker === 'function';
-  if (downloads.getMode() === 'auto' || (size > MEMORY_CEILING && !canPick)) {
+  // `batched` means this is not the first download of a batch, and it makes the
+  // streamed path preferred whatever the mode.
+  //
+  // "Ask where to save" asks per file, which is right for one file and wrong
+  // for four: a browser grants one picker per user gesture, so the second
+  // dialog has no gesture behind it and the third and fourth wait behind a
+  // dialog that waits for a human — reported from Chrome as three downloads
+  // frozen. There is no gesture left to spend, so there is nothing to lose by
+  // streaming instead: the file still lands on disk, in the browser's own
+  // download folder. Only the choice of folder goes, and it was not on offer.
+  if (downloads.getMode() === 'auto' || batched
+      || (size > MEMORY_CEILING && !canPick)) {
     const streamed = await downloads.openStreamedDownload(filename, swSize);
     if (streamed) return streamed;
     // Nothing to stream to: small enough for memory, and no dialog. The old
@@ -157,6 +168,13 @@ async function _openDownloadTarget(filename, size = 0, pickerOpts = {},
   // No File System Access API — Firefox, Safari. This is the branch that used
   // to return null at any size.
   if (!canPick) return _memoryFloor();
+  // A dialog is the one outcome nobody can diagnose after the fact: it looks
+  // the same whether it was asked for, or fallen back to because the worker
+  // did not answer. Say which, once per download, so the next report from a
+  // browser we do not have does not need a second round trip.
+  console.info('[MeshBay] asking where to save %s — mode=%s batched=%s stream=%s',
+               filename, downloads.getMode(), batched,
+               downloads.lastStreamFailure() || 'not attempted');
   try {
     const handle = await window.showSaveFilePicker({
       suggestedName: filename, ...pickerOpts,
@@ -187,6 +205,38 @@ async function _openDownloadTarget(filename, size = 0, pickerOpts = {},
   }
 }
 
+// Target openings run one at a time, across every download on the page.
+//
+// A browser shows one file picker at a time and grants one per user gesture, so
+// four downloads asking at once get one dialog and three failures. That used to
+// be prevented by accident: `downloadEntry` awaited the target inline, and
+// files-app.js's `for (const e of selected) await downloadFile(e)` serialised
+// them. Opening the target inside `prepare` — so the row appears at the click
+// instead of tens of seconds later — removed that accident, and four pickers
+// raced. Chrome showed one, prompted for a second, and the rest timed out;
+// Firefox and Electron never noticed, because neither opens a picker at all.
+//
+// So the queue is explicit now, and it is the *targets* that queue, not the
+// rows: every download still appears the moment it is asked for.
+let _targetQueue = Promise.resolve();
+
+let _targetsInFlight = 0;
+
+function _openTargetInTurn(filename, size, pickerOpts, swSize) {
+  // Anything that has to wait its turn is, by definition, not the first of the
+  // batch — so it will not be the one holding the user's gesture.
+  const batched = _targetsInFlight > 0;
+  _targetsInFlight += 1;
+  const mine = _targetQueue
+    .then(() => _openDownloadTarget(filename, size, pickerOpts, swSize,
+                                    { batched }))
+    .finally(() => { _targetsInFlight -= 1; });
+  // The chain must not break on a rejection, or one refused download stops
+  // every later one from ever opening a target.
+  _targetQueue = mine.catch(() => {});
+  return mine;
+}
+
 /** The download of last resort, for browsers with no way to stream to disk. */
 function _saveBlob(blob, filename) {
   const url = URL.createObjectURL(blob);
@@ -333,7 +383,7 @@ async function downloadEntry(transfers, transport, gek, entry) {
     // for a person — and doing it before the row meant three clicks produced no
     // panel at all and then several rows at once.
     prepare: async () => {
-      target = await _openDownloadTarget(entry.name, entry.size);
+      target = await _openTargetInTurn(entry.name, entry.size);
       // Dismissed: nothing was started, so nothing is left on screen.
       if (target === false) return false;
       return target ? { name: target.name } : true;
@@ -431,7 +481,7 @@ async function downloadDirectory(transfers, transport, gek, entries, dir, { setE
     // Same order as downloadEntry: the row first, then the target, then the
     // slot. A folder of forty files is exactly where the wait is longest.
     prepare: async () => {
-      target = await _openDownloadTarget(suggested, totalBytes, {
+      target = await _openTargetInTurn(suggested, totalBytes, {
         types: [{ description: 'ZIP archive',
                   accept: { 'application/zip': ['.zip'] } }],
       }, 0);
diff --git a/packages/meshbay-hub/tests/test_downloads.py b/packages/meshbay-hub/tests/test_downloads.py
index e68396f..81ab9d3 100644
--- a/packages/meshbay-hub/tests/test_downloads.py
+++ b/packages/meshbay-hub/tests/test_downloads.py
@@ -154,7 +154,10 @@ def test_a_length_is_only_promised_when_it_is_known(tmp_path):
     # the ability to refuse an oversized download (test_memory_ceiling.py).
     # What this test is about -- the `0` -- did not move.
     app = (STATIC / "file-utils.js").read_text()
-    zip_call = app[app.index("_openDownloadTarget(suggested"):]
+    # Anchored on the argument list, not on the function name: the call became
+    # `_openTargetInTurn(suggested, …)` when target openings were serialised.
+    # The `0` this test is about did not move.
+    zip_call = app[app.index("(suggested, totalBytes"):]
     zip_call = zip_call[:zip_call.index(");") + 2]
     assert zip_call.rstrip().endswith(", 0);"), (
         "the zip download announces a Content-Length it will not match")
@@ -363,3 +366,64 @@ def test_the_worker_is_kept_alive_while_it_streams():
     # event, but the reply is what tells the page it is talking to the worker
     # that holds its stream.
     assert "mbdl-ping" in sw and "mbdl-pong" in sw
+
+
+def test_targets_are_opened_one_at_a_time(tmp_path):
+    """
+    A browser shows one file picker at a time and grants one per user gesture,
+    so four downloads asking at once get one dialog and three failures.
+
+    That used to be prevented by accident: `downloadEntry` awaited the target
+    inline and files-app.js's `for (…) await downloadFile(e)` serialised them.
+    Opening the target inside `prepare` — so the row appears at the click rather
+    than tens of seconds later — removed the accident, and four pickers raced.
+    Reported from Chrome: one file downloaded, a prompt for the second, the
+    other two timed out. Firefox and Electron never noticed, because neither
+    opens a picker at all, which is why this reached one browser only.
+
+    The queue is on the *targets*, never on the rows: every download still
+    appears the moment it is asked for.
+
+    Queueing alone was not enough: a second dialog with no gesture behind it
+    still waits for a human, and the two behind it wait for the dialog. So
+    everything that has to wait its turn is also marked `batched`, which the
+    opener reads as "do not ask" — see the streamed-path branch below.
+    """
+    src = (STATIC / "file-utils.js").read_text()
+    fn = src[src.index("function _openTargetInTurn"):]
+    fn = fn[:fn.index("\n}\n") + 2]
+
+    script = tmp_path / "case.mjs"
+    script.write_text("""
+const out = [];
+let live = 0, peak = 0;
+// Stands in for _openDownloadTarget: records how many are open at once.
+const asked = [];
+const _openDownloadTarget = async (name, size, opts, swSize, flags) => {
+  live += 1; peak = Math.max(peak, live);
+  asked.push(flags && flags.batched);
+  await new Promise(r => setTimeout(r, 20));
+  live -= 1;
+  if (name === 'boom') throw new Error('refused');
+  return { name };
+};
+let _targetQueue = Promise.resolve();
+let _targetsInFlight = 0;
+""" + fn + """
+const results = await Promise.allSettled(
+  ['a', 'boom', 'c', 'd'].map(n => _openTargetInTurn(n)));
+out.push(peak);
+out.push(results.map(r => r.status).join(','));
+out.push(asked);
+console.log(JSON.stringify(out));
+""")
+    proc = subprocess.run(["node", str(script)], capture_output=True, text=True)
+    assert proc.returncode == 0, proc.stderr
+    peak, statuses, batched = json.loads(proc.stdout)
+    assert peak == 1, f"{peak} targets were being opened at once"
+    assert batched == [False, True, True, True], (
+        "only the first of a batch holds the user's gesture; the rest must be "
+        "opened without asking")
+    # And one refusal must not stop the rest: a chain that breaks on a rejection
+    # leaves every later download unable to open anything at all.
+    assert statuses == "fulfilled,rejected,fulfilled,fulfilled"
diff --git a/packages/meshbay-hub/tests/test_memory_ceiling.py b/packages/meshbay-hub/tests/test_memory_ceiling.py
index 8430627..d46cae3 100644
--- a/packages/meshbay-hub/tests/test_memory_ceiling.py
+++ b/packages/meshbay-hub/tests/test_memory_ceiling.py
@@ -66,12 +66,16 @@ def target_fn():
 
 
 def _run(target_fn, tmp_path, *, size, native=False, granted=False,
-         streamed=False, picker=False, mode="auto"):
+         streamed=False, picker=False, mode="auto", batched=False):
     """Drive the real function against one browser shape."""
     script = tmp_path / "case.mjs"
     script.write_text(f"""
 // Stubs for everything the lifted function reaches. `formatSize` and `t` only
 // build the message; the assertions are about which branch was taken.
+//
+// stdout carries the outcome and nothing else, so the function's own logging
+// goes to stderr -- where it is still shown when a case fails.
+console.info = (...a) => console.error(...a);
 const formatSize = (n) => `${{n}} B`;
 const t = (key, vars) => key + ' ' + JSON.stringify(vars);
 const platform = {{
@@ -107,7 +111,8 @@ if ({json.dumps(picker)}) {{
 
 let outcome;
 try {{
-  const r = await _openDownloadTarget('film.mkv', {size});
+  const r = await _openDownloadTarget('film.mkv', {size}, {{}}, {size},
+                                     {{ batched: {json.dumps(batched)} }});
   outcome = r === null ? {{ kind: 'memory' }}
     : r === false ? {{ kind: 'cancelled' }}
     : {{ kind: 'stream', name: r.name }};
@@ -180,6 +185,50 @@ def test_a_browser_with_a_picker_is_offered_one_instead_of_being_refused(
     assert out == {"kind": "stream", "name": "p"}
 
 
+# ── One dialog per gesture, not one per file ────────────────────────────────
+
+def test_the_first_of_a_batch_still_asks_where_to_save(target_fn, tmp_path):
+    """The preference is not being taken away. Someone who asked to choose the
+    folder chooses it, for the download they actually clicked."""
+    out = _run(target_fn, tmp_path, size=20 * GB, mode="ask", picker=True,
+               streamed=True)
+    assert out == {"kind": "stream", "name": "p"}
+
+
+def test_the_rest_of_a_batch_stream_instead_of_asking(target_fn, tmp_path):
+    """A browser grants one picker per user gesture and selecting four files is
+    one gesture. Chrome showed the dialog for the second file anyway and then
+    waited for a human, so the third and fourth sat behind it until they timed
+    out — reported as three downloads frozen.
+
+    There is no gesture left to spend, so nothing is lost by streaming: the file
+    still lands on disk, in the browser's own download folder. Only the choice
+    of folder goes, and it was not on offer.
+    """
+    out = _run(target_fn, tmp_path, size=20 * GB, mode="ask", picker=True,
+               streamed=True, batched=True)
+    assert out == {"kind": "stream", "name": "s"}
+
+
+def test_a_batched_download_falls_back_to_the_dialog_rather_than_failing(
+        target_fn, tmp_path):
+    """When the worker does not answer, asking is better than refusing: a
+    dialog that has to be answered is still a download, and the alternative
+    here is losing the file. A preference must not cost a capability, and
+    neither must the fix for one."""
+    out = _run(target_fn, tmp_path, size=20 * GB, mode="ask", picker=True,
+               streamed=False, batched=True)
+    assert out == {"kind": "stream", "name": "p"}
+
+
+def test_batching_never_pushes_a_large_file_into_memory(target_fn, tmp_path):
+    """Firefox shape — no picker at all. Nothing about the batch flag may reach
+    the memory floor above the ceiling."""
+    out = _run(target_fn, tmp_path, size=20 * GB, mode="ask", picker=False,
+               streamed=False, batched=True)
+    assert out["kind"] == "refused", out
+
+
 # ── The one that outlives today's branches ──────────────────────────────────
 
 def test_no_unguarded_memory_floor(target_fn):
diff --git a/packages/meshbay-hub/tests/test_transfers.py b/packages/meshbay-hub/tests/test_transfers.py
index 7e21409..c48e38c 100644
--- a/packages/meshbay-hub/tests/test_transfers.py
+++ b/packages/meshbay-hub/tests/test_transfers.py
@@ -432,7 +432,9 @@ def test_the_slot_is_asked_for_after_there_is_somewhere_to_write():
     src = (STATIC / "file-utils.js").read_text()
     fn = src[src.index("async function downloadEntry"):]
     fn = fn[:fn.index("\n}\n")]
-    assert fn.index("_openDownloadTarget") < fn.index("openTransfer"), (
+    # `_openTargetInTurn` since target openings were serialised — same call,
+    # queued. What is pinned is that it comes before the slot is asked for.
+    assert fn.index("_openTargetInTurn") < fn.index("openTransfer"), (
         "downloadEntry asks for a transfer slot before it has anywhere to "
         "write — the grant expires before the download can use it")
 
diff --git a/packages/meshbay-hub/tests/test_zip_size_limit.py b/packages/meshbay-hub/tests/test_zip_size_limit.py
index 28e3a0c..9471b8a 100644
--- a/packages/meshbay-hub/tests/test_zip_size_limit.py
+++ b/packages/meshbay-hub/tests/test_zip_size_limit.py
@@ -60,6 +60,10 @@ globalThis.localStorage = {{
 // Node 22 defines `navigator` itself, so it is left alone; `window` is what
 // platform.js reaches for to decide it is not running in the desktop app.
 globalThis.window = globalThis;
+// stdout carries the outcome and nothing else, so file-utils' own logging goes
+// to stderr -- where it is still shown when a case fails. It logs before every
+// save dialog, which is exactly what this harness provokes.
+console.info = (...a) => console.error(...a);
 const out = {{ errors: [], started: 0, asked: 0, dropped: 0 }};
 // Reached only once the size check has passed: with no File System Access API
 // under Node, downloadDirectory falls through to its build-in-memory path and
-- 
cgit v1.2.3


From 29e93e5e553c94818cd2b4e587b0e54cfe7d8424 Mon Sep 17 00:00:00 2001
From: Christophe Besson <cbesson@gmail.com>
Date: Wed, 9 Sep 2026 10:48:49 +0200
Subject: feat(spa): pause and resume a download, in session
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Stage 7a of ~/next/improve-downloads.md: pausing within a session, on the
targets that can actually do it. Resuming across a reload is 7b.

A paused transfer holds **nothing**. Its slot goes back to the node the moment
it stops and resuming rejoins the queue at the tail, because anything else lets
one member close a node by pausing four downloads and going to lunch. So the
lease is taken inside the run loop rather than before it, and pause is refused
outright for a transfer that could not ask for another one.

Resuming is exact rather than approximate: the pipeline stops between two
chunks and never inside one, so what is on disk is always a whole number of
chunks and `fromChunk` is a verified position. The failure mode being avoided
is a file that looks complete and is quietly corrupt.

The target has to survive it, so a pause no longer reaches the `abort()` that a
failure does -- that would delete Electron's `.part` or the file just created in
the granted folder, leaving nothing to continue. And the in-memory fallback
keeps its accumulated chunks rather than starting a second array.

The button is drawn only where the target says it can. A service-worker stream
says no, in its own code and for its own reasons: the browser is already writing
an HTTP response into its own download folder, not feeding it stalls that
download where we cannot see or resume it, and an idle worker is terminated
within seconds. Firefox and Safari therefore keep cancel and get no pause, which
is the decision recorded in §6.5.

Cancelling a paused transfer ends it. A paused run is parked on a promise;
without waking it the row said "cancelled" over work that had not stopped and a
target that was still open.

Six cases, each checked against the unfixed source. Hub suite 842 passed.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HCGdheDLxGReuKHga3BtST
---
 packages/meshbay-hub/src/meshbay_hub/static/app.js |  32 ++++-
 .../src/meshbay_hub/static/downloads.js            |  11 ++
 .../src/meshbay_hub/static/file-utils.js           |  57 ++++++--
 .../src/meshbay_hub/static/locales/de.js           |   5 +
 .../src/meshbay_hub/static/locales/en.js           |   5 +
 .../src/meshbay_hub/static/locales/es.js           |   5 +
 .../src/meshbay_hub/static/locales/fr.js           |   5 +
 .../src/meshbay_hub/static/locales/it.js           |   5 +
 .../src/meshbay_hub/static/locales/ja.js           |   5 +
 .../src/meshbay_hub/static/locales/nl.js           |   5 +
 .../src/meshbay_hub/static/locales/pl.js           |   5 +
 .../src/meshbay_hub/static/locales/pt-BR.js        |   5 +
 .../src/meshbay_hub/static/locales/zh-CN.js        |   5 +
 .../meshbay-hub/src/meshbay_hub/static/style.css   |  14 ++
 .../src/meshbay_hub/static/transfers.js            | 118 +++++++++++++--
 packages/meshbay-hub/tests/test_downloads.py       |  68 +++++++++
 packages/meshbay-hub/tests/test_transfers.py       | 160 +++++++++++++++++++++
 17 files changed, 484 insertions(+), 26 deletions(-)

(limited to 'packages/meshbay-hub/tests/test_transfers.py')

diff --git a/packages/meshbay-hub/src/meshbay_hub/static/app.js b/packages/meshbay-hub/src/meshbay_hub/static/app.js
index 6f4bb92..0394af6 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/app.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/app.js
@@ -242,8 +242,24 @@ function TransferRow({ it }) {
           ? html`<a class="transfer-name" href="#" title=${it.name}
               onClick=${(e) => { e.preventDefault(); transfers.open(it.id); }}>${it.name}</a>`
           : html`<span class="transfer-name" title=${it.name}>${it.name}</span>`}
+        ${it.pausable && (it.status === 'running' || it.status === 'paused')
+          && html`
+          ${/* Offered only where the target can actually do it: a
+                service-worker stream is a download the browser already owns,
+                and a pause there would restart from zero. */''}
+          <button class="transfer-pause"
+            aria-label=${t(it.status === 'paused'
+                           ? 'transfers.resume_one' : 'transfers.pause_one',
+                           { name: it.name })}
+            title=${t(it.status === 'paused'
+                      ? 'transfers.resume' : 'transfers.pause')}
+            onClick=${() => (it.status === 'paused'
+                             ? transfers.resume(it.id) : transfers.pause(it.id))}>
+            <${Icon} name=${it.status === 'paused' ? 'play' : 'pause'} />
+          </button>
+        `}
         ${(it.status === 'running' || it.status === 'queued'
-           || it.status === 'preparing') && html`
+           || it.status === 'preparing' || it.status === 'paused') && html`
           <button class="transfer-cancel"
             aria-label=${t('transfers.cancel_one', { name: it.name })}
             title=${t('transfers.cancel')}
@@ -274,6 +290,20 @@ function TransferRow({ it }) {
             <span>${formatSize(it.total)}</span>
           </div>
         `
+        : it.status === 'paused'
+        ? html`
+          ${/* The bar keeps its fill: what has been written is still there,
+                and resuming continues from it rather than starting again. */''}
+          <div class="dl-progress" role="progressbar"
+            aria-valuenow=${it.percent} aria-valuemin="0" aria-valuemax="100">
+            <div class="dl-fill dl-paused" style="width:${it.percent}%"></div>
+          </div>
+          <div class="transfer-meta">
+            <span>${t('transfers.paused')}</span>
+            <span>${formatSize(it.done)}${it.total
+              ? ' / ' + formatSize(it.total) : ''}</span>
+          </div>
+        `
         : it.status === 'running'
         ? html`
           <div class="dl-progress" role="progressbar"
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/downloads.js b/packages/meshbay-hub/src/meshbay_hub/static/downloads.js
index 87d18b7..6ee7cf0 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/downloads.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/downloads.js
@@ -178,6 +178,9 @@ export async function openTarget(filename) {
       },
     },
     name,
+    // A held-open `FileSystemWritableFileStream`: pausing is simply not
+    // writing to it, and nothing is lost while nothing is written.
+    pausable: true,
     // Reading it back is the only way a page can "open" a file it wrote: hand
     // the bytes to a tab and let the browser decide what to do with them. No
     // web page can start a desktop application, or show a file manager.
@@ -612,6 +615,14 @@ async function _attemptStreamedDownload(filename, size, attempt,
   const writer = writable.getWriter();
   return {
     name: filename,
+    // **Not pausable, and this is not a limitation of our code.** The browser
+    // is already writing an HTTP response into its own download folder: not
+    // writing to the stream stalls that download where we cannot see it or
+    // resume it, and an idle worker is terminated within seconds, taking the
+    // stream with it. A pause button here would restart from zero, which is
+    // worse than not offering one. §6.5 of ~/next/improve-downloads.md records
+    // what giving Firefox and Safari a resumable target would cost.
+    pausable: false,
     writable: {
       write: (bytes) => { lastWrite = Date.now(); return writer.write(bytes); },
       close: async () => {
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/file-utils.js b/packages/meshbay-hub/src/meshbay_hub/static/file-utils.js
index ef074dd..99d9f9a 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/file-utils.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/file-utils.js
@@ -118,7 +118,10 @@ async function _openDownloadTarget(filename, size = 0, pickerOpts = {},
         filename, { auto: downloads.getMode() === 'auto' });
       // Null means the person dismissed the dialog, which is not an error and
       // must not start a transfer.
-      return native || false;
+      //
+      // The desktop sink is an open file stream in the main process: not
+      // writing to it for a while costs nothing and loses nothing.
+      return native ? { ...native, pausable: true } : false;
     } catch (err) {
       console.warn('[MeshBay] native save failed:', platform.bridgeMessage(err));
       return false;
@@ -179,7 +182,8 @@ async function _openDownloadTarget(filename, size = 0, pickerOpts = {},
     const handle = await window.showSaveFilePicker({
       suggestedName: filename, ...pickerOpts,
     });
-    return { writable: await handle.createWritable(), name: handle.name || filename };
+    return { writable: await handle.createWritable(),
+             name: handle.name || filename, pausable: true };
   } catch (err) {
     if (err.name === 'AbortError') return false;
     // "Must be handling a user gesture to show a file picker."
@@ -350,9 +354,10 @@ async function _fetchChunkResilient(transport, fileId, index, tr = '') {
 }
 
 async function pipelinedDownload(transport, gekKey, fileId, totalChunks, onChunk,
-                                 writable, signal, tr = '') {
-  const results = writable ? null : new Array(totalChunks);
-  let nextSend = 0, nextRecv = 0;
+                                 writable, signal, tr = '', fromChunk = 0,
+                                 results = null) {
+  if (!writable && !results) results = new Array(totalChunks);
+  let nextSend = fromChunk, nextRecv = fromChunk;
   const inflight = new Array(totalChunks);
 
   const fire = () => {
@@ -369,6 +374,21 @@ async function pipelinedDownload(transport, gekKey, fileId, totalChunks, onChunk
       err.name = 'AbortError';
       throw err;
     }
+    // Between two chunks, never inside one. Everything written so far is a
+    // whole number of chunks, which is what makes resuming exact rather than
+    // approximate — `fromChunk` is a position, not an estimate, and a resumed
+    // file is never appended to at an offset nobody checked.
+    //
+    // The chunks already in flight past this point are abandoned and asked for
+    // again on resume: at most one pipeline window of duplicated traffic, in
+    // exchange for not having to hold a half-received window across a pause of
+    // unknown length.
+    if (signal && signal.paused) {
+      signal.resumeFrom = nextRecv;
+      const err = new Error('Paused');
+      err.name = 'PausedError';
+      throw err;
+    }
     const chunkMsg = await inflight[nextRecv];
     // One shape, and a refusal for anything else. There used to be two fallbacks
     // below this: a base64 `ct_b64` chunk, which was the real wire format until
@@ -409,6 +429,9 @@ async function downloadEntry(transfers, transport, gek, entry) {
   const totalChunks = Math.ceil(entry.size / CHUNK_SIZE);
   const openRef = { url: null };
   let target = null;
+  // The in-memory fallback's accumulator, held out here so a pause does not
+  // discard what has already been decrypted.
+  const memoryChunks = new Array(totalChunks);
 
   transfers.start({
     kind: 'download', name: entry.name, total: entry.size, transport,
@@ -421,7 +444,10 @@ async function downloadEntry(transfers, transport, gek, entry) {
       target = await _openTargetInTurn(entry.name, entry.size);
       // Dismissed: nothing was started, so nothing is left on screen.
       if (target === false) return false;
-      return target ? { name: target.name } : true;
+      // `pausable` travels with the target, because only the target knows. The
+      // in-memory fallback (a null target) is just an array and pauses fine.
+      return target ? { name: target.name, pausable: !!target.pausable }
+                    : { pausable: true };
     },
 
     // After the target, never before: a granted slot has to be taken up within
@@ -434,24 +460,33 @@ async function downloadEntry(transfers, transport, gek, entry) {
     open: () => (target && target.open) ? target.open()
       : (openRef.url ? window.open(openRef.url, '_blank') : undefined),
 
-    run: async ({ signal, onProgress, lease }) => {
-      let done = 0;
+    // Kept across a pause: the chunks collected so far on the in-memory path.
+    // A resumed run fills in from where it stopped rather than starting a
+    // second array and throwing the first away.
+    run: async ({ signal, onProgress, lease, from = 0 }) => {
+      let done = from * CHUNK_SIZE;
       const onChunk = (bytes) => { done += bytes; onProgress(done, entry.size); };
 
       if (target) {
         try {
           await pipelinedDownload(transport, gek, entry.id, totalChunks,
                                   onChunk, target.writable, signal,
-                                  lease && lease.tr);
+                                  lease && lease.tr, from);
           await target.writable.close();
         } catch (err) {
-          await target.writable.abort().catch(() => {});
+          // A pause is not a failure, and the target must survive it: aborting
+          // here would delete the `.part` (Electron) or the file just created
+          // in the granted folder, and resuming would then have nothing to
+          // continue. Only a real end tears the target down.
+          if (err.name !== 'PausedError') {
+            await target.writable.abort().catch(() => {});
+          }
           throw err;
         }
       } else {
         const chunks = await pipelinedDownload(
           transport, gek, entry.id, totalChunks, onChunk, null, signal,
-          lease && lease.tr);
+          lease && lease.tr, from, memoryChunks);
         const blob = new Blob(chunks);
         _saveBlob(blob, entry.name);
         openRef.url = URL.createObjectURL(blob);
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/locales/de.js b/packages/meshbay-hub/src/meshbay_hub/static/locales/de.js
index f0ec776..ae20687 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/locales/de.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/locales/de.js
@@ -586,6 +586,11 @@ export default {
   'transfers.group_waiting': 'Wartend',
   'transfers.group_finished': 'Abgeschlossen',
   'transfers.cancel_one': '{name} abbrechen',
+  'transfers.pause': 'Anhalten',
+  'transfers.resume': 'Fortsetzen',
+  'transfers.paused': 'Angehalten',
+  'transfers.pause_one': '{name} anhalten',
+  'transfers.resume_one': '{name} fortsetzen',
   'transfers.eta_seconds': 'noch {n} s',
   'transfers.eta_minutes': 'noch {n} Min.',
   'transfers.eta_hours': 'noch {n} Std.',
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/locales/en.js b/packages/meshbay-hub/src/meshbay_hub/static/locales/en.js
index c065b8a..7033778 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/locales/en.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/locales/en.js
@@ -702,6 +702,11 @@ export default {
   'transfers.group_waiting': 'Waiting',
   'transfers.group_finished': 'Finished',
   'transfers.cancel_one': 'Cancel {name}',
+  'transfers.pause': 'Pause',
+  'transfers.resume': 'Resume',
+  'transfers.paused': 'Paused',
+  'transfers.pause_one': 'Pause {name}',
+  'transfers.resume_one': 'Resume {name}',
   'transfers.eta_seconds': '{n}s left',
   'transfers.eta_minutes': '{n} min left',
   'transfers.eta_hours': '{n} h left',
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/locales/es.js b/packages/meshbay-hub/src/meshbay_hub/static/locales/es.js
index f655bc0..311ba1f 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/locales/es.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/locales/es.js
@@ -582,6 +582,11 @@ export default {
   'transfers.group_waiting': 'En espera',
   'transfers.group_finished': 'Finalizados',
   'transfers.cancel_one': 'Cancelar {name}',
+  'transfers.pause': 'Pausar',
+  'transfers.resume': 'Reanudar',
+  'transfers.paused': 'En pausa',
+  'transfers.pause_one': 'Pausar {name}',
+  'transfers.resume_one': 'Reanudar {name}',
   'transfers.eta_seconds': 'quedan {n} s',
   'transfers.eta_minutes': 'quedan {n} min',
   'transfers.eta_hours': 'quedan {n} h',
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/locales/fr.js b/packages/meshbay-hub/src/meshbay_hub/static/locales/fr.js
index e011873..106e3cd 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/locales/fr.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/locales/fr.js
@@ -585,6 +585,11 @@ export default {
   'transfers.group_waiting': 'En attente',
   'transfers.group_finished': 'Terminés',
   'transfers.cancel_one': 'Annuler {name}',
+  'transfers.pause': 'Suspendre',
+  'transfers.resume': 'Reprendre',
+  'transfers.paused': 'En pause',
+  'transfers.pause_one': 'Suspendre {name}',
+  'transfers.resume_one': 'Reprendre {name}',
   'transfers.eta_seconds': '{n} s restantes',
   'transfers.eta_minutes': '{n} min restantes',
   'transfers.eta_hours': '{n} h restantes',
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/locales/it.js b/packages/meshbay-hub/src/meshbay_hub/static/locales/it.js
index 80e3c17..a610683 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/locales/it.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/locales/it.js
@@ -585,6 +585,11 @@ export default {
   'transfers.group_waiting': 'In attesa',
   'transfers.group_finished': 'Completati',
   'transfers.cancel_one': 'Annulla {name}',
+  'transfers.pause': 'Sospendi',
+  'transfers.resume': 'Riprendi',
+  'transfers.paused': 'In pausa',
+  'transfers.pause_one': 'Sospendi {name}',
+  'transfers.resume_one': 'Riprendi {name}',
   'transfers.eta_seconds': '{n} s rimanenti',
   'transfers.eta_minutes': '{n} min rimanenti',
   'transfers.eta_hours': '{n} h rimanenti',
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/locales/ja.js b/packages/meshbay-hub/src/meshbay_hub/static/locales/ja.js
index 5dbb4fa..aed4ba0 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/locales/ja.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/locales/ja.js
@@ -577,6 +577,11 @@ export default {
   'transfers.group_waiting': '待機中',
   'transfers.group_finished': '完了',
   'transfers.cancel_one': '{name} をキャンセル',
+  'transfers.pause': '一時停止',
+  'transfers.resume': '再開',
+  'transfers.paused': '一時停止中',
+  'transfers.pause_one': '{name} を一時停止',
+  'transfers.resume_one': '{name} を再開',
   'transfers.eta_seconds': '残り {n} 秒',
   'transfers.eta_minutes': '残り {n} 分',
   'transfers.eta_hours': '残り {n} 時間',
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/locales/nl.js b/packages/meshbay-hub/src/meshbay_hub/static/locales/nl.js
index f9c7cf3..fe10e12 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/locales/nl.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/locales/nl.js
@@ -586,6 +586,11 @@ export default {
   'transfers.group_waiting': 'Wachtend',
   'transfers.group_finished': 'Voltooid',
   'transfers.cancel_one': '{name} annuleren',
+  'transfers.pause': 'Pauzeren',
+  'transfers.resume': 'Hervatten',
+  'transfers.paused': 'Gepauzeerd',
+  'transfers.pause_one': '{name} pauzeren',
+  'transfers.resume_one': '{name} hervatten',
   'transfers.eta_seconds': 'nog {n} s',
   'transfers.eta_minutes': 'nog {n} min',
   'transfers.eta_hours': 'nog {n} u',
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/locales/pl.js b/packages/meshbay-hub/src/meshbay_hub/static/locales/pl.js
index b26f3cb..c2ba35c 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/locales/pl.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/locales/pl.js
@@ -598,6 +598,11 @@ export default {
   'transfers.group_waiting': 'Oczekuje',
   'transfers.group_finished': 'Zakończone',
   'transfers.cancel_one': 'Anuluj {name}',
+  'transfers.pause': 'Wstrzymaj',
+  'transfers.resume': 'Wznów',
+  'transfers.paused': 'Wstrzymano',
+  'transfers.pause_one': 'Wstrzymaj {name}',
+  'transfers.resume_one': 'Wznów {name}',
   'transfers.eta_seconds': 'pozostało {n} s',
   'transfers.eta_minutes': 'pozostało {n} min',
   'transfers.eta_hours': 'pozostało {n} godz.',
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/locales/pt-BR.js b/packages/meshbay-hub/src/meshbay_hub/static/locales/pt-BR.js
index db5a408..83d179b 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/locales/pt-BR.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/locales/pt-BR.js
@@ -584,6 +584,11 @@ export default {
   'transfers.group_waiting': 'Aguardando',
   'transfers.group_finished': 'Concluídos',
   'transfers.cancel_one': 'Cancelar {name}',
+  'transfers.pause': 'Pausar',
+  'transfers.resume': 'Retomar',
+  'transfers.paused': 'Pausado',
+  'transfers.pause_one': 'Pausar {name}',
+  'transfers.resume_one': 'Retomar {name}',
   'transfers.eta_seconds': 'faltam {n} s',
   'transfers.eta_minutes': 'faltam {n} min',
   'transfers.eta_hours': 'faltam {n} h',
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/locales/zh-CN.js b/packages/meshbay-hub/src/meshbay_hub/static/locales/zh-CN.js
index ba88f4e..9acfb17 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/locales/zh-CN.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/locales/zh-CN.js
@@ -565,6 +565,11 @@ export default {
   'transfers.group_waiting': '等待中',
   'transfers.group_finished': '已完成',
   'transfers.cancel_one': '取消 {name}',
+  'transfers.pause': '暂停',
+  'transfers.resume': '继续',
+  'transfers.paused': '已暂停',
+  'transfers.pause_one': '暂停 {name}',
+  'transfers.resume_one': '继续 {name}',
   'transfers.eta_seconds': '剩余 {n} 秒',
   'transfers.eta_minutes': '剩余 {n} 分钟',
   'transfers.eta_hours': '剩余 {n} 小时',
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/style.css b/packages/meshbay-hub/src/meshbay_hub/static/style.css
index 22fcd3f..a37e541 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/style.css
+++ b/packages/meshbay-hub/src/meshbay_hub/static/style.css
@@ -1975,6 +1975,20 @@ a.transfer-name {
   display: flex;
 }
 .transfer-cancel:hover { color: var(--error); }
+/* Same shape as cancel, and beside it: pausing and cancelling are the two
+   things a person does to a transfer, and one of them is not destructive. */
+.transfer-pause {
+  background: none;
+  border: none;
+  color: var(--text-dim);
+  cursor: pointer;
+  padding: 0 2px;
+  display: flex;
+}
+.transfer-pause:hover { color: var(--accent); }
+/* A paused bar keeps its fill -- what was written is still on disk -- but stops
+   looking like something in progress. */
+.dl-fill.dl-paused { background: var(--text-dim); }
 .transfer-meta {
   display: flex;
   justify-content: space-between;
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/transfers.js b/packages/meshbay-hub/src/meshbay_hub/static/transfers.js
index d3b164d..797321c 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/transfers.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/transfers.js
@@ -25,7 +25,15 @@ const SPEED_WINDOW_MS = 5000;
 /** Not finished: still preparing, waiting for a slot, or transferring. One
  *  definition, because six places ask and they were drifting apart. */
 function _live(status) {
-  return status === 'preparing' || status === 'queued' || status === 'running';
+  return status === 'preparing' || status === 'queued' || status === 'running'
+    || status === 'paused';
+}
+
+/** Raised by `run` when it stopped because the transfer was paused. */
+function _pausedError() {
+  const err = new Error('Paused');
+  err.name = 'PausedError';
+  return err;
 }
 
 function _abortError() {
@@ -81,6 +89,9 @@ export class TransferStore {
       // Only for a file written into a folder the browser granted us: that is
       // the one case where the page can read its own download back.
       canOpen: it.status === 'done' && typeof it.open === 'function',
+      // Whether the target can be stopped and continued. False is the honest
+      // answer for a service-worker stream, and the button is not drawn.
+      pausable: Boolean(it.pausable),
     }));
   }
 
@@ -144,7 +155,18 @@ export class TransferStore {
       ahead: (lease && lease.ahead) || 0,
       error: '',
       samples: [{ t: this._now(), done: 0 }],
-      signal: { aborted: false },
+      signal: { aborted: false, paused: false },
+      // Set from `prepare`: whether this target can be stopped and continued.
+      pausable: false,
+      // Where a resumed run picks up, in chunks. Zero until something pauses.
+      resumeFrom: 0,
+      // Resolved by resume(); awaited by the run loop while paused.
+      resumed: null,
+      _wake: null,
+      // Pausing gives the slot back, so resuming has to be able to ask for
+      // another one. A transfer handed a lease directly cannot, and must not
+      // be offered a button that would drop its slot for good.
+      _canRelease: Boolean(makeLease),
     };
     this._items.push(item);
     this._emit();
@@ -195,25 +217,58 @@ export class TransferStore {
             return undefined;
           }
           if (ready && ready.name) item.name = ready.name;
+          // Only the target knows. A service-worker stream is already an HTTP
+          // response the browser is writing to its own download folder: not
+          // writing to it stalls that download outside our control, and an idle
+          // worker is terminated within seconds, taking the stream with it. So
+          // the button is offered where it works and nowhere else — a pause
+          // that silently restarts from zero is worse than no pause.
+          if (ready && ready.pausable) item.pausable = true;
           item.status = 'running';
           this._emit();
         }
-        if (makeLease && !item.lease) {
-          item.lease = makeLease();
-          this._watchLease(item);
-          if (item.lease.state !== 'granted') {
-            item.status = 'queued';
-            item.ahead = item.lease.ahead || 0;
+        // Run, and be prepared to be stopped and started again.
+        //
+        // A paused transfer holds **nothing**: its slot goes back to the node
+        // and resuming rejoins the queue at the tail. Anything else lets one
+        // member close a node by pausing four downloads and going to lunch.
+        // So the lease is taken inside this loop, not before it.
+        for (;;) {
+          if (makeLease && !item.lease) {
+            item.lease = makeLease();
+            this._watchLease(item);
+            if (item.lease.state !== 'granted') {
+              item.status = 'queued';
+              item.ahead = item.lease.ahead || 0;
+              this._emit();
+            }
+          }
+          if (item.lease) {
+            await item.lease.acquire();
+            if (item.signal.aborted) throw _abortError();
+            item.status = 'running';
             this._emit();
           }
-        }
-        if (item.lease) {
-          await item.lease.acquire();
-          if (item.signal.aborted) throw _abortError();
-          item.status = 'running';
+          try {
+            return await run({ signal: item.signal, onProgress,
+                               lease: item.lease, from: item.resumeFrom || 0 });
+          } catch (err) {
+            if (err.name !== 'PausedError') throw err;
+          }
+          // Where to pick up. `run` records it on the signal rather than
+          // returning it, because it has to survive being thrown past.
+          item.resumeFrom = item.signal.resumeFrom || 0;
+          if (item.lease) {
+            item.lease.release('paused');
+            item.lease = null;
+          }
+          item.status = 'paused';
+          item.ahead = 0;
           this._emit();
+          this._maybeRelease(item.transport);
+          await item.resumed;
+          if (item.signal.aborted) throw _abortError();
         }
-        return run({ signal: item.signal, onProgress, lease: item.lease });
       })
       .then(() => {
         if (item.signal.aborted) finish('cancelled');
@@ -260,6 +315,37 @@ export class TransferStore {
     if (item && typeof item.open === 'function') return item.open();
   }
 
+  /**
+   * Stop a running transfer, keeping what it has already written.
+   *
+   * Only while running: a queued transfer is already stopped and holds no slot,
+   * and pausing it would only cost it its place. Only where the target can do
+   * it — see the note in `start`.
+   *
+   * The slot goes back to the node at once (§6.2 of the plan): a paused
+   * transfer holds nothing, and resuming rejoins the queue at the tail.
+   */
+  pause(id) {
+    const item = this._items.find(it => it.id === id);
+    if (!item || !item.pausable || !item._canRelease
+        || item.status !== 'running') return;
+    item.signal.paused = true;
+    // Created here rather than in resume(): the run loop awaits it the moment
+    // `run` throws, which can be sooner than the next call into this store.
+    item.resumed = new Promise((resolve) => { item._wake = resolve; });
+    this._emit();
+  }
+
+  /** Start it again, from where it stopped, behind whatever is waiting now. */
+  resume(id) {
+    const item = this._items.find(it => it.id === id);
+    if (!item || item.status !== 'paused') return;
+    item.signal.paused = false;
+    item.status = 'queued';
+    this._emit();
+    if (item._wake) { item._wake(); item._wake = null; }
+  }
+
   cancel(id) {
     const item = this._items.find(it => it.id === id);
     // 'queued' too: a transfer waiting for a slot is exactly the one somebody
@@ -268,6 +354,10 @@ export class TransferStore {
     if (!item || !_live(item.status)) return;
     item.signal.aborted = true;
     if (item.lease) item.lease.release('cancelled');
+    // A paused run is parked on `item.resumed`. Without this it stays parked
+    // for the life of the page, holding its target open, and the row says
+    // "cancelled" over a download that never stopped.
+    if (item._wake) { item._wake(); item._wake = null; }
     // Marked at once. The work stops when it next looks, but a cancelled
     // transfer should not keep reporting progress in the meantime.
     item.status = 'cancelled';
diff --git a/packages/meshbay-hub/tests/test_downloads.py b/packages/meshbay-hub/tests/test_downloads.py
index dfb1433..41ae5d3 100644
--- a/packages/meshbay-hub/tests/test_downloads.py
+++ b/packages/meshbay-hub/tests/test_downloads.py
@@ -489,3 +489,71 @@ out.push(asked);
     assert batched == [False, True, True], (
         "the stuck one is still the only holder of the gesture, so the released "
         "openings must not try for a dialog of their own")
+
+
+def test_a_pause_falls_between_chunks_and_resumes_at_one(tmp_path):
+    """What makes resuming exact rather than approximate.
+
+    Everything written is a whole number of chunks, because the loop checks for
+    a pause between two of them and never inside one. So `fromChunk` is a
+    position, not an estimate, and a resumed download is never appended to at an
+    offset nobody verified — the failure mode being avoided is a file that looks
+    complete and is quietly corrupt.
+
+    The real `pipelinedDownload` is lifted out and run against stubs, on the
+    rule this repo follows for the video player: model the environment, never
+    the code under test.
+    """
+    src = (STATIC / "file-utils.js").read_text()
+    fn = src[src.index("async function pipelinedDownload"):]
+    fn = fn[:fn.index("\n}\n") + 2]
+
+    script = tmp_path / "pipeline.mjs"
+    script.write_text("""
+const CHUNK_SIZE = 8;
+const PIPELINE_WINDOW = 4;
+const written = [];
+// `ct` has to be truthy: chunk 0 with a falsy body is refused as undecryptable,
+// which is the guard working, not the harness.
+const _fetchChunkResilient = async (transport, fileId, i) =>
+  ({ ct: new Uint8Array([i & 0xff]), nonce: new Uint8Array(12) });
+const _writeOrStall = async (w, bytes, index) => { written.push(index); };
+globalThis.window = { MeshBayCrypto: {
+  // The plaintext carries its own index, so what lands where can be checked.
+  decryptChunkBin: async (k, id, index) => ({ byteLength: CHUNK_SIZE, index }),
+} };
+""" + fn + """
+const out = {};
+const signal = { aborted: false, paused: false };
+// Stop it part way, the way the store does.
+let seen = 0;
+const onChunk = () => { if (++seen === 3) signal.paused = true; };
+try {
+  await pipelinedDownload({}, 'k', 'file', 10, onChunk, {}, signal, '', 0);
+  out.threw = 'no';
+} catch (err) {
+  out.threw = err.name;
+}
+out.resumeFrom = signal.resumeFrom;
+out.writtenBeforePause = written.slice();
+
+// And again, from where it said.
+signal.paused = false;
+written.length = 0;
+await pipelinedDownload({}, 'k', 'file', 10, () => {}, {}, signal, '',
+                        out.resumeFrom);
+out.writtenAfterResume = written.slice();
+console.log(JSON.stringify(out));
+""")
+    proc = subprocess.run(["node", str(script)], capture_output=True, text=True)
+    assert proc.returncode == 0, proc.stderr
+    out = json.loads(proc.stdout)
+
+    assert out["threw"] == "PausedError", out
+    # Whole chunks only, in order, with nothing skipped.
+    assert out["writtenBeforePause"] == list(range(len(out["writtenBeforePause"])))
+    assert out["resumeFrom"] == len(out["writtenBeforePause"]), (
+        f"stopped after {len(out['writtenBeforePause'])} chunks but asked to "
+        f"resume at {out['resumeFrom']} — that gap is a hole in the file")
+    # The resumed run covers exactly the rest, and repeats nothing.
+    assert out["writtenAfterResume"] == list(range(out["resumeFrom"], 10)), out
diff --git a/packages/meshbay-hub/tests/test_transfers.py b/packages/meshbay-hub/tests/test_transfers.py
index c48e38c..035f569 100644
--- a/packages/meshbay-hub/tests/test_transfers.py
+++ b/packages/meshbay-hub/tests/test_transfers.py
@@ -553,3 +553,163 @@ def test_a_transport_is_not_closed_under_a_preparing_transfer(tmp_path):
     """, tmp_path)
     assert out[1] is False
     assert out[3] is True
+
+
+# ── Pause and resume ────────────────────────────────────────────────────────
+#
+# The rule the whole design turns on: **a paused transfer holds nothing.** Its
+# slot goes back to the node the moment it stops, and resuming rejoins the queue
+# at the tail. Anything else lets one member close a node by pausing four
+# downloads and going to lunch (§6.2 of ~/next/improve-downloads.md).
+
+
+def _pausable_run():
+    """A `run` that stops where it is told and reports where it resumed."""
+    return """
+const mkStore = () => {
+  const t = new TransferStore();
+  const leases = [];
+  const state = { starts: [], paused: null, aborted: false };
+  t.start({
+    kind: 'download', name: 'f', total: 1000,
+    prepare: async () => ({ name: 'f', pausable: true }),
+    makeLease: () => { const l = new L(); leases.push(l); return l; },
+    run: async ({ signal, from }) => {
+      state.starts.push(from);
+      state.running = true;
+      try {
+      // Runs until told to stop, one "chunk" at a time.
+      for (let i = from; i < 10; i++) {
+        await new Promise(r => setTimeout(r, 5));
+        if (signal.aborted) { const e = new Error('c'); e.name = 'AbortError'; throw e; }
+        if (signal.paused) {
+          signal.resumeFrom = i;
+          const e = new Error('p'); e.name = 'PausedError'; throw e;
+        }
+      }
+      } finally { state.running = false; }
+    },
+  });
+  return { t, leases, state };
+};
+"""
+
+
+def test_pausing_gives_the_slot_back(tmp_path):
+    """The node has to get it back at once, not when the person resumes: the
+    whole point of a queue is that a slot nobody is using is a slot somebody
+    else can have."""
+    out = _run(_lease_stub() + _pausable_run() + """
+      const { t, leases } = mkStore();
+      await new Promise(r => setTimeout(r, 5));
+      leases[0].grant();
+      await new Promise(r => setTimeout(r, 20));
+      say('before:' + t.list()[0].status);
+      t.pause(t.list()[0].id);
+      await new Promise(r => setTimeout(r, 30));
+      say('after:' + t.list()[0].status);
+      say('released:' + leases[0].released.join(','));
+      say('leases:' + leases.length);
+    """, tmp_path)
+    assert out[0] == "before:running"
+    assert out[1] == "after:paused"
+    assert out[2] == "released:paused", "a paused transfer kept its slot"
+    assert out[3] == "leases:1"
+
+
+def test_resuming_asks_for_a_new_slot_and_continues_where_it_stopped(tmp_path):
+    """Rejoining at the tail is the design, not an accident: a paused transfer
+    that could reclaim its old place would be a way to hold one."""
+    out = _run(_lease_stub() + _pausable_run() + """
+      const { t, leases, state } = mkStore();
+      await new Promise(r => setTimeout(r, 5));
+      leases[0].grant();
+      await new Promise(r => setTimeout(r, 20));
+      const id = t.list()[0].id;
+      t.pause(id);
+      await new Promise(r => setTimeout(r, 30));
+      t.resume(id);
+      await new Promise(r => setTimeout(r, 10));
+      say('queued:' + t.list()[0].status, 'leases:' + leases.length);
+      leases[1].grant();
+      await new Promise(r => setTimeout(r, 120));
+      say('end:' + t.list()[0].status);
+      say('starts:' + state.starts.join(','));
+    """, tmp_path)
+    assert out[0] == "queued:queued", "a resumed transfer skipped the queue"
+    assert out[1] == "leases:2", "resuming did not ask for a slot again"
+    assert out[2] == "end:done"
+    starts = out[3].split(":")[1].split(",")
+    assert starts[0] == "0" and int(starts[1]) > 0, (
+        f"resumed from {starts} — it started again from the beginning")
+
+
+def test_a_transfer_whose_target_cannot_pause_is_not_paused(tmp_path):
+    """A service-worker stream is a download the browser already owns: not
+    writing to it stalls it outside our control and an idle worker is killed
+    within seconds. A button that silently restarts from zero is worse than no
+    button, so `pause` refuses rather than pretending."""
+    out = _run(_lease_stub() + """
+      const t = new TransferStore();
+      const lease = new L();
+      t.start({ kind: 'download', name: 'f', total: 10, lease,
+                prepare: async () => ({ name: 'f' }),
+                run: async ({ signal }) => {
+                  while (!signal.aborted) await new Promise(r => setTimeout(r, 5));
+                } });
+      lease.grant();
+      await new Promise(r => setTimeout(r, 20));
+      const id = t.list()[0].id;
+      say('pausable:' + t.list()[0].pausable);
+      t.pause(id);
+      await new Promise(r => setTimeout(r, 20));
+      say('status:' + t.list()[0].status);
+      t.cancel(id);
+    """, tmp_path)
+    assert out == ["pausable:false", "status:running"]
+
+
+def test_cancelling_a_paused_transfer_actually_ends_it(tmp_path):
+    """A paused run is parked on a promise. Without waking it, cancel marks the
+    row and leaves the work parked for the life of the page, holding its target
+    open — a button that lies, in the same way the first test in this file
+    describes."""
+    out = _run(_lease_stub() + _pausable_run() + """
+      const { t, leases, state } = mkStore();
+      await new Promise(r => setTimeout(r, 5));
+      leases[0].grant();
+      await new Promise(r => setTimeout(r, 20));
+      const id = t.list()[0].id;
+      t.pause(id);
+      await new Promise(r => setTimeout(r, 30));
+      t.cancel(id);
+      // What matters is whether the store's own loop ends, not whether the row
+      // says so: the row is marked at once either way.
+      const settled = await Promise.race([
+        t._items[0].promise.then(() => 'settled', () => 'settled'),
+        new Promise(r => setTimeout(() => r('parked'), 60)),
+      ]);
+      say('status:' + t.list()[0].status);
+      say('loop:' + settled);
+      say('resumed:' + state.starts.length);
+    """, tmp_path)
+    assert out[0] == "status:cancelled"
+    assert out[1] == "loop:settled", (
+        "the run was still parked on the resume promise after a cancel — the "
+        "row said cancelled over work that had not stopped")
+    assert out[2] == "resumed:1", "cancelling started the work again"
+
+
+def test_a_paused_transfer_still_counts_as_live(tmp_path):
+    """It is not finished, and its transport must not be closed under it — the
+    person is coming back to it."""
+    out = _run(_lease_stub() + _pausable_run() + """
+      const { t, leases } = mkStore();
+      await new Promise(r => setTimeout(r, 5));
+      leases[0].grant();
+      await new Promise(r => setTimeout(r, 20));
+      t.pause(t.list()[0].id);
+      await new Promise(r => setTimeout(r, 30));
+      say('pending:' + t.pending);
+    """, tmp_path)
+    assert out == ["pending:1"]
-- 
cgit v1.2.3


From 4f5d3d4ac151874f03c6fcc451d6b1d5bb1efb78 Mon Sep 17 00:00:00 2001
From: Christophe Besson <cbesson@gmail.com>
Date: Wed, 9 Sep 2026 12:01:06 +0200
Subject: feat: resume an interrupted upload, and pause one
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Stage 8 of ~/next/improve-downloads.md, second half, plus the gap it exposed in
stage 7.

**Asking where to resume.** The node identifies an upload by (member,
directory, filename), so a client resuming one has to name the file — and
`transfer_open`, the obvious place to ask, travels in clear. Naming it there
would undo exactly what sealing this path bought in MNP 2.0: before it, the same
file was ciphertext leaving a node and plaintext arriving at one. So the
question is asked inside the seal that already exists, as an ordinary
`file_upload` with no bytes and `chunk_index: -1`. The node writes nothing,
creates no state, reserves no name, and answers with `resume_from` in the sealed
ack. A node that predates it refuses the index, which the client reads as "start
from the beginning" — the behaviour it had anyway — and the wait is bounded so
one that answers neither does not strand an upload.

The probe is answered after every check the write path makes, so it cannot ask
questions about a directory the caller may not write to, and it answers only
about the member who asks: otherwise one member could measure another's
progress on a file they never sent, and worse, resume it.

**Pausing an upload.** Reported: no pause button on an upload, even in the
desktop app. Stage 7 built pause around the download path — a target declares
whether it can be stopped — and an upload has no local target to ask. It was
also refused by design, since a transfer handed a lease it cannot re-create must
not be offered a button that would drop its slot for good. Uploads now ask for
their slot rather than being handed one, and say they are pausable outright: a
File is seekable and the node keeps the position. Resuming re-probes rather than
trusting the client's own memory, so it works across a reconnect too.

**And the slot they hold.** `_do_file_upload` never called `slots.touch(tr)`.
Chunks are not gated by the lease, so the file arrived — but the node reclaimed
a grant nobody appeared to be using after thirty seconds, twice, then abandoned
it, and the widget follows the lease. Measured from the journal: a 3.5 GB upload
read "waiting, 0 ahead" for a minute and a half while it was transferring. The
download twin of this was fixed on 2026-09-08; the same omission was still here,
invisible until uploads took a real lease.

`test_the_upload_itself_is_sealed` now checks every message `uploadFile` sends
rather than the first. Adding the probe put a second one in front of the one it
was written for, and it would have kept passing while guarding nothing.

Node suite 1202 passed, hub suite 850 passed.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HCGdheDLxGReuKHga3BtST
---
 .../meshbay-common/src/meshbay_common/protocol.py  |  24 ++++
 .../src/meshbay_hub/static/files-app.js            |  10 +-
 .../src/meshbay_hub/static/transfers.js            |   9 +-
 .../src/meshbay_hub/static/transport.js            |  85 +++++++++++++-
 .../tests/harness/upload_seal_probe.mjs            |  25 +++-
 packages/meshbay-hub/tests/test_transfers.py       |  57 +++++++++
 .../meshbay-hub/tests/test_transport_contracts.py  |  33 ++++--
 .../meshbay-hub/tests/test_upload_seal_client.py   |  38 ++++++
 .../src/meshbay_node/transport/webrtc_server.py    |  48 ++++++++
 .../meshbay-node/tests/test_partial_uploads.py     | 129 +++++++++++++++++++++
 10 files changed, 440 insertions(+), 18 deletions(-)

(limited to 'packages/meshbay-hub/tests/test_transfers.py')

diff --git a/packages/meshbay-common/src/meshbay_common/protocol.py b/packages/meshbay-common/src/meshbay_common/protocol.py
index 8a521bb..5bd2903 100644
--- a/packages/meshbay-common/src/meshbay_common/protocol.py
+++ b/packages/meshbay-common/src/meshbay_common/protocol.py
@@ -501,6 +501,22 @@ def file_upload_payload(gek: bytes, group_id: str, msg: dict) -> dict:
     return unseal(gek, PURPOSE_UPLOAD, MNP.FILE_UPLOAD, group_id, msg)
 
 
+# "Where am I?", asked as an ordinary sealed upload chunk rather than as a new
+# message.
+#
+# The node identifies an upload by (member, directory, filename), so a client
+# resuming one has to name the file — and `transfer_open`, the obvious place to
+# ask, travels in clear. Naming it there would undo exactly what sealing the
+# upload path bought: before MNP 2.0 the same file was ciphertext leaving a node
+# and plaintext arriving at one.
+#
+# So the question is asked inside the seal that already exists, as a chunk with
+# no bytes and this index. The node writes nothing, changes nothing, and answers
+# with `resume_from`. A node that predates this refuses the index, which the
+# client reads as "start from the beginning" — the behaviour it had anyway.
+UPLOAD_PROBE_INDEX = -1
+
+
 def file_upload_ack_wire(
     gek: bytes,
     group_id: str,
@@ -510,6 +526,7 @@ def file_upload_ack_wire(
     filename: str,
     stored_as: str,
     dir: str = "",
+    resume_from: int | None = None,
 ) -> dict:
     """
     The node's answer to one chunk, sealed the same way.
@@ -518,8 +535,15 @@ def file_upload_ack_wire(
     replacing anything — and `dir` is where it landed. Both name the operator's
     content, so both belong inside the seal; only `upload_id` and `chunk_index`
     stay out, because the client matches on them.
+
+    `resume_from` answers the probe chunk (`UPLOAD_PROBE_INDEX`): how many
+    chunks of this file the node already holds. Inside the seal like the rest —
+    it is a fact about the operator's disk — and absent from an ordinary ack, so
+    a client can tell the two apart without looking at `chunk_index`.
     """
     payload = {"filename": filename, "stored_as": stored_as, "dir": dir}
+    if resume_from is not None:
+        payload["resume_from"] = int(resume_from)
     return {
         "type": MNP.FILE_UPLOAD_ACK,
         "v": MNP_VERSION,
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/files-app.js b/packages/meshbay-hub/src/meshbay_hub/static/files-app.js
index fb9d801..65860ec 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/files-app.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/files-app.js
@@ -94,7 +94,15 @@ function FilesPanel({
     for (const file of files) {
       transfers.start({
         kind: 'upload', name: file.name, total: file.size, transport,
-        lease: transport.openTransfer({ kind: 'upload', bytes: file.size }),
+        // `makeLease`, not `lease`: pausing gives the slot back, so resuming
+        // has to be able to ask for another one, and a transfer handed a lease
+        // it cannot re-create is refused the button rather than offered one
+        // that would drop its slot for good.
+        makeLease: () => transport.openTransfer({ kind: 'upload',
+                                                  bytes: file.size }),
+        // A `File` is seekable and the node remembers how much it holds, so
+        // there is no target tier to consult here — unlike a download.
+        pausable: true,
         run: async ({ signal, onProgress, lease }) => {
           await transport.uploadFile(file, {
             // Bytes the node acknowledged, not bytes read locally.
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/transfers.js b/packages/meshbay-hub/src/meshbay_hub/static/transfers.js
index 797321c..524b7f3 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/transfers.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/transfers.js
@@ -141,7 +141,7 @@ export class TransferStore {
    * there is somewhere to write — see file-utils.js's downloadEntry.
    */
   start({ kind, name, total = 0, transport = null, run, open = null,
-          lease = null, prepare = null, makeLease = null }) {
+          lease = null, prepare = null, makeLease = null, pausable = false }) {
     const item = {
       id: _nextId++,
       kind, name, total, transport, open, lease,
@@ -156,8 +156,11 @@ export class TransferStore {
       error: '',
       samples: [{ t: this._now(), done: 0 }],
       signal: { aborted: false, paused: false },
-      // Set from `prepare`: whether this target can be stopped and continued.
-      pausable: false,
+      // Whether this transfer can be stopped and continued. A download learns
+      // it from `prepare`, because only its target knows; an upload says so
+      // outright, because a `File` is always seekable and the node keeps the
+      // position (see uploads.py).
+      pausable: Boolean(pausable),
       // Where a resumed run picks up, in chunks. Zero until something pauses.
       resumeFrom: 0,
       // Resolved by resume(); awaited by the run loop while paused.
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/transport.js b/packages/meshbay-hub/src/meshbay_hub/static/transport.js
index 54a1302..23823ac 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/transport.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/transport.js
@@ -40,6 +40,16 @@ async function _pkEdFromSk(skPkcs8B64) {
 // flight, which saturates any path up to roughly 100 Mb/s at 100 ms.
 const UPLOAD_CHUNK_SIZE = 48 * 1024;
 const UPLOAD_WINDOW = 32;
+// "Where am I?", asked as an ordinary sealed upload chunk with no bytes rather
+// than on a clear message. Mirrors UPLOAD_PROBE_INDEX in
+// meshbay_common/protocol.py; the node writes nothing and answers with
+// `resume_from`, and one that predates it refuses the index, which reads as
+// "start from the beginning".
+const UPLOAD_PROBE_INDEX = -1;
+// How long to wait for that answer before assuming there is none. A node that
+// answers neither the probe nor its refusal must not leave an upload waiting
+// for ever, and starting over is always safe.
+const UPLOAD_PROBE_TIMEOUT_MS = 5000;
 const UPLOAD_BUFFER_HIGH = 1024 * 1024;
 
 // Segments of 256 KB: 24 in flight is 6 MB, enough to keep playback fed over a
@@ -2409,8 +2419,23 @@ class MeshBayTransport {
       const waiter = acks.shift();
       if (waiter) waiter();
     };
+    // "Where am I?" — resolved by the node's answer to the probe chunk below,
+    // or by anything that says this node cannot answer it.
+    let settleProbe = null;
+    const probed = new Promise((r) => { settleProbe = r; });
+    const answerProbe = (from) => {
+      if (!settleProbe) return false;
+      const done = settleProbe;
+      settleProbe = null;
+      done(from);
+      return true;
+    };
     this._uploaders.set(uploadId, (msg) => {
       if (msg.type === 'error') {
+        // A node that predates the probe refuses its index. That is not a
+        // failure — it is the answer "start from the beginning", which is what
+        // this client did before there was anything to ask.
+        if (answerProbe(0)) return;
         failure = new Error(msg.detail || 'Upload refused');
         wake();
         return;
@@ -2423,19 +2448,75 @@ class MeshBayTransport {
         .then((plain) => {
           const payload = msgpack_decode(plain);
           if (payload.stored_as) stored = payload;
+          // Only the probe's answer carries this, so the two are told apart
+          // without trusting the index the node echoed back in clear.
+          if (typeof payload.resume_from === 'number') return answerProbe(payload.resume_from);
+          return false;
         })
         .catch((e) => {
           failure = new Error(
             `The node's upload reply did not open under the group key (${e.message})`);
+          return false;
         })
-        .finally(wake);
+        // A probe's answer is not a chunk: waking here would credit the
+        // progress bar with a chunk that was never sent.
+        .then((wasProbe) => { if (!wasProbe) wake(); });
     });
 
     const nextAck = () => new Promise(r => acks.push(r));
 
     try {
-      for (let i = 0; i < total; i++) {
+      // Ask before sending anything. An upload interrupted at 99% used to start
+      // again from zero, because the node kept its position on the connection
+      // that was lost — see `uploads.py`. The question goes inside the seal, as
+      // a chunk with no bytes, because naming the file on a clear message is
+      // exactly what sealing this path was for.
+      // Sealed first, spread second — the same shape as the chunk loop below,
+      // and not only for symmetry: `test_the_upload_itself_is_sealed` reads
+      // this call and fails if a filename appears in it, which is how it can
+      // tell a field outside the seal from one inside it.
+      const probeSealed = await C.sealGroup(
+        this._gekRaw, 'upload', 'file_upload', groupId,
+        msgpack_encode({ filename: file.name, data: new Uint8Array(0),
+                         dir: dir || '', root: root || '' }));
+      this._send({
+        type: 'file_upload',
+        v: '0.1',
+        upload_id: uploadId,
+        chunk_index: UPLOAD_PROBE_INDEX,
+        total_chunks: total,
+        ...(tr ? { tr } : {}),
+        ...probeSealed,
+      });
+      // Bounded: a node that answers neither the probe nor its refusal must not
+      // leave an upload waiting for ever. Starting over is always safe.
+      let from = await Promise.race([
+        probed,
+        new Promise((r) => setTimeout(() => { answerProbe(0); r(0); },
+                                      UPLOAD_PROBE_TIMEOUT_MS)),
+      ]);
+      // Defensive: a node reporting a position at or past the end would have
+      // renamed the file and dropped its state, so this cannot happen — and if
+      // it does, sending everything again is the answer that cannot corrupt.
+      if (!(from > 0) || from >= total) from = 0;
+      if (from > 0) {
+        acked = from;
+        if (onProgress) onProgress(Math.min(file.size, from * size), file.size);
+      }
+
+      for (let i = from; i < total; i++) {
         if (signal && signal.aborted) throw _aborted();
+        // Between two chunks, never inside one — the node refuses a chunk that
+        // is not the one it expects, so a position is the only thing worth
+        // remembering. Nothing is recorded here beyond that: the node holds the
+        // real position, and the probe above is what asks for it on the way
+        // back in, which makes resuming correct even across a reconnect.
+        if (signal && signal.paused) {
+          signal.resumeFrom = i;
+          const paused = new Error('Paused');
+          paused.name = 'PausedError';
+          throw paused;
+        }
         // Backpressure: without it the whole file lands in the browser's send
         // buffer in seconds and the progress bar becomes a work of fiction.
         while (this._channel && this._channel.bufferedAmount > UPLOAD_BUFFER_HIGH) {
diff --git a/packages/meshbay-hub/tests/harness/upload_seal_probe.mjs b/packages/meshbay-hub/tests/harness/upload_seal_probe.mjs
index 0b77e42..a6008c2 100644
--- a/packages/meshbay-hub/tests/harness/upload_seal_probe.mjs
+++ b/packages/meshbay-hub/tests/harness/upload_seal_probe.mjs
@@ -72,13 +72,34 @@ tp._nodeVersion = input.node_version;
 
 const frames = [];
 let uploadId = null;
+let answered = 0;
 tp._send = (msg) => {
   frames.push(toHex(msgpack_encode(msg)));
   if (msg.upload_id) uploadId = msg.upload_id;
-  if (input.mode !== 'receive') return;
+  if (input.mode !== 'receive') {
+    // Nothing answers in this mode -- except the probe, which the client waits
+    // five seconds for. A node that predates it refuses the index, and that
+    // refusal is a plain error rather than a sealed ack, so the harness can
+    // produce it honestly. It is also the degradation path worth exercising.
+    if (msg.chunk_index === -1) {
+      // With `probe_ack`, answer it the way a node holding part of this file
+      // does; without, the way one that predates the probe does.
+      const reply = input.probe_ack
+        ? Object.assign(msgpack_decode(hex(input.probe_ack)),
+                        { upload_id: uploadId })
+        : { type: 'error', upload_id: uploadId,
+            code: 'bad_chunk_index', detail: 'Unexpected chunk index' };
+      setImmediate(() => tp._dispatch(reply));
+    }
+    return;
+  }
   // Answer as the node did, on the next turn of the loop so the send path
   // finishes first — which is also how a real ack arrives.
-  const ack = msgpack_decode(hex(input.acks[msg.chunk_index]));
+  //
+  // By position, not by `chunk_index`: the node answers every frame including
+  // the probe, whose index is -1, and the two lists are built from the same
+  // sequence of frames.
+  const ack = msgpack_decode(hex(input.acks[answered++]));
   ack.upload_id = uploadId;
   // Through the real `_dispatch`, so the routing under test — matching an
   // ack to its uploader by `upload_id` — is the shipped one.
diff --git a/packages/meshbay-hub/tests/test_transfers.py b/packages/meshbay-hub/tests/test_transfers.py
index 035f569..f27d4fd 100644
--- a/packages/meshbay-hub/tests/test_transfers.py
+++ b/packages/meshbay-hub/tests/test_transfers.py
@@ -713,3 +713,60 @@ def test_a_paused_transfer_still_counts_as_live(tmp_path):
       say('pending:' + t.pending);
     """, tmp_path)
     assert out == ["pending:1"]
+
+
+def test_an_upload_can_be_paused_without_a_prepare_step(tmp_path):
+    """A download learns whether it can pause from its target, because only the
+    target knows. An upload has no target to ask: a `File` is seekable and the
+    node keeps the position, so it says so outright.
+
+    This was missed when pause shipped — the button appeared on downloads and
+    nowhere else, including in the desktop app where everything else works.
+    """
+    out = _run(_lease_stub() + """
+      const t = new TransferStore();
+      const leases = [];
+      t.start({
+        kind: 'upload', name: 'f', total: 100, pausable: true,
+        makeLease: () => { const l = new L(); leases.push(l); return l; },
+        run: async ({ signal, from }) => {
+          for (let i = from || 0; i < 10; i++) {
+            await new Promise(r => setTimeout(r, 5));
+            if (signal.paused) {
+              signal.resumeFrom = i;
+              const e = new Error('p'); e.name = 'PausedError'; throw e;
+            }
+          }
+        },
+      });
+      await new Promise(r => setTimeout(r, 5));
+      leases[0].grant();
+      await new Promise(r => setTimeout(r, 20));
+      say('pausable:' + t.list()[0].pausable);
+      t.pause(t.list()[0].id);
+      await new Promise(r => setTimeout(r, 30));
+      say('status:' + t.list()[0].status);
+      say('released:' + leases[0].released.join(','));
+    """, tmp_path)
+    assert out == ["pausable:true", "status:paused", "released:paused"]
+
+
+def test_an_upload_handed_a_lease_it_cannot_recreate_is_not_offered_pause(tmp_path):
+    """Pausing gives the slot back. A transfer that cannot ask for another one
+    would pause once and wait for ever, so the button is refused instead."""
+    out = _run(_lease_stub() + """
+      const t = new TransferStore();
+      const lease = new L();
+      t.start({ kind: 'upload', name: 'f', total: 100, pausable: true, lease,
+                run: async ({ signal }) => {
+                  while (!signal.aborted) await new Promise(r => setTimeout(r, 5));
+                } });
+      lease.grant();
+      await new Promise(r => setTimeout(r, 20));
+      const id = t.list()[0].id;
+      t.pause(id);
+      await new Promise(r => setTimeout(r, 20));
+      say('status:' + t.list()[0].status);
+      t.cancel(id);
+    """, tmp_path)
+    assert out == ["status:running"]
diff --git a/packages/meshbay-hub/tests/test_transport_contracts.py b/packages/meshbay-hub/tests/test_transport_contracts.py
index 879062b..fe550f9 100644
--- a/packages/meshbay-hub/tests/test_transport_contracts.py
+++ b/packages/meshbay-hub/tests/test_transport_contracts.py
@@ -349,16 +349,29 @@ def test_the_upload_itself_is_sealed(transport):
         "the upload must be sealed under the group key")
     assert "openGroup(" in body and "'file_upload_ack'" in body, (
         "the ack carries the stored name and must be opened, not read")
-    # The message the node actually receives: everything between `this._send({`
-    # and its close. Read on its own, because the same field names appear a few
-    # lines above inside `msgpack_encode({...})`, which is the sealed half.
-    sent = body[body.index("this._send({"):]
-    sent = sent[:sent.index("});")]
-    assert "filename" not in sent, "the filename is on the message in clear"
-    assert "data" not in sent, "the bytes are on the message in clear"
-    assert "dir" not in sent and "root" not in sent, (
-        "the destination is on the message in clear")
-    assert "...sealed," in sent, "the message must carry the sealed pair"
+    # The messages the node actually receives: everything between each
+    # `this._send({` and its close. Read on their own, because the same field
+    # names appear a few lines above inside `msgpack_encode({...})`, which is
+    # the sealed half.
+    #
+    # Every one of them, not the first: `uploadFile` sends a probe chunk before
+    # the file ("where am I?", UPLOAD_PROBE_INDEX) and it names the file too, so
+    # a check that stopped at the first message would have moved off the one it
+    # was written for the day the second appeared.
+    sends = []
+    rest = body
+    while "this._send({" in rest:
+        rest = rest[rest.index("this._send({"):]
+        sends.append(rest[:rest.index("});")])
+        rest = rest[len("this._send({"):]
+    assert len(sends) >= 2, "the probe and the chunks are both sent from here"
+    for sent in sends:
+        assert "filename" not in sent, "the filename is on the message in clear"
+        assert "data" not in sent, "the bytes are on the message in clear"
+        assert "dir" not in sent and "root" not in sent, (
+            "the destination is on the message in clear")
+        assert "...sealed," in sent or "...probeSealed," in sent, (
+            "the message must carry the sealed pair")
     assert "supportsSealedUpload" in body, (
         "an older node must be refused before a chunk is sent, not after")
 
diff --git a/packages/meshbay-hub/tests/test_upload_seal_client.py b/packages/meshbay-hub/tests/test_upload_seal_client.py
index d6f9156..2e4bfb5 100644
--- a/packages/meshbay-hub/tests/test_upload_seal_client.py
+++ b/packages/meshbay-hub/tests/test_upload_seal_client.py
@@ -167,3 +167,41 @@ def test_the_client_refuses_an_older_node_before_sending_a_chunk(_gek):
     assert result["state"] == "rejected"
     assert "older MeshBay" in result["message"]
     assert result["frames"] == [], "a chunk was sent to a node that cannot open it"
+
+
+def test_an_interrupted_upload_resumes_where_the_node_stopped(tmp_path, _gek):
+    """
+    The browser asks, the node answers, and the second attempt sends only what
+    is missing.
+
+    Both halves are the shipped ones: the frames come from the real
+    `uploadFile`, the answer comes from the real node handler. What is asserted
+    is the thing that used to be impossible — an upload interrupted at chunk two
+    of five that sends three chunks instead of five.
+    """
+    body = bytes(range(256)) * ((CHUNK * 5) // 256 + 1)
+    body = body[:CHUNK * 5]
+    first = _run_probe(_probe_input(_gek, "send",
+                                    file={"name": "film.mkv", "data": body.hex()}))
+    frames = [msgpack.unpackb(bytes.fromhex(f), raw=False)
+              for f in first["frames"]]
+    assert [f["chunk_index"] for f in frames] == [-1, 0, 1, 2, 3, 4]
+
+    # The link drops after two chunks.
+    session = _node_session(tmp_path, _gek)
+    for frame in frames[1:3]:
+        session._do_file_upload(frame)
+    assert not [m for m in session.sent if m.get("type") == "error"]
+
+    # It comes back and asks.
+    session.sent.clear()
+    session._do_file_upload(frames[0])
+    probe_ack = msgpack.packb(session.sent[-1], use_bin_type=True).hex()
+
+    second = _run_probe(_probe_input(
+        _gek, "send", file={"name": "film.mkv", "data": body.hex()},
+        probe_ack=probe_ack))
+    resumed = [msgpack.unpackb(bytes.fromhex(f), raw=False)["chunk_index"]
+               for f in second["frames"]]
+    assert resumed == [-1, 2, 3, 4], (
+        f"sent {resumed} — the answer to the probe was not used")
diff --git a/packages/meshbay-node/src/meshbay_node/transport/webrtc_server.py b/packages/meshbay-node/src/meshbay_node/transport/webrtc_server.py
index 6bae27c..9de799c 100644
--- a/packages/meshbay-node/src/meshbay_node/transport/webrtc_server.py
+++ b/packages/meshbay-node/src/meshbay_node/transport/webrtc_server.py
@@ -120,6 +120,7 @@ from meshbay_common.protocol import (
     MNP,
     chunk_ciphertext,
     file_chunk_wire,
+    UPLOAD_PROBE_INDEX,
     file_upload_ack_wire,
     file_upload_payload,
 )
@@ -4792,6 +4793,30 @@ class WebRTCPeerSession:
         ctx = self._group_ctx()
         upload_id = str(msg.get("upload_id") or "")[:64]
 
+        # Say the slot is being used, chunk by chunk, exactly as `_do_file_req`
+        # does for a download.
+        #
+        # A grant nobody takes up is reclaimed after GRANT_DEADLINE_SECS and, on
+        # the third miss, abandoned. Uploads were not gated by the lease, so the
+        # file still arrived — but the widget follows the lease, so a 3.5 GB
+        # upload showed "waiting, 0 ahead" for a minute and a half while it was
+        # in fact transferring, and the node logged three reclaims against a
+        # transfer that never stopped. Measured, from the journal:
+        #
+        #   11:52:49 open upload 919ebf54 -> granted
+        #   11:53:19 reclaimed 919ebf54 (not_taken_up)
+        #   11:54:19 reclaimed 919ebf54 (abandoned)
+        #   11:55:48 Upload complete: ... (3 522 297 517 bytes)
+        #
+        # The download twin of this was fixed on 2026-09-08 (§12.1 of
+        # ~/next/improve-downloads.md); the same omission was still here,
+        # invisible until uploads started taking a real lease.
+        tr = msg.get("tr")
+        if tr:
+            slots = self._ctx.get("_transfer_slots")
+            if slots is not None:
+                slots.touch(str(tr)[:64])
+
         gek = ctx.get("gek")
         if not gek:
             self._send({"type": "error", "detail": "Group encryption not initialized",
@@ -4949,6 +4974,29 @@ class WebRTCPeerSession:
         tmp_path = target_dir / f"{stored_name}{uploads_mod.PART_SUFFIX}"
         final_path = target_dir / stored_name
 
+        if chunk_index == UPLOAD_PROBE_INDEX:
+            # "Where am I?", asked inside the seal rather than on a clear
+            # message, because the answer is about a file whose name is exactly
+            # what sealing this path was for.
+            #
+            # It writes nothing, creates no state and reserves no name: a client
+            # that asks and then goes away has cost this node one reply. Every
+            # check above has already run, so it cannot be used to ask questions
+            # about a directory the caller may not write to.
+            self._send(file_upload_ack_wire(
+                gek, self._group_id or "",
+                upload_id=upload_id,
+                chunk_index=UPLOAD_PROBE_INDEX,
+                filename=filename,
+                # Only what is really on disk. Without state, `_free_name` above
+                # picked a name nothing has claimed yet, and reporting it would
+                # promise a destination the real chunk 0 may not choose.
+                stored_as=state.stored_name if state else "",
+                dir=rel_dir,
+                resume_from=state.next_index if state else 0,
+            ))
+            return
+
         if chunk_index == 0:
             # Backstop: _free_name already guarantees this, and it stays because
             # it asserts the invariant where the write happens.
diff --git a/packages/meshbay-node/tests/test_partial_uploads.py b/packages/meshbay-node/tests/test_partial_uploads.py
index ea5637c..f5b6602 100644
--- a/packages/meshbay-node/tests/test_partial_uploads.py
+++ b/packages/meshbay-node/tests/test_partial_uploads.py
@@ -28,6 +28,10 @@ from meshbay_node.indexer.group_index import GroupIndex
 from meshbay_node.roots import Root, RootSet
 from meshbay_node.transport.webrtc_server import WebRTCPeerSession
 
+from meshbay_common.protocol import (
+    UPLOAD_PROBE_INDEX, file_upload_ack_payload,
+)
+
 from conftest import one_root, sealed_upload
 
 from meshbay_node.uploads import (
@@ -358,3 +362,128 @@ def test_an_upload_in_flight_is_known_to_the_reaper(tmp_path):
     assert len(live) == 1
     assert next(iter(live)).name == "film.mkv.part"
     assert next(iter(live)).exists()
+
+
+# ── asking where to resume ──────────────────────────────────────────────────
+
+
+def _acks(session, ctx):
+    return [file_upload_ack_payload(ctx["gek"], GROUP, m)
+            for m in session.sent if m.get("type") == "file_upload_ack"]
+
+
+def _probe(session, filename: str) -> dict:
+    """The question, asked exactly as the client asks it: an ordinary sealed
+    upload chunk with no bytes and the probe index."""
+    return sealed_upload(session, filename=filename, data=b"",
+                         chunk_index=UPLOAD_PROBE_INDEX, total_chunks=1)
+
+
+def test_a_probe_for_an_unknown_file_says_start_at_the_beginning(tmp_path):
+    ctx = _group_ctx(tmp_path)
+    peer = _peer(ctx)
+    peer._do_file_upload(_probe(peer, "film.mkv"))
+    assert _errors(peer) == []
+    assert _acks(peer, ctx)[0]["resume_from"] == 0
+
+
+def test_a_probe_reports_what_the_node_already_holds(tmp_path):
+    """The point of the whole stage: the client learns it has 2 chunks there and
+    sends the third, instead of sending a film again."""
+    ctx = _group_ctx(tmp_path)
+    first = _peer(ctx)
+    for i in range(2):
+        first._do_file_upload(sealed_upload(first, filename="film.mkv",
+                                            data=b"xxxx", chunk_index=i,
+                                            total_chunks=5))
+    assert _errors(first) == []
+
+    reconnected = _peer(ctx)
+    reconnected._do_file_upload(_probe(reconnected, "film.mkv"))
+    ack = _acks(reconnected, ctx)[0]
+    assert ack["resume_from"] == 2
+    assert ack["stored_as"] == "film.mkv"
+
+
+def test_a_probe_writes_nothing_and_reserves_nothing(tmp_path):
+    """It has to be free of consequence: a client that asks and goes away must
+    leave no file, no state and no name taken."""
+    ctx = _group_ctx(tmp_path)
+    peer = _peer(ctx)
+    peer._do_file_upload(_probe(peer, "film.mkv"))
+    root = ctx["roots"].roots[0]
+    assert list(root.path.iterdir()) == []
+    assert len(ctx.get("partial_uploads") or []) == 0
+    # And it promises no destination it has not taken.
+    assert _acks(peer, ctx)[0]["stored_as"] == ""
+
+
+def test_a_probe_answers_only_about_the_member_who_asks(tmp_path):
+    """Same keying as the upload itself. Otherwise one member could measure
+    another's progress on a file they never sent — and worse, resume it."""
+    ctx = _group_ctx(tmp_path)
+    alice = _peer(ctx, "alice")
+    alice._do_file_upload(sealed_upload(alice, filename="film.mkv",
+                                        data=b"xxxx", chunk_index=0,
+                                        total_chunks=5))
+    bob = _peer(ctx, "bob")
+    bob._do_file_upload(_probe(bob, "film.mkv"))
+    assert _acks(bob, ctx)[0]["resume_from"] == 0
+
+
+def test_an_ordinary_ack_carries_no_resume_field(tmp_path):
+    """So a client can tell a probe's answer from a chunk's without looking at
+    the index it echoed."""
+    ctx = _group_ctx(tmp_path)
+    peer = _peer(ctx)
+    peer._do_file_upload(sealed_upload(peer, filename="a.bin", data=b"x",
+                                       chunk_index=0, total_chunks=2))
+    assert "resume_from" not in _acks(peer, ctx)[0]
+
+
+def test_a_probe_is_refused_where_an_upload_would_be(tmp_path):
+    """Every check the write path makes has already run when the probe is
+    answered, so it cannot be used to ask questions about somewhere the caller
+    may not write."""
+    ctx = _group_ctx(tmp_path)
+    peer = _peer(ctx)
+    peer._do_file_upload(sealed_upload(peer, filename="../escape",
+                                       data=b"", chunk_index=UPLOAD_PROBE_INDEX,
+                                       total_chunks=1))
+    assert [m.get("code") for m in _errors(peer)] == ["invalid_filename"]
+    assert _acks(peer, ctx) == []
+
+
+# ── the slot an upload holds ────────────────────────────────────────────────
+
+def test_an_upload_chunk_says_its_slot_is_in_use(tmp_path):
+    """A grant nobody takes up is reclaimed after thirty seconds and abandoned
+    on the third miss. Uploads are not gated by the lease, so the file arrived
+    anyway — but the widget follows the lease, and a 3.5 GB upload therefore
+    read "waiting, 0 ahead" for a minute and a half while it was transferring,
+    with three reclaims logged against it.
+
+    The download twin of this was fixed a day earlier; the same omission was
+    still here, invisible until uploads took a real lease.
+    """
+    from meshbay_node.transfers import TransferSlots, UPLOAD
+
+    ctx = _group_ctx(tmp_path)
+    peer = _peer(ctx)
+    slots = TransferSlots()
+    peer._ctx = dict(ctx)
+    peer._ctx["_transfer_slots"] = slots
+    peer._registry_key = "session-1"
+    lease, err = slots.open(tr="up-1", kind=UPLOAD, session_key="session-1",
+                            user_id="user-1", group_id=GROUP, bytes=10, chunks=2)
+    assert not err and lease.state == "granted"
+    assert lease.used is False
+
+    msg = sealed_upload(peer, filename="film.mkv", data=b"xxxx",
+                        chunk_index=0, total_chunks=2)
+    msg["tr"] = "up-1"
+    peer._do_file_upload(msg)
+
+    assert _errors(peer) == []
+    assert slots.leases["up-1"].used is True, (
+        "the node still believes nobody took this slot up, and will reclaim it")
-- 
cgit v1.2.3


From b472b4d43149ed12a7f64c94f34c34f436bef492 Mon Sep 17 00:00:00 2001
From: Christophe Besson <cbesson@gmail.com>
Date: Wed, 9 Sep 2026 14:14:11 +0200
Subject: fix(spa): a paused transfer is not a finished one
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Reported while testing the flag day: pausing an upload put it under "Finished".

"Finished" was defined by exclusion — everything that is not running, queued or
preparing — so it swallowed `paused` the day pausing shipped. A transfer
somebody stopped on purpose then sat beside the ones that are actually over,
offering a resume button in the section of things that cannot be resumed, and
dropped out of the badge, which announced less activity than there was.

Paused is now its own group, in all ten catalogues, and counts as active: it is
not over, the person means to come back to it.

The three filters are lifted out of `app.js` and executed rather than described
in the test, and one case asserts that every status lands in exactly one group
— a state added later that falls into none is a transfer the panel simply does
not show, which is how this one got in.

The same report also said the three running downloads lost their pause buttons
when the upload was paused. That part is **not** explained and **not** fixed:
the store returns `pausable` true and status `running` for all three (new test),
closing an upload lease pumps only the upload queue, and the button's condition
is a pure function of those two. All three say the buttons should have stayed,
so an observation is missing rather than a cause.

Hub suite 864 passed.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HCGdheDLxGReuKHga3BtST
---
 packages/meshbay-hub/src/meshbay_hub/static/app.js |  15 ++-
 .../src/meshbay_hub/static/locales/de.js           |   1 +
 .../src/meshbay_hub/static/locales/en.js           |   1 +
 .../src/meshbay_hub/static/locales/es.js           |   1 +
 .../src/meshbay_hub/static/locales/fr.js           |   1 +
 .../src/meshbay_hub/static/locales/it.js           |   1 +
 .../src/meshbay_hub/static/locales/ja.js           |   1 +
 .../src/meshbay_hub/static/locales/nl.js           |   1 +
 .../src/meshbay_hub/static/locales/pl.js           |   1 +
 .../src/meshbay_hub/static/locales/pt-BR.js        |   1 +
 .../src/meshbay_hub/static/locales/zh-CN.js        |   1 +
 packages/meshbay-hub/tests/test_transfers.py       | 109 +++++++++++++++++++++
 12 files changed, 132 insertions(+), 2 deletions(-)

(limited to 'packages/meshbay-hub/tests/test_transfers.py')

diff --git a/packages/meshbay-hub/src/meshbay_hub/static/app.js b/packages/meshbay-hub/src/meshbay_hub/static/app.js
index 0394af6..de47982 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/app.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/app.js
@@ -159,10 +159,20 @@ function TransferWidget() {
   const running = items.filter(i => i.status === 'running');
   const waiting = items.filter(
     i => i.status === 'queued' || i.status === 'preparing');
+  // Its own group, and not a leftover.
+  //
+  // "Finished" used to be defined as everything that is not running, queued or
+  // preparing — a definition by exclusion, which quietly swallowed `paused` the
+  // day pausing shipped. A transfer somebody stopped on purpose then sat under
+  // "Finished", beside the ones that are actually over, offering a resume
+  // button in the section of things that cannot be resumed.
+  const paused = items.filter(i => i.status === 'paused');
   const finished = items.filter(
     i => i.status !== 'running' && i.status !== 'queued'
-      && i.status !== 'preparing');
-  const active = running.length + waiting.length;
+      && i.status !== 'preparing' && i.status !== 'paused');
+  // Paused counts as active: it is not over, the person means to come back to
+  // it, and the badge saying nothing is happening would be a lie.
+  const active = running.length + waiting.length + paused.length;
 
   // Grouped, and in this order: what is moving, what is waiting, what is over.
   // Re-sorting the flat list on every emit made rows jump under the pointer
@@ -171,6 +181,7 @@ function TransferWidget() {
   const groups = [
     ['running', running],
     ['waiting', waiting],
+    ['paused', paused],
     ['finished', finished],
   ].filter(([, rows]) => rows.length);
 
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/locales/de.js b/packages/meshbay-hub/src/meshbay_hub/static/locales/de.js
index fd63ddf..738b131 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/locales/de.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/locales/de.js
@@ -584,6 +584,7 @@ export default {
   'transfers.summary': '{running} laufend · {waiting} wartend',
   'transfers.group_running': 'Laufend',
   'transfers.group_waiting': 'Wartend',
+  'transfers.group_paused': 'Angehalten',
   'transfers.group_finished': 'Abgeschlossen',
   'transfers.cancel_one': '{name} abbrechen',
   'transfers.pause': 'Anhalten',
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/locales/en.js b/packages/meshbay-hub/src/meshbay_hub/static/locales/en.js
index e9d4072..0b9de8a 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/locales/en.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/locales/en.js
@@ -700,6 +700,7 @@ export default {
   'transfers.summary': '{running} running · {waiting} waiting',
   'transfers.group_running': 'Running',
   'transfers.group_waiting': 'Waiting',
+  'transfers.group_paused': 'Paused',
   'transfers.group_finished': 'Finished',
   'transfers.cancel_one': 'Cancel {name}',
   'transfers.pause': 'Pause',
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/locales/es.js b/packages/meshbay-hub/src/meshbay_hub/static/locales/es.js
index 4fa19e7..8da8f9f 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/locales/es.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/locales/es.js
@@ -580,6 +580,7 @@ export default {
   'transfers.summary': '{running} en curso · {waiting} en espera',
   'transfers.group_running': 'En curso',
   'transfers.group_waiting': 'En espera',
+  'transfers.group_paused': 'En pausa',
   'transfers.group_finished': 'Finalizados',
   'transfers.cancel_one': 'Cancelar {name}',
   'transfers.pause': 'Pausar',
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/locales/fr.js b/packages/meshbay-hub/src/meshbay_hub/static/locales/fr.js
index 6fba91d..3135c03 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/locales/fr.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/locales/fr.js
@@ -583,6 +583,7 @@ export default {
   'transfers.summary': '{running} en cours · {waiting} en attente',
   'transfers.group_running': 'En cours',
   'transfers.group_waiting': 'En attente',
+  'transfers.group_paused': 'En pause',
   'transfers.group_finished': 'Terminés',
   'transfers.cancel_one': 'Annuler {name}',
   'transfers.pause': 'Suspendre',
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/locales/it.js b/packages/meshbay-hub/src/meshbay_hub/static/locales/it.js
index 76b3101..91f0e9b 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/locales/it.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/locales/it.js
@@ -583,6 +583,7 @@ export default {
   'transfers.summary': '{running} in corso · {waiting} in attesa',
   'transfers.group_running': 'In corso',
   'transfers.group_waiting': 'In attesa',
+  'transfers.group_paused': 'In pausa',
   'transfers.group_finished': 'Completati',
   'transfers.cancel_one': 'Annulla {name}',
   'transfers.pause': 'Sospendi',
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/locales/ja.js b/packages/meshbay-hub/src/meshbay_hub/static/locales/ja.js
index cfc1125..b352188 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/locales/ja.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/locales/ja.js
@@ -575,6 +575,7 @@ export default {
   'transfers.summary': '実行中 {running} · 待機中 {waiting}',
   'transfers.group_running': '実行中',
   'transfers.group_waiting': '待機中',
+  'transfers.group_paused': '一時停止中',
   'transfers.group_finished': '完了',
   'transfers.cancel_one': '{name} をキャンセル',
   'transfers.pause': '一時停止',
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/locales/nl.js b/packages/meshbay-hub/src/meshbay_hub/static/locales/nl.js
index 29cc566..e0a799d 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/locales/nl.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/locales/nl.js
@@ -584,6 +584,7 @@ export default {
   'transfers.summary': '{running} bezig · {waiting} wachtend',
   'transfers.group_running': 'Bezig',
   'transfers.group_waiting': 'Wachtend',
+  'transfers.group_paused': 'Gepauzeerd',
   'transfers.group_finished': 'Voltooid',
   'transfers.cancel_one': '{name} annuleren',
   'transfers.pause': 'Pauzeren',
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/locales/pl.js b/packages/meshbay-hub/src/meshbay_hub/static/locales/pl.js
index 38fe714..e6319b0 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/locales/pl.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/locales/pl.js
@@ -596,6 +596,7 @@ export default {
   'transfers.summary': '{running} w toku · {waiting} oczekuje',
   'transfers.group_running': 'W toku',
   'transfers.group_waiting': 'Oczekuje',
+  'transfers.group_paused': 'Wstrzymane',
   'transfers.group_finished': 'Zakończone',
   'transfers.cancel_one': 'Anuluj {name}',
   'transfers.pause': 'Wstrzymaj',
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/locales/pt-BR.js b/packages/meshbay-hub/src/meshbay_hub/static/locales/pt-BR.js
index 5942b77..02c8356 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/locales/pt-BR.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/locales/pt-BR.js
@@ -582,6 +582,7 @@ export default {
   'transfers.summary': '{running} em andamento · {waiting} aguardando',
   'transfers.group_running': 'Em andamento',
   'transfers.group_waiting': 'Aguardando',
+  'transfers.group_paused': 'Pausados',
   'transfers.group_finished': 'Concluídos',
   'transfers.cancel_one': 'Cancelar {name}',
   'transfers.pause': 'Pausar',
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/locales/zh-CN.js b/packages/meshbay-hub/src/meshbay_hub/static/locales/zh-CN.js
index 56af6c8..6c4c73f 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/locales/zh-CN.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/locales/zh-CN.js
@@ -563,6 +563,7 @@ export default {
   'transfers.summary': '进行中 {running} · 等待中 {waiting}',
   'transfers.group_running': '进行中',
   'transfers.group_waiting': '等待中',
+  'transfers.group_paused': '已暂停',
   'transfers.group_finished': '已完成',
   'transfers.cancel_one': '取消 {name}',
   'transfers.pause': '暂停',
diff --git a/packages/meshbay-hub/tests/test_transfers.py b/packages/meshbay-hub/tests/test_transfers.py
index f27d4fd..d19a458 100644
--- a/packages/meshbay-hub/tests/test_transfers.py
+++ b/packages/meshbay-hub/tests/test_transfers.py
@@ -770,3 +770,112 @@ def test_an_upload_handed_a_lease_it_cannot_recreate_is_not_offered_pause(tmp_pa
       t.cancel(id);
     """, tmp_path)
     assert out == ["status:running"]
+
+
+def test_pausing_one_transfer_leaves_the_others_alone(tmp_path):
+    """Reported: three downloads running, one upload paused, and the three
+    downloads lost their pause buttons.
+
+    The button is drawn from `pausable` and the status, so this asks the store
+    what it says about the other three at the moment one of them pauses.
+    """
+    out = _run(_lease_stub() + """
+      const t = new TransferStore();
+      const leases = [];
+      const mk = (kind, name) => t.start({
+        kind, name, total: 100, pausable: true,
+        makeLease: () => { const l = new L(); leases.push(l); return l; },
+        run: async ({ signal, from }) => {
+          for (let i = from || 0; i < 40; i++) {
+            await new Promise(r => setTimeout(r, 5));
+            if (signal.aborted) { const e = new Error('c'); e.name = 'AbortError'; throw e; }
+            if (signal.paused) {
+              signal.resumeFrom = i;
+              const e = new Error('p'); e.name = 'PausedError'; throw e;
+            }
+          }
+        },
+      });
+      mk('download', 'd1'); mk('download', 'd2'); mk('download', 'd3');
+      mk('upload', 'u1');
+      await new Promise(r => setTimeout(r, 5));
+      for (const l of leases) l.grant();
+      await new Promise(r => setTimeout(r, 20));
+      const up = t.list().find(i => i.kind === 'upload');
+      say('before:' + t.list().filter(
+        i => i.kind === 'download' && i.pausable && i.status === 'running').length);
+      t.pause(up.id);
+      await new Promise(r => setTimeout(r, 40));
+      const rows = t.list();
+      say('after:' + rows.filter(
+        i => i.kind === 'download' && i.pausable && i.status === 'running').length);
+      say('statuses:' + rows.map(i => i.kind[0] + ':' + i.status).join(','));
+      for (const r of rows) t.cancel(r.id);
+    """, tmp_path)
+    assert out[0] == "before:3"
+    assert out[1] == "after:3", (
+        f"pausing the upload changed the downloads — {out[2]}")
+
+
+def test_a_paused_transfer_is_not_filed_under_finished(tmp_path):
+    """"Finished" was defined by exclusion — everything that is not running,
+    queued or preparing — so it quietly swallowed `paused` the day pausing
+    shipped. A transfer somebody stopped on purpose then sat beside the ones
+    that are actually over, offering a resume button in the section of things
+    that cannot be resumed.
+
+    The three filters are lifted out of `app.js` and run, rather than described
+    here: a copy of them in this file would agree with a broken version by
+    construction.
+    """
+    src = (STATIC / "app.js").read_text()
+    start = src.index("  const running = items.filter(")
+    block = src[start:src.index("const active =", start)]
+
+    script = tmp_path / "groups.mjs"
+    script.write_text("""
+const items = [
+  { id: 1, status: 'running' },
+  { id: 2, status: 'queued' },
+  { id: 3, status: 'preparing' },
+  { id: 4, status: 'paused' },
+  { id: 5, status: 'done' },
+  { id: 6, status: 'failed' },
+  { id: 7, status: 'cancelled' },
+];
+""" + block + """
+const seen = { running, waiting, paused, finished };
+console.log(JSON.stringify(Object.fromEntries(
+  Object.entries(seen).map(([k, v]) => [k, v.map(i => i.id)]))));
+""")
+    proc = subprocess.run(["node", str(script)], capture_output=True, text=True)
+    assert proc.returncode == 0, proc.stderr
+    groups = json.loads(proc.stdout)
+
+    assert groups["paused"] == [4]
+    assert groups["finished"] == [5, 6, 7], (
+        f"paused landed in {groups['finished']}")
+    assert groups["running"] == [1] and groups["waiting"] == [2, 3]
+    # Every row appears exactly once: a state added later that lands in no group
+    # is a transfer the panel simply does not show.
+    placed = sum((groups[k] for k in groups), [])
+    assert sorted(placed) == [1, 2, 3, 4, 5, 6, 7]
+
+
+def test_a_paused_transfer_still_counts_as_active(tmp_path):
+    """The badge says how much is going on. A paused transfer is not over — the
+    person means to come back to it — so counting it as nothing would be a
+    panel that says "0" over work that is still there."""
+    src = (STATIC / "app.js").read_text()
+    start = src.index("  const running = items.filter(")
+    block = src[start:src.index("\n\n", src.index("const active =", start))]
+
+    script = tmp_path / "active.mjs"
+    script.write_text("""
+const items = [{ id: 1, status: 'paused' }, { id: 2, status: 'done' }];
+""" + block + """
+console.log(JSON.stringify({ active }));
+""")
+    proc = subprocess.run(["node", str(script)], capture_output=True, text=True)
+    assert proc.returncode == 0, proc.stderr
+    assert json.loads(proc.stdout)["active"] == 1
-- 
cgit v1.2.3


From e6f895c473a0b19e7b186889c1836d3945bc880b Mon Sep 17 00:00:00 2001
From: Christophe Besson <cbesson@gmail.com>
Date: Wed, 9 Sep 2026 14:24:59 +0200
Subject: fix(spa): say why a download cannot be paused
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Reported from Chrome, with a screenshot: four downloads with no pause button
and an upload beside them with one, and nothing anywhere saying why.

The reason is real. Without a granted download folder the browser writes
through the service worker — a download it already owns, which cannot be paused
without stalling it somewhere we can neither see nor resume. An upload writes to
the node, which keeps the position, so it is always pausable. But that was
stated only in a Settings line nobody reads on the way to a download, and a gap
where the row above has a button is not an explanation.

So a download that cannot be paused now shows a dimmed pause icon where the
button would be, carrying the reason and the remedy in its tooltip. Not a
button: there is nothing to click, and a disabled one invites the click anyway.

And only where the advice can be taken. Firefox and Safari have no folder to
choose — the streamed path is the only target they have, which is what §6.5 of
~/next/improve-downloads.md costs out — so telling someone there to choose one
would be advice they cannot follow. Nothing is drawn.

Hub suite 866 passed.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HCGdheDLxGReuKHga3BtST
---
 packages/meshbay-hub/src/meshbay_hub/static/app.js | 14 +++++++++
 .../src/meshbay_hub/static/locales/de.js           |  1 +
 .../src/meshbay_hub/static/locales/en.js           |  1 +
 .../src/meshbay_hub/static/locales/es.js           |  1 +
 .../src/meshbay_hub/static/locales/fr.js           |  1 +
 .../src/meshbay_hub/static/locales/it.js           |  1 +
 .../src/meshbay_hub/static/locales/ja.js           |  1 +
 .../src/meshbay_hub/static/locales/nl.js           |  1 +
 .../src/meshbay_hub/static/locales/pl.js           |  1 +
 .../src/meshbay_hub/static/locales/pt-BR.js        |  1 +
 .../src/meshbay_hub/static/locales/zh-CN.js        |  1 +
 .../meshbay-hub/src/meshbay_hub/static/style.css   | 10 +++++++
 packages/meshbay-hub/tests/test_transfers.py       | 35 ++++++++++++++++++++++
 13 files changed, 69 insertions(+)

(limited to 'packages/meshbay-hub/tests/test_transfers.py')

diff --git a/packages/meshbay-hub/src/meshbay_hub/static/app.js b/packages/meshbay-hub/src/meshbay_hub/static/app.js
index de47982..dfd0aeb 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/app.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/app.js
@@ -269,6 +269,20 @@ function TransferRow({ it }) {
             <${Icon} name=${it.status === 'paused' ? 'play' : 'pause'} />
           </button>
         `}
+        ${!it.pausable && downloads.SUPPORTED && it.kind === 'download'
+          && (it.status === 'running' || it.status === 'queued') && html`
+          ${/* Say why, rather than leaving a gap where a button is on the row
+                above. Without a granted folder this browser writes through the
+                service worker — a download it already owns, which cannot be
+                paused — so the button is absent for a reason nobody can see,
+                and an upload beside it has one. Shown only where choosing a
+                folder is actually possible: on Firefox and Safari there is no
+                folder to choose and this hint would be a lie. */''}
+          <span class="transfer-nopause" title=${t('transfers.not_pausable')}
+            aria-label=${t('transfers.not_pausable')}>
+            <${Icon} name="pause" />
+          </span>
+        `}
         ${(it.status === 'running' || it.status === 'queued'
            || it.status === 'preparing' || it.status === 'paused') && html`
           <button class="transfer-cancel"
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/locales/de.js b/packages/meshbay-hub/src/meshbay_hub/static/locales/de.js
index 738b131..0f632e3 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/locales/de.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/locales/de.js
@@ -590,6 +590,7 @@ export default {
   'transfers.pause': 'Anhalten',
   'transfers.resume': 'Fortsetzen',
   'transfers.paused': 'Angehalten',
+  'transfers.not_pausable': 'Kann nicht angehalten werden — wählen Sie in den Einstellungen einen Download-Ordner',
   'transfers.pause_one': '{name} anhalten',
   'transfers.resume_one': '{name} fortsetzen',
   'transfers.eta_seconds': 'noch {n} s',
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/locales/en.js b/packages/meshbay-hub/src/meshbay_hub/static/locales/en.js
index 0b9de8a..cb7f4a0 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/locales/en.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/locales/en.js
@@ -706,6 +706,7 @@ export default {
   'transfers.pause': 'Pause',
   'transfers.resume': 'Resume',
   'transfers.paused': 'Paused',
+  'transfers.not_pausable': 'Cannot be paused — choose a download folder in Settings to enable it',
   'transfers.pause_one': 'Pause {name}',
   'transfers.resume_one': 'Resume {name}',
   'transfers.eta_seconds': '{n}s left',
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/locales/es.js b/packages/meshbay-hub/src/meshbay_hub/static/locales/es.js
index 8da8f9f..fe1c13b 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/locales/es.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/locales/es.js
@@ -586,6 +586,7 @@ export default {
   'transfers.pause': 'Pausar',
   'transfers.resume': 'Reanudar',
   'transfers.paused': 'En pausa',
+  'transfers.not_pausable': 'No se puede pausar — elija una carpeta de descargas en Ajustes para activarlo',
   'transfers.pause_one': 'Pausar {name}',
   'transfers.resume_one': 'Reanudar {name}',
   'transfers.eta_seconds': 'quedan {n} s',
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/locales/fr.js b/packages/meshbay-hub/src/meshbay_hub/static/locales/fr.js
index 3135c03..ea3f60e 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/locales/fr.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/locales/fr.js
@@ -589,6 +589,7 @@ export default {
   'transfers.pause': 'Suspendre',
   'transfers.resume': 'Reprendre',
   'transfers.paused': 'En pause',
+  'transfers.not_pausable': 'Non suspendable — choisissez un dossier de téléchargement dans les Réglages pour l\'activer',
   'transfers.pause_one': 'Suspendre {name}',
   'transfers.resume_one': 'Reprendre {name}',
   'transfers.eta_seconds': '{n} s restantes',
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/locales/it.js b/packages/meshbay-hub/src/meshbay_hub/static/locales/it.js
index 91f0e9b..0687b25 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/locales/it.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/locales/it.js
@@ -589,6 +589,7 @@ export default {
   'transfers.pause': 'Sospendi',
   'transfers.resume': 'Riprendi',
   'transfers.paused': 'In pausa',
+  'transfers.not_pausable': 'Non si può sospendere — scelga una cartella di download nelle Impostazioni',
   'transfers.pause_one': 'Sospendi {name}',
   'transfers.resume_one': 'Riprendi {name}',
   'transfers.eta_seconds': '{n} s rimanenti',
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/locales/ja.js b/packages/meshbay-hub/src/meshbay_hub/static/locales/ja.js
index b352188..a02e058 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/locales/ja.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/locales/ja.js
@@ -581,6 +581,7 @@ export default {
   'transfers.pause': '一時停止',
   'transfers.resume': '再開',
   'transfers.paused': '一時停止中',
+  'transfers.not_pausable': '一時停止できません。設定でダウンロードフォルダーを選ぶと使えます',
   'transfers.pause_one': '{name} を一時停止',
   'transfers.resume_one': '{name} を再開',
   'transfers.eta_seconds': '残り {n} 秒',
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/locales/nl.js b/packages/meshbay-hub/src/meshbay_hub/static/locales/nl.js
index e0a799d..0235d8a 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/locales/nl.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/locales/nl.js
@@ -590,6 +590,7 @@ export default {
   'transfers.pause': 'Pauzeren',
   'transfers.resume': 'Hervatten',
   'transfers.paused': 'Gepauzeerd',
+  'transfers.not_pausable': 'Kan niet worden gepauzeerd — kies een downloadmap in Instellingen',
   'transfers.pause_one': '{name} pauzeren',
   'transfers.resume_one': '{name} hervatten',
   'transfers.eta_seconds': 'nog {n} s',
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/locales/pl.js b/packages/meshbay-hub/src/meshbay_hub/static/locales/pl.js
index e6319b0..af4a5bb 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/locales/pl.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/locales/pl.js
@@ -602,6 +602,7 @@ export default {
   'transfers.pause': 'Wstrzymaj',
   'transfers.resume': 'Wznów',
   'transfers.paused': 'Wstrzymano',
+  'transfers.not_pausable': 'Nie można wstrzymać — proszę wybrać folder pobierania w Ustawieniach',
   'transfers.pause_one': 'Wstrzymaj {name}',
   'transfers.resume_one': 'Wznów {name}',
   'transfers.eta_seconds': 'pozostało {n} s',
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/locales/pt-BR.js b/packages/meshbay-hub/src/meshbay_hub/static/locales/pt-BR.js
index 02c8356..f179c6f 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/locales/pt-BR.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/locales/pt-BR.js
@@ -588,6 +588,7 @@ export default {
   'transfers.pause': 'Pausar',
   'transfers.resume': 'Retomar',
   'transfers.paused': 'Pausado',
+  'transfers.not_pausable': 'Não pode ser pausado — escolha uma pasta de downloads em Configurações',
   'transfers.pause_one': 'Pausar {name}',
   'transfers.resume_one': 'Retomar {name}',
   'transfers.eta_seconds': 'faltam {n} s',
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/locales/zh-CN.js b/packages/meshbay-hub/src/meshbay_hub/static/locales/zh-CN.js
index 6c4c73f..c89bbdc 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/locales/zh-CN.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/locales/zh-CN.js
@@ -569,6 +569,7 @@ export default {
   'transfers.pause': '暂停',
   'transfers.resume': '继续',
   'transfers.paused': '已暂停',
+  'transfers.not_pausable': '无法暂停——请在设置中选择下载文件夹以启用',
   'transfers.pause_one': '暂停 {name}',
   'transfers.resume_one': '继续 {name}',
   'transfers.eta_seconds': '剩余 {n} 秒',
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/style.css b/packages/meshbay-hub/src/meshbay_hub/static/style.css
index a37e541..5e08a6a 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/style.css
+++ b/packages/meshbay-hub/src/meshbay_hub/static/style.css
@@ -1986,6 +1986,16 @@ a.transfer-name {
   display: flex;
 }
 .transfer-pause:hover { color: var(--accent); }
+/* Not a button: there is nothing to click. Dimmer than the cancel beside it,
+   and it carries its explanation in a tooltip rather than in the row, which
+   would be four lines of prose in a panel that has none. */
+.transfer-nopause {
+  color: var(--text-dim);
+  opacity: .45;
+  padding: 0 2px;
+  display: flex;
+  cursor: help;
+}
 /* A paused bar keeps its fill -- what was written is still on disk -- but stops
    looking like something in progress. */
 .dl-fill.dl-paused { background: var(--text-dim); }
diff --git a/packages/meshbay-hub/tests/test_transfers.py b/packages/meshbay-hub/tests/test_transfers.py
index d19a458..d93cf80 100644
--- a/packages/meshbay-hub/tests/test_transfers.py
+++ b/packages/meshbay-hub/tests/test_transfers.py
@@ -879,3 +879,38 @@ console.log(JSON.stringify({ active }));
     proc = subprocess.run(["node", str(script)], capture_output=True, text=True)
     assert proc.returncode == 0, proc.stderr
     assert json.loads(proc.stdout)["active"] == 1
+
+
+def test_a_row_that_cannot_pause_says_so_where_the_button_would_be():
+    """Reported from Chrome: four downloads with no pause button and an upload
+    with one, and no way to tell why.
+
+    The reason is real — without a granted folder the browser writes through the
+    service worker, a download it already owns and cannot pause — but it was
+    stated only in a Settings line nobody reads on the way to a download. A gap
+    where the row above has a button is not an explanation.
+
+    Shown only where a folder can actually be chosen: Firefox and Safari have
+    none to choose, and "choose a folder" would be advice that cannot be taken.
+    """
+    src = (STATIC / "app.js").read_text()
+    row = src[src.index("function TransferRow"):]
+    row = row[:row.index("\n}\n")]
+
+    hint = row[row.index("!it.pausable"):]
+    hint = hint[:hint.index("`}")]
+    assert "downloads.SUPPORTED" in hint, (
+        "the hint would tell a Firefox user to choose a folder it cannot offer")
+    assert "it.kind === 'download'" in hint, (
+        "an upload is always pausable; this is about download targets")
+    assert "transfers.not_pausable" in hint, "the reason is not stated"
+    # Not a button. There is nothing to click, and a disabled one invites the
+    # click anyway.
+    assert "<button" not in hint
+
+
+def test_the_reason_is_translated_everywhere():
+    """`t()` falls back to the key, so a missing catalogue entry shows
+    `transfers.not_pausable` in a tooltip rather than a sentence."""
+    for path in sorted((STATIC / "locales").glob("*.js")):
+        assert "'transfers.not_pausable'" in path.read_text(), path.name
-- 
cgit v1.2.3