From 17b35f67d97c41347ef54e1797025c4cbd896bc7 Mon Sep 17 00:00:00 2001
From: Markus Hartung <mail@hartmark.se>
Date: Fri, 21 Aug 2026 20:00:40 -0300
Subject: [PATCH] fix(cli): scoping android instrumentation-hook diagnosis to
 real platform signal (#10028)

---
 bin/cli/utils/ensureAndroidCacheDir.mjs             | 13 +++++++++----
 .../fixes/10028-windows-instrumentation-hook.md     |  1 +
 tests/unit/termux-android-cache-dir.test.ts         | 13 +++++++++++++
 3 files changed, 23 insertions(+), 4 deletions(-)
 create mode 100644 changelog.d/fixes/10028-windows-instrumentation-hook.md

diff --git a/bin/cli/utils/ensureAndroidCacheDir.mjs b/bin/cli/utils/ensureAndroidCacheDir.mjs
index 30fe073f8b..0e3f2d20ec 100644
--- a/bin/cli/utils/ensureAndroidCacheDir.mjs
+++ b/bin/cli/utils/ensureAndroidCacheDir.mjs
@@ -94,10 +94,15 @@ export function ensureAndroidCacheDir(options = {}) {
  */
 export function isFatalInstrumentationHookFailure(text) {
   if (!text) return false;
-  return (
-    /Unsupported platform:\s*android/i.test(text) ||
-    /error occurred while loading instrumentation hook/i.test(text)
-  );
+  // Next.js wraps ANY throw inside instrumentation.register() with the generic
+  // "An error occurred while loading instrumentation hook:" prefix, on every
+  // platform (node_modules/next/dist/server/web/globals.js). That prefix alone
+  // therefore cannot identify the Android/Termux cache-probe failure — a bare
+  // generic instrumentation error on win32/desktop would be misreported as the
+  // Android bug and hide the real cause. Only match when the text actually
+  // carries the Android platform marker that Next's getCacheDirectory() emits.
+  // #10028
+  return /Unsupported platform:\s*android/i.test(text);
 }
 
 /**
diff --git a/changelog.d/fixes/10028-windows-instrumentation-hook.md b/changelog.d/fixes/10028-windows-instrumentation-hook.md
new file mode 100644
index 0000000000..9879e2f3f3
--- /dev/null
+++ b/changelog.d/fixes/10028-windows-instrumentation-hook.md
@@ -0,0 +1 @@
+- fix(cli): stop diagnosing every Next.js instrumentation-hook failure as the Android/Termux cache bug — only the Android "Unsupported platform: android" signal now triggers the Android hint, so a win32/desktop instrumentation error surfaces its real cause instead of a useless `mkdir -p ~/.cache` (#10028)
\ No newline at end of file
diff --git a/tests/unit/termux-android-cache-dir.test.ts b/tests/unit/termux-android-cache-dir.test.ts
index 09c6b3b535..a99c197ec7 100644
--- a/tests/unit/termux-android-cache-dir.test.ts
+++ b/tests/unit/termux-android-cache-dir.test.ts
@@ -166,6 +166,19 @@ test("isFatalInstrumentationHookFailure: matches Next.js android + hook errors",
   assert.equal(isFatalInstrumentationHookFailure(""), false);
 });
 
+test("isFatalInstrumentationHookFailure: BUG #10028 — generic non-Android instrumentation failure is not Android/Termux", () => {
+  // Next.js wraps ANY throw inside instrumentation.register() with the generic
+  // "An error occurred while loading instrumentation hook:" prefix, on every
+  // platform. Without an actual Android/"Unsupported platform:" signal, that
+  // generic wrapper must NOT be diagnosed as the Android/Termux cache-dir bug,
+  // or a plain win32/desktop failure gets a useless `mkdir -p ~/.cache` hint
+  // and the real cause is hidden.
+  const genericWindowsFailure =
+    "Error: An error occurred while loading instrumentation hook: " +
+    "Cannot find module 'C:\\Users\\dev\\.omniroute\\config.json'";
+  assert.equal(isFatalInstrumentationHookFailure(genericWindowsFailure), false);
+});
+
 test("formatAndroidInstrumentationFailureHint: names the cache dir and TERMUX_GUIDE", () => {
   const hint = formatAndroidInstrumentationFailureHint("/data/home/.cache");
   assert.match(hint, /\/data\/home\/\.cache/);