Gossipper run

gossipper-run — Scenario Execution

Invoke Gossipper. Pinned to Gossipper 0.1.60-rtcpmuxpatch2 (sipcapture/gossipper on main, audited 2026-05-18).

When to use this skill

• Run an existing scenario (one-shot CLI or long-running).
• Pick transport mode, rate, concurrency, output flags, correlation IDs.
• Author a 3PCC peer file (CSV name;host:port).
• Convert a PCAP to scenarios via gossipper pcap2scenario.
• Smoke-test a freshly authored scenario before the real run.
• Build a run-profile JSON for systemd / long-running deployment.
• Wire -health_* thresholds when given threshold values.
• Interpret a Gossipper exit code at the operational level.

When NOT to use this skill

Task	Owner
Write or modify a scenario XML	gossipper-build
Decide what XML belongs in the scenario	gossipper-build
Parse summary JSON, trace CSVs, call records	gossipper-analyze
Classify failures (timeout / unexpected_sip / …)	gossipper-analyze
Decide threshold values for -health_*	gossipper-analyze or user
Cross-correlate with HEP/qryn production traffic	gossipper-analyze

This skill picks flags and runs the process. It does not decide what the scenario should do, and it does not interpret what came out beyond exit-code level (0 / 1 / 2).

Inputs from gossipper-build

Every scenario authored by gossipper-build starts with a top-of-file XML comment block. Read it — don't re-derive from message content.

<!--
  Scenario: <name>
  Role: <UAC | UAS | 3PCC-master | 3PCC-slave>
  Intent: <one-paragraph description>
  Partial-support features used: <list, or "none">
  Required runtime vars:
    -s <service>        ...
    -au <username>      ...
    -ap <password>      ...
    -rsa <host:port>    ...
    -mi <media_ip>      ...
    -mp <media_port>    ...

  3PCC coordination (if applicable):
    -cmd_peers peers.txt
    -cmd_name <master|slave>
    -cmd_listen_port <port>
-->

Two sections drive flag selection:

• Required runtime vars → the flags you must set on the command line.
• 3PCC coordination → you author the peer file (see below) and wire -cmd_* flags.

If the block is missing or thin, ask the user — don't guess.

Decision tree — pick the launch form

Use case	Launch form
Single scenario, finite calls, exit when done	gossipper -sf … -rsa … -m … -r …
Repeatable named runs, ops-friendly	gossipper -config profile.json -run-alias=<name>
Long-running management UAS + HTTP API	gossipper server -config flat.json
Composite: UAS listener + parallel UAC clients	gossipper server -config flat.json (with server + clients[])

Both run-profile JSON shapes and the systemd pattern are in references/patterns.md.

Common invocation patterns

Minimal flag set per pattern. Add output flags from the next section.

Intent	Invocation
Vanilla UAC, finite	gossipper -sf uac.xml -rsa <host:port> -r 5 -m 100
UAS listener	gossipper -sf uas.xml -sn uas -i <bind_ip> -p 5060
REGISTER with digest	add -au <user> -ap <pass> -s <service>
3PCC master	add -cmd_peers peers.txt -cmd_name master -cmd_listen_port <port>
3PCC slave	add -cmd_peers peers.txt -cmd_name slave -cmd_listen_port <port>
INVITE + RTP media	add -mi <media_ip> -mp <media_port>
TLS client	-t l1 -tls_ca <ca.pem> (+ -tls_skip_verify=false for strict)
TLS server	-t l1 -tls_cert <cert.pem> -tls_key <key.pem>

For TLS, see the gotcha below: -t s1 / sn are UDP, not TLS.

Full flag surface → references/cli-reference.md.

Output flags — always wire these

Without output flags, gossipper-analyze has nothing to read. Defaults:

Flag	Purpose	When to omit
-summary_json <path>	Top-level run summary, schema gossipper_summary_v1	Never — always set
-trace_stat -fd 5	Per-5s stats CSV (*_stats.log)	Only for one-call debug runs
-call_records_jsonl <path>	Per-call records (gossipper_call_record_v1)	If analyze is summary-only
-trace_msg -message_file <path>	Full SIP send/recv human-readable	Debug only — verbose
-trace_err -error_file <path>	Unexpected SIP + runtime errors	Always useful, cheap
-record_wav_dir <dir>	Per-call WAV capture, Call-ID keyed (16-bit PCM mono 8 kHz; add -record_wav_duplex for stereo)	Most runs — set only when media-quality investigation needs per-call audio

-fd <n> auto-enables -trace_stat. The full output channel matrix (rtt, screen, counts, shortmsg, error_codes, WAV capture) → references/cli-reference.md.

Correlation identifiers

Set these so gossipper-analyze can join run outputs with HEP traffic in HOMER/qryn and OTLP events downstream.

HEP (SIP signaling mirror):

Flag	Value pattern	Joins on
-hep_addr <host:port>	HOMER/heplify-server endpoint (default port 9060)	Enables HEP3 mirror
-hep_capture_id <n>	Distinct integer per run	HEP filtering
-hep_password <pw>	If destination requires auth	HEP auth

OTLP (event stream):

