fix(apply): close output fd synchronously to avoid ETXTBSY on subsequent spawn

[BYK]

Problem

applyPatchChainInMemory (and downstream consumers like
getsentry/cli) chain the apply
output immediately into a spawn to run the patched binary. On
Linux this intermittently fails with ETXTBSY ("text file busy")
even after writer.end() resolves — Node's writable stream fires
its end callback on the 'finish' event (data flushed), but
the underlying fd can still be held at the kernel level when the
caller reaches the spawn line.

fs.writeFile does not exhibit the bug because it closes the fd
synchronously before returning, which is why the issue only surfaced
in the field once a fallback path used a different API.

Fix

applyReaderToFile now writes via fs.openSync + fs.writeSync

• fs.closeSync instead of fs.createWriteStream / writer.end.
  The fd is guaranteed to be released before the function returns, so
  the caller can spawn the output file without any race.

Trade-off: we lose WriteStream's 1 MiB highWaterMark buffering, so
write syscall count scales with the bspatch chunk size (typically
16–64 KiB). Linux's write path coalesces adjacent small writes
effectively for sequential output, so the cost is bounded;
correctness is the property that matters here.

Regression test

test/bspatch.test.ts adds a case that runs applyPatchChainInMemory
then verifies no fd in /proc/self/fd points at the output file
(Linux-only check; skipped elsewhere). The bug is intermittent on
the spawn path itself, but the fd-not-leaked invariant is the
property the fix guarantees and is the directly testable one.

Documentation

While investigating I confirmed binpatch itself is correct — it
returns the SHA, throws on mismatch, falls back. Two related findings
are now documented because they're easy to miss:

1. from-version annotation is a chain pointer, not a content
   hash. binpatch only verifies the final output SHA; it cannot
   detect a publish pipeline that records from-version: A but
   generated the patch bytes from B. The CI workflow that
   publishes patches MUST pass the version from the generate step,
   not recompute it independently (this is exactly what bit
   getsentry/cli — see
   getsentry/cli#1327).
   New Security → 'from-version' annotation trust section +
   callout in Wire Contract.
2. Synchronous output-fd release is a documented guarantee. New
   Security → 'Output fd release' section explaining why the
   stream API was wrong and what the new contract is.

Files

• src/bspatch.ts — replace createWriteStream with
  openSync/writeSync/closeSync in applyReaderToFile.
• test/bspatch.test.ts — regression test verifying no fd points
  at the output after apply returns.
• website/src/content/docs/security.md — new sections:
  from-version annotation trust, Output fd release; threat
  model row for compromised publish pipeline.
• website/src/content/docs/wire-contract.md — annotation callout
  in the OCI patches table.
• CHANGELOG.md — [Unreleased] > Fixed and Documentation
  entries.

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-07-31 17:44 UTC