@@ -23,6 +23,12 @@ Follow [INSTALLATION.md](INSTALLATION.md), then run:
 Keep the helper compatible with Bash 3.2, including the system Bash on macOS.
 The default tests must run without credentials or a live provider.
 
+For focused checks, run `bash tests/identity-config.sh` for malformed defaults,
+large configurations, and model-request validation. On macOS,
+`bash tests/macos-open-with.sh` checks Finder app installation failures and
+backup recovery using temporary apps and intercepted registration calls. Both
+are included in `./tests/test.sh`.
+
 The [CI workflow](.github/workflows/ci.yml) runs offline tests with command
 mocks on Linux and macOS. It does not install Codex or validate configuration
 against a real Codex release. With Codex installed, you can opt into doctor
 
@@ -182,8 +182,7 @@ On macOS, helper-launched VS Code instances have Dock hover names such as
 See [macOS Dock names](docs/projects-vscode.md#macos-dock-names) for reopening,
 the restriction on directly launching or pinning editor copies, and the
 original-editor opt-out. After quitting, reopen a configured project through
-its matching **Open With > VS Code - NAME** entry, the Finder Quick Action, or
-`codex-home`.
+the Finder **Quick Actions > Open in Codex Project** action or `codex-home`.
 
 After project setup, enter the folder and run `codex-home run`. It uses the
 context selected by `direnv`; you do not need to type the identity name each
 
@@ -70,9 +70,9 @@ terminal, start the selected context with `codex-home run`.
 
 On macOS, the helper opens a named editor copy: hover over its running Dock
 icon to read `VS Code - NAME`. Projects using the same identity reuse its
-instance. For configured folders, Finder's **Open With > VS Code - NAME**
-entry routes through that identity. You can also use `codex-home` or Finder's
-**Quick Actions > Open in Codex Project**; do not pin or directly open the
+instance. In Finder, use **Quick Actions > Open in Codex Project** for a
+configured folder. File managers with folder **Open With** menus can use the
+matching **VS Code - NAME** handler. You can also use `codex-home`; do not pin or directly open the
 generated editor copy, which needs the helper's launch environment. See
 [macOS Dock names](docs/projects-vscode.md#macos-dock-names).
 
 
@@ -319,23 +319,22 @@ umgpt_models_file_value() {
 
 umgpt_repository_default_model() {
   local scope="$1"
-  local key model
+  local key
   [[ -f "$UMGPT_REPOSITORY_MODELS_FILE" ]] ||
     die "repository U-M GPT defaults not found: $UMGPT_REPOSITORY_MODELS_FILE"
   case "$scope" in
     openai-only) key="umgpt" ;;
     low-sensitivity) key="umgpt_low" ;;
     *) die "unknown U-M GPT model scope: $scope" ;;
   esac
-  model="$(umgpt_models_file_value "$UMGPT_REPOSITORY_MODELS_FILE" "$key")"
-  printf '%s\n' "$model"
+  umgpt_models_file_value "$UMGPT_REPOSITORY_MODELS_FILE" "$key"
 }
 
 ensure_umgpt_models_file() {
   local openai_model low_model home candidate base_url
   if [[ ! -e "$UMGPT_MODELS_FILE" ]]; then
-    openai_model="$(umgpt_repository_default_model "openai-only")"
-    low_model="$(umgpt_repository_default_model "low-sensitivity")"
+    openai_model="$(umgpt_repository_default_model "openai-only")" || return
+    low_model="$(umgpt_repository_default_model "low-sensitivity")" || return
     home="$(identity_home "umgpt")"
     if [[ -f "$home/config.toml" ]]; then
       candidate="$(config_value "$home/config.toml" "model")"
@@ -362,15 +361,14 @@ ensure_umgpt_models_file() {
 
 umgpt_default_model() {
   local scope="$1"
-  local key model
-  ensure_umgpt_models_file
+  local key
+  ensure_umgpt_models_file || return
   case "$scope" in
     openai-only) key="umgpt" ;;
     low-sensitivity) key="umgpt_low" ;;
     *) die "unknown U-M GPT model scope: $scope" ;;
   esac
