WSL: setup docs missing kernel-upgrade prerequisite, gnome-keyring unlock nuance, and v0.7.1 `builtin` profile-resolution failure

[NoRiceToday]

Duplicate check

• I have searched the existing issues

Context / Summary

A TNG colleague tried to set up omac on a fresh WSL2 Ubuntu 26.04 distro following the documented path (docs/INSTALLATION.md + omac doctor hints) and fell through three separate under-/undocumented gaps before omac start would run. Related open issues: #240 (WSL install fails), #178 (keychain IsUnavailable WSL classification gap).

Desired state: a new TNG colleague on Windows following the official onboarding guidelines (Confluence IIT/Windows Setup Walkthrough → Setting up KeeassXC, which names KeePassXC as the TNG go-to password manager on Windows) should be able to set up and use omac on WSL without leaving the docs. In particular, since omac on WSL needs a Secret Service provider and TNG's Windows go-to is KeePassXC, the docs should either steer WSL users toward the native Windows KeePassXC (Secret Share / DBus bridge to WSL) or give a one-shot gnome-keyring recipe that actually works — today neither path is documented and the gnome-keyring path the docs do show is wrong.

The three gaps below each alone blocks omac start on WSL.

Problem / What

1. Stale WSL kernel → advisory-only network filtering, undocumented in the setup path.

omac serve opencode prints:

omac sandbox: kernel-enforced network filtering needs Landlock ABI >= 4 (Linux >= 6.7); this kernel has ABI 3.
Either upgrade the kernel or set network.enforcement to "env-only" in the sandbox profile (WARNING: advisory-only filtering)

This comes from internal/sandboxrun/landlock_linux.go:51 and internal/sandboxrun/backend_linux.go:166. A default WSL2 install ships an older Microsoft kernel (the colleague had ABI 3); wsl --update (to WSL 2.7.8, kernel 6.18.33.1-microsoft-standard-WSL2) fixes it. Neither docs/INSTALLATION.md nor omac doctor tells a WSL user to run wsl --update first — the only hint is the runtime warning, which surfaces at omac serve time, not at omac doctor time where a WSL user would look.

2. gnome-keyring-daemon --unlock --components=secrets with an empty password does NOT unlock the default collection.

docs/INSTALLATION.md:152-160 and the omac doctor hint (internal/cli/keychain_hint.go:16) tell the WSL user to run:

sudo apt install gnome-keyring dbus-x11 && eval "$(dbus-launch --sh-syntax)" && gnome-keyring-daemon --unlock --components=secrets

Following this verbatim, omac doctor then reports:

[warn] keychain backend: failed to unlock correct collection '/org/freedesktop/secrets/aliases/default'

That string is emitted by go-keyring itself (github.com/zalando/go-keyring@v0.2.8/secret_service/secret_service.go:126), not by omac. The unlock only succeeds when a non-empty password is piped in (the WSL user password); with echo -n "" the default alias collection is never created/unlocked. The colleague eventually found this by guessing echo -n "<wsl password>" | gnome-keyring-daemon --unlock --components=secrets, which then popped a GUI "unlock keyring" dialog asking for the password a second time. None of this is in the docs, and it's the exact "daemon running, but the login collection was never created" failure mode that #178 notes is missing from keychain.IsUnavailable (internal/keychain/keychain.go:127-152) — so the read path hard-errors instead of degrading. The colleague also tried, and gave up on, making omac use the native Windows KeePassXC instead of gnome-keyring inside WSL — which would align with TNG's Windows go-to but is undocumented.

3. omac start fails with sandbox profile "builtin" could not be resolved: sandbox profile "builtin" not found (expected ~/.config/omac/sandbox-profiles/builtin.json) on v0.7.1.

omac start: omac: sandbox profile "builtin" could not be resolved: sandbox profile "builtin" not found
(expected /home/mech/.config/omac/sandbox-profiles/builtin.json); GET /sandbox/denied disabled

This is the #173 launcher-name/policy-ref conflation: at v0.7.1 wireFacadeSandbox (internal/cli/facade_wiring.go at the v0.7.1 tag) resolved the LAUNCHER profile name "builtin" as if it were a POLICY ref — it isn't; the policy ref is "default" (internal/config/launcher.go:111, internal/cli/sandboxplan.go:39-41). It is already fixed on main by #219 (2e92d84, "resolve the sandbox plan once so /sandbox/denied answers") — wireFacadeSandbox now takes the resolved sandboxPlan and warns on plan.PolicyErr instead. But v0.7.1 is the latest released version (omac update installs it), so any WSL user on the current release still hits this. The warning is non-fatal to the child (omac sandbox run re-resolves the policy itself), but it reads as a hard failure and the colleague stops.

