feat(desktop): install and configure Antigravity ACP

[Sun-GLiang]

Summary

Refs #5103 — PR1.

Add Settings → External Agents for local macOS arm64 users to install the pinned official Antigravity ACP 1.1.1 distribution or choose an existing executable, check the connection, sign in with Google, cancel, and retry.

Managed installation uses the configured proxy, verifies the archive size/SHA-256 and both executable hashes, publishes under the Runtime Host state root, reuses a verified cache, repairs damaged copies only after verifying a replacement, recovers an interrupted directory exchange, and removes abandoned staging. A successful install is checked through ACP before its path is saved through Settings.

The post-install Settings mutation is conditional on the executable still matching the attempt's admission basis, so optimistic revision retries cannot overwrite a newer selection. Browser presentation uses the normal 30-second lease and is renewed only by polling for the same live setup attempt; terminal results, cancellation, presentation, or abandonment release the slot. Attempt/state matching rejects a late URL from an older attempt.

RuntimePolicy schema 4 migrates schemas 2/3. Compatibility epoch remains 144 over main's 142: branch builds already advertised 143 before they contained main's epoch-142 Skill-query refusal contract, so reusing 143 would falsely claim compatibility.

Scope stays limited to PR1 Settings setup. No task execution, session creation/restoration, model catalog, disk/PATH discovery, automatic upgrade, remote Host flow, or additional workspace package is added.

Review resolution

• Fixed damaged/incomplete managed-copy recovery, failed-replacement preservation, crash-left staging cleanup, and missing proxy-credential classification.
• Replaced the fixed six-minute OAuth slot with a polling-renewed 30-second lease.
• Added a semantic compare-and-set guard to the existing Settings mutation for install results.
• Moved acceptance logs and four PR-only screenshots out of the repository; immutable historical links remain below.
• Kept expectedStateHint: a late URL from expired attempt A must not consume attempt B's replacement slot.
• Kept whole-Host drain after cleanup_failed: TERM/KILL have both failed and PR1 has no retained orphan supervisor that can safely own the surviving process.
• Kept the unrelated WorkHub readiness fix isolated in test-only commit 07af97634.

Verification

• Full repository build and typecheck passed.
• Biome lint/format, Desktop and UI Knip, renderer architecture, Astryx inventory, Windows test inventory, and the staged protocol-epoch guard passed.
• Complete Core, Runtime Host, and Desktop compiled test suites passed.
• Focused installer, ACP process, setup coordinator, OAuth presentation, Settings page/IPC, and Runtime Host client regression tests passed.
• New coverage exercises corrupted/missing managed files, failed replacement, interrupted exchange recovery, staging-directory/symlink cleanup, long-lived polling, abandonment, unrelated/late queries, stale URL isolation, and guarded Settings retry.

The controlled review follow-up did not repeat the real Google login or full production download. Historical acceptance remains evidence for the earlier UI/build and is not presented as a new run.

UI evidence

Historical real Google login success

AI use

• No generative tool made a substantive contribution
• Generative tooling made a substantive contribution

Tool(s) and scope: Codex implemented configuration, installation, setup lifecycle, Desktop UI, tests, review follow-up, and verification. Retain the Generated-by: Codex trailers when squashing.

Checklist

• Install the pinned official distribution or choose an existing executable
• Verify, cache, repair, and safely publish managed files
• Check ACP before conditionally saving through Settings
• Keep connection and authentication states separate
• Cover cancellation, timeout, disconnect, cleanup, delayed presentation, and stale results
• Keep PR1 scope boundaries intact
• Pass local builds, checks, and affected/full test suites
• Pass latest-head GitHub CI and receive final human review

[Astro-Han]

