Refresh migration docs for broad auto approval

LOCAL_SETUP.txt

@@ -1,20 +1,34 @@
 # codex_exec local shell setup
 # ============================
 #
-# This file records the local runx/rund setup used on this machine. It is
-# also valid Bash and can be copied directly to $HOME/.bash_aliases.
+# This file is valid Bash. Copy it to $HOME/.bash_aliases, then reload your
+# shell with:
 #
-# Required files:
-#   runx: $HOME/codex_auto_run.py
-#   rund: $HOME/claude_auto_run.py (not included in this repository)
-#
-# Install and reload:
-#   cp LOCAL_SETUP.txt $HOME/.bash_aliases
 #   source $HOME/.bashrc
+#
+# It defines one command:
+#
+#   runx
+#
+# runx launches $HOME/codex_auto_run.py with a tmux session prefix derived from
+# the current directory. That keeps watcher state and logs separate per project.
+#
+# Install from a fresh clone:
+#
+#   git clone https://huggingface.co/yitongl/codex_exec ~/codex_exec
+#   cp ~/codex_exec/codex_auto_run.py ~/codex_auto_run.py
+#   chmod +x ~/codex_auto_run.py
+#   cp ~/codex_exec/LOCAL_SETUP.txt ~/.bash_aliases
+#   source ~/.bashrc
+#
+# If you keep codex_auto_run.py somewhere other than $HOME/codex_auto_run.py,
+# edit CODEX_AUTORUN_SCRIPT below before copying this file.
+
+unalias runx 2>/dev/null || true
 
-unalias runx rund 2>/dev/null || true
+CODEX_AUTORUN_SCRIPT="${CODEX_AUTORUN_SCRIPT:-$HOME/codex_auto_run.py}"
 
