Базовый контракт Фазы 2a для сессий с несколькими workspace

Краткое описание

Этот документ фиксирует базовый контракт Фазы 2a для задачи #6378 после PR с WorkspaceRegistry из Фазы 1. Текущий пакет реализации объединяет доработку повторяющегося флага --workspace из Фазы 1, защитные механизмы подготовки Фазы 2a и первый внутренний контракт реестра/runtime, необходимый для последующих работ над сессиями с несколькими workspace.

Фаза 2a остается исключительно для сессий. В этом базовом пакете не добавляются множественные маршруты, WorkspaceDaemonClient, ACP/WebSocket с привязкой к workspace, файловая система, память, MCP, настройки, голос, миграция channel-worker, env overlays, допуск по общему количеству сессий, capabilities workspaces[], multi_workspace_sessions, диспетчеризация маршрутов или создание не-primary runtime.

Базовый контракт

• Флаг --workspace можно повторять на уровне парсера CLI, чтобы yargs сохранял массив входных данных, а не схлопывал его.
• Быстрый путь для serve откатывается к полному парсеру, если присутствуют повторяющиеся значения workspace.
• Массив workspace с одним элементом рассматривается как primary workspace и сохраняет существующее поведение для одного workspace.
• Работа с несколькими явными workspace по-прежнему заблокирована флагом и вызывает ошибку до загрузки runtime.
• Дублирующиеся канонические входные данные workspace явно вызывают ошибку.
• Вложенные входные данные workspace явно вызывают ошибку.
• Различные невложенные множественные входные данные workspace вызывают общую ошибку загрузки “multi-workspace serve is not enabled”.
• Первый явный workspace станет будущим primary workspace после снятия ограничения; этот базовый пакет не делает этот список публичным.

Внутренний контракт WorkspaceRuntime теперь содержит стабильные метаданные для последующих работ в Фазе 2a:

• workspaceId: стабильный хэш канонического cwd workspace.
• workspaceCwd: канонический cwd workspace.
• primary: true для primary runtime.
• trusted: метаданные доверия во время загрузки; прямой fallback createServeApp остается false, если в production не передано явное значение trusted.
• env: только метаданные. Этот базовый пакет записывает режим родительского процесса и пустые ключи overlay; он не вычисляет env overlays для локального runtime.

Внутренний WorkspaceRegistry поддерживает точный поиск по cwd, точный поиск по id, primary fallback resolveWorkspaceCwd(undefined) и разрешение владельца активной сессии. Разрешение владельца активной сессии сканирует только сводки runtime bridge; оно не сканирует постоянное хранилище, не создает дочерние элементы и пока не маршрутизирует никакие запросы. При обнаружении дублирующихся активных владельцев доступ блокируется (fail closed) из-за неоднозначности результата.

createServeApp может принимать внедренный реестр для тестов и будущей сборки, но модули маршрутов по-прежнему получают только primary runtime. Существующие устаревшие app.locals.boundWorkspace и app.locals.fsFactory остаются локальными переменными совместимости только для primary.

Классификация маршрутов Фазы 2a

Первый открытый этап Фазы 2a должен классифицировать все маршруты /session/:id/* перед включением поддержки нескольких явных workspace.

Маршруты, диспетчеризируемые в Фазе 2a:

• POST /session
• GET /session/:id/events
• POST /session/:id/prompt
• POST /session/:id/cancel
• POST /session/:id/permission/:requestId
• POST /session/:id/heartbeat
• POST /session/:id/detach
• GET /session/:id/pending-prompts
• DELETE /session/:id/pending-prompts/:promptId
• DELETE /session/:id
• GET /session/:id/status

Последующие маршруты или маршруты только для primary:

• не-primary POST /session/:id/load
• не-primary POST /session/:id/resume
• GET /session/:id/export
• POST /sessions/delete
• POST /sessions/archive
• POST /sessions/unarchive
• PATCH /session/:id/organization
• мутации групп сессий
• мутации сессий: branch, fork, cd, rewind, shell, model и language
• не относящийся к сессиям POST /permission/:requestId
• /acp

Дополнительные активные маршруты чтения могут быть маршрутизированы по владельцу в более позднем срезе Фазы 2a только после того, как тесты докажут, что они зависят исключительно от соответствующего активного bridge.

Последующие требования Фазы 2a

• Сохранять промахи при сканировании как 404 session_not_found; никогда не откатываться к primary.
• Если более одного runtime сообщает об одном и том же id активной сессии, доступ блокируется (fail closed).
• Оставить список не-primary сессий только активным (live-only), если сохраненные записи явно не помечены как не подлежащие возобновлению (non-resumable).
• Добавить env overlays для локального runtime перед созданием не-primary дочерних процессов.
• Добавить maxTotalSessions на этапе инициализации нового bridge, чтобы REST и primary /acp не могли его обойти, при этом attach по-прежнему обходит допуск (admission).
• Опубликовать workspaces[], общие лимиты и multi_workspace_sessions только в финальном PR по снятию ограничений.
• Обновить типы capabilities SDK при выпуске аддитивной схемы capabilities, но не добавлять клиент workspace в Фазе 2a.

Решения по аудиту

• Базовый PR не должен создавать не-primary runtime или смягчать какие-либо REST-маршруты.
• Существующие app.locals.boundWorkspace и app.locals.fsFactory остаются локальными переменными совместимости только для primary.
• REST routeFileSystemFactory остается отдельным от файловых систем фабрик bridge; он не должен использоваться для представления границ не-primary bridge.
• Вторичные корни файловой системы IDE не должны повышаться до явных workspace runtime.
• Поведение родительского окружения для одного workspace остается совместимым до тех пор, пока не будет снято ограничение на полноценный режим с несколькими workspace.