[Yuqing (mydmdm)]

Summary

Related: #371. The reported Filesystem proxy does not advertise the required commands error occurs before a filesystem prompt. Files previously inspected the optional session command catalogue immediately after session connection, even though its notification can arrive later. The timing failure is reproducible; its occurrence on the affected Windows machine has not yet been confirmed.

• Advertise the fixed read-only filesystem v1 contract in ACP initialize as agentCapabilities._meta["com.microsoft.agentlet/filesystem"] = { version: 1 }, with canonical constants and validation in @agentlet/protocol.
• Gate Files on the current client's initialization result, reusing existing bootstrap/profile propagation instead of waiting for available_commands_update.
• Preserve the existing slash-command transport, session lifecycle, authority boundary and legacy command announcements. Missing, malformed or unsupported capabilities fail before any filesystem prompt with an explicit Agentlet-update message.
• Add focused protocol, service and real harness/bootstrap regressions; wire the focused Agentlet tests into the normal recursive workspace test command and update the related architecture documentation.

Compatibility and scope

New Servers require an updated Agentlet that advertises the initialization extension; there is no fallback to command-announcement readiness. New proxies continue emitting the legacy catalogue for older Servers, without claiming to fix timing behavior in those old Servers.

The Agentlet subtree and Huabu changes are separate commits. No Agenetes production changes, new RPCs, filesystem operations, path/UNC fixes, HTTP contract changes, Profile migrations or release changes are included.

Validation

• pnpm typecheck
• pnpm format, pnpm lint:fix (no errors; existing warnings remain), and final pnpm format:check
• pnpm --filter @huabu/server exec vitest run src/modules/agent/acp/device-files.test.ts — 23 passed, including absent/delayed command announcements, incompatible initialization metadata, deadlines, reconnects and cleanup.
• pnpm --filter agentlet exec vitest run --root ../.. packages/protocol/tests/filesystem.test.ts packages/local/tests/fs-proxy.test.ts packages/local/tests/filesystem.test.ts — 34 passed on native Linux.
• pnpm --filter @huabu/server bundle
• AGENTLET_FS_PROXY_TEST_ENTRY="$PWD/apps/server/dist-bundle/agentlet/fs-proxy.js" pnpm --filter agentlet test — 24 passed, including the actual production proxy bundle through the trusted harness shell launch and daemon ACP bootstrap.
• node scripts/check-headers.mjs and git diff --check

Remaining machine verification

The user will test the updated Server and Windows Agentlet together to determine whether this change removes the observed remote/cross-platform instability. Verify directory listing and UTF-8 reads on Windows, with Mac regression checks; record build identities if failures persist. Native Windows/macOS, Electron utility-process behavior and the affected deployment's actual notification timing have not been verified here. This PR does not claim that Windows-specific root cause has been conclusively established.