[Tracking] Managed remote Runtime Host onboarding and lifecycle

[M4n5ter]

English

Problem

Runtime Host already provides the remote execution, authentication, reconnect, multi-Host Desktop, Host-scoped Settings, and remote Project foundations tracked by #2522. Desktop can now prepare a supported Linux computer through interactive SSH, install an exact Maka CLI release, pair the Client, verify the connection, and continue to remote Project selection.

The remaining work is the managed lifecycle after onboarding. Service inspection and maintenance are being added to Desktop, while credential maintenance, safe version switching, update policy, and the macOS service backend still require dedicated contracts and product surfaces.

Desired outcome

Desktop should provide one coherent per-computer lifecycle: guided onboarding, service health and repair, credential maintenance, safe updates, and explicit removal or uninstall actions with clear ownership boundaries.

The same management contract must remain usable from CLI and TUI, and must leave a clean path for a future macOS service backend.

Stable boundaries

• SSH is the management plane for installation, service control, updates, credentials, and diagnostics. Runtime Host remains the only Session and execution data plane.
• The OS service manager owns the persistent process. Runtime Host never overwrites or updates its own executable.
• Deployed versions are always exact. Channel names only resolve a desired exact version.
• Update policy defaults to manual. Automatic updates must wait for a safe maintenance point and respect storage compatibility.
• Credential secrets are delivered once and stored only by the Client credential store. Management UI exposes metadata, rotation, and revocation rather than secrets.
• Removing a Desktop profile, uninstalling the remote service, and deleting the State Root are three separate operations.
• The default SSH path uses the system OpenSSH client and a loopback Runtime Host listener. Maka does not modify the user's SSH config or implement a second SSH stack.

Delivery plan

