From a6cce2fec1cac8709daf212e240c3f64d6b4138b Mon Sep 17 00:00:00 2001 From: haung921209 <14533484+haung921209@users.noreply.github.com> Date: Wed, 9 Sep 2026 19:19:18 +0900 Subject: [PATCH 1/5] docs: add protected-folder diagnostics for tmux sessions --- docs/local-tmux.md | 45 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) diff --git a/docs/local-tmux.md b/docs/local-tmux.md index 4e245b3638c0..76298f2c097c 100644 --- a/docs/local-tmux.md +++ b/docs/local-tmux.md @@ -95,6 +95,51 @@ GUI/API operations still use cmux's authenticated control socket. Headless operations are limited by the operating-system user; do not share the state directory or socket with another Unix user. +## Diagnosing protected-folder access errors + +If a shell in tmux reports `Operation not permitted` while reading a file in +`~/Documents` or another protected folder, record the failure before restarting +cmux, replacing the tmux server, or changing permissions. A live server and a +successful attach do not establish that its child processes can read that file. + +First identify the affected server. Inside the affected tmux pane, run: + +```sh +tmux display-message -p 'socket=#{socket_path} server_pid=#{pid} server_version=#{version}' +tmux -V +``` + +`server_version` comes from the running server; `tmux -V` describes the client +binary currently on `PATH`. They can differ after a package upgrade. Record the +server PID and start time as well as the cmux and macOS versions. On macOS, `ps` +and `lsof` can help inspect the selected PID's start time and mapped executable. + +Outside the pane, use `tmux -S ` to query the same server, or +`tmux -L ` for an explicitly named server. A plain `tmux ls` does not +list every server. For the cmux local-tmux profile, `cmux local-tmux list --json` +includes `socket_path`; external tmux launchers may use a different socket. +Do not infer that a session died from a query against another socket. + +Use one harmless, existing file to compare a direct shell and the affected pane. +Record the exact command, time, and exit status without including private file +contents. If a separate server succeeds, also record its version and launch +context: that result alone does not isolate server age, TCC state, or cmux as the +cause. If a later retry succeeds without intervention, report the failure as +currently non-reproducible rather than permanently fixed. + +When reporting the problem, include: + +- Whether the session uses `cmux local-tmux` or an external launcher. +- The affected server's version/start time and how its socket was selected. +- The failing operation and the results of the same-file comparison. +- Any available permission-denial record at the failure time, with private paths + and unrelated process details removed. + +`EPERM` is not specific to TCC, and a daemon's parent PID alone does not identify +its responsible application. See Apple's [file-system permissions guidance](https://developer.apple.com/forums/thread/678819). +The related [protected-folder report](https://github.com/manaflow-ai/cmux/issues/2866) +is an investigation, not evidence that every similar failure has the same cause. + ## Limitations - This slice requires a local `tmux` executable (or `CMUX_LOCAL_TMUX_BIN`). From 2251c648d1673f47f691cedc12f8fbd3e714a6a8 Mon Sep 17 00:00:00 2001 From: haung921209 <14533484+haung921209@users.noreply.github.com> Date: Wed, 9 Sep 2026 19:24:26 +0900 Subject: [PATCH 2/5] docs: distinguish tested builds and replaced tmux executables --- docs/local-tmux.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/local-tmux.md b/docs/local-tmux.md index 76298f2c097c..aff590353688 100644 --- a/docs/local-tmux.md +++ b/docs/local-tmux.md @@ -113,6 +113,8 @@ tmux -V binary currently on `PATH`. They can differ after a package upgrade. Record the server PID and start time as well as the cmux and macOS versions. On macOS, `ps` and `lsof` can help inspect the selected PID's start time and mapped executable. +If the mapped executable path has been replaced or removed, record that too; it +is a possible confounding factor, not proof of the permission failure's cause. Outside the pane, use `tmux -S ` to query the same server, or `tmux -L ` for an explicitly named server. A plain `tmux ls` does not @@ -130,6 +132,8 @@ currently non-reproducible rather than permanently fixed. When reporting the problem, include: - Whether the session uses `cmux local-tmux` or an external launcher. +- The tested app build/revision and whether newer relevant changes were tested; + a marketing version alone may not distinguish a release from a development build. - The affected server's version/start time and how its socket was selected. - The failing operation and the results of the same-file comparison. - Any available permission-denial record at the failure time, with private paths From 425bc60dd704e7fbe321b0196969eeb10e59574d Mon Sep 17 00:00:00 2001 From: haung921209 <14533484+haung921209@users.noreply.github.com> Date: Wed, 9 Sep 2026 19:30:31 +0900 Subject: [PATCH 3/5] docs: address review on wrapping and errno distinctions --- docs/local-tmux.md | 37 ++++++++++++++++++++++++------------- 1 file changed, 24 insertions(+), 13 deletions(-) diff --git a/docs/local-tmux.md b/docs/local-tmux.md index aff590353688..e8ea860ff233 100644 --- a/docs/local-tmux.md +++ b/docs/local-tmux.md @@ -111,21 +111,26 @@ tmux -V `server_version` comes from the running server; `tmux -V` describes the client binary currently on `PATH`. They can differ after a package upgrade. Record the -server PID and start time as well as the cmux and macOS versions. On macOS, `ps` -and `lsof` can help inspect the selected PID's start time and mapped executable. +server PID and start time as well as the cmux and macOS versions. On macOS, +`ps` +and `lsof` can help inspect the selected PID's start time and mapped +executable. If the mapped executable path has been replaced or removed, record that too; it is a possible confounding factor, not proof of the permission failure's cause. Outside the pane, use `tmux -S ` to query the same server, or -`tmux -L ` for an explicitly named server. A plain `tmux ls` does not -list every server. For the cmux local-tmux profile, `cmux local-tmux list --json` -includes `socket_path`; external tmux launchers may use a different socket. +`tmux -L ` for an explicitly named server. A plain `tmux ls` +does not list every server. For the cmux local-tmux profile, +`cmux local-tmux list --json` includes `socket_path`; external tmux launchers +may use a different socket. Do not infer that a session died from a query against another socket. -Use one harmless, existing file to compare a direct shell and the affected pane. +Use one harmless, existing file to compare a direct shell and the affected +pane. Record the exact command, time, and exit status without including private file contents. If a separate server succeeds, also record its version and launch -context: that result alone does not isolate server age, TCC state, or cmux as the +context: that result alone does not isolate server age, TCC state, or cmux as +the cause. If a later retry succeeds without intervention, report the failure as currently non-reproducible rather than permanently fixed. @@ -133,16 +138,22 @@ When reporting the problem, include: - Whether the session uses `cmux local-tmux` or an external launcher. - The tested app build/revision and whether newer relevant changes were tested; - a marketing version alone may not distinguish a release from a development build. + a marketing version alone may not distinguish a release from a development + build. - The affected server's version/start time and how its socket was selected. - The failing operation and the results of the same-file comparison. -- Any available permission-denial record at the failure time, with private paths +- Any available permission-denial record at the failure time, with private + paths and unrelated process details removed. -`EPERM` is not specific to TCC, and a daemon's parent PID alone does not identify -its responsible application. See Apple's [file-system permissions guidance](https://developer.apple.com/forums/thread/678819). -The related [protected-folder report](https://github.com/manaflow-ai/cmux/issues/2866) -is an investigation, not evidence that every similar failure has the same cause. +`EPERM` is not specific to TCC, and a daemon's parent PID alone does not +identify +its responsible application. `Operation not permitted` (EPERM) and +`Permission denied` (EACCES) are different errors; record the exact wording or +errno rather than treating them as interchangeable. See +[Apple's guidance](https://developer.apple.com/forums/thread/678819). +The related [report](https://github.com/manaflow-ai/cmux/issues/2866) is an +investigation, not evidence that every similar failure has the same cause. ## Limitations From 4f9db46ba1aef9f3d164e91dd23905733ffbd4cb Mon Sep 17 00:00:00 2001 From: Austin Wang Date: Fri, 11 Sep 2026 22:32:55 +0000 Subject: [PATCH 4/5] docs: make tmux permission diagnostics reproducible --- docs/local-tmux.md | 64 ++++++++++++++++++++++++++++++++++------------ 1 file changed, 48 insertions(+), 16 deletions(-) diff --git a/docs/local-tmux.md b/docs/local-tmux.md index e8ea860ff233..d0b4fa908d59 100644 --- a/docs/local-tmux.md +++ b/docs/local-tmux.md @@ -112,9 +112,14 @@ tmux -V `server_version` comes from the running server; `tmux -V` describes the client binary currently on `PATH`. They can differ after a package upgrade. Record the server PID and start time as well as the cmux and macOS versions. On macOS, -`ps` -and `lsof` can help inspect the selected PID's start time and mapped -executable. +substitute the reported server PID in these read-only commands: + +```sh +ps -p -o pid=,ppid=,lstart=,command= +lsof -a -p -d txt +``` + +The `txt` entries show mapped executable and code files. If the mapped executable path has been replaced or removed, record that too; it is a possible confounding factor, not proof of the permission failure's cause. @@ -125,14 +130,43 @@ does not list every server. For the cmux local-tmux profile, may use a different socket. Do not infer that a session died from a query against another socket. -Use one harmless, existing file to compare a direct shell and the affected -pane. -Record the exact command, time, and exit status without including private file -contents. If a separate server succeeds, also record its version and launch -context: that result alone does not isolate server age, TCC state, or cmux as -the -cause. If a later retry succeeds without intervention, report the failure as -currently non-reproducible rather than permanently fixed. +Compare the original failing operation in the affected pane, a direct cmux +shell outside tmux, and a direct shell in the other terminal app. Use the same +absolute path and record which app hosts each shell. For a directory-listing +failure, run this POSIX-shell snippet in each context, replacing the example +path with the affected directory: + +```sh +diagnostic_dir="$HOME/Documents/path/to/affected-directory" +date -u '+%Y-%m-%dT%H:%M:%SZ' +/bin/ls -a "$diagnostic_dir" > /dev/null +diagnostic_status=$? +printf 'directory listing exit=%s\n' "$diagnostic_status" +``` + +Standard output is discarded to avoid printing directory entries; standard +error remains visible so the exact error can be recorded. If the original +failure used a relative path such as `ls .`, also record the working directory +and repeat that exact command: a fresh lookup by absolute path may behave +differently from access through an existing working directory. + +For a file-read failure, choose one harmless, existing regular file and use +this additional check in the same shell contexts: + +```sh +diagnostic_file="$HOME/Documents/path/to/harmless-file" +date -u '+%Y-%m-%dT%H:%M:%SZ' +cat "$diagnostic_file" > /dev/null +diagnostic_status=$? +printf 'file read exit=%s\n' "$diagnostic_status" +``` + +A successful file read does not establish that listing its directory works. +Record each command, time, exact error, and exit status without including +private contents. If a separate server succeeds, also record its version and +launch context: that result alone does not isolate server age, TCC state, or +cmux as the cause. If a later retry succeeds without intervention, report the +failure as currently non-reproducible rather than permanently fixed. When reporting the problem, include: @@ -141,13 +175,11 @@ When reporting the problem, include: a marketing version alone may not distinguish a release from a development build. - The affected server's version/start time and how its socket was selected. -- The failing operation and the results of the same-file comparison. +- The failing operation and the results for the same path in each shell context. - Any available permission-denial record at the failure time, with private - paths - and unrelated process details removed. + paths and unrelated process details removed. -`EPERM` is not specific to TCC, and a daemon's parent PID alone does not -identify +`EPERM` is not specific to TCC, and a daemon's parent PID alone does not identify its responsible application. `Operation not permitted` (EPERM) and `Permission denied` (EACCES) are different errors; record the exact wording or errno rather than treating them as interchangeable. See From ba29b1642dae4a286ec9869f7512f49a7bc3b010 Mon Sep 17 00:00:00 2001 From: Leo Li Date: Thu, 1 Oct 2026 17:23:34 -0700 Subject: [PATCH 5/5] docs: make tmux socket diagnostics read-only Co-Authored-By: Claude Opus 5.5 --- docs/local-tmux.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/docs/local-tmux.md b/docs/local-tmux.md index d0b4fa908d59..13b32f2178fa 100644 --- a/docs/local-tmux.md +++ b/docs/local-tmux.md @@ -123,9 +123,15 @@ The `txt` entries show mapped executable and code files. If the mapped executable path has been replaced or removed, record that too; it is a possible confounding factor, not proof of the permission failure's cause. -Outside the pane, use `tmux -S ` to query the same server, or -`tmux -L ` for an explicitly named server. A plain `tmux ls` -does not list every server. For the cmux local-tmux profile, +Outside the pane, query the same server with an explicit read-only command: + +```sh +tmux -S "" display-message -p 'socket=#{socket_path} server_pid=#{pid} server_version=#{version}' +tmux -L "" display-message -p 'socket=#{socket_path} server_pid=#{pid} server_version=#{version}' +``` + +Use the `-L` form for an explicitly named server. A plain `tmux ls` does not +list every server. For the cmux local-tmux profile, `cmux local-tmux list --json` includes `socket_path`; external tmux launchers may use a different socket. Do not infer that a session died from a query against another socket.