> 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/packages/protocol/readme_protocol.md).

# Protocol Package

Shared TypeScript contracts for FactionOS REST, WebSocket, missions, heroes, plans, notices, achievements, scrolls, factions, War Room state, and local orchestration state.

## Local Commands

```bash
npm --workspace packages/protocol run typecheck
```

## Layout

* `src/events.ts` is the main server-event union.
* `src/ingest.ts` owns the `/event` hook and OpenClaw compatibility ingest vocabulary.
* `src/orchestrationCommandCenter.ts` owns the command-center contracts for campaigns, tasks, attention, executors, permissions, file intents, workpads, evidence, verification, handoffs, diagnostics, channels, usage, and compact update events.
* `src/taskQueue.ts` and `src/agentTemplates.ts` own Phase 20 executable queue payloads, compact execution summaries, source metadata, and source-owned executable template defaults.
* `src/orchestration.ts`, `src/guardedActions.ts`, and `src/lineage.ts` own the Phase 03 local orchestration contracts.
* `src/heroes.ts`, `src/missions.ts`, and `src/plans.ts` define core runtime models.
* `src/factions.ts`, `src/achievements.ts`, `src/notices.ts`, `src/scrolls.ts`, and `src/warroom.ts` define supporting product surfaces.
* `tests/` covers exported contracts and compatibility behavior.

Update protocol types before wiring matching server or web behavior. Ingest changes should start in `src/ingest.ts`, then move outward to server handling, hook fixtures, and docs.

## Phase 18 Quest Board Suggestion Ownership

`src/suggestions.ts` is the shared source of truth for Quest Board suggestion contracts. It owns idle suggestions, codebase issues, session summaries with follow-up tasks, on-demand analysis results, project scan results, scan status, summary counts, dismissed-ID caps, freshness windows, bounded validation helpers, and REST request/response shapes before server or web packages consume them.

The canonical realtime event is `suggestion_update`, which carries the full typed snapshot. The existing `idle_suggestion` event remains a frozen string-only compatibility emission for older clients. The historical `quest_board` event is retired: it was defined but unwired, remains exported only as a deprecated migration reference, and is not part of the active `ServerEvent` union.

Server and web consumers must import these contracts instead of duplicating Quest Board vocabularies, caps, freshness windows, or REST shapes. Shipped REST aliases use both root and `/api` paths for `/suggestions/summary`, `/suggestions/scan`, `/suggestions/scan/status`, `/suggestions/analyze`, `/suggestions/analyze/status`, `/suggestions/project-scan`, `/suggestions/project-scan/status`, `/suggestions/:suggestionId/accept`, `/suggestions/:suggestionId/dismiss`, and `/issues/:issueId/dismiss`. External issue accept, task-queue executor routing, telemetry, and entitlement gate responses are not protocol contracts in this phase.

These contracts stay local-first. They do not imply hosted identity, entitlement gating, suggestion telemetry, analytics capture, trusted erasure, remote executors, issue accept-as-quest behavior, or production-hosted validation. File-path fields accept repo-relative paths only, and helpers reject absolute paths, traversal segments, URL-like values, backslashes, empty segments, and NUL bytes before payloads cross package boundaries. Consumers should expose compact validation and conflict errors, not raw prompts, file contents, command output, tokens, provider payloads, or broad absolute paths.

## Phase 09 Provider-Neutral Codex Baseline

Phase 09 Sessions 01-03 complete the provider-neutral CLI and hook foundation owned by this package before hooks, server ingest, CLI installers, or web labels consume it. `src/heroes.ts` owns the shared `HeroCli` values, including `codex-cli`, and the CLI display metadata helpers. Downstream packages should import those helpers instead of duplicating provider labels.

`src/ingest.ts` owns provider-neutral hook event names through `AGENT_HOOK_EVENT_NAMES`. The deprecated `CLAUDE_HOOK_EVENT_NAMES` export is a compatibility alias for existing imports and must not become a separate copied array. Codex lifecycle names are type-level contract vocabulary here only: `SubagentStart`, `PreCompact`, and `PostCompact`.

Codex-safe ingest metadata is limited to compact optional fields such as turn ids, permission mode labels, hook event names, agent ids and types, tool names, and MCP tool names. Raw prompts, transcript paths or contents, patch bodies, command output, MCP argument bodies, token-like values, provider credentials, and broad absolute paths must stay local to handler normalization unless a later scoped session adds explicit validation, redaction, tests, and docs.

