feat(desktop): configure managed remote project registration roots

[M4n5ter]

English

Problem

Runtime Host can publish up to eight named directory roots for remote project browsing and registration, and Desktop can consume those roots. A Desktop-managed remote Host is installed without an explicit root policy, so it publishes the remote service account Home by default. Desktop only displays the persisted root list and cannot change it.

Users therefore cannot use Desktop to make locations such as a workspace volume, source directory, or mounted data directory available for adding projects. They must leave Desktop and run service-management commands on the remote computer.

The persisted configuration also represents the default as an empty list while the effective Host behavior publishes Home. That makes the observed management state different from the data-plane state and makes an empty list unsafe as an explicit policy.

Desired outcome

Desktop-managed remote Hosts expose one coherent, Host-owned policy for the directories from which remote Clients may browse and register projects.

• The remote managed-service configuration is the only durable authority; Desktop Profiles do not duplicate the policy.
• Desktop reads and applies the policy over the SSH management plane. Runtime Host credentials cannot mutate it through the Session data plane.
• The policy is a complete explicit root set. New installations materialize the remote Home default; an empty set unambiguously disables directory browsing and registration.
• Existing implicit-Home configurations migrate without expanding or silently changing access.
• Configuration uses an explicit idempotent transaction with exact service identity, compare-and-set configuration identity, shared lifecycle locking, active-task refusal, readiness verification, and safe same-deployment rollback.
• Package updates and configuration changes reuse the same retirement/cutover machinery while retaining different rollback rules.
• The managed Host settings UI can add, edit, remove, and apply named remote paths. Remote paths remain opaque to Desktop and are canonicalized and validated on the remote computer.
• Managed onboarding reuses the same policy model and defaults to the remote Home directory.
• Unmanaged SSH, TLS, and plaintext Profiles remain read-only and point operators to Host-side configuration.
• Removing a root prevents future browsing and registration through that root; it does not delete or archive already registered Projects.

Alternatives or workarounds

• Storing roots in each Desktop Profile creates a second authority and cannot coordinate multiple Clients.
• Mutating roots through the Runtime Host data plane gives ordinary Client credentials control over a privileged filesystem-discovery boundary.
• Reusing service install or repair can restart a Host without the active-task retirement contract and gives a configuration change the wrong lifecycle semantics.
• A remote filesystem picker beginning at the filesystem root must disclose the filesystem before the allowlist exists.
• Extending unattended update reconciliation into a generic configuration controller adds a permanent control loop for a low-frequency explicit operation.

Acceptance criteria

• A Desktop-managed remote Host can apply zero to eight unique named project registration roots.
• Desktop and the Runtime Host directory picker report the same effective policy, including the default Home policy.
• Invalid, missing, duplicate, non-directory, or non-canonical remote paths fail before service retirement.
• An unchanged desired policy does not restart the Host.
• A stale configuration edit is rejected rather than overwriting a concurrent CLI, Desktop, or update change.
• Active work is not interrupted without explicit user authorization.
• A failed same-deployment configuration cutover restores the previous configuration and service.
• Configuration and package-update transactions cannot race.
• Reconnection observes a new Host epoch and the exact applied root set.
• Existing registered Projects remain intact when a root is removed.
• Operator schema limits, CLI limits, managed configuration, and Runtime Host enforcement agree on the maximum of eight roots.

Non-goals

• Granting or revoking access to already registered Projects
• Browsing an unrestricted remote filesystem to select a root
• Persisting project-root policy in Desktop Profiles
• Adding a generic continuously running desired-state controller
• Adding a Runtime Host hot-reload mechanism for this policy

AI disclosure: OpenAI Codex drafted this issue under maintainer direction.

简体中文

问题

Runtime Host 可以发布最多八个具名目录根，用于远程浏览目录和注册 Project，Desktop 也已经能够消费这些根目录。Desktop 托管的远端 Host 安装时没有显式根目录策略，因此默认发布远端服务账号的 Home。Desktop 只能显示持久化的根目录列表，不能修改它。

用户因此无法直接在 Desktop 中把 workspace volume、源码目录或挂载的数据目录设为可添加项目的位置，只能离开 Desktop，在远端电脑上执行服务管理命令。

持久化配置还使用空列表表示默认状态，而 Host 的有效行为却是发布 Home。这使管理面观测状态与数据面状态不一致，也使空列表无法安全表达显式策略。

期望结果

Desktop 托管的远端 Host 使用一套连贯、由 Host 持有的目录策略，限定远程 Client 可以从哪些目录浏览并注册 Project。

• 远端 managed-service configuration 是唯一持久 authority；Desktop Profile 不复制这项策略。
• Desktop 通过 SSH management plane 读取和应用策略；Runtime Host credential 不能通过 Session data plane 修改它。
• 策略是完整、显式的 root set。新安装会把远端 Home 默认值物化；空集合明确表示禁用目录浏览和注册。
• 现有隐式 Home 配置完成迁移，不扩大或静默改变访问范围。
• 配置采用显式、幂等的事务，包含 exact service identity、configuration compare-and-set、共享 lifecycle locking、active-task 拒绝、readiness 验证和同一 deployment 的安全回滚。
• Package update 与配置变更复用相同的 retirement/cutover 机制，同时保留不同的回滚规则。
• Managed Host 设置界面可以添加、编辑、移除并应用具名远端路径。远端路径对 Desktop 保持 opaque，由远端电脑完成 canonicalization 和验证。
• Managed onboarding 复用同一个策略模型，并默认使用远端 Home。
• 非托管 SSH、TLS 和 plaintext Profile 保持只读，并引导 operator 在 Host 侧配置。
• 移除 root 只阻止后续通过该 root 浏览和注册，不删除或归档已经注册的 Project。

替代方案或临时做法

• 把 roots 保存到每个 Desktop Profile 会产生第二 authority，也无法协调多个 Client。
• 通过 Runtime Host data plane 修改 roots，会让普通 Client credential 控制高权限的文件系统发现边界。
• 复用 service install 或 repair 可能绕过 active-task retirement contract 重启 Host，也赋予配置变更错误的生命周期语义。
• 从文件系统根开始的远端目录选择器，必须在 allowlist 建立前先暴露文件系统。
• 把无人值守更新 reconciliation 扩张成通用配置 controller，会为低频显式操作引入永久控制循环。

验收条件

• Desktop 托管的远端 Host 可以应用零到八个互不重复的具名项目注册根目录。
• Desktop 与 Runtime Host 目录选择器报告相同的有效策略，包括默认 Home 策略。
• 无效、不存在、重复、非目录或无法 canonicalize 的远端路径在 service retirement 前失败。
• desired policy 未变化时不重启 Host。
• 过期的配置编辑会被拒绝，不会覆盖并发的 CLI、Desktop 或 update 变更。
• 未经用户明确授权，不中断 active work。
• 同一 deployment 的配置切换失败时恢复旧配置和旧服务。
• 配置事务与 package update 不能发生竞态。
• 重连后观测到新的 Host epoch 和精确的已应用 root set。
• 移除 root 后，现有已注册 Project 保持不变。
• Operator schema、CLI、managed configuration 与 Runtime Host enforcement 对八个 root 的上限保持一致。

非目标

• 授予或撤销已经注册 Project 的访问权限
• 为选择 root 而浏览不受限制的远端文件系统
• 在 Desktop Profile 中持久化 project-root policy
• 增加通用的持续 desired-state controller
• 为这项策略增加 Runtime Host hot-reload 机制

AI 披露：此 issue 由 OpenAI Codex 在维护者指导下起草。