Event Catalog

Every event Plan Forge emits over the WebSocket hub and the run journal, grouped by family, with emitter, trigger, the key payload fields, consumers, and retention. This appendix is the ebook companion to the canonical schema at pforge-mcp/EVENTS.md: the source-of-truth JSON examples live in the schema file; this page provides the orientation, classification, and lifecycle guidance that schema files rarely carry.

Orientation

Plan Forge emits 38 distinct event types across eight families. The two most-watched families are lifecycle (run/slice progression) and LiveGuard (drift, incidents, secret scans). The remaining six families round out the picture: skills, Crucible, bridge approvals, escalation/CI, the lone client→server message, and the Tempering validation event.

Every emitted event shares a five-field envelope (documented below). Two enums, source and security_risk, are referenced throughout. Subscription mechanics are at Consuming the stream, and retention rules for events that escape the WebSocket (logged to .forge/runs/, posted to OpenClaw, etc.) are at Retention.

Common envelope

Every event, lifecycle, skill, LiveGuard, all of them, carries the same five-field envelope. Consumers can rely on these fields being present even on event types this catalog does not list (forward-compatible by design).

source enum

The nine subsystems that emit events. New subsystems are added rarely; existing values are never repurposed.

security_risk enum

The risk classification attached to every event at emission time. Subscribers (and OpenClaw) can filter by this field to focus on high-risk activity.

Lifecycle events

source: "orchestrator" (one exception). The Progress tab on the dashboard is driven entirely by this family; the run journal at .forge/runs/<run-id>.jsonl persists every one of them for replay.

Full JSON examples: EVENTS.md — Event Types.

Skill events

source: "skill". Emitted by skill-runner.mjs on every forge_run_skill invocation. The structure mirrors lifecycle events deliberately: dashboard code reuses the same renderer for both families.

Crucible events

source: "crucible". Emitted as smelts progress through the idea→hardened-spec funnel. The payload is wrapped in a data object, matching the LiveGuard convention rather than the flat-payload lifecycle convention, consumers should branch on family rather than assume one shape.

Bridge events

source: "bridge". Emitted by the notification bridge when it pauses for external approval or dispatches a webhook. Configure the bridge via the extensions/ notify-* extensions and PFORGE_BRIDGE_SECRET (see Appendix U — Server Ports).

Escalation & CI events

source: "orchestrator". Two events that mark deliberate routing decisions: quorum escalation when a slice's complexity score exceeds the threshold, and CI dispatch when a plan run triggers a GitHub Actions workflow.

Client→server messages

The only inbound message type the hub honours. Send it once after opening the WebSocket to identify your client in the session registry (visible in the dashboard's Connections badge).

LiveGuard events

source: "liveguard". The production-ops feedback family, emitted by forge_drift_report, forge_incident_capture, forge_alert_triage, forge_secret_scan, forge_fix_proposal, and the watcher tools. Most carry security_risk: "low" or higher; filter on security_risk >= medium to drive paging.

Anomaly codes used in watch-anomaly-detected: stalled, tokens-zero, high-retries, slice-failed, all-skipped, gate-on-prose, model-escalated, quorum-dissent, quorum-leg-stalled, skill-step-failed.

Tempering events

source: "audit". One event, emitted only on the green leg of the bug lifecycle, when forge_bug_validate_fix confirms all scanners pass re-run. There is no matching tempering-bug-validated-broken; the validation tool returns the result to the caller without emitting on the red leg, to keep the dashboard's Bugs Fixed tile a positive-only feed.

Consuming the stream

The simplest possible consumer, a Node script that prints every event:

import WebSocket from "ws";

const ws = new WebSocket("ws://127.0.0.1:3101");

ws.on("open", () => {
  ws.send(JSON.stringify({ type: "set-label", label: "my-consumer" }));
});

ws.on("message", (raw) => {
  const evt = JSON.parse(raw.toString());
  // Filter however you like:
  if (evt.security_risk === "high" || evt.security_risk === "critical") {
    console.error(`[HIGH] ${evt.type}`, evt);
  } else if (evt.type?.startsWith("slice-")) {
    console.log(`[LIFECYCLE] ${evt.type} sliceId=${evt.sliceId} status=${evt.status ?? ""}`);
  }
});

On connection the hub replays buffered events from the in-memory ring (default ~500 events, see hub.mjs). To enable bearer-token auth on the hub, set PFORGE_BRIDGE_SECRET, the consumer then sends Authorization: Bearer <secret> on the upgrade request.

Retention

Events live in up to four places after emission. The retention rules below tell you how long each consumer keeps them, and which fields each consumer can rely on having.

See also

• pforge-mcp/EVENTS.md, the canonical JSON-schema source for every event. This appendix is the orientation and classification companion; full payloads live there.
• Chapter 29 — Integrating from Outside, building external consumers (dashboards, paging, custom bridges) that subscribe to the hub.
• Compliance & Data Residency — Observability Export, OTel collector wiring; many of the events in this catalog are also emitted as OTel spans.
• Chapter 12 — The Dashboard, the reference UI consumer; reading its source is the fastest way to see how each event family is rendered.
• Appendix T — openclaw, configuring the optional OpenClaw analytics sink.
• Appendix U — Server Ports, PFORGE_BRIDGE_SECRET, PLAN_FORGE_WS_PORT, and other env vars that gate hub access.
• Customization — Lifecycle Hooks Reference, the hooks that fire in response to lifecycle events (postSlice, preDeploy, etc.).