> 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/runbooks/incident-response.md).

# Incident Response

## Severity

| Level | Description                                                            | Initial response |
| ----- | ---------------------------------------------------------------------- | ---------------- |
| P0    | Release-blocking data leak, destructive action, or total app outage    | Immediate        |
| P1    | Core local ingest, WebSocket hydration, hook install, or export broken | Same day         |
| P2    | Optional adapter, Worker, demo deploy, or LLM endpoint broken          | Next working day |
| P3    | Cosmetic, copy, or non-blocking documentation issue                    | Normal backlog   |

## First Checks

```bash
git status --short
npm install
npm run format:check
npm run lint
npm run typecheck --workspaces --if-present
npm test
curl http://localhost:2468/health
```

Check local FactionOS logs when hooks are involved:

```bash
tail -f ~/.factionos/hooks.log
ls ~/.factionos
```

## Local Server Unreachable

Symptoms:

* `curl http://localhost:2468/health` fails.
* Web app cannot hydrate.
* Hooks spool events or appear silent.

Response:

1. Start the server with `npm --workspace apps/server run dev`.
2. Confirm `PORT` is not occupied or overridden incorrectly.
3. Check `.env.local` for `FACTIONOS_MOCK`, `CORS_ORIGINS`, and rate-limit values.
4. Run `npm --workspace apps/server run typecheck`.
5. Run server route tests with `npx vitest run apps/server/tests`.

## Web App Shows No Live Events

Symptoms:

* Server health is OK, but roster or mission panels stay empty.
* Browser console shows WebSocket errors.

Response:

1. Confirm the web dev server is running with `npm --workspace apps/web run dev`.
2. Confirm WebSocket URL is `ws://localhost:2468/`.
3. Check whether `FACTIONOS_MOCK=false` disables synthetic events.
4. Verify browser localStorage is not carrying malformed replay/settings state.
5. Run `npx vitest run apps/web/tests`.

## Hooks Do Not Spawn Sessions

Symptoms:

* Claude Code activity does not appear in FactionOS.
* `factionos status` or `doctor` reports missing hooks or listener issues.

Response:

1. Run `factionos doctor`.
2. Confirm `CLAUDE_PLUGIN_ROOT` resolves to the installed hook package.
3. Confirm `FACTIONOS_SERVER_URL=http://localhost:2468`.
4. Check `~/.claude/settings.json` and `~/.claude/settings.backup.json`.
5. Check `~/.factionos/hooks.log` and listener logs.
6. Re-run `factionos init` only after preserving user-owned hook settings.

## Adapter Not Posting

Symptoms:

* Server emits events, but Discord, Telegram, or webhook destination receives nothing.

Response:

1. Confirm `FACTIONOS_WS_URL` points to the server WebSocket.
2. Confirm required adapter credentials are present.
3. Check severity filter and throttle settings.
4. Prefer compact webhook payloads for external systems.
5. Confirm logs redact URLs and tokens before sharing diagnostics.

## War Room Worker Failure

Symptoms:

* `/health` on the Worker fails.
* Room create, join, approve, or socket connect fails.

Response:

1. Run `npm --workspace @factionos/warroom run typecheck`.
2. Run `npx vitest run apps/warroom/tests`.
3. Run `curl --fail --show-error --max-time 8 https://warroom.faction-os.com/health`.
4. Review `docs/runbooks/war-room-operations.md`.
5. Use `npm --workspace @factionos/warroom run tail` for deployed Worker logs only when needed.
6. Check rate-limit settings and Cloudflare dashboard WAF rules.
7. Confirm the web panel shows disabled, invalid URL, unavailable, timed-out, rate-limited, malformed, healthy, or connected states without exposing secrets or raw payloads.
8. For redacted federation regressions, preserve the failing local test or browser evidence path and summarize the state transition; do not paste raw room frames, prompts, commands, transcripts, tokens, paths, exports, replay buffers, scan payloads, media drafts, or diagnostics into shared notes.

## Suspected Privacy Leak

Response:

1. Stop adapters and any deployed room relay.
2. Preserve logs and exported payload samples locally.
3. Identify whether prompts, file contents, paths, tokens, webhook URLs, or PII left the local machine.
4. Rotate affected external credentials.
5. Queue the finding for the rebuilt security register; use `docs/SECURITY-COMPLIANCE.md` as the archived baseline.
6. Add regression tests before re-enabling the integration.


---

# 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/runbooks/incident-response.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.