docs: improve Full Disk Access troubleshooting

CHANGELOG.md

@@ -3,6 +3,7 @@
 ## Unreleased
 - feat: add `imsg group` chat metadata lookup and group fields to `chats --json` (#88, thanks @mryanb)
 - fix: speed up chat listing by using `chat_message_join.message_date` when available (#76, thanks @tmad4000)
+- docs: clarify stale Full Disk Access and Terminal.app troubleshooting (#28, #32, #33, #83)
 - fix: publish universal macOS release binaries for Homebrew installs (#68, #79)
 - fix: include group metadata in CLI JSON history/watch output (#57, thanks @clawbunny)
 - docs: document Homebrew install path in the README (#61, thanks @joshuayoes)

README.md

@@ -92,8 +92,13 @@ Note: `reply_to_guid`, `destination_caller_id`, and `reactions` are read-only me
 ## Permissions troubleshooting
 If you see “unable to open database file” or empty output:
 1) Grant Full Disk Access: System Settings → Privacy & Security → Full Disk Access → add your terminal.
-2) Ensure Messages.app is signed in and `~/Library/Messages/chat.db` exists.
-3) For send, allow the terminal under System Settings → Privacy & Security → Automation → Messages.
+2) If you launch `imsg` from an editor, Node process, gateway, or shell wrapper, grant Full Disk Access to that parent app too.
+3) Also add the built-in Terminal.app (`/System/Applications/Utilities/Terminal.app`). macOS can require the default terminal even when you normally use iTerm, VS Code, or another launcher.
+4) Toggle the Full Disk Access entry off and on after terminal, Homebrew, Node, or app updates; stale TCC grants can look enabled but still produce `authorization denied (code: 23)`.
+5) Ensure Messages.app is signed in and `~/Library/Messages/chat.db` exists.
+6) For send, allow the terminal under System Settings → Privacy & Security → Automation → Messages.
+
+`imsg` opens `chat.db` read-only. It does not use SQLite `immutable=1` by default because immutable reads can miss new Messages rows and WAL-backed updates.
 
 ## Advanced Features (SIP-Off Only)
 Advanced features (`typing`, `launch`, IMCore bridge) require injecting a helper dylib into `Messages.app`.

Sources/IMsgCore/Errors.swift

@@ -22,9 +22,10 @@ public enum IMsgError: LocalizedError, Sendable {
 
         To fix:
         1. Open System Settings → Privacy & Security → Full Disk Access
-        2. Add your terminal application (Terminal.app, iTerm, etc.)
-        3. Restart your terminal
-        4. Try again
+        2. Add your terminal application and any parent launcher (VS Code, Node, gateway, etc.)
+        3. Also add the built-in Terminal.app if you normally use another terminal
+        4. Toggle stale entries off and on after terminal/Homebrew/app updates
+        5. Restart the terminal or parent app, then try again
 
         Note: This is required because macOS protects the Messages database.
         For more details, see: https://github.com/steipete/imsg#permissions-troubleshooting

Tests/IMsgCoreTests/UtilityTests.swift

@@ -326,4 +326,7 @@ func errorDescriptionsIncludeDetails() {
   let permissionDescription = permission.errorDescription ?? ""
   #expect(permissionDescription.contains("Permission Error") == true)
   #expect(permissionDescription.contains("/tmp/chat.db") == true)
+  #expect(permissionDescription.contains("parent launcher") == true)
+  #expect(permissionDescription.contains("built-in Terminal.app") == true)
+  #expect(permissionDescription.contains("stale entries") == true)
 }