Add the 1Password CLI as an Optional Managed Host Tool - #4161

Summary

Makes the 1Password CLI (op) an optional managed host tool on both installers.

A repository that reads its secrets from a 1Password vault needs op on its hosts. Its own host-tools.json cannot declare the Linux source, since an overlay's install metadata names only a package, never an apt repository or a signing key. So the hub manages it.

• spec/host-tools.json gains an op entry: required: false, no floor, probe op --version, with source and remedy for Linux, macOS, and Windows. Its pattern reads a line holding only the version, which is what the probe prints, and tolerates a pre-release suffix, since an unreadable version fails the gate even for an optional tool.
• host-setup/linux/install-tools.sh gains op_* functions modeled on gh_install. The keyring at downloads.1password.com/linux/keys/1password.asc is proved against the repository's own InRelease rather than pinned. The sources file is deb822 1password.sources naming a keyring under /etc/apt/keyrings. The vendor's one-line 1password.list and its /usr/share/keyrings keyring are removed once the new source is written, so apt never sees two Signed-By values for one repository and a key that fails its proof leaves the vendor's source working. A new register_apt_source helper holds that order for gh, node, docker, and op, so gh and docker now remove their own predecessors after the replacement too. The repository carries amd64, arm64, and armhf, and any other architecture is a named skip.
• A manual download at /usr/local/bin/op shadows the package's /usr/bin/op. It is removed after a prompt, and only beside an installed package, so a failed fetch or install leaves the working copy. An unowned op anywhere else can be a wrapper or a version manager's shim, so it is reported and left in place.
• Ripgrep, PowerShell, op, and tool_unshadow's shadow loop share new path_is_unowned, unowned_command_path, and remove_unowned_command helpers. Ripgrep and the shadow loop previously read a failed dpkg-query as "unowned" and offered to remove the file. The shared strict test stops the run instead, whatever errexit state it runs in, and a failed rm warns once rather than looping.
• install_keyring, write_sources, and microsoft_feed run with errexit off under apply_tool, and the step after each removes a working source or copy. A failed write in any of them now ends the run, found by Copilot on the first head.
• The one hard-coded optional tool on Linux becomes an OPTIONAL_TOOLS list holding powershell and op.
• host-setup/windows/install-tools.ps1 gains an AgileBits.1Password.CLI record and a tool-level $OPTIONAL_TOOLS list with the Linux semantics. An optional tool is left out of the default selection unless -Optional is given or the tool is named, and -List always shows it, marked (optional tool).
• unmanaged is defined by the absent sources file rather than by a distro install, which was false for op, in the README, a comment, and the apply log line.
• The usage examples on both platforms no longer say a bare run reports or upgrades every tool.
• Docs: docs/host-setup.md, host-setup/linux/README.md, host-setup/windows/README.md (Differences table). No new cspell.json words, since CI spell-checks only README.md and HISTORY.md.

Measured while building it

• The 1password-cli package ships only /usr/bin/op. Its install script adds an onepassword-cli group and makes the binary set-group-ID. It writes no apt source or keyring.
• The 1Password desktop app package writes /etc/apt/sources.list.d/1password.sources on each of its installs, after copying its key to /usr/share/keyrings. No package owns that key as a file. This change uses the same sources file name on purpose. A different name would leave apt with two sources for one repository disagreeing on Signed-By, which apt refuses. On a host carrying both, the desktop app's upgrade rewrites the file and the next run here writes it back, and apt reads one consistent source either way.
• The vendor's debsig step is skipped because the signed apt repository is the trust path, as for every other repository here. The package's own debsig signature measured as SHA-512, so this change does not claim debsig rejects it.

Awaiting maintainer

bootstrap.sh --dev and the Windows dev stand-up run the installers with --optional / -Optional, so a dev stand-up now also installs op. On Linux that adds 1Password's apt source and keyring, the onepassword-cli group, and a set-group-ID binary. On Windows, -Optional previously selected only the extra .NET SDK lines. This follows the requested powershell semantics, and whether a dev stand-up should carry op is the maintainer's call.

Local review

Every push carried a recorded local pass, three before the opening push. Their findings are fixed above, apart from these declines:

• remove_stale of /usr/share/keyrings/1password-archive-keyring.gpg could break the desktop app's source. Declined: that package's install script recreates the key before writing its sources file, and no package owns the key.

Findings carried past an edit budget, with their outcomes

Each push carried recorded passes, and where a push's two edit rounds were spent, its remaining findings were fixed in the next push. All are closed on the head, whose final pass recorded no findings.

• op_install removed /usr/local/bin/op under --install beside an existing package: fixed in 0545b7b.
• The report note claimed no upstream version with the vendor's 1password.list in place: fixed in 0545b7b.
• The "still shadowed, --upgrade removes it" line fired for op: fixed in 0545b7b.
• The Windows README misdescribed the optional-tool test: fixed in 0545b7b.
• unmanaged wording and the desktop-app write-back claim: fixed in 3628aca, c971f77, 7f1abb4, and 9aac122.
• A failed keyring or sources write let the predecessor source go (Copilot): fixed in 99548df, and the Microsoft feed sibling in cebc62d.
• The floor test duplicated the remedy check: fixed in 99548df.
• Usage examples, comment scope, and the InRelease docs claim: fixed in cebc62d and 263eeb0.
• The per-site registration order and the run-ending cases in the docs: fixed in 2c36667.

Pre-existing findings, not filed

• host-setup/linux/install-tools.sh powershell_install, pre-existing correctness: powershell_non_apt_paths runs inside a process substitution, so a failed dpkg-query there ends only that subshell and the install carries on with a partial path list. Not filed from this seat, since this pull request is its only write. It is reported to the dispatching session to file.

Verification

• spec/validate.py: OK.
• python3 -m unittest test_install_tools test_host_gate test_bootstrap from tests/, on the tree merged with current develop: OK. New cases drive the Linux functions with stubs and the Windows selection and list through a pwsh harness over the script's own registry. Each new guard was deleted in turn and a test failed each time.
• scripts/docker_lint.py (shellcheck, shfmt, markdownlint, PSScriptAnalyzer, editorconfig-checker): clean. ruff and mypy: clean.
• Read-only on a Debian 13 host: install-tools.sh --list marks op optional, and --report op reads it unavailable with the repository-not-configured note.
• Not verified natively: a real Linux install, its idempotent repeat, and the host gate after it, since each changes the host and waits on the maintainer. No Windows or macOS run.

🤖 Generated with Claude Code