This baseline does not install Codex CLI hooks, validate Codex runtime behavior, change server ingest behavior, activate hosted transfer, or claim custom slash command support. Later hook, server, CLI, and web sessions should consume these contracts first and keep their runtime claims scoped to the exact behavior they implement.

## Phase 05 War Room Ownership

Protocol owns shared War Room contracts before `apps/warroom` or `apps/web` consume them. Phase 05 implementation should add or harden room, participant, REST, WebSocket, error, lifecycle, authority, and redaction shapes here first, then wire Worker and web behavior against those exported contracts.

Current War Room types are a starting point, not a complete hardened contract. The baseline lifecycle states are local-only, unavailable, create, join, pending, approved, rejected, connected, reconnecting, caught-up, disconnected, and left. The Worker payload allowlist must block prompts, file contents, command bodies, terminal output, transcripts, secrets, broad paths, exports, replay buffers, media drafts, scan payloads, and local diagnostics before those events can cross the Worker boundary.

Session 02 hardens this package as the source of truth for the Worker client contract. `src/warroom.ts` owns room code validation, participant roles, bounded room snapshots, create/join/approve/reject request shapes, deterministic error envelopes, rate-limit envelopes, socket handshake frames, catch-up frames, and safe client frame validation. `apps/warroom` should import these contracts instead of redefining Worker payload shapes.

The safe Worker socket scope is protocol-owned and allowlisted. Current safe client frames are limited to `ping`, `warroom_presence`, `warroom_cursor`, `warroom_focus`, `warroom_hero_state`, `warroom_mission_state`, and `warroom_room_notice`. `ping` is not persisted. Redacted federation frames are bounded and must reject unknown fields, invalid enum values, non-finite coordinates, blocked nested keys, and path, URL, token, or secret-like string values. Prompts, command bodies, terminal output, file contents, transcripts, secrets, broad paths, exports, replay buffers, media drafts, scan payloads, diagnostics, or logs must be rejected or dropped before persistence, catch-up, diagnostics, or browser consumption.

Session 03 keeps collaboration event validation in this package. Worker and web consumers should use `parseWarRoomSocketFrame`, `parseWarRoomRecentEvent`, `parseWarRoomCatchupFrame`, `filterSafeWarRoomRecentEvents`, `warRoomFederationFamilyLabel`, and `summarizeWarRoomRecentEvents` instead of redefining safe-frame, recent-event, catch-up, or summary behavior. Catch-up summaries expose only counts, timestamps, and safe family labels, never raw target ids, prompts, file paths, commands, terminal output, exports, replay buffers, diagnostics, media drafts, logs, or settings values.

## Phase 06 Collaboration And Isolation Ownership

Phase 06 Session 01 records source-backed ownership in `.spec_system/archive/phases/phase_06/phase06_requirement_routing_matrix.md`. Protocol remains the first package for shared room authority, participant proof limits, role vocabulary, collaboration events, blocked-field categories, unavailable execution envelopes, isolation posture, and diagnostic shapes before Worker, web, server, CLI, or hook packages consume them.

Phase 06 Session 02 adds the shared non-hosted War Room authority contract. `src/warroom.ts` owns the authority envelope, authority token bounds, room revision, expected revision, idempotency key, expiration, and deterministic authority error vocabulary. Worker and web packages must import these shapes instead of redefining authority payloads. Authority can prove possession of a Worker-issued room-local opaque token for one participant in one room; it is not hosted account identity, SSO, organization membership, public collaboration safety, or trusted erasure proof.

Authority-bearing APIs use compact error codes for missing, invalid, expired, mismatched, stale revision, and replayed authority inputs. Error envelopes must not echo raw authority tokens, request bodies, URLs, account ids, paths, prompts, command output, exports, replay buffers, diagnostics, or logs. Participant display names, colors, roles, and online flags remain display metadata and must not be described as account-backed proof.

Later protocol changes must preserve optional Worker transfer, local-only fallback, sender-aware events, bounded catch-up, remote-context separation, compact errors, and explicit deferrals for hosted identity, hosted storage, analytics, public replay hosting, real file/git/terminal/Docker/remote/hosted executors, production-hosted validation, mobile certification, and trusted erasure.

