feat(debug-files): honor server upload limits and add --derived-data

[BYK]

Follow-up to #1139. Scopes the outer upload envelope of debug-files upload to parity with the legacy dif_upload — honoring server-advertised limits and adding Xcode DerivedData scanning. No WASM changes.

What's included

• Server maxFileSize enforcement — parse the optional maxFileSize from chunk-upload options; files exceeding it are dropped (with a warning) before assembling. prepareDifs also gains a scan-time size gate using the 2 GiB DEFAULT_MAX_DIF_SIZE default so --no-upload dry-runs report realistic skips without needing server options.
• Server maxWait clamp — in wait mode, the processing wait is clamped to min(requested, server.maxWait). No-wait mode leaves its hang-guard deadline untouched.
• --derived-data — additionally scans ~/Library/Developer/Xcode/DerivedData on macOS. Existence-gated (and a no-op with a warning on non-macOS), so the stricter scanPaths existence check from feat(debug-files): add upload command (core) #1139 is never tripped by an absent folder.

Both server fields are optional in the schema (maxFileSize / maxWait); a server response that omits them parses unchanged (backward compatible), and 0 means "no cap" (legacy semantics).

Testing

• chunk-upload.test.ts — schema parses with/without the new optional fields.
• debug-files.test.ts — oversized files dropped before assemble; all-oversized returns [] with no request; wait clamped to server maxWait (reflected in the timeout detail); no clamp when server advertises 0.
• scan.test.ts — prepareDifs size gate keeps/skips by limit.
• upload.test.ts — --derived-data is additive with explicit paths; on non-macOS, --derived-data alone exits non-zero (no scan targets).

53 tests pass across the touched suites; full repo lint + typecheck clean.

Deferred to follow-ups

filter_bad_sources + il2cpp sources (next PR), fix_pdb_ages (after that). Blocked on upstream WASM/tooling: --il2cpp-mapping line mappings (ObjectLineMapping), --symbol-maps (Apple dsymutil).

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://cli.sentry.dev/_preview/pr-1140/
Built to branch gh-pages at 2026-06-25 13:10 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[github-actions]

Codecov Results 📊

✅ Patch coverage is 86.46%. Project has 5107 uncovered lines.
✅ Project coverage is 81.49%. Comparing base (base) to head (head).

Files with missing lines (3)

File	Patch %	Lines
src/commands/debug-files/upload.ts	84.21%	⚠️ 6 Missing and 2 partials
src/lib/dif/scan.ts	84.85%	⚠️ 5 Missing and 2 partials
src/lib/api/debug-files.ts	91.67%	⚠️ 2 Missing and 2 partials

Coverage diff

@@            Coverage Diff             @@
##          main       #PR       +/-##
==========================================
+ Coverage    81.46%    81.49%    +0.03%
==========================================
  Files          396       396         —
  Lines        27525     27588       +63
  Branches     17863     17912       +49
==========================================
+ Hits         22422     22481       +59
- Misses        5103      5107        +4
- Partials      1861      1865        +4

---

Generated by Codecov Action

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit b38b62f. Configure here.}

[sentry-warden]

Assembly deadline runs down during chunk upload, causing false timeout when server maxWait is tight

In debug-files.ts, deadline = Date.now() + effectiveMaxWaitMs is stamped before the initial postAssemble + uploadMissing calls, so slow chunk delivery consumes the server-clamped budget. If upload takes longer than effectiveMaxWaitMs, the while loop's first Date.now() >= deadline check fires and throws ApiError(408) even though all chunks were successfully delivered and the server will complete assembly — producing a false failure on builds with large DIFs and a low server maxWait.

Evidence

• effectiveMaxWaitMs is clamped to serverOptions.maxWait * 1000 when wait=true (debug-files.ts:415-417).
• deadline = Date.now() + effectiveMaxWaitMs is set at line 418, before postAssemble (line 419) and uploadMissingBufferChunks (lines 421-427).
• The while loop checks Date.now() >= deadline at line 430 as its first action; if chunk upload consumed the budget, it immediately throws ApiError(408, 'Assembly did not complete within Xs').
• By contrast, pollAssembly in chunk-upload.ts sets its deadline only after chunks are already uploaded by the caller, so artifact-bundle uploads don't have this race.
• The server has received every chunk and will continue processing regardless; only the client reports failure.

_{Identified by Warden find-bugs}

[sentry-warden]

Partial size-drop in filterBySize (e.g. oversized source bundles) silently exits 0

In uploadDebugFiles, filterBySize drops any DIF whose content.length exceeds effectiveMaxFileSize with only a log.warn. The accepted.length === 0 guard that raises ValidationError only fires when every file is dropped. When some files are accepted and only others are dropped — most notably the in-memory source bundles produced by --include-sources, which bypass the scan-time prepareDifs size gate — the dropped files never enter chunked, so buildResults produces no result entry for them. doUpload only flags results with state === "error" || "not_found", so failures.length stays 0, setExitCode(1) is never called, and the command prints "Uploaded N debug file(s)" and exits 0 with no indication the source bundle was dropped.

Evidence

• filterBySize (debug-files.ts:309-327) drops oversized DIFs with only log.warn and continue, returning the remaining subset.
• The accepted.length === 0 guard (debug-files.ts:391) only throws ValidationError when all files are dropped; a partial drop passes through silently.
• buildResults (debug-files.ts:288) maps only over chunked, built from accepted, so dropped files have no entry in the returned results.
• --include-sources bundles are pushed by buildDifList after prepareDifs ran its scan-time gate, so they reach filterBySize as the only files that can be oversized in the real-upload path; if a bundle exceeds the limit while its parent DIF does not, it is dropped silently.
• doUpload (upload.ts) computes failures only from state === "error" || "not_found"; with no entry for the dropped bundle, failures.length is 0 and setExitCode(1) is never invoked, so the command exits 0.

_{Identified by Warden find-bugs · 9LL-87A}