feat(perps): decouple agentic cache fingerprint from project EAS fingerprint (MetaMask#30569)

## **Description**

Adds `scripts/perps/agentic/lib/compute-cache-fp.js`, an agentic-local
native-build fingerprint, and switches the build cache in
`bc_fingerprint` to use it instead of `scripts/generate-fingerprint.js`.
The project-wide fingerprint script and `fingerprint.config.js` are
untouched, so EAS Build, EAS Update, and the OTA fingerprint guard in
`nightly-ota-updates.md` keep their existing semantics.

**Why:** `--mode auto`'s shared cache (MetaMask#30565) was keyed off the same
fingerprint EAS/OTA depend on, which conservatively hashes build outputs
(`ios/build/`, `.gradle/`, IDE `xcuserdata`, env-populated
`xcconfig`/`google-services.json`). Those paths diverge per worktree, so
two slots on the same commit hashed to different keys and never shared a
cached `.app` — the cross-worktree benefit the cache was designed for
never landed. The new fingerprint uses the same `extraSources` (so
anything that genuinely affects the binary still participates) but
ignores the per-worktree noise paths.

Verified across three worktrees on the same commit (`c06187a24c`, all on
`main`):

```
mm-1: c7fe9e2161109d4ff2e092e068821a2e9984aac5
mm-5: c7fe9e2161109d4ff2e092e068821a2e9984aac5
mm-6: c7fe9e2161109d4ff2e092e068821a2e9984aac5
```

Identical → next `--mode auto` dispatch on any of these slots will
install the cached artifact from whichever slot built first.

## **Changelog**

CHANGELOG entry: null

## **Related issues**

Follows MetaMask#30565.

## **Manual testing steps**

```gherkin
Feature: Agentic cache fingerprint decoupled from project fingerprint

  Scenario: Project fingerprint unchanged
    When I run "node scripts/generate-fingerprint.js"
    Then the hash is the same as on `main` before this PR
    And EAS / OTA tools that depend on it are unaffected

  Scenario: Agentic cache fingerprint ignores build artifacts
    Given a worktree at any state
    When I capture the agentic fingerprint
    And I write a poison file under `ios/build/`
    And I capture the agentic fingerprint again
    Then the two fingerprints are identical

  Scenario: Cross-worktree fingerprint match on same commit
    Given two worktrees (mm-5, mm-6) at the same git commit
    When I compute the agentic fingerprint in each
    Then they match
    And `--mode auto` on the second slot installs from the cached artifact stored by the first
```

Programmatic check the test suite runs:

```bash
bash scripts/perps/agentic/lib/test-build-cache.sh
```

New section "agentic fp ignores build artifacts" verifies the
ignorePaths actually take effect.

## **Screenshots/Recordings**

N/A — script-only change, no UI surface.

### **Before**

N/A

### **After**

N/A

## **Pre-merge author checklist**

- [x] I've followed [MetaMask Contributor
Docs](https://github.com/MetaMask/contributor-docs) and [MetaMask Mobile
Coding
Standards](https://github.com/MetaMask/metamask-mobile/blob/main/.github/guidelines/CODING_GUIDELINES.md).
- [x] I've completed the PR template to the best of my ability
- [x] I've included tests if applicable (new "agentic fp ignores build
artifacts" assertion in `test-build-cache.sh`)
- [x] I've documented my code using [JSDoc](https://jsdoc.app/) format
if applicable (file-level rationale in `compute-cache-fp.js`)
- [x] I've applied the right labels on the PR

#### Performance checks (if applicable)

- [ ] I've tested on Android — N/A (script-only)
- [ ] I've tested with a power user scenario — N/A
- [ ] I've instrumented key operations with Sentry traces — N/A
(developer tooling)

## **Pre-merge reviewer checklist**

- [ ] I've manually tested the PR.
- [ ] I confirm that this PR addresses all acceptance criteria.

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Changes the cache key used for agentic preflight native build reuse;
incorrect ignore/hashing boundaries could cause stale or mismatched
cached binaries across worktrees.
> 
> **Overview**
> Decouples the agentic shared native build cache fingerprint from the
repo-wide EAS/OTA fingerprint by introducing
`scripts/perps/agentic/lib/compute-cache-fp.js` and switching
`bc_fingerprint` to use it.
> 
> The new fingerprint inherits `fingerprint.config.js` `extraSources`
(plus explicitly hashes `app/core/InpageBridgeWeb3.js`) while adding
`ignorePaths` for per-worktree build outputs (e.g., `ios/build`, Xcode
`xcuserdata`, `.gradle`, NDK `.cxx`) so cache artifacts can be shared
across parallel worktrees.
> 
> Updates agentic docs to describe the new keying behavior and extends
`test-build-cache.sh` with boundary tests ensuring ignored paths don’t
shift the fingerprint while binary-affecting sources still do (and
adjusts the fast-mode failure test to reference the new script).
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
32aa686. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: abretonc7s

scripts/perps/agentic/README.md

@@ -224,7 +224,7 @@ Compound: `{ all: [...] }`, `{ any: [...] }`, `{ none: [...] }`.
 | `rebuild-native` | no | yes (no `--repo-update`) | yes | no |
 | `clean` (legacy `--clean`) | yes | yes with `--repo-update` | yes | no (writes only) |
 
-Cache lives in `$MM_BUILD_CACHE_DIR` (default `~/Library/Caches/mm-mobile-builds` on macOS, `~/.cache/mm-mobile-builds` on Linux), keyed by `@expo/fingerprint` hash. Parallel worktrees at the same fingerprint share one artifact through a per-fingerprint mutex: Linux uses `flock(1)` (auto-released by the kernel on process death); macOS, where `flock` is not in base, uses an atomic `mkdir <fp>.lock.d` fallback that is released by the script's `EXIT` trap. If a script is killed with `kill -9` between `mkdir` and the trap, the mutex dir can be left behind — delete it manually under `$MM_BUILD_CACHE_DIR/<plat>/`. Override retention with `BUILD_CACHE_RETAIN=N` (default 5 per platform).
+Cache lives in `$MM_BUILD_CACHE_DIR` (default `~/Library/Caches/mm-mobile-builds` on macOS, `~/.cache/mm-mobile-builds` on Linux), keyed by an agentic `@expo/fingerprint` hash computed by `scripts/perps/agentic/lib/compute-cache-fp.js`. The agentic fingerprint *extends* the project-wide `fingerprint.config.js` (which EAS Build and OTA still consume unchanged) with additional `ignorePaths` for per-worktree build artifacts that don't influence binary semantics (`ios/build/`, `.gradle/`, Xcode `xcuserdata`, NDK `.cxx`, etc.). Binary-affecting inputs — env-populated `xcconfig`, `google-services.json`, and the bundled `InpageBridgeWeb3.js` — stay hashed, so the cache only converges across worktrees when those inputs match. Parallel worktrees at the same fingerprint share one artifact through a per-fingerprint mutex: Linux uses `flock(1)` (auto-released by the kernel on process death); macOS, where `flock` is not in base, uses an atomic `mkdir <fp>.lock.d` fallback that is released by the script's `EXIT` trap. If a script is killed with `kill -9` between `mkdir` and the trap, the mutex dir can be left behind — delete it manually under `$MM_BUILD_CACHE_DIR/<plat>/`. Override retention with `BUILD_CACHE_RETAIN=N` (default 5 per platform).
 
 Invoke directly:
 

scripts/perps/agentic/lib/build-cache.sh

@@ -78,7 +78,10 @@ bc_fingerprint() {
     fi
   fi
   local fp
-  fp=$(node scripts/generate-fingerprint.js 2>/dev/null || true)
+  # Use the agentic fingerprint. It extends the project's fingerprint.config.js
+  # (so EAS/OTA inputs still participate) with additional ignorePaths for
+  # per-worktree build outputs. See compute-cache-fp.js for the rationale.
+  fp=$(node scripts/perps/agentic/lib/compute-cache-fp.js 2>/dev/null || true)
   if [ -z "$fp" ]; then
     return 1
   fi

scripts/perps/agentic/lib/compute-cache-fp.js

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+// compute-cache-fp.js — agentic-local native-build fingerprint for the
+// shared build cache.
+//
+// Relation to the project fingerprint:
+// The repo-wide `scripts/generate-fingerprint.js` is consumed by EAS Build,
+// EAS Update, and the OTA fingerprint guard in
+// `docs/nightly-ota-updates.md`. Its `fingerprint.config.js` deliberately
+// errs on the side of hashing too much — every local build artifact that
+// could conceivably influence the produced binary participates in the key
+// so a hash collision can never reuse a build whose inputs we cannot
+// vouch for.
+//
+// `@expo/fingerprint`'s `createFingerprintAsync(projectRoot, options)`
+// loads `fingerprint.config.js` and applies caller options with these
+// semantics (per `@expo/fingerprint` 0.15.x):
+// - `extraSources`: caller OVERRIDES the config's list when set.
+// - `ignorePaths`: caller is MERGED with the config's list.
+// To stay in sync with future edits to `fingerprint.config.js`, we
+// `require()` it directly and spread its lists into our options. Our
+// added ignorePaths cover per-worktree dev/build artifacts that don't
+// affect binary semantics (compile outputs, IDE state, NDK cache,
+// per-machine `.xcode.env.local`).
+// Binary-affecting inputs — env-populated xcconfig, `google-services.json`,
+// the bridge source — stay hashed. The cache only converges across
+// worktrees when those inputs match, which is the correct behaviour.
+
+const fp = require('@expo/fingerprint');
+// Import the project's config so future additions to its extraSources
+// automatically flow into the agentic fingerprint. Using require here
+// (vs. literally copying the list) means a new entry in
+// `fingerprint.config.js` cannot silently leave the agentic cache
+// behind.
+const projectConfig = require('../../../../fingerprint.config.js');
+
+const options = {
+  // Inherit the project's extraSources and append the runtime JS bridge
+  // source. The bridge is copied into android/ios assets at build time
+  // and embedded in the .jsbundle, so its content affects binary output.
+  extraSources: [
+    ...(projectConfig.extraSources || []),
+    {
+      type: 'file',
+      filePath: 'app/core/InpageBridgeWeb3.js',
+      reasons: ['Bundled into the runtime JS — affects binary behaviour.'],
+    },
+  ],
+  // Per-worktree dev/build state that does not influence the produced
+  // binary. All are gitignored and regenerated locally; ignoring them
+  // lets two slots on the same commit with the same source env share a
+  // cached `.app`/`.apk`.
+  ignorePaths: [
+    'ios/build/**',
+    'ios/.xcode.env.local',
+    'ios/MetaMask.xcworkspace/xcshareddata/swiftpm/**',
+    'ios/**/xcuserdata/**',
+    'android/.gradle/**',
+    'android/app/.cxx/**',
+    'android/app/build/**',
+    // Mirror of app/core/InpageBridgeWeb3.js — already tracked via the
+    // extraSources entry above; ignore the generated copy so we don't
+    // double-count it on rebuild.
+    'android/app/src/main/assets/InpageBridgeWeb3.js',
+  ],
+};
+
+fp.createFingerprintAsync(process.cwd(), options)
+  .then(({ hash }) => {
+    process.stdout.write(hash);
+  })
+  .catch((err) => {
+    process.stderr.write(`compute-cache-fp: ${err.message}\n`);
+    process.exit(1);
+  });

scripts/perps/agentic/lib/test-build-cache.sh

@@ -184,6 +184,74 @@ echo "$out" | grep -qE "Mode:.*clean.*yarn setup" && pass "clean mode header ren
 out=$(_capture_for 10 bash scripts/perps/agentic/preflight.sh --clean --check-only 2>&1 | head -20 || true)
 echo "$out" | grep -qE "Mode:.*clean.*yarn setup" && pass "legacy --clean still maps to clean" || fail "legacy --clean broken"
 
+# ─── 10b. Agentic fp respects the safe/unsafe ignorePath boundary ──
+# compute-cache-fp.js ignores per-worktree build outputs but MUST keep
+# binary-affecting inputs (xcconfig, google-services.json, the bundled
+# InpageBridgeWeb3 source) hashed. Verify both halves of that contract.
+hdr "agentic fp respects ignorePath boundary"
+
+_capture_fp() {
+  bc_memo_cleanup 2>/dev/null || true
+  bc_memo_init
+  bc_fingerprint 2>/dev/null
+}
+
+FP_BASELINE=$(_capture_fp)
+[ -n "$FP_BASELINE" ] && pass "baseline fp computed: ${FP_BASELINE:0:12}" \
+  || fail "baseline fp empty"
+
+# (a) Poisoning an IGNORED path must NOT change fp.
+mkdir -p ios/build
+POISON_IGNORED="ios/build/__bc_test_poison_$$.bin"
+echo "poison-$RANDOM" > "$POISON_IGNORED"
+FP_IGNORED=$(_capture_fp)
+rm -f "$POISON_IGNORED"
+if [ "$FP_BASELINE" = "$FP_IGNORED" ]; then
+  pass "ignored ios/build/ poison did NOT shift fp"
+else
+  fail "ignored ios/build/ poison SHIFTED fp (drift): $FP_BASELINE -> $FP_IGNORED"
+fi
+
+# Restore-trapped poison helper: backs up the file, layers a temporary
+# EXIT trap that restores the file AND re-invokes the suite-level cleanup,
+# then restores the original suite-level trap before returning. Ensures
+# .agent/build-cache cleanup still runs on early abort inside the helper.
+_poison_must_shift_fp() {
+  local label="$1" path="$2"
+  if [ ! -f "$path" ]; then
+    fail "missing $path — cannot run boundary test"
+    return
+  fi
+  local bak="/tmp/__bc_test_$(basename "$path")_$$.bak"
+  cp "$path" "$bak"
+  # Capture the suite-level EXIT trap so we can re-install it after.
+  local prev_trap
+  prev_trap=$(trap -p EXIT)
+  trap "cp '$bak' '$path' 2>/dev/null; rm -f '$bak' 2>/dev/null; cleanup" EXIT
+  echo "// __bc_test_poison_$$ $RANDOM" >> "$path"
+  local fp_after
+  fp_after=$(_capture_fp)
+  cp "$bak" "$path"
+  rm -f "$bak"
+  # Restore the suite-level cleanup trap.
+  eval "${prev_trap:-trap - EXIT}"
+  if [ "$fp_after" != "$FP_BASELINE" ]; then
+    pass "$label DID shift fp (${fp_after:0:12})"
+  else
+    fail "$label was silently ignored — cache could serve stale binary"
+  fi
+}
+
+# (b) Poisoning a HASHED, binary-affecting path MUST change fp.
+_poison_must_shift_fp "InpageBridgeWeb3.js (bridge source)" "app/core/InpageBridgeWeb3.js"
+
+# (c) Poisoning an inherited project extraSource MUST change fp — proves
+# the script repeats fingerprint.config.js extraSources correctly.
+_poison_must_shift_fp "scripts/setup.mjs (project extraSource)" "scripts/setup.mjs"
+
+# Restore baseline state for the rest of the suite.
+_capture_fp >/dev/null
+
 # ─── 11. Memo cleanup refuses inherited / unowned BC_MEMO_DIR ──────
 # Across R6/R7/R8/R9 codex flagged five attack shapes against the memo
 # directory cleanup. Each scenario sets up a "victim" dir, hands its path
@@ -215,7 +283,7 @@ _memo_attack "R9B: EXIT cleanup on inherited memo"        ""
 # Codex R2 B3: --mode fast must hard-fail if the fingerprint command can't
 # run, instead of silently falling through to the legacy build path.
 hdr "preflight --mode fast / fingerprint failure"
-FP_SCRIPT="scripts/generate-fingerprint.js"
+FP_SCRIPT="scripts/perps/agentic/lib/compute-cache-fp.js"
 FP_BACKUP="${FP_SCRIPT}.test-bak-$$"
 mv "$FP_SCRIPT" "$FP_BACKUP"
 restore_fp() { [ -f "$FP_BACKUP" ] && mv "$FP_BACKUP" "$FP_SCRIPT" 2>/dev/null || true; }