dsh-plugin-mobile-link 0.3.0 → 0.4.0

package/lib/files-out.js

@@ -0,0 +1,425 @@
+/**
+ * Files the phone pulls **from** this computer, over the relay's HTTP surface.
+ *
+ * The mirror of `files.js`. Same reason for existing: the phone cannot reach the
+ * computer (this connector dials out and listens on loopback only), so the relay
+ * terminates the HTTP request — but only this side can drive the Host's
+ * `workspaceFiles/readBytes`. The relay pumps `GET /files/down`, this module
+ * answers `fsGetBegin` with a run of `fsGetChunk` frames, and the relay writes
+ * each one straight into the response body. **Nothing is stored anywhere in
+ * between.**
+ *
+ * Why not just let the app use `workspaceFiles/readBytes` over WSS, as it does
+ * today? Because a socket dies when iOS suspends the app, and a large download
+ * the user started before pocketing the phone would die with it. A background
+ * `URLSessionDownloadTask` is the only kind of transfer the system finishes on
+ * the app's behalf — and that needs an HTTP endpoint.
+ *
+ * Two shapes worth stating, because both differ from `files.js`:
+ *
+ * * the reads are **pulled a window at a time** by this module rather than
+ *   pushed at it, so a slow or vanished reader costs at most one window in
+ *   flight; and
+ * * the replies carry **no `deviceId`** (like `fsPut*`): the relay correlates by
+ *   `bid` alone, and adding an addressing field would break that.
+ */
+
+/** Reserved frame types this module answers; see `docs/relay-contract.json`. */
+export const FSGET_BEGIN = 'fsGetBegin'
+export const FSGET_CHUNK = 'fsGetChunk'
+export const FSGET_END = 'fsGetEnd'
+/**
+ * The relay's "stop reading for this run" frame.
+ *
+ * The pull side can end without the connector ever noticing: the phone hangs up,
+ * or the daily allowance cuts the response off mid-body. The relay sees that
+ * immediately (`deliver` reports a full queue), this side does not — the reads
+ * are driven here, so nothing would stop a run whose reader has left until the
+ * whole file had been read and every window thrown away at the relay.
+ *
+ * Cancelling an unknown `bid` is a no-op, exactly like `fsGetCancel`'s sibling
+ * `deviceDetach`: the relay is free to send one per dead bridge without tracking
+ * which runs are live, and a duplicate cannot hurt a run that is already gone.
+ */
+export const FSGET_CANCEL = 'fsGetCancel'
+/**
+ * The connector's "I have the file, start reading" answer.
+ *
+ * Carries `size` and `version` when the Host could tell us (P-13b). The relay
+ * needs the size to answer `Content-Length` and a full
+ * `Content-Range: bytes N-M/TOTAL`, which is what makes an interrupted download
+ * resumable by the system rather than restarted: a background
+ * `URLSessionDownloadTask` only produces resume data when the response states
+ * the total. The version becomes the `ETag`, so a `If-Range` on the retry can
+ * tell "same file, keep going" from "the file changed under me, start over".
+ *
+ * Both fields are **optional on purpose**: a Host that cannot stat the file
+ * still gets its download, just without the resume guarantee. A missing field
+ * must degrade to the old behaviour, never to an error — that is what keeps
+ * this a compatible addition rather than a protocol break.
+ */
+export const FSGET_ACK = 'fsGetAck'
+export const FSERR = 'fsErr'
+
+/**
+ * The window this module asks the Host for, and therefore the size of one
+ * `fsGetChunk` before base64.
+ *
+ * 2 MiB is the Host's own `maxBytes` for `workspaceFiles/readBytes`
+ * (`DSHClient.swift`), so asking for exactly that means no window is ever
+ * refused for being too large — and base64 makes the frame ~2.67 MB, well under
+ * the 32 MB frame ceiling (`lib/dlp.js`).
+ */
+export const DEFAULT_WINDOW_BYTES = 2 * 1024 * 1024
+
+/**
+ * The floor a window shrinks to when the Host says `workspace-file/too-large`.
+ *
+ * The Host's limit is a deployment value, not a constant this side can read, so
+ * it is discovered: refuse → halve, down to here. Same approach as the app's own
+ * downloader (`WorkspaceFileDownloader.swift`), and the same floor.
+ */
+export const MIN_WINDOW_BYTES = 128 * 1024
+
+/** How many refusals in a row before the fetch is abandoned rather than halved. */
+const MAX_SHRINKS = 8
+
+/**
+ * Host error codes that mean "asking again will answer the same thing".
+ *
+ * The app decides whether to retry from the code, so these must travel verbatim
+ * in the `fsErr` — a generic `file/rejected` would make a bad path look like a
+ * flaky network and send the user round the retry loop for nothing. The list is
+ * the connector's copy of the app's own `isRetryable` set
+ * (`WorkspaceFileDownloader.swift`); it only has to be *wider* than reality,
+ * never narrower, because a code that lands here wrongly turns a retryable
+ * failure into a permanent one.
+ */
+export const NON_RETRYABLE_CODES = new Set([
+  'workspace-file/not-found',
+  'workspace-file/outside-workspace',
+  'workspace-file/not-regular-file',
+  'workspace-file/not-directory',
+  'workspace-file/unknown-workspace',
+  'gateway/lookup-not-found',
+  'gateway/bad-request',
+])
+
+/**
+ * Whether a failure should be reported as-is (the app must not retry it).
+ *
+ * Anything unrecognised is assumed retryable: the cost of one wasted retry is a
+ * second of the user's time, while wrongly declaring a transient failure
+ * permanent leaves them with a file they cannot fetch at all.
+ */
+export function isPermanent(error) {
+  const code = error?.code
+  return typeof code === 'string' && NON_RETRYABLE_CODES.has(code)
+}
+
+/** Normalise a thrown Host failure into the `{code, message}` shape `fsErr` wants. */
+function failureOf(error) {
+  const code = typeof error?.code === 'string' && error.code ? error.code : 'file/rejected'
+  const message = error instanceof Error ? error.message : String(error ?? 'download failed')
+  return { code, message }
+}
+
+/**
+ * Whether the gateway refused a call over its argument **shape**.
+ *
+ * The Host checks every Remote call against the method's descriptor and rejects
+ * anything that does not match it field for field — a renamed or relocated
+ * argument comes back as `gateway/arguments-invalid`, never as a silent default.
+ * That refusal is the only thing a connector can learn one Host generation's
+ * signature from another by, which is why the probe in `#callReadBytes` keys on
+ * it rather than on a version number.
+ */
+function isShapeRefusal(result) {
+  return result?.ok === false && result?.error?.code === 'gateway/arguments-invalid'
+}
+
+/**
+ * One fetch, as this connector runs it.
+ *
+ * Not stateful beyond one run: it opens no file (the Host does the reading), so
+ * there is nothing to clean up but the cancellation flag.
+ */
+export class FetchRun {
+  constructor({ bid, scopeId, path, offset = 0, windowBytes = DEFAULT_WINDOW_BYTES }) {
+    this.bid = bid
+    this.scopeId = scopeId
+    this.path = path
+    this.offset = Number.isFinite(offset) ? Math.max(0, offset) : 0
+    this.windowBytes = windowBytes
+    /** Set when the relay stopped reading (it hung up, or ran out of quota). */
+    this.cancelled = false
+  }
+}
+
+/** Owns the in-flight downloads for one connector. */
+export class FileFetcher {
+  #runs = new Map()
+  #logger
+  #sends
+  #rpc
+  /**
+   * Which argument shape this Host's `workspaceFiles/readBytes` accepts.
+   *
+   * `null` until the first read has taught us which one. Per fetcher, so per
+   * connector process: the probe below costs one extra round trip, once.
+   * @type {'options'|'range'|null}
+   */
+  #byteWindowShape = null
+
+  /**
+   * @param {object} options
+   * @param {(frame: object) => boolean} options.send  one frame to the relay
+   * @param {(method: string, args: object) => Promise<object>} options.rpc
+   *        the ordinary Host call path (`this.dsh.rpc`). Injected rather than
+   *        reached for, so `node --test` can run a whole download against a stub
+   *        Host with no DSH process at all.
+   * @param {object} options.logger
+   */
+  constructor({ send, rpc, logger = {} } = {}) {
+    this.#sends = send ?? (() => false)
+    this.#rpc = rpc ?? (async () => ({ ok: false, error: { code: 'host/unavailable' } }))
+    this.#logger = logger
+  }
+
+  /**
+   * Start one download and run it to completion.
+   *
+   * Deliberately **not** awaited by the caller's frame handler: the whole point
+   * is that chunks go out while the relay reads, and a `handleRelayFrame` that
+   * awaited the file would block every other frame on the same socket.
+   * Resolves when the run finishes (or `false` if it never started).
+   */
+  start(frame) {
+    const bid = String(frame?.bid ?? '')
+    if (!bid) {
+      this.#logger.warn?.('mobile-link: fsGetBegin without a bid')
+      return false
+    }
+    const scopeId = String(frame?.scopeId ?? '')
+    const path = String(frame?.path ?? '')
+    if (!scopeId || !path) {
+      this.#sendError(bid, { code: 'file/rejected', message: 'scopeId and path are required' })
+      return false
+    }
+    // A retried `bid` replaces the previous run: the connector reuses the id
+    // across attempts of the same fetch, and two runs writing the same bid
+    // would interleave their chunks into one nonsense stream.
+    this.cancel(bid)
+    // **`replaces` is how the superseded run is named now that the relay mints
+    // its own ids.** Each HTTP request gets a fresh `bid`, so the run left over
+    // from an interrupted attempt is not reachable by this request's identifier —
+    // and on a resumed download it is very much still there: the system's resume
+    // data freezes the *original* request, so what arrives is the old identifier
+    // replayed. Without this the old run would keep reading until the new
+    // `fsGetBegin` reached it, and its windows are exactly the ones the relay
+    // cannot recall. Advisory by construction: a name we do not know stops
+    // nothing, which is what an older relay (which never sends it) relies on.
+    const replaced = String(frame?.replaces ?? '')
+    if (replaced && replaced !== bid) this.cancel(replaced)
+    const run = new FetchRun({
+      bid, scopeId, path,
+      offset: Number(frame?.offset ?? 0),
+      windowBytes: Number(frame?.window) > 0 ? Number(frame.window) : DEFAULT_WINDOW_BYTES,
+    })
+    this.#runs.set(bid, run)
+    // The stat has to happen **before** the ack: the relay builds the response
+    // (status, `Content-Length`, `Content-Range`, `ETag`) from this answer, and
+    // it can only prepare a resumable response once it is told what it is
+    // resuming. Statting after the ack would mean the headers were already sent.
+    this.#ackNow(run)
+    this.#drive(run).catch((error) => {
+      this.#logger.warn?.(`mobile-link: download ${bid} failed: ${error?.message ?? error}`)
+    })
+    return true
+  }
+
+  /**
+   * Answer the relay's `fsGetBegin`, with the file's size and version if the
+   * Host can supply them.
+   *
+   * Never fails the transfer: `stat` is an enhancement (it is what makes the
+   * download resumable), and a Host that refuses it — an older DSH, a file that
+   * vanished between the request and the stat — must still get its bytes. The
+   * ack goes out either way, just without the fields the relay would have used
+   * to build a resumable response.
+   */
+  async #ackNow(run) {
+    const extra = await this.#statFor(run)
+    // A run superseded while the stat was in flight must not ack: the relay has
+    // already opened a new bridge for that bid, and a late ack would be
+    // answering the request it just replaced.
+    if (run.cancelled) return
+    this.#sends({ t: FSGET_ACK, bid: run.bid, ...extra })
+  }
+
+  /**
+   * One `workspaceFiles/stat`, reduced to the two fields the relay uses.
+   *
+   * Returns `{}` rather than throwing: see `#ackNow`. A sized response is worth
+   * a round trip, but never worth the transfer.
+   */
+  async #statFor(run) {
+    try {
+      const result = await this.#rpc('workspaceFiles/stat', {
+        workspaceFileScopeId: run.scopeId,
+        path: run.path,
+      })
+      if (result && result.ok === false) return {}
+      const value = result?.value ?? result
+      const size = Number.isFinite(value?.bytes) ? Number(value.bytes) : undefined
+      const version = typeof value?.version === 'string' && value.version ? value.version : undefined
+      if (size === undefined && version === undefined) return {}
+      return {
+        ...size === undefined ? {} : { size },
+        ...version === undefined ? {} : { version },
+      }
+    } catch {
+      return {}
+    }
+  }
+
+  /** Stop one run. Safe for an unknown bid (a late cancel is not an error). */
+  cancel(bid) {
+    const run = this.#runs.get(bid)
+    if (run) run.cancelled = true
+  }
+
+  /** Stop every run, e.g. when the link goes down. */
+  clear() {
+    for (const run of this.#runs.values()) run.cancelled = true
+    this.#runs.clear()
+  }
+
+  async #drive(run) {
+    let offset = run.offset
+    let shrinks = 0
+    let window = run.windowBytes
+    try {
+      for (;;) {
+        if (run.cancelled) return
+        let answer
+        try {
+          answer = await this.#readWindow(run.scopeId, run.path, offset, window)
+        } catch (error) {
+          const failure = failureOf(error)
+          if (failure.code === 'workspace-file/too-large' && shrinks < MAX_SHRINKS
+              && window > MIN_WINDOW_BYTES) {
+            // The Host's cap is smaller than the window asked for. Halve and try
+            // again — the cap is a deployment value nothing here can read.
+            window = Math.max(MIN_WINDOW_BYTES, Math.floor(window / 2))
+            shrinks += 1
+            continue
+          }
+          if (!run.cancelled) this.#sendError(run.bid, failure)
+          return
+        }
+        // A window that came back after the run was superseded or dropped: the
+        // relay has already stopped listening for this bid, and appending more
+        // chunks would interleave into whatever run owns the bid now.
+        if (run.cancelled) return
+        // The bytes arrive in one of two shapes: base64 inside the JSON answer
+        // (a Host whose results are all JSON), or a `Uint8Array` (a Host that
+        // answers binary results as form parts — see `dsh-client.js`). The
+        // relay's frame carries base64 either way, so this is where the two
+        // converge.
+        const raw = answer?.data
+        const data = typeof raw === 'string'
+          ? raw
+          : raw instanceof Uint8Array ? Buffer.from(raw).toString('base64') : ''
+        const eof = answer?.eof === true
+        const piece = Buffer.from(data, 'base64')
+        if (piece.length > 0) {
+          this.#sends({ t: FSGET_CHUNK, bid: run.bid, data, eof })
+          offset += piece.length
+        } else if (!eof) {
+          // An empty window that is not the end means the Host has nothing more
+          // at this offset. Asking again would spin forever, so this is an error.
+          if (!run.cancelled) {
+            this.#sendError(run.bid, {
+              code: 'workspace-file/stalled',
+              message: `the Host returned an empty window at offset ${offset}`,
+            })
+          }
+          return
+        }
+        if (eof) {
+          // The run may have been superseded while that window was in flight —
+          // a stale `fsGetEnd` would tell the relay a download nobody wanted any
+          // more is complete, and a retried bid would answer its HTTP request
+          // twice.
+          if (run.cancelled) return
+          if (piece.length === 0) {
+            // Nothing at all was read and it is already the end: an empty file,
+            // or an offset past the end. Either way the stream is complete.
+            this.#sends({ t: FSGET_CHUNK, bid: run.bid, data: '', eof: true })
+          }
+          this.#sends({ t: FSGET_END, bid: run.bid })
+          return
+        }
+      }
+    } finally {
+      this.#runs.delete(run.bid)
+    }
+  }
+
+  /** One `workspaceFiles/readBytes`, unwrapped to `{data, eof}`. */
+  async #readWindow(scopeId, path, offset, length) {
+    const result = await this.#callReadBytes(scopeId, path, offset, length)
+    if (result && result.ok === false) {
+      // The DSH client returns failures as values (`{ok:false, error}`) rather
+      // than throwing; the code has to survive into the `fsErr`.
+      throw Object.assign(new Error(result.error?.message ?? 'read failed'),
+        { code: result.error?.code })
+    }
+    return result?.value ?? result
+  }
+
+  /**
+   * The read, in whichever argument shape this Host takes.
+   *
+   * Host 0.2.0-rc.2 moved the byte window from a top-level `range` into
+   * `options.range`, and the gateway validates field for field — so the two
+   * shapes cannot be sent at once, and a connector that speaks only one of them
+   * breaks the whole download path on the other Host generation. Which shape
+   * this Host wants is therefore **probed, not version-compared**, the same way
+   * `hello.js` treats capabilities: try the current shape, and if the descriptor
+   * refuses it, try the older one and remember the answer.
+   */
+  async #callReadBytes(scopeId, path, offset, length) {
+    const attempt = (shape) => this.#rpc('workspaceFiles/readBytes', {
+      workspaceFileScopeId: scopeId,
+      path,
+      ...shape === 'options'
+        ? { options: { range: { offset, length } } }
+        : { range: { offset, length } },
+    })
+
+    if (this.#byteWindowShape) return attempt(this.#byteWindowShape)
+
+    const current = await attempt('options')
+    if (!isShapeRefusal(current)) {
+      this.#byteWindowShape = 'options'
+      return current
+    }
+    // The older shape's own answer is the one that counts now: if that is refused
+    // too, the failure is the caller's to report, exactly as it stands.
+    const older = await attempt('range')
+    if (!isShapeRefusal(older)) this.#byteWindowShape = 'range'
+    return older
+  }
+
+  #sendError(bid, failure) {
+    this.#logger.warn?.(`mobile-link: download ${bid} failed: ${failure.code} ${failure.message}`)
+    this.#sends({ t: FSERR, bid, ...failure })
+  }
+
+  /** Whether a run is still wanted; a superseded one emits nothing more. */
+  static isLive(run) {
+    return run !== undefined && !run.cancelled
+  }
+}

