feat(desktop): add host-bound folder references to the composer

[sunrioa]

Summary

Fixes#3994.

This PR separates the composer’s “Add files or directories” entry into “Add files” and “Reference folder”, with a native folder picker and removable folder-reference chips.

• Support up to four folder references per message, represented only as { hostId, path } and bound to the originating Runtime Host.
• Preserve folder references through draft handoff, queueing, send, reload, replay, and regeneration while keeping the user-authored message text unchanged.
• Present only the referenced path to the model; directory contents are inspected on demand through the existing Glob/Read tools and permission flow.
• Keep the selected project, working directory, ordinary attachments, and sandbox permissions unchanged.

Before

After

Review focus

Selecting a folder creates a Host-bound reference; it does not upload the directory, recursively enumerate it, change the Session working directory, or grant filesystem access.

Following review, the implementation was narrowed to the path-only design. The eager directory-listing path and its timeout, cancellation, frozen-preview, and replay machinery were removed. The Agent now observes directory contents only through the existing filesystem tools, so there is a single filesystem observation and permission path.

The change spans the Desktop picker/composer, shared message contracts, Runtime Host admission and protocol transport, runtime model context, persistence, replay/regeneration, and rendering. Runtime Host compatibility advances from 68 to 69, so Desktop and Runtime Host must be updated together.

Generated source/test inventories are updated. Local validation notes, packaged applications, and other build artifacts are not included.

Verification

The final macOS and hosted results below apply to exact head 82d148ad31f71ca752b0688dc70c27c6aedaf396.

macOS

• npm ci
• npm run clean && npm run build
• npm run typecheck
• npm run lint
• npm run format:check
• npm run check:asf-headers
• npm run astryx:surface-inventory
• Core directory-reference tests: 3/3 passed.
• Runtime model-context tests: 2/2 passed.
• AI SDK path-only test: 1/1 passed.
• Runtime Host/protocol tests: 5/5 passed.
• Desktop composer and draft-handoff tests: 12/12 passed.
• UI plus-menu tests: 11/11 passed.
• Directory-reference and WorkHub Electron E2E: 3/3 passed.
• WorkHub E2E stability run: 10/10 passed with --repeat-each=5.

Windows — local verification

Full Windows validation was completed on the pre-merge feature head 82b160078730c6e34acd71dcad8a336c4061c50e using Windows 11 x64, Node.js 25.2.1, npm 11.12.1, and Rust/Cargo 1.98.0.

• Clean install, build, typecheck, lint, format, ASF-header, and generated-inventory checks passed.
• Windows Broker formatting, build, and tests passed: 51/51.
• All focused directory-reference Core, Runtime, Runtime Host, Desktop, and UI tests passed.
• Directory-reference Electron E2E passed once and then 10/10 with --repeat-each=10.
• Windows dist smoke passed.
• Windows x64 packaging and verify:windows-x64 passed, including AppContainer lifecycle, cancellation/recovery, parent-exit cleanup, 64-way concurrency, adversarial matrix, ConPTY, and renderer checks.
• The packaged app launched successfully, and the native folder picker, reference chip, removal, send/reload, and unchanged project selection were verified.

The only local check:release exception was the standalone-launcher test invoking a WSL installation without /bin/bash; the remaining release checks and the packaged-product verification passed.

GitHub Actions

All required GitHub Actions checks passed on exact final head 82d148ad31f71ca752b0688dc70c27c6aedaf396.

AI use

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

Tool(s) and scope: OpenAI Codex assisted with source inspection, implementation, regression tests, local verification, code review, and drafting this PR. I have reviewed the changes and take responsibility for this contribution.

Checklist

• Tests cover the change and fail without it
• Lint, format, typecheck, and the affected focused suites pass locally
• Windows smoke, packaging, and packaged-product verification pass

Does this PR entail a change in behavior?

• Yes — described under Summary above
• No

[Astro-Han]

Thanks for taking this all the way through the Runtime Host, persistence, replay, and Desktop UI layers. The underlying problem is real: a user should be able to reference a directory without uploading every file or changing the Session working directory.

I think the first version could be substantially simpler, though.

The PR already preserves a good core authority — the Host-bound { hostId, path } reference — but it then eagerly scans one directory level during admission and carries a frozen listing through queueing, replay, and regeneration. That introduces two views of the same directory: the submission-time snapshot and the live filesystem later observed through Glob/Read.

