docs: make tmux permission diagnostics reproducible
Follow-up to #12219, incorporating and crediting @haung921209. Improves diagnostics by comparing exact operations across shell contexts and documenting server inspection.\n\nValidation: git diff --check; Linux shell and isolated tmux checks; python3 scripts/swift_file_length_budget.py. Builds were not run per Linux-only constraints. Localization audit: Markdown only; no catalogs changed.
![View with [code]smith](https://pr-comments-assets.blacksmith.sh/codesmith/view-with-codesmith-dark-v2.svg)
![Autofix with [code]smith](https://pr-comments-assets.blacksmith.sh/codesmith/autofix-with-codesmith-dark.svg)
Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.
[!NOTE]
Low Risk
Markdown-only documentation with no runtime, API, or security behavior changes.
Overview
Adds a Diagnosing protected-folder access errors section to docs/local-tmux.md for macOS-style Operation not permitted failures in tmux (e.g. under ~/Documents).
The guide tells users to capture evidence before restarting cmux or tmux, inspect the running server (tmux display-message, ps, lsof), query the correct socket (-S, cmux local-tmux list --json), and compare the same absolute-path operations across tmux, cmux, and another terminal using copy-paste POSIX snippets for directory listing and file read. It also lists what to include in bug reports, distinguishes EPERM from EACCES, and links Apple guidance and issue #2866 as an investigation reference—not a single root cause.
Reviewed by Cursor Bugbot for commit 0002c27ec2cfc1745fdffa13a2404030a86c7630. Bugbot is set up for automated code reviews on this repo. Configure here.
Summary by cubic
Adds a documented procedure for diagnosing Operation not permitted errors in tmux panes, so failures are recorded before any restart or permission change. The new section covers identifying the server, comparing the exact failing command across shell contexts, and reporting the right data without including private contents.