Document local HYPERLOOM_RUNTIME_DIR for Codex on NFS

[BaoYunkai]

Summary

• Add a troubleshooting entry for Codex stalls and TraceLens roofline timeouts when Codex SQLite state lives on network storage (for example NFS v3 with local_lock=none).
• Document that operators can keep USER_DATA_PATH on shared storage while pointing HYPERLOOM_RUNTIME_DIR at node-local fast disk.
• Cross-link from the environment-variables and operations guides.

Test plan

• Docs build/render (no code changes)
• Review links to the new troubleshooting anchor

[ZhengGong-amd]

Reconsider this as a description of the one parent rule that already exists. Do not add a placement mechanism.

_codex_home_parent is the only parent selection: HYPERLOOM_RUNTIME_DIR when set, otherwise the first safe writable root, otherwise the run directory. A parent inside a source checkout, or one that cannot be created, raises CodexSessionUnavailableError. No new environment variable. No branch on NFS or Weka by name.

The new troubleshooting text does not match that rule. With HYPERLOOM_RUNTIME_DIR unset, the parent is the writable root, not $USER_DATA_PATH/runtime (that path is only the installer default). _cleanup_codex_home removes .hyperloom-codex-home-* when the client closes, so listing it after the stage cannot verify success. The environment-variables row in this diff already states both facts.

If the entry stays, describe only that rule, and state that the directory is gone after close. The subprocess specialist's workspace/.codex is a second CODEX_HOME policy and does not read HYPERLOOM_RUNTIME_DIR: either say this entry does not cover it, or place that home through the same function. That second policy is the mechanism to remove.

[BaoYunkai]

Thanks for the review — pushed a doc-only follow-up that aligns with the existing _codex_home_parent rule:

• Troubleshooting now documents the single selection order (HYPERLOOM_RUNTIME_DIR → first safe writable root → run cwd), installer export vs in-code fallback, and _cleanup_codex_home removing .hyperloom-codex-home-* after the SDK client closes.
• Verification no longer suggests listing Codex home directories after the stage; it points at df on the configured parent and at sqlite warnings only while a turn is still open.
• Added an explicit scope note: subprocess specialist Codex uses <workspace>/.codex and does not read HYPERLOOM_RUNTIME_DIR. Unifying that second policy would be a separate code change; this PR stays documentation-only.

Let me know if you want the specialist path called out elsewhere or a follow-up issue for consolidating CODEX_HOME placement.

[ZhengGong-amd]

One remaining mismatch. The symptom lists “GEAK on Codex” as a caller of _codex_home_parent. It is not. Callers are TraceLens roofline (run_codex_turn) and orchestrator Codex turns. Forge-fusion / GEAK Codex uses kernelforge's own home (~/.cache/kernelforge/codex_home) and does not read HYPERLOOM_RUNTIME_DIR. Drop that example. The selection order, cleanup-on-close, and the specialist workspace/.codex exclusion are fine.

[BaoYunkai]

Removed GEAK from the symptom/caller list; scope now explicitly excludes KernelForge (~/.cache/kernelforge/codex_home) and specialist workspace/.codex. Callers limited to TraceLens roofline (run_codex_turn) and orchestrator Codex turns.

[ZhengGong-amd]

validated, approved