@hasna/recordings 0.2.14 → 0.3.2

package/scripts/install_macos_app.sh

@@ -146,6 +146,66 @@ require_absolute_canonical_owned_home() {
   }
 }
 
+# Every accepted argument, because until now there was no usage output at all and an
+# unrecognized argument printed only "Unknown argument". That mattered most for
+# --allow-adhoc-identity-migration: the identity-migration gate refuses a local-only
+# reinstall by default, and an operator repairing a station had no way to discover the
+# approval flag except by reading the refusal on stderr or the script itself.
+print_usage() {
+  cat <<'USAGE'
+Usage: install_macos_app.sh --artifact <zip> --manifest <json> [options]
+
+Installs a Recordings macOS app artifact transactionally. Normally invoked through
+`recordings app install`, which forwards these arguments.
+
+Artifact and version:
+  --artifact <path>                    Finalized artifact archive to install
+  --manifest <path>                    Artifact manifest describing it
+  --manifest-sha256 <sha256>           Authenticated digest of the manifest
+  --expected-source-sha <sha>          Approved 40-character source commit
+  --expected-version <version>         Version the artifact must declare
+  --expected-team-id <team-id>         Required Apple Developer team identifier
+
+Target selection:
+  --expected-hostname <name>           Require this live short hostname before mutating
+  --variant <full|bar>                 Artifact variant the operator intends to install;
+                                       the manifest variant is verified against this at
+                                       install time (default: full)
+  --artifact-policy <release|local-only>
+                                       Trust policy to evaluate the artifact under
+  --approved-target <name>             Approved target for a local-only artifact
+  --approved-target-identity-kind <kind>
+                                       hardware_uuid_sha256 or tailscale_node_id_sha256
+  --approved-target-identity-sha256 <sha256>
+                                       Authenticated digest of the target identity
+
+Identity migration. Replacing an installed app with one signed by a different identity
+voids the Microphone and Accessibility grants the installed app holds; macOS keys those
+grants to code identity, and they cannot be restored by the installer. Both approvals are
+one-shot and deliberately distinct: approving a release signer rotation is not approving
+an ad-hoc replacement of a certificate-rooted install.
+  --allow-signing-identity-migration   Approve one reviewed release signer change
+  --expected-old-identity-sha256 <sha256>
+                                       Exact installed identity approved for migration
+  --expected-new-identity-sha256 <sha256>
+                                       Exact candidate identity approved for migration
+  --allow-adhoc-identity-migration     Approve replacing an installed app with an ad-hoc
+                                       signed local-only build. Required for essentially
+                                       every local-only reinstall, including a repair
+                                       install of the same version, because each ad-hoc
+                                       rebuild produces a new CDHash and is therefore a
+                                       real identity migration. Accepts that Microphone
+                                       and Accessibility must be granted again afterwards.
+  --acknowledge-local-signing-and-permissions
+                                       Acknowledge local-only ad-hoc signing up front
+
+Launch and help:
+  --launch                             Launch the app after installing
+  --launch-timeout <seconds>           Seconds to wait for the launch to settle
+  --help, -h                           Print this message and exit 0
+USAGE
+}
+
 ARTIFACT_PATH=""
 MANIFEST_PATH=""
 EXPECTED_TEAM_ID="${RECORDINGS_EXPECTED_TEAM_IDENTIFIER:-}"
@@ -157,11 +217,13 @@ EXPECTED_NEW_IDENTITY_SHA256=""
 EXPECTED_HOSTNAME=""
 EXPECTED_HOSTNAME_SET=0
 ARTIFACT_POLICY="release"
+INSTALL_VARIANT="full"
 APPROVED_TARGET="fleet"
 APPROVED_TARGET_IDENTITY_KIND=""
 APPROVED_TARGET_IDENTITY_SHA256="none"
 ACKNOWLEDGE_LOCAL_SIGNING_AND_PERMISSIONS=0
 ALLOW_IDENTITY_MIGRATION=0
