From bdeffa448cdde9680fbf7bdda036746b101ddf75 Mon Sep 17 00:00:00 2001
From: Christophe Besson <cbesson@gmail.com>
Date: Tue, 8 Sep 2026 14:20:57 +0200
Subject: feat(node): transfer leases, pools and a queue for downloads and
 uploads
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Step 2 of ~/next/improve-downloads.md. A download is invisible to the node: it
is a series of independent `file_req` messages, with nothing saying one started
or ended, so there is nothing to count and nothing to cap. The lease is that
missing object.

`meshbay_node/transfers.py` holds the decisions and has no asyncio and no
transport in it, on purpose. The failure modes this has to survive — a slot the
node never gets back, a client waiting on a grant the node has forgotten — are
races through a DataChannel and unprovable there; here the clock is a parameter
and every method returns what changed, so the caller does the I/O and the tests
drive the worst case directly.

What it decides:

- two pools, downloads and uploads, separate from the stream pool: different
  resources with different costs, and merging them makes both caps meaningless;
- per-member cap checked *before* the node-wide one, so a member at their own
  limit queues behind their own transfers rather than holding a slot a second
  member has none of. Per account across their devices, or the cap becomes a
  function of how many tabs somebody opens;
- a queue that skips a member at their cap instead of waiting for them —
  granting strictly in arrival order lets one member's limit stall everyone;
- `tr` drawn by the client and idempotent, which is what makes a reconnect safe;
- bounded per member, because unbounded queues are how a node runs out of
  memory politely.

Every way a slot comes back, with the session teardown as the one that matters
(a closed tab, a quit browser and a dead network all arrive at
`shutdown_tasks`, and none of them needs a timer): explicit close, session
gone, a grant nobody took up in 30 s passed to the next in line, and a granted
transfer silent for 120 s reclaimed with its peer told, so a widget can offer a
resume rather than sit on a lie.

`GET /api/transfers` is the operator's window: when somebody reports a transfer
stuck at waiting, it is the only thing that says whether the node ever had them
in a queue — a log cannot, when the symptom is that nothing is happening. It
carries no filename and no path, which a test pins, because this is exactly
where one would be tempting.

Three things found while writing it, two of them mine:

- the randomised property test rejected `in_use <= cap` at once, and it was
  right to: lowering a cap never interrupts a running transfer, so the count
  legitimately sits above the new value. The invariant is that a *new* grant
  never happens past the cap;
- the sweeper was started with `self._spawn`, which ties a task to one
  session's set. It died with whichever peer opened the first transfer, and
  every other peer's abandoned lease then stopped being reclaimed — a node that
  fills up over days with nothing in the log. It belongs to the node now, with
  its strong reference on the transport context;
- the pools are node-wide while `_peer_registry` is per group (finding H1), so
  a slot freed in one group can grant one in another and the peer to notify is
  not in the notifier's registry. Silently wrong in the first version.

Nothing enforces a lease yet: `file_req` is untouched, no client asks, and the
node grants everything. That is step 4's flag day, and this lands alone.

1148 node, 793 hub, 0 failed.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HCGdheDLxGReuKHga3BtST
---
 packages/meshbay-common/src/meshbay_common/protocol.py | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

(limited to 'packages/meshbay-common')

diff --git a/packages/meshbay-common/src/meshbay_common/protocol.py b/packages/meshbay-common/src/meshbay_common/protocol.py
index e092353..4890d3b 100644
--- a/packages/meshbay-common/src/meshbay_common/protocol.py
+++ b/packages/meshbay-common/src/meshbay_common/protocol.py
@@ -96,6 +96,20 @@ class MNP:
     # never serve the GEK in plaintext. Members obtain it by unwrapping their own
     # ECIES bundle. The constants lingered after the handlers were deleted, leaving
     # the wire contract looking as though the endpoint still existed.
+    # Transfer slots. A download is otherwise invisible to the node -- a series
+    # of independent file_req messages, with nothing saying one started or
+    # ended -- so there is nothing to count and nothing to cap. The lease is
+    # that missing object: `tr` is drawn by the client like `upload_id`, covers
+    # a job rather than a file, and dies with the connection.
+    #
+    # One reply type with a state field, not four: a client that must switch on
+    # the message type to discover it is still waiting is a client that will get
+    # one branch wrong. Carries no filename and no path -- `tr` is opaque,
+    # `bytes` and `chunks` are numbers -- so it stays in clear like
+    # INDEX_PROGRESS, for the same stated reason.
+    TRANSFER_OPEN    = "transfer_open"     # client -> node: I want a slot
+    TRANSFER_CLOSE   = "transfer_close"    # client -> node: I am done with it
+    TRANSFER_STATE   = "transfer_state"    # node -> client: granted/queued/closed
     FILE_UPLOAD      = "file_upload"       # client pushes file chunk to node
     FILE_UPLOAD_ACK  = "file_upload_ack"   # node acknowledges chunk receipt
     DIR_CREATE       = "dir_create"        # client → node: make a directory
-- 
cgit v1.2.3


From 4b94468d24913c3071b48eeefb43367f4f5cd523 Mon Sep 17 00:00:00 2001
From: Christophe Besson <cbesson@gmail.com>
Date: Tue, 8 Sep 2026 14:53:03 +0200
Subject: feat(node): make the transfer caps settable, node-wide and per group
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Step 3 of ~/next/improve-downloads.md. Step 2 built the pools with constants;
this gives them to the operator, in the two scopes they belong to.

**The pools are the machine's.** `[node] max_concurrent_downloads` and
`max_concurrent_uploads`, default 8, on the §2.11 pattern: node.toml for a
fresh install, a roster.db override for immediate effect, editable from the
Node page and from `meshbay-node transfers show|set`, applied live through the
one `set_capacity` step 1 fixed.

**The per-member cap is a group's.** How many transfers one member may run at
once here — on the node like every other group setting (not the hub, which
would have authority over someone else's disk; not node.toml, which is
hand-written and needs a restart), changed by a signed operator instruction
(`OP_TRANSFER_LIMITS`, subject "d=2,u=2" so what is signed names the outcome),
broadcast to the group, and read live by the pools.

That was the one thing step 2's shape could not express: `per_member` was a
single node-wide number. `group_limits` and `member_cap(kind, member)` make it
a lookup — the group's own value if it has one, the node's default otherwise —
and it is deliberately the only dimension that is not node-wide.

Three refusals, each with a test:

- **absent means the default (2), never "unlimited".** A group that predates
  the setting coming back unlimited would leave the node-wide pool as the only
  control, which is the situation slots exist to end;
- **zero is not "unlimited"**, and is not "this member may not transfer"
  either: the floor is one everywhere, and the CLI says to revoke the member
  instead;
- **an unreadable row reads as unset**, not as zero — the same discipline the
  sealed messages follow, where a payload that does not open must never become
  a default state on its own.

`handshake_ack` carries this member's own caps for this group, so the interface
can say "2 of your 2 slots are busy" instead of drawing a bare spinner. Absent
reads as "no limit known" and the hint is not drawn — never as "unlimited",
which would have the interface contradicting the node.

1164 node, 793 hub, 0 failed.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HCGdheDLxGReuKHga3BtST
---
 .../meshbay-common/src/meshbay_common/adminop.py   |   6 +
 .../meshbay-common/src/meshbay_common/protocol.py  |   2 +
 .../src/meshbay_hub/static/locales/de.js           |   2 +
 .../src/meshbay_hub/static/locales/en.js           |   2 +
 .../src/meshbay_hub/static/locales/es.js           |   2 +
 .../src/meshbay_hub/static/locales/fr.js           |   2 +
 .../src/meshbay_hub/static/locales/it.js           |   2 +
 .../src/meshbay_hub/static/locales/ja.js           |   2 +
 .../src/meshbay_hub/static/locales/nl.js           |   2 +
 .../src/meshbay_hub/static/locales/pl.js           |   2 +
 .../src/meshbay_hub/static/locales/pt-BR.js        |   2 +
 .../src/meshbay_hub/static/locales/zh-CN.js        |   2 +
 .../src/meshbay_hub/static/node-page.js            |  14 ++
 packages/meshbay-node/src/meshbay_node/config.py   |  21 +++
 packages/meshbay-node/src/meshbay_node/daemon.py   |  69 +++++++++-
 packages/meshbay-node/src/meshbay_node/ops.py      |  28 ++++
 packages/meshbay-node/src/meshbay_node/roster.py   |  33 +++++
 .../meshbay-node/src/meshbay_node/transfers.py     |  34 ++++-
 .../src/meshbay_node/transport/webrtc_server.py    |  89 ++++++++++++
 packages/meshbay-node/tests/test_cli_dispatch.py   |   5 +
 .../meshbay-node/tests/test_transfer_settings.py   | 152 +++++++++++++++++++++
 21 files changed, 470 insertions(+), 3 deletions(-)
 create mode 100644 packages/meshbay-node/tests/test_transfer_settings.py

(limited to 'packages/meshbay-common')

diff --git a/packages/meshbay-common/src/meshbay_common/adminop.py b/packages/meshbay-common/src/meshbay_common/adminop.py
index ed6e940..5c7345b 100644
--- a/packages/meshbay-common/src/meshbay_common/adminop.py
+++ b/packages/meshbay-common/src/meshbay_common/adminop.py
@@ -61,6 +61,12 @@ OP_APPS_ENABLED = "apps_enabled"
 # security property in itself, but the pattern (every operator setting is
 # signed) is what keeps the authorization model simple to reason about.
 OP_SET_SCAN_SETTINGS = "set_scan_settings"
+# How many transfers one member may run at once in this group. Signed like the
+# rest: an unsigned cap is one any member can raise for themselves, which makes
+# the control a suggestion. The subject is "d=2,u=2" so what the operator is
+# shown before signing names the outcome and not the operation -- the same rule
+# member_upload's on/off subject follows.
+OP_TRANSFER_LIMITS = "transfer_limits"
 # Whether the node uses the operator's own API token/language instead of the
 # shipped default — node-wide (docs/mediacenter.md §5.5), one credential
 # shared by every group. Signed like the rest: it turns on outbound
diff --git a/packages/meshbay-common/src/meshbay_common/protocol.py b/packages/meshbay-common/src/meshbay_common/protocol.py
index 4890d3b..8a521bb 100644
--- a/packages/meshbay-common/src/meshbay_common/protocol.py
+++ b/packages/meshbay-common/src/meshbay_common/protocol.py
@@ -152,6 +152,8 @@ class MNP:
     MEMBER_UPLOAD_ACK    = "member_upload_ack"
     APPS_ENABLED         = "apps_enabled"          # operator → node: which group apps to show
     APPS_ENABLED_ACK     = "apps_enabled_ack"
