> 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/apps/server/tests/fixtures/event-ingest/readme_event-ingest.md).

# Event Ingest Fixture Notes

These notes define the payload families used by the focused event ingest tests. They are hand-authored from current hook source and reference-only historical evidence; no runtime code or raw payload dumps are copied from `EXAMPLES/`.

## Claude Hook Payloads

Current handlers in `apps/hooks/src/` post to `/event` with both a Claude hook dispatch name and a hook-specific `type` value.

| Handler family                    | Dispatch key                               | Selected `type` values                                                                                                 |
| --------------------------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
| Session lifecycle                 | `SessionStart`, `UserPromptSubmit`, `Stop` | `internal_hero_spawn`, `hero_active`, `hero_idle`                                                                      |
| Tool observability                | `PreToolUse`, `PostToolUse`                | `file_access`, `bash_command`, `awaiting_input`, `input_received`, `permission_request`, `git_dirty`, `subagent_spawn` |
| Subagent and permission fallbacks | `SubagentStop`, `PermissionRequest`        | `subagent_complete`, `permission_request`                                                                              |

The critical compatibility rule is that later hook handlers send the saved Claude `sessionId` as both `sessionId` and `heroId`. Server tests should spawn a generated hero from `SessionStart`, then resolve later activity through that external session alias.

## OpenClaw Compatibility Payloads

Historical OpenClaw examples used `type`-only payloads. Session 01 intentionally supports this selected subset:

| `type`          | Expected server behavior                                                        |
| --------------- | ------------------------------------------------------------------------------- |
| `hero_active`   | Materialize or reuse a hero for `sessionId`.                                    |
| `mission_start` | Start a mission for the resolved session hero.                                  |
| `file_access`   | Emit generic tool use plus first-class `file_access` when a mission is active.  |
| `bash_command`  | Emit generic tool use plus first-class `bash_command` when a mission is active. |
| `hero_idle`     | Complete the active mission and return the hero to idle.                        |

Unsupported historical event types stay accepted only as bounded opaque `mission_event` frames when a dispatch key exists.

## Codex Lifecycle Payloads

`codexLifecycle.ts` defines the sanitized Session 02 fixture for server ingest tests. It replays this local-only lifecycle:

`SessionStart -> UserPromptSubmit -> PreToolUse Bash -> PreToolUse apply_patch -> PermissionRequest -> SubagentStart -> SubagentStop -> Stop`

The fixture intentionally exercises Codex snake\_case aliases such as `session_id`, `turn_id`, `hook_event_name`, `tool_name`, `tool_use_id`, `request_id`, `agent_id`, `parent_agent_id`, and `agent_type`. The server normalizer canonicalizes these aliases at the `/event` boundary before routing through the existing hero roster, mission manager, permission event, tool-use, and typed subagent lineage paths.

The fixture uses `cli: "codex-cli"` so tests prove the server keeps the protocol-owned OpenAI CLI vocabulary instead of falling back to Claude.

`codexExtendedLifecyclePayloads` keeps the original lifecycle order but inserts additional synthetic cases before `Stop`:

* MCP file-like tool activity with a bounded `mcp__filesystem__read_file` tool name and a redacted file label.
* `PreCompact` and `PostCompact` opaque events with compact turn metadata.
* An unknown named Codex event that includes synthetic sensitive sentinels only so redaction tests can prove prompts, commands, patch text, transcript paths, and MCP argument bodies are not promoted.

These fixtures are source-backed approximations of current FactionOS hook handler and server ingest behavior. They are not live Codex transcript captures, they do not claim Codex will always emit these exact optional fields, and they do not validate Codex hook trust or live `/hooks` review. Live or fixture- replayed cockpit validation remains owned by Phase 11 Session 03.

## Privacy Rules

* Use synthetic session ids such as `sess_test_123`.
* Use synthetic paths such as `/workspace/demo/src/file.ts`.
* Do not include real prompts, usernames, home directories, commands, tokens, or transcript excerpts in fixtures.
* Do not include raw patch bodies, command output, MCP argument bodies, hosted telemetry payloads, provider tokens, transcript paths, or broad local paths in promoted Codex fixtures. Use safe summaries such as `apply_patch 1 file (+8/-2)` and bounded IDs such as `turn_codex_001`.
* When a redaction probe needs a sensitive-looking value, keep it synthetic, put it only in a test fixture that asserts it does not persist, and use stable sentinel labels rather than provider data.


---

# 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/apps/server/tests/fixtures/event-ingest/readme_event-ingest.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.