+ALLOW_ADHOC_IDENTITY_MIGRATION=0
 LAUNCH_APP=0
 LAUNCH_TIMEOUT_SECONDS="${RECORDINGS_LAUNCH_TIMEOUT_SECONDS:-10}"
 
@@ -196,6 +258,16 @@ while [ "$#" -gt 0 ]; do
       EXPECTED_HOSTNAME_SET=1
       shift 2
       ;;
+    --variant)
+      case "${2:-}" in
+        full|bar) INSTALL_VARIANT="${2}" ;;
+        *)
+          echo "Install variant must be full or bar." >&2
+          exit 2
+          ;;
+      esac
+      shift 2
+      ;;
     --artifact-policy)
       case "${2:-}" in
         release) ARTIFACT_POLICY="release" ;;
@@ -232,6 +304,12 @@ while [ "$#" -gt 0 ]; do
       ALLOW_IDENTITY_MIGRATION=1
       shift
       ;;
+    # Distinct from --allow-signing-identity-migration: approving a release signer
+    # rotation is not approving an ad-hoc replacement of a certificate-rooted install.
+    --allow-adhoc-identity-migration)
+      ALLOW_ADHOC_IDENTITY_MIGRATION=1
+      shift
+      ;;
     --launch)
       LAUNCH_APP=1
       shift
@@ -240,8 +318,13 @@ while [ "$#" -gt 0 ]; do
       LAUNCH_TIMEOUT_SECONDS="${2:-}"
       shift 2
       ;;
+    --help | -h)
+      print_usage
+      exit 0
+      ;;
     *)
       echo "Unknown argument: $1" >&2
+      echo "Run with --help for the accepted arguments." >&2
       exit 2
       ;;
   esac
@@ -310,6 +393,19 @@ PACKAGE_ROOT="$(cd "$("$DIRNAME_EXECUTABLE" "${BASH_SOURCE[0]}")/.." && pwd)"
 ARTIFACT_TOOL="${PACKAGE_ROOT}/scripts/macos_artifact.ts"
 RUNTIME_SMOKE="${PACKAGE_ROOT}/scripts/smoke_macos_app.sh"
 TAILSCALE_RESOLVER="${PACKAGE_ROOT}/scripts/resolve_tailscale_cli.sh"
+# Sourced here, before either policy branch, so a missing or unusable guard denies every
+# install rather than only the ones that happen to reach it.
+IDENTITY_MIGRATION_GUARD="${PACKAGE_ROOT}/scripts/enforce_identity_migration.sh"
+[ -f "$IDENTITY_MIGRATION_GUARD" ] && [ ! -L "$IDENTITY_MIGRATION_GUARD" ] || {
+  echo "Packaged identity-migration guard is missing." >&2
+  exit 2
+}
+# shellcheck source=/dev/null
+. "$IDENTITY_MIGRATION_GUARD"
+declare -F recordings_enforce_identity_migration >/dev/null || {
+  echo "Packaged identity-migration guard does not define its enforcement function." >&2
+  exit 2
+}
 if [ "$ARTIFACT_POLICY" = "release" ]; then
   if [ -z "$EXPECTED_TEAM_ID" ]; then
     echo "Release install requires --expected-team-id or RECORDINGS_EXPECTED_TEAM_IDENTIFIER." >&2
@@ -331,13 +427,36 @@ if [ "$ARTIFACT_POLICY" = "release" ]; then
     echo "Local-only acknowledgment cannot be supplied for a release artifact." >&2
     exit 2
   fi
+  if [ "$ALLOW_ADHOC_IDENTITY_MIGRATION" -eq 1 ]; then
+    echo "Ad-hoc identity-migration approval is not valid for a release artifact; use --allow-signing-identity-migration with the exact old/new identity digests." >&2
+    exit 2
+  fi
 else
