> For the complete documentation index, see [llms.txt](https://faction-os.gitbook.io/faction-os-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/sessions/phase21-session03-orchestration-command-center-expansion/spec.md). # Session Specification **Session ID**: `phase21-session03-orchestration-command-center-expansion` **Phase**: 21 - Bottom Rail Focused Surface Expansion **Status**: Not Started **Created**: 2026-06-29 **Package**: apps/web **Package Stack**: TypeScript *** ## 1. Session Overview This session makes Orchestration's primary open path expose the real Command Center workbench in the focused bottom-rail surface. Sessions 01 and 02 already created transient expansion state and the shared expansion host; this session uses that host from inside the Orchestration panel instead of treating the summary details popup as the main destination. The user-facing outcome is direct: when an operator reaches for the natural Orchestration open action, the focused surface must answer where Campaigns, File/Git, Attention, Executors, Federation, and Metrics are operated. The existing `OrchestrationTabs` and `CommandCenterPanes` implementation remains the source of truth, so compact and focused modes continue sharing one mounted `OrchestrationPanel` and one `OrchestrationShell`. The old details portal may remain as a secondary state summary, but it must no longer be the primary labelled path. Tests must prove the expanded Orchestration surface contains the actual Command Center tabs, preserves tab and local row/drawer state across close and reopen, and does not re-run hydration by mounting a second Orchestration tree. *** ## 2. Objectives 1. Rename and route the primary Orchestration header action to open the focused Command Center surface. 2. Keep `OrchestrationDetailPortal` available only as a secondary state summary if retained. 3. Prove expanded Orchestration exposes Campaigns, File/Git, Attention, Executors, Federation, and Metrics through the existing tab workbench. 4. Add regression coverage for tab preservation, selected local state, terminal drawer state, and no duplicate hydration. *** ## 3. Prerequisites ### Required Sessions * [x] `phase21-session01-expansion-state-foundation` - Provides transient `expandedBottomRailSurfaceId` state and setter in `useSettingsStore`. * [x] `phase21-session02-shared-expansion-host` - Provides `BottomRailExpansionHost` in `App.tsx` with same-instance promotion, focus recovery, backdrop, Escape, and stable bottom-rail test ids. ### Required Tools Or Knowledge * Node 26.2.0+ and npm 11.16.0 workspace commands. * React component state, refs, and Testing Library behavior tests. * Zustand selector usage across `useSettingsStore` and `useGameStore`. * Existing Orchestration Command Center tabs, shortcuts, drawer, and hydration flows. ### Environment Requirements * Local repository checkout with npm dependencies installed. * Happy DOM test environment used by `apps/web/tests`. * No hosted account, Cloudflare credential, Worker credential, provider key, local server credential, or backend execution change is required. *** ## 4. Scope ### In Scope (MVP) * Web cockpit users can use the primary Orchestration header/open action to open the focused Command Center surface - implemented through `expandedBottomRailSurfaceId` in `apps/web/src/store/useSettingsStore.ts`. * The primary Orchestration open label changes from details language to product-facing working-surface language such as `Open Command Center`. * Expanded Orchestration shows the existing `OrchestrationTabs` workbench and existing Command Center pane content, including Campaigns, File/Git, Attention, Executors, Federation, and Metrics. * `commandCenter.activeTab` remains the canonical tab state and is preserved across focus close/reopen. * Local `OrchestrationShell` state for selected Attention row, selected Campaign row, and terminal drawer open state remains in the same mounted shell instance when the surface expands or closes. * Existing details popup behavior is retained, renamed, or demoted as a secondary state summary without being the main user path. * Tests prove no second `OrchestrationPanel` or `OrchestrationShell` tree is rendered for expansion. ### Out Of Scope (Deferred) * Repointing `o d` and command-center shortcut help to the expanded Command Center - Reason: Session 04 owns shortcut and overlay layering after the primary pointer path is corrected. * Nested overlay Escape precedence between terminal/runtime drawers, retained details inspectors, and the focused surface - Reason: Session 04 owns overlay-layer ordering; this session only avoids regressing retained local state. * Quest Board and War Room primary panel parity - Reason: Session 05 applies the focused-surface contract to those panels. * Responsive viewport tuning and browser screenshot evidence - Reason: Session 06 owns desktop and small viewport verification. * Backend orchestration execution, queue/campaign/file/Git/terminal/container semantics, hosted services, remote execution, trusted erasure, or Worker protocol changes - Reason: this session changes the `apps/web` access path only. *** ## 5. Technical Approach ### Architecture Route the primary Orchestration header action through the Session 01 and 02 expansion contract. `OrchestrationShell` can read `setExpandedBottomRailSurfaceId` from `useSettingsStore` and pass a primary open handler to `OrchestrationHeader`; clicking that handler sets the expanded surface id to `"orchestration"`. The `BottomRailExpansionHost` already wraps the single mounted `OrchestrationPanel` in `apps/web/src/App.tsx`, so setting the store field promotes the existing panel instead of creating a new tree. `OrchestrationHeader` should present working-surface copy for the primary header button. If the details portal remains useful, provide a separate, secondary control with state-summary copy such as `Open orchestration state summary`, keeping `detailsOpen` local in `OrchestrationShell` and preserving the existing `OrchestrationDetailPortal` tests under that secondary role. Tests should exercise both direct Orchestration rendering and the host-wrapped path. Direct panel tests can prove the primary button sets `expandedBottomRailSurfaceId`; a host-wrapped regression can prove the focused surface contains the existing Command Center tablist and that tab and local state survive close/reopen because the child instance is not remounted. ### Design Patterns * Same-instance promotion: Use `BottomRailExpansionHost` and the existing mounted `OrchestrationPanel`; do not render a second panel, shell, or tab tree. * Store-backed shell action: Route primary focus through `useSettingsStore` while preserving `useGameStore.commandCenter.activeTab` for Command Center tab state. * Secondary inspector separation: Keep summary/details behavior clearly labelled as secondary so it does not compete with the primary working surface. * Behavioral regression tests: Count hydration/API calls and assert state continuity rather than relying on visual modal chrome alone. *** ## 6. Deliverables ### Files To Create | File | Purpose | Est. Lines | | ---- | ----------------------------------------------------------------- | ---------- | | None | This session updates existing Orchestration components and tests. | 0 | ### Files To Modify | File | Changes | Est. Lines | | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | | `apps/web/src/components/orchestration/OrchestrationHeader.tsx` | Replace primary details wording with Command Center working-surface wording, accept separate primary focus and secondary summary handlers, and update ARIA labels/controls. | \~60 | | `apps/web/src/components/orchestration/OrchestrationShell.tsx` | Wire primary open action to `setExpandedBottomRailSurfaceId("orchestration")`, keep details portal secondary, preserve local selected row and terminal drawer state, and avoid duplicate hydration paths. | \~90 | | `apps/web/tests/OrchestrationPanel.test.tsx` | Update details-popup assertions, add primary Command Center open behavior, expanded tab reachability, tab/state preservation, terminal drawer preservation, and no duplicate hydration coverage. | \~220 | | `apps/web/tests/CockpitShell.test.tsx` | Add or adjust App-level Orchestration expansion assertions when mocked panel coverage needs to prove the focused route remains host-backed. | \~60 | | `apps/web/tests/keyboardShortcuts.test.ts` | Adjust only if renamed action copy affects current pure shortcut expectations before Session 04 completes. | \~20 | | `apps/web/tests/commandCenterShortcuts.test.ts` | Adjust only if renamed action copy affects shortcut metadata expectations before Session 04 completes. | \~20 | | `apps/web/tests/KeyboardShortcutsModal.test.tsx` | Adjust only if visible shortcut copy changes before Session 04 completes. | \~20 | *** ## 7. Success Criteria ### Functional Requirements * [ ] The primary Orchestration header/open action is labelled as a working surface, not as `Open Orchestration details`. * [ ] Activating the primary Orchestration action sets `expandedBottomRailSurfaceId` to `"orchestration"` with duplicate-trigger prevention while in-flight where relevant to UI state. * [ ] Expanded Orchestration includes `data-testid="command-center-tab-campaigns"`. * [ ] Campaigns, File/Git, Attention, Executors, Federation, and Metrics tabs are reachable in expanded mode through the existing `OrchestrationTabs` implementation. * [ ] Changing tabs in expanded mode updates `commandCenter.activeTab`. * [ ] Close and reopen preserves the intended tab, selected campaign, selected attention item, and terminal drawer state within the same mounted shell. * [ ] Expansion does not trigger duplicate command-center hydration, diagnostics, channel health, or lineage roster fetches. * [ ] Any retained details popup is labelled and tested as a secondary state summary. ### Testing Requirements * [ ] Focused Orchestration tests prove the primary open action routes to bottom-rail expansion. * [ ] Tests prove expanded Orchestration exposes the real Command Center tabs and panes. * [ ] Tests prove tab and local selected state survives close/reopen. * [ ] Tests prove hydration/API call counts do not increase just because the surface expands. * [ ] Focused web tests and web typecheck completed. ### Non-Functional Requirements * [ ] No backend execution, hosted service, Worker, remote execution, trusted erasure, or formal accessibility certification claim is introduced. * [ ] Broad Orchestration rows remain product-facing and do not expose raw commands, terminal output, diffs, file contents, provider payloads, tokens, secrets, or broad absolute paths. * [ ] The expanded path preserves the single mounted Orchestration implementation and avoids local state forks. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code follows project conventions. * [ ] Primary user-facing surfaces contain product-facing copy only. *** ## 8. Implementation Notes ### Working Assumptions * `apps/web` is the package context: the analysis script marks the candidate session as `apps/web`, and all source evidence points to web cockpit components and tests. * Session 02's fixed-position same-instance host is available: `apps/web/src/App.tsx` already wraps Orchestration in `BottomRailExpansionHost`, and host tests prove child state is preserved while switching compact/focused layout. * Shortcut routing remains mostly deferred to Session 04: the Session 03 stub says to update tests that currently treat details popup behavior as primary, while the Session 04 stub explicitly owns `o d` and overlay-layer behavior. This session may update copy-only expectations if required, but it should not expand shortcut scope beyond the primary Orchestration open path. ### Conflict Resolutions * The Session 03 stub says "primary Orchestration open path" and also mentions the `o d` shortcut, while Session 04 owns shortcut and overlay layering. The chosen interpretation is that Session 03 fixes the primary in-panel pointer/header path and preserves compatibility for shortcut tests unless labels must change; Session 04 will repoint shortcut dispatch and modal help comprehensively. * The existing details portal test calls the popup "full orchestration state", but the Phase 21 PRD says it is only a summary/details inspector and not the real workbench. The chosen interpretation is to keep or rename that coverage as secondary state-summary behavior while adding new primary Command Center expansion coverage. ### Key Considerations * `OrchestrationShell` already owns `detailsOpen`, `terminalDrawerOpen`, `selectedAttentionId`, and `selectedCampaignId` local state. The implementation should preserve those variables and avoid lifting them unless a test proves same-instance expansion is insufficient. * `OrchestrationTabs` already exposes `command-center-tab-campaigns`; tests should assert the existing test ids instead of creating new debug-only UI. * Existing Orchestration API mocks in `apps/web/tests/OrchestrationPanel.test.tsx` can be used to count hydration, diagnostics, channel health, and lineage roster calls. * `docs/orchestration-quickstart.md` already describes the visible Command Center tabs; documentation updates are reserved for Session 07 unless implementation changes require immediate wording fixes. ### Potential Challenges * Direct `OrchestrationPanel` tests do not include `BottomRailExpansionHost`: wrap the panel in the host for focused-surface assertions or assert the store state directly when only the header route is under test. * The old header button currently owns `aria-controls="orchestration-detail-modal"`: update ARIA to point primary behavior at the focused surface and put modal controls on the retained secondary summary control. * Command Center hydration runs on mount; tests must distinguish legitimate initial load from duplicate loads caused by rendering a second tree or remounting on expansion. * The terminal runtime drawer is local state inside the shell; close/reopen should not unmount the shell or reset that drawer unexpectedly. ### Relevant Considerations * \[P20] **Release evidence is the execution claim source**: The new Command Center open path must be proven with tests before claiming it is shipped. * \[P20] **Do not add action verbs before evidence**: Product copy such as open, dispatch, execute, or recover must remain backed by existing implementation and evidence. * \[P20] **Broad privacy gates are release-critical**: The focused surface must not broaden raw command, output, diff, file-content, token, provider, webhook, Docker, or broad-path detail into normal rows. * \[P03] **Stable docs are the current contract**: Stable docs already describe Command Center tabs; final documentation alignment belongs to Session 07 after all focused surfaces are complete. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * The primary open action opens a summary modal instead of the real workbench, leaving Campaigns undiscoverable. * Expansion renders a duplicate Orchestration tree and silently forks hydration, selected rows, terminal drawer state, or local result state. * Retained details summary, drawers, or tab controls lose accessible labels or state after the primary route is renamed. *** ## 9. Testing Strategy ### Unit Tests * Update pure/header-adjacent assertions in `apps/web/tests/OrchestrationPanel.test.tsx` to expect working-surface copy for the primary Orchestration action and secondary state-summary copy for any retained details inspector. * Add assertions that the primary header action sets `useSettingsStore.getState().expandedBottomRailSurfaceId` to `"orchestration"`. ### Integration Tests * Render Orchestration through `BottomRailExpansionHost` in an Orchestration-focused test, open the primary Command Center action, and assert `bottom-rail-expanded-orchestration` plus the existing Command Center tab test ids. * Switch to Campaigns, Attention, Executors, Federation, and Metrics in expanded mode and assert `commandCenter.activeTab` changes through `useGameStore`. * Select or focus campaign and attention records, open the terminal runtime drawer, close/reopen the focused surface, and assert local state remains in the same shell instance. * Count Orchestration API mock calls before and after expansion close/reopen to prove no duplicate hydration, diagnostics, channel health, or lineage roster calls were introduced. ### Runtime Verification * No browser viewport pass is required in this session; Session 06 owns desktop and small viewport visual evidence after all panel-specific routes are wired. ### Edge Cases * Clicking the primary header action while the Orchestration surface is already focused leaves the same focused surface active without remounting. * Opening and closing the focused surface does not reset the selected Campaigns tab or selected rows. * Secondary state-summary details can open and close without becoming the main Command Center route. * Tests distinguish initial hydration from duplicate hydration caused by expansion. *** ## 10. Dependencies ### Other Sessions * Depends on: `phase21-session01-expansion-state-foundation`, `phase21-session02-shared-expansion-host`. * Depended by: `phase21-session04-shortcut-and-overlay-layering`, `phase21-session06-responsive-layout-and-accessibility-pass`, `phase21-session07-final-regression-and-documentation`. *** ## Next Steps Run the `implement` workflow step to begin implementation. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/sessions/phase21-session03-orchestration-command-center-expansion/spec.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.