package/lib/files.js

@@ -12,10 +12,11 @@
  * neither the relay nor the protocol needs to change.
  */
 
-import { mkdirSync, writeFileSync, rmSync, statSync } from 'node:fs'
-import { homedir } from 'node:os'
+import { mkdirSync, openSync, closeSync, writeSync, renameSync, rmSync, statSync } from 'node:fs'
 import { basename, join } from 'node:path'
 
+import { dshHome } from './state.js'
+
 /** Reserved method names this module answers; never forwarded to the Host. */
 export const FILE_BEGIN = '_link/fileBegin'
 export const FILE_CHUNK = '_link/fileChunk'
@@ -26,21 +27,41 @@ export function isFileMethod(method) {
 }
 
 /**
- * One in-flight transfer. Chunks are appended in order and the file only
- * appears at its final path once the end frame arrives, so a half-sent file is
- * never mistaken for a complete one.
+ * One in-flight transfer.
+ *
+ * Chunks are **appended to a staging file as they arrive**, so the memory a
+ * transfer holds is one chunk, not the whole file. It used to accumulate every
+ * chunk in an array and `Buffer.concat` at the end, which meant a 300 MB upload
+ * needed 300 MB (plus the concatenation's copy) of RSS on this computer — fine
+ * for the few-MB screenshots this path was written for, not fine for the large
+ * files the background-URL-session path now sends through the same code.
+ *
+ * The final name only appears once the end frame has arrived and the byte count
+ * checks out, so a half-sent file is never mistaken for a complete one.
  */
 class Transfer {
   constructor({ sessionId, name, bytes }) {
     this.sessionId = sessionId
     this.name = basename(name || 'file')
     this.bytes = Number.isFinite(bytes) ? bytes : undefined
-    this.parts = []
     this.received = 0
     this.expectedSeq = 0
-    this.directory = join(homedir(), '.dsh', 'inbox', sessionId)
+    // 认 `DSH_HOME`（不是写死 `~/.dsh`）：测试与验证都靠它隔离，
+    // 混用两种口径会让隔离失效（宪法第 III 条）。
+    this.directory = join(dshHome(), 'inbox', sessionId)
     mkdirSync(this.directory, { recursive: true, mode: 0o700 })
     this.staging = join(this.directory, `.${this.name}.part`)
+    // Opened once and kept: reopening per chunk would be a syscall per chunk for
+    // no benefit. `w` truncates, which is what a retried transfer wants.
+    this.fd = undefined
+  }
+
+  #handle() {
+    if (this.fd === undefined) {
+      rmSync(this.staging, { force: true })
+      this.fd = openSync(this.staging, 'w', 0o600)
+    }
+    return this.fd
   }
 
   append(seq, base64) {
@@ -48,26 +69,34 @@ class Transfer {
       throw new Error(`chunk ${seq} arrived out of order (expected ${this.expectedSeq})`)
     }
     const buffer = Buffer.from(base64, 'base64')
-    this.parts.push(buffer)
+    writeSync(this.#handle(), buffer)
     this.received += buffer.length
     this.expectedSeq += 1
   }
 
   finish() {
-    const body = Buffer.concat(this.parts)
-    if (this.bytes !== undefined && body.length !== this.bytes) {
-      throw new Error(`expected ${this.bytes} bytes but received ${body.length}`)
+    if (this.bytes !== undefined && this.received !== this.bytes) {
+      throw new Error(`expected ${this.bytes} bytes but received ${this.received}`)
     }
-    writeFileSync(this.staging, body, { mode: 0o600 })
+    this.#close()
     // Renamed only now: the final name means "complete".
     const final = join(this.directory, this.name)
     rmSync(final, { force: true })
-    writeFileSync(final, body, { mode: 0o600 })
-    rmSync(this.staging, { force: true })
+    renameSync(this.staging, final)
     return { path: final, bytes: statSync(final).size }
   }
 
+  #close() {
+    if (this.fd === undefined) return
+    try {
+      closeSync(this.fd)
+    } finally {
+      this.fd = undefined
+    }
+  }
+
   dispose() {
+    this.#close()
     rmSync(this.staging, { force: true })
   }
 }

