Reference

Troubleshooting and privacy

First identify whether the issue concerns configuration sync, local events, or remote delivery. Check that layer directly; a failure later in the chain does not prove an earlier layer failed.

iPhone ↔ Watch

The Sync button is unavailable or reports failure

  • Check that iPhone and Watch are paired and both have the current version of bluebell.
  • Make both apps reachable. “Paired” does not mean WCSession.isReachable is currently true.
  • Tap the circular arrows on the home screen to refresh the connection status. This does not send settings.
  • Tap “Sync” again and wait for Watch to save the configuration and return a matching source/revision acknowledgment.
  • After a timeout or failure, avoid repeated rapid taps. Make sure the Watch app is active, then retry.

Reminder changes and Flow saves affecting reminders are automatic-publication exceptions. Ordinary training settings still use manual sync from the home screen.

Apple Watch

Haptics stop, time freezes, or Double Tap does not respond

  • Pressing the Crown, switching apps, resource limits, or runtime expiry may freeze the activity in a paused state.
  • Resuming does not replay haptics that already occurred or were missed. It continues from the exact remaining time saved at the pause.
  • Judge haptic feel and distinctness on a real Watch. The simulator has no physical equivalent.
  • Double Tap requires a supported model, watchOS 11+, an awake and unlocked Watch, and a primary action on the current screen.

Read the full Double Tap troubleshooting guide →

Local delivery

A bluebellctl event does not appear in recent notifications

  1. Check the help first.
    Terminal
    '/Applications/bluebellMac.app/Contents/Helpers/bluebellctl' --help
  2. Make sure bluebell Mac is running.

    The CLI does not launch the app automatically.

  3. Copy the CLI path from the app again.

    Moving or renaming the app invalidates the old path in your hooks.

  4. Run --local test.

    Exit 2 indicates an argument, JSON, or IPC issue. Exit 4 means the app rejected the event.

Advanced diagnostics: the local socket is at ~/Library/Application Support/Bluebell/EventHub.sock. The directory should have permissions 0700; the socket and state file should have 0600. Each input is limited to 64 KiB.

CloudKit and system notifications

Mac has a record, but Watch shows no notification

  1. Check that the event was not sent with --local.
  2. Check that “Deliver to Watch and iPhone” is enabled on Mac. Events received while it was off are not sent when it is turned back on.
  3. Check “Local connection,” “iCloud,” and “Delivery queue” separately. iCloud availability does not mean a record was written.
  4. If a retry card appears, follow its specific guidance to check the CloudKit environment, schema, indexes, entitlements, and current build.
  5. Check that iPhone and Watch use the same iCloud account and Development/Production environment, and have system notification permission.

Minimum necessary data

Which Agent event fields are uploaded?

Uploaded Kept on Mac only
schemaVersion, eventID, source, completed type, project display name, short summary/notification body, occurrence time, and a randomly generated originDeviceID Full workspace path, session/turn IDs, dedupeKey, raw payload, and tool callback contents
Project names or summaries you enter may contain sensitive information Prompts, source code, and full transcripts are not automatic upload fields

iPad configuration sync also uploads a full snapshot of training settings, Flow names and definitions, reminders, and local notification preferences in separate private cloud records. bluebell does not promise automatic redaction. Adapters should send only what needs to appear on a device and avoid putting assistant messages, full paths, or raw tool JSON in summaries.