> 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-session13-collaboration-and-handoff/spec.md). # Session Specification **Session ID**: `phase19-session13-collaboration-and-handoff` **Phase**: 19 - Orchestration Command Center Execution **Status**: Not Started **Created**: 2026-06-26 **Package**: null **Package Stack**: mixed *** ## 1. Session Overview This session connects the command center to the optional War Room, canonical Notice Board, and handoff/resume workflows without moving ownership of local state out of the local server. It upgrades the existing command-center handoff collection from a compact scaffold into a validated collaboration surface with visibility labels, Notice linkbacks, readiness checks, resume-source metadata, lineage links, and remote-access summary posture. It is next because Phase 19 Sessions 04, 05, 08, and 09 completed campaigns, attention/permissions, file/Git intent protection, and hero lineage. Sessions 10 through 12 then added mission artifacts, planning context, and terminal/container capability records. Those surfaces now provide the queue, approval, conflict, completion, artifact, lineage, and execution records that collaboration notices and handoffs need to reference. The session keeps Worker federation optional and redacted. War Room posture can make orchestration rows room-visible or remote-originated, but remote relay payloads stay bounded, local handoff files are validated before resume, and remote access/tunnel controls remain summary-only with no tunnel creation or sensitive control plane exposure. *** ## 2. Objectives 1. Extend command-center collaboration contracts for visibility labels, Notice linkbacks, handoff readiness, resume sources, lineage links, and remote-access summary state. 2. Add server-owned collaboration and handoff behavior that posts bounded review, blocker, and completion notices from selected command-center contexts with duplicate-trigger prevention. 3. Connect optional War Room relay posture, catch-up/import provenance, and external-transfer disabled states to command-center records without changing Worker privacy ownership. 4. Add a web Federation/Handoff workbench that renders room, notice, handoff, and resume state with complete loading, empty, error, offline, unavailable, and in-flight states. *** ## 3. Prerequisites ### Required Sessions * [x] `phase19-session04-campaign-workbench` - local plans and task queue contexts for review, blocker, and completion notices. * [x] `phase19-session05-attention-and-permissions` - approval and permission records that can be linked from notices. * [x] `phase19-session08-file-and-git` - file/Git intent state for conflict, branch, and file-state handoff checks. * [x] `phase19-session09-heroes-and-lineage` - hero lifecycle and lineage records for handoff source/target links. * [x] `phase19-session10-mission-artifacts` - evidence, verification, and review-gate records that handoffs can cite. * [x] `phase19-session12-terminal-and-containers` - terminal/container remote-access boundaries that remain summary-only here. ### Required Tools Or Knowledge * Node 26.2.0+ and npm workspaces. * Vitest root test runner. * Existing Notice Board manager, War Room Notice bridge, command-center routes, command-center store, and War Room Worker relay tests. * Current local-first collaboration, privacy, and isolation docs. ### Environment Requirements * Local workspace dependencies installed with `npm install`. * Local server auth, CORS, rate-limit, body-size, and WebSocket origin protections remain inherited by new routes. * No Cloudflare credentials, live Worker room, remote tunnel, hosted identity, provider credentials, or production deployment required for tests. *** ## 4. Scope ### In Scope (MVP) * Operators can see local-only, room-visible, relay-unavailable, catch-up-pending, imported, external, remote-originated, and external-transfer-disabled labels on relevant command-center collaboration rows. * Operators can post bounded review request, blocker, and completion notices from selected queue, permission, file-intent, review-gate, execution, handoff, or room contexts. * Notice records can carry safe command-center linkbacks for tasks, approvals, conflicts, completions, handoffs, and room state. * Handoffs can record readiness, scaffold status, secret-scan status, validation status, staleness, branch/file-state checks, resume queue source, and lineage links. * Remote access/tunnel posture appears as compact summary state with unavailable or disabled labels, docs paths, and no sensitive tunnel control. * War Room relay and catch-up provenance update local command-center posture while preserving optional external-transfer boundaries. * Protocol, server, Worker relay, web API/store/component, docs, and focused validation coverage are updated. ### Out Of Scope (Deferred) * Changing Worker privacy contracts - Reason: the session must consume and annotate the existing optional relay boundary, not broaden Worker payload permissions. * Owning remote tunnel creation inside Orchestration - Reason: remote access/tunnel control remains a disabled-default hosted operation and separate threat model. * Hosted identity, account-backed collaboration, or production audit proof - Reason: War Room authority remains room-local and non-hosted. * Raw handoff transcript storage in command-center records - Reason: handoff records carry validation, links, and safe summaries only. * Executing tasks from Notice Board posts - Reason: notices coordinate work and link records; execution stays with guarded command-center families. * Trusted unified erasure for handoff, Worker, logs, exports, backups, or archives - Reason: the cumulative trusted-erasure no-claim remains open. *** ## 5. Technical Approach ### Architecture Protocol changes lead the cross-package work. `packages/protocol/src/orchestrationCommandCenter.ts` will extend handoff and command-center event contracts with collaboration visibility labels, Notice link refs, handoff readiness fields, resume-source metadata, lineage links, and remote-access summary posture. `packages/protocol/src/notices.ts` will add bounded command-center link metadata to Notice Board create/list payloads, and `packages/protocol/src/warroom.ts` will expose only compact relay posture labels already allowed by the Worker boundary. The server will keep behavior manager-owned. A new collaboration helper/manager boundary will derive safe command-center linkbacks, build Notice Board create requests, validate handoff readiness, record resume-source state, inspect branch/file-state metadata through existing Git/file-intent summaries, and write compact handoff records through `OrchestrationCommandCenterManager`. Routes will live with the command-center router so auth, rate limiting, validation, idempotency, stale-revision checks, and WebSocket event emission stay consistent with existing mutation patterns. War Room integration will annotate, not expand, relay behavior. The existing `WarRoomNoticeBridge` and Worker relay tests already handle optional relay sends, remote Notice ingestion, catch-up, room mismatch, and provenance. This session will surface those outcomes as command-center posture and preserve filtered payloads; it will not add Worker tunnel control, hosted identity, raw remote context, or new relay frame families for sensitive data. The web app will turn the Federation tab into a product workbench. `orchestrationApi.ts` and a new command-center collaboration view-model helper will expose typed posture, notice-post, handoff validation, and resume-source actions. `CollaborationHandoffPanel.tsx` will render Federation/Handoff state with contextual Notice actions, linked records, readiness badges, remote-access summary, and duplicate-trigger guards. Existing drawer and store paths will normalize new fields before state mutation. ### Design Patterns * Protocol-first contracts: shared DTOs and parsers are extended before server or web behavior consumes them. * Manager-owned lifecycle: handoff readiness, notice request construction, resume source, and relay posture stay behind server-owned helpers. * Existing Notice Board ownership: context posting calls the canonical local Notice Board manager and routes instead of creating a parallel notice store. * Pure normalization before store mutation: web helpers reject malformed or raw collaboration payloads before updating Zustand state. * Product-surface UI: user-facing surfaces show workflow state and safe labels only; diagnostics remain explicit diagnostic surfaces. *** ## 6. Deliverables ### Files To Create | File | Purpose | Est. Lines | | --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | | `apps/server/src/lib/commandCenterCollaboration.ts` | Build safe command-center Notice linkbacks, collaboration labels, handoff readiness summaries, remote-access summaries, and privacy-safe notice requests | \~320 | | `apps/server/src/managers/handoffManager.ts` | Own handoff scaffold, validation, secret-scan status, staleness, branch/file-state, resume-source, and lineage-link records | \~360 | | `apps/server/tests/commandCenterCollaboration.test.ts` | Unit tests for Notice request building, linkback validation, visibility labels, remote-access summary, and raw payload rejection | \~240 | | `apps/server/tests/handoffManager.test.ts` | Unit tests for scaffold, validation, staleness, branch/file-state, secret-scan, resume-source, lineage, and duplicate idempotency behavior | \~280 | | `apps/web/src/lib/commandCenterCollaboration.ts` | Web view models for collaboration labels, handoff readiness, Notice post affordances, remote summary, and linked-record metadata | \~260 | | `apps/web/src/components/orchestration/CollaborationHandoffPanel.tsx` | Federation/Handoff workbench with notice actions, readiness rows, room posture, remote summary, and linked records | \~340 | | `apps/web/tests/commandCenterCollaboration.test.ts` | View-model tests for labels, safe copy, action availability, malformed payloads, and fallback ordering | \~180 | | `apps/web/tests/CollaborationHandoffPanel.test.tsx` | Component tests for loading, empty, error, offline, in-flight, notice posting, handoff readiness, and accessibility behavior | \~260 | ### Files To Modify | File | Changes | Est. Lines | | --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | | `packages/protocol/src/orchestrationCommandCenter.ts` | Add collaboration visibility, Notice link, handoff readiness, resume source, lineage link, and remote-access summary contracts | \~300 | | `packages/protocol/src/notices.ts` | Add bounded command-center link metadata to Notice Board payload parsing without allowing raw command or transcript fields | \~170 | | `packages/protocol/src/warroom.ts` | Add compact relay posture labels and catch-up/import summary helpers for existing safe frame families | \~130 | | `packages/protocol/src/index.ts` | Export updated collaboration, Notice, and War Room contract helpers | \~12 | | `packages/protocol/tests/orchestrationCommandCenter.test.ts` | Cover handoff readiness, resume source, lineage links, visibility labels, remote summary, and blocked raw fields | \~220 | | `packages/protocol/tests/notices.test.ts` | Cover Notice command-center link parsing, bounded related context, and blocked raw payload metadata | \~160 | | `packages/protocol/tests/warroomNoticeRelay.test.ts` | Cover compact relay posture labels, catch-up/import summaries, and blocked sensitive frame fields | \~140 | | `apps/server/src/lib/commandCenterValidation.ts` | Add parsers for context notice posts, handoff validation, scaffold, resume-source, and collaboration posture requests | \~220 | | `apps/server/src/managers/orchestrationCommandCenter.ts` | Store expanded handoff records, event entries, collaboration posture counts, and safe linkback metadata | \~180 | | `apps/server/src/lib/warRoomNoticeBridge.ts` | Surface remote/catch-up/import provenance and relay-unavailable outcomes as compact command-center posture data | \~140 | | `apps/server/src/routes/commandCenter.ts` | Add context notice, handoff scaffold, handoff validation, resume-source, and collaboration posture routes with duplicate-trigger prevention while in-flight | \~260 | | `apps/server/src/server.ts` | Instantiate the handoff manager and pass Notice Board, War Room bridge, command-center, and Git/file-intent dependencies into command-center routes | \~90 | | `apps/server/tests/commandCenterRoutes.test.ts` | Cover context notice posting, handoff routes, stale revision, idempotency, WebSocket updates, auth inheritance, and no raw echo | \~260 | | `apps/server/tests/warRoomNoticeBridge.test.ts` | Cover relay unavailable, catch-up pending, imported, remote-originated, external-transfer-disabled, and provenance posture cases | \~180 | | `apps/warroom/src/index.ts` | Preserve safe catch-up and Notice relay filtering while exposing only compact posture counts needed by protocol helpers | \~90 | | `apps/warroom/tests/noticeBoardRelay.test.ts` | Cover Worker relay privacy-safe Notice payloads, posture counts, catch-up limits, and blocked raw fields | \~160 | | `apps/web/src/lib/orchestrationApi.ts` | Add collaboration posture, context notice, handoff scaffold, validation, and resume-source clients with parser guards | \~260 | | `apps/web/src/lib/commandCenterUi.ts` | Add collaboration label copy, handoff readiness labels, remote summary copy, and Notice action affordance helpers | \~180 | | `apps/web/src/store/useGameStore.ts` | Normalize expanded handoffs, collaboration posture events, in-flight mutation keys, selected detail reset, and malformed payload rejection | \~180 | | `apps/web/src/components/orchestration/CommandCenterPanes.tsx` | Replace the existing Federation pane copy with the collaboration and handoff workbench | \~130 | | `apps/web/src/components/orchestration/OrchestrationDrawer.tsx` | Render handoff readiness, Notice linkbacks, resume source, lineage links, and remote summary details | \~120 | | `apps/web/src/components/orchestration/OrchestrationShell.tsx` | Wire collaboration API actions, refreshes, toasts, duplicate-trigger guards, and offline/error handling | \~220 | | `apps/web/tests/orchestrationApi.test.ts` | Cover collaboration clients, parser failures, timeout/offline mapping, ids, and duplicate mutation keys | \~180 | | `apps/web/tests/commandCenterStore.test.ts` | Cover expanded handoff normalization, collaboration posture events, stale detail reset, malformed payloads, and no raw echo | \~180 | | `apps/web/tests/OrchestrationPanel.test.tsx` | Cover Federation/Handoff integration across ready, loading, offline, error, empty, and in-flight states | \~220 | | `docs/api/README_api.md` | Document collaboration, context-notice, handoff, resume-source, and remote-summary routes and payload boundaries | \~180 | | `docs/api/event-api-hook-contracts.md` | Document command-center collaboration events, Notice linkback constraints, and War Room relay separation | \~160 | | `docs/privacy-and-security.md` | Update Notice, War Room, handoff, resume, remote-access, and no-claim privacy boundaries | \~160 | | `apps/server/README_server.md` | Document server collaboration/handoff manager behavior and local-only Notice/War Room boundaries | \~100 | | `apps/web/README_web.md` | Document Federation/Handoff workbench behavior, state handling, and product-facing copy boundary | \~90 | | `apps/warroom/README_warroom.md` | Document compact posture relay limits and unchanged Worker privacy contract | \~70 | *** ## 7. Success Criteria ### Functional Requirements * [ ] Command-center handoff records include readiness, scaffold, secret-scan, validation, staleness, branch/file-state, resume-source, lineage-link, Notice-link, visibility-label, and remote-summary metadata. * [ ] Operators can post bounded review request, blocker, and completion notices from selected command-center contexts with duplicate-trigger prevention while in-flight. * [ ] Notice Board records carry safe linkbacks for tasks, approvals, conflicts, completions, handoffs, and room state without raw prompts, command bodies, transcripts, terminal output, or broad paths. * [ ] War Room relay posture surfaces local-only, room-visible, relay-unavailable, catch-up-pending, imported, external, remote-originated, and external-transfer-disabled states. * [ ] Handoff scaffold and validation flows record secret-scan, staleness, branch, file-state, resume queue source, and lineage status before a resume source is marked ready. * [ ] Remote access and tunnel state is rendered only as disabled, unavailable, summary, docs-path, or no-claim posture with no tunnel creation or sensitive control. * [ ] Federation/Handoff UI renders complete loading, empty, error, offline, unavailable, in-flight, success, and conflict states with product-facing copy only. ### Testing Requirements * [ ] Protocol tests cover collaboration labels, handoff readiness, Notice linkbacks, resume source, lineage links, remote summary, and blocked raw fields. * [ ] Server tests cover Notice request construction, handoff manager state transitions, context routes, idempotency, stale revisions, auth inheritance, WebSocket updates, and no raw echo. * [ ] War Room tests cover relay unavailable, catch-up/import provenance, compact posture counts, and blocked sensitive Worker payload fields. * [ ] Web API, store, view-model, and component tests cover collaboration snapshots, Notice posting, handoff validation, resume source, duplicate-trigger guards, malformed payloads, and offline/error states. * [ ] Runtime verification scenarios are recorded for local-only mode, Worker disconnected, catch-up pending, imported Notice, failed handoff validation, and ready resume source. ### Non-Functional Requirements * [ ] Raw prompts, command bodies, diffs, terminal output, transcripts, file contents, broad paths, tokens, provider payloads, Worker raw frames, tunnel tokens, and hosted account data are not emitted in broad route responses, WebSocket events, Worker relay posture, logs, docs, or UI rows. * [ ] Context notice and handoff mutations use idempotency keys, in-flight locks, stale-revision checks, schema validation, and explicit error mapping. * [ ] Handoff validation is deterministic and bounded; missing optional tools produce structured unavailable states instead of blocking the cockpit. * [ ] War Room relay posture never implies hosted identity, production auditability, broad collaboration safety, remote execution, or trusted erasure. * [ ] UI controls have accessible names, visible focus states, keyboard support, and stable dimensions for compact action rows. ### Quality Gates * [ ] All files ASCII-encoded * [ ] Unix LF line endings * [ ] Code follows project conventions * [ ] Primary user-facing surfaces contain product-facing copy only * [ ] Focused protocol, server, War Room, and web tests pass * [ ] Workspace typecheck passes * [ ] Root format check and lint pass *** ## 8. Implementation Notes ### Working Assumptions * Cross-package session scope: The analysis script reports the candidate package as `null`, and the stub names `apps/server`, `apps/web`, and `apps/warroom`; planning can proceed with `Package: null` because protocol, server, Worker, web, and docs must change together. * Existing handoff records are the extension point: `CommandCenterHandoff` already exists with state, target, summary, evidence, revision, and hero IDs, so this session should extend that contract instead of creating a parallel handoff surface. * The Notice Board remains canonical: existing local routes, manager persistence, and War Room relay already own Notice posting and catch-up, so context notices should build safe create requests and linkbacks rather than introducing another notice store. * Handoff scripts from `EXAMPLES/` are evidence only: the session can model scaffold, validation, staleness, and resume checklist concepts without copying historical scripts or claiming historical runtime parity. ### Conflict Resolutions * The historical guide says War Room and Remote Access share an auto-managed cloudflared tunnel, while current Phase 19 scope excludes remote tunnel creation. The chosen interpretation is summary-only remote-access posture with disabled/unavailable labels and docs paths; Orchestration does not start, stop, extend, or kick tunnel sessions. * The Notice Board local detail popup can show first-class local coordination text, while Worker relay payloads must stay bounded. The chosen interpretation is that local command-center linkbacks may appear in local details, but optional Worker relay receives only protocol-validated Notice fields and compact link labels, never raw command or transcript content. * The existing `/command-center/handoffs` route stores generic scaffold records, while the session asks for handoff manager routes and resume source flow. The chosen interpretation is to keep the generic route for compatibility and add targeted handoff scaffold, validate, and resume-source routes that update the same canonical records. ### Key Considerations * Command-center linkbacks should use target kind/id/label metadata and safe related files only; they must not embed raw record bodies. * Branch and file-state handoff checks can use existing Git/file-intent summaries and unavailable labels rather than reading broad file contents. * Secret-scan status should be represented as pass, failed, unavailable, or stale metadata with evidence links, not raw scanner output. * Imported and remote-originated records should carry provenance labels that are useful locally but not identity claims. * Catch-up pending should remain a state label and should not imply every remote event has been replayed or persisted locally. ### Potential Challenges * Extending shared Notice payloads can drift older compatibility aliases: keep canonical fields optional and preserve `body`, `targets`, and existing War Room relay behavior. * Handoff readiness can become too broad: keep it to scaffold, secret scan, validation, staleness, branch/file state, resume source, and lineage links for this session. * War Room disconnected and local-only states can look like failures: model them as explicit expected posture states, not errors, unless a requested relay action fails. * Linked records may disappear after refresh: reset or revalidate selected details on event hydration and show compact unavailable states. * Remote-origin labels can overclaim identity: use provenance labels and participant IDs only as room metadata, not account proof. ### Relevant Considerations * \[P03] **Real executors remain unimplemented by design**: Notice and handoff actions coordinate and validate; they do not execute local, remote, Worker, or hosted commands. * \[P03-packages/protocol] **Protocol leads cross-package work**: Extend shared contracts before server, Worker, and web consumers change behavior. * \[P03-apps/server] **Local server boundary must stay conservative**: New routes inherit auth, CORS, rate limits, body caps, validation, compact errors, and explicit unavailable behavior. * \[P07] **Redaction is boundary-specific**: Notice linkbacks, handoff records, Worker relay, remote summary, docs, logs, and UI rows each need separate minimization. * \[P06-apps/warroom+apps/web] **War Room federation is optional and redacted**: Room-visible orchestration state must not imply hosted identity, production auditability, broad collaboration safety, or trusted erasure. * \[P07] **Hosted services ship as disabled-default guardrails only**: Remote access, tunnels, push, hosted identity, and hosted storage remain disabled/unavailable without separate consent, authorization, abuse controls, tests, and docs. * \[P17] **Notice Board parity is a shared contract**: Notice shape, route handling, WebSocket events, and War Room relay must move together. * \[P18-apps/web] **Pure normalization before store mutation**: Normalize collaboration and handoff payloads before updating Zustand. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Context Notice actions could duplicate posts without in-flight and idempotency protection. * Handoff readiness could mark stale or unsafe resume state as ready without revalidation on re-entry. * Worker relay posture could expose raw remote payloads or imply hosted identity if not filtered at protocol and bridge boundaries. * Federation UI could blank during local-only, disconnected, catch-up pending, malformed, or offline states. * Linked record updates could leave stale drawer state after WebSocket hydration or route refresh. *** ## 9. Testing Strategy ### Unit Tests * Protocol parser tests for collaboration labels, Notice command-center links, handoff readiness, resume source, lineage links, remote-access summary, event entries, and blocked raw fields. * Server helper tests for safe Notice request construction, linkback validation, visibility label derivation, remote summary derivation, and sensitive field rejection. * Server handoff manager tests for scaffold creation, validation transitions, secret-scan status, staleness, branch/file-state checks, resume-source generation, lineage links, and idempotency. * Web helper tests for handoff readiness labels, remote posture copy, Notice action availability, fallback ordering, and malformed payload rejection. ### Integration Tests * REST route tests for context notice posting, handoff scaffold, handoff validation, resume source, collaboration posture snapshots, stale revisions, duplicate triggers, auth inheritance, and WebSocket event emission. * War Room bridge and Worker relay tests for local-only no-op, relay unavailable, catch-up pending, imported Notice provenance, remote-originated labels, external-transfer-disabled labels, and blocked raw fields. * Web API, store, and component tests for route clients, in-flight mutation keys, expanded handoff normalization, Federation/Handoff pane rendering, drawer details, offline/error states, and product-facing copy. ### Runtime Verification * Open Orchestration in local-only mode and confirm Federation/Handoff shows local-only posture and no hosted or remote claims. * Simulate Worker disconnected relay and confirm relay-unavailable posture plus local Notice posting still works. * Ingest a safe remote Notice/catch-up frame and confirm imported/remote-originated labels plus bounded linkbacks. * Create a handoff scaffold with failing validation or stale branch/file state and confirm resume source stays unavailable. * Create a validated handoff with safe lineage and resume metadata and confirm the web pane shows ready resume source and linked records. ### Edge Cases * Missing Worker URL * Worker disconnected during Notice post * Duplicate Notice post idempotency key * Wrong-room remote Notice * Catch-up frame with duplicate notices * Handoff validation missing secret-scan evidence * Stale branch/file-state check * Resume source referencing a missing queue task * Lineage source hero dismissed or missing * Malformed command-center link metadata * Offline web client while action is in flight *** ## 10. Dependencies ### Other Sessions * Depends on: `phase19-session04-campaign-workbench`, `phase19-session05-attention-and-permissions`, `phase19-session08-file-and-git`, `phase19-session09-heroes-and-lineage`, `phase19-session10-mission-artifacts`, `phase19-session12-terminal-and-containers` * Depended by: `phase19-session14-channels-and-scope`, `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-session13-collaboration-and-handoff/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.