XERK-263: spool the migration relay's transcript bundle to disk

[xerhab]

Closes XERK-263.

The problem

POST /api/agents/<host>/migrations/<id>/blob read a moved session's whole gzipped transcript bundle into the heap (readRawBody, capped at 65 MiB) and then retained it on the migration record for the entire importing phase, until the target agent pulled it back down. The hub runs at mem_limit: 256m, and the operator can start two moves with two clicks of the Sessions page's Move control.

Measured A/B on a real hub, one 64 MiB relay:

	RSS before	during upload	after the target's GET
main (be96f6b)	40.1 MiB	—	171.1 MiB, and it stays there
this branch	40.6 MiB	55.9 MiB	63.3 MiB, nothing retained

Seven concurrent 64 MiB bundles now sit at ~74 MiB RSS and fall back to 62 MiB idle. The remaining ~16–23 MiB is allocator high-water that varies run to run with no code difference — the 65 MiB retention is gone, which is the thing the ticket is about.

The change

The relay streams instead of buffering:

• spoolRawBody(req, cap, filePath) writes the body straight to a file, reading with backpressure so a fast uploader can't just queue it all in the write buffer. It keeps readRawBody's over-cap drain rule, and removes the partial file before its rejection lands.
• The bundle spools to MIGRATE_SPOOL_DIR (/data/migrations, on the volume /data already needs — no compose change), keyed on the hub-minted migration id, never the URL segment.
• The record keeps blobPath/blobSize, not bytes. The target's GET streams the file back.
• dropMigrationBlob() unlinks on every terminal path — handoff, timeout, source session gone, MIGRATIONS_MAX eviction, retirement. Safe mid-download: the unlink drops the name, the reader's fd keeps the bytes.
• Boot sweeps the spool dir. The records are in memory, so a restart abandons every in-flight move and anything left belongs to no one. It deletes only names matching the shape it writes (see below for why that matters).

The wire contract is untouched — octet-stream in, octet-stream out. No agent change; older agents are unaffected. The tar-member ../absolute guards stay on the target, where the ticket wanted them.

Merged with XERK-266, which hardened this same route on main

XERK-266 landed while this was in QA: it scopes the POST to the migration's own source host and the GET to its target host, and makes every POST refusal answer the same 404, so no response a non-source can't also get names the source to anyone holding the migration id. Both sides are kept, and where they met XERK-266's doctrine wins on the shape of every reply — the bundle already uploading guard, the empty-bundle refusal and source session gone all answer that uniform 404 rather than the 409/400 they had here.

A spool write failure does too, where this branch answered 500. It is deliberately not a second enumerated exception beside the 413: a distinct status would name the source the moment the hub's disk misbehaved. Nothing is lost — the agent only logs the reply, the record still carries transcript bundle spool failed for the operator, and the detail goes to the hub log where it's actionable. That also subsumes the path-leak fix from earlier in this branch, since the body is now a fixed string. Verified on a real hub: a wrong host, an unknown id and an unwritable spool are byte-identical on the wire.

One addition beyond the ticket's primary direction

Spooling moves the pressure off the heap and onto /data, which the archive shares. So MIGRATE_INFLIGHT_MAX (4) bounds how many moves can hold a bundle at once — the ticket's "secondary option", taken as a complement rather than an alternative. It is enforced where a move starts, not on the relay upload: hub-agent.py's _migration_upload is best-effort with no retry, so refusing an upload strands the migration, while refusing the operator's click is a message the web Move control already shows.

What the ticket asked for that isn't here

Dropping XERK-258's refusable:false carve-out. XERK-258 is not on main and has no branch (it's being worked in parallel), so there is nothing here to remove — that cleanup belongs to whoever lands it.

QA

Three adversarial passes (~/.claude/agents/qa.md). The first returned FAIL and was right to.

Defects it found in my first attempt, all fixed here:

