@deeeed/metamask-harness 0.2.0

package/orchestration/mobile/inject.sh

@@ -0,0 +1,681 @@
+#!/usr/bin/env bash
+# inject.sh — install the mobile harness overlay into a checkout
+#
+# Purpose:
+#   Installs the runner delegate + recipe/script snapshots into the target's
+#   ignored harness dir, and (full mode) the AgenticService app overlay with
+#   backup/rollback, hash markers, and .git/info/exclude hygiene.
+#
+# Inputs (flags / env):
+#   --target <metamask-mobile> (default $PWD)
+#   --allow-dirty-harness-paths   skip dirty/managed-hash refusals
+#   --force-overlay               overwrite a product-owned in-app bridge
+#   --no-git-exclude              skip .git/info/exclude updates
+#   env RECIPE_HARNESS_ROOT, METAMASK_RUNNER_PROTOCOL_ROOT > FARMSLOT_ROOT >
+#   <runner>/.farmslot-root (protocol root provenance)
+#
+# Outputs:
+#   <harness>/manifest.json, <harness>/runner + scripts snapshots,
+#   backup dir + managed-hashes.tsv, added-git-exclude record.
+#   Exit 0 — installed; 1 — refusal (dirty paths/changed managed paths) or
+#   failed install (rolled back); 2 — bad args.
+#
+# Never touches: tracked product files unless --force-overlay (full mode
+# patches NavigationService.ts/App.tsx with backups); nothing outside the
+# target checkout and its .git dir.
+set -euo pipefail
+
+TARGET="$PWD"
+ALLOW_DIRTY=false
+FORCE_OVERLAY=false
+GIT_EXCLUDE=true
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --target) TARGET="$2"; shift 2 ;;
+    --allow-dirty-harness-paths) ALLOW_DIRTY=true; shift ;;
+    --force-overlay) FORCE_OVERLAY=true; shift ;;
+    --no-git-exclude) GIT_EXCLUDE=false; shift ;;
+    -h|--help) echo "Usage: install.sh [--target <metamask-mobile>] [--allow-dirty-harness-paths] [--force-overlay] [--no-git-exclude]"; exit 0 ;;
+    *) echo "Unknown arg: $1" >&2; exit 2 ;;
+  esac
+done
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+RUNNER_DIR="$(cd "${SCRIPT_DIR}/../.." && pwd -P)"
+ADAPTER_DIR="$RUNNER_DIR/library/actions/mobile"
+# compat-overlays: NOT applied here. orchestration/compat-overlays/ holds
+# reversible patches applied only when injecting into HISTORICAL checkouts
+# (replay/eval against old product commits, e.g. pre-RN-0.81 mobile); the
+# operator/recipe-harness skill applies them manually before the rebuild.
+# See orchestration/compat-overlays/README.md.
+# shellcheck disable=SC1091
+. "$SCRIPT_DIR/../lib/hash-helpers.sh"
+# shellcheck disable=SC1091
+for _hp in "$SCRIPT_DIR/../lib/harness-path.sh"; do
+  [ -f "$_hp" ] && { . "$_hp"; break; }
+done
+unset _hp
+if ! command -v harness_root >/dev/null 2>&1; then
+  echo "mm-harness: shared lib orchestration/lib/harness-path.sh not found; reinstall the runner." >&2
+  exit 1
+fi
+TARGET="$(cd "$TARGET" && pwd)"
+METAMASK_RUNNER_DIR="$RUNNER_DIR"
+METAMASK_RUNNER_SOURCE_KIND="runner-self"
+METAMASK_RUNNER_REVISION="$(git -C "$RUNNER_DIR" rev-parse HEAD 2>/dev/null || echo unknown)"
+METAMASK_RUNNER_PROTOCOL_ROOT="${METAMASK_RUNNER_PROTOCOL_ROOT:-${METAMASK_RUNNER_FARMSLOT_ROOT:-${FARMSLOT_ROOT:-}}}"
+if [ -z "$METAMASK_RUNNER_PROTOCOL_ROOT" ] && [ -f "$RUNNER_DIR/.farmslot-root" ]; then
+  METAMASK_RUNNER_PROTOCOL_ROOT="$(cat "$RUNNER_DIR/.farmslot-root")"
+fi
+export METAMASK_RUNNER_DIR METAMASK_RUNNER_SOURCE_KIND METAMASK_RUNNER_REVISION METAMASK_RUNNER_PROTOCOL_ROOT
+CLEANUP_SH="$SCRIPT_DIR/cleanup.sh"
+HARNESS_ROOT="$(harness_root)"
+HARNESS_REL="$HARNESS_ROOT/mobile"
+
+refuse_symlink_destination() {
+  local rel="$1"
+  local path_so_far="$TARGET"
+  IFS='/' read -r -a parts <<< "$rel"
+  for part in "${parts[@]}"; do
+    [ -n "$part" ] || continue
+    path_so_far="$path_so_far/$part"
+    if [ -L "$path_so_far" ]; then
+      echo "Refusing mobile recipe harness install: $rel contains symlink component $path_so_far." >&2
+      return 1
+    fi
+  done
+}
+
+HARNESS_DIR="$(harness_dir "$TARGET" mobile)"
+# refuse_symlink_destination walks every path component, so the deepest path also
+# guards its parents ($HARNESS_REL covers the root segments).
+refuse_symlink_destination "$HARNESS_REL"
+refuse_symlink_destination "app"
+refuse_symlink_destination "app/core"
+refuse_symlink_destination "app/dev-tools/AgenticService"
+refuse_symlink_destination "app/core/NavigationService"
+refuse_symlink_destination "app/components"
+refuse_symlink_destination "app/components/Nav"
+refuse_symlink_destination "app/components/Nav/App"
+if GIT_BACKUP_PATH="$(git -C "$TARGET" rev-parse --git-path recipe-harness/mobile/backup 2>/dev/null)"; then
+  case "$GIT_BACKUP_PATH" in
+    /*) BACKUP_DIR="$GIT_BACKUP_PATH" ;;
+    *) BACKUP_DIR="$TARGET/$GIT_BACKUP_PATH" ;;
+  esac
+else
+  BACKUP_DIR="$HARNESS_DIR/backup-store"
+fi
+OLD_BACKUP_DIR="$HARNESS_DIR/backup"
+if [ "$BACKUP_DIR" != "$OLD_BACKUP_DIR" ] && [ -f "$OLD_BACKUP_DIR/state.env" ] && [ ! -e "$BACKUP_DIR" ]; then
+  mkdir -p "$(dirname "$BACKUP_DIR")"
+  mv "$OLD_BACKUP_DIR" "$BACKUP_DIR"
+fi
+STATE_FILE="$BACKUP_DIR/state.env"
+
+install_v1_runner_assets() {
+  # refuse_symlink_destination walks every path component, so the deepest paths
+  # also guard their parents ($HARNESS_REL covers the root segments).
+  refuse_symlink_destination "$HARNESS_REL/runner"
+  refuse_symlink_destination "$HARNESS_REL/scripts"
+  refuse_symlink_destination "$HARNESS_REL/action-manifest.json"
+  mkdir -p "$HARNESS_DIR"
+  rm -rf "$HARNESS_DIR/runner" "$HARNESS_DIR/scripts"
+  mkdir -p "$HARNESS_DIR/runner/bin" "$HARNESS_DIR/runner/manifests" "$HARNESS_DIR/runner/recipes"
+
+  # Mobile Metro/Watchman observes the product checkout. Copying the full
+  # TypeScript runner tree into the watched checkout while Metro is running can trigger large
+  # file-map recrawls and make the React Native debug bridge unresponsive.
+  # Keep the target overlay lightweight: install a harness-owned delegate plus
+  # manifest/recipe snapshots, and execute the reviewed external runner source
+  # recorded in manifest.json. This preserves the injection contract without
+  # making the runner repo or the watched product checkout own the runtime.
+  # Emit shell-safe lines: %q-quote the interpolated paths (like CLEANUP_COMMAND
+  # below) so a protocol/runner path containing a space — or $()/backtick/
+  # quote — cannot break the generated wrapper or inject at runtime.
+  local runner_protocol_root_q runner_exec_q target_q
+  runner_protocol_root_q="$(printf '%q' "$METAMASK_RUNNER_PROTOCOL_ROOT")"
+  runner_exec_q="$(printf '%q' "$METAMASK_RUNNER_DIR/orchestration/porcelain/metamask-recipe")"
+  target_q="$(printf '%q' "$TARGET")"
+  {
+    printf '%s\n' '#!/usr/bin/env bash'
+    printf '%s\n' 'set -euo pipefail'
+    printf 'TARGET_DIR=%s\n' "$target_q"
+    printf '%s\n' 'if [ -f "$TARGET_DIR/.js.env" ]; then'
+    printf '%s\n' '  set +u'
+    printf '%s\n' '  set -a'
+    printf '%s\n' '  . "$TARGET_DIR/.js.env"'
+    printf '%s\n' '  set +a'
+    printf '%s\n' '  set -u'
+    printf '%s\n' 'fi'
+    printf '%s\n' 'detect_ios_simulator() {'
+    printf '%s\n' '  command -v xcrun >/dev/null 2>&1 || return 0'
+    printf '%s\n' '  node <<'"'"'NODE'"'"''
+    printf '%s\n' "const cp = require('node:child_process');"
+    printf '%s\n' 'let report;'
+    printf '%s\n' "try { report = JSON.parse(cp.execFileSync('xcrun', ['simctl', 'list', 'devices', 'booted', '-j'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] })); } catch { process.exit(0); }"
+    printf '%s\n' "const devices = Object.values(report.devices || {}).flat().filter((device) => device && device.state === 'Booted');"
+    printf '%s\n' "const bundleIds = ['io.metamask', 'io.metamask.flask', 'io.metamask.qa'];"
+    printf '%s\n' 'const withMetaMask = devices.filter((device) => {'
+    printf '%s\n' '  try {'
+    printf '%s\n' "    const apps = cp.execFileSync('xcrun', ['simctl', 'listapps', device.udid], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });"
+    printf '%s\n' '    return bundleIds.some((bundleId) => apps.includes(bundleId));'
+    printf '%s\n' '  } catch { return false; }'
+    printf '%s\n' '});'
+    printf '%s\n' 'const candidates = withMetaMask.length > 0 ? withMetaMask : devices;'
+    printf '%s\n' "if (candidates.length === 1) process.stdout.write(candidates[0].udid || candidates[0].name || '');"
+    printf '%s\n' 'NODE'
+    printf '%s\n' '}'
+    printf '%s\n' 'if [ -z "${IOS_SIMULATOR:-}" ] && [ -z "${ANDROID_DEVICE:-}" ] && [ -z "${ADB_SERIAL:-}" ] && [ -z "${ANDROID_SERIAL:-}" ]; then'
+    printf '%s\n' '  detected_simulator="$(detect_ios_simulator || true)"'
+    printf '%s\n' '  if [ -n "$detected_simulator" ]; then'
+    printf '%s\n' '    export IOS_SIMULATOR="$detected_simulator"'
+    printf '%s\n' '  fi'
+    printf '%s\n' 'fi'
+    if [ -n "$METAMASK_RUNNER_PROTOCOL_ROOT" ]; then
+      printf 'export FARMSLOT_ROOT=${FARMSLOT_ROOT:-%s}\n' "$runner_protocol_root_q"
+    fi
+    printf 'exec %s "$@"\n' "$runner_exec_q"
+  } > "$HARNESS_DIR/runner/bin/metamask-recipe"
+  chmod +x "$HARNESS_DIR/runner/bin/metamask-recipe"
+  if [ -n "$METAMASK_RUNNER_PROTOCOL_ROOT" ]; then
+    printf '%s\n' "$METAMASK_RUNNER_PROTOCOL_ROOT" > "$HARNESS_DIR/runner/.farmslot-root"
+  fi
+  printf '%s\n' "$METAMASK_RUNNER_DIR" > "$HARNESS_DIR/runner/.runner-source"
+  cp "$METAMASK_RUNNER_DIR/library/manifests/mobile.action-manifest.json" "$HARNESS_DIR/action-manifest.json"
+  cp "$METAMASK_RUNNER_DIR/library/manifests/mobile.action-manifest.json" "$HARNESS_DIR/runner/manifests/mobile.action-manifest.json"
+  cp "$METAMASK_RUNNER_DIR/library/manifests/extension.action-manifest.json" "$HARNESS_DIR/runner/manifests/extension.action-manifest.json"
+  if [ -d "$METAMASK_RUNNER_DIR/library/recipes" ]; then
+    rsync -a --delete "$METAMASK_RUNNER_DIR/library/recipes/" "$HARNESS_DIR/runner/recipes/"
+  fi
+  # Canonical recipe-library snapshot: flows/ + library.json so the installed
+  # harness mirrors the runner's library layout.
+  if [ -d "$METAMASK_RUNNER_DIR/library/flows" ]; then
+    mkdir -p "$HARNESS_DIR/runner/flows"
+    rsync -a --delete "$METAMASK_RUNNER_DIR/library/flows/" "$HARNESS_DIR/runner/flows/"
+  fi
+  if [ -f "$METAMASK_RUNNER_DIR/library/library.json" ]; then
+    cp "$METAMASK_RUNNER_DIR/library/library.json" "$HARNESS_DIR/runner/library.json"
+  fi
+  # Installed-layout back-compat (INTENTIONAL): targets keep a flat
+  # <harness>/scripts/ subtree assembled from the runner trees, so installed
+  # consumers are unaffected by runner-repo layout changes.
+  if [ -d "$METAMASK_RUNNER_DIR/orchestration/mobile" ]; then
+    mkdir -p "$HARNESS_DIR/scripts"
+    cp "$METAMASK_RUNNER_DIR/orchestration/mobile/launch.sh" "$HARNESS_DIR/scripts/launch.sh"
+    cp "$METAMASK_RUNNER_DIR/orchestration/mobile/live.sh" "$HARNESS_DIR/scripts/live.sh"
+    cp "$METAMASK_RUNNER_DIR/runner/mobile/verify.sh" "$HARNESS_DIR/scripts/verify.sh"
+    mkdir -p "$HARNESS_DIR/scripts/lib"
+    cp "$METAMASK_RUNNER_DIR/orchestration/lib/harness-path.sh" "$HARNESS_DIR/scripts/lib/harness-path.sh"
+    cp "$METAMASK_RUNNER_DIR/orchestration/lib/path-defaults.json" "$HARNESS_DIR/scripts/lib/path-defaults.json"
+    cp "$METAMASK_RUNNER_DIR/orchestration/lib/recipe-paths.mjs" "$HARNESS_DIR/scripts/lib/recipe-paths.mjs"
+    chmod -R u+rwX,go+rX "$HARNESS_DIR/scripts"
+    find "$HARNESS_DIR/scripts" -type f \( -name '*.sh' -o -name '*.cjs' -o -name '*.mjs' \) -exec chmod +x {} +
+  fi
+  if [ ! -x "$HARNESS_DIR/runner/bin/metamask-recipe" ]; then
+    echo "Refusing mobile recipe harness install: failed to make runner executable." >&2
+    return 1
+  fi
+}
+
+git_tracks_any_under() {
+  git -C "$TARGET" ls-files -- "$1" 2>/dev/null | grep -q .
+}
+
+has_product_owned_mobile_harness() {
+  # If the product repo tracks any first-party harness subtree, installing the
+  # runner overlay must be metadata-only by default. Requiring every marker to be
+  # present is unsafe for partial Mobile checkouts: falling through would
+  # rsync --delete tracked product-owned files without --force-overlay.
+  git_tracks_any_under "app/dev-tools/AgenticService" && return 0
+  # Marker fallback for checkouts where the harness was patched but not tracked.
+  grep -q "AgenticService.install" "$TARGET/app/core/NavigationService/NavigationService.ts" 2>/dev/null \
+    && grep -q "AgentStepHud" "$TARGET/app/components/Nav/App/App.tsx" 2>/dev/null
+}
+
+add_git_exclude_entry() {
+  local entry="$1"
+  local tracking_file="${2:-}"
+  local git_dir
+  local exclude_file
+  if ! git_dir="$(git -C "$TARGET" rev-parse --git-dir 2>/dev/null)"; then
+    return 0
+  fi
+  # Skip if the path is already gitignored (e.g. a temp/-rooted harness under an
+  # existing temp/ rule) — no redundant info/exclude entry needed.
+  if git -C "$TARGET" check-ignore -q "${entry%/}" 2>/dev/null; then
+    return 0
+  fi
+  case "$git_dir" in
+    /*) ;;
+    *) git_dir="$TARGET/$git_dir" ;;
+  esac
+  exclude_file="$git_dir/info/exclude"
+  mkdir -p "$(dirname "$exclude_file")"
+  touch "$exclude_file"
+  if ! grep -qxF "$entry" "$exclude_file"; then
+    echo "$entry" >> "$exclude_file"
+    if [ -n "$tracking_file" ]; then
+      echo "$entry" >> "$tracking_file"
+    fi
+  fi
+}
+
+if [ "$FORCE_OVERLAY" = false ] && has_product_owned_mobile_harness; then
+  install_v1_runner_assets
+  SOURCE_REV="$(git -C "$RUNNER_DIR" rev-parse HEAD 2>/dev/null || echo unknown)"
+  CLEANUP_COMMAND="RECIPE_HARNESS_ROOT=$HARNESS_ROOT $(printf '%q' "$CLEANUP_SH") --target $(printf '%q' "$TARGET")"
+  if [ "$GIT_EXCLUDE" = true ]; then
+    echo "[recipe-harness] Adding local .git/info/exclude entries (removed on cleanup): $HARNESS_ROOT/"
+    add_git_exclude_entry "$HARNESS_ROOT/" "$HARNESS_DIR/added-git-exclude"
+  else
+    echo "[recipe-harness] --no-git-exclude: skipping .git/info/exclude updates; harness overlay paths may show as untracked in git status."
+  fi
+  node -e '
+    const fs = require("fs");
+    const [runnerOwnerDir, runnerOwnerRevision, runnerDir, runnerRevision, runnerSourceKind, adapterRuntime, target, scriptDir, manifestPath, harnessRoot, harnessRel, cleanupCommand] = process.argv.slice(1);
+    const m = {
+      adapter: "mobile",
+      installMode: "product-owned",
+      installedAt: new Date().toISOString(),
+      source: {
+        runnerOwnerDir,
+        runnerOwnerRevision,
+        runnerDir,
+        runnerRevision,
+        runnerSourceKind,
+        adapterRuntime,
+      },
+      target,
+      protocolVersion: "v1",
+      actionManifestPath: harnessRel + "/action-manifest.json",
+      runnerEntrypoint: harnessRel + "/runner/bin/metamask-recipe",
+      runtimeHelpers: {
+        launch: harnessRel + "/scripts/launch.sh",
+        live: harnessRel + "/scripts/live.sh",
+        verify: harnessRel + "/scripts/verify.sh"
+      },
+      installedPaths: [],
+      harnessInstalledPaths: [harnessRel + "/runner", harnessRel + "/scripts", harnessRel + "/action-manifest.json"],
+      patchedFiles: [],
+      productOwnedPaths: [
+        "app/dev-tools/AgenticService",
+        "app/core/NavigationService/NavigationService.ts",
+        "app/components/Nav/App/App.tsx"
+      ],
+      backupDir: null,
+      cleanupCommand,
+      productDiffExcludes: [
+        ":(exclude)" + harnessRoot
+      ],
+      note: "This checkout already contains the Mobile in-app bridge. Runner install only writes recipe-harness metadata and must not overwrite tracked in-app bridge files."
+    };
+    fs.writeFileSync(manifestPath, JSON.stringify(m, null, 2) + "\n");
+  ' "$RUNNER_DIR" "$SOURCE_REV" "$METAMASK_RUNNER_DIR" "$METAMASK_RUNNER_REVISION" "$METAMASK_RUNNER_SOURCE_KIND" "$ADAPTER_DIR" "$TARGET" "$SCRIPT_DIR" "$HARNESS_DIR/manifest.json" "$HARNESS_ROOT" "$HARNESS_REL" "$CLEANUP_COMMAND"
+  echo "Installed mobile recipe harness metadata only (in-app bridge detected): $HARNESS_DIR/manifest.json"
+  exit 0
+fi
+
+# Full-install path: reached when the checkout lacks the bridge, or when
+# --force-overlay was passed to deliberately overwrite a product-owned bridge.
+if [ "$FORCE_OVERLAY" = true ] && has_product_owned_mobile_harness; then
+  echo "[recipe-harness] --force-overlay: OVERWRITING tracked in-app bridge files with the runner overlay:"
+  echo "    app/dev-tools/AgenticService, app/core/NavigationService/NavigationService.ts, app/components/Nav/App/App.tsx"
+  echo "[recipe-harness] Files are backed up and restorable via cleanup. This replaces the checkout's in-app bridge/HUD."
+fi
+if [ "$GIT_EXCLUDE" = false ]; then
+  echo "[recipe-harness] --no-git-exclude: skipping .git/info/exclude updates; harness overlay paths may show as untracked in git status."
+fi
+
+INSTALLED=false
+INSTALL_MUTATING=false
+ROLLBACK_BACKUP_DIR="$BACKUP_DIR"
+ROLLBACK_STATE_FILE="$STATE_FILE"
+REFRESH_BACKUP_DIR=""
+REBASE_BACKUP=false
+
+verify_installed_paths_unchanged() {
+  local hash_file="$BACKUP_DIR/managed-hashes.tsv"
+  if [ ! -f "$hash_file" ]; then
+    return 0
+  fi
+  local rel expected actual conflicts=0 stale_clean=0
+  while IFS=$'\t' read -r rel expected; do
+    [ -n "$rel" ] || continue
+    actual="$(hash_path "$rel")"
+    if [ "$actual" != "$expected" ]; then
+      if git -C "$TARGET" rev-parse --git-dir >/dev/null 2>&1 \
+        && [ -z "$(git -C "$TARGET" status --porcelain -- "$rel")" ]; then
+        echo "Mobile recipe harness managed path changed after install but is clean in git: $rel" >&2
+        echo "  expected: $expected" >&2
+        echo "  actual:   $actual" >&2
+        stale_clean=1
+      else
+        echo "Refusing to refresh mobile recipe harness: managed path changed after install: $rel" >&2
+        echo "  expected: $expected" >&2
+        echo "  actual:   $actual" >&2
+        conflicts=1
+      fi
+    fi
+  done < "$hash_file"
+  if [ "$conflicts" != "0" ]; then
+    cat >&2 <<EOF
+Reinstall would bless local edits as harness-managed and make cleanup unsafe.
+Save/stash product changes or rerun with --allow-dirty-harness-paths if you intentionally want to overwrite and refresh harness-managed state.
+EOF
+    exit 1
+  fi
+  if [ "$stale_clean" != "0" ]; then
+    cat >&2 <<EOF
+Managed hashes are stale, but all changed harness-managed paths are clean in git.
+This usually means the checkout was reset/rebased after a previous harness install.
+Rebaselining the harness backup to the current clean checkout before refreshing.
+EOF
+    REBASE_BACKUP=true
+  fi
+}
+
+if [ -f "$HARNESS_DIR/manifest.json" ] && [ -f "$STATE_FILE" ]; then
+  INSTALLED=true
+  echo "Existing mobile recipe harness found; refreshing injected files from source." >&2
+fi
+
+if [ "$ALLOW_DIRTY" = false ] && [ "$INSTALLED" = true ]; then
+  verify_installed_paths_unchanged
+fi
+
+if [ "$ALLOW_DIRTY" = false ] && [ "$INSTALLED" = false ] && git -C "$TARGET" rev-parse --git-dir >/dev/null 2>&1; then
+  DIRTY_PATHS="$(git -C "$TARGET" status --porcelain -- app/dev-tools/AgenticService app/core/NavigationService/NavigationService.ts app/components/Nav/App/App.tsx)"
+  if [ -n "$DIRTY_PATHS" ]; then
+    cat >&2 <<EOF
+Refusing to install mobile recipe harness over dirty harness paths.
+Clean, stash, or rerun with --allow-dirty-harness-paths if you intentionally want backup/restore behavior.
+
+$DIRTY_PATHS
+EOF
+    exit 1
+  fi
+fi
+
+mkdir -p "$HARNESS_DIR"
+
+backup_path() {
+  local rel="$1"
+  local var="$2"
+  local target_path="$TARGET/$rel"
+  local backup_path="$ACTIVE_BACKUP_DIR/$rel"
+  if [ -e "$target_path" ]; then
+    mkdir -p "$(dirname "$backup_path")"
+    cp -a "$target_path" "$backup_path"
+    printf '%s=1\n' "$var" >> "$ACTIVE_STATE_FILE"
+  else
+    printf '%s=0\n' "$var" >> "$ACTIVE_STATE_FILE"
+  fi
+}
+
+rollback_path() {
+  local rel="$1"
+  local existed="$2"
+  local target_path="$TARGET/$rel"
+  local backup_path="$ROLLBACK_BACKUP_DIR/$rel"
+  if [ "$existed" = "1" ]; then
+    if [ -e "$backup_path" ]; then
+      rm -rf "$target_path"
+      mkdir -p "$(dirname "$target_path")"
+      cp -a "$backup_path" "$target_path"
+    else
+      echo "Rollback warning: missing backup for $rel at $backup_path" >&2
+    fi
+  else
+    rm -rf "$target_path"
+  fi
+}
+
+rollback_git_exclude() {
+  [ -f "$ROLLBACK_BACKUP_DIR/added-git-exclude" ] || return 0
+  local git_dir exclude_file tmp_file entry
+  git_dir="$(git -C "$TARGET" rev-parse --git-dir 2>/dev/null || true)"
+  [ -n "$git_dir" ] || return 0
+  case "$git_dir" in
+    /*) ;;
+    *) git_dir="$TARGET/$git_dir" ;;
+  esac
+  exclude_file="$git_dir/info/exclude"
+  [ -f "$exclude_file" ] || return 0
+  tmp_file="$(mktemp)"
+  cp "$exclude_file" "$tmp_file"
+  while IFS= read -r entry; do
+    [ -n "$entry" ] || continue
+    grep -vxF "$entry" "$tmp_file" > "$tmp_file.next" || true
+    mv "$tmp_file.next" "$tmp_file"
+  done < "$ROLLBACK_BACKUP_DIR/added-git-exclude"
+  mv "$tmp_file" "$exclude_file"
+}
+
+rollback_failed_install() {
+  local code="${1:-1}"
+  if [ "$INSTALL_MUTATING" != true ]; then
+    exit "$code"
+  fi
+
+  set +e
+  echo "Mobile recipe harness install failed; restoring backed-up product files." >&2
+  if [ -f "$ROLLBACK_STATE_FILE" ]; then
+    while IFS= read -r _line || [ -n "$_line" ]; do
+      [[ "$_line" =~ ^[[:space:]]*(#|$) ]] && continue
+      _key="${_line%%=*}"; _val="${_line#*=}"
+      case "$_key" in
+        AGENTIC_SERVICE_EXISTED|NAVIGATION_SERVICE_EXISTED|APP_TSX_EXISTED) ;;
+        *) continue ;;
+      esac
+      export "$_key=$_val"
+    done < "$ROLLBACK_STATE_FILE"
+    unset _line _key _val
+    rollback_path "app/dev-tools/AgenticService" "${AGENTIC_SERVICE_EXISTED:-0}"
+    rollback_path "app/core/NavigationService/NavigationService.ts" "${NAVIGATION_SERVICE_EXISTED:-0}"
+    rollback_path "app/components/Nav/App/App.tsx" "${APP_TSX_EXISTED:-0}"
+    rollback_git_exclude
+  else
+    echo "Rollback warning: no backup state found at $ROLLBACK_STATE_FILE" >&2
+  fi
+  if [ "$INSTALLED" = true ]; then
+    [ -n "$REFRESH_BACKUP_DIR" ] && rm -rf "$REFRESH_BACKUP_DIR"
+  else
+    rm -rf "$HARNESS_DIR"
+    rm -rf "$BACKUP_DIR"
+  fi
+  exit "$code"
+}
+
+trap 'rollback_failed_install $?' ERR
+
+if [ ! -f "$STATE_FILE" ] || [ "$REBASE_BACKUP" = true ]; then
+  TMP_BACKUP_DIR="$(mktemp -d "$HARNESS_DIR/backup.tmp.XXXXXX")"
+  ACTIVE_BACKUP_DIR="$TMP_BACKUP_DIR"
+  ACTIVE_STATE_FILE="$TMP_BACKUP_DIR/state.env"
+  : > "$ACTIVE_STATE_FILE"
+  backup_path "app/dev-tools/AgenticService" "AGENTIC_SERVICE_EXISTED"
+  backup_path "app/core/NavigationService/NavigationService.ts" "NAVIGATION_SERVICE_EXISTED"
+  backup_path "app/components/Nav/App/App.tsx" "APP_TSX_EXISTED"
+  if [ "$REBASE_BACKUP" = true ] && [ -e "$BACKUP_DIR" ]; then
+    ARCHIVE_DIR="$HARNESS_DIR/backup-stale.$(date -u +%Y%m%dT%H%M%SZ)"
+    mkdir -p "$(dirname "$ARCHIVE_DIR")"
+    mv "$BACKUP_DIR" "$ARCHIVE_DIR"
+    echo "Archived stale mobile harness backup: $ARCHIVE_DIR" >&2
+  else
+    rm -rf "$BACKUP_DIR"
+  fi
+  mkdir -p "$(dirname "$BACKUP_DIR")"
+  mv "$TMP_BACKUP_DIR" "$BACKUP_DIR"
+  STATE_FILE="$BACKUP_DIR/state.env"
+  ROLLBACK_BACKUP_DIR="$BACKUP_DIR"
+  ROLLBACK_STATE_FILE="$STATE_FILE"
+else
+  REFRESH_BACKUP_DIR="$(mktemp -d "$HARNESS_DIR/refresh-backup.tmp.XXXXXX")"
+  ACTIVE_BACKUP_DIR="$REFRESH_BACKUP_DIR"
+  ACTIVE_STATE_FILE="$REFRESH_BACKUP_DIR/state.env"
+  : > "$ACTIVE_STATE_FILE"
+  backup_path "app/dev-tools/AgenticService" "AGENTIC_SERVICE_EXISTED"
+  backup_path "app/core/NavigationService/NavigationService.ts" "NAVIGATION_SERVICE_EXISTED"
+  backup_path "app/components/Nav/App/App.tsx" "APP_TSX_EXISTED"
+  ROLLBACK_BACKUP_DIR="$REFRESH_BACKUP_DIR"
+  ROLLBACK_STATE_FILE="$REFRESH_BACKUP_DIR/state.env"
+fi
+
+INSTALL_MUTATING=true
+
+install_v1_runner_assets
+
+mkdir -p "$TARGET/app/dev-tools/AgenticService"
+while IFS= read -r -d '' overlay_file; do
+  rel="${overlay_file#$ADAPTER_DIR/app-overlay/app/dev-tools/AgenticService/}"
+  dest_rel="${rel%.patch}"
+  dest="$TARGET/app/dev-tools/AgenticService/$dest_rel"
+  mkdir -p "$(dirname "$dest")"
+  # Skip when the checkout already has identical content (e.g. the committed
+  # in-app seam) so install stays a no-op and produces no spurious diff.
+  cmp -s "$overlay_file" "$dest" || cp "$overlay_file" "$dest"
+  # Exclude overlay *.test.* files: they are source tests for the overlay
+  # templates and must not ship into the product checkout, where the product's
+  # jest could pick them up on local runs.
+done < <(find "$ADAPTER_DIR/app-overlay/app/dev-tools/AgenticService" -type f ! -name '*.test.*' -print0)
+
+node - "$TARGET" <<'NODE'
+const fs = require('fs');
+const path = require('path');
+
+const target = process.argv[2];
+
+function patchNavigation() {
+  const file = path.join(target, 'app/core/NavigationService/NavigationService.ts');
+  if (!fs.existsSync(file)) throw new Error(`missing ${file}`);
+  const original = fs.readFileSync(file, 'utf8');
+  let src = original;
+  const devToolsImport = "import('../../dev-tools/AgenticService/AgenticService')";
+  if (src.includes('AgenticService.install')) {
+    const upgraded = src
+      .replaceAll("import('../AgenticService/AgenticService')", devToolsImport)
+      .replaceAll("import('../../core/AgenticService/AgenticService')", devToolsImport);
+    if (upgraded !== src) {
+      fs.writeFileSync(file, upgraded);
+      return 'upgraded-import';
+    }
+    return 'already-present';
+  }
+  const marker = '    this.#navigation = this.#createReactAwareNavigation(navRef);\n';
+  const insert = `${marker}\n    if (__DEV__) {\n      import('../../dev-tools/AgenticService/AgenticService').then(\n        ({ default: AgenticService }) => {\n          AgenticService.install(navRef, this.#navigation);\n        },\n      );\n    }\n`;
+  if (!src.includes(marker)) {
+    throw new Error(`cannot patch NavigationService.ts: marker not found`);
+  }
+  src = src.replace(marker, insert);
+  if (src === original) return 'already-present';
+  fs.writeFileSync(file, src);
+  return 'patched';
+}
+
+function patchApp() {
+  const file = path.join(target, 'app/components/Nav/App/App.tsx');
+  if (!fs.existsSync(file)) throw new Error(`missing ${file}`);
+  const original = fs.readFileSync(file, 'utf8');
+  let src = original;
+  let importStatus = 'already-present';
+  if (src.includes('core/AgenticService/AgentStepHud') && !src.includes('dev-tools/AgenticService/AgentStepHud')) {
+    src = src.replaceAll("../../../core/AgenticService/AgentStepHud", "../../../dev-tools/AgenticService/AgentStepHud");
+    importStatus = 'upgraded-import';
+  }
+  if (!src.includes('dev-tools/AgenticService/AgentStepHud')) {
+    const marker = "import PerpsWebSocketHealthToast";
+    const line = "import AgentStepHud from '../../../dev-tools/AgenticService/AgentStepHud';\n";
+    if (src.includes(marker)) {
+      src = src.replace(marker, `${line}${marker}`);
+    } else {
+      throw new Error(`cannot patch App.tsx: import marker not found`);
+    }
+    importStatus = 'patched';
+  }
+  let renderStatus = 'already-present';
+  if (!src.includes('<AgentStepHud')) {
+    const marker = /^(\s*)<ControllerEventToastBridge\b[^\n]*\/>/m;
+    const match = src.match(marker);
+    if (!match) {
+      throw new Error(`cannot patch App.tsx: render marker not found`);
+    }
+    src = src.replace(marker, `${match[1]}{__DEV__ && <AgentStepHud />}\n${match[0]}`);
+    renderStatus = 'patched';
+  }
+  if (src !== original) fs.writeFileSync(file, src);
+  return `${importStatus},${renderStatus}`;
+}
+
+console.log(JSON.stringify({
+  navigation: patchNavigation(),
+  app: patchApp(),
+}));
+NODE
+
+if [ "$GIT_EXCLUDE" = true ]; then
+  echo "[recipe-harness] Adding local .git/info/exclude entries (removed on cleanup): $HARNESS_ROOT/, app/dev-tools/AgenticService/"
+  add_git_exclude_entry "$HARNESS_ROOT/" "$BACKUP_DIR/added-git-exclude"
+  add_git_exclude_entry "app/dev-tools/AgenticService/" "$BACKUP_DIR/added-git-exclude"
+fi
+
+write_managed_hashes() {
+  local hash_file="$BACKUP_DIR/managed-hashes.tsv"
+  local rel
+  : > "$hash_file"
+  for rel in \
+    "app/dev-tools/AgenticService" \
+    "app/core/NavigationService/NavigationService.ts" \
+    "app/components/Nav/App/App.tsx"; do
+    printf '%s\t%s\n' "$rel" "$(hash_path "$rel")" >> "$hash_file"
+  done
+}
+
+write_managed_hashes
+INSTALL_MUTATING=false
+trap - ERR
+[ -n "$REFRESH_BACKUP_DIR" ] && rm -rf "$REFRESH_BACKUP_DIR"
+
+SOURCE_REV="$(git -C "$RUNNER_DIR" rev-parse HEAD 2>/dev/null || echo unknown)"
+CLEANUP_COMMAND="RECIPE_HARNESS_ROOT=$HARNESS_ROOT $(printf '%q' "$CLEANUP_SH") --target $(printf '%q' "$TARGET")"
+node -e '
+  const fs = require("fs");
+  const [runnerOwnerDir, runnerOwnerRevision, runnerDir, runnerRevision, runnerSourceKind, adapterRuntime, target, backupDir, scriptDir, manifestPath, mobileAgenticSource, harnessRoot, harnessRel, cleanupCommand] = process.argv.slice(1);
+  const m = {
+    adapter: "mobile",
+    installedAt: new Date().toISOString(),
+    source: {
+      runnerOwnerDir,
+      runnerOwnerRevision,
+      runnerDir,
+      runnerRevision,
+      runnerSourceKind,
+      adapterRuntime,
+    },
+    target,
+    protocolVersion: "v1",
+    actionManifestPath: harnessRel + "/action-manifest.json",
+    runnerEntrypoint: harnessRel + "/runner/bin/metamask-recipe",
+    runtimeHelpers: {
+      launch: harnessRel + "/scripts/launch.sh",
+      live: harnessRel + "/scripts/live.sh",
+      verify: harnessRel + "/scripts/verify.sh"
+    },
+    installedPaths: [harnessRel + "/runner", harnessRel + "/scripts", harnessRel + "/action-manifest.json", "app/dev-tools/AgenticService"],
+    patchedFiles: ["app/core/NavigationService/NavigationService.ts", "app/components/Nav/App/App.tsx"],
+    backupDir,
+    managedHashes: backupDir + "/managed-hashes.tsv",
+    cleanupCommand,
+    productDiffExcludes: [
+      ":(exclude)" + harnessRoot,
+      ":(exclude)app/dev-tools/AgenticService"
+    ]
+  };
+  fs.writeFileSync(manifestPath, JSON.stringify(m, null, 2) + "\n");
+' "$RUNNER_DIR" "$SOURCE_REV" "$METAMASK_RUNNER_DIR" "$METAMASK_RUNNER_REVISION" "$METAMASK_RUNNER_SOURCE_KIND" "$ADAPTER_DIR" "$TARGET" "$BACKUP_DIR" "$SCRIPT_DIR" "$HARNESS_DIR/manifest.json" "${MOBILE_AGENTIC_SOURCE:-}" "$HARNESS_ROOT" "$HARNESS_REL" "$CLEANUP_COMMAND"
+
+ENSURE_DEPS="$SCRIPT_DIR/../lib/ensure-runner-deps.sh"
+if [ -f "$ENSURE_DEPS" ]; then
+  bash "$ENSURE_DEPS" "$RUNNER_DIR"
+fi
+
+echo "Installed mobile recipe harness: $HARNESS_DIR/manifest.json"