create-walle 0.10.2 → 0.10.3

package/template/coding-task-manager/lib/agent-bundle/push.js

@@ -0,0 +1,717 @@
+'use strict';
+
+/**
+ * WP-3 (docs/remote-agent-skills-bundles-2026-10-25.html §5 D-4/D-6, §6.5): the HUB side of the
+ * agent-skill push — build the bundle for the box's platform, ask which blobs it lacks, upload
+ * those, then PUT the manifest.
+ *
+ * Three rules drive every decision here:
+ *   D-4  push once per hash, only missing blobs. The `POST /missing` round trip is the authority (the
+ *        box may have garbage-collected a tree WP-5 dropped), so it runs on EVERY push — including a
+ *        push whose tree this process has already delivered.
+ *   D-6  skills NEVER block a session. `budgetMs` (10 s by default) bounds the CALLER'S WAIT — not
+ *        the push (rev 3, D-11 below) — and any failure (4xx/5xx, a build error, an unreadable blob)
+ *        comes back as `{ok:false, code, detail}`: the caller records it on the machine row and
+ *        forwards the create exactly as it would have without skills.
+ *   D-5  the manifest carries ONLY `{schema, treeHash, entries}`. `blobsByHash` is hub-local by
+ *        construction (build.js says so) and `items` / `heldBack` / `warnings` are hub-side reporting
+ *        that must never ride the wire — they are not part of the box's manifest contract.
+ *
+ * Rev 3 (docs/remote-skills-hub-peer-identity-2026-10-26.html §5 D-11/D-12/D-13, §6.3) — a push
+ * outlives the create's wait, one push per box, and every result says which phase cost what:
+ *   D-11  the push's lifetime is decoupled from the caller's wait. On budget expiry `pushBundleToBox`
+ *         resolves `{ok:false, code:'agent_bundle_push_timeout', continuing:true, phase, timings}`
+ *         and the push is NOT aborted — it runs on to completion or to `BACKGROUND_CEILING_MS`
+ *         (120 s, `options.ceilingMs` in tests), whichever is first. The push's final result goes to
+ *         `options.onLateResult(result)` EXACTLY ONCE, and only when THIS call timed out and THIS call
+ *         STARTED the push (a joined caller never gets a late result — the starter's caller records the
+ *         outcome once). A throwing `onLateResult` is REPORTED with `console.warn`, never left as an
+ *         unhandled rejection. The work promise never rejects.
+ *   D-12  single-flight per box: a call while a push to the same `instanceId` is in flight starts
+ *         nothing — it waits on that push with its OWN budget and returns its result (or its own
+ *         timeout) with `joined:true`. At most one upload per box at a time; a joiner costs zero
+ *         requests. Configuration failures (no credential / fetch / url) return before any of this.
+ *   D-13  every result (ok, failure, timeout snapshot, late, ceiling) carries
+ *         `timings: {buildMs, missingMs, readMs, uploadMs, manifestMs, totalMs, batches, batchesDone}`
+ *         measured with `options.monotonicNow` (default `performance.now`), rounded to integer ms and
+ *         summed across the D-4 409 retry. A batch POST or an oversize PUT is ONE batch.
+ *
+ * Error codes (the closed set; `detail` is a short message and never carries a token, a bearer or
+ * any file contents):
+ *   agent_bundle_build_failed    the bundle could not be built (or built into something unusable)
+ *   agent_bundle_push_timeout    the caller's budget expired (D-11: the push keeps running until its
+ *                                ceiling) — `continuing:true` on the budget result, `ceiling:true` on
+ *                                the ceiling result
+ *   agent_bundle_push_http_<n>   the box answered a non-2xx status
+ *   agent_bundle_push_network    the transport failed, or nothing could be dialled
+ *   agent_bundle_push_no_credential  no peer credential is configured (a configuration error)
+ *
+ * A non-2xx push also carries the BOX's own reason, when it named one, as `boxCode` on the failure
+ * result (D-4, docs/remote-skills-hub-peer-identity-2026-10-26.html §5 D-4/§6). `code` is unchanged —
+ * a `403 {"code":"agent_bundle_peer_unidentified"}` is still `agent_bundle_push_http_403` — and the
+ * `boxCode` key is ABSENT when the body had no code, or a code that is not a snake_case token.
+ *
+ * Request count, not concurrency, is the scarce resource. The box charges every request to one
+ * `peer` rate bucket keyed by the HUB (lib/auth-rate-limit.js:16-24: burst 120, 600/min), and that
+ * same key carries the hub's live keystroke/prompt relay for every box session — so a per-blob upload
+ * of a real ~585-blob home (S-7, docs/remote-skills-hub-peer-identity-2026-10-26.html §1.3, rev 2)
+ * answers 429 at request 125 and starves the relay while it runs. WP-4 uploads in BATCHES instead
+ * (D-6/D-7, this doc rev 2): blobs are packed in order into groups of at most BATCH_MAX_RAW_BYTES
+ * (4 MiB) raw bytes and POSTed one group at a time — the REAPI `FindMissingBlobs` + `BatchUpdateBlobs`
+ * shape, with the existing per-blob `PUT /blobs/<hex>` kept as the ByteStream analogue for a single
+ * oversized blob. A first push therefore costs `2 + ⌈bytes/4 MiB⌉ + (oversize blobs)` requests; the
+ * per-process cache is described at `_pushedTrees` below.
+ */
+
+const fsp = require('fs/promises');
+const os = require('os');
+
+const { buildAgentBundle } = require('./build');
+
+const DEFAULT_BUDGET_MS = 10_000;
+/**
+ * D-7: the raw-byte budget of ONE batch request. Base64 grows it to ~5.4 MiB, under the box's D-6
+ * `MAX_BATCH_BODY_BYTES` of 8 MiB. A single blob larger than this goes alone through the existing
+ * per-blob PUT (the REAPI ByteStream analogue).
+ */
+const BATCH_MAX_RAW_BYTES = 4 * 1024 * 1024;
+const MAX_DETAIL_CHARS = 200;
+const HEX_RE = /^[0-9a-f]{64}$/;
+/**
+ * D-4 (docs/remote-skills-hub-peer-identity-2026-10-26.html §6): the shape a box's own reason may
+ * take. The box answers a non-2xx with `{code}` — a snake_case token — and `code` alone cannot say
+ * WHY (a 403 is "peer unidentified" or a dozen other refusals). Kept only if it matches this form,
+ * so nothing arbitrary (a path, a sentence, an uppercase word) can ride into the machine row.
+ */
+const BOX_CODE_RE = /^[a-z][a-z0-9_]{0,79}$/;
+/** build.js's `computeTreeHash` form. A hash the box would reject on format is a local build failure. */
+const TREE_HASH_RE = /^sha256:[0-9a-f]{64}$/;
+
+const CODE_BUILD_FAILED = 'agent_bundle_build_failed';
+const CODE_TIMEOUT = 'agent_bundle_push_timeout';
+const CODE_NETWORK = 'agent_bundle_push_network';
+const CODE_NO_CREDENTIAL = 'agent_bundle_push_no_credential';
+
+/**
+ * Per-process push cache: instanceId -> Set<treeHash> of trees this process has successfully
+ * delivered to that box.
+ *
+ * CHOICE (the brief leaves this open): a cache HIT still runs the `POST /missing` check — that is
+ * the box's own truth and the only thing that can reveal a garbage-collected tree — and it skips
+ * the manifest PUT ONLY when the check came back EMPTY. The reasoning: a box's hub pointer moves
+ * only when THIS hub successfully PUTs a manifest for that peer, and `(instanceId, treeHash)` is the
+ * cache key, so "we pushed T to box B in this process and B is still missing nothing" means B's
+ * pointer already names T and its tree directory is protected by WP-5's pointer rule. That is
+ * exactly AC-3a ("the second create with no change uploads 0 blobs and 0 manifest bytes beyond the
+ * missing check"). A box that lost the tree or moved its pointer is a non-empty answer, and then the
+ * full push runs as usual — the skip can never hide a missing tree.
+ */
+const _pushedTrees = new Map();
+
+/**
+ * D-11 (rev 3): how long a push may run on after the caller stopped waiting, before its
+ * AbortController is aborted and the push reports a ceiling failure. 11.3 MB on the wire / 120 s ≈
+ * 94 KB/s, so this covers any link the relay itself is usable on; `options.ceilingMs` overrides it.
+ */
+const BACKGROUND_CEILING_MS = 120_000;
+
+/**
+ * D-12 (rev 3): single-flight per box — `instanceId -> {promise, progress, controller}` for every push
+ * this process has running. A second call for the same box JOINS the running push instead of sending
+ * a second copy of the bundle through the one `peer` bucket the relay shares.
+ */
+const _inFlight = new Map();
+
+/** Test seam: the cache is module state and must never leak between tests. D-12: in-flight pushes too. */
+function _resetPushCacheForTests() {
+  _pushedTrees.clear();
+  for (const entry of _inFlight.values()) {
+    try {
+      entry.controller.abort();
+    } catch {
+      // expected: an already-aborted controller
+    }
+  }
+  _inFlight.clear();
+}
+
+/** D-13: the eight numbers every result carries, in one place. */
+function _newTimings() {
+  return {
+    buildMs: 0, missingMs: 0, readMs: 0, uploadMs: 0, manifestMs: 0, totalMs: 0, batches: 0, batchesDone: 0,
+  };
+}
+
+function _defaultMonotonicNow() {
+  return performance.now();
+}
+
+/**
+ * D-13 (rev 3): the per-push progress — the phase the push is in, the batch counters, and the timings —
+ * read by a budget/ceiling snapshot while the push is still running. `measure` is the only way a phase
+ * is entered, so `phase` is always the phase whose work is in flight.
+ */
+function _newProgress(monotonicNow) {
+  const started = monotonicNow();
+  const timings = _newTimings();
+  const progress = {
+    phase: 'build',
+    batches: 0,
+    batchesDone: 0,
+    timings,
+    /** Run `fn` with `phase` current; charge the elapsed wall time to `timings[phaseKey]` (summed). */
+    async measure(phase, phaseKey, fn) {
+      progress.phase = phase;
+      const t0 = monotonicNow();
+      try {
+        return await fn();
+      } finally {
+        timings[phaseKey] += Math.max(0, Math.round(monotonicNow() - t0));
+      }
+    },
+    /** One planned group (a batch POST or an oversize PUT). */
+    plan(count) {
+      timings.batches += Math.max(0, Number(count) || 0);
+      progress.batches = timings.batches;
+    },
+    /** One acknowledged group (its 2xx came back). */
+    planned() {
+      timings.batchesDone += 1;
+      progress.batchesDone = timings.batchesDone;
+    },
+    /** A copy, safe to hand out while the push keeps writing. */
+    snapshot() {
+      timings.totalMs = Math.max(0, Math.round(monotonicNow() - started));
+      return { ...timings };
+    },
+  };
+  return progress;
+}
+
+/** D-11: the result the caller gets when its own wait (not the push) ran out. */
+function _budgetExpired(budgetMs, progress) {
+  return {
+    ok: false,
+    code: CODE_TIMEOUT,
+    detail: `push exceeded ${budgetMs}ms in ${progress.phase}; continuing in background`,
+    phase: progress.phase,
+    timings: progress.snapshot(),
+    continuing: true,
+  };
+}
+
+/** D-11: the result every waiter gets when the push itself ran past BACKGROUND_CEILING_MS. */
+function _ceilingExpired(ceilingMs, progress) {
+  return {
+    ok: false,
+    code: CODE_TIMEOUT,
+    detail: `push exceeded ceiling ${ceilingMs}ms in ${progress.phase}`,
+    phase: progress.phase,
+    ceiling: true,
+    timings: progress.snapshot(),
+  };
+}
+
+/**
+ * D-11: bound the CALLER'S WAIT — never the push. Resolves `{timedOut:false, result}` when the push
+ * settles first, or `{timedOut:true, result:<snapshot>}` when `budgetMs` expires first. It owns no
+ * controller and aborts nothing: the deadline here is Node's own unref'd `AbortSignal.timeout`.
+ */
+function _budgetWait(promise, budgetMs, progress) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const deadline = AbortSignal.timeout(Math.max(1, Number(budgetMs) || DEFAULT_BUDGET_MS));
+    deadline.addEventListener('abort', () => {
+      if (settled) return;
+      settled = true;
+      resolve({ timedOut: true, result: _budgetExpired(budgetMs, progress) });
+    }, { once: true });
+    promise.then((result) => {
+      if (settled) return;
+      settled = true;
+      resolve({ timedOut: false, result });
+    }, (error) => {
+      // Defensive: the work promise never rejects, but a regression here must still not hang a create.
+      if (settled) return;
+      settled = true;
+      resolve({ timedOut: false, result: _fail(CODE_NETWORK, error) });
+    });
+  });
+}
+
+function _string(value, max = 1000) {
+  return String(value == null ? '' : value).trim().slice(0, max);
+}
+
+/** A short, safe `detail`: bounded, single-line, and never a credential. */
+function _safeDetail(value) {
+  let text = value instanceof Error
+    ? String(value.message || value.name || 'error')
+    : String(value == null ? '' : value);
+  // Defensive: a transport error message is caller-supplied text, and the only secret this module
+  // holds is the bearer in `peerHeaders` — so redact the shape a bearer takes before it can escape.
+  text = text.replace(/bearer\s+[^\s,;]+/gi, 'bearer <redacted>');
+  text = text.replace(/[\r\n\t]+/g, ' ').trim();
+  return text.slice(0, MAX_DETAIL_CHARS);
+}
+
+function _fail(code, detail, boxCode) {
+  const result = { ok: false, code, detail: _safeDetail(detail) };
+  // D-4: `boxCode` is present ONLY when the box really named a code — an absent key, never an
+  // empty string, so a reader can tell "the box said nothing" from "the box said ''".
+  const reason = _boxCodeString(boxCode);
+  if (reason) result.boxCode = reason;
+  return result;
+}
+
+/** The box's own reason, kept only when it is a plain snake_case token (BOX_CODE_RE). */
+function _boxCodeString(value) {
+  const text = _string(value, 80);
+  return BOX_CODE_RE.test(text) ? text : '';
+}
+
+/**
+ * D-9: read a refusal body with the bounded `_readJson` and keep `body.code` if it matches
+ * BOX_CODE_RE, else `body.error` if THAT matches, else ''. The box's own route handlers answer
+ * `{code}` (a snake_case token, D-4), but the auth WALL answers `{error}` (server.js:11791) — so a
+ * 429 reads as `rate_limited` and an old box with no batch route reads as `auth_rule_missing`.
+ * Never throws: a body this hub cannot read is "the box said nothing", and the push still reports by
+ * status.
+ */
+async function _boxCodeOf(response) {
+  const body = await _readJson(response);
+  return _boxCodeString(body && body.code) || _boxCodeString(body && body.error);
+}
+
+/** `http_<status>` for every non-2xx the box answers, including its 409/413/422 refusals. */
+function _httpFail(status, detail, boxCode) {
+  return _fail(`agent_bundle_push_http_${Number(status) || 0}`, detail, boxCode);
+}
+
+/** The bundle's unique entry hashes, in entry order, deduped — the `/missing` request body. */
+function _uniqueHashes(entries) {
+  const hashes = [];
+  const seen = new Set();
+  for (const entry of entries) {
+    const hex = _string(entry && entry.sha256, 64);
+    if (seen.has(hex)) continue;
+    seen.add(hex);
+    hashes.push(hex);
+  }
+  return hashes;
+}
+
+/** Every entry's hash must be a 64-hex digest: the box would 422 anything else, so fail locally. */
+function _entriesAreWellFormed(entries) {
+  if (!Array.isArray(entries)) return false;
+  for (const entry of entries) {
+    if (!entry || typeof entry !== 'object') return false;
+    if (!HEX_RE.test(_string(entry.sha256, 64))) return false;
+  }
+  return true;
+}
+
+function _joinUrl(baseUrl, pathname) {
+  const base = _string(baseUrl, 1000).replace(/\/+$/, '');
+  if (!base) return '';
+  try {
+    return new URL(pathname, base).toString();
+  } catch {
+    // expected: an unparseable machine url is a dial failure, never a throw out of a create
+    return '';
+  }
+}
+
+async function _readJson(response) {
+  try {
+    return await response.json();
+  } catch {
+    // expected: a non-JSON body is a refusal we report by STATUS, not a parse failure of our own
+    return null;
+  }
+}
+
+/**
+ * Push `targetPlatform`'s bundle to `machine` = `{instanceId, url}`.
+ *
+ * @param {{instanceId: string, url: string}} machine
+ * @param {object} options
+ * @param {Function} [options.fetchImpl]   the fetch implementation (injectable for tests)
+ * @param {object}   [options.peerHeaders] the Authorization + X-CTM-Sync-Peer headers the dial uses
+ * @param {string}   options.targetPlatform 'darwin' | 'linux' | 'win32' — the BOX's os
+ * @param {string[]} [options.excludePlugins] plugin names never shipped to this box (WP-8 wires it)
+ * @param {number}   [options.budgetMs]    the CALLER's wait (D-11; the push itself runs on to the ceiling)
+ * @param {number}   [options.ceilingMs]   how long the push may run past the wait (D-11, default
+ *                                         BACKGROUND_CEILING_MS)
+ * @param {Function} [options.onLateResult] `(result) => void` — the push's final result, exactly once,
+ *                                         and only for a caller that timed out AND started the push (D-11)
+ * @param {Function} [options.monotonicNow] the monotonic clock the timings are measured with (D-13)
+ * @param {Function} [options.build]       the bundle builder (injectable for tests)
+ * @param {Function} [options.now]         the clock for the cache stamp
+ * @param {object}   [options.env]         the env the build reads (WP-1)
+ * @param {string}   [options.homeDir]     the home the build reads (WP-1)
+ * @returns {Promise<{ok: true, treeHash: string, uploadedBlobs: number, uploadedBytes: number,
+ *   sentCount: number, heldBack: Array, timings: object}|{ok: false, code: string, detail: string,
+ *   boxCode?: string, phase?: string, continuing?: true, ceiling?: true, timings: object}>}
+ *   `boxCode` is the box's own refusal reason (D-4), present ONLY when it named a well-formed one.
+ *   `timings` (D-13) is on EVERY result; `joined` marks a caller that waited on someone else's push (D-12).
+ */
+async function pushBundleToBox(machine, options = {}) {
+  const opts = options && typeof options === 'object' ? options : {};
+  const fetchImpl = opts.fetchImpl || (typeof fetch === 'function' ? fetch : null);
+  const budgetMs = Number(opts.budgetMs) || DEFAULT_BUDGET_MS;
+  const build = typeof opts.build === 'function' ? opts.build : buildAgentBundle;
+  const targetPlatform = _string(opts.targetPlatform, 40);
+  const excludePlugins = Array.isArray(opts.excludePlugins) ? opts.excludePlugins.map((name) => _string(name, 200)).filter(Boolean) : [];
+  const headers = opts.peerHeaders && typeof opts.peerHeaders === 'object' ? opts.peerHeaders : null;
+  const env = opts.env && typeof opts.env === 'object' ? opts.env : process.env;
+  const homeDir = _string(opts.homeDir, 1000) || os.homedir();
+  const instanceId = _string(machine && machine.instanceId, 160);
+  const baseUrl = _string(machine && machine.url, 1000);
+  const monotonicNow = typeof opts.monotonicNow === 'function' ? opts.monotonicNow : _defaultMonotonicNow;
+  const ceilingMs = Math.max(1, Math.round(Number(opts.ceilingMs) || BACKGROUND_CEILING_MS));
+  const onLateResult = typeof opts.onLateResult === 'function' ? opts.onLateResult : null;
+
+  // Configuration failures, named as such: a push is skipped, never attempted anonymously — and
+  // never enters _inFlight (D-12: a joiner must never wait on a push that was never started).
+  if (!headers) return _fail(CODE_NO_CREDENTIAL, 'no peer credential is configured for this machine');
+  if (!fetchImpl) return _fail(CODE_NETWORK, 'no fetch implementation is available');
+  if (!baseUrl) return _fail(CODE_NETWORK, 'machine url is missing');
+  const missingUrl = _joinUrl(baseUrl, '/api/agent-bundles/missing');
+  if (!missingUrl) return _fail(CODE_NETWORK, 'machine url is not a valid url');
+
+  // D-12: single-flight per box. A push to this instanceId is already in flight: start NOTHING, wait
+  // on it with this caller's own budget, and hand back its result (`joined:true`). A joiner never
+  // calls its own `onLateResult` — the starter's caller records the outcome exactly once.
+  const running = _inFlight.get(instanceId);
+  if (running) {
+    const waited = await _budgetWait(running.promise, budgetMs, running.progress);
+    return { ...waited.result, joined: true };
+  }
+
+  const controller = new AbortController();
+  const progress = _newProgress(monotonicNow);
+  // D-11: the CEILING — and only the ceiling — aborts the push. The budget above never does.
+  const ceilingResult = new Promise((resolve) => {
+    AbortSignal.timeout(ceilingMs).addEventListener('abort', () => {
+      try {
+        controller.abort();
+      } catch {
+        // expected: an already-aborted controller
+      }
+      resolve(_ceilingExpired(ceilingMs, progress));
+    }, { once: true });
+  });
+
+  // D-11: the work promise NEVER rejects; every failure is a result. Every result carries `timings`.
+  const push = _runPush({
+    build, targetPlatform, excludePlugins, env, homeDir, headers, fetchImpl, baseUrl, missingUrl, instanceId, controller, progress, opts,
+  }).then(
+    (result) => (result && result.timings ? result : { ...result, timings: progress.snapshot() }),
+    // Defensive: `_runPush` resolves its own failures, so a rejection here is a bug — never a hang.
+    (error) => ({ ..._fail(CODE_NETWORK, error), timings: progress.snapshot() }),
+  );
+  const work = Promise.race([push, ceilingResult]);
+
+  const entry = { promise: work, progress, controller };
+  _inFlight.set(instanceId, entry);
+  // D-12: the entry is deleted when the push settles — and only if the map still holds THIS entry.
+  const release = () => {
+    if (_inFlight.get(instanceId) === entry) _inFlight.delete(instanceId);
+  };
+  work.then(release, release);
+
+  const waited = await _budgetWait(work, budgetMs, progress);
+  if (!waited.timedOut) return waited.result;
+
+  // D-11: this call timed out AND this call started the push, so it — and only it — owns the late
+  // result. A throwing callback is REPORTED, never an unhandled rejection.
+  if (onLateResult) {
+    work.then((late) => {
+      try {
+        onLateResult(late);
+      } catch (error) {
+        console.warn(`[agent-bundle] onLateResult threw for ${instanceId}: ${_safeDetail(error)}`);
+      }
+    }, () => { /* unreachable: the work promise never rejects */ });
+  }
+  return waited.result;
+}
+
+/**
+ * The push itself (D-4/D-5/D-7, and the D-13 phase bookkeeping): build, ask what is missing, upload,
+ * PUT the manifest, with the D-4 409 retry. Resolves a result — it never rejects — and reads its
+ * `progress` to say which phase is in flight when a budget/ceiling snapshot is taken.
+ */
+async function _runPush(ctx) {
+  const {
+    build, targetPlatform, excludePlugins, env, homeDir, headers, fetchImpl, baseUrl, missingUrl,
+    instanceId, controller, progress, opts,
+  } = ctx;
+  const signal = controller.signal;
+  try {
+    let bundle = null;
+    try {
+      bundle = await progress.measure('build', 'buildMs', () => build({ targetPlatform, excludePlugins, env, homeDir }));
+    } catch (error) {
+      return _fail(CODE_BUILD_FAILED, error);
+    }
+    const treeHash = _string(bundle && bundle.treeHash, 80);
+    const entries = bundle && bundle.entries;
+    const blobsByHash = bundle && bundle.blobsByHash;
+    if (!TREE_HASH_RE.test(treeHash) || !_entriesAreWellFormed(entries) || !(blobsByHash instanceof Map)) {
+      // REPORT-grade: the builder handed us a bundle the box could never accept. Same code as a
+      // build error — nothing left this hub, and the caller treats it identically (D-6).
+      return _fail(CODE_BUILD_FAILED, 'the bundle is not usable');
+    }
+
+    const jsonInit = (body) => ({
+      method: 'POST',
+      headers: { ...headers, 'content-type': 'application/json' },
+      body: JSON.stringify(body),
+      signal,
+    });
+    const manifestUrl = _joinUrl(baseUrl, `/api/agent-bundles/manifests/${encodeURIComponent(treeHash)}`);
+
+    const missingCheck = () => progress.measure('missing', 'missingMs', async () => {
+      let response;
+      try {
+        response = await fetchImpl(missingUrl, jsonInit({ blobs: hashes }));
+      } catch (error) {
+        throw Object.assign(new Error(_safeDetail(error)), { code: CODE_NETWORK });
+      }
+      const status = Number(response && response.status) || 0;
+      if (status < 200 || status >= 300) {
+        throw Object.assign(new Error(`missing check answered ${status}`), {
+          code: `agent_bundle_push_http_${status}`,
+          // S-2: the box's reason rides the throw so the outer catch can keep it (D-4).
+          boxCode: await _boxCodeOf(response),
+        });
+      }
+      const body = await _readJson(response);
+      const raw = body && Array.isArray(body.missing) ? body.missing : [];
+      // The box is the authority on WHICH blobs it lacks; it is not trusted for how many times a
+      // hash appears (a repeat would otherwise be uploaded, and counted, twice).
+      const wanted = [];
+      const seen = new Set();
+      for (const value of raw) {
+        const hex = _string(value, 64);
+        if (!HEX_RE.test(hex) || seen.has(hex)) continue;
+        seen.add(hex);
+        wanted.push(hex);
+      }
+      return wanted;
+    });
+
+    /** The REAPI ByteStream analogue: ONE blob over the existing per-blob PUT. */
+    const putOneBlob = async (hex, buffer) => {
+      let response;
+      try {
+        response = await fetchImpl(_joinUrl(baseUrl, `/api/agent-bundles/blobs/${hex}`), {
+          method: 'PUT',
+          headers: { ...headers, 'content-type': 'application/octet-stream' },
+          body: buffer,
+          signal,
+        });
+      } catch (error) {
+        throw Object.assign(new Error(_safeDetail(error)), { code: CODE_NETWORK });
+      }
+      const status = Number(response && response.status) || 0;
+      if (status < 200 || status >= 300) {
+        throw Object.assign(new Error(`blob ${hex.slice(0, 12)} answered ${status}`), {
+          code: `agent_bundle_push_http_${status}`,
+          // S-3: a 409/413/422 here is the box refusing for a reason (blobs_missing, too big, hash
+          // mismatch) — keep it exactly as the missing check does.
+          boxCode: await _boxCodeOf(response),
+        });
+      }
+      return buffer.length;
+    };
+
+    /** One D-6 `POST /api/agent-bundles/blobs` carrying a group of already-read blobs. */
+    const postBatch = async (items) => {
+      const payload = items.map(({ hex, buffer }) => ({ hash: hex, data: buffer.toString('base64') }));
+      let response;
+      try {
+        response = await fetchImpl(_joinUrl(baseUrl, '/api/agent-bundles/blobs'), jsonInit({ blobs: payload }));
+      } catch (error) {
+        throw Object.assign(new Error(_safeDetail(error)), { code: CODE_NETWORK });
+      }
+      const status = Number(response && response.status) || 0;
+      if (status < 200 || status >= 300) {
+        throw Object.assign(new Error(`blob batch answered ${status}`), {
+          code: `agent_bundle_push_http_${status}`,
+          boxCode: await _boxCodeOf(response),
+        });
+      }
+      return items.reduce((total, { buffer }) => total + buffer.length, 0);
+    };
+
+    /**
+     * D-7: read EVERY blob first (an unreadable one is a local build failure, D-6), then pack the
+     * buffers IN ORDER into groups whose raw total is at most BATCH_MAX_RAW_BYTES and send them one
+     * at a time. A single blob over the cap goes alone through the per-blob PUT. Request count is
+     * the scarce resource (see the header note), so batches are strictly sequential — never two in
+     * flight — and this returns the raw bytes sent (uploadedBytes' meaning).
+     *
+     * D-13: the reads are the `read` phase and the sends are the `upload` phase; one group — a batch
+     * POST or an oversize PUT — is one batch, counted as planned before the sends and as done after
+     * each 2xx.
+     */
+    const uploadBlobs = async (hexes) => {
+      const pending = await progress.measure('read', 'readMs', async () => {
+        const read = [];
+        for (const hex of hexes) {
+          const source = blobsByHash.get(hex);
+          let buffer;
+          try {
+            buffer = await fsp.readFile(source);
+          } catch (error) {
+            // A blob the builder named but we cannot read: the push cannot be completed, and D-6
+            // says the session is unaffected.
+            throw Object.assign(new Error(`blob unreadable: ${_safeDetail(error)}`), { code: CODE_BUILD_FAILED });
+          }
+          read.push({ hex, buffer });
+        }
+        return read;
+      });
+
+      const groups = [];
+      let current = [];
+      let currentBytes = 0;
+      for (const item of pending) {
+        if (item.buffer.length > BATCH_MAX_RAW_BYTES) {
+          if (current.length) {
+            groups.push({ items: current });
+            current = [];
+            currentBytes = 0;
+          }
+          groups.push({ oversize: item });
+          continue;
+        }
+        if (currentBytes + item.buffer.length > BATCH_MAX_RAW_BYTES) {
+          groups.push({ items: current });
+          current = [];
+          currentBytes = 0;
+        }
+        current.push(item);
+        currentBytes += item.buffer.length;
+      }
+      if (current.length) groups.push({ items: current });
+      progress.plan(groups.length);
+
+      let bytes = 0;
+      await progress.measure('upload', 'uploadMs', async () => {
+        for (const group of groups) {
+          bytes += group.oversize
+            ? await putOneBlob(group.oversize.hex, group.oversize.buffer)
+            : await postBatch(group.items);
+          progress.planned();
+        }
+      });
+      return bytes;
+    };
+
+    const putManifest = () => progress.measure('manifest', 'manifestMs', async () => {
+      let response;
+      try {
+        response = await fetchImpl(manifestUrl, {
+          // D-5: only the manifest's own three fields cross — never blobsByHash, items, heldBack
+          // or warnings.
+          method: 'PUT',
+          headers: { ...headers, 'content-type': 'application/json' },
+          body: JSON.stringify({ schema: 1, treeHash, entries }),
+          signal,
+        });
+      } catch (error) {
+        throw Object.assign(new Error(_safeDetail(error)), { code: CODE_NETWORK });
+      }
+      const status = Number(response && response.status) || 0;
+      // S-3: the manifest PUT reports its status rather than throwing (the 409 retry lives at the
+      // call site), so carry the box's reason alongside it for that call site to keep.
+      const boxCode = (status < 200 || status >= 300) ? await _boxCodeOf(response) : '';
+      return { status, boxCode };
+    });
+
+    const hashes = _uniqueHashes(entries);
+    let uploadedBlobs = 0;
+    let uploadedBytes = 0;
+
+    const missing = await missingCheck();
+    if (missing.length) {
+      uploadedBytes += await uploadBlobs(missing);
+      uploadedBlobs = missing.length;
+    }
+
+    const delivered = _pushedTrees.get(instanceId);
+    const alreadyDelivered = !!(delivered && delivered.has(treeHash));
+    if (alreadyDelivered && !missing.length) {
+      progress.phase = 'done';
+      return _success(treeHash, 0, 0, bundle, opts);
+    }
+
+    let manifest = await putManifest();
+    if (manifest.status === 409) {
+      // D-4's one retry: the box named blobs it wants after all (a GC, or a first push that raced
+      // another hub). Re-upload exactly what it asks for and PUT the manifest once more; a second
+      // 409 is reported, not looped on. D-13: the retry re-enters missing → read → upload → manifest.
+      const lateMissing = await missingCheck();
+      if (lateMissing.length) {
+        uploadedBytes += await uploadBlobs(lateMissing);
+        uploadedBlobs += lateMissing.length;
+      }
+      manifest = await putManifest();
+    }
+    if (manifest.status < 200 || manifest.status >= 300) {
+      return _httpFail(manifest.status, `manifest answered ${manifest.status}`, manifest.boxCode);
+    }
+
+    const entry = _pushedTrees.get(instanceId) || new Set();
+    entry.add(treeHash);
+    _pushedTrees.set(instanceId, entry);
+    progress.phase = 'done';
+    return _success(treeHash, uploadedBlobs, uploadedBytes, bundle, opts);
+  } catch (error) {
+    const code = _string(error && error.code, 80) || CODE_NETWORK;
+    // With D-11 nothing here times the push out (only the ceiling aborts, and its result wins the
+    // race), but a tagged CODE_TIMEOUT still reports as one.
+    if (code === CODE_TIMEOUT) return _fail(CODE_TIMEOUT, `push timed out in ${progress.phase}`);
+    // Any other tagged code is already one of this module's closed set; anything untagged is a
+    // transport/unexpected fault and reads as a network failure. S-4: the box's reason, when a
+    // non-2xx site attached one, rides out unchanged — `code` keeps its `agent_bundle_push_http_<n>`
+    // value, so nothing that branches on it changes.
+    return _fail(
+      code.startsWith('agent_bundle_push_http_') ? code : (code === CODE_BUILD_FAILED ? CODE_BUILD_FAILED : CODE_NETWORK),
+      error,
+      error && error.boxCode,
+    );
+  }
+}
+
+function _success(treeHash, uploadedBlobs, uploadedBytes, bundle, opts) {
+  return {
+    ok: true,
+    treeHash,
+    uploadedBlobs: Number(uploadedBlobs) || 0,
+    uploadedBytes: Number(uploadedBytes) || 0,
+    sentCount: Array.isArray(bundle.items) ? bundle.items.length : 0,
+    heldBack: Array.isArray(bundle.heldBack) ? bundle.heldBack : [],
+    // WP-9 (§9 S-9): the plugin names this push carried — the machine row's Review checklist reads them
+    // (machine-registry.js `_pluginsFromResult`). Names only; the item hashes stay inside the bundle.
+    plugins: (Array.isArray(bundle.items) ? bundle.items : [])
+      .filter((item) => item && item.kind === 'plugin' && item.name).map((item) => String(item.name)),
+    at: typeof opts.now === 'function' ? Number(opts.now()) || 0 : Date.now(),
+  };
+}
+
+module.exports = {
+  pushBundleToBox,
+  DEFAULT_BUDGET_MS,
+  BACKGROUND_CEILING_MS,
+  BATCH_MAX_RAW_BYTES,
+  CODE_BUILD_FAILED,
+  CODE_TIMEOUT,
+  CODE_NETWORK,
+  CODE_NO_CREDENTIAL,
+  _resetPushCacheForTests,
+};