feat: add distro-agnostic PRoot/Chroot support for 39-bit Android

[estiaksoyeb]

This PR addresses a critical "Out of Memory" crash (MmapAligned() failed) encountered
when running the Antigravity CLI in non-Termux environments on Android, such as Ubuntu
chroots (Proot/Chroot).

The Problem:

The upstream binary uses TCMalloc, which assumes a 48-bit Virtual Address (VA) space.
Most ARM64 Android kernels are limited to a 39-bit VA space. While the current Python
binary patch helps, it is often insufficient for early-stage allocations in certain
environments, and the current C bootstrapper is hardcoded specifically for Termux-only
file paths.

The Solution:

I have implemented a robust Runtime Mmap Interposer and an Environment-Aware
Bootstrapper.

1. Dynamic Memory Redirection (lib/mmap_va39_fix.c)

• Intercepts mmap calls at runtime.
• Detects if a hint address exceeds the 39-bit boundary (2^39) and clears it.
• This allows the kernel to safely place allocations in valid memory ranges,
  preventing the TCMalloc abort.

2. Smart Bootstrapper (lib/agy_helper.c)

• Environment Detection: Automatically detects if it is running in native Termux
  or a standard Linux chroot (Ubuntu/Debian).
• Dynamic Path Resolution: Configures the correct glibc loader
  (/lib/ld-linux-aarch64.so.1) and SSL certificates
  (/etc/ssl/certs/ca-certificates.crt) based on the detected environment.
• Auto-Preload: Automatically injects the memory fixer library using the glibc
  --preload flag.

3. CI/CD & Build Updates:

• build.sh now compiles the compatibility library as a shared object.
• The GitHub Actions workflow now packages the lib/ directory into the standalone
  release.

Verification Results:

Tested on an ARM64 Android device (Kernel 5.4) across two environments:

• Native Termux: Continues to work as expected (backward compatible).
• Ubuntu 24.04 Chroot: Successfully launches without LD_PRELOAD manual intervention.

Files Changed:

• lib/mmap_va39_fix.c (New)
• lib/agy_helper.c (Updated)
• build.sh (Updated)
• .github/workflows/auto-sync-release.yml (Updated)
• UBUNTU_CHROOT_COMPAT.md (Technical Documentation)

[wallentx]

Thanks for the PR! This is a huge help.

Could you rebase your branch on dev? I recently added some strict CI checks to the pipeline (cppcheck, compiler warning gates, and build tests) that will run against your changes. The new CI will also upload built artifacts directly to the workflow run summary, so we can download and test them on the fly.

Also, I'd like to tweak the architecture a bit to keep the release archive clean. Instead of packaging a lib/ folder in the tarball, we can dynamically embed the interposer:

1. Build-time: Convert libmmap_va39_fix.so into a static byte array inside agy_helper.c.
2. Runtime: Have agy unpack the .so to a temp directory (checking $TMPDIR, the bin folder, or /tmp) and preload it on the fly.

This keeps the standalone footprint limited strictly to bin/.

Let me know if you want me to drop in the C/Bash code snippets to handle the hex-conversion and runtime unpacking, happy to help!

[wallentx]

@estiaksoyeb I realized that what i was suggesting was a very specific thing, so I'm going to push those changes to this PR if that is okay with you.

[Copilot]

Pull request overview

This PR adds a runtime mmap interposer and updates the bootstrap/build flow to improve Antigravity CLI compatibility in Ubuntu/Debian chroot or proot environments on Android 39-bit VA kernels.

Changes:

• Adds a mmap interposer shared library and embeds it into the launcher at build time.
• Updates agy_helper.c to detect Termux vs chroot, unpack/preload the interposer, and adjust loader/library/certificate paths.
• Updates docs, README, gitignore, and PR validation workflow to account for generated transient artifacts.

Reviewed changes

Copilot reviewed 6 out of 7 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
README.md	Documents the new chroot/proot compatibility architecture and embedded interposer flow.
lib/mmap_va39_fix.c	Adds the runtime mmap interposer for clearing high VA hint addresses.
lib/agy_helper.c	Adds environment detection, interposer unpacking, preload injection, and chroot path handling.
docs/UBUNTU_CHROOT_COMPAT.md	Adds technical documentation for the compatibility layer.
build.sh	Builds the interposer, generates the embedded byte header, and compiles the launcher with it.
.gitignore	Ignores generated interposer build artifacts.
.github/workflows/pr-check.yml	Generates transient headers for lint/static-analysis jobs and updates strict compile checks.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[estiaksoyeb]

Thanks, appreciate it! I was planning to rebase anyway since the recent changes caused some conflicts on my side. But you did great work implementing the architecture changes directly in this PR.

[wallentx]

@estiaksoyeb CI has produced this artifact https://github.com/wallentx/antigravity-cli-termux/actions/runs/26542545809/artifacts/7253387988 https://github.com/wallentx/antigravity-cli-termux/actions/runs/26552654844/artifacts/7257053241 if you'd like to test it. If it comes back good, I'll go ahead and merge

gh api \
  -H "Accept: application/vnd.github+json" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  /repos/wallentx/antigravity-cli-termux/actions/artifacts/7257053241/zip > artifact.zip

Or

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -o artifact.zip \
  "https://api.github.com/repos/wallentx/antigravity-cli-termux/actions/artifacts/7257053241/zip"

[wallentx]

I tried in my Arch proot, and got:

32569 third_party/tcmalloc/internal/system_allocator.h:595] MmapAligned() failed - unable to allocate with tag (hint=0x2c1d00000000, size=1073741824, alignment=1073741824) - is something limiting address placement?
32569 third_party/tcmalloc/internal/system_allocator.h:602] Note: the allocation may have failed because TCMalloc assumes a 48-bit virtual address space size; you may need to rebuild TCMalloc with TCMALLOC_ADDRESS_BITS defined to your system's virtual address space size
32569 third_party/tcmalloc/arena.cc:61] CHECK in Alloc: FATAL ERROR: Out of memory trying to allocate internal tcmalloc data (bytes=131072, object-size=16384); is something preventing mmap from succeeding (sandbox, VSS limitations)?
Aborted

But agy.va39 worked fine. I'm not sure if this is accidental or if I mixed up something. Will review later this evening

[wallentx]

Nice! This now works in my Arch proot distro too.

agy still needed the host distro’s shared libraries at startup, and it was only pointing glibc to the Ubuntu/Debian-style multiarch paths like /lib/aarch64-linux-gnu.
The latest commit also adds standard Linux library locations like /lib, /usr/lib, /lib64, and /usr/lib64, making the bootstrapper distro-agnostic enough to work across Arch and other PRoot environments 🎉