Could we narrow the first slice to:

• persist and present only the Host-bound directory reference;
• let the Agent inspect it on demand using the existing Glob/Read tools;
• continue relying on the existing Runtime Host boundary and permission flow?

This would avoid a second filesystem observation path and remove much of the preparation, timeout, frozen-listing, replay, and coordinator machinery. If real usage later shows that Agents routinely fail to inspect referenced directories, an eager bounded preview could still be added from evidence rather than assumed up front.

There is also one concrete P2 in the current implementation: the five-second abort reaches the managed worker path, but the local bypass/full-access path does not pass the signal into nodeGlob. A slow or unavailable network mount can therefore keep the submission blocked well past the intended timeout. The smaller path-only design would avoid needing this admission-time timeout altogether.

This is intended as a simplification suggestion, not a request for a parallel implementation. The directory reference should remain the single authority either way.

Review analysis was assisted by Codex and independent @reviewer agents; Astro-Han evaluated the proposed authority boundary, reachability, and simplification and owns this comment.

中文对照

谢谢你把这个功能完整地贯通到 Runtime Host、持久化、重放和 Desktop UI。它要解决的问题是真实的：用户应该能够引用一个目录，而不需要上传其中的每个文件，也不需要改变 Session 的工作目录。

不过我认为第一版可以明显更简单。

当前 PR 已经保留了一个很好的核心 authority——Host-bound 的 { hostId, path } 引用；但随后又在 admission 阶段主动扫描一层目录，并让冻结的 listing 参与排队、重放和重新生成。这会产生同一目录的两种视图：提交时的快照，以及 Agent 后续通过 Glob/Read 看到的实时文件系统。

是否可以把第一版收敛为：

• 只持久化并呈现 Host-bound 的目录引用；
• 让 Agent 按需使用现有 Glob/Read 工具检查目录；
• 继续复用现有 Runtime Host boundary 和权限流程？

这样可以避免第二条文件系统观察路径，并删除大量 preparation、timeout、冻结 listing、重放和 coordinator 机制。如果真实使用证明确实有很多 Agent 不会主动检查被引用的目录，我们再基于证据增加有限的主动预览也不迟。

当前实现还有一个具体的 P2：五秒取消信号能够到达 managed worker，但 local bypass/full-access 路径没有把它传进 nodeGlob。遇到缓慢或不可用的网络挂载时，一次提交可能远远超过预期时间仍无法结束。采用更小的纯路径方案后，也不再需要这套 admission-time timeout。

这是一个收敛实现的建议，并不是建议另建一套并行方案。无论最终选择哪种方式，目录引用都应该保持为唯一 authority。

本次审查分析由 Codex 和独立的 @reviewer 子代理协助；Astro-Han 评估了 authority 边界、问题可达性和简化方案，并对这条评论负责。

[sunrioa]

Addressed in 82d148ad31f71ca752b0688dc70c27c6aedaf396.

I narrowed the implementation to the path-only design suggested in the review:

• directory references now persist only { hostId, path };
• the eager directory listing and its timeout, cancellation, frozen-preview, and replay machinery were removed;
• directory contents are inspected on demand through the existing Glob/Read tools and permission flow;
• draft handoff, queueing, send, reload, replay, and regeneration continue to preserve the Host-bound reference.

The focused macOS suites and E2E stability runs pass. Full Windows validation passed on the pre-merge feature head, and all required GitHub Actions checks are green on the final head.

The PR description has also been updated to reflect the reduced scope and current verification results.

简体中文

已在 82d148ad31f71ca752b0688dc70c27c6aedaf396 中按照审查建议完成调整。

实现现已收窄为仅保留路径的设计：

• 目录引用只持久化 { hostId, path }；
• 删除了预先读取目录以及相关的超时、取消、冻结预览和重放逻辑；
• Agent 通过现有的 Glob/Read 工具和权限流程按需检查目录内容；
• 草稿交接、排队、发送、重载、重放和重新生成仍会保留绑定 Host 的目录引用。

macOS 定向测试和 E2E 稳定性复跑均已通过。合并前的功能提交已完成完整 Windows 验证，最终提交上的全部必需 GitHub Actions 检查也已通过。

PR 描述也已更新，以反映收窄后的实现范围和最新验证结果。