fix: make doctor, deploy and printed commands match what runs

[abrichr]

This branch fixes 13 launcher problems found in a review of what openadapt prints and checks. In each case a check said [OK] or "passed" when it hadn't checked, a printed command failed when pasted, or the docs described an action as safer than it is. Each fix has a regression test that fails on origin/main (60938ae) and passes here.

Fixes

Problem	Change	Regression test	Ref
The README called openadapt flow replay bundle --url ... a "permissive local rehearsal". Replay performs every recorded action against that app, including saves that can't be undone, and doesn't ask first.	The README says replay writes to the app at --url, isn't a dry run, doesn't certify the bundle, and belongs on a test or staging copy. The example URLs use a staging placeholder.	tests/test_readme_replay_warning.py	B011
PyPI keeps a release's description forever. The next wheel would have frozen the README's generated lifecycle block, which states an admission, onto PyPI, where it could outlive a revocation.	A hatchling metadata hook (hatch_build.py) builds the package description from the README with that block replaced by a link to the live signed record. scripts/verify_release_artifacts.py refuses a wheel or sdist whose description states a lifecycle state. The GitHub README doesn't change.	tests/test_pypi_description.py, tests/test_release_artifacts.py::test_release_artifacts_reject_a_frozen_lifecycle_description	B007
The quickstart's "See a fail-safe halt" command replayed the tutorial bundle with --drift modal. That bundle doesn't match plain MockMed, so it halted at step_000 on the login screen with or without drift.	The hint prints demo-record, compile, and replay --drift modal for a separate demo on plain MockMed. That replay stops at step_010 when the screen changes.	tests/test_cli_quickstart_polish.py::test_drift_hint_replays_a_bundle_recorded_on_plain_mockmed	B008
openadapt doctor --backend with macos, windows, linux, or citrix printed [OK] and exited 0 on a base install, where the modules those backends import are missing.	doctor and deploy look up the modules each Flow backend imports (find_spec, nothing is imported). A missing module prints [MISSING] with the install command. A host that can't open the surface prints [UNSUPPORTED]. Both fail the check.	tests/test_cli_smoke.py::test_doctor_native_backend_*, ::test_deploy_native_backend_*	B009
Flow 1.33 and 1.34 look up four X11 libraries in the wrong case and refuse Chromium on Linux. The launcher accepted Flow >=1.29.0, so pip install --upgrade openadapt kept 1.34.	Every openadapt-flow requirement, the range that doctor and deploy report, and the platform manifest's copy of the pins start at 1.35.0. uv.lock is refreshed.	tests/test_flow_floor.py	B012
openadapt --help and the quickstart printed openadapt-agent serve .... After uv tool install openadapt or pipx, only openadapt is on PATH, so that command failed with exit 127.	A new openadapt agent command passes every argument to openadapt-agent and returns its exit code. It writes nothing to stdout first, so an MCP client can launch it. Help, quickstart, and the README use it.	tests/test_agent_command.py	B042
Step 3 of the help's Manual Demo Lifecycle was lint --strict, which exits 1 on the demo bundle, so a set -e script stopped there.	Step 3 is openadapt flow lint bundle. A note says --strict exits 1 on the demo.	tests/test_help_demo_lifecycle.py (the end-to-end test runs with OPENADAPT_E2E=1)	B006
openadapt replay suggested deploy. openadapt quickstart --brek-it printed Flow's 43-verb usage and no hint.	A Flow verb typed without flow fails with "Did you mean 'openadapt flow replay'?". Quickstart checks each forwarded long option against Flow's tutorial parser and suggests the closest name. Abbreviations are refused, because an abbreviation Flow would expand could change what runs.	tests/test_cli_dead_ends.py	B013
doctor listed PyTorch, ANTHROPIC_API_KEY, and OPENAI_API_KEY as missing on every base install. Compiled workflows make no model calls.	Without a research extra, doctor prints "Model access: not required." With one, the same checks appear under "Research extras" and name the command that needs each item.	tests/test_doctor_research_checks.py	B014
openadapt version printed five research packages as "not installed". capture stop was advertised, though it can't stop a capture. Two module usage lines didn't parse.	version lists the product packages and shows research packages only when installed. capture stop is hidden from help and still exits 1 with the Ctrl+C note. The usage lines are fixed and parsed by a test.	tests/test_cli_leftovers.py	B015
The README and docs/LEGACY_FREEZE.md offered pip install openadapt==0.46.0, which fails because openai-whisper imports pkg_resources. The freeze doc said to run poetry install on main, which has no Poetry project.	The freeze doc gives a recipe that upgrades pip and caps setuptools below 81 with --build-constraint, and clones the v0.46.0 tag. The runs are in docs/legacy-install-evidence.md.	tests/test_legacy_install_docs.py	B017
Printed commands broke in cmd and PowerShell (curl ... | sh, single-quoted specs), in zsh (unquoted openadapt[ml]), or when the output path had a space.	Windows gets uv's PowerShell installer. Package specs are double-quoted. Paths in quickstart hints are quoted for the host's shell.	tests/test_cli_shell_hints.py	B019
deploy --secret-ref env:FOO printed [OK] with FOO unset, and the preflight printed "Preflight passed" right after a [SETUP] line that says readiness isn't checked.	An env: reference is [OK] only when the variable is set and non-empty; otherwise it's [MISSING] and the preflight fails. The value is never printed. A keychain: reference is [SETUP]. Any [SETUP] item turns the last line into "Preflight incomplete", with a count.	tests/test_deploy_preflight_readiness.py	B021

