Recorder binary crashes on macOS 26 (Tahoe) — exit code 2, TCC permission loop

[mertkalak]

Description

The native recorder binary crashes repeatedly on macOS 26.2 (Tahoe) (Build 25C56, Darwin 25.2.0), causing a max_restarts error. The binary exits with code 2 (not a segfault — controlled exit), due to a breaking TCC policy change in macOS Tahoe.

Root Cause: macOS Tahoe TCC Policy Change

This is a confirmed, widespread macOS Tahoe breaking change affecting all non-bundled screen recording binaries.

Apple changed the TCC (Transparency, Consent, and Control) security model in macOS 26. Plain binaries and background services are now completely invisible to the screen recording permission system. The OS demands that any process requesting screen pixels must be a proper native App Bundle with a valid Info.plist and Bundle Identifier.

This means the VideoDB recorder binary (a raw Mach-O executable in node_modules/videodb/bin/recorder) cannot receive screen recording permission on Tahoe — it won't appear in System Settings, won't get prompted, and TCC silently denies it.

Other affected projects

• Sunshine (screen sharing) — fixed via native wrapper method
• Isadora (media server) — logged as known issue
• RustDesk — reported screen recording permission invalid

Environment

• macOS: 26.2 (Tahoe) — Build 25C56
• Architecture: Apple Silicon (arm64)
• videodb SDK: 0.2.0 (latest)
• Claude Code plugin: pair-programmer 1.0.0
• Terminal: Warp

Error

Uncaught Exception:
Error [ERR_UNHANDLED_ERROR]: Unhandled error. ({
  type: 'max_restarts',
  message: 'Binary crashed too many times. Please check logs.'
})
  at CaptureClient.emit (node:events:506:17)
  at BinaryManager.<anonymous> (captureClient.js:56:18)

Investigation

1. Binary loads fine — DYLD_PRINT_LIBRARIES=1 shows all libraries (AVFoundation, AVFCapture, CoreAudio, etc.) resolve correctly.

2. Exit code is 2, not a crash — No crash reports in ~/Library/Logs/DiagnosticReports/. The binary exits with code 2 in a controlled manner.

3. TCC permission loop — macOS system logs show repeated TCCAccessRequest() IPC calls with connections being immediately invalidated:

   recorder: (TCC) TCCAccessRequest() IPC
   recorder: [com.apple.xpc:connection] activating connection: com.apple.tccd.system
   recorder: [com.apple.xpc:connection] invalidated after the last release
   

4. All macOS permissions granted — Screen Recording, Microphone, and Accessibility are all enabled for Warp in System Settings.

5. Ad-hoc code signing didn't help — The binary was originally unsigned. Signing with codesign --force --sign - didn't resolve the TCC issue because the fundamental problem is the lack of an App Bundle structure.

Suggested Fix

Wrap the recorder binary inside a proper macOS .app bundle with:

• A valid Info.plist with CFBundleIdentifier
• A Swift/ObjC launcher that spawns the recorder binary as a child process
• Proper code signing (codesign --force --deep --sign -)

This is the approach that worked for Sunshine and other affected projects. Example:

VideoDBRecorder.app/
  Contents/
    Info.plist          (with CFBundleIdentifier)
    MacOS/
      Launcher          (Swift binary that spawns recorder)
    Resources/
      recorder          (original binary)
      librecorder.dylib

Workaround

None currently available for end users. The binary must be repackaged as an App Bundle by the VideoDB team.

[mertkalak]

✅ Working Fix: App Bundle Wrapper

I was able to fix this locally by wrapping the recorder binary in a proper macOS .app bundle. Recording now works on macOS 26.2 (Tahoe).

The Fix (3 steps)

1. Create the App Bundle

BIN_DIR="<plugin-root>/node_modules/videodb/bin"
APP_DIR="${BIN_DIR}/VideoDBRecorder.app"

# Create bundle structure
mkdir -p "${APP_DIR}/Contents/MacOS"
mkdir -p "${APP_DIR}/Contents/Resources"