-_autorun_dir_name() {
+_codex_autorun_dir_name() {
     local rel
 
     if [[ "$PWD" == "$HOME" ]]; then
@@ -35,7 +49,8 @@ _autorun_dir_name() {
     done
     [[ -n "$rel" ]] || rel="home"
 
-    # codex_auto_run.py limits a session prefix to 48 characters.
+    # codex_auto_run.py limits a session prefix to 48 characters. Leave room
+    # for the "-x" suffix.
     if (( ${#rel} > 45 )); then
         rel="${rel:0:28}-${rel: -16}"
     fi
@@ -44,49 +59,26 @@ _autorun_dir_name() {
 
 runx() {
     local base
-    base="$(_autorun_dir_name)"
-    python3 "$HOME/codex_auto_run.py" --session-prefix "${base}-x" "$@"
+    base="$(_codex_autorun_dir_name)"
+    python3 "$CODEX_AUTORUN_SCRIPT" --session-prefix "${base}-x" "$@"
 }
 
-rund() {
-    local base
-    base="$(_autorun_dir_name)"
-    python3 "$HOME/claude_auto_run.py" --session-prefix "${base}-d" "$@"
-}
-
-# Usage:
-#   cd $HOME/code/my_project
-#   runx
-#   rund
+# Examples:
 #
-# Start with an initial prompt:
+#   cd $HOME/code/my_project
 #   runx -p "Inspect the project, make the requested changes, and run tests."
-#   rund -p "Inspect the project, make the requested changes, and run tests."
 #
 # Enable Codex web search:
+#
 #   runx -p "Research and complete the task." -- --search
 #
-# Because the launchers default to the current directory, -C is unnecessary
-# after cd. Additional arguments are passed through unchanged.
+# Disable broad MCP/app or directory-trust auto approval when needed:
 #
-# Tmux naming for $HOME/code/my_project:
-#   code-my_project-x    Codex / runx
-#   code-my_project-d    Claude / rund
+#   runx --no-approve-mcp -p "Work without app/tool auto approval."
+#   runx --no-auto-trust-directory -p "Work without automatic directory trust."
 #
-# The launcher appends a timestamp/PID uniqueness suffix to the actual tmux
-# session name. The -x and -d suffixes deliberately keep the Codex and Claude
-# approval watchers from scanning each other's sessions.
+# Status, logs, and daemon control from the same project directory:
 #
-# Run status or stop commands from the same project directory so the dynamic
-# prefix matches:
 #   runx --status
-#   rund --status
+#   tail -f ~/.runtime/$(_codex_autorun_dir_name)-x/approve-debug.log
 #   runx --stop-daemon
-#   rund --stop-daemon
-#
-# Optional global Codex skill on this machine:
-#   Path:   $HOME/.codex/skills/codex-autorun
-#   Invoke: $codex-autorun
-#
-# The filesystem skill name uses a hyphen because Codex skill identifiers do
-# not allow underscores; its UI display name is codex_autorun.

README.md

@@ -8,66 +8,122 @@ tags:
 
 # codex_exec
 
-`codex_exec` is an **unofficial** launcher for the interactive OpenAI Codex TUI. It starts a real interactive `codex` session inside `tmux` and runs a small watcher that can confirm recognized approval and selection overlays automatically.
+`codex_exec` is an unofficial launcher for the interactive OpenAI Codex TUI.
+It starts a real interactive `codex` session inside `tmux` and runs a watcher
+that automatically confirms recognized Codex approval and selection overlays.
 
-Despite the repository name, this is **not** `codex exec` and it does not turn Codex into a non-interactive subprocess. You can attach to the TUI, type follow-up messages, detach, reattach, and resume persisted Codex conversations normally.
+Despite the repository name, this is not `codex exec` and it does not turn
+Codex into a non-interactive subprocess. You can attach to the TUI, type
+follow-up messages, detach, reattach, and resume persisted Codex conversations.
 
-The runtime is one self-contained Python script with no third-party Python dependencies.
+The project is intentionally small and self-contained:
+
+- `codex_auto_run.py`: the launcher and approval watcher.
+- `test_codex_auto_run.py`: unit tests for detection, argument handling, and
+  daemon lifecycle behavior.
+- `LOCAL_SETUP.txt`: optional `runx` Bash setup.
+- `README.md`: this document.
 
 ## Requirements
 
-- Linux. The watcher uses `fcntl` and `/proc` for locking and process identity checks.
+- Linux. The watcher uses `fcntl`, `/proc`, and `tmux`.
 - Python 3.10 or newer.
 - `tmux` available on `PATH`.
-- The Codex CLI installed, authenticated, and available as `codex` on `PATH` (or supplied with `--codex-binary`).
+- Codex CLI installed, authenticated, and available as `codex` on `PATH`, or
+  supplied with `--codex-binary`.
+
+The watcher recognizes text rendered by the Codex TUI. If a future Codex
+release changes approval wording or layout, detector updates may be required.
+
+## Current Approval Policy
 
-The current implementation and tests were validated with Codex CLI 0.142.3. The watcher recognizes text rendered by the Codex TUI, so a future Codex release that changes approval wording or layout may require detector updates.
+By default, Codex still starts with `on-request` approvals and the
+`workspace-write` sandbox. The watcher then confirms recognized overlays after
+the screen is stable for multiple polls.
 
-## Important safety warning
+The current default is broad auto-approval. It confirms the currently selected
+option when that option is not an obvious negative or cancel choice.
 
-By default, Codex still starts with `on-request` approvals and the `workspace-write` sandbox. However, the watcher automatically confirms recognized approval and selection overlays for:
+Automatically confirmed by default:
 
-- shell commands;
-- file edits;
-- permission requests; and
-- network access requests;
-- MCP/app/tool calls;
+- shell command approvals;
+- file edit approvals;
+- permission approvals;
+- network access approvals;
+- MCP/app/tool approvals;
 - directory trust prompts;
-- full-access, hook, plugin, and ordinary multi-choice prompts.
+- full-access prompts;
+- hook/plugin prompts;
+- ordinary multi-choice prompts such as `Questions 1/1`;
+- persistent approval rows such as "don't ask again", session-wide approvals,
+  or future host approvals, if that row is currently selected.
 
-This removes the human review normally provided by an approval prompt. A mistaken or prompt-injected Codex action may delete files, run untrusted commands, disclose accessible data over the network, request broader permissions, choose an unintended default answer, or act through connected apps. The watcher is a convenience mechanism, **not a security boundary**. Use it only in a workspace whose contents and consequences you understand, keep important work under version control, and prefer a disposable or externally isolated environment for risky tasks.
+The watcher will not confirm an option whose label starts with an obvious
+negative/cancel prefix such as `No`, `Cancel`, `Deny`, `Reject`, `Quit`,
+`Do not`, or `Don't`.
 
-The watcher confirms the currently selected option if it is not an obvious negative or cancel choice. This includes persistent choices such as "don't ask again", session-wide approvals, or future host approvals if that row is selected.
+This removes the human review normally provided by an approval prompt. A
+mistaken or prompt-injected Codex action may delete files, run untrusted
+commands, disclose accessible data over the network, request broader
+permissions, choose an unintended default answer, or act through connected apps.
+Use this only in an environment where those side effects are acceptable.
 
-`--no-approve-mcp` disables automatic app or MCP approval. `--no-auto-trust-directory` disables automatic directory trust. `--bypass` is substantially more dangerous: it passes Codex's `--dangerously-bypass-approvals-and-sandbox` option and should only be used inside an environment that is already isolated outside Codex.
+Useful opt-out switches:
+
+```bash
+./codex_auto_run.py --no-approve-mcp ...
+./codex_auto_run.py --no-auto-trust-directory ...
+```
 
-## Installation
+`--bypass` is more dangerous: it passes Codex's
+`--dangerously-bypass-approvals-and-sandbox` option and should only be used
+inside an externally isolated container or VM.
+
+## Install Or Migrate
+
+Clone the repository on the target machine:
 
 ```bash
 git clone https://huggingface.co/yitongl/codex_exec
 cd codex_exec
 chmod +x codex_auto_run.py
+PYTHONDONTWRITEBYTECODE=1 python3 -m unittest -v test_codex_auto_run.py
+```
+
+Run directly from the clone:
+
+```bash
+./codex_auto_run.py -C ~/code/my_project -p "Inspect the project and run tests."
 ```
 
-## Migrate to another machine
+## Optional `runx` Command
+
+`LOCAL_SETUP.txt` provides a Bash function named `runx`. It derives a tmux
+session prefix from the current directory, so different projects get separate
+watcher state and logs.
 
-Copy or clone the repository on the target machine, then install the optional
-`runx` shell function:
+The default `runx` setup expects the launcher at `$HOME/codex_auto_run.py`.
+Install it like this:
 
 ```bash
-git clone https://huggingface.co/yitongl/codex_exec
-cd codex_exec
-chmod +x codex_auto_run.py
-cp LOCAL_SETUP.txt ~/.bash_aliases
+git clone https://huggingface.co/yitongl/codex_exec ~/codex_exec
+cp ~/codex_exec/codex_auto_run.py ~/codex_auto_run.py
+chmod +x ~/codex_auto_run.py
+cp ~/codex_exec/LOCAL_SETUP.txt ~/.bash_aliases
 source ~/.bashrc
-PYTHONDONTWRITEBYTECODE=1 python3 -m unittest -v test_codex_auto_run.py
 ```
 
-`runx` expects `codex_auto_run.py` to live at `$HOME/codex_auto_run.py`. If you
-keep the clone in another directory, either copy/symlink the script there or
-adjust the path in `LOCAL_SETUP.txt`.
+Then use it from any project directory:
+
+```bash
+cd ~/code/my_project
+runx -p "Implement the requested change and verify it."
+```
+
+If you want to keep the script somewhere else, edit the path in
+`LOCAL_SETUP.txt` before copying it to `~/.bash_aliases`.
 
-## Start a new session
+## Start A Session
 
 ```bash
 ./codex_auto_run.py \
@@ -75,51 +131,47 @@ adjust the path in `LOCAL_SETUP.txt`.
   -p "Implement the requested change, run the tests, and summarize the result."
 ```
 
-The launcher creates a uniquely named `tmux` session and normally attaches to it immediately. The printed startup information includes the exact command needed to reattach.
+The launcher creates a uniquely named `tmux` session and normally attaches to
+it immediately. Startup output includes:
 
-Use a UTF-8 prompt file when the task is long:
+- the tmux session name;
+- the Codex binary path;
+- the working directory;
+- the approval log path;
+- the reattach command.
+
+Use a UTF-8 prompt file for long tasks:
 
 ```bash
 ./codex_auto_run.py -C ~/code/my_project --prompt-file task.md
 ```
 
-## Detach and reattach
-
 Start without attaching:
 
 ```bash
-./codex_auto_run.py \
-  --detach \
-  -C ~/code/my_project \
-  -p "Run the full task and verify the result."
+./codex_auto_run.py --detach -C ~/code/my_project -p "Run the full task."
 ```
 
-Then attach with the session name printed by the launcher:
+Reattach later:
 
 ```bash
 tmux attach -t codex-auto-YYYYMMDD-HHMMSS-PID-RANDOM
 ```
 
-Inside `tmux`, press `Ctrl-b d` to detach without stopping Codex. Exiting Codex normally ends the `tmux` session unless `--keep-dead-session` was used. When no managed panes remain, the watcher exits after its idle timeout (120 seconds by default).
+Inside `tmux`, press `Ctrl-b d` to detach without stopping Codex.
 
-## Resume a Codex conversation
+## Resume
 
 Resume the most recent interactive conversation for a working directory:
 
 ```bash
-./codex_auto_run.py \
-  --resume-last \
-  -C ~/code/my_project \
-  -p "Continue the task and rerun the verification."
+./codex_auto_run.py --resume-last -C ~/code/my_project -p "Continue and verify."
 ```
 
 Resume a specific Codex session ID or name:
 
 ```bash
-./codex_auto_run.py \
-  --resume SESSION_ID \
-  -C ~/code/my_project \
-  -p "Continue from the previous result."
+./codex_auto_run.py --resume SESSION_ID -C ~/code/my_project -p "Continue."
 ```
 
 Open Codex's interactive session picker:
@@ -128,11 +180,12 @@ Open Codex's interactive session picker:
 ./codex_auto_run.py --resume -C ~/code/my_project
 ```
 
-The picker form cannot be combined with `-p` or `--prompt-file`; select the conversation first and then type in Codex. Resuming starts a new `tmux` wrapper around a persisted Codex conversation. If the original `tmux` session is still running, simply reattach to that session instead.
+The picker form cannot be combined with `-p` or `--prompt-file`; select the
+conversation first, then type in Codex.
 
-## Pass options to Codex
+## Pass Codex Options
 
-Place Codex-specific global options after `--`:
+Put Codex-specific global options after `--`:
 
 ```bash
 ./codex_auto_run.py \
@@ -143,15 +196,17 @@ Place Codex-specific global options after `--`:
   --model MODEL_NAME
 ```
 
-The wrapper reserves `-p` for the initial or resumed-session follow-up prompt. Use `--codex-profile PROFILE_NAME` for a Codex profile.
-
-No model is hardcoded by this repository. Without `--model`, Codex inherits the model selected by the user's Codex configuration and CLI defaults.
+The wrapper reserves `-p` for the initial or resumed-session follow-up prompt.
+Use `--codex-profile PROFILE_NAME` for Codex's own profile option.
 
-Some Codex options that conflict with wrapper-managed behavior, including Codex's own approval, sandbox, working-directory, full-auto, and bypass flags, are rejected. Use the wrapper's `--sandbox`, `-C`, and `--bypass` options instead.
+Some Codex options conflict with wrapper-managed behavior and are rejected,
+including Codex's own approval, sandbox, working-directory, full-auto, and
+bypass flags. Use the wrapper's `--sandbox`, `-C`, and `--bypass` options
+instead.
 
-## Watcher controls
+## Watcher Status, Logs, And Control
 
-Show the watcher and managed-session status:
+Show status:
 
 ```bash
 ./codex_auto_run.py --status
@@ -169,27 +224,48 @@ Start only the watcher:
 ./codex_auto_run.py --start-daemon
 ```
 
-By default, private watcher state and logs are stored under `~/.runtime/codex-auto/`. Only sessions created and registered by this wrapper are watched.
+Default runtime state and logs are stored under:
+
+```bash
+~/.runtime/<session-prefix>/
+```
+
+The approval log is:
+
+```bash
+~/.runtime/<session-prefix>/approve-debug.log
+```
 
-Run `./codex_auto_run.py --help` for all tuning and safety options.
+For the default direct launcher prefix this is:
 
-## Optional shell aliases
+```bash
+~/.runtime/codex-auto/approve-debug.log
+```
+
+For `runx`, the prefix is based on the current directory and ends in `-x`.
+For example, running from `$HOME` uses:
+
+```bash
+~/.runtime/home-x/approve-debug.log
+```
 
-[`LOCAL_SETUP.txt`](LOCAL_SETUP.txt) contains the current `runx`/`rund` Bash
-functions, project-relative tmux naming rules, usage examples, and the local
-`codex-autorun` skill location. The `rund` function expects a separate
-`~/claude_auto_run.py`, which is not included in this repository.
+Log events include `daemon_start`, `launcher_ready`, `pending`, `approve`,
+`approve_failed`, `clear_active`, `daemon_exit`, and `daemon_stop`.
 
 ## Tests
 
-The unit tests exercise approval-screen detection, argument validation, resume command construction, binary probing, `tmux` command construction, and daemon lifecycle safeguards without starting a real Codex session:
+Run the unit tests:
 
 ```bash
 PYTHONDONTWRITEBYTECODE=1 python3 -m unittest -v test_codex_auto_run.py
 ```
 
-A passing unit-test suite cannot guarantee compatibility with a future Codex TUI. Before relying on unattended operation after a Codex upgrade, observe a real low-risk session and verify that approvals are detected as intended.
+The tests do not start a real Codex session. They cover approval-screen
+detection, broad default approval behavior, opt-out switches, argument
+validation, resume command construction, binary probing, tmux command
+construction, and daemon lifecycle safeguards.
 
-## Project status
+## Project Status
 
-This project is independent and unofficial. It is not an OpenAI product and is not endorsed or supported by OpenAI.
+This project is independent and unofficial. It is not an OpenAI product and is
+not endorsed or supported by OpenAI.