• Platform-neutral service lifecycle contract and Linux systemd user backend: install, status, start, stop, restart, readiness verification, and clean uninstall while retaining the State Root (feat(cli): manage Linux Runtime Host services #3205)
• Add an idempotent remote bootstrap, exact-release deployment, and pairing contract with structured progress and stable errors (Add an idempotent managed Runtime Host setup contract #3229, feat(cli): set up managed remote Runtime Hosts #3230)
• Add the Desktop Add Computer wizard over interactive system SSH (feat(desktop): add managed remote Runtime Host onboarding over SSH #3233, feat(desktop): add managed remote Runtime Host onboarding #3236)
• Add per-Host Desktop service status, bounded logs, start/restart, repair, and clean uninstall (feat(desktop): manage installed remote Runtime Host services #3281, feat(desktop): manage remote runtime host services #3282)
• Add per-Host credential metadata, rotation, and revocation (feat(desktop): manage access credentials for remote Runtime Hosts #3418)
• Add safe side-by-side version switching, health checks, failure recovery, and manual updates
• Add manual | fixed | latest | next update policy and bounded automatic reconciliation
• Add a macOS LaunchAgent backend that reuses the same lifecycle and management contract

Each slice should remain independently useful. Update automation must not block initial onboarding, and Desktop UI must not duplicate service or credential authority.

Definition of done

• A user can prepare a supported Linux remote computer from Desktop without manually copying a port, Root ID, or credential
• Password, host-key, passphrase, and MFA prompts can be completed through the existing bounded interactive SSH surface
• Setup is retryable and does not leave duplicate services, profiles, or credentials
• Desktop saves a Profile only after the service and authenticated Runtime Host connection have been verified
• Users can distinguish removing the computer from Desktop, uninstalling Maka-managed service files, and explicitly deleting all Host data
• Manual and automatic updates never silently cross an unsupported storage compatibility boundary
• CLI and TUI can use the same machine-readable management contract without adopting Desktop's multi-Host UI
• Linux and macOS backends share lifecycle semantics rather than separate product state machines

Non-goals

• A federated Runtime Host or cross-Host Session migration
• A custom SSH implementation, silent sudo, or automatic installation of Node.js
• Opening the Runtime Host listener to the public network by default
• Treating uninstall as permission to delete the State Root
• A Windows persistent-service backend without a concrete product requirement
• A cloud pairing or rendezvous service before local SSH onboarding proves insufficient

简体中文

问题

#2522 已经完成 Runtime Host 的远程执行、认证、重连、Desktop Multi-Host、Host-scoped Settings 与远程 Project 等基础能力。Desktop 现在也可以通过交互式 SSH 准备受支持的 Linux 电脑，安装精确的 Maka CLI release、配对 Client、验证连接，并继续选择远程 Project。

剩余工作是 onboarding 之后的托管生命周期。Desktop 正在增加服务检查与维护能力；credential 维护、安全版本切换、更新策略和 macOS service backend 仍需要独立的契约与产品界面。

期望结果

Desktop 应提供一套连贯的 per-computer 生命周期：引导式 onboarding、服务健康与修复、credential 维护、安全更新，以及所有权边界清晰的移除或卸载操作。

同一套管理契约仍须可供 CLI 与 TUI 使用，并为未来的 macOS service backend 保留干净边界。

稳定边界

• SSH 是安装、服务控制、更新、credential 和诊断的管理面；Runtime Host 仍是唯一的 Session 与 execution 数据面
• 持久进程由 OS service manager 管理；Runtime Host 不能覆盖或更新自己的可执行文件
• 实际部署永远使用精确版本；频道名称只用于解析期望的精确版本
• 更新策略默认是手动；自动更新必须等待安全维护点，并遵守 storage compatibility
• Credential secret 只交付一次，并且只存入 Client credential store；管理界面只展示 metadata、轮换和撤销
• 从 Desktop 移除 Profile、卸载远程 service、删除 State Root 是三个独立操作
• 默认 SSH 路径使用系统 OpenSSH 和远端 loopback Runtime Host listener；Maka 不修改用户 SSH config，也不实现第二套 SSH

交付计划

• 平台无关的 service lifecycle contract 与 Linux systemd user backend，包括 install、status、start、stop、restart、readiness 验证，以及保留 State Root 的干净卸载（feat(cli): manage Linux Runtime Host services #3205）
• 增加幂等的远程 bootstrap、精确 release deployment 与配对契约，并提供结构化进度和稳定错误（Add an idempotent managed Runtime Host setup contract #3229、feat(cli): set up managed remote Runtime Hosts #3230）
• 通过交互式 system SSH 增加 Desktop 添加电脑 向导（feat(desktop): add managed remote Runtime Host onboarding over SSH #3233、feat(desktop): add managed remote Runtime Host onboarding #3236）
• 增加 per-Host Desktop 服务状态、有界日志、启动/重启、修复与干净卸载（feat(desktop): manage installed remote Runtime Host services #3281、feat(desktop): manage remote runtime host services #3282）
• 增加 per-Host credential metadata、轮换与撤销（feat(desktop): manage access credentials for remote Runtime Hosts #3418）
• 增加安全的 side-by-side 版本切换、健康检查、失败恢复与手动更新
• 增加 manual | fixed | latest | next 更新策略及有界的自动 reconcile
• 增加复用相同 lifecycle 与管理契约的 macOS LaunchAgent backend

每个 slice 都应能够独立提供价值。自动更新不能阻塞首次 onboarding，Desktop UI 也不能复制 service 或 credential authority。

完成标准

• 用户可以直接在 Desktop 中准备受支持的 Linux 远程电脑，无需手工复制 port、Root ID 或 credential
• Password、host key、passphrase 与 MFA prompt 可以通过现有的有界交互式 SSH 界面完成
• Setup 可以安全重试，不会留下重复 service、Profile 或 credential
• 只有 service 和经过认证的 Runtime Host 连接都验证成功后，Desktop 才保存 Profile
• 用户能够明确区分从 Desktop 移除电脑、卸载 Maka 托管的 service 文件，以及显式删除全部 Host 数据
• 手动或自动更新都不能静默跨越不受支持的 storage compatibility 边界
• CLI 与 TUI 可以使用同一套机器可读管理契约，而无需复制 Desktop Multi-Host UI
• Linux 与 macOS backend 共享 lifecycle 语义，不形成两套产品状态机

非目标

• Federated Runtime Host 或跨 Host Session migration
• 自研 SSH、静默执行 sudo，或自动安装 Node.js
• 默认把 Runtime Host listener 开放到公网
• 把卸载视为删除 State Root 的授权
• 在没有明确产品需求前实现 Windows persistent-service backend
• 在本地 SSH onboarding 被证明不足前引入云端 pairing 或 rendezvous service