fix(hire): the hire flow grants MCP connectors that every bundled engine rejects at first turn, with no warning at creation time #314

Preflight

• I searched open and closed issues for duplicates.
• I removed credentials, personal data, and private content from this report.
• This is not a security vulnerability.

Tracker sweep. Scanned all 116 issues (open + closed, GET /issues?state=all, pages 1–3) for mcp / connector / connection in the title. One hit: #89 ("hire flow has no way to grant MCP tools to a digital employee", blocked by upstream). Not a duplicate: #89 records the 2026-08 state where no grant path existed. Since #205 (2026-09-07, "promote RoleWeave workspace and branding to main") the grant path does exist — the hire UI ships an MCP connector picker and the AI proposal can bind servers — so the failure mode has changed from "cannot grant" to "grant succeeds, first turn always fails". This issue records that new state. Posted a cross-reference comment on #89.

Summary

The hire flow (v0.2.0) lets an operator bind MCP connectors to a new employee — via the CapabilityPicker UI or via an AI proposal — and the hire completes successfully with the binding written into the position package. But every bundled engine rejects employee-level MCP bindings before the first turn starts, so the employee's first task fails in under a second with qoder.mcp_binding_unsupported. Nothing at hire time warns that the granted capability is currently unusable.

Expected behavior

The hire flow should not let an operator grant a capability that the selected (or any) engine cannot honor — or should at least warn at binding/creation time that employee-level MCP is not yet supported by any engine.

Actual behavior

1. In the hire drawer's CapabilityPicker, clicking an MCP server card (workspace-drive / issue-tracker / repository) binds it and shows "已绑定" — no warning.
2. An AI hire proposal carrying mcpServers is applied verbatim (applyProposal) — also no warning.
3. Hire submits, returns status: "hired". buildPositionSkeletonFiles() writes the non-empty mcpServers into permissions.json, generates mcp.json, and attaches entrypoints.mcp + policy.mcpTools to employee.json.
4. First turn dispatch fails in <1 s: 当前 Qoder 适配器尚不支持员工 MCP 绑定；未加载全局 MCP 配置。 (qoder.mcp_binding_unsupported, retryable: false). The user experience is "employee created fine, then instantly broken, with no hint that the MCP binding is the cause" — and re-hiring the next employee reproduces it.

Reproduction

Observed on a real install (Windows, v0.2.0, Qoder host bound):

1. Hire a new employee with an MCP server selected in the CapabilityPicker (or accept an AI proposal that grants one).
2. Hire succeeds; the position package on disk contains "mcpServers": [{...}] in permissions.json.
3. Dispatch any task to the employee → fails immediately with qoder.mcp_binding_unsupported.
4. Manual workaround: edit the position's permissions.json, set mcpServers to []; the next turn spawns normally (verified).

Version or commit

Environment

• Windows 11 (10.0.26200), RoleWeave v0.2.0 desktop installer, engine control plane over WSL, Qoder host.
• Server-side behavior read from main 5f2f6a88; not run from a source checkout (see Not verified here).

Affected component

• apps/desktop/renderer/src/org/PermissionsEditor.tsx (CapabilityPicker MCP section)
• apps/desktop/renderer/src/org/HireDrawer.tsx (proposal application)
• apps/server/src/routes/hire.ts + apps/server/src/org/apply.ts (creation-time gate)
• apps/server/bin/qoder-engine.mjs (the guard that fires at turn time)

Proposed severity

S2. A first-class hire-flow path completes "successfully" while producing an employee whose every turn fails until the operator manually edits permissions.json. The failure surfaces away from its cause (at turn time, not hire time), the error copy does not name the MCP binding as removable, and re-hiring reproduces it.

Current evidence level

E2 — source + live reproduction. Steps 1–4 of the Reproduction were executed on the reporter's machine (v0.2.0 install; screenshots and the on-disk package files inspected). Engine-side guard and hire-side code paths are read from main 5f2f6a88 at the listed blobs. Line numbers below are from those exact blobs.

Evidence

Grant side — no engine-capability gate anywhere before the package is staged:

