Keychain 3.0.0 beta2

[danielrobbins]

Second public beta of Keychain 3.x, collecting all changes made after the
3.0.0_beta1 tag.

This release transforms the multi-terminal experience and strengthens GPG key
handling. The headline feature is a coordinated unlock protocol that eliminates
the frustrating "could not acquire lock" errors when multiple shells start
simultaneously -- a common occurrence when Visual Studio Code reconnects to
WSL and restores several terminals at once.

Highlights:

• Coordinated multi-terminal initialization (solves issue Error: could not acquire lock in 3.0.0_beta1 #214). Keychain
  now uses an elegant coordination protocol instead of the classic lock-timeout
  race. When multiple terminals detect missing SSH keys:

  • All terminals display: Press Enter to initialize keys
  • Pressing Enter in any terminal runs ssh-add in that terminal
  • Other terminals wait automatically and are notified when initialization completes
  • Waiting terminals print Keys initialized by another terminal. and configure
    their environment without prompting

  This eliminates the could not acquire lock errors that plagued earlier
  versions. The technical implementation uses a short-lived state lock for
  metadata updates, a dedicated activation lock to elect the loader, and FIFO
  endpoints for instant kernel-level notification (no polling). A takeover
  mechanism allows any waiting terminal to cancel a stuck ssh-add by typing
  takeover, ensuring you're never blocked by a hidden or inaccessible prompt.
  Internal coordination is quiet -- no more Waiting N seconds for lock...
  messages during interactive key loading.

• Improved startup and key-loading output.

  • Multi-key ssh-add prompts render as compact lists instead of long inline
    messages
  • Common stale pidfile/socket cases (especially in WSL restart scenarios) are
    folded into the Starting ssh-agent... context instead of producing
    separate noisy notes
  • Empty gpg-agent wipe diagnostics no longer render awkward (output: )
    text; non-actionable no-agent details are debug output
  • Successful remote initialization is reported as Keys initialized by another terminal.

• Reliable GPG warm-up with explicit verification. The gpge:KEYID and
  gpga:KEYID extended key syntax now perform a complete encrypt-then-decrypt
  verification cycle instead of relying on signing warm-up side effects. A tiny
  temporary payload is encrypted to the requested key and immediately decrypted
  through gpg-agent. If this verification cannot be completed, add fails
  rather than reporting success. This is significantly more reliable across
  different GnuPG versions and key configurations, where signing warm-up may
  not populate the decryption passphrase cache. The legacy gpgk:KEYID alias
  remains equivalent to gpgs:KEYID (signing warm-up only).

• Enhanced documentation. The embedded man page now includes comprehensive
  coverage of the coordination model (keychain man topic:coordination),
  updated guidance for --lockwait and --no-lock options, and clearer
  explanations of GPG warm-up guarantees. New design documents and a formal
  UX acceptance checklist support manual multi-terminal testing.

• Focused test coverage. New tests validate the coordination state file,
  waiter FIFO registration, activation lock handoff, takeover/cancel mechanics,
  and GPG end-to-end warm-up for both signing and encryption/decryption paths.
  Test infrastructure improvements ensure the checkout's source code is tested
  rather than any installed version, and CI coverage now includes macOS GPG
  validation.

Beta notes:

• The coordinated unlock flow applies to SSH key loading only. GPG keys use
  explicit warm-up paths (gpgs:, gpge:, gpga:) and do not participate
  in multi-terminal coordination.
• Terminal prompt erasing is best-effort: used on ANSI-capable terminals,
  falling back to ordinary line output when stderr is redirected, TERM=dumb,
  or the prompt would wrap.

---

This discussion was created from the release Keychain 3.0.0 beta2.

[pjv]

Hi Daniel,

From reading the readme and the release notes for the two betas for 3.0 and assuming that the python 3.9+ requirement is met, I think that a basic upgrade from 2.9.8 to 3.0+ would be:

1. replace the existing 2.9.8 executable with the new 3.0+ executable
2. construct a suitable ~/.keychainrc to replace existing environment variable configs

Is there anything else required?

Thank you.

[runelan]

Is there a way to generate a full-fledged default config to ~/.keychainrc? The man subcommand is really useful, but the explanation for the structure is rather confusing and I can't seem to get my head around how I am supposed to define defaults for our users.

Also, just as a sidenote, the application itself does not seem to agree with the example config specified in the readme, as it returns the following:

 ▲ Warning: Ignoring unknown section [keychain] in .keychainrc
 ▲ Warning: Ignoring unknown section [agent.ssh] in .keychainrc

[danielrobbins]

Hey @pjv and @runelan -- to upgrade to the new 3.0+ executable, just replace the old one with the new one. There is no need to construct a suitable ~/.keychainrc as this was a 3.x addition so it did not exist in 2.x and is not required.

@runelan I agree, the docs for the .keychainrc are not complete right now, and it's something I know I have to work on. I am actually working on having keychain automatically generate better help for this, and I know that completing the man page, particularly in regards to .keychainrc, is a TODO item prior to 3.0.0.

@runelan that looks like a bug to me, so I'll look into it (feel free to file an issue for this if you'd like, will tackle it either way.)