Session 05 adds `src/isolation.ts` as the shared source of truth for local isolation posture. It owns executor family labels, unavailable reasons, future-control requirements, redaction categories, recovery limits, and compact diagnostic summary shapes before server, CLI, hook, or web surfaces display them. These contracts describe unavailable and non-executing posture only; they do not imply that file, git, terminal, container, remote, Worker, or hosted executors exist.

Consumers must keep isolation diagnostics compact. Safe isolation output is limited to family labels, status labels, bounded counts, timestamps, docs paths, and explicit recovery limits. Prompts, command bodies, terminal output, file contents, broad paths, transcripts, tokens, raw queue entries, proposal rationale, raw spool payloads, state files, logs, backups, archives, browser state, Worker payloads, and hosted account data remain blocked categories.

Phase 06 closeout confirms this package as the completed shared-contract owner for the shipped subset: room-local authority, safe collaboration frames, bounded catch-up summaries, redaction categories, local isolation diagnostics, unsupported-route envelopes, and guarded-action unavailable results. Future changes should stay protocol-first before Worker, web, server, CLI, or hook consumers change behavior. Hosted identity, hosted storage, analytics, public replay hosting, real file/git/terminal/Docker/remote/hosted executors, production-hosted validation, certification, and trusted erasure remain outside the Phase 06 protocol closeout.

Phase 08 adds protocol-owned release vocabulary for erasure, hosted guardrails, media release gates, and no-overclaim states. Session 08 records passing focused protocol checks as local source-level evidence only. Protocol contracts must still describe deployed-hosted validation, formal certification, hosted identity, broad media readiness, real executors, and full trusted unified erasure as unavailable/no-claim unless a later release record proves the exact claim.

## Phase 07 Hosted Contract Ownership

Phase 07 Session 01 defines documentation-only hosted-service guardrails. Session 02 adds `src/hostedConfig.ts` as the shared source of truth for hosted configuration categories, exposure labels, status labels, docs paths, variable metadata, public URL normalization, browser-blocked mirrors, diagnostic entry shapes, and summary counts. Server and web packages should consume this module through the package barrel instead of duplicating category strings.

Hosted config contracts keep public-client values separate from server-only secrets, deploy-only credentials, reserved future placeholders, and blocked browser mirrors. Diagnostics are status-only and must not carry raw env values. Session 03 adds `src/hostedIdentity.ts` as the shared source of truth for hosted identity planned/unavailable status, lifecycle requirements, authorization surfaces, role requirements, audit requirements, docs paths, unsupported account claims, non-overclaim labels, and compact summary counts. Server and web consumers should import this module through the package barrel instead of redefining identity, SSO, organization, analytics-consent, production-audit, or trusted-erasure labels.

Hosted identity contracts describe guardrails only. They do not imply OAuth, SSO, organization management, billing, Supabase auth, account UI, hosted storage authorization, analytics consent, public replay hosting, push, remote access, production audit proof, or trusted erasure. Future protocol contracts for storage, public replay, analytics, push, remote access, diagnostics upload, unsupported states, redaction, or errors must still start here before server, web, Worker, CLI, hooks, or adapters consume them.

Session 04 adds `src/hostedPersistence.ts` as the shared source of truth for hosted persistence and public replay posture. It owns planned/unavailable status labels, data eligibility decisions, future storage requirements, public replay requirements, blocked payload labels, docs paths, unsupported claim labels, compact summary counts, and pure helper functions. Server and web consumers should import this module through the package barrel instead of duplicating storage, replay, deletion, takedown, or erasure strings.

Hosted persistence contracts describe guardrails only. They do not imply Supabase readiness, database schemas, storage buckets, migrations, browser direct storage writes, account-backed persistence, hosted replay uploads, public replay pages, takedown runtime, release-grade deletion, production-hosted validation, or trusted erasure. Future storage and public replay consumers must add server mediation by default for sensitive data, authorization or RLS tests, schema artifacts where applicable, consent, retention, export, deletion, expiration, takedown, no-index posture, abuse controls, failure states, tests, and docs before runtime activation.

Session 05 adds `src/hostedAnalytics.ts` as the shared source of truth for hosted analytics guardrails. It owns provider labels, planned/disabled/ unavailable/consent-required/ready/opted-out status labels, consent state and requirement labels, approved event taxonomy, allowed payload fields, blocked payload labels, docs paths, unsupported claim labels, provider metadata, and compact summary counts. Web and future server or diagnostics consumers should import this module through the package barrel instead of redefining analytics provider, consent, payload, dashboard, recorder, replay, or erasure strings.