# Copy binaries into bundle
cp "${BIN_DIR}/recorder" "${APP_DIR}/Contents/MacOS/recorder"
cp "${BIN_DIR}/librecorder.dylib" "${APP_DIR}/Contents/MacOS/librecorder.dylib"
cp "${BIN_DIR}/meet_detector" "${APP_DIR}/Contents/MacOS/meet_detector"
chmod 755 "${APP_DIR}/Contents/MacOS/recorder" "${APP_DIR}/Contents/MacOS/meet_detector"

2. Create Info.plist

Write this to ${APP_DIR}/Contents/Info.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>CFBundleExecutable</key>
    <string>recorder</string>
    <key>CFBundleIdentifier</key>
    <string>io.videodb.recorder.wrapper</string>
    <key>CFBundleName</key>
    <string>VideoDB Recorder</string>
    <key>CFBundlePackageType</key>
    <string>APPL</string>
    <key>CFBundleShortVersionString</key>
    <string>0.2.7</string>
    <key>LSUIElement</key>
    <true/>
    <key>NSMicrophoneUsageDescription</key>
    <string>VideoDB Recorder needs microphone access to capture audio.</string>
    <key>NSScreenCaptureUsageDescription</key>
    <string>VideoDB Recorder needs screen recording access to capture your screen.</string>
</dict>
</plist>

3. Sign the bundle and clear quarantine

# Sign dylib first, then binary, then full bundle
codesign --force --sign - "${APP_DIR}/Contents/MacOS/librecorder.dylib"
codesign --force --sign - "${APP_DIR}/Contents/MacOS/meet_detector"
codesign --force --sign - "${APP_DIR}/Contents/MacOS/recorder"
codesign --force --deep --sign - "${APP_DIR}"

# Clear quarantine attributes
xattr -cr "${APP_DIR}"

Patch binaryManager.js

In node_modules/videodb/dist/recorder/binaryManager.js, update getBinaryCommand() to use the bundled binary on macOS Tahoe:

getBinaryCommand() {
    // ... existing dev mode check ...

    // macOS Tahoe (26+) workaround: use app bundle wrapper for TCC compatibility.
    const path = require('path');
    const os = require('os');
    const fs = require('fs');
    const appBundlePath = path.join(__dirname, '..', '..', 'bin',
        'VideoDBRecorder.app', 'Contents', 'MacOS', 'recorder');
    if (os.platform() === 'darwin'
        && parseInt(os.release().split('.')[0]) >= 25
        && fs.existsSync(appBundlePath)) {
        return { command: appBundlePath, args: [] };
    }

    const binaryPath = this.installer.getBinaryPath();
    return { command: binaryPath, args: [] };
}

Why This Works

• The @rpath in the recorder binary resolves via @executable_path and @loader_path — both point to Contents/MacOS/ where the dylib lives
• The Info.plist with CFBundleIdentifier makes macOS Tahoe's TCC system recognize the binary as a proper app
• LSUIElement: true keeps it as a background app (no dock icon)
• The Darwin version check (>= 25) ensures this only activates on macOS Tahoe+, leaving older macOS versions unaffected
• Stdio piping from child_process.spawn() works identically since we're still spawning the same binary — just from a different path inside the bundle

Result

{
  "status": "ok",
  "recording": true,
  "sessionId": "cap-b89f75de-d54a-42b0-8fa4-614114956310",
  "duration": 6,
  "rtstreams": [
    {
      "rtstream_id": "rts-019c9676-1fda-7e61-b18d-0066f19b9d8d",
      "name": "screen",
      "scene_index_id": "8545af12389e8072",
      "index_type": "screen"
    }
  ]
}

Suggested Permanent Fix

Ship the recorder binary inside a proper .app bundle as part of the npm package, and update getBinaryPath() / getBinaryCommand() to use the bundled path on macOS 26+. This would make it work out of the box for all Tahoe users without manual patching.