bug: intermittent `--headless` timeout on Windows cold start causes silent generation failure

Summary

Note: written and created by GHCP.

On Windows, agentrc init and agentrc instructions have two intermittent failure modes that both stem from the Copilot CLI headless server not being fully ready. Both resolve on retry, making the tool unreliable on first use.

Issue 1: --headless probe timeout (cold start)

isHeadlessCompatible() uses a 5-second timeout when running copilot --headless --version. On Windows cold starts (first run after boot or long idle), the .bat wrapper → Node.js startup can exceed this, causing agentrc to throw "does not support '--headless'" even though the CLI is perfectly valid.

The npx path already has a 30-second timeout for this reason, but the direct CLI and AGENTRC_COPILOT_CLI_PATH paths do not.

Issue 2: SDK session tools fail even after successful session start

Even when the --headless probe passes and the SDK session starts successfully, the file tools (glob, view, grep) intermittently return permission errors. The LLM then produces an error message like:

"All file access tools are blocked... This appears to be blocked by your organization's content exclusion policy or a file system permission issue."

This error text gets written to copilot-instructions.md as if it were valid generated content. No CLI-level error is surfaced to the user.

Debug output from a successful run (for contrast):

[agentrc:copilot] probe VS Code globalStorage: ...copilot.bat => compatible
[agentrc:copilot] selected compatible candidate from VS Code globalStorage
[agentrc:copilot] creating SDK client with cliPath=...copilot.bat useStdio=false
[agentrc:copilot] .bat/.cmd shim detected; using external server mode directly
[agentrc:copilot] starting external CLI server: cmd /c ...copilot.bat --headless --log-level debug
  ✔ Updated .github\copilot-instructions.md

On the failed runs, the same debug output appears (session starts, no error thrown) but the LLM's tools are denied. The only difference is retry timing.

Repro

# Windows 11, PowerShell 7
# Copilot CLI 1.0.49 (VS Code globalStorage)
# Repo: subdirectory of a git repo (level1-brownfield/ inside agentrc-demo-repos/)

cd C:\repos\agentrc-demo-repos\level1-brownfield
npx github:microsoft/agentrc instructions --repo . --force
# → Completes with exit code 0, but copilot-instructions.md contains error text

# Immediate retry:
npx github:microsoft/agentrc instructions --repo . --force
# → Works correctly, generates proper instructions

Root cause hypothesis

The Copilot CLI headless server starts asynchronously. When agentrc sends sendAndWait() immediately after session creation, the tool subsystem may not be fully initialized. The trySetAutopilot() call is best-effort and doesn't gate on tool readiness.

A contributing factor may be that the workingDirectory is a subdirectory (level1-brownfield/) of the actual git root (agentrc-demo-repos/). The CLI's tool sandboxing might have a race between resolving the git root and making tools available.

UX impact

1. Silent corruption: Error content is written to copilot-instructions.md with exit code 0. Users may not notice until they read the file.
2. Confusing error: The --headless error implies wrong CLI version. The tool access error (seen only in the generated file) implies org policy issues.
3. Non-deterministic: Works on retry, making diagnosis difficult.

Suggested fixes

1. Increase timeout for .bat/.cmd paths on Windows (5s → 15s) in isHeadlessCompatible()
2. Add retry with backoff in the headless compatibility check
3. Validate generated content before writing — if output contains no markdown headings, or matches known error patterns (e.g., "permission error", "file access tools are blocked"), warn the user instead of writing
4. Distinguish timeout from incompatibility in error messages (the catch {} currently swallows both)
5. Wait for tool readiness after session creation before sending the first prompt — or retry the session if the LLM reports tool failures

Environment

• Windows 11
• PowerShell 7
• Copilot CLI 1.0.49 (VS Code globalStorage)
• AGENTRC_COPILOT_CLI_PATH = %APPDATA%\Code\User\globalStorage\github.copilot-chat\copilotCli\copilot.bat
• agentrc via npx github:microsoft/agentrc (latest main)
• VS Code Copilot Chat extension installed and authenticated
• Repo structure: subdirectory of git root (level1-brownfield/ inside agentrc-demo-repos/)

Start by tracing isHeadlessCompatible(), including the direct CLI, AGENTRC_COPILOT_CLI_PATH, and npx paths, then follow session creation through trySetAutopilot() and sendAndWait(). Reproduce the Windows cold-start behavior and compare timeout, tool-readiness, and generated-content handling; done means failures are surfaced distinctly and invalid error text is not silently written as instructions.