feat(harness-desktop): install and launch isolated agent CLIs

[ynadge]

Primary change type

• Feature

Problem and motivation

Managed npm CLIs can require an interpreter and entry script, but the adapters only accepted a binary. Desktop also needs an isolated installer with a deadline before it can safely adopt newer agent versions.

Summary and scope

Resolve Claude/Codex package entry points and launch them through the bundled runtime when needed. Preserve interpreter arguments and environment across version checks, new sessions, resume, and Claude headless tasks. Add exact-version installation with process-tree timeout/cancellation and Windows process-identity checks.

This is the runtime foundation for #843. Its packaged smoke check exercises a managed JavaScript CLI through a real PTY.

Related work

First of two stacked PRs. #843 adds startup version checks, verified selection, and fallback using these primitives. Diff: 572 additions + 16 deletions = 588 lines.

Validation

pnpm build — passed
pnpm typecheck — passed
pnpm lint — passed (existing warnings)
pnpm test — existing agent-core permission test fails in this VM
pnpm --filter @sapiom/harness --filter @sapiom/harness-desktop test — 3,330 harness and 179 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 unchanged permission test fails because this VM can list directories with mode 0111; the previous combined PR passed Node 20/22 CI. Temporary build/test files use a memory filesystem due to limited disk space. The subsequent macOS validation below exercised the real runtime and updater. Full GUI startup and Windows execution remain unverified.

Real runtime validation — 2026-09-06

Used installed Sapiom 0.4.4's bundled Electron 33.4.11 / Node 20.18.3 and npm inside app.asar on macOS to execute these actual installer/resolver/adapter primitives with #843's coordinator. Installed real @openai/codex@0.153.4 into an isolated temporary prefix, verified its version, passed adapter doctor, and launched its authenticated model-list interface through the managed runtime and production adapter arguments. The account-visible catalog included GPT-6 Astra and GPT-5.6 models that were absent from fresh runs of the original 0.143.0. Repeating the coordinator reused the same installation. Packaged Linux runtime also installed real Codex 0.100.0 → 0.153.4 successfully.

This adds real-package macOS/Linux evidence to the existing stub-based tests. It did not exercise a full GUI/PTY session, inference, a real Claude update, or Windows. All Mac test files and credential copies were temporary and removed; the original installed CLI remained unchanged. See #843 for the controlled old/new/old reproduction and its limits.

Tests and documentation

Retained installer failure/timeout/cancellation tests, Windows PID-reuse cases, adapter launch/resume tests, and the packaged managed-agent smoke check. Added adapter option documentation and a changeset.

Compatibility and release impact

• Breaking or externally visible changes: additive adapter options and createCodexAdapter export; existing callers retain their defaults.
• Changeset: patch entries for harness and desktop.

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.