-  if [ -n "$EXPECTED_TEAM_ID" ]; then
-    echo "Local-only artifacts do not accept --expected-team-id or a release TeamIdentifier environment value." >&2
+  # A local-station artifact may be Developer ID signed under a pinned team, because ad-hoc
+  # signing cannot hold a macOS TCC grant: TCC keys Accessibility to bundle id plus signing
+  # identity, and an ad-hoc CDHash changes on every rebuild, which is what silently killed the
+  # Fn/Globe hold-to-talk CGEventTap. A supplied team must therefore be a real Apple team, and
+  # it is matched against the manifest below exactly as a release team is.
+  if [ -n "$EXPECTED_TEAM_ID" ] && ! [[ "$EXPECTED_TEAM_ID" =~ ^[A-Z0-9]{10}$ ]]; then
+    echo "Local-only --expected-team-id must be a 10-character Developer ID team identifier." >&2
     exit 2
   fi
-  if [ "$APPROVED_TARGET" != "station06" ]; then
-    echo "Local-only install is currently restricted to --approved-target station06." >&2
+  # The approved local-only targets are policy data shared with the artifact tool
+  # and the builder, parsed by one sourced reader so all three agree.
+  LOCAL_TARGET_POLICY="${PACKAGE_ROOT}/scripts/policy/local-only-approved-targets.txt"
+  LOCAL_TARGET_READER="${PACKAGE_ROOT}/scripts/read_local_only_targets.sh"
+  [ -f "$LOCAL_TARGET_READER" ] && [ ! -L "$LOCAL_TARGET_READER" ] || {
+    echo "Packaged local-only approved target reader is missing." >&2
+    exit 2
+  }
+  # shellcheck source=/dev/null
+  . "$LOCAL_TARGET_READER"
+  APPROVED_TARGET_MATCHED=0
+  APPROVED_TARGET_LIST=""
+  read_local_only_targets \
+    "$LOCAL_TARGET_POLICY" APPROVED_TARGET_LIST APPROVED_TARGET_MATCHED "$APPROVED_TARGET" || exit 2
+  if [ "$APPROVED_TARGET_MATCHED" -ne 1 ]; then
+    echo "Local-only install requires an approved --approved-target (${APPROVED_TARGET_LIST})." >&2
     exit 2
   fi
   if ! [[ "$APPROVED_TARGET_IDENTITY_SHA256" =~ ^[a-f0-9]{64}$ ]]; then
@@ -386,12 +505,16 @@ else
     exit 1
   fi
   if [ "$ALLOW_IDENTITY_MIGRATION" -eq 1 ] || [ -n "$EXPECTED_OLD_IDENTITY_SHA256" ] || [ -n "$EXPECTED_NEW_IDENTITY_SHA256" ]; then
-    echo "Release identity-migration flags are not valid for local-only artifacts." >&2
+    echo "Release identity-migration flags are not valid for local-only artifacts; an ad-hoc replacement is approved with --allow-adhoc-identity-migration." >&2
     exit 2
   fi
-  EXPECTED_TEAM_ID="ADHOC"
+  if [ -z "$EXPECTED_TEAM_ID" ]; then
+    EXPECTED_TEAM_ID="ADHOC"
+  fi
   echo "WARNING: installing a non-notarized local-only artifact approved only for ${APPROVED_TARGET}." >&2
-  echo "WARNING: code identity can change; Microphone or Accessibility may require manual reauthorization." >&2
+  if [ "$EXPECTED_TEAM_ID" = "ADHOC" ]; then
+    echo "WARNING: code identity can change; Microphone or Accessibility may require manual reauthorization." >&2
+  fi
 fi
 if [ "$ARTIFACT_POLICY" = "release" ] && [ "$ALLOW_IDENTITY_MIGRATION" -eq 1 ] && \
    { [ -z "$EXPECTED_OLD_IDENTITY_SHA256" ] || [ -z "$EXPECTED_NEW_IDENTITY_SHA256" ]; }; then