-  model="$(umgpt_models_file_value "$UMGPT_MODELS_FILE" "$key")"
-  printf '%s\n' "$model"
+  umgpt_models_file_value "$UMGPT_MODELS_FILE" "$key"
 }
 
 replace_identity_model() {
@@ -624,6 +622,9 @@ create_umgpt() {
   fi
   local name="${2:-umgpt}"
   validate_umgpt_model "openai-only" "$model"
+  if [[ "$name" == "umgpt" && "$explicit" -eq 1 && -e "$UMGPT_MODELS_FILE" ]]; then
+    umgpt_models_file_value "$UMGPT_MODELS_FILE" umgpt >/dev/null || return
+  fi
   create_api_identity \
     "$name" \
     "$UMGPT_BASE_URL" \
@@ -649,6 +650,9 @@ create_umgpt_low() {
   fi
   local name="${2:-umgpt-low}"
   validate_umgpt_model "low-sensitivity" "$model"
+  if [[ "$name" == "umgpt-low" && "$explicit" -eq 1 && -e "$UMGPT_MODELS_FILE" ]]; then
+    umgpt_models_file_value "$UMGPT_MODELS_FILE" umgpt_low >/dev/null || return
+  fi
   create_api_identity \
     "$name" \
     "$UMGPT_BASE_URL" \
@@ -673,7 +677,8 @@ config_values() {
 }
 
 config_value() {
-  config_values "$1" "$2" | head -n 1
+  # Drain the producer so large configs cannot fail with SIGPIPE under pipefail.
+  config_values "$1" "$2" | sed -n '1p'
 }
 
 set_umgpt_scope() {
@@ -744,16 +749,18 @@ load_secret_env() {
 fetch_model_ids() {
   local base_url="$1"
   local api_key="$2"
-  local url response ids status
+  local url quoted_url quoted_header response ids status
 
   command -v curl >/dev/null 2>&1 || die "curl is required for model discovery"
   command -v jq >/dev/null 2>&1 || die "jq is required for model discovery"
   url="${base_url%/}/models"
+  quoted_url="$(curl_config_quote "$url")" || return
+  quoted_header="$(curl_config_quote "Authorization: Bearer $api_key")" || return
 
   response="$(
     {
-      printf 'url = %s\n' "$(curl_config_quote "$url")"
-      printf 'header = %s\n' "$(curl_config_quote "Authorization: Bearer $api_key")"
+      printf 'url = %s\n' "$quoted_url"
+      printf 'header = %s\n' "$quoted_header"
       printf '%s\n' 'silent' 'show-error' 'fail-with-body'
     } | curl --config -
   )" || {
@@ -1822,8 +1829,8 @@ ensure_macos_vscode_open_with() (
   local plist_buddy="/usr/libexec/PlistBuddy"
   local runtime_app="$home/vscode-editor/VS Code - $name.app"
   [[ "${CODEX_MACOS_SKIP_REGISTER:-0}" != "1" ]] || return 0
-  app_dir="$HOME/Applications"
-  app="$(macos_vscode_open_with_path "$name")"
+  app="$(macos_vscode_open_with_path "$name")" || die "could not determine the VS Code Finder app path"
+  app_dir="$(dirname "$app")"
   source="$SCRIPT_DIR/VSCodeIdentity.applescript"
   [[ -f "$source" ]] || source="$REPOSITORY_ROOT/macos/VSCodeIdentity.applescript"
   [[ -f "$source" ]] || die "missing the VS Code Finder handler source"
@@ -1832,7 +1839,7 @@ ensure_macos_vscode_open_with() (
   [[ -x /usr/bin/codesign && -x "$plist_buddy" ]] || die "required macOS application tools were not found"
   [[ ! -L "$app_dir" ]] || die "refusing a symbolic link at $app_dir"
   mkdir -p "$app_dir" || die "could not create $app_dir"
-  app_dir="$(cd "$app_dir" && pwd -P)"
+  app_dir="$(cd "$app_dir" && pwd -P)" || die "could not open $app_dir"
   app="$app_dir/VS Code - $name.app"
   [[ ! -L "$app" ]] || die "refusing a symbolic link at $app"
   metadata="$(shasum -a 256 "$source" "$SCRIPT_DIR/$(basename "${BASH_SOURCE[0]}")" "$SCRIPT_DIR/../config/umgpt-models.toml")" || return 1
@@ -1850,40 +1857,52 @@ ensure_macos_vscode_open_with() (
   build="$(mktemp -d "$app_dir/.vscode-open-with.XXXXXX")" || die "could not stage the VS Code Finder app"
   cleanup_vscode_open_with() {
     local status=$?
-    if [[ "$status" -ne 0 && -d "$build/previous.app" && ! -e "$app" ]]; then
+    if [[ "$status" -ne 0 && -d "$build/previous.app" && ! -e "$app" && ! -L "$app" ]]; then
       mv "$build/previous.app" "$app" || true
     fi
-    rm -rf -- "$build"
+    if [[ "$status" -ne 0 && -e "$build/previous.app" ]]; then
+      printf 'Previous Finder app preserved at %s; restore it to %s after resolving the installation failure.\n' \
+        "$build/previous.app" "$app" >&2
+    else
+      rm -rf -- "$build"
+    fi
     return "$status"
   }
-  trap cleanup_vscode_open_with EXIT HUP INT TERM
+  trap cleanup_vscode_open_with EXIT
+  trap 'exit 129' HUP
+  trap 'exit 130' INT
+  trap 'exit 143' TERM
   candidate="$build/VS Code - $name.app"
   osacompile -o "$candidate" "$source" || die "could not compile the VS Code Finder app"
-  mkdir -p "$candidate/Contents/config"
-  cp "$SCRIPT_DIR/$(basename "${BASH_SOURCE[0]}")" "$candidate/Contents/Resources/codex-home"
-  cp "$SCRIPT_DIR/VSCodeIdentity.applescript" "$candidate/Contents/Resources/VSCodeIdentity.applescript" 2>/dev/null || \
-    cp "$REPOSITORY_ROOT/macos/VSCodeIdentity.applescript" "$candidate/Contents/Resources/VSCodeIdentity.applescript"
-  cp "$SCRIPT_DIR/../config/umgpt-models.toml" "$candidate/Contents/config/umgpt-models.toml"
-  printf '%s\n' "$name" >"$candidate/Contents/Resources/identity"
-  printf '%s\n' "$metadata" >"$candidate/Contents/Resources/codex-contexts-open-with"
+  # Callers may handle failure with ||, which disables Bash's errexit here.
+  mkdir -p "$candidate/Contents/config" || die "could not create the Finder app config directory"
+  cp "$SCRIPT_DIR/$(basename "${BASH_SOURCE[0]}")" "$candidate/Contents/Resources/codex-home" ||
+    die "could not bundle the Finder app helper"
+  cp "$source" "$candidate/Contents/Resources/VSCodeIdentity.applescript" ||
+    die "could not bundle the Finder handler source"
+  cp "$SCRIPT_DIR/../config/umgpt-models.toml" "$candidate/Contents/config/umgpt-models.toml" ||
+    die "could not bundle the U-M GPT model defaults"
+  printf '%s\n' "$name" >"$candidate/Contents/Resources/identity" || die "could not record the Finder app identity"
+  printf '%s\n' "$metadata" >"$candidate/Contents/Resources/codex-contexts-open-with" ||
+    die "could not record the Finder app ownership marker"
   info_plist="$candidate/Contents/Info.plist"
   "$plist_buddy" -c 'Delete :CFBundleIdentifier' "$info_plist" >/dev/null 2>&1 || true
-  "$plist_buddy" -c "Add :CFBundleIdentifier string org.codex-contexts.vscode.$name" "$info_plist"
+  "$plist_buddy" -c "Add :CFBundleIdentifier string org.codex-contexts.vscode.$name" "$info_plist" || die "could not configure the Finder app identifier"
   "$plist_buddy" -c 'Delete :CFBundleName' "$info_plist" >/dev/null 2>&1 || true
-  "$plist_buddy" -c "Add :CFBundleName string VS Code - $name" "$info_plist"
+  "$plist_buddy" -c "Add :CFBundleName string VS Code - $name" "$info_plist" || die "could not configure the Finder app name"
   "$plist_buddy" -c 'Delete :CFBundleDisplayName' "$info_plist" >/dev/null 2>&1 || true
-  "$plist_buddy" -c "Add :CFBundleDisplayName string VS Code - $name" "$info_plist"
+  "$plist_buddy" -c "Add :CFBundleDisplayName string VS Code - $name" "$info_plist" || die "could not configure the Finder app display name"
   "$plist_buddy" -c 'Delete :LSUIElement' "$info_plist" >/dev/null 2>&1 || true
-  "$plist_buddy" -c 'Add :LSUIElement bool true' "$info_plist"
+  "$plist_buddy" -c 'Add :LSUIElement bool true' "$info_plist" || die "could not configure the Finder app UI behavior"
   "$plist_buddy" -c 'Delete :CFBundleDocumentTypes' "$info_plist" >/dev/null 2>&1 || true
-  "$plist_buddy" -c 'Add :CFBundleDocumentTypes array' "$info_plist"
-  "$plist_buddy" -c 'Add :CFBundleDocumentTypes:0 dict' "$info_plist"
-  "$plist_buddy" -c 'Add :CFBundleDocumentTypes:0:CFBundleTypeName string Folder' "$info_plist"
-  "$plist_buddy" -c 'Add :CFBundleDocumentTypes:0:CFBundleTypeRole string Editor' "$info_plist"
-  "$plist_buddy" -c 'Add :CFBundleDocumentTypes:0:LSHandlerRank string Alternate' "$info_plist"
-  "$plist_buddy" -c 'Add :CFBundleDocumentTypes:0:LSItemContentTypes array' "$info_plist"
-  "$plist_buddy" -c 'Add :CFBundleDocumentTypes:0:LSItemContentTypes:0 string public.folder' "$info_plist"
-  chmod 700 "$candidate/Contents/Resources/codex-home"
+  "$plist_buddy" -c 'Add :CFBundleDocumentTypes array' "$info_plist" || die "could not configure Finder document types"
+  "$plist_buddy" -c 'Add :CFBundleDocumentTypes:0 dict' "$info_plist" || die "could not configure the Finder folder handler"
+  "$plist_buddy" -c 'Add :CFBundleDocumentTypes:0:CFBundleTypeName string Folder' "$info_plist" || die "could not configure the Finder folder type"
+  "$plist_buddy" -c 'Add :CFBundleDocumentTypes:0:CFBundleTypeRole string Editor' "$info_plist" || die "could not configure the Finder folder role"
+  "$plist_buddy" -c 'Add :CFBundleDocumentTypes:0:LSHandlerRank string Alternate' "$info_plist" || die "could not configure the Finder handler rank"
+  "$plist_buddy" -c 'Add :CFBundleDocumentTypes:0:LSItemContentTypes array' "$info_plist" || die "could not configure Finder content types"
+  "$plist_buddy" -c 'Add :CFBundleDocumentTypes:0:LSItemContentTypes:0 string public.folder' "$info_plist" || die "could not configure the Finder folder content type"
+  chmod 700 "$candidate/Contents/Resources/codex-home" || die "could not make the Finder app helper executable"
   /usr/bin/codesign --force --deep --sign - "$candidate" >/dev/null || die "could not sign the VS Code Finder app"
   macos_vscode_unregister_editor "$runtime_app"
   if [[ -e "$app" ]]; then mv "$app" "$build/previous.app" || die "could not stage the old VS Code Finder app"; fi
 
@@ -33,14 +33,14 @@ The bundled helper opens a named copy of VS Code for each identity, such as
 `VS Code - work` or `VS Code - default`. Hover over its running Dock icon to
 read the identity, or click it to focus the editor. Projects using a running
 identity are sent to that instance. The installer also creates identity-specific
-Finder handlers named `VS Code - NAME`. Choose **Open With > VS Code - NAME** to
-open a folder through the matching identity. The folder must have an approved
+app handlers named `VS Code - NAME` for file managers that expose folder handlers
+in an **Open With** menu, such as ForkLift. The folder must have an approved
 `.envrc` selecting that identity and its generated workspace. If it selects a
 different identity, the handler reports the mismatch instead of opening the
-wrong account. Use **Codex Project** when you need to set up or change a folder
-context. Do not pin or directly relaunch the generated editor copies under
-`~/.codex-homes`; those copies need the helper's environment and launch
-arguments. See
+wrong account. Finder exposes folder actions through **Quick Actions** and
+**Services**; use **Open in Codex Project** there. Do not pin or directly
+relaunch the generated editor copies under `~/.codex-homes`; those copies need
+the helper's environment and launch arguments. See
 [macOS Dock names](projects-vscode.md#macos-dock-names) for copy refresh and
 the original-editor opt-out.
 
@@ -72,13 +72,16 @@ In Finder:
    folder, choose an identity directly.
 
 You can also select a folder and use **Finder > Services > Open in Codex
-Project**. If **Open With > Codex Project** is available, it opens the same app;
-folder context menus do not consistently offer that route. Do not choose
-**Change All**; Finder should remain the normal default handler for folders.
-
-For an already configured project, **Open With > VS Code - NAME** routes the
-folder through the matching identity. The handler passes it to `codex-home`,
-which opens the project workspace and uses the named Dock instance.
+Project**. In Finder, this is the supported folder route; the app offers the
+current context and setup/change actions. File managers such as ForkLift may
+also expose **Open With > VS Code - NAME** for a direct identity-specific
+launch. Do not choose **Change All**; Finder should remain the normal default
+handler for folders.
+
+In file managers that provide an **Open With** menu for folders, choose
+**VS Code - NAME** to route an already configured project through that
+identity. The handler passes it to `codex-home`, which opens the project
+workspace and uses the named Dock instance.
 
 When the folder has no `.envrc`, the app goes straight to identity selection.
 When it is already configured, the menu offers:
 
@@ -267,20 +267,21 @@ the source application. Where cloning is unavailable, macOS makes a normal
 copy, which can use a full application's worth of storage per identity. The
 original VS Code installation remains available for ordinary use.
 
-On macOS, the Finder installer creates a small handler app at
-`~/Applications/VS Code - NAME.app` for each configured identity. It appears in
-**Open With** and forwards the selected folder to `codex-home vscode NAME`.
-The actual editor copy remains under `CODEX_HOME/vscode-editor`, where the
-helper keeps its separate Dock name without registering it as a direct folder
-opener.
+On macOS, the Finder integration creates a small handler app at
+`~/Applications/VS Code - NAME.app` for each configured identity. File managers
+that expose folder handlers in an **Open With** menu, such as ForkLift, can use
+it to forward the folder to `codex-home vscode NAME`. In Finder, use **Quick
+Actions > Open in Codex Project** or **Services > Open in Codex Project**; that
+app reads the folder's current context. The actual editor copy remains under
+`CODEX_HOME/vscode-editor` and keeps its separate Dock name.
 
 Hover over a running editor's Dock icon to read its identity. Clicking that
 running icon focuses the editor. The icon artwork remains VS Code's, while
 the workspace title and status-bar color also identify the selected context.
 
-**After quitting, start the identity through the Finder Quick Action, its
-matching Open With entry, or `codex-home`.** Do not pin or directly open the
-generated editor copies: macOS launches them without the helper's
+**After quitting, start the identity through the Finder Quick Action, a
+file-manager Open With handler, or `codex-home`.** Do not pin or directly open
+the generated editor copies: macOS launches them without the helper's
 `CODEX_HOME`, approved environment, or `--user-data-dir` arguments.
 
 Update the original VS Code installation and let the helper refresh its
 
@@ -39,15 +39,16 @@ copies under `$CODEX_HOME/vscode-editor/`; hover over a running icon to read
 colors also identify the context.
 
 Quit the intended identity and reopen its project through the helper, Finder's
-**Open With > VS Code - NAME** handler, or the **Codex Project** Quick Action.
-Each named Finder handler checks that the folder's `.envrc` selects the same
-identity before opening it. If `CODEX_VSCODE_DOCK_LABEL=0` is set, the helper
+**Open in Codex Project** Quick Action/Service, or a file manager's
+**Open With > VS Code - NAME** handler. The identity-specific handler checks
+that the folder's `.envrc` selects the same identity before opening it. If
+`CODEX_VSCODE_DOCK_LABEL=0` is set, the helper
 uses the original installed editor without the named editor copy. An
 already-running identity keeps its original application until it quits.
 
 Clicking a running Dock icon focuses that editor. **After quitting, use
-Finder > Quick Actions > Open in Codex Project, Open With > VS Code - NAME,
-or `codex-home vscode`.** Do not pin or directly launch the generated editor
+Finder > Quick Actions > Open in Codex Project, a file manager's Open With
+> VS Code - NAME, or `codex-home vscode`.** Do not pin or directly launch the generated editor
 copies under the identity home: a direct macOS launch does not supply the
 identity environment and isolated user-data arguments.
 
 
@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+
+resolve_codex_home_tool() {
+  local bin_dir="$1" candidate
+  local -a matches=()
+  for candidate in "$bin_dir"/*home; do
+    [[ -f "$candidate" && -x "$candidate" ]] && matches+=("$candidate")
+  done
+  if [[ "${#matches[@]}" -ne 1 ]]; then
+    printf 'test setup failure: expected one executable *home tool in %s; found %s\n' \
+      "$bin_dir" "${#matches[@]}" >&2
+    return 1
+  fi
+  printf '%s\n' "${matches[0]}"
+}