diff --git a/docs/environment.md b/docs/environment.md
index aa9ccf90..8b939c8a 100644
--- a/docs/environment.md
+++ b/docs/environment.md
@@ -102,9 +102,10 @@ The following environment variables are set internally by the firewall and used
 | `AWF_DNS_SERVERS` | Comma-separated list of trusted DNS servers | `8.8.8.8,8.8.4.4` |
 | `AWF_CHROOT_ENABLED` | Whether chroot mode is enabled | `true` |
 | `AWF_HOST_PATH` | Host PATH passed to chroot environment | `/usr/local/bin:/usr/bin` |
+| `AWF_SESSION_STATE_DIR` | Directory for Copilot CLI session state output (equivalent to `--session-state-dir`) | *(unset)* |
 | `NO_PROXY` | Domains bypassing Squid (host access mode) | `localhost,host.docker.internal` |
 
-**Note:** These are set automatically based on CLI options and should not be overridden manually.
+**Note:** Most of these are set automatically based on CLI options and should not be overridden manually. `AWF_SESSION_STATE_DIR` is an exception — it is the environment-variable equivalent of `--session-state-dir` and can be set by users to configure a predictable session-state output path.
 
 ## GitHub Actions `setup-*` Tool Availability
 
diff --git a/docs/usage.md b/docs/usage.md
index 4f17525c..28d20903 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -53,6 +53,9 @@ Options:
                                allowed to these servers (default: 8.8.8.8,8.8.4.4)
   --proxy-logs-dir <path>      Directory to save Squid proxy logs to (writes access.log directly to
                                this directory)
+  --session-state-dir <path>   Directory to save Copilot CLI session state (events.jsonl, session
+                               data). Writes directly during execution (timeout-safe, predictable
+                               path). Also configurable via AWF_SESSION_STATE_DIR env var.
   --enable-host-access         Enable access to host services via host.docker.internal. Security
                                warning: When combined with --allow-domains host.docker.internal,
                                containers can access ANY service on the host machine. (default: false)
@@ -847,9 +850,12 @@ sudo awf \
 
 **Agent Session State:**
 - Contains structured conversation data written by Copilot CLI (e.g., `events.jsonl`)
-- Location: `/tmp/awf-agent-session-state-<timestamp>/`
+- Default location: `/tmp/awf-agent-session-state-<timestamp>/`
 - View with: `cat /tmp/awf-agent-session-state-<timestamp>/events.jsonl`
 - Useful for triage dashboards, benchmarking, and debugging Copilot CLI runs
+- Use `--session-state-dir <path>` (or `AWF_SESSION_STATE_DIR`) to write session state to a
+  predictable path during execution — ideal for artifact upload in GitHub Actions where the
+  runner may time out before cleanup completes
 
 **Squid Logs:**
 - Contains all HTTP/HTTPS traffic (allowed and denied)