fix(harness-desktop): update Claude and Codex on startup

[ynadge]

Primary change type

• Bug fix

Problem and motivation

Studio disables Codex's own update check but previously kept using an older installed CLI across restarts. That can leave users with an outdated model picker. Installed Claude Code had the same update gap.

Summary and scope

Check both installed providers against npm latest before starting sessions. Use #845's isolated installer, verify the executable, then atomically select it. Failed/offline updates retain the working CLI; newer or unrecognized local builds are preserved. Cancel updates when quitting during setup and bound doctor probes.

Progress uses the existing startup screen. Dev/smoke and SAPIOM_DISABLE_AGENT_UPDATES=1 skip update traffic. Provider configuration and history are preserved; model access still depends on the account. Old install directories remain available to running processes.

Related work

Second of two stacked PRs; merge #845 first. This diff is based on its branch and contains only startup update policy/wiring, tests, and documentation: 546 additions + 10 deletions = 556 lines.

Validation

pnpm build — passed
pnpm typecheck — passed
pnpm lint — passed (existing warnings)
pnpm --filter @sapiom/harness --filter @sapiom/harness-desktop test — 3,330 harness and 197 desktop tests passed
pnpm -C packages/harness-desktop exec node scripts/pack.mjs --linux --dir — passed
bash packages/harness-desktop/scripts/smoke.sh — 14 passed, 1 Windows-only check skipped
git diff --check — passed

The workspace pnpm test check during the split hit the same unchanged agent-core permission-test failure documented in #845. This VM can list directories with mode 0111; Node 20/22 CI passed on the original combined change. Temporary build/test files use a memory filesystem. The subsequent macOS validation below exercised the real runtime and updater. Full GUI startup and Windows execution remain unverified.

Real reproduction and update validation — 2026-09-06

Authenticated macOS comparison, using the same ChatGPT account/configuration and separate empty caches:

CLI	Picker-visible catalog
Installed Codex 0.143.0, fresh process	GPT-5.5 and GPT-5.4-mini; no GPT-6 Astra or GPT-5.6 models
Actual npm 0.153.4	GPT-6 Astra and GPT-5.6 Sol/Terra/Luna also available
PR-managed 0.153.4	Same newer models available
Original 0.143.0 repeated afterward, fresh cache	Newer models still absent

The PR's actual coordinator/installer/adapter ran under installed Sapiom 0.4.4's bundled Electron 33.4.11 / Node 20.18.3 and npm. It detected 0.143.0, downloaded and verified real 0.153.4, published the selection, passed adapter doctor, and reused the selection on a second coordinator call (one installation total). Its managed executable and adapter config flags produced the authenticated newer catalog. The original system installation remained 0.143.0. A separate packaged Linux run also installed real Codex 0.100.0 → 0.153.4 and reused it.

This validates a version-dependent picker omission and the production update path. Codex's TUI bootstrap consumes this model/list catalog. It does not establish the exact originally reported incident: that model/error was not supplied. No inference prompt, full GUI startup, real Claude update, or Windows run was tested here. Credentials stayed on the Mac; temporary installations and credential copies were removed. This reproduction was performed after implementation, not before it.

Tests and documentation

Retained all update coverage: both providers, newer/beta/unknown versions, offline reuse, failed/incomplete installs, cancellation, immutable selection, and Windows npm layout. Shortened repetitive comments and the desktop README. A syntax-tree comparison confirmed all six updater functions retain their original implementations after extraction.

Compatibility and release impact

• Breaking or externally visible changes: automatic CLI updates can delay startup, with a 90-second installer deadline per provider plus bounded checks/cleanup. New or resumed processes use the selected version.
• Changeset: desktop patch entry; adapter/runtime release notes are in feat(harness-desktop): install and launch isolated agent CLIs #845.

Security

• No secrets, private data, or unsanitized logs included.
• No suspected vulnerability publicly disclosed; the repository Security Policy applies.

AI assistance

• Codex implemented and split the change, reviewed the diff, and ran the checks above.

Checklist

• Read CONTRIBUTING.md; follows the requested contribution scope.
• Focused change; tests and documentation included.
• Build, typecheck, lint, and tests run; limitations documented.
• Changeset included; all submitted changes reviewed.