> 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/docs/api/readme_api.md). # API Reference This is the concise stable reference for the shipped API surface. See [`event-api-hook-contracts.md`](/faction-os-docs/docs/api/event-api-hook-contracts.md) for the detailed source-backed API, event, WebSocket, protocol, hook, historical-source, and Phase 01 hardening contract. Historical inventories in ignored `EXAMPLES/findings/` remain temporary local traceability inputs until release decommission gates close. ## Local Server Default base URL: `http://127.0.0.1:2468` Default WebSocket URL: `ws://127.0.0.1:2468/` Current security note: the local server binds to loopback by default, refuses non-loopback binds without explicit opt-in, restricts default CORS/WebSocket origins to local Vite dev origins, and enforces HTTP/WebSocket bearer auth on read, write, and unsupported catch-all routes when `FACTIONOS_AUTH_TOKEN` is set. Runtime schemas now cover the high-risk current local POST routes listed below, WebSocket client messages, and session export options. Session exports and local session archives apply deterministic redaction for prompts, paths, commands, token-like values, URLs, terminal identifiers, and transcript text where those values cross the export/archive boundary. Archives, browser replay, and exports remain local-first audit artifacts, not hosted-safe or share-safe payloads. Command-center collaboration and handoff routes are local scaffolds for coordination, review requests, completion notices, readiness checks, resume source labels, and War Room relay posture summaries. They do not create remote access, claim a tunnel, run Worker commands, or store raw prompts, command bodies, terminal output, transcripts, diffs, file contents, tokens, logs, or export payloads. Command-center metrics and notifications are local operational posture. Usage metrics aggregate bounded counts, age buckets, provider usage summaries, token and cost estimates, line estimates, executor utilization, and notification readiness labels. Notification routes store local preferences, consent, safe subscription summaries, and readiness gates only. They do not store raw provider payloads, prompts, transcripts, terminal output, push endpoints, VAPID private keys, or hosted analytics payloads, and they do not imply active hosted Web Push delivery without configured consent, VAPID, subscription, and server delivery evidence. Local channel and webhook intake routes are proposal-first scaffolds for operator review. They accept bounded GitHub or generic webhook metadata, record channel command rows with replay metadata and scope labels, and may convert the row into a queue entry, attention item, or guarded channel proposal. They inherit local auth, rate limits, and body caps, reject raw headers, cookies, auth material, raw request bodies, raw payloads, and secret fields, and never execute trusted remote commands. Phase 20 local Command Center execution claims are limited to evidence-backed local families: terminal queue dispatch through the PTY gate, Git status/stage or unstage, file mutation and rollback through `FileMutationManager`, bounded container isolated-spawn dispatch when runtime and image gates pass, campaign dispatch that routes those families through queue entries, guarded approvals for registered local executors, source-owned template queue creation, and owned managed-session stop/restart/message actions. Optional runtime absence must return `unavailable` evidence rather than hidden execution; Git push, generic webhook/chat auto-execution, hosted/Worker command bridges, remote access, arbitrary Docker commands, provider model/permission/isolation mutation, production-hosted Command Center validation, hosted identity, hosted storage/public replay, and trusted unified erasure remain no-claim, proposal-only, approved-not-executing, policy-blocked, or unsupported until a later source-backed release record promotes them. ## Hosted Route Families Phase 07 Session 01 defines hosted-service guardrails but does not add hosted API behavior. Current local server and Worker routes remain the only shipped API surfaces documented below. Future hosted configuration, identity, storage, public replay, analytics, push, remote access, and diagnostic routes must add protocol contracts, validation, auth or authorization, redaction, disabled or unsupported states, tests, and docs before they can be listed as shipped. Server-only secrets and deploy-only credentials must not be exposed through browser config, health responses, diagnostics, error envelopes, WebSocket frames, replay fragments, exports, archives, logs, or docs examples. Future hosted errors should use compact stable codes and safe messages only. `GET /diagnostics/runtime` is a local size and throughput route. It inherits the local auth boundary and returns compact counts for heroes, missions, tool uses, connected clients, and recent event throughput only. It never returns raw prompts, paths, commands, exports, replay buffers, logs, WebSocket frames, or session payloads. `GET /diagnostics/provider-readiness` is a local provider, setup, and orchestration-readiness route. It inherits the local auth boundary and returns provider status labels, hook/model availability labels, setup command/env-name labels, runtime health counts, safe recovery descriptors, and docs paths only. It never calls cloud providers and never returns raw env values, provider payloads, prompts, command output, logs, transcripts, local absolute paths, or tokens. `POST /diagnostics/orchestration/recover` accepts only `cleanup_stale_listener_pids` and `cleanup_malformed_spool_entries` with an idempotency key. It deletes only stale listener PID files or malformed local spool JSON entries and reports compact action counts. `GET /diagnostics/hosted-config` is a local diagnostic route, not hosted runtime behavior. It inherits the local server auth boundary and returns status-only hosted config posture: categories, exposure labels, status labels, counts, and docs paths. It never returns raw env values, tokens, account ids, zone ids, tunnel tokens, provider keys, webhook URLs, local paths, request bodies, replay buffers, exports, archives, logs, or backups. `GET /diagnostics/hosted-identity` is also local diagnostics only. It reports Phase 07 Session 03 planned or unavailable hosted identity posture, lifecycle requirements, authorization surfaces, role/audit requirements, unsupported account claims, non-overclaim labels, counts, and docs paths. It does not add OAuth, SSO, Supabase auth, organization membership, account UI, billing, hosted storage authorization, analytics consent, public replay hosting, push, remote access, production audit proof, or trusted erasure. `GET /diagnostics/hosted-persistence` is local planned-state diagnostics for Phase 07 Session 04. It reports hosted persistence and public replay posture, data eligibility labels, storage activation requirements, public replay requirements, blocked payload labels, unsupported claim labels, counts, and docs paths. It does not add Supabase, a database, storage bucket, storage migration, upload endpoint, browser direct storage write, account-backed persistence, public replay page, takedown runtime, release-grade deletion, or trusted erasure. It never returns raw env values, tokens, account ids, request bodies, local paths, prompts, commands, terminal output, replay buffers, exports, archives, logs, backups, scan payloads, media drafts, or War Room payloads. `GET /diagnostics/hosted-operations` is local planned-state diagnostics for Phase 07 Session 06. It reports push, Web Push, VAPID, remote access, Cloudflare Tunnel, and operator diagnostics posture using status labels, requirement labels, blocked payload labels, unsupported claim labels, booleans, counts, and docs paths only. It does not add push delivery, push subscription storage, VAPID private key use, Cloudflare Tunnel, remote access, remote execution, hosted diagnostic agents, production-hosted validation, or trusted erasure. It never returns raw env values, subscriptions, account ids, zone ids, tunnel tokens, local paths, prompts, commands, terminal output, room payloads, logs, backups, exports, archives, replay buffers, scan payloads, or media drafts. Phase 07 Session 07 closeout validated all four hosted diagnostics routes (`hosted-config`, `hosted-identity`, `hosted-persistence`, `hosted-operations`) as status-only local planned/disabled/unavailable posture endpoints. Server route tests and the secret scan (886 tracked files) confirm they expose bounded labels and counts only and never raw credentials, account ids, zone ids, tunnel tokens, or local payloads. No hosted route family is promoted to active; the deterministic 501 catch-all still governs unshipped hosted, push, and remote-access paths. Production-hosted route validation remains Phase 08. ## Erasure Inventory And Cleanup Boundary Phase 08 Session 02 adds shared erasure inventory contracts. Phase 08 Session 03 adds the local-server runtime endpoints for the local filesystem subset, and Session 04 adds the Worker room-state erasure endpoints for one Durable Object room record. The protocol module `packages/protocol/src/erasure.ts`, server helpers `apps/server/src/lib/erasureInventory.ts` and `apps/server/src/lib/localErasure.ts`, Worker helpers `apps/warroom/src/erasureInventory.ts` and `apps/warroom/src/roomErasure.ts`, and inventory artifact `.spec_system/archive/phases/phase_08/unified_erasure_inventory.md` expose boundary ids, owners, authority labels, dry-run labels, confirmation states, verification labels, audit labels, blocked payload labels, unsupported claim labels, docs paths, booleans, and counts only. `POST /erasure/local/preview` returns a dry-run summary for release-scoped local boundaries. `POST /erasure/local/confirm` requires the exact phrase `ERASE LOCAL FACTIONOS STATE` plus an idempotency key before deleting eligible local files. Both routes inherit local bearer auth, return `Cache-Control: no-store`, include no-overclaim headers, and never echo raw paths, prompts, commands, exports, backups, logs, diagnostics, spool payloads, tokens, or request bodies. Confirmed deletion skips backup and malformed-spool manual-review boundaries, skips unsupported Worker/hosted/workspace/future boundaries, reports boundary-level partial failures, and verifies absence for eligible local targets. `POST /rooms/:code/erasure/preview` returns sanitized Worker room-state counts for participants, recent events, authority hash metadata, idempotency metadata, room revision state, and browser-hint adjacency. `POST /rooms/:code/erasure/confirm` requires current room leader authority, expected room revision, the exact phrase `ERASE WORKER WAR ROOM STATE`, and an idempotency key before deleting the Durable Object `room` record. Confirmed deletion closes active sockets, stores a redacted receipt, verifies room absence, and returns boundary/audit/verification labels only. Responses must not echo authority tokens, authority hashes, participant secrets, participant names, room payloads, request bodies, paths, env values, logs, exports, replay buffers, or diagnostics payloads. There is still no shipped generic `DELETE`, purge-all route, hosted account deletion, public replay takedown, production-hosted deletion evidence, or trusted unified erasure endpoint. Current flows keep their narrower meanings: * `GET|POST /export/session` creates a redacted local download; deleting that file later is export cleanup only. * Local session archive retention and manual archive cleanup are local audit artifact handling only. * `GET /diagnostics/*` routes are read-only compact posture routes. * `factionos doctor --recover-orchestration` removes stale listener PID files and malformed spool entries only. * Browser reset clears browser settings/runtime context only. * War Room leave/reset/disconnect clears local browser or socket lifecycle state only; Durable Object room erasure requires the separate leader-only Worker erasure confirmation route above. * CLI uninstall edits hook settings only and does not erase FactionOS state. Trusted unified erasure remains a Phase 08 no-claim until local/browser runtime deletion, Worker handling, audit, idempotency, partial failure, hosted no-claim posture, verification evidence, and release-candidate wording pass Session 08. ## REST Endpoints | Method | Path | Body or query | Response | | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `GET` | `/health` | none | `{ ok, version, uptimeMs, mock, time }` | | `POST` | `/event` | Hook payload | `{ accepted: true, heroId?, missionId? }` | | `GET` | `/heroes` | none | `{ heroes }` | | `GET` | `/heroes/:id` | none | `Hero` or `404` | | `GET` | `/missions` | `?limit=50`, valid `1..1000` | `{ missions }` | | `GET` | `/missions/:id` | none | `Mission` or `404` | | `GET` | `/notice-board` | `type`, `since`, `forSession`, `limit`, `offset`, `includeResolved`, `roomCode`, optional `debug=1` | `{ messages, total, debug? }` | | `GET` | `/notice-board/context` | `sessionId`, optional `roomCode`, `limit` | `{ context, messages?, total? }` | | `POST` | `/notice-board` | `{ type, content, priority?, tags?, authorSessionId?, authorName?, authorType?, targetSessionIds?, relatedFiles?, roomCode?, expiresAt? }` | `201 { notice }` | | `POST` | `/notice-board/:id/resolve` | `{ resolution?, resolvedAt?, authorSessionId? }`, optional `roomCode` query | `{ success, noticeId, resolvedAt? }` | | `GET` | `/notices` | optional `roomCode` | Compatibility `{ notices }` | | `POST` | `/notice` | Compatibility `{ body, severity?, targets? }` plus canonical notice fields | Compatibility `Notice` | | `GET` | `/scrolls` | none | `{ scrolls }` | | `POST` | `/scrolls/:id/collect` | `{ heroId? }` | `Scroll` or `404` | | `GET` | `/achievements` | none | `{ achievements }` | | `GET` | `/quests` | none | `{ quests }` | | `GET` | `/warroom` | none | Compatibility/status stub with `capability.status: "stubbed"` and Worker `separate-surface` metadata. | | `POST` | `/permission-response` | `{ requestId, approved?, reason? }` | Compatibility response `{ ok: true, resolved }`; also records paired command-center permission and attention decision state. | | `POST` | `/plan/approve` | `{ planId, approved?, reason? }` | Compatibility response `{ ok: true, resolved }`; also records paired command-center plan-approval permission and attention decision state. | | `GET`/`POST` | `/export/session` | \`?format=csv | json`or POST`{ format }\` | | `POST` | `/erasure/local/preview` | `{ boundaryIds? }` | Dry-run local erasure summary with redacted labels, counts, manual-review states, unsupported boundaries, and no full trusted erasure claim. | | `POST` | `/erasure/local/confirm` | `{ confirmationPhrase, idempotencyKey, boundaryIds? }` | Confirmed local erasure for eligible local filesystem boundaries; reports completed, verified, manual-review, skipped, failed, and partial-failure states without raw sensitive values. | | `GET` | `/task-queue` | `?limit=50`, optional `state` | Local in-memory queue snapshot with counts and bounded entries. Terminal, Git, file, and container executable rows expose only safe execution summaries and links, not command text, output, diffs, file contents, patch bodies, Docker command/output fields, env, mounts, or broad paths. | | `POST` | `/task-queue` | `{ title, summary?, priority?, source?, references?, executable?, idempotencyKey? }` | Creates a local queue entry. `executable.kind: "terminal"` stores request-scoped command text privately; `executable.kind: "git"` stores an allowlisted Git workbench request privately; `executable.kind: "file"` stores a schema-validated file mutation request privately; `executable.kind: "container"` stores only safe hero/image/runtime labels privately. Public rows expose only safe execution metadata and emit `task_queue_update`. | | `PATCH` | `/task-queue/:id` | `{ title?, summary?, state?, priority?, references?, executable?, blockedReason?, expectedRevision? }` | Updates local queue metadata or a private terminal/Git/file/container executable payload; emits `task_queue_update`. | | `POST` | `/task-queue/:id/reject` | `{ reason, code?, expectedRevision? }` | Rejects a queue entry; emits `task_queue_update`. | | `POST` | `/task-queue/:id/start-tracking` | `{ expectedRevision?, idempotencyKey? }` | Preserves metadata-only queue behavior by moving a queued or blocked row into truthful local tracking state without claiming terminal execution; emits `task_queue_update`. | | `POST` | `/task-queue/:id/dispatch` | `{ expectedRevision?, idempotencyKey?, executable? }` | Dispatches queue rows with terminal, Git, file, or container executable payloads. Terminal rows run through the local PTY gate; Git rows execute only status, stage, and unstage queue operations; file rows execute through the local file mutation manager with workspace containment and expected-hash checks; container rows run the existing isolated-spawn container manager and return unavailable when runtime or image gates fail. It creates or reuses a queue-targeted command-center execution run, records safe execution summaries, emits `task_queue_update` and `command_center_execution_update`, and returns unavailable/failed states instead of leaking command text, output, diffs, file contents, patch bodies, Docker command/output fields, env, mounts, or broad paths. | | `POST` | `/task-queue/:id/rollback` | `{ backupId, expectedRevision?, idempotencyKey? }` | Rolls back a file queue execution through a manager backup when `rollbackState` is available. Responses expose compact rollback metadata only: operation labels, path labels, changed-byte counts, backup id, rollback state, execution run id, and bounded result status. | | `GET` | `/agent-templates` | `?limit=20`, optional `role`, `tag` | Lists compact source-owned local templates; emits `agent_template_update`. | | `GET` | `/agent-templates/:id` | none | Returns a template or `404`; emits `agent_template_update` when found. | | `POST` | `/agent-templates/suggestions` | `{ desiredRole?, tags?, summary?, limit? }` | Returns bounded local template suggestions; emits `agent_template_update`. | | `GET` | `/guarded-actions` | `?limit=50`, optional `state`, `family` | Lists local in-memory guarded-action proposals with counts and bounded entries. | | `POST` | `/guarded-actions` | `{ family, kind, requester?, rationale, preview, references?, expiresInMs?, idempotencyKey? }` | Creates a bounded guarded-action proposal; emits `guarded_action_update`. | | `GET` | `/guarded-actions/:id` | none | Returns a guarded-action proposal or `404`; expired pending proposals update state first. | | `POST` | `/guarded-actions/:id/approve` | `{ reason?, expectedRevision?, idempotencyKey? }` | Records approval, evaluates the executor registry, creates a bounded command-center execution run, and completes with executed, failed, unavailable, or not-executed result state; emits guarded-action and command-center executor/execution updates. Guarded file actions execute only when they include a validated `fileMutation` request and the local file manager is ready. | | `POST` | `/guarded-actions/:id/reject` | `{ reason?, expectedRevision?, idempotencyKey? }` | Rejects a pending guarded-action proposal; emits `guarded_action_update`. | | `POST` | `/guarded-actions/:id/decision` | `{ approved, reason?, expectedRevision?, idempotencyKey? }` | Generic approve/reject decision endpoint for local clients. | | `GET` | `/channels` | none | Lists local channel intake health for GitHub, generic webhook, Telegram, and Discord providers with proposal-only/trusted-execution posture. | | `POST` | `/channels/:provider/pair` | `{ enabled?, sourceLabel? }` for `github`, `webhook`, `telegram`, or `discord` | Records local pairing/config status metadata only. It does not grant trusted execution or store secrets. | | `GET` | `/channel-commands` | `?limit=50`, optional command-center scope filters | Lists bounded inbound channel command rows with source, delivery, validation, replay, and scope labels. | | `POST` | `/webhooks/generic` | `{ deliveryId, summary, provider?, sourceLabel?, title?, conversion?, priority?, queuePriority?, risk?, scope?, receivedAt? }` | Records a generic, Telegram, or Discord-style inbound command as proposal-first state and may create queue, attention, or guarded review records. Duplicate replay keys update replay metadata instead of duplicating conversions. | | `POST` | `/webhooks/github` | `{ deliveryId?, eventName?, repository?, action?, sourceLabel?, title?, summary?, conversion?, priority?, queuePriority?, risk?, scope?, receivedAt? }` plus optional GitHub delivery/event headers | Records a GitHub webhook delivery as proposal-first state with repository/source labels and replay guard. It does not verify GitHub signatures or execute trusted commands in this session. | | `GET` | `/command-center/capabilities` | none | Lists command-center and executor capability envelopes with docs paths and explicit registry-gated status. | | `POST` | `/command-center/capabilities/refresh` | none | Refreshes capability timestamps and emits `command_center_executor_update` without invoking any executor. | | `POST` | `/command-center/campaigns/preview` | `{ title, summary?, tasks?, idempotencyKey? }` where task items may include `dependencyTaskIds?` and \`executable.kind: "terminal" | "git" | | `POST` | `/command-center/campaigns` | `{ title, summary?, tasks?, idempotencyKey? }` where task items may include `dependencyTaskIds?` and \`executable.kind: "terminal" | "git" | | `POST` | `/command-center/campaigns/:id/refine` | `{ summary?, tasks?, expectedRevision?, idempotencyKey? }` where task items may include `dependencyTaskIds?` and \`executable.kind: "terminal" | "git" | | `POST` | `/command-center/campaigns/:id/dispatch` | `{ expectedRevision?, idempotencyKey? }` | Walks the campaign DAG in serial dependency order, creates queue entries only for ready executable campaign tasks, links them with `{ planId, taskId }`, dispatches terminal/Git/file/container work through the task execution coordinator, and returns safe queue entries, execution links/runs, executed/planning-only/unavailable/failed/blocked/waiting/retryable task id buckets, and `partialFailure` when applicable. Planning-only tasks are not queued or executed. | | `GET` | `/command-center/{plans,tasks,attention,executors,heroes,executions,permissions,file-intents,workpads,evidence,verification,review-gates,handoffs,diagnostics,channels,usage,notification-readiness,collaboration-posture}` | `?limit=50`, optional `cursor`, `sort`, `states`, `families`, ids, `packagePath`, `projectLabel`, `worktreeLabel`, `sourceLabel`, `rosterLabel`, or `scopeKinds` | Lists bounded command-center scaffold snapshots with typed scope metadata. The `heroes` slice returns hero lifecycle command records, not raw terminal sessions. | | `GET` | `/command-center/collaboration-posture` | `?limit=50`, optional `cursor` | Lists compact collaboration posture rows with visibility, room code labels, Notice links, visibility counts, and remote-access summary labels only. It does not expose raw Worker, tunnel, prompt, command, transcript, or relay payloads. | | `GET` | `/command-center/lineage-roster` | `?limit=50`, optional `cursor`, \`state=all | spawned | | `POST` | `/command-center/executors/probe` | `{ expectedRevision?, idempotencyKey? }` | Re-probes all registered executor capabilities, stores compact capability posture, and emits `command_center_executor_update`; no executor action runs. | | `POST` | `/command-center/executors/:id/probe` | `{ expectedRevision?, idempotencyKey? }` | Re-probes one executor capability id such as `capability_file_file_edit`, stores compact posture, and emits `command_center_executor_update`; invalid ids and raw payload fields are rejected. | | `POST` | `/command-center/{plans,tasks,attention,permissions,file-intents,verification,review-gates,handoffs,channels,usage,notification-readiness}` | Protocol-shaped command-center DTO plus optional `expectedRevision`, `idempotencyKey` | Records bounded scaffold state and emits the matching `command_center_*_update` event. | | `POST` | `/command-center/usage/refresh` | `{ providerUsage?, missionArtifactEstimates?, generatedAt?, windowStartedAt?, windowEndedAt? }` | Rebuilds deterministic usage rollups for tasks, queue age, attention, reviews, executors, providers, tokens, cost, lines, notifications, throughput, and latency. Input is bounded metadata only; raw provider payloads, prompts, transcripts, terminal output, file contents, and absolute paths are rejected. | | `GET` | `/command-center/notifications/preferences` | none | Returns local notification preferences, readiness records, generated timestamp, and an optional safe Web Push subscription summary with endpoint hash and key lengths only. | | `POST` | `/command-center/notifications/preferences` | `{ localEnabled?, webPushConsent?, categories?, mutedCategories?, browserPermission?, serviceWorkerAvailable?, secureContext?, generatedAt? }` | Updates local command-center notification preferences and readiness posture. Consent does not create a push subscription or activate hosted delivery. | | `GET` | `/command-center/notifications/readiness` | none | Returns local notification readiness records and optional safe subscription summary. | | `POST` | `/command-center/notifications/readiness` | `{ browserPermission?, serviceWorkerAvailable?, secureContext?, generatedAt? }` | Refreshes browser/service-worker/Web Push readiness gates without creating a subscription or sending push payloads. | | `POST` | `/command-center/notifications/subscribe` | `{ consentGranted, subscription, browserPermission?, serviceWorkerAvailable?, secureContext?, generatedAt? }` | Stores a validated Web Push subscription summary only when explicit consent and VAPID readiness gates pass. Responses never echo the raw endpoint or keys and `pushDeliveryActive` remains false unless the server delivery path is explicitly configured. | | `POST` | `/command-center/notifications/unsubscribe` | `{ revokeConsent?, browserPermission?, serviceWorkerAvailable?, secureContext?, generatedAt? }` | Clears any recorded subscription summary, optionally revokes consent, refreshes readiness, and keeps hosted push delivery inactive by default. | | `POST` | `/command-center/context-notices` | \`{ kind: "review\_request" | "blocker" | | `POST` | `/command-center/handoffs/scaffold` | `{ target, summary, evidenceIds?, noticeLinks?, lineageLinks?, visibility?, remoteAccess?, expectedRevision?, idempotencyKey? }` | Creates a handoff scaffold with visibility, Notice linkbacks, lineage links, remote-access summary, and initial readiness checks. Remote access remains `no_claim` unless a future scoped implementation proves otherwise. | | `POST` | `/command-center/handoffs/validate` | `{ handoffId, checks, expectedRevision?, idempotencyKey? }` | Updates handoff readiness checks and readiness status, rejects stale or duplicate validations, and emits `command_center_handoff_update`. | | `POST` | `/command-center/handoffs/resume-source` | `{ handoffId, resumeSource, expectedRevision?, idempotencyKey? }` | Records a bounded resume-source label for a ready handoff. It does not read transcripts, replay buffers, Worker payloads, or local files. | | `POST` | `/command-center/handoffs/reentry` | `{ handoffId, reason?, expectedRevision?, idempotencyKey? }` | Marks a handoff re-entry, stales resume-source readiness, preserves safe lineage metadata, and emits `command_center_handoff_update`. | | `POST` | `/command-center/collaboration-posture` | `{ id, visibility, summary, roomCode?, noticeLinks?, remoteAccess? }` | Records compact collaboration posture and emits `command_center_collaboration_posture_update` with visibility labels, counts, room labels, and links only. | | `POST` | `/command-center/workpads` | `{ item: CommandCenterWorkpadRecord, expectedRevision?, idempotencyKey? }` | Records workpad metadata, target links, item counts, evidence ids, revision state, and blocked-category labels only; emits `command_center_workpad_update`. | | `POST` | `/command-center/evidence` | `{ item: CommandCenterEvidenceArtifact, expectedRevision?, idempotencyKey? }` | Records evidence artifact metadata such as kind, state, safe title, redaction state, optional repo-relative source path, and blocked-category labels only; emits `command_center_evidence_update`. | | `POST` | `/command-center/verification/:id/retry` | `{ expectedRevision?, idempotencyKey?, requestedAt?, retryLimit?, summary? }` | Creates a pending verification retry for a failed attempt, enforces retry limits and stale revisions, resolves failed-verification attention when applicable, and emits `command_center_verification_update`. | | `POST` | `/command-center/verification/:id/skip` | `{ decidedAt?, expectedRevision?, idempotencyKey?, reason? }` | Marks a pending or failed verification attempt as skipped, records bounded audit summary, dismisses failed-verification attention when applicable, and emits `command_center_verification_update`. | | `POST` | `/command-center/review-gates/:id/decision` | \`{ state: "approved" | "rejected" | | `POST` | `/command-center/file-intents/conflicts` | `{ path, operation, intentId?, heroId? }` | Checks active file-intent conflicts for one repo-relative path and operation. Returns only repo-relative file labels, intent ids, state, and generated timestamp; no file content is read. | | `POST` | `/command-center/file-intents/:id/resolve` | \`{ action: "cleared" | "override" | | `POST` | `/command-center/git/preview` | `{ operation, paths, idempotencyKey?, message?, branch? }` for allowlisted operations | Returns a bounded Git workbench plan, risk label, cleanup note, rollback note, and unavailable reason when blocked. It does not run Git. | | `POST` | `/command-center/git/execute` | Same body as preview | Runs only allowlisted local Git workbench operations with timeout and bounded output, stores a compact command-center execution run, and emits `command_center_execution_update`; push remains policy-blocked unless external Git execution is explicitly enabled. | | `GET` | `/command-center/terminal/snapshot` | none | Probes local PTY readiness and returns terminal policy metadata, active terminal sessions, safe shell/cwd labels, output cap, timeout, cleanup posture, docs path, and fallback reason. | | `GET` | `/command-center/terminal/sessions/:id` | none | Returns one scoped terminal session with bounded output window and lifecycle metadata, or `404`; route ids must be normalized command-center ids. | | `POST` | `/command-center/terminal/preview` | `{ commandText, ownerId?, timeoutMs?, executionRunId?, idempotencyKey? }` | Validates request-scoped command text and returns a safe terminal preview with command label, risk, timeout, output cap, approval requirement, and fallback reason; it does not start a PTY. | | `POST` | `/command-center/terminal/run` | Same body as preview | Starts a local PTY-backed terminal session only when the optional PTY adapter probes ready, records a compact terminal execution with safe attachment metadata, rejects duplicate in-flight runs, and keeps bounded output scoped to the terminal session detail. | | `POST` | `/command-center/terminal/sessions/:id/input` | `{ inputText, idempotencyKey? }` | Sends request-scoped input to a running terminal session, rejects duplicate in-flight inputs, and returns the updated bounded session state. | | `POST` | `/command-center/terminal/sessions/:id/kill` | `{ idempotencyKey? }` | Kills a running terminal session, records cleanup and compact execution metadata, and returns the bounded session state. | | `POST` | `/command-center/terminal/sessions/:id/restart` | `{ idempotencyKey? }` | Restarts a known terminal command through the same PTY gate and returns the replacement bounded session state plus compact execution metadata. | | `GET` | `/command-center/containers/probe` | none | Probes Docker and Apple Containers readiness plus image, browser dependency, auth mount, worktree mount, network profile, provider runtime, cleanup posture, docs path, and fallback reason. | | `POST` | `/command-center/containers/probe` | `{ imageName?, idempotencyKey? }` | Re-probes local container readiness for an optional safe image label, rejects duplicate in-flight probes, and does not start a container. | | `POST` | `/command-center/containers/isolated-spawn/preview` | `{ heroId?, heroLabel?, imageName?, runtime?, idempotencyKey? }` | Returns a guarded isolated-spawn preview with safe hero/image labels, runtime readiness, requirements, and fallback reason; it does not start a container. | | `POST` | `/command-center/containers/isolated-spawn/run` | Same body as preview | Runs a local isolated spawn only when required Docker readiness gates pass, records a compact container execution attachment, rejects duplicate in-flight runs, and returns unavailable or failed states without raw probe output. | | `POST` | `/command-center/heroes/commands` | `{ heroId, kind, requester, summary?, target?, modelId?, permissionMode?, isolationMode?, managedSessionId?, messageInput?, expectedRevision?, idempotencyKey? }` where managed execution is limited to `stop`, `restart`, and `message` for a registered managed session | Records a bounded hero lifecycle command, rejects stale or duplicate in-flight triggers, and emits `command_center_hero_lifecycle_update`. When `managedSessionId` references an owned process or PTY session, supported `stop`/`restart`/`message` actions route through the managed lifecycle manager and create a compact execution run. `messageInput` is request-scoped and is never stored. Hook-observed and unregistered sessions remain record-only; model, permission, and isolation changes return unavailable policy-blocked records before execution. | | `POST` | `/command-center/permissions/:id/decision` | Protocol-shaped permission decision body | Records an approve or reject decision for a scaffold permission request and emits paired `command_center_permission_update` and `command_center_attention_update` frames when linked. | | `POST` | `/command-center/attention/:id/decision` | \`{ decision: "approved" | "rejected", reason?, expectedRevision?, idempotencyKey?, decidedAt?, decidedBy? }\` | | `POST` | `/command-center/executions/unavailable` | Protocol-shaped execution run with `state: "unavailable"` and `resultStatus: "unavailable"` | Records an unavailable execution result only; no executor is invoked. | | `GET` | `/command-center/executions/:id` | none | Returns one bounded execution run detail or `404`; route ids must start with `execution_` or persisted Git workbench `git_` ids, and responses may include safe terminal, container, or compact file attachment metadata but never raw command output, file content, patch bodies, diffs, or broad absolute paths. | | `GET` | `/diagnostics/runtime` | none | Returns compact local runtime counts for heroes, missions, tool uses, connected clients, and recent event throughput only. | | `GET` | `/diagnostics/orchestration` | none | Returns compact local orchestration availability, generated-at metadata, and counts for queue, templates, mission graph, guarded actions, command-center scaffolds, recent execution runs, terminal queue posture, and Git queue posture. | | `GET` | `/diagnostics/provider-readiness` | none | Returns compact local provider/setup/runtime readiness, command-center provider diagnostics posture, safe recovery descriptors, and docs paths without raw provider payloads or env values. | | `POST` | `/diagnostics/orchestration/recover` | `{ action, idempotencyKey, dryRun? }` | Performs only stale listener PID cleanup or malformed spool JSON cleanup, rejects unsupported actions, guards duplicate idempotency keys, and returns compact action counts. | | `GET` | `/diagnostics/isolation` | none | Returns compact read-only isolation posture, executor family readiness, terminal/container readiness metadata when wired, unsupported route families, redaction categories, and recovery limits. | | `GET` | `/diagnostics/hosted-config` | none | Returns status-only local hosted config posture, categories, exposure labels, counts, and docs paths without raw env values. | | `GET` | `/diagnostics/hosted-identity` | none | Returns status-only local hosted identity posture, lifecycle and authorization requirement labels, unsupported claim labels, non-overclaim labels, counts, and docs paths without raw account or authority values. | | `GET` | `/diagnostics/hosted-persistence` | none | Returns status-only local hosted persistence and public replay posture, data eligibility labels, storage and replay requirement labels, blocked payload labels, unsupported claim labels, counts, and docs paths without raw payload values. | | `GET` | `/diagnostics/hosted-operations` | none | Returns status-only local push, remote access, tunnel, and operator diagnostics posture with requirement labels, blocked payload labels, unsupported claim labels, counts, and docs paths without raw payload values. | Mission artifact records are metadata-only local command-center records. Route parsers reject blocked raw field names such as `prompt`, `commandBody`, `diff`, `terminalOutput`, `fileContent`, `transcriptText`, `token`, `secret`, `rawLog`, `absolutePath`, `replayBuffer`, and `exportPayload`; accepted records may carry `blockedCategories` labels but must not carry the raw material. Session 16 command-center ergonomics are browser behavior layered on the same local API. The web cockpit maps `O` sequence shortcuts to detail open, Attention focus and selected approve/reject decisions, blocked and failed queue cycling, scope filters, terminal entry, isolated spawn focus, and handoff focus. Mutating shortcuts still call existing local decision routes with expected revisions and idempotency keys; no shortcut bypasses duplicate guards or starts an executor directly. Adjacent-surface rows link Mission Control, Plan Workpad, Permission Modal, Notice Board, Quest Board, War Room, Settings, Git/Codex, terminal, handoff, export, replay, achievements, mission history, channels, remote access, and usage to existing browser surfaces or explicit unavailable/no-claim rows. Remote Access remains a no-claim row and does not open tunnels, hosted diagnostics, Worker commands, or remote executors. Evidence lives in `tests/e2e/orchestration-command-center.e2e.ts` for app desktop and mobile plus the focused web component and helper tests. Terminal and container command-center routes are local-only executor surfaces. Terminal command and input text are request-scoped, validated, length-bounded, and blocked from command-center execution records, broad rows, diagnostics, WebSocket snapshots, exports, replay, docs examples, and Worker transfer. Terminal output is capped and appears only in `CommandCenterTerminalSession` detail responses for the selected scoped terminal session. Execution runs carry safe `attachment` metadata such as kind, summary, line count, truncation flag, duration, cleanup posture, terminal session id, container run id, runtime, and fallback reason. The Phase 20 file mutation core is manager-level, not a public apply route. `apps/server/src/managers/fileMutationManager.ts` owns repo-relative path validation, symlink escape rejection, generated/ignored path policy, stale hash guards, active file-intent conflict checks, backup-before-mutation, rollback, and compact execution evidence for read, preview, write, edit, delete, move, and rename requests. Backups are local-only recovery artifacts under the injected FactionOS state root at `file-mutations/backups//`; backup metadata exposes ids, operation labels, safe path labels, hashes, timestamps, and rollback state only. File contents and edit text stay request-scoped or in the local backup content file and must not appear in command-center rows, WebSocket events, diagnostics, docs examples, logs, exports, replay buffers, or Worker payloads. Session 07 wires file mutations into guarded approvals, task queue dispatch, campaign dispatch, and queue rollback. File execution requires structured `CommandCenterFileMutationRequest` payloads, workspace containment, expected hashes for destructive mutations, conflict checks, and local backup metadata for rollback-capable operations. Public REST responses, WebSocket frames, UI rows, docs examples, and diagnostics expose only compact metadata: operation labels, path labels, changed-byte counts, backup ids, rollback state, result status, failure/unavailable codes, and execution run ids. Task queue execution uses the same executor boundaries. A queue row may store a private `executable.kind: "terminal"` payload or a private `executable.kind: "git"` allowlisted Git workbench request, or a private `executable.kind: "file"` file mutation request, or a private `executable.kind: "container"` payload with safe hero/image/runtime labels, but broad queue entries, `task_queue_update` frames, command-center execution rows, diagnostics, and docs examples expose only safe command labels, executor family, execution state, retryability, result summary, execution run id, terminal session id when present, container run id when present, runtime, cleanup posture, Git operation labels, file operation labels, safe path labels, changed-byte counts, backup ids, rollback state, compact counts, and recovery guidance. Metadata-only queue rows use `/task-queue/:id/start-tracking`; `/task-queue/:id/dispatch` is reserved for terminal, Git, file, and container executable rows. `/task-queue/:id/rollback` restores a file backup when the manager still reports rollback as available. Terminal dispatch fails closed when PTY is unavailable, stale, timed out, killed, or duplicated. Git dispatch executes only status, stage, and unstage queue operations; push is policy-blocked, and commit, stash, revert, and branch-switch drafts remain unavailable for queue dispatch in this release. File dispatch fails closed on unsafe paths, stale hashes, active conflicts, unavailable manager state, duplicate in-flight keys, and missing rollback backups. Container dispatch is distinct from the direct `/command-center/containers/isolated-spawn/run` route but uses the same manager-owned local gates; it fails closed for runtime unavailable, image unavailable, stale revisions, duplicate in-flight keys, timeout, or failed cleanup, and it never accepts or returns raw Docker commands, raw output, env, mount, volume, image-inspect, or workspace path payloads. Campaign executable dispatch uses the task queue execution boundary rather than a campaign-specific executor. Campaign task create/refine payloads can carry `dependencyTaskIds` plus a private terminal, Git, file, or container executable payload; public campaign task rows show only dependency ids, readiness, safe result summaries, queue ids, execution run ids, terminal session ids when present, container run ids/runtime/cleanup posture when present, and compact file rollback metadata when present. Dispatch walks the persisted task DAG in stable topological order. It queues a task only after known executable prerequisites complete, marks dependents blocked for unknown, cyclic, failed, unavailable, cancelled, or planning-only prerequisites, and leaves dependents waiting while prerequisites are still in progress. The dispatch response shape includes `changes.campaign`, `changes.tasks`, `changes.queue`, `changes.executions`, `queueEntries`, `executionLinks`, `executionRuns`, `executedTaskIds`, `planningOnlyTaskIds`, `unavailableTaskIds`, `failedTaskIds`, `blockedTaskIds`, `waitingTaskIds`, `retryableTaskIds`, and `partialFailure`. Unavailable executor readiness is represented by `executionReadiness.status: "unavailable"` with `unavailableReason`; failed readiness/summary records may include `failureCode`. Retry resets only failed or unavailable executable tasks that remain retryable and keeps earlier queue and execution-run history; the next dispatch creates fresh retry evidence for the reset executable tasks. Broad responses and WebSocket frames do not include command text, executable payloads, terminal output, stdout, stderr, Git diffs, broad paths, terminal session output, or private Git request payloads; full terminal output is available only through the scoped terminal session detail route. The PTY adapter is the required native `node-pty` dependency; if it fails to load or probe on the local host, terminal probes and terminal executor entries fail closed with `pty_unavailable`. Container routes probe Docker and Apple Containers separately and keep image, browser dependency, auth mount, worktree mount, network, provider runtime, and cleanup posture explicit. Missing runtimes return structured unavailable or preview-only states, not hosted execution, remote access, tunnel, Worker command bridge, or production Docker claims. ## Notice Board Routes The Notice Board is an explicit coordination channel for active local and optional War Room work. It is not a raw event log. API callers should post only brief `status`, `question`, `review`, `announcement`, `conflict`, `completion`, or `human` messages that other active agents or humans need to see. Notice payloads may include safe coordination metadata: bounded content, priority, tags, display author metadata, target session ids, room code, and up to 20 normalized relative `relatedFiles`. Notice payloads must not carry raw prompts, transcripts, terminal output, command bodies, file contents, secrets, tokens, absolute paths, logs, exports, replay buffers, scan payloads, media drafts, diagnostics, backups, or quarantined historical content. `GET /notice-board` returns newest-first messages for the active room. Query filters are: | Query | Meaning | | ----------------- | ----------------------------------------------------------------------------------------------------------------- | | `type` | One of the canonical notice types. | | `since` | Millisecond timestamp lower bound. | | `forSession` | Filters out notices targeted to other sessions and hides expired or resolved messages unless explicitly included. | | `limit` | Result cap, valid `1..500`. | | `offset` | Pagination offset. | | `includeResolved` | Include resolved messages when `true`. | | `roomCode` | Optional active-room override. Omitted requests use the local active room. | | `debug=1` | Adds compact filter and provenance labels without raw payloads. | `GET /notice-board/context?sessionId=` returns bounded prompt-start context for that session. The context includes only unresolved active-room messages that are relevant to the target session, excludes messages authored by the same session, and uses the heading `## Notice Board (New Messages)` when there is content. Empty, invalid, or unavailable context should be treated as no additional context. `POST /notice-board` validates the canonical notice model before mutation. Required fields are `type` and `content`; `content` is capped at 2000 characters. Optional fields include `priority`, `tags`, `authorMachineId`, `authorSessionId`, `authorName`, `authorAvatarUrl`, `authorType`, `targetSessionIds`, `parentMessageId`, `relatedFiles`, `roomCode`, and `expiresAt`. Compatibility aliases `body`, `targets`, and `severity` are accepted during migration and normalized into the canonical shape. `POST /notice-board/:id/resolve` resolves a notice in the active room and emits `notice_resolved` to connected local clients. Unknown notice ids in the active room return `404`. Duplicate in-flight posts or resolutions return a compact `409 conflict` envelope. Compatibility routes remain supported for older callers. `GET /notices` reads from the same manager and returns `{ notices }`. `POST /notice` accepts legacy `body`, `severity`, and `targets` fields, normalizes them through the canonical manager, stores the notice in the active room, emits `notice_board_message`, and returns the stored `Notice` object. ## Quest Board Suggestion Endpoints The Quest Board route family is local-server state owned by `SuggestionManager`. Every route below is mounted at the root path and under the `/api` prefix. All routes run behind the local auth token when configured, the shared rate limiter, the 2 MB JSON body cap, and schema/type validation. Invalid bodies return compact `400 invalid_request` envelopes with field labels only. Duplicate in-flight mutations or scans return `409 conflict`. Manager validation failures also map to `400 invalid_request`; missing suggestions return `404 not_found`; failed scan or analysis runs return compact `503` labels without raw prompts, provider payloads, file contents, command output, tokens, or broad absolute paths. | Method | Path | Body | Response | | ------ | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `GET` | `/suggestions/summary` | none | `{ summary }` with manager counts, active counts, dismissed counts, severity buckets, and generated timestamp. | | `GET` | `/suggestions/scan/status` | none | `{ status }` with codebase scan scope, mode, status, in-flight flag, timestamps, optional last error, and last scan commit. | | `POST` | `/suggestions/scan` | `{ scope: "codebase", mode?, forceFull?, force?, root?, questIgnorePatterns? }`; `?full=true` also forces full mode | Starts a full, diff, or daily codebase scan and returns `{ accepted: true, status, fileCount, issueCount }`. | | `GET` | `/suggestions/analyze/status` | none | `{ status }` for on-demand analysis progress, completion, and compact failure state. | | `POST` | `/suggestions/analyze` | `{ scope?: "analysis", force?, forceRefresh?, root? }` | Runs analysis or returns a fresh cached result with `{ accepted: true, status, cached, itemCount, analysisResult }`. | | `GET` | `/suggestions/project-scan/status` | none | `{ status }` for project scan progress, completion, and compact failure state. | | `POST` | `/suggestions/project-scan` | `{ scope?: "project", force?, forceRefresh?, root? }` | Runs project scan or returns a fresh cached result with `{ accepted: true, status, cached, itemCount, projectScan }`. | | `POST` | `/suggestions/:suggestionId/accept` | optional `{ suggestionId?, heroId? }` | Accepts an idle suggestion and returns `send_prompt` for a resolvable internal hero or `prompt_sent` compatibility intent otherwise. | | `POST` | `/suggestions/:suggestionId/dismiss` | optional `{ suggestionId? }` | Dismisses an idle suggestion, persists the dismissed ID, emits an update, and returns `{ success, suggestionId, dismissed: true }`. | | `POST` | `/issues/:issueId/dismiss` | optional `{ issueId? }` | Dismisses a codebase issue, persists the dismissed ID, emits an update, and returns `{ success, issueId, dismissed: true }`. | `/suggestions/scan` roots must be approved local roots. Request ignore patterns are merged with `.factionos-questignore` under the approved root, then applied before codebase issues enter manager state. Analysis results are fresh for 30 minutes; project scans and codebase scans are fresh for 24 hours. Fresh cached analysis or project scan results return without provider work unless `force` or `forceRefresh` is true. LLM provider transfer is disabled unless both provider credentials and `FACTIONOS_ALLOW_LLM_PROVIDER_TRANSFER=true` are present; local fallback output remains schema-valid. The canonical Quest Board WebSocket event is `suggestion_update`. It carries a typed snapshot with `idleSuggestions`, `codebaseIssues`, `sessionSummaries`, `analysisResult`, `projectScan`, `scanStatus`, dismissed ID arrays, `summary`, and `updatedAt`. New socket clients receive one hydrate frame during connect, and manager mutations emit another snapshot. The string-only `idle_suggestion` event remains a compatibility event derived from active idle suggestions; new consumers should use `suggestion_update`. The historical `quest_board` event is retired and should not be used for new Quest Board clients. ## LLM Endpoints All LLM engines return deterministic fallback output when provider configuration is absent, blocked, or unavailable. `ANTHROPIC_API_KEY` alone does not transfer local prompts or code; provider transfer also requires `FACTIONOS_ALLOW_LLM_PROVIDER_TRANSFER=true`. LLM responses include provider mode and privacy headers. | Method | Path | Body | Notes | | ------ | ---------------------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `POST` | `/llm/plan` | `{ missionId?, prompt, conventions? }` | Generates a plan and emits `plan_generated`. | | `POST` | `/llm/analyze` | `{ files: [{ path, content }], antiPatterns? }` | Requires valid file objects; caps input to 12 files and 12000 chars per file. | | `POST` | `/llm/scan-codebase` | `{ root, limit?, extensions?, antiPatterns? }` | Walks only approved server-local roots, ignores historical artifact directories, redacts absolute roots, and emits progress events. | | `POST` | `/llm/idle-suggestion` | `{ heroId, lastUserTask, recentActivity }` | Emits `idle_suggestion` when suggestions exist. | | `GET` | `/memory` | none | Returns redacted transcript-mined findings. | | `GET` | `/memory/:type` | `workspace_fact`, `convention`, or `anti_pattern` | Returns redacted findings of a single type. | Approved scan roots are the server working directory plus paths listed in `FACTIONOS_SCAN_ROOTS` using the platform path delimiter. Malformed LLM requests use the shared `invalid_request` envelope and do not echo raw prompts, file contents, tokens, provider errors, or absolute roots. `POST /llm/scan-codebase` refuses empty roots, non-directories, the filesystem root, and roots outside the approved allowlist. Responses expose redacted root metadata plus relative file metadata only. The endpoint skips symlinks, ignores generated and historical artifact directories, caps the file count and file content size, and reports provider-transfer mode through LLM privacy headers. `GET|POST /export/session` downloads local CSV or JSON only. Successful responses include `X-FactionOS-Export-Schema`, `X-FactionOS-Export-Privacy: redacted-local`, and `Cache-Control: no-store`. Invalid export formats return a compact `invalid_request` envelope listing `csv` and `json` without echoing the raw invalid value. ## Event Ingest Mapping `POST /event` accepts a tolerant hook payload shape. Current source dispatches specific handling from `eventName` or `hook`, plus selected type-only compatibility values: `hero_active`, `mission_start`, `file_access`, `bash_command`, and `hero_idle`. Unknown named events should not crash ingest; when possible they are forwarded as bounded `mission_event` frames. Unknown type-only payloads are accepted as no-ops, not shipped behavior. | Hook event | Current server behavior | | -------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `SessionStart` / `hero_active` | Spawns or reuses a hero, stores `sessionId` as an alias, emits `internal_hero_spawn` only for new heroes, and records bounded command-center hero lifecycle metadata such as model, permission mode, isolation mode, worktree label, terminal label, listener label, process label, and event count when supplied by hooks. | | `UserPromptSubmit` / `mission_start` | Resolves `heroId` or `sessionId`, starts or reuses an active mission, marks hero active, emits `mission_start`. | | `Stop` / `hero_idle` | Resolves `heroId` or `sessionId`, completes active mission, clears `activeMissionId`, marks hero idle, and records a bounded hero lifecycle stop observation when supplied by hooks. | | `PreToolUse` with `file_access` or `bash_command` | Adds generic `tool_use` and emits first-class file or bash events when an active mission exists. File access payloads with safe `repoRelativePath` metadata are also promoted into command-center file intents; unsafe absolute fallback paths are skipped. | | `PreToolUse` / `PostToolUse` input and permission types | Emits `awaiting_input`, `input_received`, or `permission_request`; permission requests are also promoted into paired command-center permission and attention records; missing heroes emit bounded `missing_hero` mission events. | | `PreToolUse` or `SubagentStart` with `subagent_spawn` | Emits typed lineage and mission graph updates when safe IDs are available, records a bounded hero lifecycle fork observation, and exposes the child row through `/command-center/lineage-roster`; missing, malformed, oversized, or duplicate IDs degrade with compact reason codes. | | `SubagentStop` with `subagent_complete` | Completes typed lineage graph state when safe IDs are available, records a bounded hero lifecycle stop observation for the child, and degrades missing child state without crashing. | | Git guard, cancel, unsupported subagent variants, and unknown named events | Git guard payloads are promoted into compact command-center Git diagnostics when safe attribution metadata is present and also emit a bounded compatibility `mission_event`. Other unsupported variants emit bounded opaque `mission_event` frames. | Hook File/Git attribution fields are intentionally compact. File-access hooks may send `repoRelativePath`, `repoRelativePaths`, and `attributionStatus` so the server can record file intents without storing broad absolute paths or file content. Git-guard hooks may send `gitOperation`, `gitRisk`, and `attributionStatus`; the server summarizes the risk class and never stores raw shell command text, stdout, stderr, diffs, patches, or secret values in command-center diagnostics. Hook lifecycle metadata is likewise compact. Session and subagent hooks may send `modelId`, `permissionMode`, `isolationMode`, `worktreeLabel`, `terminalLabel`, `listenerLabel`, `processLabel`, `eventCount`, `subagentId`, `parentAgentId`, `subagentType`, and a short `description`. Hooks and server ingest must not use these fields to store raw prompts, raw transcripts, transcript paths, terminal output, shell command bodies, broad absolute paths, provider payloads, tokens, or secret values. Oversized or malformed lineage identifiers remain observable through degraded reason codes instead of crashing ingest. The installed Claude Code compatibility map lives in `apps/hooks/hooks.json`. `apps/hooks/hooks.claude.json` mirrors that installed map, and `apps/hooks/hooks.codex.json` is the provider-specific Codex source template consumed by `factionos init --cli codex` and `factionos init --cli all` for user-level hook install and `/hooks` trust-review workflow. ## Local WebSocket On connection, the server attaches the socket and sends: 1. `connected` 2. `roster_update` 3. `mission_state` 4. `notice_board_hydrate` 5. `suggestion_update` 6. `scroll_state` 7. `achievement_state` 8. `task_queue_update` 9. `agent_template_update` 10. `mission_graph_update` 11. `guarded_action_update` 12. `command_center_plan_update` 13. `command_center_task_update` 14. `command_center_attention_update` 15. `command_center_executor_update` 16. `command_center_hero_lifecycle_update` 17. `command_center_execution_update` 18. `command_center_permission_update` 19. `command_center_file_intent_update` 20. `command_center_workpad_update` 21. `command_center_evidence_update` 22. `command_center_verification_update` 23. `command_center_handoff_update` 24. `command_center_diagnostic_update` 25. `command_center_channel_command_update` 26. `command_center_usage_update` The initial `mission_state` frame is compact by default: the local server sends the most recent `FACTIONOS_WS_HYDRATION_MISSION_LIMIT` missions, defaulting to `80` and capped at `200`. Non-active mission tool-use arrays are compacted to `FACTIONOS_WS_HYDRATION_TOOL_USE_LIMIT`, defaulting to `20` and capped at `100`. Imported-session heroes that are not referenced by that compact mission snapshot are omitted from the initial `roster_update`, while non-imported live heroes remain included. Full imported session history is still available through authenticated HTTP mission and hero snapshots. `notice_board_hydrate` carries the active-room Notice Board state as both canonical `messages` and compatibility `notices` arrays when applicable. Local posts emit `notice_board_message` with canonical `notice` and compatibility `message` aliases. Local or relayed resolutions emit `notice_resolved` with `noticeId`, `messageId`, and resolved notice aliases. Clients should normalize either alias form and should not treat an empty hydrate as permission to erase newer local state they have already received in the same socket lifecycle. `suggestion_update` carries the manager-owned Quest Board snapshot. It includes typed cards and compact counts only; clients should merge it as the source of truth for Quest Board state and keep `idle_suggestion` support only for compatibility. The remaining orchestration frames include compact counts, IDs, states, timestamps, revisions, bounded references, and graph or proposal summaries only. They do not include raw queue titles, raw proposal rationale, prompts, command bodies, terminal output, file contents, tokens, transcript paths, transcript contents, raw suggestion payloads, scan payloads, or broad absolute paths. `command_center_workpad_update`, `command_center_evidence_update`, and `command_center_verification_update` carry mission artifact metadata only. Verification frames include both verification attempts and linked review-gate entries so clients can reconcile review state with verification history in one local update. These frames may include blocked-category labels, safe target refs, safe source labels or repo-relative paths, revisions, and timestamps; they must not include raw prompts, command bodies, diffs, terminal output, file contents, transcripts, provider payloads, tokens, secrets, raw logs, replay buffers, export payloads, or broad absolute paths. `command_center_hero_lifecycle_update` carries compact hero lifecycle command entries only: command id, hero id, kind, state, revision, timestamps, optional model, permission, isolation, worktree, terminal, listener, process, event count, permission request, unavailable reason labels, managed session id, managed provider label, readiness, supported managed actions, linked execution run id, compact result status, and compact result summary. The browser Hero/Lineage tab reads this frame with `/command-center/heroes` and `/command-center/lineage-roster`, offers record-intent buttons for observed records, and offers stop/restart/message controls only for ready supported managed records. The tab disables offline, stale, unsupported, unavailable, and duplicate in-flight lifecycle actions and does not display raw prompt, transcript, terminal-output, command-body, provider-payload, token, or broad path data. Command-center REST and WebSocket frames are registry-gated local state only. They expose capabilities, counts, IDs, states, revisions, safe relative paths, docs paths, execution run state, and unavailable, approved-not-executing, proposal-only, ready, executed, or failed labels. File guarded-action entries execute only through structured file mutation requests and compact rollback evidence. Git guarded-action adapters, Git queue rows, and the Git workbench execute only allowlisted local Git operations through bounded argv construction, timeout handling, rollback notes, and redacted result summaries; push remains policy-blocked in queue and campaign flows. Terminal and container adapters may report `executor_ready` only when their PTY or runtime probes pass; otherwise they remain unavailable with repair guidance. Remote, Worker, hosted, channel, mission, handoff, and subagent families remain unavailable, approved-not-executing, observe-only, or proposal-only unless an explicit executor entry reports `executor_ready`. Frames must not carry raw prompts, command bodies, diffs, terminal output, stdout, stderr, file contents, provider payloads, tokens, secrets, raw logs, replay buffers, or export payloads. Client messages currently handled: | Type | Behavior | | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `hello` | No-op after initial attach. | | `ping` | Replies with `pong`. | | `permission_response` | Resolves pending permission, records paired command-center permission and attention decision state, emits command-center frames, then emits `permission_response`. | | `plan_approval` | Resolves pending plan approval, records paired command-center plan-approval permission and attention decision state, emits command-center frames, then emits `plan_approval_response`. | | `guarded_action_decision` | Approves or rejects a pending guarded action with duplicate-message suppression. Accepted approvals evaluate the executor registry, emit guarded-action plus command-center executor/execution updates, and complete with executed, failed, unavailable, or approved-not-executing state. | | `post_notice` | Compatibility client message that accepts canonical or legacy notice fields, stores the notice through the canonical manager, and broadcasts `notice_board_message`. | | `collect_scroll` | Collects and broadcasts a scroll. | | `hero_state_override` | Updates a hero state and emits `hero_state`. | Client messages are schema-validated before manager state changes. Malformed payloads return a compact `server_toast` warning without closing the healthy socket or echoing the raw payload. Duplicate permission and plan responses from the same socket lifecycle are ignored after the first accepted response. The command-center attention and permission decision records are local audit and cockpit state only; they do not execute tools, file edits, terminal commands, Worker actions, hosted jobs, or remote operations. Guarded-action approvals are separate registry-gated operations: default registry entries fail closed, while executor-ready entries such as the bounded Git workbench and Session 12 terminal/container adapters must prove capability readiness, bounded output, cleanup, rollback notes, audit, and redaction before they can return executed state. Event and message shapes are exported from `packages/protocol/src/events.ts`. The local server also emits `task_queue_update` after successful task queue mutations, `agent_template_update` after successful template availability or suggestion responses, `subagent_lineage_update` plus `mission_graph_update` after typed subagent lifecycle events, `command_center_hero_lifecycle_update` after lifecycle command or hook observations, and `guarded_action_update` after guarded-action creation, expiration, approval, rejection, or unavailable result transitions. Queue, lineage, lifecycle, and guarded-action frames carry counts, IDs, state, timestamps, revision or change metadata, optional references, bounded labels, safe terminal/Git execution summaries, and degraded or unavailable reason codes only. Queue terminal summaries may include command label, execution state, retryability, result summary, execution run id, and terminal session id. Queue Git summaries may include operation, path count, dirty/staged/conflict counts, policy-blocked state, retryability, result summary, execution run id, and recovery guidance. They do not carry raw queue titles, proposal rationale, prompts, command text, command bodies, diffs, paths, tokens, stdout, stderr, terminal output, transcript paths, file contents, or transcript contents. Campaign dispatch frames reuse those same safe summaries plus campaign/task ids and outcome buckets. They can report planning-only, completed, unavailable, failed, blocked, waiting, retryable, and partial-failure states, plus safe `failureCode` or `unavailableReason` labels, but never raw terminal or Git execution payloads. ## Local Orchestration Diagnostics `GET /diagnostics/orchestration` is the local CLI diagnostics snapshot. It returns manager availability, generated-at metadata, queue counts, template availability totals, mission graph counts, guarded-action counts, and command-center registry-gated counts with deterministic labels. The command-center section reports `posture: "registry_gated"`, capability status counts, recent execution counts, terminal queue execution counters, and Git queue execution counters without raw payloads. It inherits the local server's bearer auth, CORS, Origin, rate-limit, and body-size protections. The diagnostics snapshot does not expose raw queue titles, proposal rationale, prompts, command bodies, terminal output, Git diffs, Git paths, file contents, tokens, transcript paths, broad absolute paths, raw spool payloads, raw state files, or raw manager payloads. It does not execute queued tasks, approve guarded actions, run commands, mutate workspace files, or perform recovery. ## War Room Worker `apps/warroom` exposes a separate Cloudflare Worker API: | Method | Path | Purpose | | ------ | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `GET` | `/` | HTML landing page. | | `GET` | `/health` | Worker health probe with compact service, time, rate-limit, and deployment metadata. | | `POST` | `/rooms` | Create a room and return `{ code, leader, authority, roomRevision }`. Optional body: `{ leaderId?, leaderName?, leaderColor?, idempotencyKey? }`. | | `GET` | `/rooms/:code?participant=:id&authority=:token` | Read an authority-checked room snapshot with `revision`. | | `POST` | `/rooms/:code/join` | Request to join or refresh an existing participant. Body: `{ id?, name?, color?, authority?, idempotencyKey? }`; response includes `{ authority, roomRevision }`. | | `POST` | `/rooms/:code/approve` | Leader approves a pending participant. Body: `{ requesterId, approver, approverAuthority, expectedRevision, idempotencyKey? }`. | | `POST` | `/rooms/:code/reject` | Leader rejects a pending participant. Body: `{ requesterId, approver, approverAuthority, expectedRevision, idempotencyKey? }`. | | `WS` | `/rooms/:code/socket?participant=:id&authority=:token` | Authority-checked participant socket. | Health responses are intentionally small: ```json { "ok": true, "service": "factionos-warroom", "time": "2026-05-30T00:00:00.000Z", "rateLimit": { "enabled": true, "max": 240, "windowMs": 60000 }, "deployment": { "label": "custom-domain", "urlType": "custom-domain" } } ``` `deployment.urlType` is one of `local-wrangler`, `workers-dev`, `custom-domain`, or `unknown`. Health responses do not expose Cloudflare account ids, zone ids, tokens, request headers, client IPs, request bodies, room payloads, prompt content, command output, paths, exports, scans, media drafts, logs, or local diagnostics. The Worker enforces application-level rate limiting. A rate-limited response uses status `429`, `Retry-After`, `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` headers plus the deterministic `rate_limited` envelope. Room lifecycle routes and socket frames are validated through `@factionos/protocol`. Room authority is a Worker-issued opaque room-local token envelope with room code, participant id, role, room revision, issued-at, expires-at, and token fields. The Worker stores token hashes and authority metadata inside the room Durable Object; raw tokens are returned only to the requesting browser and must not be logged, displayed, exported, replayed, or persisted in browser storage. Snapshot, duplicate join, approve, reject, and socket setup require current authority. Leader approve/reject requests also require the expected room revision and an idempotency key. Duplicate decision retries with the same key return the stored response with `duplicate: true`; reused keys for a different decision return `replayed_authority`. Stale room revisions return `stale_room_revision` before mutation. Socket requests must use a WebSocket upgrade and include an approved participant id plus authority token. Failed setup returns compact error codes such as `expected_upgrade`, `missing_participant`, `missing_authority`, `invalid_authority`, `expired_authority`, `authority_mismatch`, `pending_approval`, or `forbidden_participant`. Accepted sockets relay only allowlisted redacted presence, cursor, focus, hero, mission, and room-notice frames, exclude the sender from remote broadcasts, and cap reconnect catch-up to 100 safe events. Allowed client socket frame types are `ping`, `warroom_presence`, `warroom_cursor`, `warroom_focus`, `warroom_hero_state`, `warroom_mission_state`, and `warroom_room_notice`. `ping` is accepted for liveness only and is not persisted. Persisted recent events and `warroom_pending_catchup` envelopes are revalidated through shared protocol contracts before storage and browser consumption. `remote_event` frames sent to peers include only the sender participant id and the validated safe event. Unknown types, unknown fields, invalid enum values, non-finite coordinates, bad participant ids, blocked nested keys, sensitive values, and oversized catch-up envelopes fail with `invalid_socket_frame` or `blocked_frame_field`. Catch-up summaries are counts, timestamps, and safe family labels only. Stable War Room authority and lifecycle error codes include `invalid_request`, `invalid_room_code`, `room_not_found`, `room_full`, `pending_approval`, `forbidden_participant`, `stale_join_decision`, `only_leader_can_decide`, `expected_upgrade`, `missing_participant`, `missing_authority`, `invalid_authority`, `expired_authority`, `authority_mismatch`, `stale_room_revision`, `replayed_authority`, `not_found`, `rate_limited`, `invalid_socket_frame`, and `blocked_frame_field`. Error envelopes expose only bounded code, message, and details fields; they must not echo authority tokens, request bodies, URLs, account ids, local paths, prompts, command output, exports, replay buffers, diagnostics, logs, or Worker secrets. This authority model is not hosted identity. It proves possession of one Worker-issued token for one participant in one room; hosted account lifecycle, organization membership, public replay hosting, analytics, production-hosted validation, mobile certification, real command execution, and trusted erasure remain Phase 07 or Phase 08 deferrals unless a later spec changes scope. The hosted identity diagnostics route preserves the same negative claim: room authority is not SSO, organization membership, public collaboration safety, analytics consent, production audit proof, or trusted erasure. The web War Room panel can use the optional Worker for room lifecycle, health diagnostics, approval, presence, reconnect, bounded catch-up, and allowlisted redacted federation. Empty, invalid, unreachable, timed-out, rate-limited, and malformed Worker states remain visible in the browser without blocking local cockpit use. Phase 05 closeout evidence in `.spec_system/archive/sessions/phase05-session07-war-room-validation-and-documentation-closeout/` validated focused Worker, protocol, and web tests plus app desktop/mobile browser states for disabled, diagnostics, join, pending, create, approved, connected, reconnecting, unavailable, and redacted remote-context behavior. This evidence is local/browser validation, not production-hosted app validation or a trusted identity claim. Phase 06 closeout evidence in `.spec_system/archive/sessions/phase06-session07-collaboration-isolation-and-mobile-validation-closeout/` validates the current authority contract, safe socket frame families, sender exclusion, bounded catch-up, web remote-context state, local isolation diagnostics, unsupported-route envelopes, guarded-action unavailable results, CLI and hook diagnostics, and app desktop/mobile behavior. The local server `/warroom` route remains a compatibility/status stub, not a room relay or Worker proxy. The evidence is local Vitest and Playwright coverage with mocked or same-origin Worker paths; it is not hosted identity, production-hosted validation, mobile certification, real execution, or trusted erasure. ## Phase 03 Local Orchestration Closeout Phase 03 local orchestration status is tracked in `.spec_system/archive/phases/phase_03/orchestration_gap_matrix.md`. Current source ships the Session 02 local task queue and agent template contract subset, the Session 03 typed subagent lineage and in-memory mission graph runtime, the Session 04 guarded-action proposal and decision runtime, and the Session 05 local web cockpit orchestration controls. Campaign graph state and guarded-action proposals are local, in-memory, bounded, and non-executing; template defaults are source-owned and compact. Metadata-only queue rows remain tracking state, while terminal executable queue rows dispatch through the local terminal runtime with safe execution summaries and scoped terminal session links. Git executable queue rows dispatch through the allowlisted local Git workbench for status, stage, and unstage with safe operation/count summaries; push remains policy-blocked by default, and broader Git workbench operations remain unavailable for queue dispatch. Session 06 adds a registry-gated guarded-action approval path: approved actions create bounded command-center execution runs and complete as unavailable or not-executed by default unless an explicit executor-ready entry runs and returns a redacted bounded result. Phase 19 Session 08 promotes Git into that bounded executor-ready subset, and Phase 20 Session 07 promotes structured file adapters when the local file mutation manager is ready. File adapters execute only schema-validated mutation requests and record compact `file_` command-center execution runs with rollback metadata. Git adapters run only the Git workbench allowlist, and direct Git workbench execution persists compact `git_` command-center execution runs. Phase 19 command-center permission and attention records are likewise local, bounded, non-executing audit state; approving an attention item records decision metadata and paired WebSocket updates only. Phase 19 Session 09 adds the bounded Hero/Lineage command-center surface: hook observations promote session spawn, hero stop, subagent fork, and subagent stop into lifecycle records; `/command-center/heroes/commands` records lifecycle intents with duplicate in-flight protection; `/command-center/lineage-roster` exposes filtered active/completed/failed/degraded roster rows derived from the mission graph; and the web cockpit renders those records with offline, unavailable, degraded, and duplicate-action states. The web cockpit consumes local REST snapshots and compact WebSocket frames for queue, templates, mission graph, guarded actions, command-center attention, file intents, diagnostics, execution runs, hero lifecycle, and lineage roster state; it can submit guarded-action and attention approve/reject decisions, Hero/Lineage lifecycle intents, plus File/Git workbench conflict, resolution, preview, and execution requests with expected revisions and idempotency keys. Current source does not ship broad subagent control actions beyond registered managed lifecycle `stop`/`restart`/`message` for owned local process or PTY sessions. Hook observations, external sessions, and provider mutation intents remain record-only or unavailable before execution. Current source also does not ship hidden terminal execution beyond explicit registry-ready entries, broad file mutation routes, remote Git push by default, CLI orchestration recovery commands, hosted queues, inbound chat commands, War Room federation, analytics dashboards, public replay hosting, or remote execution. Session 06 adds CLI and hook/listener diagnostics for the same local orchestration state. `factionos status` and `factionos doctor` report compact server, queue, template, mission graph, guarded-action, listener, hook, and spool posture. `factionos doctor --recover-orchestration` only removes stale listener PID files and malformed spool JSON entries under the configured FactionOS home; it is not unified erasure and does not delete settings, lifecycle files, archives, memory, browser state, valid spool files, session exports, or workspace files. Session 07 browser and focused test evidence validated this Phase 03 local subset without adding hosted queues, Worker federation, trusted inbound command execution, analytics, Docker isolation, remote execution, or media/release work. Phase 19 later adds local proposal-first channel intake under the command-center route family. The local server currently classifies historical file, git, terminal, task-queue, settings, collaboration, webhook, push, remote-access, and container route families through the deterministic 501 catch-all unless a listed shipped route handles the request first. War Room room APIs remain a separate Worker surface. Unapproved queue-adjacent paths such as broad sessions, suggestions, skills, issues, usage, and raw template routes remain planned 501 responses. Later approved sessions must add protocol contracts, validation, auth inheritance, redaction, tests, and docs before any further planned or deferred orchestration route family can be documented as shipped. ## Error Model Common responses: * `400 { error: "invalid_request", message, details? }` for missing or invalid request fields. `/event` malformed-body responses preserve `accepted: false`. * `404` for missing heroes, missions, scrolls, or rooms. * `409` when a room is full or a task queue or guarded-action mutation is stale, no longer pending, duplicated, or already in flight. * `429` when rate limits are exceeded. * `501 { error: "not_implemented", method, path, family, status, docs, message }` from the local server catch-all for historical or unknown routes that are not wired in the current build. Validation errors describe field names and reasons only. They do not echo prompts, command previews, tokens, request bodies, query strings, or private file path fragments. --- # 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/docs/api/readme_api.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.