Stale path references in nested AGENTS.md files (agentHost sessions tree moved; copilotcli missing ../; protocol.md does not resolve)
- Dominant language
- TypeScript
- Stars
- 193k
- Forks
- 42.4k
- PR merge metrics
- PR metrics pending
Description
## Stale path references in nested `AGENTS.md` files (agentHost, copilotcli)
While auditing agent-instruction files for internal path drift, I found three files under `src/vs/platform/agentHost/` and `extensions/copilot/` whose references no longer resolve in the current tree. These files are read first by every coding agent working in these areas, so dead paths there send agents hunting for files that are not where the doc says.
Verified against the full recursive tree at current `main` (22,757 entries) with git-history checks.
---
### 1. `src/vs/platform/agentHost/AGENTS.md` — sessions tree moved to `src/vs/sessions/`
Lines 154, 287 reference:
- `` `sessions/services/sessions/common/session.ts` ``
- `` `sessions/services/sessions/common/sessionContextKeys.ts` ``
**Neither path exists under `agentHost/`** — and per commit history, `src/vs/platform/agentHost/sessions/` has never existed on main. The files actually live in the top-level sessions tree:
| Referenced (dead under agentHost) | Actual location |
| --- | --- |
| `src/vs/platform/agentHost/sessions/services/sessions/common/session.ts` | `src/vs/sessions/services/sessions/common/session.ts` |
| `src/vs/platform/agentHost/sessions/services/sessions/common/sessionContextKeys.ts` | `src/vs/sessions/services/sessions/common/sessionContextKeys.ts` |
(`src/vs/sessions/` is actively developed — commits within the last few days.)
**Fix:** replace both occurrences with the `src/vs/sessions/...` paths (or `vs/sessions/...` if the doc prefers src-relative shorthand).
### 2. `extensions/copilot/src/extension/chatSessions/copilotcli/AGENTS.md` line 336 — missing `../`
> **VS Code Session commands** (registered via `registerCLIChatCommands` in `vscode-node/copilotCLIChatSessions.ts`)
`copilotcli/vscode-node/` does not exist. The file lives one directory up: `extensions/copilot/src/extension/chatSessions/vscode-node/copilotCLIChatSessions.ts`.
The doc's own convention elsewhere is correct — lines 260 and 363 both use `../vscode-node/...`. Line 336 is the outlier.
**Fix:** `vscode-node/copilotCLIChatSessions.ts` → `../vscode-node/copilotCLIChatSessions.ts`.
### 3. `src/vs/platform/agentHost/common/state/AGENTS.md` lines 63, 79 — `../../../protocol.md` resolves to nothing
Both lines instruct: *Update `../../../protocol.md` version history and any affected AHP docs.* From `common/state/`, that resolves to `src/vs/platform/protocol.md` — which does not exist, has no commit history, and there is **no `protocol.md` anywhere in the tree**.
Related: the auto-generated `state/protocol/version/registry.ts` jsdoc points at `../../docs/specification/versioning.md`, which also does not resolve in-tree. So the question for maintainers: **where does the canonical protocol/version-history doc live now** (separate repo? generated?), and should these pointers be updated or dropped? As written, an agent following the checklist hits a dead path on both protocol-change recipes.
---
### Verification
- All six occurrences grep-checked against the full recursive git tree (`truncated: false`)
- `src/vs/platform/agentHost/sessions` commit history: empty (path never existed on main)
- Replacement paths confirmed present: `src/vs/sessions/services/sessions/common/session.ts`, `.../sessionContextKeys.ts`, `extensions/.../chatSessions/vscode-node/copilotCLIChatSessions.ts`
- No existing issue found for these paths (searched `AGENTS.md`, `agentHost stale`, `protocol.md`, `copilotcli AGENTS`)
Happy to open a PR with the two mechanical fixes (items 1–2); item 3 needs a maintainer call on where the protocol doc belongs.
---
*Context: I audit agent-facing docs for exactly this failure class (stale paths that mislead coding agents). Recent fixes credited in the wild: [cloudflare-docs#32985](https://github.com/cloudflare/cloudflare-docs/pull/32985) (merged, llms.txt hub link generation), [context7#3075](https://github.com/upstash/context7/pull/3075) (maintainer-shipped from my report #3060). I also do this as a paid micro-service for teams that want their agent context files drift-checked — sample: https://deploy-foorge-team.vercel.app/sample-fresh-context-pack.html*
Contributor guide
Assessment
This issue has not been assessed yet.