@@ -423,7 +546,8 @@ fi
 "$BUN_EXECUTABLE" "$ARTIFACT_TOOL" native-fs-guard-check
 DATA_DIR="${HOME}/.hasna/recordings"
 DATA_PARENT="$("$DIRNAME_EXECUTABLE" "$DATA_DIR")"
-APP_DEST="${HOME}/Applications/Recordings.app"
+MANIFEST_BUNDLE_NAME="Recordings.app"
+APP_DEST="${HOME}/Applications/${MANIFEST_BUNDLE_NAME}"
 APP_PARENT="$("$DIRNAME_EXECUTABLE" "$APP_DEST")"
 ROLLBACK_DIR="${DATA_DIR}/rollbacks"
 JOURNAL_PATH="${APP_PARENT}/.Recordings-install-transaction.json"
@@ -1214,6 +1338,7 @@ MANIFEST_SNAPSHOT="${WORK_DIR}/$("$BASENAME_EXECUTABLE" "$MANIFEST_PATH")"
   --source-sha "$EXPECTED_SOURCE_SHA" \
   --version "$EXPECTED_VERSION" \
   --artifact-policy "$ARTIFACT_POLICY" \
+  --variant "$INSTALL_VARIANT" \
   --approved-target "$APPROVED_TARGET" \
   --approved-target-identity-kind "$APPROVED_TARGET_IDENTITY_KIND" \
   --approved-target-identity-sha256 "$APPROVED_TARGET_IDENTITY_SHA256"
@@ -1221,6 +1346,22 @@ MANIFEST_BUILDER_IDENTITY_KIND="$("$BUN_EXECUTABLE" "$ARTIFACT_TOOL" manifest-ge
   --manifest "$MANIFEST_SNAPSHOT" \
   --manifest-sha256 "$EXPECTED_MANIFEST_SHA256" \
   --field builder_identity_kind)"
+AUTHENTICATED_BUNDLE_NAME="$("$BUN_EXECUTABLE" "$ARTIFACT_TOOL" manifest-get \
+  --manifest "$MANIFEST_SNAPSHOT" \
+  --manifest-sha256 "$EXPECTED_MANIFEST_SHA256" \
+  --field bundle_name)"
+case "$AUTHENTICATED_BUNDLE_NAME" in
+  *.app) ;;
+  *)
+    echo "Authenticated artifact manifest carries an invalid bundle name: ${AUTHENTICATED_BUNDLE_NAME}." >&2
+    exit 1
+    ;;
+esac
+if [ "$AUTHENTICATED_BUNDLE_NAME" != "$MANIFEST_BUNDLE_NAME" ]; then
+  MANIFEST_BUNDLE_NAME="$AUTHENTICATED_BUNDLE_NAME"
+  APP_DEST="${HOME}/Applications/${MANIFEST_BUNDLE_NAME}"
+  APP_PARENT="$("$DIRNAME_EXECUTABLE" "$APP_DEST")"
+fi
 
 CURRENT_MACOS="$("$SW_VERS_EXECUTABLE" -productVersion)"
 MINIMUM_MACOS="$("$BUN_EXECUTABLE" "$ARTIFACT_TOOL" manifest-get \
@@ -1252,7 +1393,7 @@ verify_secure_parent "$APP_PARENT"
 verify_existing_state_root
 
 STAGING_DIR="$("$MKTEMP_EXECUTABLE" -d "${APP_PARENT}/.Recordings-install.XXXXXX")"
-STAGED_APP="${STAGING_DIR}/Recordings.app"
+STAGED_APP="${STAGING_DIR}/${MANIFEST_BUNDLE_NAME}"
 "$BUN_EXECUTABLE" "$ARTIFACT_TOOL" verify-archive \
   --archive "$ARTIFACT_SNAPSHOT" \
   --manifest "$MANIFEST_SNAPSHOT" \
