Stale Forwarded SSH Agent

Detect stale forwarded SSH agents in VS Code container sessions after the host sleeps and wakes. This targets the common forwarded-agent failure mode, including with the 1Password SSH agent, where ssh-add still lists keys but real signing or authentication fails with errors like communication with agent failed.

What it does

• Activates only in container remotes such as Dev Containers and attached containers.
• Runs a conservative health check inside the remote container where the forwarded agent is actually used.
• Uses a real signing-path smoke test by default with ssh-keygen -Y sign.
• Optionally uses ssh -T git@github.com as a network-dependent probe.
• Checks on startup, on window focus regain, after long timer gaps that suggest sleep or wake, and on a configurable interval.
• Shows a warning with Reload Window, Ignore Once, and Disable Checks when the agent appears stale.

By default the extension does not auto-reload. It prompts and lets the user decide.

Why ssh-add -l alone is not enough

ssh-add -l and ssh-add -L only ask the agent to enumerate identities. In the stale forwarded-agent failure mode, listing keys can still succeed while the real signing path fails later during ssh, git, or ssh-keygen -Y sign. This extension treats key listing as preflight only and checks the signing path to reduce false negatives.

Setup

Your container needs access to the host's forwarded SSH agent socket. A minimal devcontainer.json looks like this:

{
  "mounts": [
    "source=${localEnv:SSH_AUTH_SOCK},target=/tmp/ssh-agent.sock,type=bind,consistency=cached"
  ],
  "remoteEnv": {
    "SSH_AUTH_SOCK": "/tmp/ssh-agent.sock"
  }
}

The included .devcontainer/devcontainer.json in this repo uses the same approach.

Settings

• staleAgent.enabled - turn checks on or off.
• staleAgent.intervalMinutes - set the background interval in minutes.
• staleAgent.checkOnFocus - check again when the VS Code window regains focus.
• staleAgent.probeMode - choose sign or github.
• staleAgent.signProbeUseExitCodeOnly - in sign mode, treat any nonzero ssh-keygen -Y sign exit code as stale, even without a known stale-agent signature.
• staleAgent.autoReload - automatically reload once per stale episode.

Behavior and limitations

• The default sign probe avoids network dependence and works well in devcontainers.
• The sign probe needs a usable identity in the forwarded agent.
• staleAgent.signProbeUseExitCodeOnly only affects the final ssh-keygen -Y sign step; ssh-add -L remains preflight so missing tools, empty agents, and similar setup issues stay conservative.
• To avoid extra touch prompts, the extension skips the signing smoke test when only security-key backed identities are available.
• The optional github probe depends on outbound network access and GitHub SSH behavior.
• Some agent failures may surface as non-specific SSH errors; the extension intentionally only warns on known stale-agent signatures or strong healthy-to-broken transitions.
• If you enable staleAgent.signProbeUseExitCodeOnly, the sign probe becomes more aggressive and may warn on non-stale signing failures.

Development

For local development, packaging, and contributor workflow details, see CONTRIBUTING.md. The GitHub packaging workflow runs automatically for stable semver tags and can also be dispatched manually for an existing stable semver tag.