+    TRANSFER_LIMITS       = "transfer_limits"       # operator → node: per-member caps for this group
+    TRANSFER_LIMITS_ACK   = "transfer_limits_ack"   # node → this group: the new caps
     SET_SCAN_SETTINGS     = "set_scan_settings"     # operator → node: reconcile/debounce timing
     SET_SCAN_SETTINGS_ACK = "set_scan_settings_ack"
     MEDIA_META_REQ        = "media_meta_req"        # client → node: TMDB metadata for a path
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 1ebab8b..8ed1ef0 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/locales/de.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/locales/de.js
@@ -739,6 +739,8 @@ export default {
   'node.setting_pair_ttl': 'Pairing code TTL',
   'node.setting_device_ttl': 'Device request TTL',
   'node.setting_max_streams': 'Max concurrent streams',
+  'node.setting_max_downloads': 'Max. gleichzeitige Downloads',
+  'node.setting_max_uploads': 'Max. gleichzeitige Uploads',
   'node.setting_transcode': 'Transcode incompatible video',
   'node.setting_unit_hours': 'hours',
   'node.setting_unit_minutes': 'min',
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 d85f51b..285ff7a 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/locales/en.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/locales/en.js
@@ -890,6 +890,8 @@ export default {
   'node.setting_pair_ttl': 'Pairing code TTL',
   'node.setting_device_ttl': 'Device request TTL',
   'node.setting_max_streams': 'Max concurrent streams',
+  'node.setting_max_downloads': 'Max concurrent downloads',
+  'node.setting_max_uploads': 'Max concurrent uploads',
   'node.setting_transcode': 'Transcode incompatible video',
   'node.setting_unit_hours': 'hours',
   'node.setting_unit_minutes': 'min',
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 bfe4112..f74c763 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/locales/es.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/locales/es.js
@@ -734,6 +734,8 @@ export default {
   'node.setting_pair_ttl': 'Pairing code TTL',
   'node.setting_device_ttl': 'Device request TTL',
   'node.setting_max_streams': 'Max concurrent streams',
+  'node.setting_max_downloads': 'Descargas simultáneas máximas',
+  'node.setting_max_uploads': 'Subidas simultáneas máximas',
   'node.setting_transcode': 'Transcode incompatible video',
   'node.setting_unit_hours': 'hours',
   'node.setting_unit_minutes': 'min',
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 9addec5..0c5103f 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/locales/fr.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/locales/fr.js
@@ -737,6 +737,8 @@ export default {
   'node.setting_pair_ttl': 'Durée du code d\'appairage',
   'node.setting_device_ttl': 'Durée des demandes d\'appareil',
   'node.setting_max_streams': 'Flux vidéo simultanés max',
+  'node.setting_max_downloads': 'Téléchargements simultanés max',
+  'node.setting_max_uploads': 'Téléversements simultanés max',
   'node.setting_transcode': 'Transcoder les vidéos incompatibles',
   'node.setting_unit_hours': 'heures',
   'node.setting_unit_minutes': 'min',
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 fe76b9e..ebac541 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/locales/it.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/locales/it.js
@@ -736,6 +736,8 @@ export default {
   'node.setting_pair_ttl': 'Pairing code TTL',
   'node.setting_device_ttl': 'Device request TTL',
   'node.setting_max_streams': 'Max concurrent streams',
+  'node.setting_max_downloads': 'Download simultanei massimi',
+  'node.setting_max_uploads': 'Caricamenti simultanei massimi',
   'node.setting_transcode': 'Transcode incompatible video',
   'node.setting_unit_hours': 'hours',
   'node.setting_unit_minutes': 'min',
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 272be73..1b49ddb 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/locales/ja.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/locales/ja.js
@@ -724,6 +724,8 @@ export default {
   'node.setting_pair_ttl': 'Pairing code TTL',
   'node.setting_device_ttl': 'Device request TTL',
   'node.setting_max_streams': 'Max concurrent streams',
+  'node.setting_max_downloads': '同時ダウンロードの上限',
+  'node.setting_max_uploads': '同時アップロードの上限',
   'node.setting_transcode': 'Transcode incompatible video',
   'node.setting_unit_hours': 'hours',
   'node.setting_unit_minutes': 'min',
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 76f3586..7cf4cd4 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/locales/nl.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/locales/nl.js
@@ -738,6 +738,8 @@ export default {
   'node.setting_pair_ttl': 'Pairing code TTL',
   'node.setting_device_ttl': 'Device request TTL',
   'node.setting_max_streams': 'Max concurrent streams',
+  'node.setting_max_downloads': 'Max. gelijktijdige downloads',
+  'node.setting_max_uploads': 'Max. gelijktijdige uploads',
   'node.setting_transcode': 'Transcode incompatible video',
   'node.setting_unit_hours': 'hours',
   'node.setting_unit_minutes': 'min',
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 dd05487..6edffd5 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/locales/pl.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/locales/pl.js
@@ -756,6 +756,8 @@ export default {
   'node.setting_pair_ttl': 'Pairing code TTL',
   'node.setting_device_ttl': 'Device request TTL',
   'node.setting_max_streams': 'Max concurrent streams',
+  'node.setting_max_downloads': 'Maks. równoczesnych pobierań',
+  'node.setting_max_uploads': 'Maks. równoczesnych wysyłek',
   'node.setting_transcode': 'Transcode incompatible video',
   'node.setting_unit_hours': 'hours',
   'node.setting_unit_minutes': 'min',
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 4632d36..3a6fa22 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
@@ -735,6 +735,8 @@ export default {
   'node.setting_pair_ttl': 'Pairing code TTL',
   'node.setting_device_ttl': 'Device request TTL',
   'node.setting_max_streams': 'Max concurrent streams',
+  'node.setting_max_downloads': 'Máximo de downloads simultâneos',
+  'node.setting_max_uploads': 'Máximo de envios simultâneos',
   'node.setting_transcode': 'Transcode incompatible video',
   'node.setting_unit_hours': 'hours',
   'node.setting_unit_minutes': 'min',
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 b6ff3c9..f43ef72 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
@@ -711,6 +711,8 @@ export default {
   'node.setting_pair_ttl': 'Pairing code TTL',
   'node.setting_device_ttl': 'Device request TTL',
   'node.setting_max_streams': 'Max concurrent streams',
+  'node.setting_max_downloads': '最大同时下载数',
+  'node.setting_max_uploads': '最大同时上传数',
   'node.setting_transcode': 'Transcode incompatible video',
   'node.setting_unit_hours': 'hours',
   'node.setting_unit_minutes': 'min',
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/node-page.js b/packages/meshbay-hub/src/meshbay_hub/static/node-page.js
index 2e216a9..c1d57f9 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/node-page.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/node-page.js
@@ -1043,6 +1043,20 @@ export function NodePage({ groups }) {
                   onInput=${e => setEditSettings(s => ({...s, max_concurrent_streams: parseInt(e.target.value) || 1}))} />
               </div>
             </label>
+            <label class="node-setting">
+              <span class="node-setting-label">${t('node.setting_max_downloads')}</span>
+              <div class="node-setting-input">
+                <input type="number" min="1" value=${editSettings.max_concurrent_downloads}
+                  onInput=${e => setEditSettings(s => ({...s, max_concurrent_downloads: parseInt(e.target.value) || 1}))} />
+              </div>
+            </label>
+            <label class="node-setting">
+              <span class="node-setting-label">${t('node.setting_max_uploads')}</span>
+              <div class="node-setting-input">
+                <input type="number" min="1" value=${editSettings.max_concurrent_uploads}
+                  onInput=${e => setEditSettings(s => ({...s, max_concurrent_uploads: parseInt(e.target.value) || 1}))} />
+              </div>
+            </label>
             <label class="node-setting">
               <span class="node-setting-label">${t('node.setting_transcode')}</span>
               <div class="node-setting-input">
diff --git a/packages/meshbay-node/src/meshbay_node/config.py b/packages/meshbay-node/src/meshbay_node/config.py
index 7673a51..7351b1c 100644
--- a/packages/meshbay-node/src/meshbay_node/config.py
+++ b/packages/meshbay-node/src/meshbay_node/config.py
@@ -60,6 +60,13 @@ device_request_ttl_minutes = 60
 # lower it on a Pi.
 max_concurrent_streams = 8
 
+# How many downloads and uploads run at once on this node, across every group.
+# A slot is concurrency, not bandwidth: what it protects is open file handles,
+# disk seeks and the channel buffer each transfer keeps full. Past this, a
+# member is queued and told so, and starts when a slot frees.
+max_concurrent_downloads = 8
+max_concurrent_uploads = 8
+
 # HEVC sources have no browser decoder on most platforms, so streaming one is
 # transcoded to H264 rather than the usual free copy — real CPU per viewer.
 # Set to false only if every viewer's client is known to decode HEVC itself.
@@ -157,6 +164,14 @@ class NodeConfig:
     # the node answers "server busy" — see MAX_CONCURRENT_TRANSCODES in
     # transport/webrtc_server.py for what one costs.
     max_concurrent_streams: int = 8
+    # How many transfers run at once on this node, across every group —
+    # separate pools, because a download and an upload cost different things
+    # and one queue for both makes each cap meaningless. Streaming has its own
+    # third pool (max_concurrent_streams above): a member watching a film is
+    # not charged a download slot, and a download does not make the next film
+    # answer "server busy". See meshbay_node/transfers.py.
+    max_concurrent_downloads: int = 8
+    max_concurrent_uploads: int = 8
     # HEVC (and any future codec in media_probe.py's
     # BROWSER_INCOMPATIBLE_VIDEO_CODECS) has no decoder in most browsers, so
     # streaming it needs a real re-encode to H264 rather than the usual free
@@ -332,6 +347,12 @@ def load_config(path: Path = DEFAULT_CONFIG_PATH) -> Config:
         cfg.node.max_concurrent_streams = _positive(
             nd.get("max_concurrent_streams", cfg.node.max_concurrent_streams),
             cfg.node.max_concurrent_streams, "max_concurrent_streams")
+        cfg.node.max_concurrent_downloads = _positive(
+            nd.get("max_concurrent_downloads", cfg.node.max_concurrent_downloads),
+            cfg.node.max_concurrent_downloads, "max_concurrent_downloads")
+        cfg.node.max_concurrent_uploads = _positive(
+            nd.get("max_concurrent_uploads", cfg.node.max_concurrent_uploads),
+            cfg.node.max_concurrent_uploads, "max_concurrent_uploads")
         cfg.node.transcode_incompatible_video = bool(
             nd.get("transcode_incompatible_video", cfg.node.transcode_incompatible_video))
         ice_if = nd.get("ice_interfaces")
diff --git a/packages/meshbay-node/src/meshbay_node/daemon.py b/packages/meshbay-node/src/meshbay_node/daemon.py
index e270b6c..f7c1b33 100644
--- a/packages/meshbay-node/src/meshbay_node/daemon.py
+++ b/packages/meshbay-node/src/meshbay_node/daemon.py
@@ -406,6 +406,12 @@ class NodeDaemon:
                     # which the RootSet above already carries.)
                     "enabled_apps": await self._roster.enabled_apps(
                         group_cfg.id) if self._roster else list(Roster.DEFAULT_APPS),
+                    # How many transfers one member may run at once here. Empty
+                    # means the operator has not said, and the node's default
+                    # applies — never "unlimited" (transfers.member_cap).
+                    "transfer_limits": (
+                        await self._roster.transfer_limits(group_cfg.id)
+                        if self._roster else {}),
                     # Which folder(s) inside the shared roots each app works
                     # over. One shape for every app (roster.py's
                     # app_directories) — an empty list means nothing has been
@@ -511,6 +517,8 @@ class NodeDaemon:
                     groups=groups_ctx,
                     denylist=denylist,
                     max_concurrent_streams=self._config.node.max_concurrent_streams,
+                    max_concurrent_downloads=self._config.node.max_concurrent_downloads,
+                    max_concurrent_uploads=self._config.node.max_concurrent_uploads,
                     transcode_incompatible_video=self._config.node.transcode_incompatible_video,
                     stun_servers=self._config.node.stun_servers or None,
                 )
@@ -874,6 +882,9 @@ class NodeDaemon:
                 "enabled_apps": (
                     await self._roster.enabled_apps(group_cfg.id)
                     if self._roster else list(Roster.DEFAULT_APPS)),
+                "transfer_limits": (
+                    await self._roster.transfer_limits(group_cfg.id)
+                    if self._roster else {}),
                 **(await self._app_directories_ctx(group_cfg.id)),
                 "chat_link_preview": (
                     await self._roster.chat_link_preview(group_cfg.id)
@@ -1799,6 +1810,7 @@ def main() -> None:
                         choices=["init", "reset", "status", "gek-init",
                                  "gek", "operator", "member", "group", "root",
                                  "file", "video", "chat", "denylist", "stun",
+                                 "transfers",
                                  "reload",
                                  "restart-daemon", "autostart", "service",
                                  "calibrate-argon2"],
@@ -1814,6 +1826,8 @@ def main() -> None:
                              "| chat status|rotate|encrypt-history|prune "
                              "| denylist show|clear "
                              "| stun list|add|remove|reset "
+                             "| transfers show|set: live transfer slots, and "
+                             "the node-wide download/upload caps "
                              "| reload: re-read node.toml (hot; systemd or the "
                              "loopback API) | restart-daemon: restart the node "
                              "(systemd unit, the Windows autostart launcher, or the "
@@ -1831,12 +1845,16 @@ def main() -> None:
                              "init|rotate for gek; "
                              "list|rm for file; rematch for video; show|clear for "
                              "denylist; list|add|remove|reset for stun; "
+                             "show|set for transfers; "
                              "install|remove|start|stop|status for autostart and "
                              "for service")
     parser.add_argument("target", nargs="?",
                         help="username for member invite|revoke|unpin; group name "
                              "for group add; file id for file rm; identifier for "
-                             "denylist clear")
+                             "denylist clear; download cap for transfers set")
+    parser.add_argument("value", nargs="?",
+                        help="the second value where a verb takes two: the "
+                             "upload cap for transfers set")
     parser.add_argument("--hub-url", default=None,
                         help="hub URL, for init (e.g. https://meshbay.org)")
     parser.add_argument("--username", default=None,
@@ -2560,6 +2578,55 @@ def main() -> None:
         print("usage: meshbay-node stun list|add|remove|reset [url]")
         sys.exit(1)
 
+    if args.command == "transfers":
+        cfg = load_config(args.config or DEFAULT_CONFIG_PATH)
+        sub = args.subcommand or "show"
+
+        if sub == "show":
+            out = _daemon_api(cfg, "/api/transfers")
+            for kind, pool in out.get("pools", {}).items():
+                print(f"  {kind:<9} {pool['in_use']}/{pool['cap']} in use, "
+                      f"{pool['queued']} queued, "
+                      f"{pool['per_member']} per member")
+            leases = out.get("leases", [])
+            if not leases:
+                print("\n  nothing transferring")
+                return
+            print(f"\n  {'transfer':<14}{'kind':<10}{'state':<9}"
+                  f"{'user':<12}{'bytes':>12}")
+            for x in leases:
+                where = f"  (#{x['ahead'] + 1} in queue)" if x["state"] == "queued" else ""
+                print(f"  {x['tr']:<14}{x['kind']:<10}{x['state']:<9}"
+                      f"{x['user_id'][:10]:<12}{x['bytes']:>12}{where}")
+            return
+
+        if sub == "set":
+            # `transfers set 4 2` — downloads, then uploads. Node-wide; the
+            # per-member cap is a group's setting and is signed, so it is not
+            # settable from here (see `ops.set_transfer_limits`).
+            values = [v for v in (args.target, args.value) if v]
+            if len(values) != 2:
+                print("usage: meshbay-node transfers set <downloads> <uploads>")
+                sys.exit(1)
+            try:
+                downloads, uploads = int(values[0]), int(values[1])
+            except ValueError:
+                print("error: both values must be whole numbers")
+                sys.exit(1)
+            if downloads < 1 or uploads < 1:
+                print("error: a cap below 1 is not 'unlimited'; it would stop "
+                      "every transfer. Revoke the member instead.")
+                sys.exit(1)
+            out = _daemon_api(cfg, "/api/node-settings", method="PUT",
+                              body={"max_concurrent_downloads": downloads,
+                                    "max_concurrent_uploads": uploads})
+            print(f"downloads: {downloads}, uploads: {uploads} "
+                  f"(applied now, and kept in node.toml)")
+            return
+
+        print("usage: meshbay-node transfers show|set <downloads> <uploads>")
+        sys.exit(1)
+
     if args.command == "file":
         cfg = load_config(args.config or DEFAULT_CONFIG_PATH)
         sub = args.subcommand or "list"
diff --git a/packages/meshbay-node/src/meshbay_node/ops.py b/packages/meshbay-node/src/meshbay_node/ops.py
index 9fcbc21..81b92c7 100644
--- a/packages/meshbay-node/src/meshbay_node/ops.py
+++ b/packages/meshbay-node/src/meshbay_node/ops.py
@@ -1298,6 +1298,8 @@ async def get_node_settings(state: dict) -> dict:
         "pair_ttl_hours": nd.pair_ttl_hours,
         "device_request_ttl_minutes": nd.device_request_ttl_minutes,
         "max_concurrent_streams": nd.max_concurrent_streams,
+        "max_concurrent_downloads": nd.max_concurrent_downloads,
+        "max_concurrent_uploads": nd.max_concurrent_uploads,
         "transcode_incompatible_video": nd.transcode_incompatible_video,
         "stun_servers": nd.stun_servers if nd.stun_servers else list(DEFAULT_STUN_SERVERS),
         "ice_interfaces": nd.ice_interfaces,
@@ -1318,6 +1320,8 @@ async def set_node_settings(state: dict, settings: dict) -> dict:
         "pair_ttl_hours": ("int", roster.SETTING_PAIR_TTL),
         "device_request_ttl_minutes": ("int", roster.SETTING_DEVICE_TTL),
         "max_concurrent_streams": ("int", roster.SETTING_MAX_STREAMS),
+        "max_concurrent_downloads": ("int", roster.SETTING_MAX_DOWNLOADS),
+        "max_concurrent_uploads": ("int", roster.SETTING_MAX_UPLOADS),
         "transcode_incompatible_video": ("bool", roster.SETTING_TRANSCODE),
         "stun_servers": ("stun_list", roster.SETTING_STUN_SERVERS),
         "ice_interfaces": ("list", roster.SETTING_ICE_INTERFACES),
@@ -1393,6 +1397,30 @@ async def set_node_settings(state: dict, settings: dict) -> dict:
 
 # ── Transfers ────────────────────────────────────────────────────────────────
 
+async def set_transfer_limits(state: dict, group_id: str,
+                              downloads: int, uploads: int) -> dict:
+    """How many transfers one member may run at once in this group.
+
+    Same shape as every other operator setting: lives on the node (roster.db,
+    not the hub and not node.toml, for the reason change 5 gives — a hub that
+    decided this would have authority over someone else's machine), signed
+    (webrtc_server checks the caller's admin authority before this runs), and
+    live, so the pools are updated in place rather than at the next restart.
+    """
+    roster = _roster(state)
+    ctx = _group_ctx(state, group_id)
+    limits = await roster.set_transfer_limits(
+        group_id, {"download": downloads, "upload": uploads},
+        set_by=state.get("node_user_id", ""))
+    ctx["transfer_limits"] = limits
+    webrtc = state.get("webrtc")
+    slots = getattr(webrtc, "_ctx", {}).get("_transfer_slots") if webrtc else None
+    granted = slots.set_group_limits(group_id, limits) if slots else []
+    log.info("Transfer limits for group %s: %s (%d started at once)",
+             group_id[:8], limits, len(granted))
+    return {"group_id": group_id, "limits": limits,
+            "started": [x.tr for x in granted]}
+
 async def list_transfers(state: dict) -> dict:
     """Live transfer leases and queue depth.
 
diff --git a/packages/meshbay-node/src/meshbay_node/roster.py b/packages/meshbay-node/src/meshbay_node/roster.py
index 3d3a143..ae0b4cf 100644
--- a/packages/meshbay-node/src/meshbay_node/roster.py
+++ b/packages/meshbay-node/src/meshbay_node/roster.py
@@ -701,6 +701,35 @@ class Roster:
     SETTING_ENABLED_APPS = "enabled_apps"
     DEFAULT_APPS = ("chat", "files")
 
+    # How many transfers one member may run at once in this group. Unset means
+    # the node's default (transfers.DEFAULT_MAX_PER_MEMBER), never "unlimited":
+    # a group that predates this coming back unlimited would leave the
+    # node-wide pool as the only control.
+    SETTING_TRANSFER_LIMITS = "transfer_limits"
+
+    async def transfer_limits(self, group_id: str) -> dict[str, int]:
+        """{"download": n, "upload": n}, or {} when the operator has not said."""
+        value = await self.get_setting(group_id, self.SETTING_TRANSFER_LIMITS)
+        if value is None:
+            return {}
+        try:
+            raw = json.loads(value)
+        except (ValueError, TypeError):
+            return {}
+        out: dict[str, int] = {}
+        for kind in ("download", "upload"):
+            if isinstance(raw.get(kind), int) and raw[kind] >= 1:
+                out[kind] = raw[kind]
+        return out
+
+    async def set_transfer_limits(self, group_id: str, limits: dict[str, int],
+                                  set_by: str = "") -> dict[str, int]:
+        clean = {k: max(1, int(v)) for k, v in limits.items()
+                 if k in ("download", "upload")}
+        await self.set_setting(group_id, self.SETTING_TRANSFER_LIMITS,
+                               json.dumps(clean), set_by)
+        return clean
+
     async def enabled_apps(self, group_id: str) -> list[str]:
         value = await self.get_setting(group_id, self.SETTING_ENABLED_APPS)
         if value is None:
@@ -936,6 +965,8 @@ class Roster:
     SETTING_PAIR_TTL = "pair_ttl_hours"
     SETTING_DEVICE_TTL = "device_request_ttl_minutes"
     SETTING_MAX_STREAMS = "max_concurrent_streams"
+    SETTING_MAX_DOWNLOADS = "max_concurrent_downloads"
+    SETTING_MAX_UPLOADS = "max_concurrent_uploads"
     SETTING_TRANSCODE = "transcode_incompatible_video"
     SETTING_STUN_SERVERS = "stun_servers"
     SETTING_ICE_INTERFACES = "ice_interfaces"
@@ -949,6 +980,8 @@ class Roster:
             ("pair_ttl_hours", self.SETTING_PAIR_TTL),
             ("device_request_ttl_minutes", self.SETTING_DEVICE_TTL),
             ("max_concurrent_streams", self.SETTING_MAX_STREAMS),
+            ("max_concurrent_downloads", self.SETTING_MAX_DOWNLOADS),
+            ("max_concurrent_uploads", self.SETTING_MAX_UPLOADS),
             ("transcode_incompatible_video", self.SETTING_TRANSCODE),
         ]:
             stored = await self.get_setting(self.NODE_WIDE_GROUP_ID, setting)
diff --git a/packages/meshbay-node/src/meshbay_node/transfers.py b/packages/meshbay-node/src/meshbay_node/transfers.py
index 0689ec8..533e985 100644
--- a/packages/meshbay-node/src/meshbay_node/transfers.py
+++ b/packages/meshbay-node/src/meshbay_node/transfers.py
@@ -104,8 +104,13 @@ class TransferSlots:
 
     caps: dict[str, int] = field(
         default_factory=lambda: {k: DEFAULT_MAX_CONCURRENT for k in KINDS})
+    # The node-wide default per member, per kind.
     per_member: dict[str, int] = field(
         default_factory=lambda: {k: DEFAULT_MAX_PER_MEMBER for k in KINDS})
+    # Per-group overrides: {group_id: {kind: n}}. The cap is a group's setting
+    # (its operator signs it), while the pools are the machine's — so this is
+    # the one dimension that is not node-wide, and a lookup rather than a field.
+    group_limits: dict[str, dict[str, int]] = field(default_factory=dict)
     leases: dict[str, Lease] = field(default_factory=dict)
     # FIFO of `tr`, per kind. Order is arrival; a member at their own cap is
     # skipped rather than blocking the head, or one member's limit would stall
@@ -135,10 +140,22 @@ class TransferSlots:
         except ValueError:
             return 0
 
+    def member_cap(self, kind: str, member: tuple[str, str]) -> int:
+        """This member's cap in this group: the group's own, else the default.
+
+        Absent means the default, never "unlimited" — a group that predates the
+        setting coming back unlimited would leave the node-wide cap as the only
+        control, which is the situation slots exist to end.
+        """
+        group_id = member[0]
+        override = self.group_limits.get(group_id, {}).get(kind)
+        if override is not None:
+            return int(override)
+        return self.per_member.get(kind, DEFAULT_MAX_PER_MEMBER)
+
     def _has_room(self, kind: str, member: tuple[str, str]) -> bool:
         # Per-member first: see the module docstring.
-        if self.member_in_use(kind, member) >= self.per_member.get(
-                kind, DEFAULT_MAX_PER_MEMBER):
+        if self.member_in_use(kind, member) >= self.member_cap(kind, member):
             return False
         return self.in_use(kind) < self.caps.get(kind, DEFAULT_MAX_CONCURRENT)
 
@@ -292,6 +309,19 @@ class TransferSlots:
 
     # ── what the operator sees ──────────────────────────────────────────────
 
+    def set_group_limits(self, group_id: str, limits: dict[str, int],
+                         now: float | None = None) -> list[Lease]:
+        """One group's per-member caps, as its operator signed them."""
+        current = dict(self.group_limits.get(group_id, {}))
+        for kind, value in limits.items():
+            if kind in KINDS:
+                current[kind] = max(1, int(value))
+        self.group_limits[group_id] = current
+        granted: list[Lease] = []
+        for kind in KINDS:
+            granted.extend(self._pump(kind, now))
+        return granted
+
     def set_caps(self, *, node: dict[str, int] | None = None,
                  per_member: dict[str, int] | None = None,
                  now: float | None = None) -> list[Lease]:
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 164cc62..fdab53d 100644
--- a/packages/meshbay-node/src/meshbay_node/transport/webrtc_server.py
+++ b/packages/meshbay-node/src/meshbay_node/transport/webrtc_server.py
@@ -70,6 +70,7 @@ from meshbay_common.adminop import (
     OP_MEMBER_UPLOAD,
     OP_APPS_ENABLED,
     OP_SET_SCAN_SETTINGS,
+    OP_TRANSFER_LIMITS,
     OP_TMDB_CONFIG,
     OP_TMDB_ENABLED,
     OP_VIDEO_ROOT,
@@ -565,6 +566,8 @@ class WebRTCPeerSession:
                 self._do_member_upload(msg)
             elif mtype == MNP.APPS_ENABLED:
                 self._do_apps_enabled(msg)
+            elif mtype == MNP.TRANSFER_LIMITS:
+                self._do_transfer_limits(msg)
             elif mtype == MNP.SET_SCAN_SETTINGS:
                 self._do_set_scan_settings(msg)
             elif mtype == MNP.TMDB_CONFIG:
@@ -933,6 +936,19 @@ class WebRTCPeerSession:
             # No `chat_encrypted` beside it: there is no switch. A peer that
             # reached this point speaks MNP 2.0, and 2.0 has no plaintext chat.
             "chat_epoch": int(self._group_ctx().get("chat_epoch", 0) or 0),
+            # This member's own transfer caps in this group, so the interface
+            # can say "2 of 2 of your slots are busy" rather than draw a bare
+            # spinner. Absent reads as "no limit known" and the hint is simply
+            # not drawn — never as "unlimited", which would have the interface
+            # contradicting the node.
+            "transfer_limits": {
+                "download": self._slots().member_cap(
+                    transfers_mod.DOWNLOAD,
+                    (self._group_id or "", self._user_id or "")),
+                "upload": self._slots().member_cap(
+                    transfers_mod.UPLOAD,
+                    (self._group_id or "", self._user_id or "")),
+            },
             # So a client that connects mid-scan shows the indexing state
             # immediately, instead of waiting for the next periodic
             # INDEX_PROGRESS push. Never a path or filename — see
@@ -2715,6 +2731,64 @@ class WebRTCPeerSession:
         self._issue_admin_challenge(
             OP_SET_SCAN_SETTINGS, f"{reconcile:g},{debounce:g}")
 
+    MIN_TRANSFER_LIMIT = 1
+    MAX_TRANSFER_LIMIT = 32
+
+    def _do_transfer_limits(self, msg: dict) -> None:
+        """How many transfers one member may run at once in this group.
+
+        Zero is not "unlimited" and is refused: a member who may not transfer at
+        all is a member the operator revokes, and reading 0 as no-limit would
+        make the most dangerous value the easiest to type by accident.
+        """
+        try:
+            downloads = int(msg.get("downloads"))
+            uploads = int(msg.get("uploads"))
+        except (TypeError, ValueError):
+            self._send({"type": "error", "detail": "Invalid transfer limits"})
+            return
+        for value in (downloads, uploads):
+            if not (self.MIN_TRANSFER_LIMIT <= value <= self.MAX_TRANSFER_LIMIT):
+                self._send({"type": "error",
+                            "detail": f"transfer limits must be between "
+                                      f"{self.MIN_TRANSFER_LIMIT} and "
+                                      f"{self.MAX_TRANSFER_LIMIT}"})
+                return
+        if not self._has_admin_authority():
+            self._send({"type": "error", "detail": "No authorized key for this"})
+            return
+        self._issue_admin_challenge(OP_TRANSFER_LIMITS,
+                                    f"d={downloads},u={uploads}")
+
+    async def _admin_exec_transfer_limits(
+        self, pending: dict, transcript: bytes, sig: bytes,
+    ) -> None:
+        try:
+            parts = dict(p.split("=") for p in pending["subject"].split(","))
+            downloads, uploads = int(parts["d"]), int(parts["u"])
+        except (ValueError, KeyError):
+            self._send({"type": "error", "detail": "Invalid transfer limits"})
+            return
+        if not await self._verify_admin_sig(transcript, sig):
+            self._send({"type": "error", "detail": "Signature verification failed"})
+            self._audit("admin_auth_failed", f"transfer_limits:{pending['subject']}")
+            return
+        try:
+            result = await self._run_op(
+                ops.set_transfer_limits, self._group_id or "", downloads, uploads)
+        except ops.OpError as e:
+            self._send({"type": "error", "detail": e.message})
+            return
+        self._audit("transfer_limits", pending["subject"])
+
+        notice = {"type": MNP.TRANSFER_LIMITS_ACK, "v": MNP_VERSION,
+                  "limits": result["limits"]}
+        for session in list(self._peer_registry().values()):
+            try:
+                session._send(notice)
+            except Exception:
+                pass
+
     async def _admin_exec_set_scan_settings(
         self, pending: dict, transcript: bytes, sig: bytes,
     ) -> None:
@@ -3341,6 +3415,12 @@ class WebRTCPeerSession:
                 slots.caps[transfers_mod.UPLOAD] = int(u)
             self._ctx["_transfer_slots"] = slots
             log.info("transfer: %s", slots.summary())
+        # Refreshed from the group context rather than only at construction: a
+        # node serves several groups, each with its own signed cap, and the
+        # pools are built by whichever group happens to transfer first.
+        limits = self._group_ctx().get("transfer_limits")
+        if limits and self._group_id:
+            slots.group_limits[self._group_id] = dict(limits)
         return slots
 
     def _transfer_state_msg(self, lease, state: str, reason: str = "") -> dict:
@@ -5124,6 +5204,9 @@ class WebRTCPeerSession:
         elif pending["op"] == OP_APPS_ENABLED:
             self._spawn(
                 self._admin_exec_apps_enabled(pending, transcript, sig_bytes))
+        elif pending["op"] == OP_TRANSFER_LIMITS:
+            self._spawn(
+                self._admin_exec_transfer_limits(pending, transcript, sig_bytes))
         elif pending["op"] == OP_SET_SCAN_SETTINGS:
             self._spawn(
                 self._admin_exec_set_scan_settings(pending, transcript, sig_bytes))
@@ -5795,6 +5878,8 @@ class WebRTCTransport:
         denylist: Any | None = None,
         stun_servers: list[str] | None = None,
         max_concurrent_streams: int | None = None,
+        max_concurrent_downloads: int | None = None,
+        max_concurrent_uploads: int | None = None,
         transcode_incompatible_video: bool = True,
     ):
         self._ctx: dict[str, Any] = {
@@ -5807,6 +5892,10 @@ class WebRTCTransport:
             # None means "the operator said nothing" — the default applies. It
             # is read once, when the first stream builds the semaphore.
             "max_concurrent_streams": max_concurrent_streams,
+            # Read once, when the first transfer builds the pools. None means
+            # the operator said nothing and transfers.py's defaults apply.
+            "max_concurrent_downloads": max_concurrent_downloads,
+            "max_concurrent_uploads": max_concurrent_uploads,
             # Operator opt-out (node.toml) for the HEVC-etc. transcode
             # fallback in _stream_video_inner — real CPU cost, unlike copy.
             "transcode_incompatible_video": transcode_incompatible_video,
diff --git a/packages/meshbay-node/tests/test_cli_dispatch.py b/packages/meshbay-node/tests/test_cli_dispatch.py
index 6f43772..87b8550 100644
--- a/packages/meshbay-node/tests/test_cli_dispatch.py
+++ b/packages/meshbay-node/tests/test_cli_dispatch.py
@@ -46,6 +46,11 @@ VERBS = [
     # that no longer takes one.
     ["member", "upload"],
     ["operator", "pair"],
+    ["transfers"],                         # defaults to show
+    ["transfers", "show"],
+    ["transfers", "set", "4", "2"],
+    ["transfers", "set", "4"],             # only one number: usage, then exit
+    ["transfers", "set", "0", "2"],        # zero is not "unlimited": refused
     ["file", "list"],
     ["file", "rm", "abc", "--yes"],
     ["video", "rematch", "--yes"],
diff --git a/packages/meshbay-node/tests/test_transfer_settings.py b/packages/meshbay-node/tests/test_transfer_settings.py
new file mode 100644
index 0000000..79502e7
--- /dev/null
+++ b/packages/meshbay-node/tests/test_transfer_settings.py
@@ -0,0 +1,152 @@
+"""
+The two scopes a transfer cap has, and the rule that they are not the same kind
+of setting.
+
+The **pools** are the machine's: how many transfers this node runs at once,
+across every group, from `[node]` in node.toml with a roster override — the
+§2.11 pattern, changed from the Node page or the CLI, applied live.
+
+The **per-member cap** is a group's: how many one member may run at once here.
+It lives on the node like every other group setting (not the hub, which would
+have authority over someone else's disk; not node.toml, which is hand-written
+and needs a restart), and changing it is a signed operator instruction, because
+an unsigned cap is one any member can raise for themselves.
+
+What is checked here is the seam between the stored value and the pool that
+enforces it — a setting that is written, acknowledged and never read is the
+shape of the bug this whole branch started from (`webrtc._stream_sem`).
+"""
+
+import pytest
+
+from meshbay_node.roster import Roster
+from meshbay_node.transfers import (
+    DEFAULT_MAX_PER_MEMBER, DOWNLOAD, UPLOAD, TransferSlots,
+)
+
+
+@pytest.fixture
+async def roster(tmp_path):
+    r = Roster(db_path=tmp_path / "roster.db")
+    await r.open()
+    yield r
+    await r.close()
+
+
+# ── the group's own cap ─────────────────────────────────────────────────────
+
+@pytest.mark.asyncio
+async def test_absent_means_the_default_not_unlimited(roster):
+    """A group that predates the setting must not come back unlimited: the
+    node-wide pool would then be the only control, which is the situation slots
+    exist to end."""
+    assert await roster.transfer_limits("g1") == {}
+    slots = TransferSlots()
+    assert slots.member_cap(DOWNLOAD, ("g1", "alice")) == DEFAULT_MAX_PER_MEMBER
+
+
+@pytest.mark.asyncio
+async def test_the_cap_survives_a_restart(roster, tmp_path):
+    await roster.set_transfer_limits("g1", {"download": 4, "upload": 1},
+                                     set_by="op")
+    await roster.close()
+    reopened = Roster(db_path=tmp_path / "roster.db")
+    await reopened.open()
+    try:
+        assert await reopened.transfer_limits("g1") == {"download": 4,
+                                                        "upload": 1}
+    finally:
+        await reopened.close()
+
+
+@pytest.mark.asyncio
+async def test_one_group_does_not_set_anothers(roster):
+    await roster.set_transfer_limits("g1", {"download": 5}, set_by="op")
+    assert await roster.transfer_limits("g2") == {}
+
+
+@pytest.mark.asyncio
+async def test_a_stored_zero_never_becomes_a_cap_of_zero(roster):
+    """Zero is not "unlimited" and must not be "nobody may transfer" either.
+    Whatever reaches storage, the floor is one."""
+    await roster.set_transfer_limits("g1", {"download": 0}, set_by="op")
+    assert (await roster.transfer_limits("g1"))["download"] == 1
+
+
+@pytest.mark.asyncio
+async def test_rubbish_in_the_row_reads_as_unset(roster):
+    """A row this code did not write must not take a group's transfers down —
+    the same "a payload that does not open ends nothing silently" discipline
+    the sealed messages follow."""
+    await roster.set_setting("g1", Roster.SETTING_TRANSFER_LIMITS,
+                             "not json", "op")
+    assert await roster.transfer_limits("g1") == {}
+
+
+# ── the pool that enforces it ───────────────────────────────────────────────
+
+def test_a_group_cap_overrides_the_node_default():
+    slots = TransferSlots()
+    slots.set_group_limits("strict", {DOWNLOAD: 1})
+    assert slots.member_cap(DOWNLOAD, ("strict", "alice")) == 1
+    assert slots.member_cap(DOWNLOAD, ("other", "alice")) == DEFAULT_MAX_PER_MEMBER
+    assert slots.member_cap(UPLOAD, ("strict", "alice")) == DEFAULT_MAX_PER_MEMBER, (
+        "setting the download cap must not silently change the upload one")
+
+
+def test_the_group_cap_is_what_queues_a_member():
+    slots = TransferSlots()
+    slots.set_group_limits("strict", {DOWNLOAD: 1})
+    args = dict(kind=DOWNLOAD, session_key="s1", user_id="alice",
+                group_id="strict")
+    assert slots.open(tr="t1", **args)[0].state == "granted"
+    assert slots.open(tr="t2", **args)[0].state == "queued"
+
+
+def test_raising_a_group_cap_starts_what_was_waiting():
+    slots = TransferSlots()
+    slots.set_group_limits("g1", {DOWNLOAD: 1})
+    args = dict(kind=DOWNLOAD, session_key="s1", user_id="alice", group_id="g1")
+    slots.open(tr="t1", **args)
+    slots.open(tr="t2", **args)
+    granted = slots.set_group_limits("g1", {DOWNLOAD: 3})
+    assert [x.tr for x in granted] == ["t2"], (
+        "the cap was raised and the waiting transfer was left waiting")
+
+
+def test_one_groups_cap_does_not_move_anothers_queue():
+    slots = TransferSlots()
+    slots.set_group_limits("g1", {DOWNLOAD: 1})
+    slots.set_group_limits("g2", {DOWNLOAD: 1})
+    for g in ("g1", "g2"):
+        args = dict(kind=DOWNLOAD, session_key=f"s-{g}", user_id="alice",
+                    group_id=g)
+        slots.open(tr=f"{g}-1", **args)
+        slots.open(tr=f"{g}-2", **args)
+    granted = slots.set_group_limits("g1", {DOWNLOAD: 2})
+    assert [x.tr for x in granted] == ["g1-2"]
+    assert slots.leases["g2-2"].state == "queued"
+
+
+# ── the node-wide pools ─────────────────────────────────────────────────────
+
+@pytest.mark.asyncio
+async def test_the_node_wide_caps_round_trip_through_the_roster(roster):
+    defaults = {"max_concurrent_downloads": 8, "max_concurrent_uploads": 8}
+    assert await roster.node_settings(defaults) == {
+        **{k: v for k, v in defaults.items()},
+        **{k: None for k in ("invite_ttl_hours", "pair_ttl_hours",
+                             "device_request_ttl_minutes",
+                             "max_concurrent_streams",
+                             "transcode_incompatible_video")},
+        "stun_servers": [], "ice_interfaces": [],
+    }
+    await roster.set_node_setting(roster.SETTING_MAX_DOWNLOADS, "3", "op")
+    assert (await roster.node_settings(defaults))["max_concurrent_downloads"] == 3
+
+
+def test_node_toml_carries_both_keys():
+    """The template is what an operator reads before they read any document."""
+    from meshbay_node.config import EXAMPLE_CONFIG as tpl
+    assert "max_concurrent_downloads" in tpl
+    assert "max_concurrent_uploads" in tpl
-- 
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-common')

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 53ea44cb03ef6f8d941f6c8c9446551b0c5cd1ac Mon Sep 17 00:00:00 2001
From: Christophe Besson <cbesson@gmail.com>
Date: Wed, 9 Sep 2026 14:00:22 +0200
Subject: feat: MNP 3.0 — a transfer needs a lease
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Stage 4 of ~/next/improve-downloads.md, the flag day. Leases become compulsory
and a 2.x peer is refused at the handshake.

**The bound on leaseless reads (§3.4.1) did not exist, and it is what makes the
rest mean anything.** Browsing a group is never subject to a transfer slot —
that is an operator decision and a requirement: a member must be able to browse
a group at capacity exactly as they browse an idle one. But "not leased" cannot
mean "unbounded", or a client that simply omits `tr` transfers outside every cap
and the caps are decoration. A session may now read two distinct files at once
without a lease: one because a viewer looks at one file, two so that prefetching
the next photo stays possible. A count of files and not a byte budget, because a
RAW photo is 60-80 MB and is browsing while a 40 MB archive is a download, and
no size threshold separates them. Thumbnails, posters and cover art never reach
this check at all — they resolve out of the node's own cache.

It is a fairness control among cooperating clients, in the company of
`max_concurrent_streams`, and is not a defence against a member determined to
saturate a node's disk. That member is a member, and the answer to them is
`member revoke`.

**MNP_VERSION and MNP_MIN_SUPPORTED both move to 3.0**, on both sides. The
messages are additive; the requirement is not. An opt-in switch would leave a
leaseless branch reachable on every node, which is finding C6's lesson — a
transport that accepted a bare JWT — one feature later.

**The desktop client now checks before it connects.** The SPA is served by the
hub and picks up a new client on reload; the application ships its own
interface, so an un-updated one would sign in, list groups, and fail every
connection with `version_too_old` — a refusal in a protocol vocabulary with
nothing anyone can act on. It asks `/v1/hub/version` for `client.minimum` and
says so plainly instead. An unreachable hub is deliberately *not* "too old": a
captive portal or a closed laptop must not make starting the application
impossible.

**Every package is aligned on 0.13.0.** `meshbay-client/package.json` had
drifted to 1.0.0 while the Python packages were on 0.12.0 — invisible until
something compared those numbers, and then load-bearing: an installed client
announcing 1.0.0 sorts above a 0.13.0 minimum and walks through the gate meant
to stop it. That is stated in the code rather than left to be rediscovered; it
is acceptable exactly once, because the operator is updating every client, node
and hub by hand for this flag day. A new test fails if two packages ever
disagree again, and another fails if the hub would refuse the client the tree
builds.

Node suite 1209 passed, hub suite 861 passed.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HCGdheDLxGReuKHga3BtST
---
 packages/meshbay-client/package.json               |   4 +-
 packages/meshbay-client/src/main.js                |  70 +++++++++-
 packages/meshbay-common/pyproject.toml             |   2 +-
 .../meshbay-common/src/meshbay_common/__init__.py  |  36 +++++-
 .../meshbay-common/src/meshbay_common/handshake.py |   7 +-
 packages/meshbay-hub/pyproject.toml                |   2 +-
 packages/meshbay-hub/src/meshbay_hub/__init__.py   |   2 +-
 packages/meshbay-hub/src/meshbay_hub/api/hub.py    |  17 ++-
 .../src/meshbay_hub/static/transport.js            |   8 +-
 .../meshbay-hub/tests/test_client_version_gate.py  | 141 +++++++++++++++++++++
 packages/meshbay-hub/tests/test_versions_agree.py  |  74 +++++++++++
 packages/meshbay-node/pyproject.toml               |   2 +-
 packages/meshbay-node/src/meshbay_node/__init__.py |   2 +-
 .../meshbay-node/src/meshbay_node/transfers.py     |  83 ++++++++++++
 .../src/meshbay_node/transport/webrtc_server.py    |  29 +++++
 .../meshbay-node/tests/test_leaseless_reads.py     |  85 +++++++++++++
 16 files changed, 549 insertions(+), 15 deletions(-)
 create mode 100644 packages/meshbay-hub/tests/test_client_version_gate.py
 create mode 100644 packages/meshbay-hub/tests/test_versions_agree.py
 create mode 100644 packages/meshbay-node/tests/test_leaseless_reads.py

(limited to 'packages/meshbay-common')

diff --git a/packages/meshbay-client/package.json b/packages/meshbay-client/package.json
index 00ed8a9..e88b2f0 100644
--- a/packages/meshbay-client/package.json
+++ b/packages/meshbay-client/package.json
@@ -1,7 +1,7 @@
 {
   "name": "meshbay-client",
-  "version": "1.0.0",
-  "description": "MeshBay desktop client — the interface ships with the application, not from the hub",
+  "version": "0.13.0",
+  "description": "MeshBay desktop client \u2014 the interface ships with the application, not from the hub",
   "license": "AGPL-3.0-or-later",
   "author": "MeshBay Team <team@meshbay.org>",
   "homepage": "https://meshbay.org",
diff --git a/packages/meshbay-client/src/main.js b/packages/meshbay-client/src/main.js
index 9ff0069..ab579a1 100644
--- a/packages/meshbay-client/src/main.js
+++ b/packages/meshbay-client/src/main.js
@@ -1701,6 +1701,71 @@ function describeUnreachable(url, error) {
   return `Could not reach ${url}: ${detail}`;
 }
 
+// ── The version gate ────────────────────────────────────────────────────────
+
+/** Compare two dotted versions. -1, 0 or 1; unreadable sorts as equal. */
+function compareVersions(a, b) {
+  const parse = (v) => String(v || '').split('.').map((n) => parseInt(n, 10));
+  const [x, y] = [parse(a), parse(b)];
+  if (x.some(Number.isNaN) || y.some(Number.isNaN)) return 0;
+  for (let i = 0; i < Math.max(x.length, y.length); i++) {
+    const d = (x[i] || 0) - (y[i] || 0);
+    if (d) return d < 0 ? -1 : 1;
+  }
+  return 0;
+}
+
+/**
+ * Refuse to start when this build is older than the hub will talk to.
+ *
+ * The reason this exists rather than letting the handshake do it: the SPA is
+ * served by the hub and picks up a new client on reload, but **this
+ * application ships its own interface**. On the MNP 3.0 flag day an
+ * un-updated one can still sign in, still list groups, and then fail every
+ * connection with `version_too_old` — a refusal in a protocol vocabulary,
+ * surfacing as a node that will not talk, with nothing anyone can act on.
+ *
+ * So the question is asked once, up front, of `/v1/hub/version`, which has
+ * carried `client.minimum` since before there was a client to check it.
+ *
+ * **Unreachable is not too old.** A hub that is down, a laptop with no network,
+ * a captive portal: none of those are a reason to refuse to open the
+ * application, and treating them as one would make an offline start impossible
+ * for ever. Only a definite answer, saying in so many words that this version
+ * is below the minimum, stops anything.
+ */
+async function refuseIfTooOld() {
+  const base = String(config.hubBase || '').replace(/\/+$/, '');
+  if (!base) return false;   // First run: there is no hub to ask yet.
+  let info;
+  try {
+    const r = await fetch(`${base}/v1/hub/version`,
+                          { signal: AbortSignal.timeout(10000) });
+    if (!r.ok) return false;
+    info = await r.json();
+  } catch {
+    return false;
+  }
+  const minimum = info && info.client && info.client.minimum;
+  if (!minimum) return false;
+  const mine = app.getVersion();
+  if (compareVersions(mine, minimum) >= 0) return false;
+
+  const { response } = await dialog.showMessageBox({
+    type: 'warning',
+    title: 'Update required',
+    message: 'This version of MeshBay can no longer connect',
+    detail: `This application is version ${mine}, and ${base} now requires `
+      + `${minimum} or later.\n\nDownload the current version and install it `
+      + 'over this one — your groups, keys and settings are kept.',
+    buttons: ['Download the update', 'Quit'],
+    defaultId: 0,
+    cancelId: 1,
+  });
+  if (response === 0) await shell.openExternal(base);
+  return true;
+}
+
 // ── Lifecycle ───────────────────────────────────────────────────────────────
 
 // One instance. Two would fight over the config file and the secrets blob, and
@@ -1712,7 +1777,10 @@ if (!app.requestSingleInstanceLock()) {
     showFromTray();
   });
 
-  app.whenReady().then(() => {
+  app.whenReady().then(async () => {
+    // Before anything else is built. A window that opens and then cannot
+    // connect is the failure this replaces.
+    if (await refuseIfTooOld()) { app.quit(); return; }
     registerUiProtocol();
     // Before ensureTray: buildTrayMenu reads `nodeService`, which registerBridge
     // assigns, so creating the tray after it means the Start/Stop entry is on
diff --git a/packages/meshbay-common/pyproject.toml b/packages/meshbay-common/pyproject.toml
index 13ade83..6a1370d 100644
--- a/packages/meshbay-common/pyproject.toml
+++ b/packages/meshbay-common/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "meshbay-common"
-version = "0.12.0"
+version = "0.13.0"
 description = "MeshBay shared cryptographic primitives and protocol types"
 requires-python = ">=3.12"
 dependencies = [
diff --git a/packages/meshbay-common/src/meshbay_common/__init__.py b/packages/meshbay-common/src/meshbay_common/__init__.py
index b64a6f2..1aaa269 100644
--- a/packages/meshbay-common/src/meshbay_common/__init__.py
+++ b/packages/meshbay-common/src/meshbay_common/__init__.py
@@ -1,6 +1,6 @@
 """MeshBay common — shared crypto primitives and protocol types."""
 
-__version__ = "0.12.0"
+__version__ = "0.13.0"
 # 0.2: added PING/PONG, and `before`/`has_more` on chat history. Both are
 # additive — an 0.1 peer sends no `before` and gets the newest page, which is
 # what it wanted — so this is a MINOR bump, not a MAJOR one.
@@ -133,5 +133,37 @@ __version__ = "0.12.0"
 # `index_progress` (counters only — see daemon.py `_push_index_progress`), the
 # admin and configuration acks, and the media-metadata replies. The index at
 # rest and file content on the operator's disk are unchanged.
-MNP_VERSION = "2.0"
+# **3.0 (2026-09-09): a transfer needs a lease, and a peer that cannot ask for
+# one is refused at the handshake.**
+#
+# `transfer_open` / `transfer_close` / `transfer_state` carry the lease a
+# download or an upload runs under; `file_req` gains an optional `tr` and
+# `file_upload` gains one beside the `upload_id` already in clear. All three are
+# in clear, like `index_progress` and for the same stated reason: `tr` is
+# opaque, `bytes` and `chunks` are numbers, and there is no filename and no path
+# anywhere in them. Putting one there to make a log line prettier is exactly the
+# trade `groupbox.py` exists to refuse.
+#
+# **The messages are additive; the requirement is not, and that is what makes
+# this MAJOR.** A 2.0 client sends no `tr`, so it is a leaseless reader — and a
+# leaseless reader is either refused as soon as it opens a third file, or it is
+# not refused and transfers outside every cap the operator set. An opt-in switch
+# ("enforce leases only for clients that speak 3.0") leaves that branch
+# reachable on every node, which is finding C6's lesson — a transport that
+# accepted a bare JWT — one feature later. It was already refused once, for chat
+# encryption, on 2026-09-07.
+#
+# Browsing is deliberately **not** leased and never will be: not the poster
+# grid, not the covers, not opening a photo to look at it. That exemption is
+# bounded rather than open (`transfers.LeaselessReads`, two files in flight per
+# session), because an exemption with no bound is the leaseless branch under
+# another name.
+#
+# **What it costs, stated plainly.** The SPA is served by the hub, so a browser
+# picks up the new client on reload. The desktop client ships its own UI, so an
+# un-updated one is locked out — which is why `GET /v1/hub/version` carries
+# `client.minimum` and the client checks it *before* connecting, and says "this
+# version can no longer connect" rather than showing a handshake refusal nobody
+# can act on.
+MNP_VERSION = "3.0"
 MHP_VERSION = "0.1"
diff --git a/packages/meshbay-common/src/meshbay_common/handshake.py b/packages/meshbay-common/src/meshbay_common/handshake.py
index 188a8aa..65b4e85 100644
--- a/packages/meshbay-common/src/meshbay_common/handshake.py
+++ b/packages/meshbay-common/src/meshbay_common/handshake.py
@@ -78,7 +78,12 @@ HANDSHAKE_PREFIX = b"meshbay:mnp:handshake:v1"
 # handshake and then discovering that every message it sends is rejected and
 # every message it receives is unreadable. A stated refusal is a bug report; a
 # chat that quietly does not work is a support case.
-MNP_MIN_SUPPORTED = "2.0"
+# 3.0 (2026-09-09): a transfer runs under a lease, and a 2.x peer cannot ask for
+# one. Admitting it would mean either refusing it later, per file, in a way it
+# has no vocabulary to understand — or serving it outside every cap the operator
+# set, which makes the caps decoration. Neither is honest, so it is refused
+# here, with a code and a sentence.
+MNP_MIN_SUPPORTED = "3.0"
 
 ROLE_CLIENT = "client"
 ROLE_NODE = "node"
diff --git a/packages/meshbay-hub/pyproject.toml b/packages/meshbay-hub/pyproject.toml
index 9e5aace..012824c 100644
--- a/packages/meshbay-hub/pyproject.toml
+++ b/packages/meshbay-hub/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "meshbay-hub"
-version = "0.12.0"
+version = "0.13.0"
 description = "MeshBay Hub — identity authority and group registry server"
 requires-python = ">=3.12"
 dependencies = [
diff --git a/packages/meshbay-hub/src/meshbay_hub/__init__.py b/packages/meshbay-hub/src/meshbay_hub/__init__.py
index b713cf7..117aced 100644
--- a/packages/meshbay-hub/src/meshbay_hub/__init__.py
+++ b/packages/meshbay-hub/src/meshbay_hub/__init__.py
@@ -1,3 +1,3 @@
 """MeshBay Hub — identity authority and group registry."""
 
-__version__ = "0.12.0"
+__version__ = "0.13.0"
diff --git a/packages/meshbay-hub/src/meshbay_hub/api/hub.py b/packages/meshbay-hub/src/meshbay_hub/api/hub.py
index 8223400..a48313d 100644
--- a/packages/meshbay-hub/src/meshbay_hub/api/hub.py
+++ b/packages/meshbay-hub/src/meshbay_hub/api/hub.py
@@ -54,8 +54,21 @@ async def hub_pubkey():
 # user "update to keep using this" before it becomes "this stopped working".
 # Raise `minimum` only for a change a client genuinely cannot survive, and
 # remember store review latency makes that expensive on Android.
-MIN_CLIENT_VERSION = "0.1.0"
-RECOMMENDED_CLIENT_VERSION = "0.1.0"
+# Raised on the MNP 3.0 flag day (2026-09-09). A client older than this speaks
+# MNP 2.x, cannot ask for a transfer lease, and is refused at the node's
+# handshake with `version_too_old` — a refusal in a protocol vocabulary that
+# surfaces as "the node will not talk to me". The client checks this field
+# before connecting and says something a person can act on instead.
+#
+# **This first raise does not reach the clients already installed**, and that is
+# understood rather than overlooked. `package.json` had drifted to "1.0.0" while
+# every other package was on 0.12.0, so an installed client announces a version
+# that sorts *above* this minimum and sails through the gate — then meets the
+# handshake refusal anyway. The operator is updating every client, node and hub
+# by hand for this flag day, which is what makes that acceptable exactly once.
+# The gate is in place for the next one, where it will work as intended.
+MIN_CLIENT_VERSION = "0.13.0"
+RECOMMENDED_CLIENT_VERSION = "0.13.0"
 
 
 @router.get("/version")
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/transport.js b/packages/meshbay-hub/src/meshbay_hub/static/transport.js
index 23823ac..0b2fed5 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/transport.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/transport.js
@@ -261,8 +261,12 @@ window.addEventListener('hashchange', () => {
 // The `v: '0.1'` on every other message in this file is the historical value
 // and is read by nothing; it is left alone deliberately. The range is
 // negotiated once, at the start, not restated per message.
-const MNP_V = '2.0';
-const MNP_V_MIN = '1.0';
+const MNP_V = '3.0';
+// Raised with it on the 3.0 flag day. A node older than 3.0 cannot grant the
+// lease this client opens for every download and upload, so talking to one
+// would mean every transfer failing for a reason the person cannot act on.
+// Refusing it at the handshake says so once, in a sentence.
+const MNP_V_MIN = '3.0';
 
 // Codes a NODE sends us, in its own vocabulary (meshbay_common/handshake.py's
 // check_version): `version_too_old` means *we* are too old for it,
diff --git a/packages/meshbay-hub/tests/test_client_version_gate.py b/packages/meshbay-hub/tests/test_client_version_gate.py
new file mode 100644
index 0000000..69ca062
--- /dev/null
+++ b/packages/meshbay-hub/tests/test_client_version_gate.py
@@ -0,0 +1,141 @@
+"""
+The desktop client refuses to start when the hub will no longer talk to it.
+
+The SPA is served by the hub, so a browser picks up a new client on reload. The
+desktop application **ships its own interface**, so on a flag day an un-updated
+one can still sign in, still list groups, and then fail every connection with
+`version_too_old` — a refusal in a protocol vocabulary, surfacing as a node that
+will not talk, with nothing anyone can act on. §12.3 of
+~/next/improve-downloads.md named this as the thing that had to exist before
+MNP 3.0 could ship.
+
+`compareVersions` and `refuseIfTooOld` are lifted out of `main.js` **as text**
+and executed against a modelled environment, on the rule this repo follows
+elsewhere: model the environment, never the code under test. The rest of
+`test_desktop_shell.py` can only read the source, because there is no npm here
+to launch Electron with; these two are ordinary functions and can be run.
+"""
+
+import json
+import shutil
+import subprocess
+from pathlib import Path
+
+import pytest
+
+CLIENT = Path(__file__).resolve().parents[2] / "meshbay-client"
+MAIN = CLIENT / "src" / "main.js"
+
+pytestmark = pytest.mark.skipif(
+    shutil.which("node") is None or not MAIN.exists(),
+    reason="node or the desktop client sources are not available")
+
+
+def _lift(name: str) -> str:
+    src = MAIN.read_text()
+    cut = src[src.index(name):]
+    return cut[:cut.index("\n}\n") + 2]
+
+
+def _run(tmp_path, *, mine="1.1.0", hub_base="https://hub.example",
+         answer=None, status=200, throws=False):
+    """Drive the gate against one hub.
+
+    `answer` is what `/v1/hub/version` returns; None means the field is absent
+    entirely, which is what an older hub sends.
+    """
+    script = tmp_path / "gate.mjs"
+    script.write_text(f"""
+const out = {{ dialogs: 0, opened: null }};
+const config = {{ hubBase: {json.dumps(hub_base)} }};
+const app = {{ getVersion: () => {json.dumps(mine)} }};
+const dialog = {{
+  showMessageBox: async () => {{ out.dialogs += 1; return {{ response: 0 }}; }},
+}};
+const shell = {{ openExternal: async (u) => {{ out.opened = u; }} }};
+globalThis.fetch = async () => {{
+  if ({json.dumps(throws)}) throw new Error('unreachable');
+  return {{ ok: {json.dumps(status)} === 200,
+           json: async () => ({json.dumps(answer)}) }};
+}};
+""" + _lift("function compareVersions") + _lift("async function refuseIfTooOld") + """
+out.refused = await refuseIfTooOld();
+out.compare = [
+  compareVersions('1.0.0', '1.1.0'),
+  compareVersions('1.1.0', '1.1.0'),
+  compareVersions('1.2.0', '1.1.0'),
+  compareVersions('1.10.0', '1.9.0'),
+  compareVersions('1.1', '1.1.0'),
+  compareVersions('nonsense', '1.1.0'),
+];
+console.log(JSON.stringify(out));
+""")
+    proc = subprocess.run(["node", str(script)], capture_output=True, text=True)
+    assert proc.returncode == 0, proc.stderr
+    return json.loads(proc.stdout)
+
+
+OK = {"client": {"minimum": "1.1.0", "recommended": "1.1.0"}}
+
+
+# ── the comparison ──────────────────────────────────────────────────────────
+
+def test_versions_compare_by_number_and_not_by_string(tmp_path):
+    """`1.10.0` is newer than `1.9.0`, which string comparison gets backwards —
+    and that mistake locks out exactly the people who did update."""
+    assert _run(tmp_path, answer=OK)["compare"] == [-1, 0, 1, 1, 0, 0]
+
+
+# ── the gate ────────────────────────────────────────────────────────────────
+
+def test_a_client_older_than_the_minimum_is_stopped(tmp_path):
+    out = _run(tmp_path, mine="1.0.0", answer=OK)
+    assert out["refused"] is True
+    assert out["dialogs"] == 1, "it stopped without saying why"
+    assert out["opened"] == "https://hub.example", (
+        "the offer to download the update led nowhere")
+
+
+def test_a_current_client_starts_normally(tmp_path):
+    out = _run(tmp_path, mine="1.1.0", answer=OK)
+    assert out["refused"] is False
+    assert out["dialogs"] == 0
+
+
+def test_a_newer_client_is_not_stopped(tmp_path):
+    """A development build ahead of the hub is not a reason to refuse to open
+    the application."""
+    assert _run(tmp_path, mine="2.0.0", answer=OK)["refused"] is False
+
+
+def test_an_unreachable_hub_is_not_too_old(tmp_path):
+    """A hub that is down, a laptop with no network, a captive portal. Treating
+    any of those as "you are out of date" would make an offline start
+    impossible for ever, and would do it at the worst moment."""
+    assert _run(tmp_path, mine="1.0.0", throws=True)["refused"] is False
+    assert _run(tmp_path, mine="1.0.0", status=503, answer=OK)["refused"] is False
+
+
+def test_a_hub_that_states_no_minimum_stops_nothing(tmp_path):
+    """An older hub answers without the field. Absent must read as "no opinion",
+    never as a refusal."""
+    assert _run(tmp_path, mine="0.0.1", answer={"hub": "1.2.3"})["refused"] is False
+
+
+def test_a_first_run_with_no_hub_yet_is_not_stopped(tmp_path):
+    """There is nothing to ask, and the first-run screen is where the address
+    gets typed."""
+    assert _run(tmp_path, mine="0.0.1", hub_base="", answer=OK)["refused"] is False
+
+
+# ── where it is called ──────────────────────────────────────────────────────
+
+def test_the_gate_runs_before_the_window_is_built():
+    """A window that opens and then cannot connect is the failure this
+    replaces, so the order is the whole point."""
+    src = MAIN.read_text()
+    ready = src[src.index("app.whenReady().then("):]
+    ready = ready[:ready.index("createWindow();")]
+    assert "await refuseIfTooOld()" in ready, (
+        "the version check does not run before the window is created")
+    assert "app.quit()" in ready
diff --git a/packages/meshbay-hub/tests/test_versions_agree.py b/packages/meshbay-hub/tests/test_versions_agree.py
new file mode 100644
index 0000000..4466c93
--- /dev/null
+++ b/packages/meshbay-hub/tests/test_versions_agree.py
@@ -0,0 +1,74 @@
+"""
+Every package in this repository carries the same version.
+
+They are built, deployed and updated together — hub, node, common and the
+desktop client — so a version that differs is not a statement about that
+package, it is a mistake nobody has noticed yet.
+
+**Found on 2026-09-09, on the MNP 3.0 flag day.** `meshbay-client`'s
+`package.json` had drifted to `1.0.0` while every Python package was on
+`0.12.0`. That was invisible until the hub started publishing a minimum client
+version and the client started comparing itself against it — at which point an
+installed client announcing `1.0.0` sorted *above* a minimum of `0.13.0` and
+walked straight through the gate meant to stop it. A version nobody reads is
+free to be wrong; the moment something compares it, it is load-bearing.
+"""
+
+import json
+import re
+from pathlib import Path
+
+import pytest
+
+ROOT = Path(__file__).resolve().parents[3]
+PACKAGES = ROOT / "packages"
+
+
+def _python_versions() -> dict[str, str]:
+    found = {}
+    for pyproject in sorted(PACKAGES.glob("*/pyproject.toml")):
+        m = re.search(r'^version = "([^"]+)"', pyproject.read_text(), re.M)
+        if m:
+            found[f"{pyproject.parent.name}/pyproject.toml"] = m.group(1)
+    for init in sorted(PACKAGES.glob("*/src/*/__init__.py")):
+        m = re.search(r'^__version__ = "([^"]+)"', init.read_text(), re.M)
+        if m:
+            found[f"{init.parent.name}/__init__.py"] = m.group(1)
+    return found
+
+
+def _client_version() -> str | None:
+    pkg = PACKAGES / "meshbay-client" / "package.json"
+    if not pkg.exists():
+        return None
+    return json.loads(pkg.read_text()).get("version")
+
+
+@pytest.mark.skipif(not PACKAGES.is_dir(), reason="package layout not present")
+def test_every_package_carries_the_same_version():
+    versions = _python_versions()
+    assert versions, "no package versions found at all — has the layout moved?"
+    client = _client_version()
+    if client is not None:
+        versions["meshbay-client/package.json"] = client
+    distinct = sorted(set(versions.values()))
+    assert len(distinct) == 1, (
+        "packages disagree about the version: "
+        + ", ".join(f"{k}={v}" for k, v in sorted(versions.items())))
+
+
+@pytest.mark.skipif(not PACKAGES.is_dir(), reason="package layout not present")
+def test_the_hub_will_not_refuse_the_client_it_ships_with():
+    """`MIN_CLIENT_VERSION` is compared against a client's own version, so a
+    minimum above the version being built would lock out the very build being
+    released — the one failure this field can cause that nobody would think to
+    test for by hand."""
+    from meshbay_hub.api.hub import MIN_CLIENT_VERSION
+
+    client = _client_version()
+    if client is None:
+        pytest.skip("desktop client sources not present")
+    as_numbers = lambda v: [int(n) for n in v.split(".")]   # noqa: E731
+    assert as_numbers(MIN_CLIENT_VERSION) <= as_numbers(client), (
+        f"the hub requires client {MIN_CLIENT_VERSION} but this tree builds "
+        f"{client}")
diff --git a/packages/meshbay-node/pyproject.toml b/packages/meshbay-node/pyproject.toml
index 7cd0ca9..aa13d1e 100644
--- a/packages/meshbay-node/pyproject.toml
+++ b/packages/meshbay-node/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "meshbay-node"
-version = "0.12.0"
+version = "0.13.0"
 description = "MeshBay Node — local file host, streaming server, and group daemon"
 requires-python = ">=3.12"
 dependencies = [
diff --git a/packages/meshbay-node/src/meshbay_node/__init__.py b/packages/meshbay-node/src/meshbay_node/__init__.py
index 1bc8c9f..182ed32 100644
--- a/packages/meshbay-node/src/meshbay_node/__init__.py
+++ b/packages/meshbay-node/src/meshbay_node/__init__.py
@@ -1,3 +1,3 @@
 """MeshBay Node — local file host, streaming server, and group daemon."""
 
-__version__ = "0.12.0"
+__version__ = "0.13.0"
diff --git a/packages/meshbay-node/src/meshbay_node/transfers.py b/packages/meshbay-node/src/meshbay_node/transfers.py
index dd5da5c..2185547 100644
--- a/packages/meshbay-node/src/meshbay_node/transfers.py
+++ b/packages/meshbay-node/src/meshbay_node/transfers.py
@@ -403,3 +403,86 @@ class TransferSlots:
         return " ".join(
             f"{kind[0]}={p[kind]['in_use']}/{p[kind]['cap']}"
             f"(q{p[kind]['queued']})" for kind in KINDS)
+
+
+# ── Reads that carry no lease ───────────────────────────────────────────────
+
+# How many distinct files one session may be reading at once without a lease.
+#
+# Browsing a group is never subject to a transfer slot — not the poster grid,
+# not the covers, not opening a photo or a PDF to look at it. A member must be
+# able to browse a group that is at capacity exactly as they browse an idle one.
+# That is a requirement, and §3.4 of ~/next/improve-downloads.md satisfies it
+# structurally: a transfer is what the transfers widget shows, and nothing else
+# takes a slot.
+#
+# But "not leased" cannot mean "unbounded", or a client that simply omits `tr`
+# transfers outside every cap and the caps are decoration. Two, because a viewer
+# looks at *one* file — one photo, one document — and the second is there so
+# that prefetching the next photo stays possible.
+#
+# Deliberately a count of files and not a byte budget: a RAW photo out of a
+# camera is 60-80 MB and is browsing, a 40 MB archive is a download, and no
+# size threshold separates them. What separates them is which function asked.
+#
+# What it costs, stated plainly: a client that lies — labelling a bulk download
+# as a view — gets two files at a time instead of its member cap. That is the
+# residual, it is bounded, it is audited, and it is the same kind of statement
+# as the cap itself. **This is a fairness control among cooperating clients**,
+# not a defence against a member determined to saturate a node's disk. The
+# answer to that member is `member revoke`.
+MAX_LEASELESS_IN_FLIGHT = 2
+
+# A leaseless read has no "close" message, so it ends when the last chunk goes
+# out — or, when a viewer is closed mid-file and simply stops asking, when it
+# has been quiet this long.
+LEASELESS_IDLE_SECS = 60
+
+
+class LeaselessReads:
+    """
+    The files one session is reading without a lease, and the bound on them.
+
+    Per session rather than per member: this is not a resource pool, it is a
+    ceiling on what one connection can do while claiming to be browsing. A
+    member with three tabs open is browsing in three tabs, which is fine.
+    """
+
+    def __init__(self, limit: int = MAX_LEASELESS_IN_FLIGHT,
+                 idle: float = LEASELESS_IDLE_SECS) -> None:
+        self.limit = limit
+        self.idle = idle
+        self._seen: dict[str, float] = {}
+
+    def admit(self, file_id: str, now: float | None = None) -> bool:
+        """May this session read `file_id` without a lease right now?
+
+        True for a file it is already reading, whatever the count: refusing a
+        chunk halfway through a photo because the limit moved would be worse
+        than never having admitted it.
+        """
+        when = time.monotonic() if now is None else now
+        self._expire(when)
+        if file_id in self._seen:
+            self._seen[file_id] = when
+            return True
+        if len(self._seen) >= self.limit:
+            return False
+        self._seen[file_id] = when
+        return True
+
+    def finish(self, file_id: str) -> None:
+        """The last chunk went out; the slot is free at once rather than in a
+        minute."""
+        self._seen.pop(file_id, None)
+
+    def _expire(self, now: float) -> None:
+        # A viewer closed mid-file stops asking and says nothing. Without this
+        # the session would carry two dead entries and refuse every later
+        # preview, which is the bound turning into a bug.
+        for file_id, last in list(self._seen.items()):
+            if now - last > self.idle:
+                del self._seen[file_id]
+
+    def __len__(self) -> int:
+        return len(self._seen)
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 9de799c..507650a 100644
--- a/packages/meshbay-node/src/meshbay_node/transport/webrtc_server.py
+++ b/packages/meshbay-node/src/meshbay_node/transport/webrtc_server.py
@@ -430,6 +430,11 @@ class WebRTCPeerSession:
         self._admin_ops: dict[str, dict] = {}   # op_id → pending admin operation
         # Uploads in progress live in the group context, not here: see
         # `_partial_uploads` and `uploads.py`.
+        #
+        # Leaseless reads, though, *are* this connection's: the bound is on what
+        # one session may do while claiming to be browsing, not a pool shared
+        # between them. Three tabs open is browsing in three tabs.
+        self._leaseless = transfers_mod.LeaselessReads()
         # Diagnostics only (_WEBRTC_TRACE): when the last DataChannel message
         # arrived, so the heartbeat can report silence duration.
         self._last_msg_at: float = 0.0
@@ -3689,6 +3694,25 @@ class WebRTCPeerSession:
             self._send({"type": "error", "detail": "File not on disk"})
             return
 
+        # A real index entry, asked for without a lease: browsing, or a client
+        # helping itself to the whole library outside every cap.
+        #
+        # Both look identical here — which is why the bound is a small count of
+        # files rather than a judgement about what the read is for. Thumbnails,
+        # posters and cover art never reach this line: they resolve through
+        # `_try_serve_thumbnail` above, out of a cache the node built itself,
+        # and are never leased, never counted, never queued.
+        if not tr:
+            if not self._leaseless.admit(str(file_id)):
+                self._send({
+                    "type": "error",
+                    "detail": "Too many files open at once without a transfer. "
+                              "Download this one instead of previewing it.",
+                    "code": "transfer_required",
+                    "file_id": file_id,
+                })
+                return
+
         log.debug("dl: req file=%s chunk=%s buffered=%s",
                  file_id[:12], chunk_index,
                  getattr(self._channel, "bufferedAmount", "?"))
@@ -3713,6 +3737,11 @@ class WebRTCPeerSession:
                  getattr(self._channel, "bufferedAmount", "?"))
         if chunk_index == 0:
             self._audit("file_download", entry.name)
+        # The last chunk is the only "close" a leaseless read has. Without this
+        # the session carries the entry until it goes idle, and the person who
+        # just looked at two photos cannot look at a third for a minute.
+        if not tr and (chunk_index + 1) * CHUNK_SIZE >= entry.size:
+            self._leaseless.finish(str(file_id))
 
     @staticmethod
     async def _fetch_and_cache_poster(media_cache, tmdb_client, poster_path: str | None) -> str | None:
diff --git a/packages/meshbay-node/tests/test_leaseless_reads.py b/packages/meshbay-node/tests/test_leaseless_reads.py
new file mode 100644
index 0000000..70fd24f
--- /dev/null
+++ b/packages/meshbay-node/tests/test_leaseless_reads.py
@@ -0,0 +1,85 @@
+"""
+Browsing is never subject to a transfer slot — and is not unbounded either.
+
+**Operator decision, 2026-09-08:** a member must be able to browse a group that
+is at capacity exactly as they browse an idle one. Not the poster grid, not the
+covers, not opening a photo or a PDF to look at it. §3.4 of
+~/next/improve-downloads.md satisfies that structurally: a transfer is what the
+transfers widget shows, and nothing else takes a slot.
+
+But "not leased" cannot mean "unbounded". With MNP 3.0 making leases
+compulsory, a client that simply omits `tr` would otherwise transfer outside
+every cap, and the caps would be decoration — the leaseless branch left
+reachable is finding C6's lesson (a transport that accepted a bare token) one
+feature later.
+
+So a leaseless read is bounded by a small count of *files in flight*, not by
+bytes: a RAW photo out of a camera is 60–80 MB and is browsing, a 40 MB archive
+is a download, and no size threshold separates them. What separates them is
+which function asked.
+"""
+
+from meshbay_node.transfers import (
+    LEASELESS_IDLE_SECS, MAX_LEASELESS_IN_FLIGHT, LeaselessReads,
+)
+
+
+def test_a_viewer_looking_at_one_file_is_never_refused():
+    reads = LeaselessReads()
+    for chunk in range(20):
+        assert reads.admit("photo-1", now=float(chunk)) is True
+
+
+def test_a_second_file_is_allowed_so_prefetching_stays_possible():
+    """One is what a viewer needs; two is so the photo viewer can fetch the
+    next one while showing this one."""
+    reads = LeaselessReads()
+    assert reads.admit("photo-1", now=0.0) is True
+    assert reads.admit("photo-2", now=0.0) is True
+
+
+def test_a_third_file_is_refused():
+    reads = LeaselessReads()
+    reads.admit("a", now=0.0)
+    reads.admit("b", now=0.0)
+    assert reads.admit("c", now=0.0) is False
+
+
+def test_a_file_already_being_read_is_never_cut_off():
+    """Even once the limit is reached. Refusing a chunk halfway through a photo
+    because the count moved would be worse than never having admitted it — the
+    viewer would show half an image and no error anyone can act on."""
+    reads = LeaselessReads()
+    reads.admit("a", now=0.0)
+    reads.admit("b", now=0.0)
+    assert reads.admit("c", now=0.0) is False
+    assert reads.admit("a", now=1.0) is True
+
+
+def test_finishing_one_frees_it_at_once():
+    """The last chunk is the only "close" a leaseless read has. Waiting for the
+    idle timeout instead would mean somebody who looked at two photos cannot
+    look at a third for a minute."""
+    reads = LeaselessReads()
+    reads.admit("a", now=0.0)
+    reads.admit("b", now=0.0)
+    reads.finish("a")
+    assert reads.admit("c", now=0.0) is True
+
+
+def test_a_viewer_closed_mid_file_does_not_hold_its_place_for_ever():
+    """It stops asking and says nothing — there is no message for "I closed the
+    tab". Without the idle expiry the session would carry two dead entries and
+    refuse every later preview, which is the bound turning into a bug."""
+    reads = LeaselessReads()
+    reads.admit("a", now=0.0)
+    reads.admit("b", now=0.0)
+    assert reads.admit("c", now=1.0) is False
+    assert reads.admit("c", now=LEASELESS_IDLE_SECS + 2) is True
+
+
+def test_the_bound_is_two():
+    """Stated here so that changing it is a decision rather than a typo: it is
+    the number §3.4.1 argues for, and the argument is about viewers, not about
+    tuning."""
+    assert MAX_LEASELESS_IN_FLIGHT == 2
-- 
cgit v1.2.3