Architecture: right seam. Installer, ACP child spawn/teardown, attempt admission and residency all live in Runtime Host (HostExternalAgentSetupCoordinator → withAcpConnection, acquireResidency('external-agent-setup'), beginDrain/close/releaseConnection, terminateProcessTree). The managed copy is a Host-owned directory under the Host state root; Desktop only sees the path through the setup projection and saves it via the existing set_external_agents mutation. Desktop main is limited to IPC, the oauth_presentation gate and the native picker. Proxy transport, RuntimePolicy revisioning, open_external presentation and process-tree termination are all reused, and nothing pre-commits a shape PR2 must fight: no backend/session/model types, and withAcpConnection (spawn → op → kill) can be split into open/close later without touching the coordinator. Solution is sound; the gaps below are all on failure/recovery paths.

P2 — A tampered or corrupted managed copy is unrecoverable from the UI

Reachability ②. installAntigravity treats an existing <state>/external-agents/antigravity/1.1.1 as immutable: packages/runtime-host/src/server/acp/antigravity-install.ts:65-71 rethrows integrity_failed on any mismatch, and antigravity-install.test.ts:90-95 pins it. Once one byte of agy_acp_server.par or the helper changes (disk error, a helper rewriting itself, a half-applied manual edit), both Install and Reinstall return integrity_failed forever; the only recovery is rm -rf on a directory the UI never names. The archive is hash-pinned, so replacing a mismatched copy with a freshly verified one cannot install anything unverified. Fix: when verifyInstallation(destination) fails, remove or rename the directory aside and fall through to the staged install; keep the reuse fast path for the match case. If the copy must stay immutable, add a distinct managed_copy_modified failure whose copy names the directory.

P3 — "Late results cannot replace changed configuration" holds only in the renderer

Reachability ②, narrow window. The Host compares expectedExecutable only at admission (external-agent-setup-coordinator.ts:102-104); the post-install save goes through applyHostPatchWithoutLane → updateRuntimePolicy (runtime-host-settings-ipc-main.ts:384-386), which is optimistic-retry and overwrites the current revision. The only guard is object identity on props.settings in external-agent-settings/page.tsx:188-196. Fine for PR1, but the PR body states it as a Host property. Either soften the claim, or let the install attempt capture the RuntimePolicy revision at admission and commit set_external_agents itself with that expectedRevision.

P3 — cleanup_failed drains the whole Host

Reachability ④, noted for blast radius only. onCleanupFailure calls retainUntilProcessExit() + requestDrain() (execution-composition.ts:1430-1433), so one leaked child from a Settings-page check takes every running session on the Host down. Marking setup unavailable for the process lifetime and logging the pid bounds the damage to the feature that caused it.

WorkHub E2E change

Test-only, not masking a product bug: packages/ui/src/composer.tsx:1267-1273 deliberately ignores Enter while sendPendingRef.current is set, and the click path already auto-waits; workhub-layout.spec.ts:354,372 gives the keyboard path the same wait. Unrelated to Antigravity, so give it its own commit.

Complexity

