# tools/matrix-presence-harness — RFC-001 P1 validation (A1–A5)

> **DEV-ONLY. LOCAL SANDBOX.** Drives the local `infra/matrix` Synapse only.
> Never point it at live infra.

The dev validation harness for the presence slice. It is the **minimal P1
provisioner** + an end-to-end demo that proves the acceptance criteria against
a real Synapse.

## Pieces

- `provision.ts` — the **minimal provisioner**: registers ≥3 agent MXIDs, creates
  the fleet presence room, joins the agents. Reuses the existing tested
  `@mosaicstack/appservice` intent library (register / createRoom / join). It is
  deliberately **not** the P2 appservice (no auto-enroll / taxonomy / token minting).
- `agent-proc.ts` — one presence agent as its **own OS process** (via
  `@mosaicstack/comms`): joins the fleet room and heartbeats `mosaic.presence`.
  Standalone so the harness can `SIGKILL` it for a true hard-kill (A3).
- `validate.ts` — provisions, spawns the agents, then asserts:
  - **A2** ≥3 agents show **online** in the fleet room.
  - **A3** a `SIGKILL`'d agent flips to **offline within `dark_threshold`**,
    deterministically (heartbeat-age based, not native-presence timeout), while
    survivors stay online.
  - **A4** prints the human-readable fleet liveness board.
- `run.sh` — wires dev secrets + env and runs `validate.ts` over the self-signed
  TLS endpoint (A1). Exits non-zero on any failed assertion.

## Usage

```bash
../../infra/matrix/dev-up.sh     # bring Synapse up first
./run.sh                         # provision + validate (A2/A3/A4)
```

Tunables (env): `HEARTBEAT_INTERVAL_MS` (1000), `MISS_TOLERANCE` (2),
`DARK_THRESHOLD_MS` (6000), `AGENT_SLUGS` (`alpha,bravo,charlie`),
`VICTIM_SLUG` (`charlie`), `MATRIX_CS_URL` (defaults to the TLS endpoint).

## Note on `NODE_TLS_REJECT_UNAUTHORIZED=0`

`run.sh` sets this **only** because the dev homeserver uses a self-signed cert.
It is a dev convenience for exercising the SDK over TLS and must never be used
against a real CA-issued endpoint.