From d0fbbab6231b5c1e2150444abb77b20330f0b5b4 Mon Sep 17 00:00:00 2001 From: Adeloye Adetayo Date: Tue, 10 Nov 2026 03:25:36 +0000 Subject: [PATCH 1/7] docs: add CONTRIBUTING with the branch and release rules The repo had no CONTRIBUTING.md, so nothing stated that pull requests target native-android, that the lock is the only place versions live, or that releases come from a CI artifact. Record those, plus the aarch64-only and guard-before-strip constraints, so a contributor does not have to reverse-engineer them from the workflows. --- CONTRIBUTING.md | 62 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 62 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..f357568 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,62 @@ +# Contributing + +## Branching + +The default branch is **`native-android`**. It is the only branch that ships, and it is what `origin/HEAD` points at. Open every pull request against it. + +``` +native-android <- default, release line, protected in practice + feat/ <- your work +``` + +- Branch off `native-android`, keep the branch focused, and open the PR back into `native-android`. +- Prefix names with `feat/`, `fix/`, `docs/` or `chore/`. Longer-lived trains use `rc*/` or `archive/` as the existing branches do. +- Do not force-push `native-android`; rewrite your own branch instead. +- The `archive/`, `glibc`, `rc6-*` and `test-*` branches are historical. Leave them alone; do not base new work on them. + +## What this project ships + +One Android/aarch64 Bionic ELF for Termux. No PRoot, no glibc, no wrapper in the runtime path. The wrapper line exists as `opencode-wrapper` appendix packaging only, and it stays out of the mainline. + +## Ground rules + +- **aarch64 only.** Do not add a 32-bit (armv7/arm32) target or re-introduce its scripts; that track failed and was removed. +- **Pinned inputs.** Versions, commits and hashes live in [`tools/supply-chain-lock.json`](tools/supply-chain-lock.json), read through [`tools/ocver.py`](tools/ocver.py). Never hardcode a version in a script, workflow or installer — read it from the lock. A version bump means a new lock entry, not an edit to existing pins. +- **Do not edit generated output.** `artifacts/`, `packing/dpkg/work/`, `packing/pacman/pkg/` and versioned packages are build products. +- **Actions are pinned** to immutable commit SHAs with the version in a trailing comment. Use the v6 line where it exists. +- **Shell scripts** use `set -euo pipefail` and fail fast on missing binaries or files. + +## Testing + +```sh +make selfcheck # local consistency checks +``` + +The **Unit Tests** workflow runs the `bats` suite on every push and pull request. Release builds are not part of PR CI: they are dispatched by hand through `build-native-android.yml`, which compiles the pinned source, builds the Bionic OpenTUI library, verifies the FFI guard *before* stripping, and produces an unsigned candidate artifact. + +A change to the build pipeline is not done until that workflow is green. A change to the runtime is not done until the candidate runs on a real device: `--version`, TUI, auth, one real prompt, clean exit. + +## Releases + +Releases are published from CI, never from a maintainer machine: + +1. `build-native-android.yml` produces the candidate plus checksums. +2. The candidate is smoke-tested on a device. +3. `publish-native-android.yml` is dispatched with that run ID; it re-checks provenance and checksums, then publishes [`RELEASE_NOTES.md`](RELEASE_NOTES.md) verbatim. + +Do not upload a locally built binary. Do not tag a release that has no verified CI artifact behind it. + +## Documentation + +Docs are grouped by purpose under [`docs/`](docs/): + +| Folder | Contents | +|---|---| +| `guides/` | How to build, install, migrate, manage plugins | +| `reference/` | How the pipeline works, contracts, design notes | +| `ops/` | Runbooks and maintainer operations | +| `history/` | Superseded material, kept for archaeology | + +When behaviour and docs disagree, fix the doc in the same change as the code. When you add or move a workflow-critical document, update the [`docs/README.md`](docs/README.md) index and the root [`AGENTS.md`](AGENTS.md) map. + +Documents written in Chinese are kept as-is because their evidence trails are still cited. From 34ef28e936a49695127de8c0ad293436dd6fbd16 Mon Sep 17 00:00:00 2001 From: Adeloye Adetayo Date: Tue, 10 Nov 2026 03:25:42 +0000 Subject: [PATCH 2/7] native: retarget to OpenCode 2.2.6 on OpenTUI 0.8.1 / Zig 0.17.0 Upstream v2.2.6 moves OpenTUI from 0.8.0 to 0.8.1, and 0.8.1 declares minimum_zig_version 0.17.0 (.zig-version), so the bump is not version-only: the Zig toolchain pin moves with it. Verified before pinning: - source tarball sha256 4dec545d... matches tools/verify-release-input.py - @opentui/core 0.8.1 gitHead 9a09079c... resolves from the npm registry - zig-x86_64-linux-0.17.0.tar.xz sha256 1cbe9df9... - patch-opencode-source.py and patch-opentui-android.py both apply to the 2.2.6 / 0.8.1 trees (bionic hooks and buffer guards land as expected) - the OpenTUI FFI shim still exposes toSafeNumberPointer, so the top-byte pointer mask still has its anchor build-libopentui.sh now reads the Zig version from the lock instead of hardcoding 0.16.0. --- AGENTS.md | 4 ++-- docs/guides/native-v2-build.md | 12 ++++++------ scripts/ci/build-opencode-source.sh | 2 +- tools/supply-chain-lock.json | 13 ++++++++++++- tools/transplant/build-libopentui.sh | 6 ++++-- 5 files changed, 25 insertions(+), 12 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index a75ed98..5bfb960 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,8 +2,8 @@ ## ACTIVE NATIVE V2 WORK (2026-10-31) -- Release candidate: OpenCode `2.2.5` on Android/Bionic Bun `1.4.4` with OpenTUI `0.8.0` (Zig `0.16.0`). Pins live in `tools/supply-chain-lock.json`; `tools/ocver.py` is the only reader, and `current` drives CI, publishing and `install.sh`. -- `2.2.5` release candidate builds and runs on-device (version, server, TUI); not yet published. +- Release candidate: OpenCode `2.2.6` on Android/Bionic Bun `1.4.4` with OpenTUI `0.8.1` (Zig `0.17.0`). Pins live in `tools/supply-chain-lock.json`; `tools/ocver.py` is the only reader, and `current` drives CI, publishing and `install.sh`. +- `2.2.5` is published and runs on-device (version, server, TUI). `2.2.6` is the current candidate and is not yet released. - Publish only from a CI candidate artifact via `publish-native-android.yml` (it re-checks provenance and checksums); never upload a binary built on a device. - Android bionic tags heap pointers in the top byte; OpenTUI's `toSafeNumberPointer()` rejects them, so `tools/patch-opentui-ffi.py` must run before `Bun.build` (`bytecode:true` makes binary-level JS edits dead). - Build guide: `docs/guides/native-v2-build.md`; transplant details: `docs/reference/transplant.md`. Release builds run in GitHub Actions for reproducibility. On-device local builds are allowed; Termux already is Bionic so no NDK. Needs Termux `python3`, `npm`, `clang`, `make` (`zig` only to rebuild OpenTUI) and network. diff --git a/docs/guides/native-v2-build.md b/docs/guides/native-v2-build.md index b5e970c..bebf91b 100644 --- a/docs/guides/native-v2-build.md +++ b/docs/guides/native-v2-build.md @@ -19,14 +19,14 @@ tag so a tagged copy cannot silently install a later release. `tools/ocver.py` is the only reader. Use it instead of hardcoding: ```sh -python3 tools/ocver.py current # 2.2.5 -python3 tools/ocver.py tag # v2.2.5 +python3 tools/ocver.py current # 2.2.6 +python3 tools/ocver.py tag # v2.2.6 python3 tools/ocver.py field bun_version # 1.4.4 -python3 tools/ocver.py asset source # opencode-2.2.5-android-aarch64-source +python3 tools/ocver.py asset source # opencode-2.2.6-android-aarch64-source ``` -Current release record: OpenCode `2.2.5` (commit `9bbb8ce1…`) on Bun `1.4.4`, -OpenTUI `0.8.0` (commit `738067f4…`), Zig `0.16.0`, `ANDROID_API=28`. Bun `1.4.4` +Current release record: OpenCode `2.2.6` (commit `dc2ffcf8…`) on Bun `1.4.4`, +OpenTUI `0.8.1` (commit `9a09079c…`), Zig `0.17.0`, `ANDROID_API=28`. Bun `1.4.4` is the only supported host and base — upstream `package.json` declares `packageManager: bun@1.4.4`, and there is no 1.4.2 fallback. @@ -82,7 +82,7 @@ explicit gap, never a silent skip. ## Why the transplant tools remain -For 2.2.5, CI compiles directly against the Android Bun ELF and uses only +For 2.2.x, CI compiles directly against the Android Bun ELF and uses only `swap_tui.py` from the transplant tools. The older `transplant.py all` path remains for supported transplant builds; running it on this already compiled 1.4.4 ELF produced a binary that failed on device. diff --git a/scripts/ci/build-opencode-source.sh b/scripts/ci/build-opencode-source.sh index ab1b947..cde2e58 100755 --- a/scripts/ci/build-opencode-source.sh +++ b/scripts/ci/build-opencode-source.sh @@ -68,7 +68,7 @@ OPENCODE_BUN_VERSION="$BUN_VERSION" python3 tools/patch-opencode-source.py "$src cd "$src" "$host_bun" install --frozen-lockfile --ignore-scripts --os=linux --cpu='*' -# bionic tags heap pointers in the top byte; OpenTUI 0.8.0's FFI shim treats +# bionic tags heap pointers in the top byte; OpenTUI's FFI shim treats # them as "Pointer exceeds safe integer range" and the TUI refuses to start. # Patch the installed shim before Bun builds, because build.ts sets # bytecode:true -- editing the JS inside the compiled ELF afterwards does diff --git a/tools/supply-chain-lock.json b/tools/supply-chain-lock.json index 4223241..dd47dd2 100644 --- a/tools/supply-chain-lock.json +++ b/tools/supply-chain-lock.json @@ -1,6 +1,6 @@ { "schema_version": 1, - "current": "2.2.5", + "current": "2.2.6", "opencode": { "2.0.26": { "commit": "9b4ec5714d481559990db0a816d5dec19541a814", @@ -19,6 +19,12 @@ "source_sha256": "04621edf6c47c2c7a36982ef39914d482c16977708fbd7b779f49f928bdc4fba", "bun_version": "1.4.4", "opentui_version": "0.8.0" + }, + "2.2.6": { + "commit": "dc2ffcf8bf26f9e669b6aa22b95f50e12be15e06", + "source_sha256": "4dec545d50bfbce8952360b50e6b9487f4c92d822bb5dab14ac698e8bb933e12", + "bun_version": "1.4.4", + "opentui_version": "0.8.1" } }, "android_bun": { @@ -49,6 +55,11 @@ "commit": "738067f47e940dcec3f5aab74868908574335c6c", "zig_version": "0.16.0", "zig_x86_64_linux_sha256": "70e49664a74374b48b51e6f3fdfbf437f6395d42509050588bd49abe52ba3d00" + }, + "0.8.1": { + "commit": "9a09079c0c7ad0fb2d55404f66a5c453204328dd", + "zig_version": "0.17.0", + "zig_x86_64_linux_sha256": "1cbe9df9f27e6b78d14ccbca43b6703a404ef79ef1c463de901d7f088d4e2026" } }, "source_build_bun_1_4_4": { diff --git a/tools/transplant/build-libopentui.sh b/tools/transplant/build-libopentui.sh index 36c56a1..1060bab 100755 --- a/tools/transplant/build-libopentui.sh +++ b/tools/transplant/build-libopentui.sh @@ -51,8 +51,10 @@ PATCH_DIR="${PATCH_DIR:-$REPO_ROOT/patches/opentui}" INSTALL_PATH="${INSTALL_PATH:-$REPO_ROOT/artifacts/transplant/opentui-bionic/libopentui.so}" GLIBC_LD="${GLIBC_LD:-/data/data/com.termux/files/usr/glibc/lib/ld-linux-aarch64.so.1}" GLIBC_LIB="${GLIBC_LIB:-/data/data/com.termux/files/usr/glibc/lib}" -# Native profile toolchain (w7b recipe). ZIG 0.16.0 native aarch64 build. -ZIG_BIN="${ZIG_BIN:-${TMPDIR:-/tmp}/zig-0.16.0/zig}" +# Native profile toolchain (w7b recipe). Zig version comes from the lock: the +# pinned OpenTUI needs a specific Zig, and 0.8.1 requires 0.17.0. +OPENTUI_ZIG_VERSION="$(python3 -c 'import json,sys; d=json.load(open(sys.argv[1])); print(d["opentui"][d["opencode"][d["current"]]["opentui_version"]]["zig_version"])' "$REPO_ROOT/tools/supply-chain-lock.json")" +ZIG_BIN="${ZIG_BIN:-${TMPDIR:-/tmp}/zig-${OPENTUI_ZIG_VERSION}/zig}" BIONIC_SYSROOT="${BIONIC_SYSROOT:-/data/data/com.termux/files/usr}" BIONIC_HDRFIX="${BIONIC_HDRFIX:-${TMPDIR:-/tmp}/w7b-hdrfix}" BIONIC_LIBM="${BIONIC_LIBM:-/system/lib64/libm.so}" From 323e393fdb03104704629e8820cf89d5bb9d3b7a Mon Sep 17 00:00:00 2001 From: Adeloye Adetayo Date: Wed, 11 Nov 2026 01:42:21 +0000 Subject: [PATCH 3/7] ci: emit a libc file Zig 0.17.0 can parse Zig 0.17 made the --libc schema strict: every field must appear, the new darwin_sdk_dir included, and cc_dir may not be empty for linux targets (Android's os tag). The old file omitted darwin_sdk_dir and sent an empty gcc_dir, so configurer died with 'missing field: darwin_sdk_dir' before compiling anything. Emit cc_dir as gcc_dir, which 0.16 still reads by name and 0.17 accepts as an alias for cc_dir, and point it at the NDK API lib dir that holds crtbegin_so.o. Add the empty darwin_sdk_dir field that 0.17 requires. --- .github/workflows/build-native-android.yml | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/.github/workflows/build-native-android.yml b/.github/workflows/build-native-android.yml index 7585d9c..f1eed7b 100644 --- a/.github/workflows/build-native-android.yml +++ b/.github/workflows/build-native-android.yml @@ -115,12 +115,19 @@ jobs: echo "LLVM_STRIP=$LLVM_STRIP" >> "$GITHUB_ENV" mkdir -p work artifacts/transplant/opentui-bionic { + # Zig 0.17.0 requires every libc field, including the new + # `cc_dir` and `darwin_sdk_dir`, and rejects an empty `cc_dir` for + # linux targets. `gcc_dir` is the 0.16 field name and a 0.17 alias + # for `cc_dir`, so emitting that spelling keeps one file valid on + # either toolchain. cc_dir holds crtbegin_so.o, which for the NDK + # is the same API-level lib dir as crt_dir. echo "include_dir=$SYSROOT/usr/include/aarch64-linux-android" echo "sys_include_dir=$SYSROOT/usr/include" echo "crt_dir=$LIBDIR" echo "msvc_lib_dir=" echo "kernel32_lib_dir=" - echo "gcc_dir=" + echo "gcc_dir=$LIBDIR" + echo "darwin_sdk_dir=" } > work/android-libc.txt sh work/opentui/packages/native/scripts/prepare-zig-deps.sh ( From 9acacf6035e4e9a60e6bb75b3447a42cabac4ef8 Mon Sep 17 00:00:00 2001 From: Adeloye Adetayo Date: Wed, 11 Nov 2026 02:16:24 +0000 Subject: [PATCH 4/7] opentui: keep translate-c inside the bionic sysroot on Zig 0.17 Zig 0.17's translate-c also puts the host /usr/include on the system include path; 0.16 did not. Bionic's ends with #if __has_include_next() #include_next #endif so on 0.17 that include_next resolved to glibc's limits.h and the three translate-c steps died on __GLIBC_USE and gnu/stubs-32.h, before the library compiled at all: /usr/include/x86_64-linux-gnu/bits/libc-header-start.h:74:5: error: function-like macro '__GLIBC_USE' is not defined Inject an empty src/bionic-include-next/limits.h as a system include dir right after the NDK ones, so include_next terminates inside the sysroot. This reproduces 0.16's behaviour, where nothing followed the NDK dirs. The shadow dir is only added when the BIONIC_* env vars are set, so a desktop build still sees the real limits.h. Also route the context ABI translate-c (include/opentui.h) through the same helper. It was the third failing step, and it has no NDK paths of its own, so it fell straight through to the host headers. Verified locally with Zig 0.17.0 and NDK r28: the exact CI command now translates yoga-bridge.h, miniaudio.h and opentui.h, and the complete -Dlibrary-target=aarch64-linux-android.28 build produces an aarch64 libopentui.so with the tlsdesc shim and guard symbols intact. --- tools/patch-opentui-android.py | 46 ++++++++++++++++++++++++++++++++-- 1 file changed, 44 insertions(+), 2 deletions(-) diff --git a/tools/patch-opentui-android.py b/tools/patch-opentui-android.py index f71aa55..65b2c98 100644 --- a/tools/patch-opentui-android.py +++ b/tools/patch-opentui-android.py @@ -47,12 +47,23 @@ def main() -> int: build, "fn addTranslatedCImports(\n b: *std.Build,", """fn addBionicTranslateIncludes(b: *std.Build, step: *std.Build.Step.TranslateC) void { - if (b.graph.environ_map.get("BIONIC_ARCH_INCLUDE")) |path| { + const arch_inc = b.graph.environ_map.get("BIONIC_ARCH_INCLUDE"); + const sys_inc = b.graph.environ_map.get("BIONIC_SYS_INCLUDE"); + if (arch_inc) |path| { step.addSystemIncludePath(.{ .cwd_relative = path }); } - if (b.graph.environ_map.get("BIONIC_SYS_INCLUDE")) |path| { + if (sys_inc) |path| { step.addSystemIncludePath(.{ .cwd_relative = path }); } + if (arch_inc != null or sys_inc != null) { + // Zig 0.17's translate-c also searches the host /usr/include (0.16 did + // not). Bionic ends with `#include_next `, which + // would then resolve to glibc's limits.h and fail on __GLIBC_USE and + // gnu/stubs-32.h. This empty shadow sits right after the NDK dirs, so + // include_next stops inside the sysroot. Kept conditional so a + // desktop build without the NDK still gets the real limits.h. + step.addSystemIncludePath(b.path("src/bionic-include-next")); + } // Nullability is type metadata only. Zig translate-c rejects the NDK's // annotated array parameters, so erase these annotations for translation. step.defineCMacroRaw("_Nullable="); @@ -66,6 +77,19 @@ def main() -> int: b: *std.Build,""", ) + # Bionic's ends with `#include_next `. Zig 0.17's + # translate-c also searches the host /usr/include (0.16 did not), so that + # include_next lands in glibc and dies on __GLIBC_USE / gnu/stubs-32.h. + # This empty file is injected as a system include dir after the NDK ones, + # so include_next stops at the sysroot boundary instead of the host. + shadow = src / "bionic-include-next" + shadow.mkdir(parents=True, exist_ok=True) + (shadow / "limits.h").write_text( + "/* Terminates bionic's `#include_next ` inside the NDK.\n" + " Host glibc limits.h is not a valid target for this sysroot. */\n", + encoding="utf-8", + ) + replace( build, ' miniaudio_translate.addIncludePath(b.path("src"));\n' @@ -84,6 +108,24 @@ def main() -> int: ' module.addImport("yoga", yoga_translate.createModule());', ) + # The context ABI header is translated too, and it includes system headers + # (stdint.h, limits.h). Without the bionic paths its translate-c falls back + # to the host headers just like the other two steps did. + replace( + build, + ' .root_source_file = b.path("include/opentui.h"),\n' + " .target = target,\n" + " .optimize = optimize,\n" + " });\n" + ' module.addImport("context_abi_c", header.createModule());', + ' .root_source_file = b.path("include/opentui.h"),\n' + " .target = target,\n" + " .optimize = optimize,\n" + " });\n" + " addBionicTranslateIncludes(b, header);\n" + ' module.addImport("context_abi_c", header.createModule());', + ) + # Bionic has no libpthread stub: pthread lives in libc. replace( build, From fad22f4b114d6a79a721e49b8836125cb04f5fd2 Mon Sep 17 00:00:00 2001 From: Adeloye Adetayo Date: Wed, 11 Nov 2026 02:17:18 +0000 Subject: [PATCH 5/7] docs: record the Zig 0.17 libc-file and translate-c host-include quirks Both cost a CI cycle: 0.17 rejects an incomplete --libc file, and its translate-c searches the host /usr/include, which bionic's limits.h include_next happily follows. Note them next to the pointer-tagging caveat so the next bump does not rediscover them. --- AGENTS.md | 1 + 1 file changed, 1 insertion(+) diff --git a/AGENTS.md b/AGENTS.md index 5bfb960..451625c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,6 +6,7 @@ - `2.2.5` is published and runs on-device (version, server, TUI). `2.2.6` is the current candidate and is not yet released. - Publish only from a CI candidate artifact via `publish-native-android.yml` (it re-checks provenance and checksums); never upload a binary built on a device. - Android bionic tags heap pointers in the top byte; OpenTUI's `toSafeNumberPointer()` rejects them, so `tools/patch-opentui-ffi.py` must run before `Bun.build` (`bytecode:true` makes binary-level JS edits dead). +- Zig `0.17.0` needs every field in the `--libc` file (`cc_dir` is mandatory for linux/Android) and its `translate-c` also searches the host `/usr/include`, which bionic's `#include_next ` then follows into glibc. `tools/patch-opentui-android.py` injects an empty `src/bionic-include-next/limits.h` to stop that inside the sysroot. - Build guide: `docs/guides/native-v2-build.md`; transplant details: `docs/reference/transplant.md`. Release builds run in GitHub Actions for reproducibility. On-device local builds are allowed; Termux already is Bionic so no NDK. Needs Termux `python3`, `npm`, `clang`, `make` (`zig` only to rebuild OpenTUI) and network. - History: native v2 `2.0.26`/`2.0.28` on Bun `1.4.0`/`1.4.2` were the previous user-facing line. The Bun 1.4.0 candidate from Actions run 38142306988 passed on-device TUI, API, session and real-prompt checks. - Pin current native workflow actions to immutable commit SHAs, with the version in a comment. Use v6 where available. From bc9b4eb51d443006367528ce41df58c1cb47611b Mon Sep 17 00:00:00 2001 From: Adeloye Adetayo Date: Wed, 11 Nov 2026 02:31:27 +0000 Subject: [PATCH 6/7] opentui: hand Bionic's tagged pointers to the FFI instead of masking them 2.2.5 cleared the ARM TBI tag in toSafeNumberPointer so the shim's safe-integer check would pass. The renderer started, but Scudo re-checks the tag in free() and aborts at teardown ("Pointer tag for 0x... was truncated"), i.e. when the user quits. Bun 1.4's FFI keeps all 64 bits for BigInt `ptr` arguments, so return the tagged BigInt unchanged (untagged pointers still become Numbers, matching upstream on every other platform) and stop toBunPointer2 from truncating through Number(). POINTER_UNSAFE stays for the node:ffi backend. The patched return is BigInt.asUintN(64, pointer): identity for the range the checks already enforce, and a rare token the source build greps for in the compiled ELF, because bytecode:true freezes the shim into the binary. Trees patched by the old revision are migrated by dropping the mask line. tests/unit/patch-opentui-ffi.bats covers the patch, idempotency, migration and the drift guard. --- AGENTS.md | 2 +- scripts/ci/build-opencode-source.sh | 17 ++-- tests/unit/patch-opentui-ffi.bats | 117 +++++++++++++++++++++++ tools/patch-opentui-ffi.py | 139 ++++++++++++++++++++++------ 4 files changed, 238 insertions(+), 37 deletions(-) create mode 100644 tests/unit/patch-opentui-ffi.bats diff --git a/AGENTS.md b/AGENTS.md index 451625c..c820e59 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -5,7 +5,7 @@ - Release candidate: OpenCode `2.2.6` on Android/Bionic Bun `1.4.4` with OpenTUI `0.8.1` (Zig `0.17.0`). Pins live in `tools/supply-chain-lock.json`; `tools/ocver.py` is the only reader, and `current` drives CI, publishing and `install.sh`. - `2.2.5` is published and runs on-device (version, server, TUI). `2.2.6` is the current candidate and is not yet released. - Publish only from a CI candidate artifact via `publish-native-android.yml` (it re-checks provenance and checksums); never upload a binary built on a device. -- Android bionic tags heap pointers in the top byte; OpenTUI's `toSafeNumberPointer()` rejects them, so `tools/patch-opentui-ffi.py` must run before `Bun.build` (`bytecode:true` makes binary-level JS edits dead). +- Android bionic tags heap pointers in the top byte; OpenTUI's `toSafeNumberPointer()` rejects them, so `tools/patch-opentui-ffi.py` passes the tagged BigInt straight to Bun's FFI (masking the tag makes Scudo abort at `free()` with "Pointer tag … was truncated"). It must run before `Bun.build` (`bytecode:true` makes binary-level JS edits dead); CI greps the built ELF for the `BigInt.asUintN` marker. - Zig `0.17.0` needs every field in the `--libc` file (`cc_dir` is mandatory for linux/Android) and its `translate-c` also searches the host `/usr/include`, which bionic's `#include_next ` then follows into glibc. `tools/patch-opentui-android.py` injects an empty `src/bionic-include-next/limits.h` to stop that inside the sysroot. - Build guide: `docs/guides/native-v2-build.md`; transplant details: `docs/reference/transplant.md`. Release builds run in GitHub Actions for reproducibility. On-device local builds are allowed; Termux already is Bionic so no NDK. Needs Termux `python3`, `npm`, `clang`, `make` (`zig` only to rebuild OpenTUI) and network. - History: native v2 `2.0.26`/`2.0.28` on Bun `1.4.0`/`1.4.2` were the previous user-facing line. The Bun 1.4.0 candidate from Actions run 38142306988 passed on-device TUI, API, session and real-prompt checks. diff --git a/scripts/ci/build-opencode-source.sh b/scripts/ci/build-opencode-source.sh index cde2e58..52f53bf 100755 --- a/scripts/ci/build-opencode-source.sh +++ b/scripts/ci/build-opencode-source.sh @@ -70,9 +70,11 @@ cd "$src" "$host_bun" install --frozen-lockfile --ignore-scripts --os=linux --cpu='*' # bionic tags heap pointers in the top byte; OpenTUI's FFI shim treats # them as "Pointer exceeds safe integer range" and the TUI refuses to start. -# Patch the installed shim before Bun builds, because build.ts sets -# bytecode:true -- editing the JS inside the compiled ELF afterwards does -# nothing. +# The tag must survive to native free() as well -- Scudo aborts with +# "Pointer tag ... was truncated" when it does not -- so the shim hands the +# tagged BigInt to Bun's FFI instead of masking it. Patch the installed shim +# before Bun builds, because build.ts sets bytecode:true -- editing the JS +# inside the compiled ELF afterwards does nothing. python3 "$ROOT/tools/patch-opentui-ffi.py" "$src" cd "$src/packages/cli" # Upstream 2.2.x selects the compile target from OPENCODE_TARGET (env), not @@ -88,10 +90,11 @@ BUN_SOURCE_TARGET_ELF="$target_bun" \ compiled="$src/packages/cli/dist/cli-linux-arm64/bin/opencode" test -s "$compiled" # source maps keep the bundled JS readable in the ELF, so this proves the -# pointer mask survived into the build (bytecode:true makes it unpatched at -# runtime otherwise). -grep -aq '0x00ffffffffffffffn' "$compiled" || { - echo "opentui top-byte pointer mask missing from the compiled ELF" >&2 +# tagged-pointer passthrough survived into the build (bytecode:true makes it +# unpatched at runtime otherwise). The marker is the u64 clamp the patched +# shim returns: minification drops comments but never a global property access. +grep -aq 'BigInt.asUintN' "$compiled" || { + echo "opentui tagged-pointer passthrough missing from the compiled ELF" >&2 exit 1 } cd "$ROOT" diff --git a/tests/unit/patch-opentui-ffi.bats b/tests/unit/patch-opentui-ffi.bats new file mode 100644 index 0000000..eff598f --- /dev/null +++ b/tests/unit/patch-opentui-ffi.bats @@ -0,0 +1,117 @@ +#!/usr/bin/env bats +# Unit tests for tools/patch-opentui-ffi.py: the shim must keep Bionic's +# top-byte pointer tag intact (Scudo aborts on a truncated tag at free()). + +load '../lib/helper' + +setup() { + make_tmpdir + PATCHER="$(script_path tools/patch-opentui-ffi.py)" + CHUNK_DIR="$TEST_TMPDIR/node_modules/@opentui/core" + mkdir -p "$CHUNK_DIR" + CHUNK_JS="$CHUNK_DIR/chunk-bun-test00000.js" + cat > "$CHUNK_JS" <<'EOF' +var POINTER_NEGATIVE = "Pointer must be non-negative"; +var POINTER_UNSAFE = "Pointer exceeds safe integer range"; +function toPointer(value) { + if (isBun && typeof value === "bigint") { + return toSafeNumberPointer(value); + } + return value; +} +function toSafeNumberPointer(pointer) { + if (pointer < 0n) { + throw new Error(POINTER_NEGATIVE); + } + if (pointer > BigInt(Number.MAX_SAFE_INTEGER)) { + throw new Error(POINTER_UNSAFE); + } + return Number(pointer); +} +function toSafeBigIntPointer(pointer) { + if (pointer < 0) { + throw new Error(POINTER_NEGATIVE); + } + if (!Number.isSafeInteger(pointer)) { + throw new Error(POINTER_UNSAFE); + } + return BigInt(pointer); +} +function toBunPointer(pointer) { + return typeof pointer === "bigint" ? toSafeNumberPointer(pointer) : pointer; +} +function toBunPointer2(pointer) { + return typeof pointer === "bigint" ? Number(pointer) : pointer; +} +EOF +} + +teardown() { + clean_tmpdir +} + +@test "keeps the tagged BigInt instead of throwing or masking it" { + run python3 "$PATCHER" "$TEST_TMPDIR" + [ "$status" -eq 0 ] + grep -q 'return BigInt.asUintN(64, pointer);' "$CHUNK_JS" + # the old tag-stripping patch must not come back: Scudo frees with the tag + ! grep -q '0x00ffffffffffffffn' "$CHUNK_JS" + # the unsafe-range throw survives only in the node:ffi backend + [ "$(grep -c 'throw new Error(POINTER_UNSAFE);' "$CHUNK_JS")" -eq 1 ] + grep -q 'return Number(pointer);' "$CHUNK_JS" +} + +@test "stops toBunPointer2 from truncating the pointer through Number()" { + run python3 "$PATCHER" "$TEST_TMPDIR" + [ "$status" -eq 0 ] + run grep -A2 'function toBunPointer2(pointer)' "$CHUNK_JS" + [[ "$output" == *'return pointer;'* ]] + [[ "$output" != *'Number(pointer)'* ]] +} + +@test "is idempotent" { + run python3 "$PATCHER" "$TEST_TMPDIR" + [ "$status" -eq 0 ] + cp "$CHUNK_JS" "$TEST_TMPDIR/first.js" + run python3 "$PATCHER" "$TEST_TMPDIR" + [ "$status" -eq 0 ] + [[ "$output" == *"already applied"* ]] + cmp -s "$CHUNK_JS" "$TEST_TMPDIR/first.js" +} + +@test "migrates a tree patched by the old tag-stripping revision" { + python3 - "$CHUNK_JS" <<'PY' +import sys +from pathlib import Path + +path = Path(sys.argv[1]) +text = path.read_text() +text = text.replace( + " if (pointer > BigInt(Number.MAX_SAFE_INTEGER)) {\n", + " if (pointer > BigInt(Number.MAX_SAFE_INTEGER)) {\n" + " pointer &= 0x00ffffffffffffffn;\n", +) +path.write_text(text) +PY + run python3 "$PATCHER" "$TEST_TMPDIR" + [ "$status" -eq 0 ] + ! grep -q '0x00ffffffffffffffn' "$CHUNK_JS" + grep -q 'return BigInt.asUintN(64, pointer);' "$CHUNK_JS" +} + +@test "fails loudly when upstream moves the unsafe-integer check" { + python3 - "$CHUNK_JS" <<'PY' +import sys +from pathlib import Path + +path = Path(sys.argv[1]) +text = path.read_text().replace( + "if (pointer > BigInt(Number.MAX_SAFE_INTEGER)) {", + "if (pointer > 9007199254740991n) {", +) +path.write_text(text) +PY + run python3 "$PATCHER" "$TEST_TMPDIR" + [ "$status" -ne 0 ] + [[ "$output" == *"upstream changed the shim"* ]] +} diff --git a/tools/patch-opentui-ffi.py b/tools/patch-opentui-ffi.py index 1473858..35bfb8e 100755 --- a/tools/patch-opentui-ffi.py +++ b/tools/patch-opentui-ffi.py @@ -1,20 +1,30 @@ #!/usr/bin/env python3 -"""Clear top-byte tags from pointers in OpenTUI's Bun FFI shim. +"""Keep Android top-byte pointers intact in OpenTUI's Bun FFI shim. On some Android/Termux builds bionic hands out heap pointers whose top byte carries a tag (top-byte-ignore tagging, e.g. 0xb4000075ac80a000 for a mapping at 0x75ac400000). The address itself stays in the low 48 bits; only the tag byte is extra. -OpenTUI 0.8.0 converts native pointers to JS numbers and rejects anything above -Number.MAX_SAFE_INTEGER, so every tagged pointer looks unsafe and the TUI dies -at ot_context_create with "Pointer exceeds safe integer range" before drawing a -single frame. Unpatched, `opencode --version` and the server keep working -- -only the renderer aborts. +OpenTUI converts native pointers to JS numbers (`toSafeNumberPointer`) and +rejects anything above Number.MAX_SAFE_INTEGER, so every tagged pointer looks +unsafe and the TUI dies at ot_context_create with "Pointer exceeds safe +integer range" before drawing a single frame. -The mask is lossless and strictly additive: a pointer that already fits the -safe range has a zero top byte, so masking changes nothing for it, and only -conversions that used to throw become usable. Untagged platforms are unaffected. +Clearing the tag is not an option: bionic's Scudo allocator re-checks the tag +in free(), so a masked pointer (tag 0x00 for a 0xb4 allocation) aborts at +teardown with "Pointer tag for 0x... was truncated". Bun 1.4's FFI accepts a +BigInt for `ptr` arguments and passes all 64 bits through to native code, so +the fix is to hand tagged pointers over unchanged: + + * `toSafeNumberPointer` returns the BigInt when it exceeds the safe range + (untagged pointers keep returning a plain Number, so every other platform + and every small allocation behaves exactly as upstream); + * `toBunPointer2` stops wrapping the pointer in Number(); bun.toArrayBuffer + takes a BigInt too. + +`POINTER_UNSAFE` remains for the node:ffi backend, which cannot represent +tagged 64-bit pointers at all. patch-opentui-ffi.py """ @@ -23,37 +33,108 @@ import re from pathlib import Path -MASK = "0x00ffffffffffffffn" +# BigInt.asUintN(64, p) is the identity for the 0..2^64-1 range the checks +# above already enforce, and it is far too rare to appear anywhere else in the +# bundle -- which makes it the marker the build greps for in the compiled ELF: +# minification drops comments but never a global property access. +TOKEN = "BigInt.asUintN(64, " +LEGACY_MASK = "0x00ffffffffffffffn" FUNC = re.compile(r"function toSafeNumberPointer\((?P[A-Za-z_$][\w$]*)\)") +BUN2 = re.compile(r"function toBunPointer2\((?P[A-Za-z_$][\w$]*)\)") +UNSAFE_HEAD = r"if \(%s > BigInt\(Number\.MAX_SAFE_INTEGER\)\) \{" +UNSAFE_THROW = "throw new Error(POINTER_UNSAFE);" -def patch_file(path: Path) -> bool | None: - """Return True when patched, False when already patched, None without a shim.""" - text = path.read_text(encoding="utf-8") +def _tagged_return(arg: str, indent: str) -> str: + return ( + f"{indent}// Bionic tags heap pointers in the top byte; Scudo free()\n" + f"{indent}// rejects a cleared tag, so pass the BigInt through untouched.\n" + f"{indent}return {TOKEN}{arg});\n" + ) + + +def _strip_legacy_mask(text: str, arg: str) -> tuple[str, bool]: + """Drop the `ptr &= 0x00ffffffffffffffn` line older releases inserted.""" + pattern = re.compile(rf"^[ \t]*{re.escape(arg)} &= {LEGACY_MASK};\r?\n", re.MULTILINE) + return pattern.subn("", text) + + +def patch_number_pointer(path: Path, text: str) -> tuple[str, bool]: match = FUNC.search(text) if not match: - return None + raise SystemExit( + f"patch-opentui-ffi: {path.name}: no toSafeNumberPointer shim found" + ) arg = match.group("arg") - check = re.search( - rf"^(?P[ \t]*)if \({re.escape(arg)} > BigInt\(Number\.MAX_SAFE_INTEGER\)\)", - text[match.end() :], - re.MULTILINE, + text, stripped = _strip_legacy_mask(text, arg) + patched_return = f"return {TOKEN}{arg});" + unsafe = re.search(UNSAFE_HEAD % re.escape(arg), text[match.end() :]) + if not unsafe: + raise SystemExit( + f"patch-opentui-ffi: {path.name}: toSafeNumberPointer found without " + "its unsafe-integer check; upstream changed the shim" + ) + + check_at = match.end() + unsafe.end() + tail = text[check_at : check_at + 400] + for statement in (patched_return, f"return {arg};", UNSAFE_THROW): + offset = tail.find(statement) + if offset < 0 or offset > 200: + continue + line_start = text.rfind("\n", 0, check_at + offset) + 1 + indent = text[line_start : check_at + offset] + if indent.strip(): + raise SystemExit( + f"patch-opentui-ffi: {path.name}: unexpected text before " + f"{statement}" + ) + if statement == patched_return: + return text, stripped + end = check_at + offset + len(statement) + rest = text[end:] + if rest.startswith("\r\n"): + rest = rest[2:] + elif rest.startswith("\n"): + rest = rest[1:] + return text[:line_start] + _tagged_return(arg, indent) + rest, True + raise SystemExit( + f"patch-opentui-ffi: {path.name}: unsafe-integer check has no " + f"{UNSAFE_THROW} to replace; upstream changed the shim" ) - if not check: + + +def patch_array_buffer_pointer(path: Path, text: str) -> tuple[str, bool]: + match = BUN2.search(text) + if not match: + # Older OpenTUI builds have no second backend; nothing to do. + return text, False + arg = match.group("arg") + body_start = match.end() + body = text[body_start : body_start + 400] + truncate = f'return typeof {arg} === "bigint" ? Number({arg}) : {arg};' + keep = f"return {arg};" + if keep in body: + return text, False + if truncate not in body: raise SystemExit( - f"patch-opentui-ffi: {path}: toSafeNumberPointer found without its " - "unsafe-integer check; upstream changed the shim" + f"patch-opentui-ffi: {path.name}: toBunPointer2 body changed upstream" ) + return text.replace(truncate, keep, 1), True + - position = match.end() + check.start() - if MASK in text[match.start() : position]: - return False +def patch_file(path: Path) -> bool | None: + """Return True when patched, False when already patched, None without a shim.""" + text = path.read_text(encoding="utf-8") + if not FUNC.search(text): + return None - indent = check.group("indent") - insert = f"{indent}{arg} &= {MASK};\n" - path.write_text(text[:position] + insert + text[position:], encoding="utf-8") - return True + text, changed_pointers = patch_number_pointer(path, text) + text, changed_buffer = patch_array_buffer_pointer(path, text) + if changed_pointers or changed_buffer: + path.write_text(text, encoding="utf-8") + return True + return False def main() -> int: @@ -83,7 +164,7 @@ def main() -> int: ) for path in patched: - print(f"patch-opentui-ffi: masked top-byte pointer tags in {path.name}") + print(f"patch-opentui-ffi: kept tagged BigInt pointers intact in {path.name}") if not patched: print(f"patch-opentui-ffi: already applied to {seen} chunk(s)") return 0 From ab27c5ff04b62968d4e407fab386d1190ea7d1c6 Mon Sep 17 00:00:00 2001 From: Adeloye Adetayo Date: Wed, 11 Nov 2026 03:16:16 +0000 Subject: [PATCH 7/7] chore(release): prepare 2.2.6 notes and installer --- README.md | 4 ++-- RELEASE_NOTES.md | 46 ++++++++++++---------------------------------- install.sh | 2 +- 3 files changed, 15 insertions(+), 37 deletions(-) diff --git a/README.md b/README.md index 18b8340..cf2aae9 100644 --- a/README.md +++ b/README.md @@ -17,9 +17,9 @@ curl -fsSL https://github.com/Spectra010s/opencode-termux/raw/native-android/ins opencode ``` -The installer downloads the [GitHub release](https://github.com/Spectra010s/opencode-termux/releases) binary, checks its SHA-256 against the release checksum file, and installs it as `~/.local/bin/opencode`. If `~/.local/bin` is not on `PATH`, it prints the direct command and the exact PATH line to add; it does not silently edit your shell startup files. +The installer downloads the [GitHub release](https://github.com/Spectra010s/opencode-termux/releases) binary, checks its SHA-256 against the release checksum file, and installs it as `~/.local/bin/opencode`, keeping your chats, sign-ins, and configuration. If `~/.local/bin` is not on `PATH`, it prints the direct command and the exact PATH line to add; it does not silently edit your shell startup files. -Once installed this way, `opencode upgrade`, its `opencode update` alias, and the TUI's `/update` use this repository's latest published release and verified installer. To update an APT installation, use `apt update && apt install --only-upgrade opencode`. +Already on an earlier build? Run `opencode upgrade`; its `opencode update` alias and the TUI's `/update` do the same. They point at this repository's verified installer. To update an APT installation, use `apt update && apt install --only-upgrade opencode`. OpenCode is also available from this project's APT source. Follow the [APT setup and install instructions](docs/guides/apt-repository.md). diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index 6519bfa..1a45708 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -1,39 +1,17 @@ -# OpenCode 2.2.5 for Termux +## What changed upstream (2.2.5 → 2.2.6) -OpenCode v2 as a native Android/aarch64 Bionic binary for Termux: no PRoot, no glibc. This release moves the Android build from 2.0.28 to 2.2.5, and fixes the reason the previous 2.2.x candidates died before drawing a single frame. +- **Shared MCP connections**: `pool: true` on an MCP server shares one connection across projects with the same setup, so you run fewer processes and start faster. +- **Scripted runs in worktrees**: `opencode run -w` (or `--worktree=`) starts the session in a new git worktree, and `--archived` keeps CI and scripted sessions out of the inbox, home, and session lists. +- **Session warming**: provider- and model-specific warming settings, including an `interval: "auto"` mode based on cache TTL. +- **`opencode run` waits for its background work**: background shells, subagents, and image jobs finish first (it prints `waiting for N background job(s)`) and the model answers their results before the run exits. There is no time limit, so set a timeout on CI jobs. +- **TUI fixes**: Ctrl+Z suspends while a form or dialog is open, session titles containing newlines no longer crash the TUI, focus stays on an open dialog when a question arrives, and **Scroll on send** keeps your reading position after you submit a prompt. +- **Security**: file reads and media are served as sandboxed downloads, `/api/*` refuses cross-site navigations and requests from disallowed origins, and webfetch/Code Mode URLs that contain credentials are rejected. +- **Also**: MCP servers that are still connecting get up to 2 seconds before a model call, OpenCode Console config requests time out after 5 seconds instead of hanging startup, and `opencode acp` no longer leaves empty IDE sessions behind. -## Install - -```sh -curl -fsSL https://github.com/Spectra010s/opencode-termux/raw/v2.2.5/install.sh | sh -``` - -Then run `opencode`. The installer checks the compressed download and the executable against the release checksums before replacing `~/.local/bin/opencode`, and keeps your chats, sign-ins, and configuration. - -Already on 2.0.28? Run `opencode upgrade`. It points at this verified installer. - -Requires Android 9 (API 28) or newer, aarch64, and about 700 MiB free. - -## What changed upstream (2.2.0 → 2.2.5) - -- **`/goal`**: keep a session working toward an objective until a reviewer confirms it is met (`/goal pause`, `/goal resume`, `/goal clear`). -- **Image generation**: agents can create or edit images through `experimental_image_generate`, enabled automatically when a connected provider has image models. -- **Claude Agent**: sign in with Claude Code (`claude auth login`) and select it in `/connect` to use those models. -- **OpenTUI 0.8**: TUI plugins now require `@opentui/core` and `@opentui/solid` 0.8 or newer; scroll and render-context APIs changed accordingly. -- **Compaction buffer as a percentage**: `"compaction": { "buffer": "20%" }` keeps part of any model's context window free. -- **Fixes**: MCP servers sending messages over 10 MiB no longer get disconnected, calls to a tool named `bash` run as `shell` instead of failing, and `read`/`edit` errors now point at the missing folder or the closest matching lines. - -Desktop-only changes in these versions (persistent desktop terminals, artifacts, the desktop model picker) do not apply to this Termux build. +Desktop-only changes in 2.2.6 (mobile composer dock, GUI plugin themes and slots, tab menu actions) do not apply to this Termux build. ## What changed in this Android build -- Built from pinned OpenCode source with Bun 1.4.4 and OpenTUI 0.8.0 (Zig 0.16.0); versions, hashes, and commits live in [`tools/supply-chain-lock.json`](https://github.com/Spectra010s/opencode-termux/blob/native-android/tools/supply-chain-lock.json). -- The candidate now compiles directly against the pinned Android Bun base and grafts the bionic OpenTUI library onto it. Re-running the old post-compile transplant on a 1.4.4 base produced a binary that died with SIGILL on the first instruction. -- **TUI fix**: Android bionic tags heap pointers in the top byte, and OpenTUI's FFI shim rejected those as unsafe (`Pointer exceeds safe integer range`) before the first frame. The build now masks that tag before the check, so the renderer starts normally. -- `opencode upgrade` still points at this verified installer instead of an incompatible upstream download. `opencode uninstall --dry-run` previews removal; `opencode uninstall` removes the binary and shared cache but keeps user data. - -## Verified build - -The candidate came from [Actions run 41906034445](https://github.com/Spectra010s/opencode-termux/actions/runs/41906034445), built and checked by CI, with `sha256 24e9600d80752a31c052135a75677495fcb0ee694580216aa9dc37a89a75d657`. It was tested: `--version` passed, providers and models listed through the server, and the TUI started. Wider device testing is welcome; report problems at [issues](https://github.com/Spectra010s/opencode-termux/issues). - -Checksums and build inputs are attached to this release. The [source-build guide](https://github.com/Spectra010s/opencode-termux/blob/native-android/docs/guides/native-v2-build.md) shows how to reproduce the build. +- Built from pinned OpenCode source with Bun 1.4.4 and OpenTUI 0.8.1 (Zig 0.17.0); versions, hashes, and commits live in [`tools/supply-chain-lock.json`](https://github.com/Spectra010s/opencode-termux/blob/native-android/tools/supply-chain-lock.json). +- **Quiet shutdown**: 2.2.5 cleared the ARM top-byte tag that bionic puts on heap pointers so the renderer would start, but Scudo re-checks that tag when the memory is freed, so quitting printed a pointer-tag message. Pointers are now handed to Bun's FFI unchanged (Bun 1.4 keeps all 64 bits for `ptr` arguments), so nothing is truncated and shutdown prints nothing. Untagged platforms and small allocations still take the plain-number path upstream uses. +- **OpenTUI 0.8.1 build**: Zig 0.17.0 requires every field in the `--libc` file and its `translate-c` also searches the host include directories. The build now writes the full schema and shadows bionic `limits.h` inside the sysroot, so the Android OpenTUI library builds the same way in CI and on a Termux device. diff --git a/install.sh b/install.sh index e40158c..2d283c3 100644 --- a/install.sh +++ b/install.sh @@ -2,7 +2,7 @@ set -eu repo=Spectra010s/opencode-termux -release_tag=v2.2.5 +release_tag=v2.2.6 if [ "$#" -gt 0 ]; then [ "$#" -eq 2 ] && [ "$1" = --version ] || { echo 'Usage: install.sh [--version X.Y.Z]' >&2; exit 2; } case "$2" in