The six-module move into application/contracts/settings-presentation/ plus shims (~470 lines) is forced by the renderer-architecture check. Two things can go: docs/antigravity-acp-settings.md:49-67 and the login screenshot are PR evidence committed as docs (user docs are PR3 in #5103), and expectedStateHint in runtime-host-oauth-presentation.ts:94 is defensive only since the single-slot expectation already serialises attempts. Existing-program selection saving without validation is per #5103; the Host still validates at spawn (checkedFile), same trust level as shell.executable.

Tests: Host 66 / storage 71 / CLI 7 / Desktop 39 passed; the admission guard, per-file hash verification and the six-minute window each go red with their fix reverted. Compatibility epoch on the head is 144 over main's 142; the PR body's 143/141 is stale.

中文

架构：接缝正确。 安装器、ACP 子进程启动/回收、attempt 准入和 residency 都在 Runtime Host（HostExternalAgentSetupCoordinator → withAcpConnection、acquireResidency('external-agent-setup')、beginDrain/close/releaseConnection、terminateProcessTree）。托管副本是 Host state root 下 Host 自有的目录；Desktop 只通过 setup projection 拿到路径，再经现有 set_external_agents mutation 保存。Desktop main 只做 IPC、oauth_presentation 门禁和原生文件选择。代理传输、RuntimePolicy revision、open_external 展示、进程树终止全部复用，也没有预设会与 PR2 冲突的形状：没有 backend/session/model 类型，withAcpConnection（spawn → op → kill）以后可拆成 open/close 而不动 coordinator。方案成立；下面的缺口都在失败/恢复路径上。

P2 — 托管副本被篡改或损坏后 UI 无法恢复

可达 ②。installAntigravity 把已存在的 <state>/external-agents/antigravity/1.1.1 视为不可变：antigravity-install.ts:65-71 任何不匹配都抛 integrity_failed，antigravity-install.test.ts:90-95 还固定了这一行为。一旦 agy_acp_server.par 或 helper 变了一个字节（磁盘错误、helper 自改写、手工改到一半），Install 和 Reinstall 都永远返回 integrity_failed；唯一恢复办法是手动 rm -rf 一个 UI 从不显示的目录。归档是 hash 固定的，用新验证的副本替换不匹配的副本不会装进任何未验证内容。修法：verifyInstallation(destination) 失败时删除或改名挪开该目录，然后走 staged 安装；匹配时保留复用快路径。若坚持不可变，则新增 managed_copy_modified 失败码并在文案里指出目录。

P3 — “迟到结果不能覆盖已变更配置”只在 renderer 层成立

可达 ②，窗口很窄。Host 只在准入时比较 expectedExecutable（external-agent-setup-coordinator.ts:102-104）；安装后的保存走 applyHostPatchWithoutLane → updateRuntimePolicy（runtime-host-settings-ipc-main.ts:384-386），乐观重试会覆盖当前 revision。唯一守卫是 external-agent-settings/page.tsx:188-196 对 props.settings 的对象同一性判断。PR1 可接受，但 PR 正文把它表述成 Host 属性。要么弱化表述，要么让安装 attempt 在准入时记录 RuntimePolicy revision，自己用该 expectedRevision 提交 set_external_agents。

P3 — cleanup_failed 会 drain 整个 Host

可达 ④，只因影响面记一笔。onCleanupFailure 调用 retainUntilProcessExit() + requestDrain()（execution-composition.ts:1430-1433），Settings 页一次检查泄漏一个子进程就会让该 Host 上所有会话退出。改成本进程生命周期内标记 setup 不可用并记录 pid，可把损害限定在引发它的功能内。

WorkHub E2E 改动

仅测试层面，没有掩盖产品 bug：packages/ui/src/composer.tsx:1267-1273 在 sendPendingRef.current 期间有意忽略 Enter，点击路径本来就会自动等待；workhub-layout.spec.ts:354,372 只是让键盘路径等同样的就绪。与 Antigravity 无关，请单独一个 commit。

复杂度

六个模块搬到 application/contracts/settings-presentation/ 加 shim（约 470 行）是 renderer-architecture 检查强制的。可去掉两处：docs/antigravity-acp-settings.md:49-67 和登录截图是当作文档提交的 PR 证据（用户文档按 #5103 属于 PR3）；runtime-host-oauth-presentation.ts:94 的 expectedStateHint 纯属防御，单槽 expectation 已经串行化了 attempt。选择已有程序不验证即保存符合 #5103；Host 启动时仍会校验（checkedFile），信任等级与 shell.executable 相同。

测试：Host 66 / storage 71 / CLI 7 / Desktop 39 通过；准入守卫、逐文件 hash 校验、六分钟窗口三处在回退修复后各自变红。head 的兼容 epoch 是 144（main 为 142）；PR 正文写的 143/141 已过期。

[Astro-Han]

Head is 144 over main's 142, but the log now lists 142 twice and a 143 that never shipped. Collapse to 143 with one line ("Antigravity setup: RuntimePolicy externalAgents, external_agents.setup.* operations, managed install progress") and update the PR body, which still says 143/141.
（epoch 只需大于 main 的 142；合成一行 143，PR 正文同步。）

[Sun-GLiang]

Push back on lowering the epoch to 143, while accepting the history correction. The branch had already advertised 143 before it incorporated main epoch 142, whose Skill-query refusal contract is incompatible with those builds. Reusing 143 would therefore let different protocols claim compatibility, and the repository guard states that epochs never decrease. Commit 1c83548 keeps 144, corrects the 142/143 history, and adds a comment-only compatible-change declaration. The PR body now states 144 over main 142. （由 Codex 代为更新）

[Astro-Han]

expectedStateHint is defensive only: the single #pending slot already refuses a second expectation, so no other attempt can present into this one. Drop the parameter and the field; setup can rely on the existing attempt-scoped slot like model OAuth does.
（单槽已保证不串号，expectedStateHint 可删。）

[Sun-GLiang]

Push back: keep expectedStateHint. A single slot serializes current expectations but does not bind a late producer to the current generation. Attempt A can expire or cancel, attempt B can occupy the slot, and then a delayed URL from A can arrive; without the state check it would consume B and open the wrong URL. The rolling-lease regression in 1c83548 proves that an expired A cannot present into B. （由 Codex 代为更新）

[Sun-GLiang]

Reworked from the reviewed f0b78a2 baseline in 1c8354860 and updated the PR description.

Accepted and fixed:

• Damaged or incomplete managed copies are repaired only after a fresh archive and both members verify. Replacement moves the old directory aside, rolls back on publication failure, and recovers the old directory after an interrupted exchange.
• Crash-left .install-* staging is swept without following symlinks.
• Missing proxy credentials report download_failed.
• Setup browser presentation uses a same-attempt polling-renewed 30-second lease and releases after abandonment.
• The post-install Settings mutation carries the original executable as a semantic precondition; optimistic revision retries stop if another client has changed that selection.
• Acceptance logs and four PR-only screenshots were removed from the tree.

Push back:

• Keep epoch 144, not 143: pre-merge branch builds already advertised 143 without main epoch 142, so reuse would falsely claim compatibility. The history comments are corrected.
• Keep expectedStateHint: a late URL from expired attempt A must not consume attempt B.
• Keep whole-Host drain after cleanup_failed: TERM and KILL have both failed, while PR1 has no retained orphan supervisor to own the surviving process. Feature-only disablement would leave an unowned process and violate the cleanup invariant.

The WorkHub readiness fix remains isolated in test-only commit 07af97634.

Validation: full build and typecheck; Biome lint/format; Desktop/UI Knip; renderer architecture; Astryx and Windows inventories; staged epoch guard; complete Core, Runtime Host, and Desktop compiled test suites; focused setup regression suites. All passed. Real Google/download acceptance was not repeated.

（由 Codex 代为更新）

[Sun-GLiang]

Reworked the review follow-up from f0b78a2 in 1c8354860; the PR body and inline replies now reflect the accepted fixes and the three evidence-backed push backs. All local checks and complete Core/Runtime Host/Desktop compiled test suites passed. Please re-review the new head. （由 Codex 代为提交）

[Astro-Han]

Follow-up on 1c8354860. Every previous item is resolved or correctly declined; my earlier calls on expectedStateHint and on lowering the epoch were wrong. Not approving yet: the PR is about 1.1k lines larger than its behaviour needs, and one of those blocks is a scope question for the maintainers.

Previous item	Status
P2 tampered/corrupted managed copy unrecoverable	Fixed. antigravity-install.ts:93-97 falls through on integrity_failed; move-aside + rename-in are same-filesystem atomic, crash windows are restored/swept on the next attempt. Repair, sweep and displaced-recovery tests go red with their block removed.
P3 late result guarded only in renderer	Fixed. updateRuntimePolicyIf refuses the mutation when the executable no longer equals the admission basis.
P3 cleanup_failed drains the Host	Declined, accepted — same seam as onPoison/onFatal.
Epoch log / 143	History corrected; keeping 144 is right, the guard only forbids going below base.
Proxy credential → connection_failed	Fixed (execution-composition.ts:1410); no test pins the line.
Crash-left .install-*	Fixed, red with the sweep removed.
Six-minute presentation slot	Fixed: 30 s lease renewed only by query of the same attempt.
expectedStateHint	Declined, and the author is right: Host attempt A can still call openExternal after Desktop's slot expired and B occupies it. Keep.
Acceptance log / PNGs in docs	Fixed.
E2E in own commit	Already 07af97634.

P2 — The page belongs in src/renderer/settings/, not features/

Reachability ① for maintenance, not runtime. Placing page.tsx under features/external-agent-settings/ triggers the renderer-architecture rule that a feature may not import src/renderer/settings/*, so the PR copies six modules (settings-section, settings-route-header, runtime-host-settings-target, action-guard, oauth-login-flow-guard, use-action-guard) to application/contracts/settings-presentation/, leaves six re-export shims, re-types DesktopRuntimeHostRef as SettingsHostTarget, and adds services.ts, platform/desktop/create-external-agent-settings-services.ts and provider wiring because features may not read window.maka. The same script explicitly allows growth in src/renderer/settings (legacyGrowthDirectories, isAllowedLegacyGrowthPath), and every sibling page (subagent-settings-page.tsx, providers-panel.tsx, …) lives there and uses window.maka directly. Move the page there, restore the six modules, delete the contracts directory, services context and adapter, and add one legacyRendererFiles entry. About −750 lines and −10 files, no runtime change.

Scope question — managed installation

Not graded; this needs a maintainer decision, raised here so it does not block the P2. The installer (antigravity-install.ts + test, the install action, downloading/installing phases, downloadPercent, download_failed/installation_failed, proxy download wiring, Install/Reinstall/progress UI and copy) is roughly 900 of the PR's lines, and it makes Maka a package manager for a proprietary binary it does not own. The alternative is that PR1 only configures an ACP program the user already has (the existing Choose existing program path), checks it and signs in; Install ships later if there is demand. Two facts bear on it: neither the Antigravity IDE nor the agy CLI speaks ACP, so "already has" means the user downloaded Google's agy-acp-server zip themselves or through another ACP client (Zed installs registry agents under its own directory) — a narrower audience; and if the IDE's ACP extension places agy_acp_server.par on disk, pointing the picker at it is enough. If the maintainers keep Install, the current implementation is the floor for its own invariants and nothing further is asked.

Inline: timeoutMs on expect() is test-only; the renderer pre-computes host availability the Host already refuses; docs restate constants.

Tests on this head: Host antigravity-install + external-agent-setup-coordinator 17/17; Desktop setup IPC, presentation, settings page, settings IPC, client operations 57/57; six revert checks red as expected.

中文

对 1c8354860 的跟进。上一轮所有意见都已解决或被正确拒绝；我之前关于 expectedStateHint 和降低 epoch 的判断是错的。暂不 approve：PR 比其行为所需多出约 1.1k 行，其中一块需要维护者决定范围。

上一轮意见	状态
P2 托管副本损坏后无法恢复	已修。antigravity-install.ts:93-97 在 integrity_failed 时继续安装；挪开 + rename-in 同文件系统原子，崩溃窗口由下次尝试还原/清扫。修复、清扫、还原测试去掉对应代码块后变红。
P3 迟到结果只在 renderer 守卫	已修。updateRuntimePolicyIf 在可执行文件与准入基线不一致时拒绝 mutation。
P3 cleanup_failed drain Host	拒绝，接受——与 onPoison/onFatal 同一接缝。
Epoch 日志 / 143	历史已更正；保留 144 是对的，守卫只禁止低于 base。
代理凭据 → connection_failed	已修（execution-composition.ts:1410）；没有测试固定这一行。
崩溃残留 .install-*	已修，去掉清扫后变红。
六分钟展示槽	已修：30 秒租约，只由同一 attempt 的 query 续期。
expectedStateHint	拒绝，作者是对的：Desktop 槽过期、B 占槽后，Host 的 attempt A 仍可能调用 openExternal。保留。
验收日志 / PNG 进 docs	已修。
E2E 单独 commit	本就是 07af97634。

P2 — 页面应放在 src/renderer/settings/，不是 features/

维护层面的可达 ①，非运行时。把 page.tsx 放到 features/external-agent-settings/ 触发了 renderer 架构规则"feature 不得引用 src/renderer/settings/*"，于是 PR 把六个模块（settings-section、settings-route-header、runtime-host-settings-target、action-guard、oauth-login-flow-guard、use-action-guard）复制到 application/contracts/settings-presentation/，留下六个 re-export shim，把 DesktopRuntimeHostRef 重新定义成 SettingsHostTarget，又因为 feature 不能读 window.maka 而新增 services.ts、platform/desktop/create-external-agent-settings-services.ts 和 provider 接线。同一个脚本明确允许 src/renderer/settings 增长（legacyGrowthDirectories、isAllowedLegacyGrowthPath），所有兄弟页面（subagent-settings-page.tsx、providers-panel.tsx 等）都在那里并直接用 window.maka。把页面移过去、恢复六个模块、删掉 contracts 目录、services context 和 adapter，加一条 legacyRendererFiles 记录。约 −750 行、−10 个文件，无运行时变化。

范围问题——托管安装

不定级；需要维护者决定，在此提出以免阻塞上面的 P2。安装器（antigravity-install.ts 及测试、install action、downloading/installing phase、downloadPercent、download_failed/installation_failed、代理下载接线、Install/Reinstall/进度 UI 与文案）约占 PR 900 行，并让 Maka 成为一个不属于自己的专有二进制的包管理器。替代方案是 PR1 只配置用户已有的 ACP 程序（现有的 Choose existing program 路径）、检查并登录；有需求再做 Install。两个相关事实：Antigravity IDE 和 agy CLI 都不说 ACP，所以"已有"意味着用户自己下载了 Google 的 agy-acp-server zip，或通过其他 ACP 客户端（Zed 把 registry agent 装在自己目录下）得到——受众更窄；如果 IDE 的 ACP 扩展会把 agy_acp_server.par 放到磁盘上，用选择器指向它就够了。若维护者保留 Install，当前实现已是其自身不变量的下限，不再另提要求。

行内：expect() 的 timeoutMs 只有测试使用；renderer 预先计算 Host 已会拒绝的可用性；docs 复述常量。

本 head 测试：Host antigravity-install + external-agent-setup-coordinator 17/17；Desktop setup IPC、presentation、settings page、settings IPC、client operations 57/57；六项回退检查按预期变红。

[Astro-Han]

timeoutMs is only ever passed by tests; both production callers use the default and the lease is what actually governs lifetime. Drop the parameter here and in renew/expire.
timeoutMs 只有测试传，删掉。

[Astro-Han]

isAvailable(host) re-derives "local macOS arm64" from app.info + runtimeHostProfiles to disable the buttons and show copy.unavailable, but the Host already answers operation_unavailable on the first action. Two authorities for one fact; drop the pre-check and its retry state, render the Host's failure instead.
可用性判断 Host 已负责，renderer 不必再算一遍。

[Astro-Han]

The first paragraphs restate constants that live in code (15-minute timeout, 30 s handshake, 5-minute login, 32-record history, BROWSER=/usr/bin/true, staging sweep) and will drift on the next change. Keep only the observed-1.1.1 facts the code cannot carry (auth methods, stderr prefix, the −32000 response, hashes).
文档只留代码里没有的观测事实，不复述常量。