• PermissionsEditor.tsx:207-222 — CapabilityPicker renders the "MCP 连接器" section from hireMcpCatalog (capabilities.ts:51-70 registers workspace-drive, issue-tracker, repository); toggleMcpServerGrant binds with one click; no warning copy.
• HireDrawer.tsx:196-200 — applyProposal persists proposal.mcpServers verbatim via replaceCapabilityRules; no warning.
• permission-artifacts.ts:58-111 (derivePermissionArtifacts) validates only that the grant id exists in hireMcpCatalog; it cannot see engines.
• apply.ts:543-617 — buildPositionSkeletonFiles writes permissions.json with the granted mcpServers (L617 mcp.json; L571 entrypoints.mcp when mcpTools non-empty; L582 assets list).
• routes/hire.ts (351 lines) contains zero occurrences of mcp — the server-side hire contract imposes no engine-capability check on the grant.

Engine side — every host refuses the grant the hire flow just wrote:

• qoder-engine.mjs:802 — fail("qoder.mcp_binding_unsupported", "当前 Qoder 适配器尚不支持员工 MCP 绑定；未加载全局 MCP 配置。", false) whenever permissions.mcpServers is non-empty; the turn never starts.
• qoder-engine.mjs:839 — the Qoder spawn hardcodes --strict-mcp-config --mcp-config '{"mcpServers":{}}' --setting-sources ""; :1016 shows the Claude branch doing the same.
• agent-registry.ts:103-123 — all six host definitions declare capabilities: ["turns", "streaming", "sessions", "groups", "approvals"]; no host declares MCP support, so "no engine can honor this" is currently a static fact, not a per-host check.

History context: #89 (blocked by upstream) predates #205; PR #91 was closed unmerged after review, and the MCP runtime itself is owned upstream (fullstack-ai-infra/digital-employee#219). The grant surface shipped regardless, which is what this issue is about.

Proposed fix / 未决决策

The engine-side MCP runtime is upstream's to build (#219); this issue only asks that the hire surface stop selling a capability no engine can honor. Options, in decreasing rigor:

• A (recommended): gate at hire time. In the hire contract (routes/hire.ts) / org-apply staging, reject a request whose permissions.mcpServers is non-empty with a clear error ("employee-level MCP is not yet supported by any engine; leave MCP connectors unbound"), and grey out the MCP section in CapabilityPicker with the same copy. When a host eventually declares MCP support (via agent-registry.ts capabilities), the gate unlocks automatically.
• B: warn only. Keep the binding creatable but show a persistent warning in the picker and at hire submit. Weaker: the failure still exists, just announced.
• C: leave as-is until upstream test(desktop): stabilize the group workspace navigation regression #219 lands. Every v0.2.0 user who tries the visible MCP section gets a silently broken employee.

Decision needed from the product owner: reject-at-hire (A) vs warn-and-allow (B). Either way the fix is small and entirely inside roleweave.

Non-goals

• Implementing the employee-level MCP runtime / spawn plumbing — owned by fullstack-ai-infra/digital-employee#219; see also [blocked by upstream] hire flow has no way to grant MCP tools to a digital employee (requires MCP runtime + permission chain in digital-employee) #89.
• Changing the position-package schema, hireMcpCatalog contents, or the permission-artifact validation rules.
• Any change to already-created packages (the manual unbind workaround already works).

Acceptance criteria

• Hiring an employee with a non-empty mcpServers grant is either rejected at hire time with copy that names the limitation (A), or the picker/submit surfaces a persistent warning (B) — per the product owner's call.
• The CapabilityPicker MCP section is rendered disabled (A) or annotated (B) while no host in agent-registry.ts declares MCP support.
• An employee hired without MCP grants behaves exactly as today (no regression in the default path).
• When a future host declares MCP support in agent-registry.ts, the gate/warning no longer triggers for that host without further edits to the hire surface (the check reads the registry, not a hardcoded list).

Not verified here

• Whether engines outside the bundled set (if any runtime-resolved hosts exist) honor MCP grants — the check would read agent-registry.ts, whose six built-ins are all I verified.
• macOS/Linux packaged builds were not exercised; the reporter verified Windows only.