Suggested fix / Ask

• Docs: add a WSL-specific prereq to docs/INSTALLATION.md (Prerequisites → WSL note, and the omac doctor WSL hint at internal/cli/keychain_hint.go:16) telling users to run wsl --update before first run, since the default WSL kernel predates Landlock ABI 4.
• Docs: correct the gnome-keyring unlock command in docs/INSTALLATION.md:152-160 and the omac doctor/keychainUnavailableHint (internal/cli/keychain_hint.go:18) text — echo -n "" does not create the default collection. Document piping the WSL user password (or a dedicated passphrase), and note the second GUI unlock prompt. Cross-link keychain.IsUnavailable doesn't classify the WSL 'Secret Service running but login collection missing' failure mode, so reads hard-error instead of degrading #178 for the IsUnavailable classification gap that makes the failure mode a hard error.
• Docs/research: evaluate whether omac on WSL can use the native Windows KeePassXC (the TNG Windows go-to, per Confluence IIT/Windows Setup Walkthrough → Setting up KeepassXC) via a Secret Service bridge, and document that path as the preferred one for TNG colleagues if viable. Falls back to the corrected gnome-keyring recipe above otherwise.
• Code: consider a WSL-specific omac doctor check that detects the "failed to unlock correct collection '/org/freedesktop/secrets/aliases/default'" signature (from go-keyring secret_service.go:126) and prints an actionable hint (pipe a password to gnome-keyring-daemon --unlock), instead of the bare [warn] keychain backend: failed to unlock correct collection … line. This is the WSL twin of keychain.IsUnavailable doesn't classify the WSL 'Secret Service running but login collection missing' failure mode, so reads hard-error instead of degrading #178's missing IsUnavailable branch.
• Release/backport: confirm fix(cli,sandbox): resolve the sandbox plan once so /sandbox/denied answers #219 (2e92d84) is in the next release so omac start no longer prints the spurious sandbox profile "builtin" could not be resolved warning. (Already on main; this is a release-tracking note, not code work.)

Non-goals

• Adding a WSL/Windows CI runner (keychain.IsUnavailable doesn't classify the WSL 'Secret Service running but login collection missing' failure mode, so reads hard-error instead of degrading #178 already argues against it — the failure modes are reproducible via the error signatures on ubuntu-latest).
• Implementing the age-encrypted file fallback for headless Linux keychain (separate, larger piece — keychain.IsUnavailable doesn't classify the WSL 'Secret Service running but login collection missing' failure mode, so reads hard-error instead of degrading #178 non-goals).
• Auto-creating the login/default collection on the user's behalf (orthogonal; tracked in keychain.IsUnavailable doesn't classify the WSL 'Secret Service running but login collection missing' failure mode, so reads hard-error instead of degrading #178's future-work note).

Evidence / Environment

• omac 0.7.1, Ubuntu 26.04 LTS under WSL2, kernel 6.18.33.x-microsoft-standard-WSL2 (after wsl --update to WSL 2.7.8; was ABI 3 before).
• Scratchpad: <CONFLUENCE: OMAC scratchpad>, <CONFLUENCE: OMAC again>.
• TNG onboarding ref: Confluence IIT/Windows Setup Walkthrough - Consulting Edition → Setting up KeepassXC (names KeePassXC as the go-to on Windows).
• Code refs: internal/sandboxrun/landlock_linux.go:51, internal/sandboxrun/backend_linux.go:166, internal/cli/keychain_hint.go:14-23, docs/INSTALLATION.md:152-160, internal/keychain/keychain.go:127-152, internal/cli/facade_wiring.go (v0.7.1 tag vs HEAD), internal/cli/sandboxplan.go:39-90, internal/config/launcher.go:106-142, go-keyring@v0.2.8/secret_service/secret_service.go:126.
• Related: WSL installation fails #240, keychain.IsUnavailable doesn't classify the WSL 'Secret Service running but login collection missing' failure mode, so reads hard-error instead of degrading #178, Facade sandbox wiring resolves the launcher profile name against the sandbox-policy namespace, disabling GET /sandbox/denied on every default launch #173 (closed by fix(cli,sandbox): resolve the sandbox plan once so /sandbox/denied answers #219).