Hosted analytics contracts describe the approved optional runtime boundary. They allow the web client to send minimized approved events to Umami when public config and consent are ready. They do not imply tracking scripts, beacons, SDK imports, server-side ingestion, analytics dashboards, recorder, heatmaps, session replay, console-log capture, account-backed consent storage, production-hosted validation, or trusted erasure. Analytics consumers must keep analytics disabled by default, require config and consent together, honor opt-out, allowlist payload fields, drop blocked categories, add tests, and keep local-only fallback visible before new events or providers are added. Local Umami setup and verification evidence lives in `../../docs/runbooks/local-umami-analytics.md`; the protocol source remains the authority for approved event names, allowed payload fields, and blocked labels.

Session 06 adds `src/hostedOperations.ts` as the shared source of truth for push, Web Push, VAPID, remote access, Cloudflare Tunnel, and operator diagnostic guardrails. It owns planned/disabled/unavailable/local-only status labels, operation surface labels, future requirement labels, blocked payload labels, docs paths, unsupported claim labels, compact booleans, and summary counts. Server, CLI, web, and future consumers should import this module through the package barrel instead of redefining push, tunnel, remote access, diagnostic-agent, production-validation, or erasure strings.

Hosted operation contracts describe guardrails only. They do not imply push delivery, push subscription storage, VAPID private key browser exposure, Cloudflare Tunnel, remote access, remote executors, hosted diagnostic agents, production-hosted validation, or trusted erasure. Future consumers must keep browser notifications local-only, fetch operator diagnostics from loopback only, block raw subscriptions, VAPID private keys, Cloudflare ids, zone ids, tunnel tokens, prompts, commands, paths, room payloads, logs, backups, exports, archives, and replay buffers, and add tests and docs before runtime activation.

Blocked payload categories must stay out of hosted storage, analytics, public replay, push, diagnostics, remote access, Worker transfer, adapters, exports, archives, logs, and backups unless a scoped session adds explicit validation, minimization, redaction, authorization, tests, and docs.

Phase 07 Session 07 closeout validated this contract ownership: the shared hosted config, identity, persistence, analytics, and operations contracts are the single source consumers depend on, and protocol contract tests plus the full suite (2186 passed / 1 skipped) confirm they expose planned/disabled/unavailable posture and bounded summaries only. The package adds no active hosted runtime; activation remains later scoped-session work.

Phase 08 Session 01 routes future release-sensitive protocol work through `.spec_system/archive/phases/phase_08/phase08_requirement_routing_matrix.md` and `.spec_system/archive/phases/phase_08/release_requirements_risk_baseline.md`. Shared trusted-erasure vocabulary must start here in Session 02 before server, web, CLI, Worker, or docs claim erasure behavior. Hosted identity, hosted storage, analytics, public replay, push, remote access, production-hosted validation, certification, media promotion, and decommission claims remain no-claim or owner-gated unless the Phase 08 release-candidate record or a later scoped release record proves the specific claim.

## Phase 08 Erasure Contract Ownership

Session 02 adds `src/erasure.ts` as the shared source of truth for erasure inventory vocabulary. It owns boundary ids, boundary families, owner labels, status labels, authority labels, dry-run labels, confirmation labels, partial-failure labels, audit labels, verification labels, blocked payload categories, unsupported claim labels, negative-claim helpers, inventory rows, deterministic summary builders, and guard functions.

Consumers must import erasure data through the package barrel before adding server, Worker, web, CLI, hook, or docs behavior. Do not duplicate boundary ids or blocked payload labels in package-local code. Server and Worker helpers may derive read-only summaries from protocol rows, but runtime deletion, purge, clear, reset, Worker room deletion, hosted account deletion, public replay takedown, and end-user trusted-erasure controls remain Session 03, Session 04, or later scoped work.

Blocked erasure payload categories include prompts, transcripts, file and code contents, command bodies, terminal output, secrets, credentials, authority tokens, authority hashes, local paths, raw env dumps, replay buffers, export bodies, archive bodies, backup payloads, diagnostics, logs, scans, memory finding text, spool payloads, room payloads, participant secrets, idempotency response bodies, browser storage values, workspace file contents, hosted or cloud account ids, analytics payloads, push subscriptions, media drafts, and quarantined historical content. Safe summaries expose labels, counts, booleans, docs paths, status values, timestamps, and synthetic identifiers only.

