docs: document --session-state-dir flag and AWF_SESSION_STATE_DIR env var (#1600)

Add the --session-state-dir CLI flag and AWF_SESSION_STATE_DIR environment
variable to the documentation, introduced in #1593.

- docs/usage.md: add --session-state-dir to the CLI options list (after
  --proxy-logs-dir), and expand the Agent Session State description to
  mention the flag's timeout-safe, predictable-path behaviour useful for
  GitHub Actions artifact uploads
- docs/environment.md: add AWF_SESSION_STATE_DIR to the internal variables
  table and update the note to clarify it is user-configurable

Co-authored-by: Copilot <copilot@github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: 3 people

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
 

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)