@@ -1261,6 +1402,7 @@ STAGED_APP="${STAGING_DIR}/Recordings.app"
   --source-sha "$EXPECTED_SOURCE_SHA" \
   --version "$EXPECTED_VERSION" \
   --artifact-policy "$ARTIFACT_POLICY" \
+  --variant "$INSTALL_VARIANT" \
   --approved-target "$APPROVED_TARGET" \
   --approved-target-identity-kind "$APPROVED_TARGET_IDENTITY_KIND" \
   --approved-target-identity-sha256 "$APPROVED_TARGET_IDENTITY_SHA256"
@@ -1538,10 +1680,11 @@ write_journal() {
   --source-sha "$EXPECTED_SOURCE_SHA" \
   --version "$EXPECTED_VERSION" \
   --artifact-policy "$ARTIFACT_POLICY" \
+  --variant "$INSTALL_VARIANT" \
   --approved-target "$APPROVED_TARGET" \
   --approved-target-identity-kind "$APPROVED_TARGET_IDENTITY_KIND" \
   --approved-target-identity-sha256 "$APPROVED_TARGET_IDENTITY_SHA256"
-CANDIDATE_APP="$UNPACK_DIR/Recordings.app"
+CANDIDATE_APP="$UNPACK_DIR/${MANIFEST_BUNDLE_NAME}"
 
 "$BUN_EXECUTABLE" "$ARTIFACT_TOOL" verify-app \
   --app "$CANDIDATE_APP" \
@@ -1549,6 +1692,7 @@ CANDIDATE_APP="$UNPACK_DIR/Recordings.app"
   --manifest-sha256 "$EXPECTED_MANIFEST_SHA256" \
   --team-id "$EXPECTED_TEAM_ID" \
   --artifact-policy "$ARTIFACT_POLICY" \
+  --variant "$INSTALL_VARIANT" \
   --approved-target "$APPROVED_TARGET" \
   --approved-target-identity-kind "$APPROVED_TARGET_IDENTITY_KIND" \
   --approved-target-identity-sha256 "$APPROVED_TARGET_IDENTITY_SHA256"
@@ -1562,10 +1706,12 @@ fi
 DISCOVERED_APPS=()
 add_unique_app "$APP_DEST"
 add_unique_app "${DATA_DIR}/Recordings.app"
-for candidate in "${HOME}"/Applications/Recordings.app.*; do
+add_unique_app "${DATA_DIR}/HasnaRecordings.app"
+for candidate in "${HOME}"/Applications/Recordings.app.* "${HOME}"/Applications/HasnaRecordings.app.*; do
   add_unique_app "$candidate"
 done
 add_unique_app "/Applications/Recordings.app"
+add_unique_app "/Applications/HasnaRecordings.app"
 if [ -x "$MDFIND_EXECUTABLE" ]; then
   while IFS= read -r candidate; do
     [ -n "$candidate" ] || continue
@@ -1576,7 +1722,7 @@ fi
 MANAGEABLE_APPS=()
 for existing_app in ${DISCOVERED_APPS[@]+"${DISCOVERED_APPS[@]}"}; do
   case "$existing_app" in
-    "$APP_DEST"|"${DATA_DIR}/Recordings.app"|"${HOME}/Applications/Recordings.app."*)
+    "$APP_DEST"|"${DATA_DIR}/Recordings.app"|"${DATA_DIR}/HasnaRecordings.app"|"${HOME}/Applications/Recordings.app."*|"${HOME}/Applications/HasnaRecordings.app."*)
       echo "Duplicate disposition: archive transactionally, remove after activation: ${existing_app}"
       MANAGEABLE_APPS+=("$existing_app")
       ;;
@@ -1621,7 +1767,10 @@ if [ "$ARTIFACT_POLICY" = "release" ] && [ -z "$candidate_requirement" ]; then
   exit 1
 fi
 identity_migration=0