Negative-claim helpers intentionally return `trustedUnifiedErasure: false` for browser reset, Worker leave, diagnostics recovery, CLI uninstall, manual file removal, local archive cleanup, valid spool cleanup, and one-boundary cleanup. Those flows cannot become trusted unified erasure until every release-scoped local, browser, Worker, workspace, backup, export, archive, diagnostic, log, spool, runtime memory, and hosted-placeholder boundary has deletion, dry-run, audit, partial-failure, idempotency, and verification evidence.

## Phase 17 Notice Board Ownership

Phase 17 Session 01 adds `src/notices.ts` as the shared source of truth for the canonical Notice Board model before server, web, CLI, hooks, or Worker sessions consume it. Protocol owns the notice type, priority, author type, severity, REST request/response, WebSocket event, compatibility alias, and pure helper contracts for the recovered Notice Board route family.

Downstream packages should import `Notice`, `NoticeBoardNotice`, `NoticeBoardCreateRequest`, `NoticeBoardListResponse`, `NoticeBoardResolveRequest`, `NoticeCompatibilityCreateRequest`, `deriveNoticeSeverity`, and the `normalizeNotice*` helpers instead of duplicating Notice Board vocabularies or ad hoc target/file parsing.

Compatibility aliases remain intentional during the migration: `body` mirrors `content`, `targets` mirrors `targetSessionIds`, `postedAt` mirrors `createdAt`, and `severity` remains a UI tint derived from canonical `type` and `priority`. WebSocket frames support canonical `notice` keys and recovered `message` compatibility keys.

Notice Board contracts describe explicit coordination messages only. They do not permit raw prompts, transcripts, terminal output, command bodies, file contents, secrets, absolute local paths, logs, exports, replay buffers, scans, media drafts, diagnostics, backups, or quarantined historical content to cross REST, WebSocket, Worker, CLI, hook, replay, export, log, or diagnostic boundaries. They also do not imply hosted identity, hosted storage, public collaboration safety, production auditability, real executors, or trusted erasure.

## Phase 19 Command Center Ownership

Phase 19 Session 01 adds `src/orchestrationCommandCenter.ts` as the shared source of truth for the command-center contract surface before server managers, web stores, WebSocket reducers, panels, routes, or executors consume it. The module owns campaign, task, attention, permission, executor capability, hero lifecycle command, execution run, file intent, workpad, evidence, verification attempt, review gate, handoff, diagnostic, channel command, scope, usage metric, notification readiness, compact error, blocked payload, REST alias, and WebSocket update shapes.

Session 15 extends the same module with enriched usage metric and notification readiness vocabularies. Protocol owns usage metric families and kinds, metric rollup targets, usage units, notification channels, routing categories, payload categories, readiness requirements, subscription statuses, browser permission labels, and safe subscription summary shapes. It also owns the compact event fields used when usage metrics and notification readiness are emitted together in `command_center_usage_update`.

Session 16 command-center ergonomics do not add protocol DTOs. The browser shortcut helpers and adjacent-surface rows derive from existing command-center families, target refs, capability states, permission/attention decision records, queue states, terminal/container snapshots, collaboration posture, channels, and usage metrics. `O` sequence shortcut labels, selected-row safety, and cross-link rows are web-owned presentation contracts; server and protocol packages still own only the bounded local REST and WebSocket shapes. Remote Access remains no-claim metadata unless a later protocol session adds a scoped remote-access contract with authorization, redaction, tests, and docs. App desktop/mobile evidence for the web behavior is `tests/e2e/orchestration-command-center.e2e.ts`.

Downstream packages should import these contracts from `@factionos/protocol`. Do not duplicate command-center state names, capability statuses, blocked payload categories, pagination filters, route aliases, or compact event payloads in server, web, Worker, CLI, hook, or adapter packages. Server and web sessions may derive manager state, route handlers, and reducers from these types, but runtime behavior belongs to the scoped server and web sessions that prove each family with implementation, tests, and docs.