1. Silent truncation, and a false success. A spool write error surfacing during the final flush was swallowed — out.end(() => resolve(len)) discards the callback's error, and settled was already set so the error handler was a no-op too. The hub answered 200 {"ok":true} for a truncated bundle, advanced to importing, queued importSession, and logged nothing; the move then died at the 5-minute timeout with no diagnostic. Repro on a spool FS with 12 KiB free: 40960 bytes -> 200, 28672 on disk. Now: 500, no file, phase=failed, no import queued. spoolRawBody settles inside the end callback, and resolves on close — the descriptor is still open in the end callback, so a close(2) failure would land on the same swallowed side.
2. A 200 whose Content-Length didn't describe it. The GET read blobPath at handler time but blobSize inside the async open callback; a concurrent settle zeroes both, and since the unlink leaves the fd valid the hub sent the whole body under Content-Length: 0 — which the agent's urllib reads as an empty bundle. 296/300 in QA's race harness. Both fields are now snapshotted before the first async hop: 300/300 correct, and 40/40 through the real Python client.
3. The boot sweep deleted every file it found. MIGRATE_SPOOL_DIR is deployment config; pointed at /data by a one-word compose slip, boot deleted state.json and devices.json (verified). It now matches /^[0-9a-f]{16}\.bin$/.
4. The spool-failure 500 leaked the hub's absolute filesystem path; it goes to the log now.
5. The bundle already uploading 409 didn't drain the body, so the losing uploader got a socket error instead of the refusal.

The second pass returned PARTIAL — not for the product code, which held under fresh attack, but because my regression test for #2 caught a reintroduced bug only 1 run in 5. It timed the settle from outside with a 1 ms sleep, and took a 404 early-out when the drop won. It now lands the settle in the window by construction, on the read stream's open event, and asserts that it landed: 12/12 caught.

The third pass returned PASS. Its remaining nit is taken inline: requestRaw had no timeout, so an unanswerable route hung the suite until the CI job died. The guard moved into the shared helper.

Verified in that final pass, on real hubs over real sockets: the ENOSPC sweep, EISDIR, the over-cap boundary (413 within RAW_BODY_DRAIN_SLACK, socket cut past it — inherited from readRawBody; a conforming agent can't reach it, since it caps its own bundle 1 MiB below the hub's), aborted uploads, empty bodies, concurrent 32 MiB uploads, source session gone, seven successive 64 MiB relays, the in-flight cap with a real handoff freeing its slot, and — closing the biggest gap from pass 1 — the real hub-agent.py legs: _pack_transcript → _migration_upload → _migration_download → _unpack_transcript byte-identical, torn tail dropped, and a malicious tar refused with unsafe tar member '../../…' and nothing written.

Not verified, stated plainly: no move has ever been completed by a live agent pair — the command loop, tmux launch, worktree creation and claude --resume were never driven. That is a standing gap in the migration feature, not in this diff. close(2) failures are structurally closed but not exercised (local volume). RSS was measured unconstrained, not under a real 256 MiB cgroup. Android/glasses/veiller/the browser UI were read, not run.

CI

Semgrep flagged path.join(MIGRATE_SPOOL_DIR, ...) as a possible traversal. It wasn't — the only caller passes the hub-minted m.id — but the function documented that as a fact about its caller rather than enforcing it, which is the kind of comment that goes stale when a second caller appears. migrationSpoolPath now validates the id against the shape startMigration mints and throws otherwise, so the nosemgrep sits behind a real check (the same idiom archive.js uses for the same rule). Verified with CI's exact invocation locally: 0 findings.

Tests

New cases in turma/tests/server.test.js: spool-on-disk on the happy path, the empty body, the over-cap 413 (sized cap + 4096, well inside the drain slack so it can't sit one byte from flaking), the concurrent-upload guard (which no test caught — removing it was a clean mutation escape), an unwritable spool, the download/settle race, the sweep's selectivity, the boot sweep, the in-flight cap freeing its slot, and the spool-path guard. 1095 JS + 1288 Python green.

One test-hygiene fix the merge exposed: the in-flight-cap case left the fleet at MIGRATE_INFLIGHT_MAX, so every later test that started a move got a 503. It settles its own moves on the way out now.

Findings routed elsewhere

• XERK-271 — filed, then closed as already fixed. I raised it from a code read of the old base: Android's FleetViewModel.run() rendered every non-2xx as "✗ hub unreachable", so the new 503 would have lost its wording on the phone. XERK-264 had already landed the same fix on main (hubErrorMessage reads the {error} off an HttpException or a typed Response), so the merge closed it for free. The ticket is closed with that explanation and the PARITY.md gap line I'd added is removed — the entry now records that Move's refusals reach the operator in the hub's own words like every other command.
• Accepted limit, not fixed: a second hub sharing one MIGRATE_SPOOL_DIR sweeps the first's in-flight bundles at boot. One hub per volume is already assumed by state.json, devices.json and the archive index; if that changes, the spool isn't where to start.
• Kept but honestly described: ordering the empty-body unlink before the response closes a real ordering hazard, but QA could not win the race in 40/40 attempts against either build. It's hardening, not a demonstrated bug fix.