-candidate_identity_sha256="$("$BUN_EXECUTABLE" "$ARTIFACT_TOOL" requirement-digest --app "$CANDIDATE_APP" --artifact-policy "$ARTIFACT_POLICY")"
+# Pass the SAME pinned team already given to verify-archive and verify-app. Without it the
+# digest verifies the candidate against the ad-hoc shape, which rejects a correctly
+# Developer-ID-signed local-station bundle and, under `set -euo pipefail`, aborts the install.
+candidate_identity_sha256="$("$BUN_EXECUTABLE" "$ARTIFACT_TOOL" requirement-digest --app "$CANDIDATE_APP" --artifact-policy "$ARTIFACT_POLICY" --expected-team-id "$EXPECTED_TEAM_ID")"
 candidate_tree_sha256="$("$BUN_EXECUTABLE" "$ARTIFACT_TOOL" tree-digest --path "$CANDIDATE_APP")"
 [ "$candidate_identity_sha256" = "$("$BUN_EXECUTABLE" "$ARTIFACT_TOOL" manifest-get \
   --manifest "$MANIFEST_SNAPSHOT" \
@@ -1655,21 +1804,18 @@ for existing_app in ${MANAGEABLE_APPS[@]+"${MANAGEABLE_APPS[@]}"}; do
     identity_migration=1
   fi
 done
-if [ "$ARTIFACT_POLICY" = "release" ] && [ "$identity_migration" -eq 1 ] && [ "$ALLOW_IDENTITY_MIGRATION" -ne 1 ]; then
-  echo "Candidate and existing app designated requirements are not mutually compatible; review the signer change and rerun once with --allow-signing-identity-migration." >&2
-  exit 1
-fi
-if [ "$ARTIFACT_POLICY" = "release" ] && [ "$identity_migration" -eq 1 ] && {
-     [ "$previous_identity_sha256" != "$EXPECTED_OLD_IDENTITY_SHA256" ] ||
-     [ "$candidate_identity_sha256" != "$EXPECTED_NEW_IDENTITY_SHA256" ];
-   }; then
-  echo "Signing identity migration does not match the exact operator-approved old/new identities." >&2
-  exit 1
-fi
-if [ "$ARTIFACT_POLICY" = "release" ] && [ "$identity_migration" -eq 0 ] && [ "$ALLOW_IDENTITY_MIGRATION" -eq 1 ]; then
-  echo "Identity migration approval was supplied but no identity migration is required." >&2
-  exit 1
-fi
+# Enforced for every artifact policy. A local-only artifact is ad-hoc signed, so this is
+# the point at which an install would void the installed app's Microphone and
+# Accessibility grants; the printed warning further down is not a gate.
+recordings_enforce_identity_migration \
+  "$ARTIFACT_POLICY" \
+  "$identity_migration" \
+  "$ALLOW_IDENTITY_MIGRATION" \
+  "$ALLOW_ADHOC_IDENTITY_MIGRATION" \
+  "$previous_identity_sha256" \
+  "$candidate_identity_sha256" \
+  "$EXPECTED_OLD_IDENTITY_SHA256" \
+  "$EXPECTED_NEW_IDENTITY_SHA256" || exit 1
 
 TRANSACTION_DIR="$("$MKTEMP_EXECUTABLE" -d "${APP_PARENT}/.Recordings-transaction.XXXXXX")"
 TRANSACTION_NONCE="$("$BUN_EXECUTABLE" -e 'import { randomUUID } from "node:crypto"; process.stdout.write(randomUUID())')"
@@ -1738,6 +1884,7 @@ done
   --manifest-sha256 "$EXPECTED_MANIFEST_SHA256" \
   --team-id "$EXPECTED_TEAM_ID" \
   --artifact-policy "$ARTIFACT_POLICY" \
+  --variant "$INSTALL_VARIANT" \
   --approved-target "$APPROVED_TARGET" \
   --approved-target-identity-kind "$APPROVED_TARGET_IDENTITY_KIND" \
   --approved-target-identity-sha256 "$APPROVED_TARGET_IDENTITY_SHA256"
@@ -1903,6 +2050,7 @@ write_journal candidate-installed
   --manifest-sha256 "$EXPECTED_MANIFEST_SHA256" \
   --team-id "$EXPECTED_TEAM_ID" \
   --artifact-policy "$ARTIFACT_POLICY" \
+  --variant "$INSTALL_VARIANT" \
   --approved-target "$APPROVED_TARGET" \
   --approved-target-identity-kind "$APPROVED_TARGET_IDENTITY_KIND" \
   --approved-target-identity-sha256 "$APPROVED_TARGET_IDENTITY_SHA256"
@@ -1918,11 +2066,12 @@ fi
   --manifest-sha256 "$EXPECTED_MANIFEST_SHA256" \
   --team-id "$EXPECTED_TEAM_ID" \
   --artifact-policy "$ARTIFACT_POLICY" \
+  --variant "$INSTALL_VARIANT" \
   --approved-target "$APPROVED_TARGET" \
   --approved-target-identity-kind "$APPROVED_TARGET_IDENTITY_KIND" \
   --approved-target-identity-sha256 "$APPROVED_TARGET_IDENTITY_SHA256"
 SMOKE_TOOL_PATH="/usr/bin:/bin:/usr/sbin:/sbin:$("$DIRNAME_EXECUTABLE" "$BUN_EXECUTABLE")"
-PATH="$SMOKE_TOOL_PATH" "$RUNTIME_SMOKE" "$APP_DEST" "$BUN_EXECUTABLE"
+PATH="$SMOKE_TOOL_PATH" "$RUNTIME_SMOKE" "$APP_DEST" "$BUN_EXECUTABLE" --variant "$INSTALL_VARIANT"
 write_journal activated
 
 write_journal committed
@@ -1934,7 +2083,14 @@ STOPPED_RUNNING_APP=0
 if [ "$LAUNCH_APP" -eq 1 ] || [ "$was_running" -eq 1 ]; then
   EXPECTED_EXECUTABLE="$APP_DEST/Contents/MacOS/Recordings"
   RUNNING_EXECUTABLES+=("$EXPECTED_EXECUTABLE")
-  "$OPEN_EXECUTABLE" -n "$APP_DEST"
+  if [ "$INSTALL_VARIANT" = "bar" ]; then
+    # Bar installs relaunch with an explicit --bar-only so the launch record is
+    # self-describing; the compile-time RECORDINGS_BAR_ONLY default makes the bar
+    # windowless even without the argument.
+    "$OPEN_EXECUTABLE" -n "$APP_DEST" --args --bar-only
+  else
+    "$OPEN_EXECUTABLE" -n "$APP_DEST"
+  fi
   attempts=$((LAUNCH_TIMEOUT_SECONDS * 10))
   launched_pid=""
   launched_start_identity=""
@@ -1962,7 +2118,12 @@ fi
 
 if [ "$ARTIFACT_POLICY" = "local_only" ]; then
   echo "Installed local-only Recordings.app for ${APPROVED_TARGET}; this artifact is ad-hoc signed and non-notarized."
-  echo "Microphone or Accessibility may require manual reauthorization after this code-identity change."
+  if [ "$identity_migration" -eq 1 ]; then
+    # Not a maybe: the designated requirement did change, under an explicit approval.
+    echo "Code identity changed under --allow-adhoc-identity-migration; the Microphone and Accessibility grants held by the replaced app no longer apply and must be reauthorized."
+  else
+    echo "Microphone or Accessibility may require manual reauthorization if this code identity differs from the last authorized one."
+  fi
 elif [ "$identity_migration" -eq 1 ]; then
   echo "Installed a new signing identity; macOS will require one-time permission approval for this migration."
 else