@rightkit/release 0.2.164 → 0.2.172

package/README.md

@@ -15,7 +15,7 @@ Signing and publication rules are in the workspace file `docs/rules/release-sign
 
 Release and update builds (`right-release build`, `publish-update`) must not contain any test-automation or debugging surface; the development lane may. Layers, in the order they run:
 
-1. **Source (before anything is built; `right-release build --dry-run` only loads the config and does not reach this layer)** - `qa-build-features.mjs` refuses a build command, a package.json script it runs, or an app `Cargo.toml` that enables `devtools`, `qa-native`, `qa-control`, `dev-native` or `dev-inspect` (also `--all-features`, and `devtools` on the `tauri` dependency, `qa-control` on a non-optional `rightkit-qa-driver`, `dev-inspect` on a non-optional `rightkit-tauri-shell`, a non-optional `tauri-plugin-wdio-webdriver`, or any of them reachable from the default features).
+1. **Source (before anything is built; `right-release build --dry-run` only loads the config and does not reach this layer)** - `qa-build-features.mjs` refuses a build command, a package.json script it runs, or an app `Cargo.toml` that enables `devtools`, `qa-native`, `qa-control`, `dev-native` or `dev-inspect` (also `--all-features`, and `devtools` on the `tauri` dependency, `qa-control` on a non-optional `rightkit-qa-driver` (or `control` on a non-optional `rightkit-qa`; `rightkit-qa/control` is also refused as a feature item), `dev-inspect` on a non-optional `rightkit-tauri-shell`, a non-optional `tauri-plugin-wdio-webdriver`, or any of them reachable from the default features).
 2. **Pre-pack payload scan** - `qa-control-scan.mjs` over the raw EXE (Windows NSIS and portable), the macOS signing set and `notarize.app` (the `.app` going into the DMG; `dmg build` also scans its staging directory), the MSIX `stageDir` before packing, and `target.qaControlScan`. Mach-O, PE and ELF files are matched against five rules: `qa-control-server` (marker `RIGHTKIT-QA-CONTROL-SERVER-PRESENT`), `shell-dev-inspect` (marker `RIGHTKIT-SHELL-DEV-INSPECT-COMPILED`, written by rightkit-tauri-shell's `dev-inspect` feature; no allow-list lifts it), `wdio-webdriver` (2 of 3 of `tauri-plugin-wdio-webdriver`, `tauri_plugin_wdio_webdriver`, `wdio-webdriver:default`), `remote-debugging` (`--remote-debugging-port`, `WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS`) and `tauri-devtools` (`plugin:webview|internal_toggle_devtools`, `toggleDevtoolsHotkey`); each signature also as UTF-16LE. A scan that finds no native binary fails.
 
    Web-bundle mock scan: `release` also runs `assertNoWebBundleMocks` over the frontend dist (`target.webBundleScan`, else `build.frontendDist` of `src-tauri/tauri.conf.json`) before packaging when it already exists (also under `--dry-run`) and after the package command, where a missing or empty dist fails. `right-release bundle-scan` (Node/Python runtime roots) and `identity-scan` (needs the app's declared cdhash/team/identifier) are not automatic: both need app-specific inputs, so each app runs them from its own `checks`.
@@ -69,7 +69,10 @@ Every Right app has absolutely NO access to DevTools; the single exception is Vi
 | Build (SwiftPM apps) | `swift-package` (`windows-stage`, `msix`, `mac-app`) (config schema 1: `windows.{exe,out,searchDirs,include,dependencies,publisher,assets}`, `mac.{executable,bundleId,out,frameworks,resources,entitlements}`) |
 | Install | `install-app` |
 | Publish | `publish`, `upload`, `publish-update`, `github`, `mirror-root-artifact` |
-| Signing | `sign-windows`, `sign-updater`, `signing-agent`, `create-mac-updater` |
+| Signing | `sign-windows`, `sign-updater`, `signing-agent`, `create-mac-updater`, `sign-dev-artifact`, `sign-candidate` |
+| Engine locator | `engine-locate --engine cutright\|genright [--sha256 <hex>] [--json]`: the verified route to the installed CutRight or GenRight engine, also importable as `locateEngine` from `engine-locator.mjs`. The path is fixed (`<LocalAppData or ~/Library/Application Support>/Orthic Labs/<App>/current/bin/<engine>`), must be a regular file (no symlink or junction), and must pass signature and identity checks (macOS: strict codesign, Developer ID Team ID, fixed Identifier, hardened runtime, not ad hoc; Windows: valid Authenticode with the Orthic Labs signer). An optional sha256 pins the exact build. There is no environment variable, path option or PATH search, so release builds never trust a caller-supplied engine path. Exit 1 with a typed `ENGINE_*` code on any failure |
+| Candidate signing | `sign-candidate --platform win\|mac --artifact <dir> --candidate-receipt <receipt.json> --out <binding.json> [--manifest <sign.json>] [--publisher <subject>] [--dry-run]`: signs the exact unsigned candidate bytes in place instead of rebuilding from source. The candidate receipt (`{ schema: 1, files: [{ path, sha256 }] }`) is checked first and any mismatch refuses; Windows signs through Azure Artifact Signing (`--publisher` pins the MSIX signer subject), macOS through Developer ID with fixed identifiers from `--manifest`. Writes a binding receipt (`rebuilt: false`, candidate sha -> signed sha per file). Never builds, notarizes or publishes |
+| Dev artifact signing | `sign-dev-artifact --artifact <dir> --manifest <sign.json> [--metadata <payload.json>] [--evidence <path>] [--dry-run]`: Developer ID signs an existing CI dev artifact per file with fixed identifiers (macOS). It verifies the recorded hashes in the payload metadata (default `payload.json`, `{ schema: 1, files: [{ path, sha256 }] }`) first, signs each sign-manifest entry (`file` relative to the artifact, `identifier` required, nested code before its bundle) through the dev-signing identity (missing Developer ID: `DEV_MAC_SIGNING_DEVELOPER_ID_REQUIRED`, no ad hoc fallback), verifies with `codesign --verify --strict`, reads back Identifier and TeamIdentifier, refreshes the metadata hashes, and writes evidence JSON. Never builds, notarizes or publishes. The payload metadata must sit outside every signed entry (`SIGN_DEV_ARTIFACT_METADATA_IN_SIGNED_ENTRY`). An optional declarative `refresh` in the sign manifest recomputes digests that other JSON files record about signed bytes: `{ "refreshRoot": "<dir inside the artifact>", "refresh": [{ "file", "pointer" (JSON pointer to an existing string), "compute": "sha256-file" \| "sha256-tree-v1" \| "verify-sha256-file", "of", "format"?, "currentMatches"? }] }` (`file` and `of` relative to `refreshRoot`; `sha256-tree-v1` = sha256 over the sorted relative paths, each as path, NUL, 8-byte big-endian length, bytes; `verify-sha256-file` writes nothing and refuses a digest that changed; `format` embeds the digest in a locator string through one `{value}`; `currentMatches` refuses to overwrite a value of another kind, such as a signed attestation locator). Order is enforced: operations run after the entries they read are signed and before the first entry that contains a refreshed file, so that bundle (the wrapper) signs last over the final bytes; an operation may not read what a later one writes. JSON is rewritten in place with key order kept, and a file the writer would have to reformat is refused. Evidence gains a `refresh` list |
 | Checks | `deps`, `hardening`, `harden`, `hardeningscan`, `cargo-target` |
 | Ownership | `ownership`, `ownership-approval`, `ownership-report` |
 | Other | `dev`, `doctor`, `suite-doctor`, `qa`, `dmg`, `cache`, `apple`, `inventory`, `model`, `addon`, `hooks`, `lsclean`, `generate-dmg-background`, `publish cargo`, `publish npm`, `publish swift` |
@@ -93,8 +96,18 @@ right-release install-app --dmg <path.dmg> [--app-name Pulse.app] [--bundle-id d
 
 It mounts the image read-only and hidden (`-nobrowse`), verifies the app (`codesign --verify --deep --strict`, `spctl --assess`, `stapler validate`, bundle id, and Team ID against the installed copy; a Team ID change is refused) before touching the installed copy, stages a `ditto` copy beside it in the destination and verifies that copy, quits the running instance with SIGTERM (15 s, then SIGKILL), swaps the staged copy in (one atomic exchange when the `rightkit-swap` helper is found, otherwise two journaled renames; the old bundle is restored on failure), re-verifies the installed copy, only then moves the old bundle to `~/.Trash/<App> <timestamp>.app`, and relaunches only if it was running or `--relaunch` is given, using `open -g -j -b` (background, hidden, never activated). `--json` emits one lifecycle event per line (`start`, `verified`, `quit`, `replaced`, `relaunched`, `done`/`failed`, among others). `right-release install-app --recover [--dest <dir>] [--app-name <App.app>] [--json]` rolls an interrupted install forward or back from its journal; every install runs that recovery first. Win32 exits with "not implemented on win32". Exit codes: 0 ok, 1 failed, 2 usage, 3 unsupported platform.
 
+The shipped `bin/darwin/rightkit-swap` is Developer ID signed. It is added by `right-release publish npm --package @rightkit/release --local` on the Mac (managed `rightkit cargo build --release -p rightkit-fs --bin rightkit-swap`, `codesign --options runtime --timestamp`, strict verify; CI has no signing secrets, so this package is published locally). `install-app` refuses a helper that exists but is not validly signed (`SWAP_HELPER_UNSIGNED`, naming the fix); with no helper at all it uses the journaled two-rename fallback and logs it (`swap-fallback`, `replaced {swap}`).
+
 Development builds (from `@rightkit/ci` `devArtifact`, Developer ID-signed but not notarized) install with `--dev` and exactly one of `--dmg`, `--zip <path.zip>` (extracted with `ditto -x -k`), or `--app <path.app>`: `right-release install-app --dev --zip dev-mac.zip`. `--dev` still requires `codesign --verify --deep --strict`, a Team ID, no Team ID change, and a bundle-id match; it skips only `spctl` and `stapler`, removes `com.apple.quarantine` from the new bundle only, prints `DEV BUILD (not notarized)`, and sets `dev: true` on every JSON event.
 
+## One fixed path, one identity, one `.previous` (every app)
+
+macOS and Windows tie privacy grants (mic, screen, Files and Folders, Removable Volumes, Full Disk Access) to the path an app runs from and to its code identity. So every app, helper and dev or QA binary installs and updates IN PLACE at ONE fixed path under ONE identity; there is no per-version, per-digest, per-pid or per-build install folder or bundle id. Rollback is a persistent `<name>.previous` beside the fixed path (rename it back); nothing ever runs from `.previous` or from a staging copy.
+
+- `install-app` (macOS) renames the replaced app to `<App>.app.previous` (never the Trash); `install-app --installer <Setup.exe> --dest <folder> --exe <App.exe>` does the same for a Windows folder install. `right-release dev` (mac) installs to `install.destination` (required) with `<dest>.previous` and fails if its designated requirement differs from the installed copy; a portable dev payload installs as `<installRoot>/current` with `current.previous`; the Windows direct installer installs to `current` with `current.previous`.
+- `right-release dev` (mac) signs with the same Developer ID Application identity as release (an app that needs a provisioning profile uses a Developer ID profile); Apple Development certificates are refused with `DEV_MAC_SIGNING_DEVELOPER_ID_REQUIRED`.
+- **Cargo target folders are not stable paths.** The broker's target tree is `<managed>/rightkit-build-control/ws/<hash>/g/<generation>/target/...` and the generation changes; `cargo-guard` uses a hashed `dev-targets/<project>-<hash>` folder. They are build output only, so nothing may run from them. Dev and QA binaries run from a fixed staged path: list them in `development.targets.<platform>.stage` (`[{ source } | { manifestPath, bin, targetTriple?, profile?, name? }]`) and `right-release dev` copies each in place to `<app root>/.rightkit-dev-bin/<triple-or-host>/<name>` (keeping `<name>.previous`); `rightkit-qa` launches from its `.rightkit-qa-bin` stash on every path.
+
 ## Runtime budget gate (crates)
 
 `publish cargo` runs the `runtime budget` step (`runtime-budgets.mjs`) right after the secret scan. Full contract, schema and refusal table: `docs/RUNTIME-BUDGETS.md`.
@@ -109,6 +122,14 @@ What it does not do: run the bench, prove the bench ran, detect `[profile]`, `[p
 
 A real `publish cargo --crate <name>` refuses with `RUNTIME_BUDGET_MISSING` listing every problem; `--dry-run` prints `[FAIL] runtime-budget: ...` and continues.
 
+## QA adoption (mandatory)
+
+RightKit QA is a mandatory component: every Orthic Labs app adopts it. `assertQaAdoption` (`qa-contract.mjs`, next to the native-QA backdoor contract) runs in `release.mjs` beside the package and Cargo contracts on every release, `--dry-run` and `doctor` included, SwiftPM apps without a `package.json` too.
+
+- **Refused:** the app has no QA lane. A lane is the native wdio lane (`right-qa.config.mjs`, validated by `validateQaBackdoorContract`), `@rightkit/qa` in any non-`node_modules` `package.json` (dependencies or devDependencies), or `rightkit-qa` in any `Cargo.toml` (dependencies, dev-dependencies, build-dependencies, `[workspace.dependencies]`; path and workspace declarations count). Message: `RightKit QA is mandatory for every Orthic Labs app, and <app> has no QA lane ... Adopt it: ...`.
+- **Warned:** a `@rightkit/qa`, `@rightkit/qa-chrome` or `rightkit-qa` pin behind the latest published version in `rightkit-versions.json` (`[right-release] QA warning: <app> runs RightKit QA behind the latest published version: <pin> -> <latest> (<file>)`). **Refused** when the lag is a breaking bump (`breakingBump` of `rightkit-drift`: a minor bump below 1.0, a major from 1.0). `@rightkit/qa-chrome` is lag-checked but its presence is not enforced.
+- **Exempt:** only a repository that is not an app. `qa-adoption-exemptions.json` (`nonAppRepositories`: `{ repositoryIdentity, kind: "library" | "tooling", reason }`, matched against the git `origin`) is RightKit-owned, so a change needs a RightKit release; the RightKit source tree is recognised by `packages/release/package.json` named `@rightkit/release`. There is no per-app opt-out, config key or environment switch.
+
 ## Entry points
 
 Bin: `right-release` (`cli/right-release.mjs`). The package has no `exports` map. The CLI is the supported surface.
@@ -156,8 +177,8 @@ For `projectType: "swiftpm"` on mac with `appBeforePackage: true` and no `target
 
 By default every code item is signed with the hardened runtime and no entitlements, so a bundle that needs entitlements on some of its code (an app, a sandboxed extension) declares them per file. Both forms below are optional and backwards compatible; a config of plain path strings signs exactly as before.
 
-- `sign.prePackageFiles[]` entries are a path string or `{ file, entitlements?, hardenedRuntime?, options? }`. `entitlements` is a plist path relative to the release config directory. For a `.app` entry the settings apply to the bundle signature.
-- `sign.nestedCode` is a map from a path inside the bundle (`Contents/...`, forward slashes) to `{ entitlements?, hardenedRuntime?, options? }`. It needs exactly one `.app` entry in `sign.prePackageFiles` to resolve against. Nested code the map does not name keeps the defaults.
+- `sign.prePackageFiles[]` entries are a path string or `{ file, entitlements?, hardenedRuntime?, options?, identifier? }`. `identifier` is the codesign `--identifier` (letters, digits, `.`, `-`): set it on loose tools (for example `legion`, `legion-hook`, `legion-mcp`) so each keeps one stable code identity across builds; it is carried through the plan and signing manifest and checked against the receipt. `entitlements` is a plist path relative to the release config directory. For a `.app` entry the settings apply to the bundle signature.
+- `sign.nestedCode` is a map from a path inside the bundle (`Contents/...`, forward slashes) to `{ entitlements?, hardenedRuntime?, options?, identifier? }`. It needs exactly one `.app` entry in `sign.prePackageFiles` to resolve against. Nested code the map does not name keeps the defaults.
 - `options` are extra codesign `--options` names (`expires`, `hard`, `host`, `kill`, `library`; `runtime` is always on). `hardenedRuntime` may be `true` or omitted: `false` is a config error because a notarized target cannot ship code without it.
 
 Signing order stays inside-out: all nested code, deepest path first (a nested bundle after everything inside it), then the `sign.prePackageFiles` entries in declared order. A `nestedCode` path is signed once, with its own settings, in that sequence; it must exist, must not be a symlink or leave the bundle, and must not be the bundle's main executable (that is signed with the bundle). Every configuration problem found is reported at once, before anything is signed.
@@ -198,6 +219,102 @@ Supported: `title`, `icon` (`.icns` volume icon), `background` (PNG or TIFF), `i
 
 `right-release upload` and `right-release github --release` share one gate (`github-upload-gate.mjs`): both require `--tier patch|update`, the primary checkout with a clean tree, a sealed release built from the current HEAD with matching ownership evidence, and a release config that declares `distribution.provider: "github-releases"` and `distribution.repository` (`--repo` may only repeat it; the `origin` remote is never consulted). The gate makes no network call and also runs on `--dry-run`. Private products publish with `publish-update` and `distribution.provider: "r2-rightapps"`. `github --addon` publishes headless add-ons and takes no tier. Not gated the same way: `github --addon` (no tier), `addon upload` (no provider requirement), and the direct R2 uploaders `upload-large.mjs` and `pub-upload.mjs` (no tier, provider or clean-tree check).
 
+## GitHub Releases updater lane (`publish-update`, `github-releases`)
+
+A public app with an in-app Tauri updater publishes with `right-release publish-update --release <sealed-id> --platform win|mac --tier update` and `distribution: { provider: "github-releases", repository: "<owner>/<repo>", updaterKeyId?: "29395F9FF466261D" }`. It is the r2-rightapps lane with a different destination, not a second signer: the updater bundles are signed by `sign-updater.mjs` with the Right Suite updater key (the one every app uses; no per-app key or trust root), sealed with their `.sig` files, and re-verified by `verifyPublicationRelease` before anything is uploaded. The lane then:
+
+- builds the same `platforms` map the R2 lane builds (`{ <target>: { signature, url } }`), with each `url` the GitHub asset URL `https://github.com/<owner>/<repo>/releases/download/v<version>/<asset>`;
+- uploads each sealed bundle and `.sig` to release `v<version>` (created when missing, never a draft), byte-verifying every asset by download, and refusing, not overwriting, a remote asset whose bytes differ;
+- writes a Tauri v2 static `latest.json` (`version`, `notes`, `pub_date`, `platforms`) and uploads it last, merged with the other platform's entries already on that release (the win and mac runs share one `latest.json`; a different version on the release is refused), so `https://github.com/<owner>/<repo>/releases/latest/download/latest.json` resolves.
+
+`updaterKeyId` is optional; when set, a sealed signature made by any other key refuses the publish (`PUBLICATION_SIGNATURE_KEY_MISMATCH`). Notes come from `RIGHT_RELEASE_NOTES`. `--dry-run` prints the upload plan and the manifest with no network call. Uploads use `gh` (already authenticated); no RightApps token is read.
+
+Updater artifacts are declared as for R2 but need no `key`; `platform` must be a Tauri updater target (`windows-x86_64`, `windows-aarch64`, `darwin-aarch64`, `darwin-x86_64`, `linux-x86_64`, optionally with an installer suffix such as `-nsis`, `-msi`, `-app`, `-appimage`) and file names must match `[A-Za-z0-9._+-]` so GitHub does not rename them:
+
+```js
+targets: {
+  win: {
+    updater: { keyFile: "%APPDATA%/RightKit/updater.key", artifacts: [
+      { file: "src-tauri/target/release/bundle/nsis/Ember_1.2.3_x64-setup.exe", signature: "src-tauri/target/release/bundle/nsis/Ember_1.2.3_x64-setup.exe.sig", platform: "windows-x86_64" },
+    ] },
+    artifacts: ["dist/Ember-1.2.3-portable-win.zip"], // portable zips seal alongside; they are not in latest.json
+  },
+  mac: { updater: { artifacts: [
+    { file: "src-tauri/target/release/bundle/macos/Ember.app.tar.gz", signature: "src-tauri/target/release/bundle/macos/Ember.app.tar.gz.sig", platform: "darwin-aarch64" },
+  ] } },
+}
+```
+
+NSIS, MSI, `.app.tar.gz` and AppImage bundles all work the same way (any file signed by `sign-updater`). With no sealed installer the installer platform-trust check is skipped (reported in the output); installer-bearing seals still run it. The app side: `plugins.updater.endpoints` is the `latest.json` URL above and `plugins.updater.pubkey` is the suite updater public key (see `@rightkit/app-update` README).
+
+## Android (AAB build, Play internal track, dev install)
+
+The Android lane is native Kotlin with Gradle plus Rust `.so` libraries per ABI (`docs/design/android-minimum.md` section 4). It follows the same split as the desktop lanes: `build` never uploads, `upload` never builds.
+
+| Step | Command | Config |
+|---|---|---|
+| Build | `right-release build --platform android` | `targets.android`: `gradle` (`bundle<Variant>Release` only), optional `ndk`, `aab`, `artifacts`, `signing` (see `android-release.mjs`) |
+| Upload | `right-release upload --platform android --release <sealed-id> [--apply]` | top-level `distribution: { provider: "google-play", packageName, track: "internal", releaseStatus?, releaseName?, serviceAccount }` |
+| Dev | `right-release dev --platform android --serial <adb serial>` | `development.targets.android`: `ndk?`, `build` (debug tasks), `install: { kind: "adb", apk, package, activity? }` |
+
+- Build: `targets.android.ndk = { abis?: ["arm64-v8a"], jniLibs: "android/app/src/main/jniLibs", manifestPath?, package?, features?, apiLevel? }` runs `cargo ndk -t <abi> ... -o <jniLibs> build --release` before Gradle. Release defaults to `arm64-v8a`; add `x86_64` only for an emulator-installable bundle. `jniLibs` is generated and emptied before each real build. Gradle then runs `bundleRelease` with the upload keystore passwords handed over only as the path of a transient 0600 properties file. The AAB is scanned and must be signed by the pinned upload certificate.
+- Upload: dry run is the default; `--apply` performs `edits.insert`, `bundles.upload`, `tracks.update` (internal) and `edits.commit`. A debug-signed, unsigned or unpinned bundle is refused. Only the internal track and a non-test package can be named. There is no `--tier`.
+- Secrets: the keystore passwords and the Play service-account JSON live in the OS credential store (macOS Keychain `rightkit-android-<name>`; a protected token file on Windows and Linux, so store the JSON as one line) or in a 0600 file outside the repository, selected by `{ credential: "<name>" }` or `{ file: "<path>" }`. They never appear in the environment, on argv, in config, or in a log; key material found in the environment refuses the command.
+- Dev: a debug build installed by serial (never "the only device") with a package ending in `.dev`, `.qa`, `.test` or `.debug`; release tasks and signing properties are refused.
+
+## Bundled FFmpeg decode sidecar (Ember and other media apps)
+
+An app that decodes video through `rightkit-ffmpeg` ships the verified LGPL `ffmpeg` and `ffprobe` programs as a Tauri `externalBin` sidecar. right-release adds no new bundling mechanism: Tauri bundles the files (mac `Contents/MacOS`, Windows next to the app EXE), and right-release plans them from the catalog the app compiled against, ships the LGPL text and source offer, signs the binaries with the app, and seals their hashes. Set `targets.mac.mediaSidecar` and `targets.win.mediaSidecar`:
+
+```js
+mediaSidecar: {
+  arch: "aarch64",                        // catalog arch, one per build (mac aarch64 | x86_64; win x86_64). Default: the build host.
+  variant: "decode",                      // catalog variant (default "decode")
+  tools: ["ffmpeg", "ffprobe"],           // default both
+  stageDir: "src-tauri/binaries",         // where Tauri finds binaries/<tool>-<triple>[.exe] (default)
+  bundleDir: "Contents/MacOS",            // mac only; "Contents/Resources" if the app looks there instead
+  notices: { dir: "src-tauri/resources/third-party/ffmpeg", sourceOfferContact: "https://example.com/ffmpeg-source" },
+  stage: { cmd: "<runner>", args: ["run", "--bin", "stage-ffmpeg"] },   // optional: your call to rightkit_ffmpeg::stage_external_bin
+  catalog: "path/to/artifacts.json",      // optional; default: the rightkit-ffmpeg crate the app's Cargo graph resolves (metadata, offline)
+}
+```
+
+The app still declares `"externalBin": ["binaries/ffmpeg", "binaries/ffprobe"]` and lists `notices.dir` under Tauri `bundle.resources`; `LIGHTCRAFT_FFMPEG_DIR` and the other lookup places are the app's own. Order of a build:
+
+1. Plan: one approved catalog row per tool for the variant, OS and arch. A missing, pending or stale row, a row without a content digest, or an ambiguous match refuses the release (`MEDIA_SIDECAR_NO_ROW`, `MEDIA_SIDECAR_NOT_APPROVED`, `MEDIA_SIDECAR_AMBIGUOUS_ROW`).
+2. Before the app is built: the row's notice files (the LGPL text and build notes) are copied into `notices.dir` together with a generated `FFMPEG-SOURCE-OFFER.txt` (licence, exact FFmpeg source URL and archive SHA-256, build recipes, component notices, `sourceOfferContact`); then `stage` runs if configured. Staging must use `stage_external_bin`, which checks the catalog content digest (signature-independent) as it copies. right-release does not recompute that digest; it checks that each `<tool>-<triple>[.exe]` exists, is a non-empty file, and records its hash.
+3. Signing: macOS adds `Contents/MacOS/ffmpeg` and `ffprobe` to `sign.nestedCode` (hardened runtime, no entitlements, signed inside-out with the bundle and notarized with the app; the nested signing receipt must show each strict-valid and the app must contain `FFMPEG-SOURCE-OFFER.txt`). Windows signs the staged `.exe` files through `sign-windows` in the same raw-EXE step as the app EXE, before Tauri packs them into the installer, so they land in the `raw-exe` receipt.
+4. Receipt and seal: `media-sidecar.json` (state root) records the catalog row ids and content digests, the pre-sign and signed SHA-256 and size of each binary, the notice digests and the signing mode. `right-release build` refuses to seal a release that configures `mediaSidecar` without it, and on Windows checks each signed digest against the sealed raw-EXE receipt. The sealed `release-manifest.json` carries it as `mediaSidecars`, and publication re-validates its shape.
+
+Linux has catalog and planner support only: the planner maps `linux` to the `*-unknown-linux-gnu` triples and works as soon as the crate catalog carries approved Linux rows, but there is no Linux release target in right-release yet, and the catalog has no Linux rows (they need a Linux build and the crate's identity check; see the rightkit-ffmpeg README). Until then an app ships without video on Linux. Tests (fakes only, no catalog download, binary, signer or notary): `media-sidecar.test.mjs`.
+
+## Generic Tauri externalBin sidecars (any app)
+
+Any app that ships more than the ffmpeg sidecar (MailRight: `mailright-engine`, `mailright-core`) sets `targets.mac.externalBin` / `targets.win.externalBin`: `{ names: [...], arch?, stageDir? ("src-tauri/binaries"), bundleDir? (mac: "Contents/MacOS" | "Contents/Resources"), stage?: { cmd, args? } }`. It is the generic form of the ffmpeg staging above and reuses its target-triple naming (`<name>-<triple>[.exe]`), staged-file checks and signing evidence checks (`external-bin.mjs` over `media-sidecar.mjs`); it has no catalog, notices or manifest seal. `stage` is the app's own build of the files. Windows signs the staged files in the raw-EXE step; macOS signs `<bundleDir>/<name>` as nested code (hardened runtime) and checks the nested receipt. `external-bin.json` (state root) records pre-sign and signed digests. Names that `mediaSidecar` stages (`ffmpeg`, `ffprobe`) are refused here. Tests: `external-bin.test.mjs`.
+
+## Keeping agent writes off the internal drive (`disk agent-env`, `disk probe`)
+
+No agent may write to the internal drive (C: on Windows, the internal disk on macOS); only installed apps go there.
+
+`right-release disk agent-env [--root <dir>] [--format sh|ps1|cmd|json] [--check] [--include-agent-homes]` prints the environment that sends agent and child-tool writes to the external root (default `D:\` on Windows, `/Volumes/D` on macOS; default format `ps1` on Windows, `sh` on macOS). It fails closed: if the root is missing, not writable, on the system drive, or (macOS) not under `/Volumes`, it prints nothing on stdout and exits 1. It never falls back to the internal drive. It creates the target folders under the root. `CARGO_TARGET_DIR` is deliberately not set because RustRight owns cargo targets. `CODEX_HOME` and `CLAUDE_CONFIG_DIR` appear only with `--include-agent-homes`, because moving them requires restarting every chat. `--check` compares the current process environment with the map and lists each variable that is on the internal drive or unset; exit 1 when any is. The paths are the ones RustRight applied to the user environment, in one exported table (`AGENT_ENV_TABLE`, imported by the RustRight broker), relative to the root and the same on both platforms:
+
+| Variables | Path under the root |
+| --- | --- |
+| `TEMP`, `TMP`, `TMPDIR`, `CLAUDE_CODE_TMPDIR` | `agent-cache/tmp` |
+| `XDG_CACHE_HOME`, `XDG_DATA_HOME`, `XDG_STATE_HOME`, `XDG_CONFIG_HOME` | `agent-cache/xdg`, `xdg-data`, `xdg-state`, `xdg-config` |
+| `PNPM_STORE_DIR`, `NUGET_PACKAGES` | `agent-cache/pnpm-store`, `agent-cache/nuget` |
+| `npm_config_cache`, `PIP_CACHE_DIR`, `UV_CACHE_DIR`, `HF_HOME` | `.dev-cache/npm-cache`, `pip`, `uv`, `huggingface` |
+| `YARN_CACHE_FOLDER`, `TORCH_HOME`, `TRANSFORMERS_CACHE`, `PLAYWRIGHT_BROWSERS_PATH`, `PUPPETEER_CACHE_DIR`, `GOCACHE`, `GOMODCACHE`, `DOTNET_CLI_HOME`, `ELECTRON_CACHE`, `DENO_DIR` | `agent-cache/yarn`, `torch`, `transformers`, `playwright`, `puppeteer`, `go-build`, `go-mod`, `dotnet`, `electron`, `deno` |
+| `CODEX_HOME`, `CLAUDE_CONFIG_DIR` (`--include-agent-homes`) | `agent-home/codex`, `agent-home/claude` |
+
+`right-release disk probe [--json]` makes a real attempt to create, then immediately remove, one uniquely named 0-byte file (`.rk-disk-probe-<pid>-<nonce>`) in the user profile root, the local temp (`AppData\Local\Temp`, or `TMPDIR` on macOS), the OS temp and the external root. It writes nothing else. Run it from Claude, Codex and a child process as proof. It exits 1 when `internalWritable` is true (or a probe file could not be removed). `--json` prints exactly:
+
+```json
+{"schema":"rightkit.disk.probe.v1","host":"<hostname>","root":"<external root>","results":[{"location":"profile|local-temp|os-temp|external-root","path":"<directory probed>","outcome":"blocked|allowed|error","code":"<error code or null>"}],"internalWritable":false}
+```
+
+`outcome` is `allowed` (file created and removed), `blocked` (`EACCES`, `EPERM` or `EROFS`) or `error` (directory missing or another failure; `code` says which). `code` is `null` when allowed, except `UNLINK_<code>` when the probe file could not be removed. `internalWritable` is true when profile, local-temp or os-temp is `allowed`.
+
 ## Known issues
 
 - `smol-toml` is pinned exactly. A consumer that depends on a different `smol-toml` version gets a second copy.

package/addon-command.mjs

@@ -4,6 +4,7 @@ import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, renameS
 import os from "node:os";
 import path from "node:path";
 import { spawnSync } from "./background-process.mjs";
+import { swapInPlace } from "./in-place-install.mjs";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { addonManifestSha256, addonRoutes, canonicalAddonManifest, createAddonManifest, downloadImmutableAddOn, immutableAddonManifestUrl, validateAddonConfig, validateAddonManifest } from "./addon-contract.mjs";
 import { assertPrimaryReleaseCheckout } from "./release-invocation.mjs";
@@ -147,7 +148,7 @@ async function adopt(options) {
   if (!immutableAddonManifestUrl(manifest, entry.manifestUrl, entry.manifestSha256)) fail("add-on lock manifestUrl is not immutable");
   const output = path.resolve(options.output);
   const destination = path.join(output, manifest.addon);
-  const stage = `${destination}.tmp-${process.pid}`;
+  const stage = `${destination}.staging`;
   const adoptedFiles = [];
   rmSync(stage, { recursive: true, force: true }); mkdirSync(stage, { recursive: true });
   for (const file of manifest.files) {
@@ -171,19 +172,11 @@ async function adopt(options) {
     }
   }
   copyFileSync(path.join(source, "addon-manifest.json"), path.join(stage, "addon-manifest.json"));
-  // Directory rename is atomic on one filesystem. Move any previous add-on
-  // aside first, restore it if replacement fails, then clean it only after the
-  // new verified tree is in place.
-  const previous = `${destination}.previous-${process.pid}`;
+  // Directory rename is atomic on one filesystem. The previous add-on stays beside the fixed path as
+  // `<destination>.previous` (one copy, rename it back to roll back; never run from it) and is restored if
+  // replacement fails.
   mkdirSync(output, { recursive: true });
-  if (existsSync(destination)) renameSync(destination, previous);
-  try {
-    renameSync(stage, destination);
-  } catch (error) {
-    if (existsSync(previous)) renameSync(previous, destination);
-    throw error;
-  }
-  rmSync(previous, { recursive: true, force: true });
+  swapInPlace({ staging: stage, destination });
   if (temporary) rmSync(temporary, { recursive: true, force: true });
   const repoRoot = git(path.dirname(lockPath), ["rev-parse", "--show-toplevel"]);
   const receipt = path.join(repoRoot, ".right-release", "addons", "adoptions", `${manifest.addon}-${manifest.platform}.json`);

package/android-aab-scan.mjs

@@ -0,0 +1,265 @@
+// Release-tier scan of an Android App Bundle (.aab), read in-process: an AAB is a ZIP, so no unzip, bundletool or
+// jarsigner binary is run. It applies the same refusals the desktop lane applies to its binaries:
+//   - every native library (`<module>/lib/<abi>/*.so`) is an ELF file and goes through the shared QA/debug rules of
+//     qa-control-scan.mjs (QA control marker, wdio WebDriver, remote debugging, devtools, dev-inspect);
+//   - every frontend text file inside the bundle goes through the web-bundle mock markers of qa-control-scan.mjs;
+//   - the bundle must be a well-formed AAB (BundleConfig.pb and a base manifest) with at least one native library, so an
+//     empty or wrong file never reads as "clean";
+//   - the bundle must carry exactly one jarsigner signature block, whose first certificate is returned as a SHA-256
+//     fingerprint (the caller pins it to the expected upload key) and which must not be the Android debug certificate.
+// Fails closed: anything that cannot be read is a finding or a problem, never a pass.
+import { createHash, X509Certificate } from "node:crypto";
+import { mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import zlib from "node:zlib";
+import { bufferQaFindings, webBundleMockFindings } from "./qa-control-scan.mjs";
+
+const ELF_MAGIC = Buffer.from([0x7f, 0x45, 0x4c, 0x46]);
+
+const DEFAULT_LIMITS = Object.freeze({
+  maxEntries: 50_000,
+  maxFileBytes: 2 * 1024 * 1024 * 1024 - 1, // readFileSync ceiling
+  maxEntryBytes: 1024 * 1024 * 1024,
+  totalInflated: 6 * 1024 * 1024 * 1024,
+});
+const limitsOf = (limits) => ({ ...DEFAULT_LIMITS, ...(limits ?? {}) });
+
+export const AAB_REQUIRED_ENTRIES = Object.freeze(["BundleConfig.pb", "base/manifest/AndroidManifest.xml"]);
+const NATIVE_LIB = /^([^/]+)\/lib\/([^/]+)\/([^/]+\.so)$/i;
+const SIGNATURE_BLOCK = /^META-INF\/([^/]+)\.(RSA|DSA|EC)$/i;
+const WEB_FILE = /\.(?:m?js|cjs|html?|css|map)$/i;
+const DEBUG_CERT_MARKER = Buffer.from("Android Debug", "latin1");
+
+// ---- CRC-32 (verifies that an entry was read whole and unmodified) -----------------------------------------------
+const CRC_TABLE = (() => {
+  const table = new Uint32Array(256);
+  for (let n = 0; n < 256; n += 1) {
+    let c = n;
+    for (let k = 0; k < 8; k += 1) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    table[n] = c >>> 0;
+  }
+  return table;
+})();
+export function crc32(buffer) {
+  if (typeof zlib.crc32 === "function") return zlib.crc32(buffer) >>> 0;
+  let c = 0xffffffff;
+  for (let i = 0; i < buffer.length; i += 1) c = CRC_TABLE[(c ^ buffer[i]) & 0xff] ^ (c >>> 8);
+  return (c ^ 0xffffffff) >>> 0;
+}
+
+// ---- ZIP reader (stored and deflate; ZIP64 sizes and offsets) ----------------------------------------------------
+function u64(buffer, offset) {
+  const value = buffer.readBigUInt64LE(offset);
+  if (value > BigInt(Number.MAX_SAFE_INTEGER)) throw new Error("zip64 value out of range");
+  return Number(value);
+}
+
+function findEndOfCentralDirectory(buffer) {
+  const floor = Math.max(0, buffer.length - (22 + 65535));
+  for (let i = buffer.length - 22; i >= floor; i -= 1) {
+    if (buffer.readUInt32LE(i) !== 0x06054b50) continue;
+    if (i + 22 + buffer.readUInt16LE(i + 20) > buffer.length) continue;
+    let entries = buffer.readUInt16LE(i + 10); let size = buffer.readUInt32LE(i + 12); let offset = buffer.readUInt32LE(i + 16);
+    if (entries === 0xffff || size === 0xffffffff || offset === 0xffffffff) {
+      if (i < 20 || buffer.readUInt32LE(i - 20) !== 0x07064b50) throw new Error("zip64 locator missing");
+      const record = u64(buffer, i - 12);
+      if (record + 56 > buffer.length || buffer.readUInt32LE(record) !== 0x06064b50) throw new Error("zip64 end record missing");
+      entries = u64(buffer, record + 32); size = u64(buffer, record + 40); offset = u64(buffer, record + 48);
+    }
+    return { entries, size, offset };
+  }
+  throw new Error("end of central directory not found");
+}
+
+export function listZipEntries(buffer, limits = DEFAULT_LIMITS) {
+  const eocd = findEndOfCentralDirectory(buffer);
+  if (eocd.entries > limits.maxEntries) throw new Error(`more than ${limits.maxEntries} entries`);
+  if (eocd.offset + eocd.size > buffer.length) throw new Error("central directory out of bounds");
+  const out = [];
+  let at = eocd.offset;
+  const end = eocd.offset + eocd.size;
+  for (let n = 0; n < eocd.entries; n += 1) {
+    if (at + 46 > end || buffer.readUInt32LE(at) !== 0x02014b50) throw new Error("bad central directory entry");
+    const flags = buffer.readUInt16LE(at + 8); const method = buffer.readUInt16LE(at + 10);
+    const crc = buffer.readUInt32LE(at + 16);
+    let compressed = buffer.readUInt32LE(at + 20); let uncompressed = buffer.readUInt32LE(at + 24);
+    const nameLength = buffer.readUInt16LE(at + 28); const extraLength = buffer.readUInt16LE(at + 30);
+    const commentLength = buffer.readUInt16LE(at + 32); let localOffset = buffer.readUInt32LE(at + 42);
+    const next = at + 46 + nameLength + extraLength + commentLength;
+    if (next > end) throw new Error("central directory entry out of bounds");
+    const name = buffer.subarray(at + 46, at + 46 + nameLength).toString("utf8");
+    const extra = buffer.subarray(at + 46 + nameLength, at + 46 + nameLength + extraLength);
+    for (let e = 0; e + 4 <= extra.length;) {
+      const id = extra.readUInt16LE(e); const size = extra.readUInt16LE(e + 2);
+      if (id === 0x0001) {
+        let p = e + 4;
+        if (uncompressed === 0xffffffff) { uncompressed = u64(extra, p); p += 8; }
+        if (compressed === 0xffffffff) { compressed = u64(extra, p); p += 8; }
+        if (localOffset === 0xffffffff) localOffset = u64(extra, p);
+      }
+      e += 4 + size;
+    }
+    out.push({ name, flags, method, crc, compressed, uncompressed, localOffset });
+    at = next;
+  }
+  return out;
+}
+
+export function readZipEntry(buffer, entry, limits = DEFAULT_LIMITS) {
+  if (entry.flags & 1) throw new Error("encrypted entry");
+  const at = entry.localOffset;
+  if (at + 30 > buffer.length || buffer.readUInt32LE(at) !== 0x04034b50) throw new Error("bad local header");
+  const start = at + 30 + buffer.readUInt16LE(at + 26) + buffer.readUInt16LE(at + 28);
+  if (start + entry.compressed > buffer.length) throw new Error("entry data out of bounds");
+  if (entry.uncompressed > limits.maxEntryBytes || entry.compressed > limits.maxEntryBytes) throw new Error(`entry larger than ${limits.maxEntryBytes} bytes`);
+  const raw = buffer.subarray(start, start + entry.compressed);
+  let data;
+  if (entry.method === 0) data = raw;
+  else if (entry.method === 8) data = zlib.inflateRawSync(raw, { maxOutputLength: Math.max(1, entry.uncompressed + 1) });
+  else throw new Error(`unsupported compression method ${entry.method}`);
+  if (data.length !== entry.uncompressed) throw new Error("entry size does not match its directory record");
+  if (crc32(data) !== entry.crc) throw new Error("entry CRC-32 mismatch");
+  return data;
+}
+
+// ---- PKCS#7 signature block --------------------------------------------------------------------------------------
+function tlv(buffer, at, limit = buffer.length) {
+  if (at + 2 > limit) throw new Error("DER truncated");
+  const tag = buffer[at]; let length = buffer[at + 1]; let head = 2;
+  if (length & 0x80) {
+    const count = length & 0x7f;
+    if (count === 0 || count > 4 || at + 2 + count > limit) throw new Error("DER length unsupported");
+    length = 0;
+    for (let i = 0; i < count; i += 1) length = length * 256 + buffer[at + 2 + i];
+    head = 2 + count;
+  }
+  const end = at + head + length;
+  if (end > limit) throw new Error("DER truncated");
+  return { tag, start: at, body: at + head, end };
+}
+function children(buffer, node) {
+  const out = [];
+  for (let at = node.body; at < node.end;) {
+    const child = tlv(buffer, at, node.end);
+    out.push(child);
+    at = child.end;
+  }
+  return out;
+}
+
+// DER certificates carried by a PKCS#7 SignedData block, in file order (jarsigner writes the signer first).
+export function pkcs7Certificates(block) {
+  const root = tlv(block, 0);
+  if (root.tag !== 0x30) throw new Error("signature block is not a DER sequence");
+  const [oid, wrap] = children(block, root);
+  if (!oid || oid.tag !== 0x06 || !wrap || wrap.tag !== 0xa0) throw new Error("signature block is not PKCS#7 SignedData");
+  const signed = children(block, wrap)[0];
+  if (!signed || signed.tag !== 0x30) throw new Error("signature block has no SignedData");
+  // SignedData: version, digestAlgorithms, contentInfo, [0] certificates, [1] crls, signerInfos.
+  const certificates = children(block, signed).find((part, index) => index >= 3 && part.tag === 0xa0);
+  if (!certificates) throw new Error("signature block carries no certificate");
+  return children(block, certificates).filter((cert) => cert.tag === 0x30).map((cert) => block.subarray(cert.start, cert.end));
+}
+
+const sha256Hex = (bytes) => createHash("sha256").update(bytes).digest("hex");
+
+function signerOf(blockName, block, problems) {
+  try {
+    const certificates = pkcs7Certificates(block);
+    if (certificates.length === 0) throw new Error("signature block carries no certificate");
+    const der = certificates[0];
+    let subject = null; let notAfter = null;
+    try { const x509 = new X509Certificate(der); subject = x509.subject.replace(/\n/g, ", "); notAfter = Date.parse(x509.validTo); } catch { /* the pinned fingerprint is the authority */ }
+    return { block: blockName, certSha256: sha256Hex(der), certificates: certificates.length, subject, notAfter: Number.isFinite(notAfter) ? notAfter : null, debugCertificate: der.includes(DEBUG_CERT_MARKER) };
+  } catch (error) {
+    problems.push(`${blockName}: ${error.message}`);
+    return null;
+  }
+}
+
+// ---- the AAB scan ------------------------------------------------------------------------------------------------
+// Returns { entries, problems[], findings[], nativeLibs[], webFiles, signature }. `problems` are structural/signature
+// defects, `findings` are test-automation or debugging surfaces; either one refuses the release.
+export function scanAabBuffer(buffer, { allowContentOnlyDevtools = false, limits, label = "<aab>" } = {}) {
+  const lim = limitsOf(limits);
+  const result = { entries: 0, problems: [], findings: [], nativeLibs: [], webFiles: 0, signature: null };
+  let entries;
+  try { entries = listZipEntries(buffer, lim); } catch (error) { result.problems.push(`not a readable ZIP/AAB (${error.message})`); return result; }
+  result.entries = entries.length;
+  const names = new Map();
+  for (const entry of entries) {
+    if (names.has(entry.name)) result.problems.push(`duplicate entry name ${entry.name}`);
+    names.set(entry.name, entry);
+  }
+  for (const required of AAB_REQUIRED_ENTRIES) if (!names.has(required)) result.problems.push(`missing required AAB entry ${required}`);
+  let budget = lim.totalInflated;
+  const read = (entry) => {
+    if ((budget -= entry.uncompressed) < 0) throw new Error("bundle exceeds its inflate budget");
+    return readZipEntry(buffer, entry, lim);
+  };
+  const unscannable = (entry, why) => result.findings.push({ file: `${label}!/${entry.name}`, rule: "unscannable", reason: `could not scan: ${why}` });
+
+  for (const entry of entries) {
+    if (entry.name.endsWith("/")) continue;
+    const lib = NATIVE_LIB.exec(entry.name);
+    if (lib) {
+      try {
+        const bytes = read(entry);
+        if (!bytes.subarray(0, 4).equals(ELF_MAGIC)) { unscannable(entry, "native library is not an ELF file"); continue; }
+        result.nativeLibs.push({ name: entry.name, module: lib[1], abi: lib[2], size: bytes.length, sha256: sha256Hex(bytes) });
+        for (const finding of bufferQaFindings(bytes, { allowContentOnlyDevtools })) result.findings.push({ file: `${label}!/${entry.name}`, ...finding });
+      } catch (error) { unscannable(entry, error.message); }
+    } else if (WEB_FILE.test(entry.name)) {
+      try {
+        result.webFiles += 1;
+        for (const finding of webBundleMockFindings(read(entry).toString("utf8"))) result.findings.push({ file: `${label}!/${entry.name}`, ...finding });
+      } catch (error) { unscannable(entry, error.message); }
+    }
+  }
+  if (result.nativeLibs.length === 0 && !result.findings.some((f) => f.rule === "unscannable")) {
+    result.problems.push("no native library (<module>/lib/<abi>/*.so) found to scan; cannot verify");
+  }
+
+  const blocks = entries.filter((entry) => SIGNATURE_BLOCK.test(entry.name));
+  if (blocks.length === 0) result.problems.push("bundle is not signed: no META-INF/*.RSA, *.DSA or *.EC signature block");
+  else if (blocks.length > 1) result.problems.push(`bundle carries ${blocks.length} signature blocks; exactly one upload-key signature is expected`);
+  else {
+    const [block] = blocks;
+    const stem = SIGNATURE_BLOCK.exec(block.name)[1];
+    if (!names.has(`META-INF/${stem}.SF`)) result.problems.push(`signature block ${block.name} has no matching META-INF/${stem}.SF`);
+    if (!names.has("META-INF/MANIFEST.MF")) result.problems.push("signed bundle has no META-INF/MANIFEST.MF");
+    try { result.signature = signerOf(block.name, read(block), result.problems); } catch (error) { result.problems.push(`${block.name}: ${error.message}`); }
+  }
+  return result;
+}
+
+export function scanAab(file, options = {}) {
+  const size = statSync(file).size;
+  const lim = limitsOf(options.limits);
+  if (size > lim.maxFileBytes) return { entries: 0, problems: [`bundle is larger than ${lim.maxFileBytes} bytes`], findings: [], nativeLibs: [], webFiles: 0, signature: null };
+  return scanAabBuffer(readFileSync(file), { ...options, label: options.label ?? file });
+}
+
+// Writes every native library of the bundle to `dir` (flat, index-named, so an entry name can never escape it) and returns
+// the written paths. Lets the caller run path-based layers (release-switch scan) over the same bytes.
+export function extractNativeLibs(file, dir, { limits } = {}) {
+  const lim = limitsOf(limits);
+  const buffer = readFileSync(file);
+  mkdirSync(dir, { recursive: true });
+  const written = [];
+  let index = 0;
+  for (const entry of listZipEntries(buffer, lim)) {
+    if (!NATIVE_LIB.test(entry.name)) continue;
+    const target = path.join(dir, `${String(index += 1).padStart(3, "0")}-${path.basename(entry.name).replace(/[^A-Za-z0-9._-]/g, "_")}`);
+    writeFileSync(target, readZipEntry(buffer, entry, lim));
+    written.push(target);
+  }
+  return written;
+}
+
+export function describeAabProblems(scan) {
+  return [
+    ...scan.problems.map((problem) => `- ${problem}`),
+    ...scan.findings.map((finding) => `- ${finding.file}: ${finding.reason}`),
+  ];
+}