Not fixed here

• Already fixed on main, waiting for a release: the base dependency on openadapt-agent (B002; PyPI's 1.16.0 doesn't include it, main's wheel does) and the README lifecycle block naming Flow 1.35.1 (B004; the scheduled check passes again, but README Production lifecycle source has drifted #1123 is still open).
• In openadapt-flow: its README still says "permissive rehearsal path", certify --policy permissive prints "certified safe", openadapt flow replya prints openadapt-flow usage, and lint --strict still prints Next command: openadapt-flow certify ... through the launcher, which rewrites only the tutorial's output.
• doctor and deploy still print python -m pip ..., which is the wrong interpreter under uv tool install.
• examples/capture_train_eval.py still prints openadapt train --capture and openadapt eval view.
• docs/LEGACY_FREEZE.md keeps unrelated stale statements, such as "Python 3.12+" for the new packages. The legacy recipe was run on macOS only.
• deploy exits 0 when only [SETUP] items remain, because the native backends always leave the target check to Flow. The last line says "Preflight incomplete" in that case.

How it was tested

• Each new or changed test file was copied onto origin/main in a separate worktree. Every fix has tests that fail there on an assertion about the old behavior and pass here. Control tests (forwarding real flags, Click's own suggestions, a fully checked web host) pass on both.
• Full suite: 454 passed, 7 skipped on Python 3.12 and on 3.10. The skips are the openadapt-ml seam tests, the opt-in browser test, and a CI-only sibling-install check. ruff check and ruff format --check pass on openadapt/.
• uv build --wheel --sdist (uv 0.11.29, as in the release workflow) passes verify_release_artifacts.py, and a wheel rebuilt from the sdist is byte-identical. A wheel built from origin/main is refused by the new check. uv lock --check and validate_platform_manifest.py --offline pass.
• On macOS (Apple silicon), with real Chromium and MockMed:
  • The help's five lifecycle commands ran end to end (OPENADAPT_E2E=1); on main they stop at lint --strict.
  • Quickstart ran from a directory whose path has a space. Its printed lint line and the three drift commands were pasted into sh and ran. The drift replay stopped at step_010; the same bundle without drift ended COMPLETED_UNVERIFIED. The old hint's command halted at step_000.
  • openadapt agent serve --bundles <bundle> answered an MCP initialize and tools/list on stdout.
  • doctor --backend macos reported [MISSING] with python -m pip install "openadapt[macos]", and --backend linux reported [UNSUPPORTED]. deploy --secret-ref env:FOO with FOO unset failed.
• Legacy install on Python 3.11 with pip 26.2.1: the plain dry run exits 1 on pkg_resources, and the constrained dry run exits 0.
• The CI install set (pip install -e ".[dev]" plus the research packages) resolves with Flow 1.35.1 on Python 3.10 and 3.12, for Linux and macOS. In a local environment with those packages, the first CI run's failure reproduced: every test passed and pytest then exited 139. Doctor tests that stub importlib.util.find_spec made doctor import torch under the stub, which left torch half-loaded. tests/conftest.py now imports torch once before any stub; three full runs then exited 0.
• gitleaks found no leaks in the branch commits.

Before merging

• The "Validate platform manifest against published artifacts" check fails here and on main for the same reason: openadapt-privacy 1.1.2 is newer than the manifest's 1.1.1 (platform-manifest.json has drifted from the published releases #1110). The offline manifest check passes.
• Review the uv.lock change: openadapt-flow 1.29.0 to 1.35.1, openadapt-types 0.17.1 added, opencv-python-headless removed.
• These changes alter what scripts see. doctor --backend <native> exits 1 on a base install. deploy fails on an unset env: reference. Quickstart refuses unknown or abbreviated tutorial flags. deploy prints "Preflight incomplete" instead of "Preflight passed" while [SETUP] items remain.
• PyPI users get B002, B007, B012, and B042 only after a launcher release through the reviewed release workflow. The bundle-free openadapt agent serve --allow-run also needs openadapt-agent 2.0.2.

🤖 Generated with Claude Code