package/lib/handoff.js

@@ -0,0 +1,53 @@
+/**
+ * 连接器写给**进程外**消费者的交接文件。
+ *
+ * 为什么需要它：跑在 DSH 宿主进程之外的脚本（`scripts/dev/dsh-probe.mjs`、`verify-simulator.sh`、
+ * `test/tools/host.mjs` 等）与 iOS 的集成测试辅助都没有进程内上下文，拿不到注入的服务；
+ * 它们需要一个本机可读的"带凭据本机地址"。契约见
+ * `specs/001-connector-host-compat/contracts/out-of-process-handoff.md`。
+ *
+ * 安全取舍：该文件含可用凭据，因此权限固定 0600、只写本机、不进日志；
+ * 这是"让进程外工具可用"与"凭据不落盘"之间**有意识接受**的代价。
+ *
+ * 不变量：连接器**不读回**这个文件（避免自证循环）；连接器停止时**不删除**它
+ * （宿主短暂重启期间，进程外工具仍要能读到最近一次的值）。
+ */
+
+import { chmod, mkdir, rename, writeFile } from 'node:fs/promises'
+import { dirname } from 'node:path'
+
+import { defaultHandoffFile } from './state.js'
+
+/**
+ * 原子写入交接文件。
+ *
+ * @param {object} input
+ * @param {string} input.url 带凭据的本机地址（`http://127.0.0.1:<port>/?token=...`）
+ * @param {number} input.port 本机 DSH 端口
+ * @param {string} input.source 该地址来自哪一级（通常是 `host-service`）
+ * @param {string} [input.path] 覆盖默认路径（测试用）
+ * @param {number} [input.pid] 写入进程 pid
+ * @param {string} [input.updatedAt] ISO-8601 时间戳
+ * @returns {Promise<string>} 写好的文件路径
+ */
+export async function writeHandoff({ url, port, source, path = defaultHandoffFile(), pid = process.pid, updatedAt = new Date().toISOString() }) {
+  if (typeof url !== 'string' || url === '') throw new TypeError('handoff: url is required')
+  if (!Number.isFinite(Number(port)) || Number(port) <= 0) throw new TypeError('handoff: port is required')
+  const payload = { url, port: Number(port), pid, source: source ?? null, updatedAt }
+  await mkdir(dirname(path), { recursive: true })
+  const temporary = `${path}.${process.pid}.tmp`
+  await writeFile(temporary, `${JSON.stringify(payload, null, 2)}\n`, { mode: 0o600 })
+  await rename(temporary, path)
+  await chmod(path, 0o600).catch(() => {})
+  return path
+}
+
+/** 由已认证的 endpoint 组出交接文件内容所需的字段。 */
+export function handoffFromEndpoint(endpoint) {
+  if (!endpoint?.base || !endpoint?.token) return undefined
+  return {
+    url: `${endpoint.base}/?token=${encodeURIComponent(endpoint.token)}`,
+    port: endpoint.port,
+    source: endpoint.source,
+  }
+}

package/lib/hello.js

@@ -46,9 +46,17 @@ function readManifestVersion() {
  * - `self-enroll`    this connector can register itself with an invite code
  * - `git`            git status / diff / log / show can be read from the work
  *                    tree on this computer (see git.js)
+ * - `background-transfer`
+ *                    this connector speaks the `fsPut*` / `fsGet*` bridge frames,
+ *                    so the app may **send and fetch** large files over the
+ *                    relay's HTTPS surface with a background URL session instead
+ *                    of the WebSocket. An app that does not see this falls back to
+ *                    the WSS path — which is why adding the capability is the
+ *                    *only* switch the client needs.
  */
 export const SERVER_CAPABILITIES = [
   'file-transfer', 'events', 'session-streams', 'pair-code', 'qr-pairing', 'self-enroll', 'git',
+  'background-transfer',
 ]
 
 export function isHelloMethod(method) {