package/android-dev.mjs

@@ -0,0 +1,111 @@
+// right-release dev --platform android: a DEBUG build installed on an emulator or a device through adb. Never a release lane:
+// no keystore, no password, no upload key and no AAB. The release lane (android-release.mjs) and the upload (android-play-upload.mjs)
+// refuse everything this file accepts.
+//
+// Config (development.targets.android):
+//   {
+//     ndk?: { abis?: ["arm64-v8a", "x86_64"], jniLibs: "android/app/src/main/jniLibs", manifestPath?, package?, features?, apiLevel? },
+//     build: [{ cmd: "./gradlew", args: [":app:assembleDebug"], cwd: "android" }],     // debug tasks only (no bundle/assemble Release)
+//     install: { kind: "adb", apk: "android/app/build/outputs/apk/debug/app-debug.apk", package: "com.orthiclabs.heardright.dev",
+//                activity?: ".MainActivity", serial?: "emulator-5554" },
+//   }
+// The device is chosen by serial only, never "the only device": `serial` here, `--serial` on the command line, or
+// RIGHTKIT_ANDROID_SERIAL. The package's last segment must be dev, qa, test or debug, so a dev install can coexist with the
+// production app and can never replace it (rightkit-qa requirement, docs/design/android-minimum.md section 5).
+import { existsSync, statSync } from "node:fs";
+import path from "node:path";
+import { spawnSync } from "./background-process.mjs";
+import { androidNdkCommand, validateAndroidNdk } from "./android-ndk.mjs";
+
+export class AndroidDevelopmentError extends Error {
+  constructor(code, message) { super(message); this.name = "AndroidDevelopmentError"; this.code = code; }
+}
+const refuse = (code, message) => { throw new AndroidDevelopmentError(code, message); };
+
+const SERIAL = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$/;
+const PACKAGE_NAME = /^[A-Za-z][A-Za-z0-9_]*(?:\.[A-Za-z][A-Za-z0-9_]*)+$/;
+const ACTIVITY = /^\.?[A-Za-z][A-Za-z0-9_.$]*$/;
+const TEST_SEGMENT = /^(?:dev|qa|test|debug)$/i;
+const RELEASE_TASK = /(?:bundle|assemble|install)[A-Za-z0-9]*Release|publish|upload/i;
+const inside = (root, child) => { const rel = path.relative(path.resolve(root), path.resolve(child)); return rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel); };
+
+export function androidDevelopmentSerial({ descriptor, serial, env = process.env }) {
+  const chosen = serial ?? descriptor?.serial ?? env.RIGHTKIT_ANDROID_SERIAL;
+  if (!chosen) refuse("DEV_ANDROID_SERIAL_REQUIRED", "name the device by serial (install.serial, --serial or RIGHTKIT_ANDROID_SERIAL); the only attached device is never assumed");
+  if (!SERIAL.test(chosen)) refuse("DEV_ANDROID_SERIAL_INVALID", "the adb serial must be a plain device or emulator serial");
+  return chosen;
+}
+
+// Validates development.targets.android in place of the generic build/install rules. Returns { ndk } (normalised or null).
+export function validateAndroidDevelopment(target, { root }) {
+  for (const [index, command] of target.build.entries()) {
+    const tokens = [command.cmd, ...(command.args ?? [])].map(String);
+    const bad = tokens.find((token) => !token.startsWith("-") && RELEASE_TASK.test(token));
+    if (bad !== undefined) refuse("DEV_ANDROID_RELEASE_TASK", `development.targets.android.build[${index}] runs ${bad}; a dev build is a debug build (assembleDebug), never a release or upload task`);
+    if (tokens.some((token) => /pass(?:word|phrase)?\s*=|storepass|keypass|signing\.(?:store|key)|RIGHTKIT_ANDROID_SIGNING/i.test(token))) {
+      refuse("DEV_ANDROID_SIGNING_ARGUMENT", `development.targets.android.build[${index}] carries a signing property; a dev build uses the debug keystore only`);
+    }
+  }
+  if (target.install !== undefined && target.install.kind !== "adb") refuse("DEV_ANDROID_INSTALL_KIND", "development.targets.android.install.kind must be adb");
+  const ndk = target.ndk === undefined ? null : validateAndroidNdk(target.ndk, { root, kind: "dev" });
+  if (target.install) {
+    const { apk, package: pkg, activity } = target.install;
+    if (typeof apk !== "string" || !/\.apk$/i.test(apk) || path.isAbsolute(apk) || path.win32.isAbsolute(apk) || !inside(root, path.resolve(root, apk))) refuse("DEV_ANDROID_APK_INVALID", "install.apk must be a relative .apk path inside the app");
+    if (/(^|[\\/])release([\\/]|$)|[-_.]release\.apk$/i.test(apk)) refuse("DEV_ANDROID_APK_INVALID", "install.apk names a release output; a dev install is a debug APK");
+    if (typeof pkg !== "string" || !PACKAGE_NAME.test(pkg)) refuse("DEV_ANDROID_PACKAGE_INVALID", "install.package must be the Android applicationId");
+    if (!TEST_SEGMENT.test(pkg.split(".").at(-1))) refuse("DEV_ANDROID_PACKAGE_NOT_TEST", `install.package ${pkg} must end in .dev, .qa, .test or .debug so it never replaces the production app`);
+    if (activity !== undefined && (typeof activity !== "string" || !ACTIVITY.test(activity))) refuse("DEV_ANDROID_ACTIVITY_INVALID", "install.activity must be a class name such as .MainActivity");
+    if (target.install.serial !== undefined && !SERIAL.test(String(target.install.serial))) refuse("DEV_ANDROID_SERIAL_INVALID", "install.serial must be a plain device or emulator serial");
+  }
+  return { ndk };
+}
+
+export function androidDevelopmentNdkCommand(ndk) {
+  return androidNdkCommand(ndk, { profile: "dev" });
+}
+
+export function resolveAdb(env = process.env, { exists = existsSync, platform = process.platform } = {}) {
+  if (env.RIGHTKIT_ADB) return env.RIGHTKIT_ADB;
+  for (const home of [env.ANDROID_HOME, env.ANDROID_SDK_ROOT]) {
+    if (!home) continue;
+    const candidate = path.join(home, "platform-tools", platform === "win32" ? "adb.exe" : "adb");
+    if (exists(candidate)) return candidate;
+  }
+  return "adb";
+}
+
+// Pure: the adb argument lists, in order. No secret is ever part of them.
+export function androidInstallPlan(descriptor, { root, serial }) {
+  const apk = path.resolve(root, descriptor.apk);
+  const base = ["-s", serial];
+  return {
+    apk,
+    serial,
+    steps: [
+      { id: "state", args: [...base, "get-state"] },
+      { id: "install", args: [...base, "install", "-r", "-d", apk] },
+      { id: "verify", args: [...base, "shell", "pm", "path", descriptor.package] },
+      ...(descriptor.activity ? [{ id: "launch", args: [...base, "shell", "am", "start", "-n", `${descriptor.package}/${descriptor.activity}`] }] : []),
+    ],
+  };
+}
+
+// `run` is spawnSync-shaped (tests inject a fake). Every step is bounded; the first failure stops and throws.
+export function installAndroidDevelopment(descriptor, { root, env = process.env, run = spawnSync, serial, adb = resolveAdb(env), log = console.log, stat = statSync } = {}) {
+  const chosen = androidDevelopmentSerial({ descriptor, serial, env });
+  const plan = androidInstallPlan(descriptor, { root, serial: chosen });
+  let size = 0;
+  try { size = stat(plan.apk).size; } catch { /* reported below */ }
+  if (!size) refuse("DEV_ANDROID_APK_MISSING", `the debug APK was not produced: ${descriptor.apk}`);
+  const timeouts = { state: 30_000, install: 5 * 60_000, verify: 30_000, launch: 30_000 };
+  for (const step of plan.steps) {
+    const result = run(adb, step.args, { cwd: root, env, encoding: "utf8", windowsHide: true, shell: false, timeout: timeouts[step.id] });
+    const out = `${result.stdout ?? ""}`.trim();
+    if (result.error || result.status !== 0) refuse(`DEV_ANDROID_${step.id.toUpperCase()}_FAILED`, `adb ${step.id} failed (${result.status ?? "unavailable"}) for ${chosen}${result.error ? `: ${result.error.message}` : ""}`);
+    if (step.id === "state" && out !== "device") refuse("DEV_ANDROID_DEVICE_NOT_READY", `${chosen} is not ready (adb state: ${out || "unknown"})`);
+    if (step.id === "install" && !/Success/i.test(out)) refuse("DEV_ANDROID_INSTALL_FAILED", `adb install did not report Success for ${chosen}`);
+    if (step.id === "verify" && !out.includes("package:")) refuse("DEV_ANDROID_VERIFY_FAILED", `${descriptor.package} is not installed on ${chosen} after the install`);
+  }
+  log(`right-release dev: installed ${descriptor.package} on ${chosen} (debug build; not a release artifact)`);
+  return { serial: chosen, package: descriptor.package, apk: plan.apk };
+}