feat(chat-swarm): add MCP peer-worker protocol and conversation identity binding #47

Owner scope amendment — macOS only (2026-09-11)

依 Owner 最新裁決，本工作線相關功能設計、實作、交付與驗收 只處理 macOS。本裁決取代下文較早的跨平台／三平台要求。

• Windows、Linux 支援、移植、修復與平台驗證不在本次工作範圍；不再以三平台全綠作為本工作線的 acceptance criterion。
• 驗收保留 macOS 上必要的 source tests、獨立 package/install、真實呼叫入口、operation／副作用／讀回及適用的恢復與終態證據；ownership、lease、CAS、安全與獨立審查要求保持有效。
• 下方歷史測試、PR、平台結果與問題紀錄保留作為歷史證據，不代表目前仍有跨平台交付承諾。後續設計及驗收計畫以此 macOS-only 範圍為準。
• 本次更新僅修正 Issue 與規劃範圍；實作、部署與重啟仍依 Owner 的暫停指令保持暫停。
• 此文字更新不會自行修改 GitHub CI 設定或 branch protection；既有檢查設定如與新範圍不符，須另行明確調整，不得假稱已通過或繞過保護。

Status

BLOCKED_BY #46

Purpose

Add the first ChatGPT Swarm execution protocol on top of the accepted Swarm Core/SQLite layer. This Issue owns MCP peer workers only: ChatGPT conversations directly connected to Dev MCP, not Codex/Agy/OpenCode, not OpenCLI browser automation, and not Nexus MCP.

Source boundary

Observed main when this Issue was created: 296a3066fc620169f23beeeb5c9c41d9c9370d75 (tree 4d47c8e5e58b8302c076c1b97c990c4005b11843). Rebind fresh canonical main before mutation. Do not start until #46 has an independently accepted exact Candidate integrated or otherwise selected as the explicit successor base.

Hard prerequisite

• feat(chat-swarm): add durable core contract and SQLite store #46 — durable Swarm contract + SQLite store accepted.

Objective

Implement a bounded peer-worker protocol with explicit controller/worker identity binding and no repository mutation authority.

Expected controller-facing semantics to support later tooling:

• create swarm
• dispatch queued task
• inspect status
• collect result
• cancel/reconcile metadata

Expected worker-facing protocol:

• join swarm
• obtain/check next task
• submit structured result
• checkpoint/refresh lease

This Issue should implement protocol/coordinator logic and identity evidence handling, but should not yet register the final production chat_swarm_* MCP tool surface in src/server.ts unless the accepted #46 result proves a smaller required seam cannot express the production-path tests. If broader server wiring is required, stop and hand that delta to the next Issue rather than expanding silently.

Conversation identity requirements

Current DevSpace conversation scoping historically relied on openai/session. Swarm needs a stricter evidence abstraction.

Implement a conversation/session identity resolver with these properties:

• only explicitly allowlisted ChatGPT/OpenAI metadata keys may be authority evidence;
• normalize to {source, fingerprint};
• persist only a cryptographic fingerprint, not raw host session identifiers;
• if two present authority-capable keys disagree, fail closed as ambiguous;
• MCP transport/session ID may be diagnostic evidence but must not silently become worker authority;
• no reliable identity => controller/worker mutation actions fail closed;
• worker logical identity remains independent from conversation carrier identity.

Suggested evidence keys to investigate on the fresh host contract:

• openai/session
• openai/conversation_id
• openai/conversationId
• chatgpt/session

Do not assume all are currently emitted; tests must distinguish observed support from allowed parsing.

Required invariants

1. Controller mutation is bound to the swarm owner identity.
2. Worker join is bound to one verifiable conversation identity fingerprint.
3. One active logical worker cannot be simultaneously rebound to a conflicting live conversation without explicit reconciliation/continuation state.
4. A worker can claim/receive only one active task.
5. A worker can submit only its own assigned task.
6. Result submission never upgrades controller authority or retry permission.
7. Worker lease expiry does not automatically make a possibly-started task retryable.
8. RECONCILE_REQUIRED from feat(chat-swarm): add durable core contract and SQLite store #46 remains fail-closed through the protocol.
9. Targeted dispatch and first-available dispatch are deterministic under one coordinator transaction.
10. Duplicate join/dispatch/submit requests are idempotent only when their material request identity is identical.

Expected files

Likely new:

• src/chat-swarm-coordinator.ts
• src/chat-swarm-peer-runtime.ts
• corresponding focused tests

Likely existing:

• src/request-meta.ts
• src/request-meta.test.ts

Use the accepted #46 API instead of duplicating storage/state-machine logic.

Forbidden scope

• production browser automation
• OpenCLI integration
• src/durable-operations.ts
• Nexus-specific authority/recovery semantics
• provider-agent adapters
• Codex Goal
• automatic worktree/repository mutation by peer workers
• deployment/runtime reload

Verification

At minimum:

• focused coordinator tests
• focused identity resolver tests
• focused peer-runtime tests
• affected feat(chat-swarm): add durable core contract and SQLite store #46 store/contract regressions
• npm run typecheck
• git diff --check

Required hostile tests:

• conflicting conversation metadata
• worker identity substitution
• wrong-worker submit
• duplicate dispatch with changed payload
• lease expiry while task may have started
• restart/reload preserving RECONCILE_REQUIRED

Claim ceiling

CANDIDATE_READY only.

Do not claim production MCP tools are registered, live ChatGPT workers operate, OpenCLI works, or Dev MCP runtime contains the feature.

Next gate

Independent acceptance, then #48 may wire the accepted protocol into production MCP tools, cutover admission, capability manifest, and config.