Capability states are explicit: unavailable, observe-only, proposal-only, approved-not-executing, executor-ready, executing, executed, and failed. An approval does not imply execution unless the concrete family is executor-ready and the later runtime session adds validation, permission enforcement, idempotency, audit fields, output caps, tests, and docs. Future file, git, terminal, container, remote, Worker, channel, provider, and hosted families must keep unavailable or proposal-only states until their scoped session proves the exact behavior.

Broad command-center REST and WebSocket payloads are compact. They may expose safe IDs, state labels, capability labels, counts, timestamps, bounded summaries, safe repo-relative paths, evidence IDs, and blocked category labels. They must not expose raw prompts, command bodies, diffs, terminal output, file contents, transcript text, provider payloads, tokens, secrets, broad absolute paths, hosted account data, raw logs, replay buffers, or export payloads. Detailed local-only content requires a later scoped detail route with explicit validation and redaction.

Usage metrics and notification readiness follow the same boundary. They may carry bounded provider names, source ids, token counts, cost estimates, line estimates, readiness labels, consent booleans, VAPID configured booleans, endpoint hashes, and key lengths. They must not carry raw provider requests or responses, prompts, transcripts, terminal output, file contents, diffs, raw push endpoints, push keys, VAPID private keys, hosted analytics payloads, or absolute local paths. Readiness and consent labels do not prove active hosted Web Push delivery.

The actual Phase 19 module layout is one dependency-free TypeScript file: `src/orchestrationCommandCenter.ts`. `src/events.ts` includes the compact `CommandCenterServerEvent` union in `ServerEvent`, and `src/rest.ts` exposes typed command-center list, mutation, capability, request, and response aliases for planned route families. This package does not implement persistence, server routes, WebSocket emitters, React UI, hosted transfer, real executors, or production validation.

## Phase 20 Command Center Actionability Ownership

Phase 20 keeps protocol as the first contract owner for local orchestration actionability. `src/taskQueue.ts`, `src/orchestrationCommandCenter.ts`, `src/agentTemplates.ts`, `src/events.ts`, and `src/rest.ts` define the public queue, campaign, execution, capability, template, channel, WebSocket, and REST shapes before server managers or web reducers consume them.

Release-scoped local execution claims are family-specific:

| Family or path                     | Protocol-owned shipped boundary                                                                                                                                                      | Remaining no-claim boundary                                                                                                                                                                     |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Terminal queue and campaign work   | Terminal executable queue payloads, queue-targeted execution summaries, terminal execution-run attachments, `pty_unavailable`, timeout, kill, retry, and scoped terminal detail ids. | No hosted terminal, remote shell, Worker command bridge, or broad terminal output event claim.                                                                                                  |
| Git queue and campaign work        | Bounded Git status, stage, and unstage executable payloads, compact Git result counts, policy-blocked push unavailable state, and queue/campaign execution links.                    | Git push, arbitrary Git commands, raw Git output, diffs, patch bodies, broad path lists, and remote repository mutation remain no-claim.                                                        |
| File mutation and file execution   | File mutation request/result contracts, queue/campaign/guarded file summaries, backup ids, rollback states, stale/conflict labels, and repo-relative path labels.                    | Broad workspace-file deletion, raw file contents, raw patches, absolute paths, hosted storage mutation, and trusted erasure remain no-claim.                                                    |
| Campaign dispatch and DAG recovery | Campaign task execution readiness, compact execution summaries, dependency ids, blocked/unavailable reasons, retryable flags, and deterministic state labels.                        | Metadata-only, proposal-only, preview-only, planning-only, or unavailable tasks cannot complete campaign execution claims.                                                                      |
| Managed hero lifecycle             | Managed local process or PTY action vocabulary, supported action lists, readiness labels, execution ids, and compact lifecycle result summaries.                                     | Observed Claude Code or Codex CLI sessions, provider model changes, provider permission changes, and isolation mutation remain unavailable or record-only.                                      |
| Container dispatch                 | Bounded local isolated-spawn payloads, runtime labels, container run ids, cleanup posture, unavailable reasons, and compact queue/campaign execution summaries.                      | Arbitrary Docker commands, builds, mounts, remote images, host internals, raw Docker output, hosted containers, and Worker/container bridges remain no-claim.                                   |
| Templates and channel intake       | Source-owned executable template defaults, channel command metadata, replay metadata, local approval state, executable draft refs, and local queue conversion ids.                   | Generic webhook or chat command auto-execution, raw webhook bodies, remote approval, untrusted executable claims, provider payloads, and hosted channel trust remain proposal-only or no-claim. |

