Desktop app: custom agents from .github/agents missing in fresh worktree sessions — config discovery runs before the deferred checkout populates the tree and agents are never re-scanned

[TwoPatient]

Summary

In the desktop app, a new worktree session frequently ends up with only the 7 built-in task agent types (explore, task, general-purpose, rubber-duck, code-review, research, security-review). The repo's custom agents in .github/agents/*.agent.md are missing for the life of the session, even though glob/ls in the same session see the files.

Root cause is a race between two things:

1. App: the worktree is created with deferred_checkout=true (returns in ~30 ms with an empty tree) and session.create (enable_config_discovery=true) is issued 7–600 ms later, while the file populate takes 3–5 s.
2. CLI: custom agents are discovered **exactly once, during session.create**, and never re-scanned. If .github/agents/ isn't on disk at that instant, the session never gets them.

The app's post-attach "extensibility live-session refresh" reconciles plugins / mcp / extensions / skills — there is no agents dimension — which is why skills and project extensions survive the deferred checkout but custom agents don't.

Environment

• GitHub Copilot desktop app 1.1.23 (commit d1a29ed), macOS arm64, bundling CLI 1.0.87-0
• CLI-only repro also reproduces on 1.0.83-5 and 1.0.84-5 (cached binaries from earlier app versions) — the one-shot discovery is long-standing; the deferred checkout has been on since app 1.1.14
• Repo: private Azure DevOps repo with 25 agents in .github/agents/

App timeline (from ~/.copilot/logs/github-app.<pid>.log)

Session that lost the race (task enum = built-ins only):

10:10:53.540  github_app_git::worktree        create worktree completed ... existing_branch=false sparse=false deferred_checkout=true elapsed_ms=31
10:10:53.566  github_app::session::core        creating session session_id="7085…" ... enable_config_discovery=true
10:10:57.101  workspace::handlers::init        deferred worktree checkout complete ... populate_ms=3540
10:11:24.329  github_app::session::core        CLI session created ... create_session_rpc_ms=30762 enable_config_discovery=true

Session that happened to win it (tool-created; session.create started ~0.9 s into the populate, and .github/ is checked out first alphabetically) got all 25 custom agents. Same app, same repo, same CLI — the outcome depends on milliseconds.

Extensibility refresh (only runs for resumed sessions, and has no agents field):

extensibility live-session refresh completed session_id=… plugins_stale=false mcp_stale=false extensions_stale=true skills_stale=true extensions_reconciliation_needed=true … target_session_skills=0 duration_ms=46

Deterministic CLI-only repro (no app involved)

# empty worktree, populated 3 s after the session starts
git worktree add --no-checkout /tmp/wt-empty -b probe origin/dev
cd /tmp/wt-empty
( sleep 3; git reset -q --hard ) &
copilot -s -p 'Step 1: run bash `sleep 20; ls .github/agents | wc -l`. Step 2: print verbatim, as a JSON array, every value in the enum of the agent_type parameter of your task tool. Step 3: run glob `.github/agents/*.agent.md` and report the count.' --allow-tool shell --allow-tool glob

Result (1.0.87-0, also 1.0.83-5 and 1.0.84-5):

Step 1: 25
Step 2: ["explore","task","general-purpose","rubber-duck","code-review","research","security-review"]
Step 3: 25 matches

Control — same worktree, already populated, fresh session → 32 values (7 built-ins + 25 custom).
copilot --resume <the broken session> in the populated worktree → 32 values. Resume re-discovers; nothing else does.

Impact

Any workflow that dispatches task agent_type: <custom> fails in these sessions with Unknown agent_type: <name> (first seen here 2026-09-14 on app 1.1.20, again today), often 20–30 minutes into a run. Users read this as "custom agents randomly don't load".

Workarounds

• Close and reopen (resume) the session — or restart the app — before running anything that needs custom agents.
• Branch-type sessions (existing checkout) are unaffected.

Suggested fixes

• CLI: re-scan .github/agents/ at prompt time (or watch the directory) — the same class of fix 1.0.85 shipped for skills ("skills no longer missing when a skills load races the directory registration").
• App: await deferred worktree checkout complete before session.create on kickoff; and/or add an agents dimension to the extensibility live-session refresh and run it after populate for fresh sessions.

Related but separate (same machine, fixed in 1.1.23): #4905. App and CLI process logs for the sessions above are available on request.

[TwoPatient]

Workaround + extra data point for maintainers

session.agent.reload (SDK: session.rpc.agent.reload()) does re-run discovery from disk and the task tool's agent_type enum picks the result up from the next turn (verified with the bundled SDK 1.0.87-0: create session in an empty worktree → populate → agent.reload() → first prompt sees all custom agents). It does not take effect within an already-running turn — a reload issued from an onUserPromptSubmitted hook is too late for that same turn, the tool schema is already built.

So a tiny user-scope extension (~/.copilot/extensions/agent-rescan/extension.mjs) fully heals the race with no user action: on join it polls <cwd>/.github/agents until the deferred checkout has finished writing it, compares against session.rpc.agent.list(), and calls session.rpc.agent.reload() if anything is missing. In the app-like flow (create at +0.5 s, populate at +7 s) it reloads within ~0.5 s of the populate and the first prompt has the full enum. User scope matters: .github/extensions is itself missing at create time in the raced sessions.

For the app side, the same call is presumably what reload_session_agents in the app backend already wraps — invoking it once after deferred worktree checkout complete would fix this at the source.

One more observation: re-creating an empty worktree at a path that a populated session had previously used did not reproduce (full enum despite an empty tree at create), while a never-used path reproduced every time. Looks like discovered agents are cached per working directory somewhere; app worktree paths are always new, so that cache never helps them.