From 7b549c1eb6090a7f574d5f0333e0d5b54e4b92d5 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Thu, 20 Aug 2026 16:42:48 +0000
Subject: [PATCH] docs: update for Copilot Auto API versions and Cloud
 Hypervisor network readiness

- Document Copilot Auto API version auto-injection (/auto, /models/session, /models/session/intent)
- Clarify that x-github-api-version headers are only for GitHub Copilot targets
- Add lifecycle detail: guest network readiness check before connectivity probe
- Add troubleshooting section for network readiness timeout with diagnostic guidance

Relates to:
- c80f528: feat: support Copilot Auto API versions (#7554)
- d79988b: Fix Cloud Hypervisor guest network readiness race (#7555)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 docs/auth-matrix.md                 | 16 ++++++++++++++++
 docs/cloud-hypervisor-foundation.md | 15 +++++++++++++--
 2 files changed, 29 insertions(+), 2 deletions(-)

diff --git a/docs/auth-matrix.md b/docs/auth-matrix.md
index 0f4c2da66..42fc4251b 100644
--- a/docs/auth-matrix.md
+++ b/docs/auth-matrix.md
@@ -184,6 +184,22 @@ When the resolved upstream host is a Copilot host (`githubcopilot.com` or a `*.g
 
 Non-empty inbound values are preserved; empty values and case-variant duplicates are replaced so exactly one instance of each header reaches CAPI. Harnesses that do not send a stable `X-Interaction-Id` themselves (aider, Pi, …) therefore still get prompt-cache hits, and a harness that owns its own session identity can override the value simply by sending the header. There is no AWF-specific override env var for `X-Interaction-Id`: outside GitHub Actions the sidecar mints one UUID per process. Neither header is injected on non-Copilot hosts, so BYOK targets (Azure OpenAI, OpenRouter, …) and the OpenAI/Anthropic/Gemini providers are unaffected.
 
+### Auto API Version Injection (`*.githubcopilot.com` only)
+
+For GitHub Copilot catalog targets, the sidecar auto-selects appropriate `x-github-api-version` headers for certain endpoints to ensure API compatibility:
+
+| Endpoint | HTTP Method | Auto-Selected Version | Notes |
+|----------|-------------|----------------------|-------|
+| `/auto` | POST | `2026-08-01` | Copilot Auto inference endpoint |
+| `/models/session` | POST | `2025-07-16` | Model session initialization |
+| `/models/session/intent` | POST | `2025-07-16` | Model session intent parsing |
+
+**Key behaviors:**
+- Auto-injection applies only to GitHub Copilot targets (`*.githubcopilot.com`); BYOK and non-Copilot targets are unaffected.
+- If the request already includes an `x-github-api-version` header (case-insensitive), it is preserved and auto-injection is skipped.
+- POST requests to other endpoints do not receive auto-injected versions; callers must specify versions for other endpoints if needed.
+- Non-POST requests never receive auto-injected versions.
+
 ### `/models` Endpoint (Special Case)
 
 The `/models` endpoint prefers `COPILOT_GITHUB_TOKEN` (GitHub OAuth) over BYOK keys when both are configured, because model listing is a GitHub platform feature. However, when no GitHub token is available (typical for direct-BYOK/custom targets), `/models` will use the BYOK credential.
diff --git a/docs/cloud-hypervisor-foundation.md b/docs/cloud-hypervisor-foundation.md
index c54ec2a7e..5ac96c06d 100644
--- a/docs/cloud-hypervisor-foundation.md
+++ b/docs/cloud-hypervisor-foundation.md
@@ -75,8 +75,9 @@ AWF performs these steps for each run:
 6. Create a bounded cgroup v2 leaf and launch Cloud Hypervisor as the invoking
    non-root identity.
 7. Start one sandboxed `virtiofsd` process for each validated export.
-8. Create and boot the VM, connect to the guest supervisor over VSOCK, and
-   probe infrastructure connectivity.
+8. Create and boot the VM, connect to the guest supervisor over VSOCK, verify
+   guest network readiness (loopback interface UP), and probe infrastructure
+   connectivity.
 9. Execute the agent command and propagate its exit code. Timeouts return
    `124`.
 10. Sync and unmount guest filesystems, stop the VM and VMM, reap `virtiofsd`,
@@ -241,6 +242,16 @@ Preserved namespaces and processes continue consuming host resources. Remove
 them only after collecting the diagnostics you need.
 :::
 
+### Guest network readiness timeout
+
+If the guest network readiness check times out (error: `guest-network-not-ready`), the guest's loopback interface did not become UP before the timeout expired. Possible causes:
+
+1. **Guest image mismatch** — The guest supervisor contract requires loopback to be brought up before opening the VSOCK listener. A mismatched or incompatible guest image may violate this ordering.
+2. **Host system issue** — Delays in kernel or KVM initialization may cause the readiness check to timeout. Retry the run; transient delays are sometimes recoverable.
+3. **Supervisor crash** — The guest supervisor may have crashed before initializing networking. Check preserved guest logs under `<workDir>/microvm-images/<runId>/` for supervisor output.
+
+Verify the guest image digest and supervisor version match the build expectation, then retry.
+
 ### Guest cannot reach Squid or the API proxy
 
 Check the namespace nftables rules, TAP state, and Squid/API proxy health. The