Flag	Value pattern	Joins on
-log_otel_endpoint <host:port>	OTLP receiver	Enables OTLP export — required for any OTEL data to flow
-log_otel_proto <grpc|http>	Default grpc	Wire protocol
-log_otel_insecure	Set for plaintext (lab / intra-VPN)	TLS off
-log_attr self_tag=<id>	Per-run unique ID (e.g. gossipper-<region>-<ts>)	OTEL resource attr — the run-correlation key
-log_attr <other>=<val>	Free-form (repeatable)	Additional resource attrs

For autonomous Cowork-scheduled runs: generate one logical run identifier (string), then derive a correlated pair:

• self_tag=<run_id> — full string (e.g. cowork-soak-20260521T0930Z)
• hep_capture_id=<int_derived_from_run_id> — deterministic mapping, e.g. CRC32(run_id) mod <reserved_capture_id_range>

Analyze consumes both. The string→int derivation must be reproducible (or logged in the Run report's Notes) so cross-channel pivot works. A single identifier cannot serve both channels — hep_capture_id is int, self_tag is string.

3PCC peer file

When the scenario block declares 3PCC coordination, this skill authors the peer file. Format is CSV, one row per peer:

master;<master_ip>:<master_cmd_port>
slave;<slave_ip>:<slave_cmd_port>

Naming matches -cmd_name on each instance. Slave must be running before master starts — master immediately tries to connect.

Full coordination pattern (multi-slave, init-block, Call-ID adoption) → references/patterns.md.

pcap2scenario

Convert a captured PCAP to paired UAC/UAS XML scenarios:

gossipper pcap2scenario -in capture.pcap -out-uac uac.xml -out-uas uas.xml

The produced XML often needs cleanup before reliable runs — CDATA fixes, timing tuning, partial-support feature trimming. Hand the raw output to gossipper-build, then come back here to run it.

Loopback smoke run (optional pre-flight)

Catches gossipper-specific XML loader complaints that well-formedness validation (build's job) doesn't surface:

gossipper -sf scenario.xml -sn uas

Binds locally and starts the UAS listener; the scenario goes through gossipper's stricter XML loader during startup. Send SIGINT (Ctrl-C) to exit cleanly. Load-time errors surface immediately as stderr output with exit code 1. Run once after authoring, before the first real run. Not required on every subsequent run.

Health thresholds

When the user (or analyze) provides threshold values, wire -health_* flags on the command line. On clean shutdown, gossipper compares final summary metrics against thresholds; breach exits 2.

This skill sets the flags. It does not decide the values — threshold values come from analyze or directly from the user. Full flag list → references/cli-reference.md.

Exit codes (operational interpretation only)

Exit	Meaning	Operational action
0	Clean run, no health breach	Hand off outputs to analyze
1	Engine or parse error	Re-check scenario (hand back to build) or flags
2	Health threshold breach	Run completed; analyze for the failing dimension

Do not classify failure shapes here (timeout vs unexpected_sip vs transport_error etc.) — that's the analyze skill's vocabulary.

Always-remember gotchas

1. -m 0 is not "unlimited" — it means zero calls. Use a large number, or -config with total_calls: 0 in the JSON (which IS unlimited in run-profile form).
2. -fd <n> auto-enables -trace_stat — don't set both.
3. -t s1 / sn are UDP aliases, not TLS, despite the "s" prefix. TLS server modes are l1 / sl. TLS client is l1 / cl.
4. Port 5060 as non-root needs CAP_NET_BIND_SERVICE (not CAP_NET_RAW — gossipper uses normal sockets).
5. -summary_json is written only on clean shutdown. SIGKILL loses it. Use SIGINT to drain in-flight calls and finalize.
6. HTTP management API is OPEN by default — -api_addr :8080 has no auth unless wired via -config JSON. Don't expose beyond VPN.
7. No Docker image is published. Build your own; package layout is under /usr/local/gossipper/ per the upstream conventions.

Going deeper

Read on demand:

• references/cli-reference.md — full flag surface grouped (engine, transport, rate, auth, TLS, media, output/trace, HEP, OTEL, profiling, 3PCC, health, config bootstrap), subcommand routing, transport mode matrix, signals (SIGINT drain, SIGUSR1 screen snapshot), exit codes, HTTP management API (/api/v1/* and /api/v2/* with -ui_data_dir).
• references/patterns.md — run-profile JSON (aliased form for root command, flat composite for gossipper server), 3PCC peer authoring + multi-slave coordination, pcap2scenario workflow, loopback smoke pattern, HEP/OTEL correlation wiring for autonomous runs, health threshold authoring, systemd unit pattern, deployment notes.

Run report (handoff to gossipper-analyze)

After every run, surface this structured block in chat. Analyze consumes it to know which artifacts to ingest and which correlation identifiers to use.

Run report
----------
Invocation:           <command line, or profile path + alias>
Started / ended:      <ISO 8601> / <ISO 8601>
Exit code:            <0 | 1 | 2>

Outputs produced:
  summary_json:       <path>
  trace_stat:         <path or omitted>
  call_records_jsonl: <path or omitted>
  message_file:       <path or omitted>
  error_file:         <path or omitted>
  wav_dir:            <path or omitted>

Correlation identifiers:
  hep_capture_id:     <int or omitted>
  self_tag:           <id or omitted>
  hep_addr:           <host:port or omitted>
  otel_endpoint:      <host:port or omitted>

Notes:
  <anything operationally relevant — e.g. SIGINT drained, retries observed,
   any flag fallbacks that happened>

Hand this block to gossipper-analyze. Do not also paste the summary JSON content here — analyze reads files itself.