Broad Phase 20 protocol events remain compact. `command_center_execution_update`, `command_center_executor_update`, `command_center_channel_command_update`, `task_queue_update`, and `agent_template_update` may expose ids, families, kinds, states, safe labels, counts, timestamps, compact result summaries, blocked category labels, scoped detail ids, and docs paths only. They must not carry raw command text, command output, Git output, diffs, file contents, patch bodies, tokens, secrets, provider payloads, raw webhook bodies, broad absolute paths, raw Docker output, transcripts, replay buffers, export payloads, or hosted account data.

Phase 20 protocol tests now own release regressions for executable queue summaries and command-center update privacy in `tests/orchestration.test.ts` and `tests/orchestrationCommandCenter.test.ts`. Server, web, and browser tests must consume these contracts rather than redefining safe event subsets.

The protocol package still does not implement runtime execution. It only defines the shared public contract. Server managers own execution, idempotency, retries, state transitions, diagnostics, exports, and route authorization; web owns product-facing labels and duplicate-trigger guards; `tests/e2e/orchestration-command-center.e2e.ts` owns local browser evidence. Hosted identity, hosted storage, public replay hosting, production-hosted Command Center validation, remote access, Worker command bridges, trusted unified erasure, and legal/privacy approval remain no-claim until a later source-backed release record proves each claim.

## WebSocket Ownership

`src/events.ts` owns both server event frames and client-to-server message shapes. The currently shipped local WebSocket hydration order is:

1. `connected`
2. `roster_update`
3. `mission_state`
4. `notice_board_hydrate`
5. `scroll_state`
6. `achievement_state`
7. `task_queue_update`
8. `agent_template_update`
9. `mission_graph_update`
10. `guarded_action_update`

The currently supported client-message vocabulary is `hello`, `ping`, `permission_response`, `plan_approval`, `guarded_action_decision`, `post_notice`, `collect_scroll`, and `hero_state_override`. Add or change these protocol shapes before updating the server WebSocket validator or the web client sender.

## Phase 01 Runtime Coverage

Phase 01 keeps `packages/protocol` as the source of truth for shipped event and client-message shapes. The local server, web client, hooks, and docs now test the current `/event` compatibility subset, WebSocket hydration order, client message vocabulary, REST validation envelopes, and unsupported-route status. Historical event inventories under ignored `EXAMPLES/` remain traceability evidence until a future phase deliberately implements, rejects, or decommissions each remaining item.

## Phase 03 Orchestration Ownership

Phase 03 shipped the local-first subset of shared orchestration contracts from this package before server, hook, CLI, and web consumers used them. The shipped subset covers task queue and agent template REST shapes, compact queue/template WebSocket frames, typed subagent lineage and mission graph state, and guarded local action proposal, decision, result, unavailable, and failure shapes.

Contracts here do not imply hosted queues, remote workers, Docker/container execution, inbound chat commands, or War Room federation. Those remain separate or deferred surfaces until a later PRD adds matching runtime producers, authorization, redaction, tests, and stable docs.

## Phase 04 Media Catalog Boundary

Phase 04 Session 02 adds shared media catalog contracts from `@factionos/protocol` through `src/mediaCatalog.ts`. Runtime packages should import the shared vocabulary, record shape, validators, validation issue codes, and release-ready helpers from the package barrel instead of redefining media status or category strings.

The protocol package owns only the shared contract. App runtime assets stay in the app package that loads them, public demo copies stay standalone, and cross-surface references stay under `assets/` or stable docs. Public demo paths may be cataloged as repository-relative records, but `public-demo/` must not import workspace TypeScript.

New runtime media references should be catalog-first: add a typed record with source, rights, attribution state, optimized output metadata, byte size, dimensions or duration, browser support, fallback, accessibility, privacy, and release-gate notes before app, docs, demo, or tooling code depends on the file. Approved records must have no release blockers. Unknown, planned, prototype-only, rejected, deferred, needs-attribution, needs-replacement, or conditional records must carry explicit blocker context.

Protocol media records must not imply hosted storage, analytics transfer, public replay hosting, provider upload, or direct promotion from `EXAMPLES/`. Historical evidence can be cited only as non-release traceability.


---

# 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/packages/protocol/readme_protocol.md?ask=<question>&goal=<endgoal>
```

`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.