> 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/phase19-session14-channels-and-scope/spec.md). # Session Specification **Session ID**: `phase19-session14-channels-and-scope` **Phase**: 19 - Orchestration Command Center Execution **Status**: Not Started **Created**: 2026-06-26 **Package**: null **Package Stack**: mixed *** ## 1. Session Overview This session adds external channel and webhook command intake to the Orchestration command center while making scope visible and filterable across queue, lineage, attention, and guarded-action surfaces. It is next because Sessions 04 through 06 and 13 are complete, and Session 15 explicitly depends on this channel and scope slice. The implementation is cross-cutting. It touches protocol contracts first, then server manager and route behavior, then adapter attribution helpers and web controls. External payloads must create visible proposals or local queue/attention records first; trusted automatic execution remains out of scope. The session also closes the current product gap where channels and webhooks are represented only as generic command-center records or unsupported historical routes. It keeps local-first privacy boundaries intact by using path-safe project labels, replay guards, source attribution, and bounded payload summaries. *** ## 2. Objectives 1. Extend shared protocol contracts for channel-originated work, guarded channel proposals, replay metadata, and cross-surface scope labels. 2. Implement manager-owned inbound channel/webhook intake routes that validate payloads, reject unsafe raw fields, dedupe replayed events, and create proposal-first command-center records. 3. Add web scope controls and channel command UI that filter queue, lineage, attention, guarded actions, and command-center snapshots without exposing absolute paths. 4. Add focused protocol, server, adapter, and web tests for validation, replay protection, source attribution, conversion behavior, and path-safe filtering. *** ## 3. Prerequisites ### Required Sessions * [x] `phase19-session04-campaign-workbench` - provides command-center campaign and queue workbench foundations. * [x] `phase19-session05-attention-and-permissions` - provides attention and permission decision machinery. * [x] `phase19-session06-executor-registry` - provides executor capability and guarded-action evaluation machinery. * [x] `phase19-session13-collaboration-and-handoff` - provides federation, handoff, room posture, and collaboration context. ### Required Tools Or Knowledge * Current command-center protocol contracts in `packages/protocol/src/orchestrationCommandCenter.ts`. * Current task queue and guarded-action contracts in `packages/protocol/src/taskQueue.ts` and `packages/protocol/src/guardedActions.ts`. * Current server route, manager, auth, rate-limit, and unsupported-route patterns in `apps/server/src/`. * Current outbound adapter privacy and formatter boundaries in `apps/adapters/src/shared/`. * Current Orchestration shell, store, API client, and pane patterns in `apps/web/src/`. ### Environment Requirements * Node 26.2.0+ and npm 11.16.0. * Root npm workspace dependencies installed. * Local validation through Vitest, TypeScript, Biome, and root workspace checks. *** ## 4. Scope ### In Scope (MVP) * Operators can receive generic webhook, GitHub webhook, Telegram, Discord, or generic channel events as validated command-center channel commands - implement source attribution, replay guard, validation status, and bounded summaries. * Operators can see channel-created queue entries, attention items, or guarded channel proposals - route all external commands through existing permission and execution machinery with duplicate-trigger prevention while in flight. * Operators can filter command-center state by current project, all projects, active room, imported session, remote context, package/worktree/source, and session roster labels - use path-safe labels and avoid absolute path leakage. * Operators can inspect channel health, pairing/config status, and command source in the web Orchestration surface - show loading, empty, error, offline, and unavailable states. * Engineers can validate intake, replay, source attribution, command conversion, and scope filtering through focused tests. ### Out Of Scope (Deferred) * Trusted automatic execution from external channels by default - Reason: the PRD requires permission, audit, redaction, tests, and docs before execution claims. * Hosted identity, hosted collaboration safety, production-hosted validation, or account-backed channel trust - Reason: hosted services remain disabled-default or no-claim. * Push/mobile notification routing and usage metrics - Reason: owned by Session 15. * Final keyboard workflow and stable documentation closeout - Reason: owned by Session 16. * Broad historical `/channels/:room/messages` parity - Reason: this session implements command intake, health, pairing, and command records only. *** ## 5. Technical Approach ### Architecture Shared protocol changes lead the work. Add channel-originated task queue sources, guarded channel proposal vocabulary, command-center channel metadata, and scope labels before server or web consumers depend on them. Keep `packages/protocol/src/orchestrationCommandCenter.ts`, `packages/protocol/src/taskQueue.ts`, and `packages/protocol/src/guardedActions.ts` as the source of truth. Server behavior should live behind a new manager boundary that receives already-authenticated local HTTP requests, validates channel/webhook payloads, checks replay keys, produces bounded channel command records, and optionally creates task queue entries, attention items, or guarded channel proposals. Route handlers should be thin and should emit existing command-center, queue, and guarded-action events. The web surface should reuse the existing Orchestration shell and command-center store. Add a scope filter bar and a channel command panel instead of building a separate route. All filters should flow through existing API query parameters or targeted extensions to queue and guarded-action list queries. ### Design Patterns * Protocol-first contracts: prevents server/web drift for channel command, scope, and guarded channel vocabulary. * Manager-owned intake: keeps replay protection, validation, source attribution, and conversion behavior in one server boundary. * Proposal-first external input: external payloads create visible local records before any execution path. * Pure web normalization: sanitize and normalize channel/scope payloads before mutating Zustand state. * Product-facing UI copy: broad views show channel/source/scope metadata only; raw payloads, command bodies, prompts, secrets, and absolute paths stay out of the browser. *** ## 6. Deliverables ### Files To Create | File | Purpose | Est. Lines | | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ---------- | | `apps/server/src/managers/channelCommandManager.ts` | Manager-owned channel/webhook intake, replay guard, source attribution, and proposal conversion. | \~240 | | `apps/server/src/lib/channelCommandValidation.ts` | Validation and normalization for GitHub, generic webhook, Telegram, Discord, and channel pairing inputs. | \~220 | | `apps/server/src/routes/channelCommands.ts` | Local routes for channel health, pairing, command listing, GitHub webhook intake, and generic webhook intake. | \~170 | | `apps/server/tests/channelCommandManager.test.ts` | Manager tests for replay, conversion, source attribution, and safe labels. | \~170 | | `apps/server/tests/channelCommandRoutes.test.ts` | Route tests for validation, auth inheritance, idempotency, WebSocket updates, and no raw echo. | \~190 | | `apps/adapters/src/shared/channelCommandSource.ts` | Shared adapter helper for channel source labels, delivery ids, and bounded external attribution. | \~120 | | `apps/adapters/tests/channelCommandSource.test.ts` | Adapter helper tests for provider labels and secret/path redaction. | \~100 | | `apps/web/src/components/orchestration/ScopeFilterBar.tsx` | Scope labels and filters for command-center, queue, lineage, attention, and guarded-action views. | \~170 | | `apps/web/src/components/orchestration/ChannelCommandPanel.tsx` | Channel command health/intake UI with source attribution and visible failure states. | \~210 | | `apps/web/tests/ChannelCommandPanel.test.tsx` | Component tests for source labels, action states, empty/error/offline states, and accessibility. | \~150 | ### Files To Modify | File | Changes | Est. Lines | | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ---------- | | `packages/protocol/src/taskQueue.ts` | Add channel task source/ref vocabulary and safe source attribution coverage. | \~50 | | `packages/protocol/src/guardedActions.ts` | Add guarded channel family/kind labels and validation surface. | \~35 | | `packages/protocol/src/orchestrationCommandCenter.ts` | Add channel command metadata, scope labels, replay status, source validation, and parser tests. | \~150 | | `packages/protocol/tests/orchestrationCommandCenter.test.ts` | Cover channel/scope parsing, blocked raw fields, path-safe labels, and replay metadata. | \~120 | | `apps/server/src/lib/guardedActionValidation.ts` | Accept guarded channel proposals and enforce kind/family mapping. | \~20 | | `apps/server/src/managers/executorRegistry.ts` | Add default proposal-only or unavailable channel executor capability for guarded channel commands. | \~45 | | `apps/server/src/managers/orchestrationCommandCenter.ts` | Store enriched channel commands, attention linkages, scope metadata, and filtered event snapshots. | \~100 | | `apps/server/src/routes/commandCenter.ts` | Reuse channel manager output with command-center mutation/event helpers where needed. | \~45 | | `apps/server/src/server.ts` | Wire channel command routes and manager dependencies at root and `/api` prefixes. | \~35 | | `apps/server/src/lib/unsupportedRoutes.ts` | Keep unsupported broad channel routes while allowing implemented webhook/channel intake routes. | \~25 | | `apps/web/src/lib/orchestrationApi.ts` | Add channel intake clients, scope query support for queue/guarded-action snapshots, and parser error mapping. | \~120 | | `apps/web/src/lib/commandCenterUi.ts` | Add channel command view models, scope labels, and path-safe label helpers. | \~95 | | `apps/web/src/store/useGameStore.ts` | Store scope filters, normalize channel events, reset selected details on filter changes, and apply scoped hydration. | \~110 | | `apps/web/src/components/orchestration/OrchestrationHeader.tsx` | Surface current scope and channel intake posture without overclaiming remote execution. | \~35 | | `apps/web/src/components/orchestration/CommandCenterPanes.tsx` | Mount scope and channel panels in the correct Orchestration views. | \~45 | | `apps/web/src/components/orchestration/OrchestrationShell.tsx` | Pass scope filters to snapshots, queue, guarded actions, lineage, refreshes, and mutations. | \~120 | | `apps/web/tests/orchestrationApi.test.ts` | Cover scoped query strings, channel intake clients, validation failures, and offline mapping. | \~100 | | `apps/web/tests/commandCenterStore.test.ts` | Cover scoped hydration, channel event normalization, malformed payload rejection, and selected-detail cleanup. | \~90 | | `apps/web/tests/commandCenterUi.test.ts` | Cover channel/scope labels and absolute-path redaction. | \~80 | | `docs/api/README_api.md` | Document implemented local channel/webhook intake routes and proposal-first boundary. | \~60 | | `apps/server/README_server.md` | Document server channel manager, routes, replay guard, and local-first limits. | \~45 | | `apps/web/README_web.md` | Document web scope filters, channel panel states, and product-facing copy boundary. | \~45 | | `apps/adapters/README_adapters.md` | Document that outbound adapters can share attribution helpers while inbound trust remains server-routed and proposal-first. | \~35 | *** ## 7. Success Criteria ### Functional Requirements * [ ] `POST /webhooks/generic` and `POST /webhooks/github` accept valid bounded payloads and create visible channel command records with source, validation, replay, and target metadata. * [ ] Replayed channel or webhook events return deterministic duplicate results without creating duplicate queue, attention, or guarded-action records. * [ ] Channel-created work can appear as queue entries, attention items, or guarded channel proposals, and approval remains explicit. * [ ] Scope filters consistently affect queue, lineage, attention, guarded actions, command-center snapshots, and channel records. * [ ] Project/worktree/source labels avoid absolute path leakage and reject unsafe path-like values. ### Testing Requirements * [ ] Unit tests cover protocol parsing, channel validation, adapter attribution, manager conversion, replay protection, and source labels. * [ ] Route tests cover auth inheritance, invalid payloads, duplicate triggers, WebSocket updates, and no raw echo. * [ ] Web tests cover API clients, store normalization, UI filters, source attribution, loading/empty/error/offline states, and accessibility labels. ### Non-Functional Requirements * [ ] External payload summaries are bounded and redacted before storage or browser display. * [ ] Channel intake remains local-first and disabled from trusted automatic execution unless a later session explicitly changes the boundary. * [ ] UI controls remain dense, responsive, and product-facing with diagnostics confined to tests, docs, or dev-only detail. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code follows project conventions. * [ ] Primary user-facing surfaces contain product-facing copy only. * [ ] `npm --workspace packages/protocol run typecheck` passes. * [ ] `npm --workspace apps/server run typecheck` passes. * [ ] `npm --workspace apps/web run typecheck` passes. * [ ] `npm --workspace apps/adapters run typecheck` passes. * [ ] Focused Vitest suites pass before broad workspace validation. *** ## 8. Implementation Notes ### Working Assumptions * Session 14 is the next executable session: the analysis script reports Phase 19 in progress, Sessions 01-13 complete, and Session 14 as the earliest unfinished candidate; Sessions 15 and 16 remain unfinished and Session 15 depends on Session 14. * This is a cross-cutting monorepo session: the analysis script reports `package: null` for the candidate, the stub lists `apps/server`, `apps/web`, and `apps/adapters`, and project conventions require protocol-led shared contract changes. * `packages/protocol` is in scope even though the session stub omits it: `CONVENTIONS.md` states shared queue, guarded-action, route, WebSocket, and domain types should change in protocol before package-specific behavior. * External commands create proposals first: the master PRD, security record, and considerations all require threat, permission, audit, redaction, unavailable states, tests, and docs before real executor or inbound command claims. ### Conflict Resolutions * Candidate package metadata conflicts with the stub package list. The chosen interpretation is `Package: null` cross-cutting work because the session spans protocol, server, web, and adapters and cannot be safely scoped to one package. * Stable docs mention `packages/protocol/src/orchestration.ts`, but the current repository has `packages/protocol/src/orchestrationCommandCenter.ts`, `taskQueue.ts`, and `guardedActions.ts`. The plan targets the actual files present in the repo. * `apps/server/src/lib/unsupportedRoutes.ts` currently classifies `/webhooks/` and `/channels/` as historical unsupported routes, while Phase 19 makes bounded intake routes in scope. The plan implements only the explicit MVP intake routes and leaves broad historical channel messaging unsupported. ### Key Considerations * Protocol must lead cross-package work to avoid drift. * Inbound channel payloads are external input and must be schema-validated, bounded, redacted, and replay-guarded. * Web broad views should show source and scope metadata, not raw payloads or command bodies. * Existing app auth, rate limits, body caps, CORS, and WebSocket origin checks must continue to wrap the new routes. ### Potential Challenges * Scope filter semantics can drift across queue, lineage, attention, guarded actions, and command-center records: centralize scope labels and query construction in protocol/API helpers and test every surface. * Channel command conversion can accidentally duplicate records: use idempotency keys and replay keys at the manager boundary and assert duplicate behavior in tests. * GitHub and generic webhook payloads vary widely: normalize a small bounded MVP shape and reject unsupported raw fields instead of accepting arbitrary payloads. * Adding channel guarded actions touches executor registry mappings: keep the default channel capability proposal-only or unavailable, not executor-ready. ### Relevant Considerations * \[P03] **Real executors remain unimplemented by design**: inbound command intake must stay proposal-first unless an executor family has permission, audit, redaction, tests, and docs. * \[P03-packages/protocol] **Protocol leads cross-package work**: shared channel, scope, queue, guarded-action, route, and event shapes change before server and web wiring. * \[P03-apps/server] **Local server boundary must stay conservative**: new routes inherit loopback defaults, auth, rate limits, body caps, validation, and explicit unavailable behavior. * \[P07] **Redaction is boundary-specific**: channel, queue, attention, guarded-action, adapter, and web payloads each need bounded summaries and blocked raw fields. * \[P07] **Hosted services ship as disabled-default guardrails only**: channel intake must not imply hosted identity, production collaboration, push delivery, analytics, or trusted erasure. * \[P06-apps/warroom+apps/web] **War Room federation is optional and redacted**: active-room scope labels must not imply hosted account identity or production auditability. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Replayed or double-submitted webhooks creating duplicate local work. * External payload fields leaking prompts, tokens, command bodies, absolute paths, or raw provider payloads. * Scope filters appearing active in one pane while stale data remains visible in another pane. * Channel proposals being mistaken for trusted automatic execution. *** ## 9. Testing Strategy ### Unit Tests * Protocol parser tests for channel source, replay metadata, scope labels, task queue source vocabulary, guarded channel action vocabulary, and blocked raw fields. * Adapter helper tests for bounded source labels, delivery ids, and redaction. * Server manager tests for generic/GitHub payload normalization, replay guard behavior, source attribution, path-safe labels, and queue/attention/guarded conversion. * Web helper and store tests for scope label normalization, malformed channel event rejection, selected-detail cleanup, and safe path handling. ### Integration Tests * Server route tests for `GET /channels`, `POST /channels/:id/pair`, `GET /channel-commands`, `POST /webhooks/github`, and `POST /webhooks/generic` at root and `/api`. * Web API tests for scoped query strings, channel command fetches, intake mutation clients, timeout/offline failures, invalid responses, and stale/duplicate conflict mapping. * Component tests for scope filter controls and channel command panel states. ### Runtime Verification * Start the local server in a test port and submit bounded generic and GitHub webhook payloads. * Verify a channel command record, queue or attention proposal, and WebSocket channel update are emitted. * Verify replaying the same delivery id returns a duplicate result without creating another record. * Verify the web Orchestration surface can filter to current project/all projects/active room/imported/remote labels without raw absolute paths. ### Edge Cases * Missing or invalid delivery id. * Oversized summary or unsafe raw field. * Absolute path, URL-like, traversal, or backslash project labels. * Offline web client and timeout while refreshing scoped snapshots. * Channel source configured but execution capability remains unavailable or proposal-only. * Scope filter changed while a selected detail no longer exists in the filtered collection. *** ## 10. Dependencies ### Other Sessions * Depends on: `phase19-session04-campaign-workbench`, `phase19-session05-attention-and-permissions`, `phase19-session06-executor-registry`, `phase19-session13-collaboration-and-handoff`. * Depended by: `phase19-session15-metrics-and-notifications`, `phase19-session16-ergonomics-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/phase19-session14-channels-and-scope/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.