rmagent-fr — The Flight Recorder
Follow one work id without a span warehouse. The reliability half of the
RMAgent security observatory: security asks who walked, reliability asks why
it felt slow — same ticket, two questions, one case file.
This is the Flight Recorder engine, split out of rmagent-windows so the
tracing half can be reasoned about (and loaded) on its own. rmagent-windows
remains the complete, runnable skill; rmagent-so is the witness-question
half. The three skills share one constitution.
Needle tier 0 — offline extraction and drift
Alongside the Laya matrices, every skill in this family can call
needle — a 121M on-device model (Cactus Compute Needle, ~35 MB, no
network, no keys, ~100 MB RAM) installed once on the jump host, never on
the witnesses. It is the free tier of the judgment stack: needle extracts
and compares offline, Laya judges, the LLM reasons.
Two scripts ship in scripts/:
needle_extract.py — typed field extraction from a witness fragment
(count, source_ip, …). Rigid tokens (numbers, IPs) are reliable;
semantic fields are not, so the wrapper validates what it can (:ip,
:int) and blanks anything it cannot trust — never a guess.echo "<attest answer>" | scripts/needle_extract.py user count:int source_ip:ip --json
needle_drift.py — baseline-drift detection via needle's 3072-dim
embeddings: record what an answer normally looks like, score today's
answer against it (similar / drifted / changed, thresholds calibrated
empirically). Separates shape and topic, not field values — value drift
stays the job of the field rules and correlate joins.echo "<routine answer>" | scripts/needle_drift.py record <host>-<question>
echo "<today's answer>" | scripts/needle_drift.py score <host>-<question>
The engine runs in-process on the jump host (the wrapper finds a Python
with cactus-needle — set NEEDLE_PYTHON if it lives elsewhere). No port
is opened, nothing is installed on any witness, and the baselines are
kilobyte holes under ~/.rmagent/needle-drift/, not a lake. On an
air-gapped estate this tier keeps working — and the judgment tier with it: Laya is offline too (pre-seed its HF-cache checkpoint on air-gapped hosts), so no matrix judgment waits for a connected session.
Non-negotiables
- The ticket is a grain, not a tag. It propagates through every hop, every
span, every index record — and is queryable back.
- A case file, not a lake. Megabytes. Adaptive sampling keeps join keys on
every walk and full detail only when something was found.
- The budget belongs to the identity. Depth ≤ 8, fan-out 3, 32 KB pull cap.
An unconstrained hunter is a worm.
- Context propagates, data does not. The STC carries identifiers; the
answers stay on the machine that produced them.
- Clock skew is detected on every walk. Cross-host timelines you can trust.
The scripts
| Script |
Role |
scripts/stc.py |
Security Trace Context — case; principal; window; depth; ticket; trigger. The distributed circuit breaker. Immutable; child() returns depth+1. Rejects ;/= in fields (injection fix). |
scripts/traj.py |
The trajectory — append-only DAG of observations, thoughts, actions, results, holes, forks, merges. The recorder's reasoning chain, replayable. |
scripts/hop_index.py |
Cross-case memory — keyed (host, principal, logonid, kind, case). by_principal(), by_logonid(), seen_before(). Adaptive sampling: full detail when smoke, join keys when clean. |
scripts/causal.py |
Causal graph — nodes (host, principal, logonid), edges hops. blast_radius() computes everything reachable from the compromise. |
scripts/dthinker.py |
Distributed thinker — temporal_cluster, cross_host_chain, session_correlation, repeat_offender across the hop index. |
scripts/thinker.py |
Persistent reasoning between knocks — acceleration, cliffs, persistence, correlation, silence, DNS tunneling over census history. |
scripts/trace.py |
Trace query API — trace.py CASE-X, --ticket PAY-4419, --principal Admin, --list. Merges trajectory + hops + holes + causal graph. get_trace() for the gateway. |
scripts/trace_merge.py |
Pull-merge multi-jump-host — fan out over SSH, dedup, merge. Two-site estates without shared state. |
scripts/otel_emit.py |
Every trajectory entry becomes one OTel span → RTerm gateway → Grafana/Jaeger/Splunk. |
scripts/census.py |
The minute watch — attest on all witnesses, 2 misses = Critical → Telegram. Writes the history the thinker reasons over. |
The ticket join — one tape, two questions
case.py open --ticket PAY-4419
hunt.py --case-dir cases/<the case> # ticket inherited from case.json
trace.py --ticket PAY-4419
The ticket propagates through the whole trace: every question, every hop,
every span, every index record. Rev 18: case.py open --ticket now PERSISTS
the ticket in case.json and hunt.py inherits it from there — the ticket
no longer has to be typed twice (the old flow accepted it at case-open and
dropped it). trace.py reconstructs it from the trajectory's STC line, or
falls back to case.json. Query it back from either side of the house. That
is the Flight Recorder's actual product.
Rev 18 hardening
- Trace ids are collision-safe.
stc.trace_id is now sha256(case)[:32] —
the old scheme gave two cases opened in the same second (and every default
admin-walk hunt) the SAME OTel trace id, merging unrelated walks in
Grafana.
- The hop index ages out honestly. Entries older than
KEEP_DAYS (30)
are shed at trim; seen_before() returns (seen, honest) — honest=False
means "beyond what the index can see", never a confident False.
- Blindness reaches the thinker. census records
blind_count and
raw_4624_24h in its history; three consecutive blind censuses produce a
CRITICAL thinker finding. Census owns the silent-host book (Rev 17's L2
cooldown): its knock clears/marks silence, so one blip never blinds a hunt.
- OTel spans reach a live gateway. The emit URL is configurable
(
RMAgent_OTEL_URL env → ~/.rmagent/config.json otel_gateway_url →
default http://127.0.0.1:17888), with optional bearer token. The old
hard-coded port 8765 pointed at nothing — 326 spans were found buffered,
zero delivered.
trace_merge resolves current trees. The remote script no longer
hard-codes the legacy path (now resolved via rmagent-core loader).
The honest limit
The business side must emit events carrying the ticket. The security half is
done — a ticket given at case-open flows through everything. The reliability
half needs the payment system to stamp PAY-4419 into its own events, which is
an integration with whatever runs the payments, not a feature of this skill.
Laya-assisted intake and hop routing
Two recurring judgments of a walk can be made by a fast, typed decision model
(Laya, via the use-laya skill): is a symptom worth a walk at all, and which hop
should the walker visit next? Two matrices live in decisions/:
intake_triage.json — at intake: worth_walking / urgency / next (start the
walk, gather more context, or record and decline).
hop_route.json — mid-walk, over the trajectory so far: which plane to walk
next (user, edge, service, data, queue, platform, network, business), close
the walk and synthesize, or hand the choice to the LLM.
echo "<symptom report>" | scripts/laya_decide.py intake_triage
scripts/laya_decide.py hop_route --state-file trajectory.json
Policy: confidence below 0.5 is flagged ESCALATE — the LLM (not Laya) reasons
about ambiguous walks. Verdicts are advisory; the trajectory DAG, the STC, and
the pull-only rules are unchanged.
Relationship to the other skills
| Skill |
Half |
rmagent-windows |
The complete skill — both halves, fully runnable |
rmagent-fr |
This skill — the Flight Recorder (tracing) half |
rmagent-so |
The witness-question (Security Observatory) half |
rmagent-redteam |
The drill — stages artifacts, scores detection |
rmagent-actuate |
Phase 1 response — named, journaled, reversible |
rmagent-linux |
The Linux/macOS sibling of rmagent-so |
Enterprise scope, sizing & cadence
- Scale: a case file is megabytes by design (adaptive sampling: join
keys always, full detail only on smoke). 100 concurrent open cases ≈ tens
of MB under
~/.rmagent/cases/ — no lake, no warehouse. case.py prune
ages closed cases out (KEEP_DAYS default 30).
- Sizing the walks: depth ≤ 8, fan-out 3, 32 KB pull cap — one full walk
≈ ≤24 questions ≈ ≤1 min of witness time. Budget belongs to the identity;
an unconstrained hunter is a worm.
- Cadence: open a case per ticket/symptom (not per sweep). Census is the
only standing loop (5-min cron); hunts fire on trigger. OTel spans flow to
your existing Grafana/Jaeger/Splunk via the configurable gateway —
the Flight Recorder complements APM, never replaces it.
- No-Python estates: the engine runs on the jump host you control;
witnesses only ever see their OS-native question payloads (
.ps1 on
Windows, .sh on Linux). rmagent-windows/scripts/ops/rmagent-ops.ps1
and rmagent-linux/scripts/ops/rmagent-ops.sh reproduce the health/
doctor/watchdog loop natively if even the jump host must stay Python-free.
- The worked case: EXAMPLES.md carries a full 2026-10-04 incident
walkthrough — intake triage, hop table with join keys, the
"healthy-answer-vs-degraded-box" lesson, and holes recorded as holes.
1---2name: rmagent-fr3description: >4 The Flight Recorder — follow one work id (a ticket, a payment, an incident)5 across the estate without a span warehouse. The tracing half of the RMAgent6 security observatory: a Security Trace Context (STC) carries case, principal,7 window, depth, ticket and trigger through every hop; the trajectory records8 the reasoning chain as an append-only DAG; the hop index remembers whether a9 principal has appeared before; the causal graph computes blast radius from10 kilobytes; OTel spans land in Grafana/Jaeger next to application traces. Use11 when a payment is slow, an incident needs a timeline, or security and12 reliability must read the same tape. Pull-based, capped, case-filed — not a13 lake.14metadata:15 source: https://skillmd.com/skills/drolu/rmagent-fr16---1718# rmagent-fr — The Flight Recorder1920Follow one work id without a span warehouse. The reliability half of the21RMAgent security observatory: **security asks who walked, reliability asks why22it felt slow — same ticket, two questions, one case file.**2324This is the Flight Recorder engine, split out of `rmagent-windows` so the25tracing half can be reasoned about (and loaded) on its own. `rmagent-windows`26remains the complete, runnable skill; `rmagent-so` is the witness-question27half. The three skills share one constitution.2829## Needle tier 0 — offline extraction and drift3031Alongside the Laya matrices, every skill in this family can call32**needle** — a 121M on-device model (Cactus Compute Needle, ~35 MB, no33network, no keys, ~100 MB RAM) installed once on the jump host, never on34the witnesses. It is the free tier of the judgment stack: needle extracts35and compares offline, Laya judges, the LLM reasons.3637Two scripts ship in `scripts/`:3839- `needle_extract.py` — typed field extraction from a witness fragment40 (`count`, `source_ip`, …). Rigid tokens (numbers, IPs) are reliable;41 semantic fields are not, so the wrapper validates what it can (`:ip`,42 `:int`) and blanks anything it cannot trust — never a guess.43 ```bash44 echo "<attest answer>" | scripts/needle_extract.py user count:int source_ip:ip --json45 ```46- `needle_drift.py` — baseline-drift detection via needle's 3072-dim47 embeddings: record what an answer normally looks like, score today's48 answer against it (similar / drifted / changed, thresholds calibrated49 empirically). Separates shape and topic, not field values — value drift50 stays the job of the field rules and correlate joins.51 ```bash52 echo "<routine answer>" | scripts/needle_drift.py record <host>-<question>53 echo "<today's answer>" | scripts/needle_drift.py score <host>-<question>54 ```5556The engine runs in-process on the jump host (the wrapper finds a Python57with `cactus-needle` — set `NEEDLE_PYTHON` if it lives elsewhere). No port58is opened, nothing is installed on any witness, and the baselines are59kilobyte holes under `~/.rmagent/needle-drift/`, not a lake. On an60air-gapped estate this tier keeps working — and the judgment tier with it: Laya is offline too (pre-seed its HF-cache checkpoint on air-gapped hosts), so no matrix judgment waits for a connected session.6162## Non-negotiables6364- **The ticket is a grain, not a tag.** It propagates through every hop, every65 span, every index record — and is queryable back.66- **A case file, not a lake.** Megabytes. Adaptive sampling keeps join keys on67 every walk and full detail only when something was found.68- **The budget belongs to the identity.** Depth ≤ 8, fan-out 3, 32 KB pull cap.69 An unconstrained hunter is a worm.70- **Context propagates, data does not.** The STC carries identifiers; the71 answers stay on the machine that produced them.72- **Clock skew is detected on every walk.** Cross-host timelines you can trust.7374## The scripts7576| Script | Role |77|---|---|78| `scripts/stc.py` | Security Trace Context — `case; principal; window; depth; ticket; trigger`. The distributed circuit breaker. Immutable; `child()` returns depth+1. Rejects `;`/`=` in fields (injection fix). |79| `scripts/traj.py` | The trajectory — append-only DAG of observations, thoughts, actions, results, holes, forks, merges. The recorder's reasoning chain, replayable. |80| `scripts/hop_index.py` | Cross-case memory — keyed `(host, principal, logonid, kind, case)`. `by_principal()`, `by_logonid()`, `seen_before()`. Adaptive sampling: full detail when smoke, join keys when clean. |81| `scripts/causal.py` | Causal graph — nodes `(host, principal, logonid)`, edges hops. `blast_radius()` computes everything reachable from the compromise. |82| `scripts/dthinker.py` | Distributed thinker — `temporal_cluster`, `cross_host_chain`, `session_correlation`, `repeat_offender` across the hop index. |83| `scripts/thinker.py` | Persistent reasoning between knocks — acceleration, cliffs, persistence, correlation, silence, DNS tunneling over census history. |84| `scripts/trace.py` | Trace query API — `trace.py CASE-X`, `--ticket PAY-4419`, `--principal Admin`, `--list`. Merges trajectory + hops + holes + causal graph. `get_trace()` for the gateway. |85| `scripts/trace_merge.py` | Pull-merge multi-jump-host — fan out over SSH, dedup, merge. Two-site estates without shared state. |86| `scripts/otel_emit.py` | Every trajectory entry becomes one OTel span → RTerm gateway → Grafana/Jaeger/Splunk. |87| `scripts/census.py` | The minute watch — attest on all witnesses, 2 misses = Critical → Telegram. Writes the history the thinker reasons over. |8889## The ticket join — one tape, two questions9091```92case.py open --ticket PAY-441993hunt.py --case-dir cases/<the case> # ticket inherited from case.json94trace.py --ticket PAY-441995```9697The ticket propagates through the whole trace: every question, every hop,98every span, every index record. Rev 18: `case.py open --ticket` now PERSISTS99the ticket in `case.json` and `hunt.py` inherits it from there — the ticket100no longer has to be typed twice (the old flow accepted it at case-open and101dropped it). `trace.py` reconstructs it from the trajectory's STC line, or102falls back to `case.json`. Query it back from either side of the house. That103is the Flight Recorder's actual product.104105## Rev 18 hardening106107- **Trace ids are collision-safe.** `stc.trace_id` is now sha256(case)[:32] —108 the old scheme gave two cases opened in the same second (and every default109 `admin-walk` hunt) the SAME OTel trace id, merging unrelated walks in110 Grafana.111- **The hop index ages out honestly.** Entries older than `KEEP_DAYS` (30)112 are shed at trim; `seen_before()` returns `(seen, honest)` — `honest=False`113 means "beyond what the index can see", never a confident False.114- **Blindness reaches the thinker.** census records `blind_count` and115 `raw_4624_24h` in its history; three consecutive blind censuses produce a116 CRITICAL thinker finding. Census owns the silent-host book (Rev 17's L2117 cooldown): its knock clears/marks silence, so one blip never blinds a hunt.118- **OTel spans reach a live gateway.** The emit URL is configurable119 (`RMAgent_OTEL_URL` env → `~/.rmagent/config.json otel_gateway_url` →120 default `http://127.0.0.1:17888`), with optional bearer token. The old121 hard-coded port 8765 pointed at nothing — 326 spans were found buffered,122 zero delivered.123- **`trace_merge` resolves current trees.** The remote script no longer124 hard-codes the legacy path (now resolved via rmagent-core loader).125126## The honest limit127128The business side must emit events carrying the ticket. The security half is129done — a ticket given at case-open flows through everything. The reliability130half needs the payment system to stamp `PAY-4419` into its own events, which is131an integration with whatever runs the payments, not a feature of this skill.132133## Laya-assisted intake and hop routing134135Two recurring judgments of a walk can be made by a fast, typed decision model136(Laya, via the `use-laya` skill): is a symptom worth a walk at all, and which hop137should the walker visit next? Two matrices live in `decisions/`:138139- `intake_triage.json` — at intake: worth_walking / urgency / next (start the140 walk, gather more context, or record and decline).141- `hop_route.json` — mid-walk, over the trajectory so far: which plane to walk142 next (user, edge, service, data, queue, platform, network, business), close143 the walk and synthesize, or hand the choice to the LLM.144145```bash146echo "<symptom report>" | scripts/laya_decide.py intake_triage147scripts/laya_decide.py hop_route --state-file trajectory.json148```149150Policy: confidence below 0.5 is flagged ESCALATE — the LLM (not Laya) reasons151about ambiguous walks. Verdicts are advisory; the trajectory DAG, the STC, and152the pull-only rules are unchanged.153154## Relationship to the other skills155156| Skill | Half |157|---|---|158| `rmagent-windows` | The complete skill — both halves, fully runnable |159| `rmagent-fr` | This skill — the Flight Recorder (tracing) half |160| `rmagent-so` | The witness-question (Security Observatory) half |161| `rmagent-redteam` | The drill — stages artifacts, scores detection |162| `rmagent-actuate` | Phase 1 response — named, journaled, reversible |163| `rmagent-linux` | The Linux/macOS sibling of `rmagent-so` |164165## Enterprise scope, sizing & cadence166167- **Scale:** a case file is megabytes *by design* (adaptive sampling: join168 keys always, full detail only on smoke). 100 concurrent open cases ≈ tens169 of MB under `~/.rmagent/cases/` — no lake, no warehouse. `case.py prune`170 ages closed cases out (KEEP_DAYS default 30).171- **Sizing the walks:** depth ≤ 8, fan-out 3, 32 KB pull cap — one full walk172 ≈ ≤24 questions ≈ ≤1 min of witness time. Budget belongs to the identity;173 an unconstrained hunter is a worm.174- **Cadence:** open a case per ticket/symptom (not per sweep). Census is the175 only standing loop (5-min cron); hunts fire on trigger. OTel spans flow to176 your existing Grafana/Jaeger/Splunk via the configurable gateway —177 the Flight Recorder complements APM, never replaces it.178- **No-Python estates:** the *engine* runs on the jump host you control;179 witnesses only ever see their OS-native question payloads (`.ps1` on180 Windows, `.sh` on Linux). `rmagent-windows/scripts/ops/rmagent-ops.ps1`181 and `rmagent-linux/scripts/ops/rmagent-ops.sh` reproduce the health/182 doctor/watchdog loop natively if even the jump host must stay Python-free.183- **The worked case:** EXAMPLES.md carries a full 2026-10-04 incident184 walkthrough — intake triage, hop table with join keys, the185 "healthy-answer-vs-degraded-box" lesson, and holes recorded as holes.