Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.automagik.dev/llms.txt

Use this file to discover all available pages before exploring further.

​
Detectors

Detectors emit rot.* and detector.* events when genie observes anomalies in its own state — worktree drift, tmux/PG disagreements, orphaned executors, silently-dropped broadcasts, and more. Each detector is read-only: it inspects PostgreSQL, tmux, and the filesystem on a scheduler tick and publishes an event you can stream, filter, and triage. You decide what to do about it.
Detectors surface anomalies, not errors — not every event requires action. Many patterns have known false-positive sources (mid-transaction races, transient network mounts) that clear themselves on the next tick.

​
Listing active detectors

Eight rot.* pattern families ship in the current scheduler. Use genie events list --kind 'detector.*' (see Observability) to pull recent fires for any of them.
PatternRiskWhat it detects
rot.backfill-no-worktreelowA teams row claims a worktree_path that no longer exists on disk.
rot.team-ls-driftmediumgenie team ls and genie team disband disagree about what a team is.
rot.anchor-orphanhighAn agent row is alive but the tmux pane is dead and its worktree transcript is missing.
rot.duplicate-agentslowTwo non-archived agents share the same (custom_name, team) pair.
rot.zombie-team-leadlowA live team-lead has not seen any team activity event in 5+ minutes.
rot.subagent-cascadehighA parent agent is in error together with two or more of its direct children.
rot.dispatch-silent-drophighA @team broadcast landed in PG but zero prompt events reached idle members.
rot.session-reuse-ghosthighA fresh agent has bound to an archived peer’s transcript via a custom_name collision.

​
Streaming in real time

genie events stream-follow tails enriched genie_runtime_events via LISTEN/NOTIFY. The --kind flag accepts *-glob prefixes, so you can watch every detector fire with one pattern. 
# Follow every detector event as it fires, seeded with the last 5 minutes.
genie events stream-follow --kind 'detector.*' --since 5m

# Only show warnings or worse.
genie events stream-follow --kind 'detector.*' --severity warn

# Machine-readable stream for alerting pipelines.
genie events stream-follow --kind 'rot.*' --json
The first page is a seed window (--since), then the stream follows new events as they arrive. Use --consumer-id if you want a persistent cursor that resumes where it left off.

​
Triage procedure

1

Identify

Read the event payload. observed_state_json names the first offender and carries enough context (counts, IDs, timestamps) to judge scope without a follow-up query.
2

Classify

Check the pattern’s known false-positive sources in the runbook. A single fire during a mid-disband tick or tmux restart is usually noise.
3

Escalate

If the detector fires repeatedly for the same entity or the scope count is above the pattern’s threshold (e.g., drop_count > 2, ghost_count > 3), treat it as a real incident and follow the runbook’s per-pattern action box.
4

Verify

Re-run the detector’s probes by hand (genie team show, genie agent show, psql snippets in the runbook) and confirm the anomaly persists before mutating state.
Never act on a detector event alone — always reconfirm with a live probe. Detector evidence is one scheduler tick old and can race with concurrent lifecycle transitions.

​
Self-healing groups

The detectors and their substrate shipped in four upstream groups. Each card links back to the authoritative runbook in the genie repo.

Group 3a — low-risk detectors

Patterns 1, 4, 5 (rot.backfill-no-worktree, rot.duplicate-agents, rot.zombie-team-lead) — low false-positive surfaces safe to watch on every tick.

Group 3c — high-risk detectors

Patterns 3, 6, 7, 8 (rot.anchor-orphan, rot.subagent-cascade, rot.dispatch-silent-drop, rot.session-reuse-ghost) — high-stakes failures that need careful payload review before remediation.

Group 4 — tail filter

The --kind '*'-glob predicate on genie events stream-follow — runtime filtering for rot.* and detector.* prefixes without per-subject flags.

Group 5 — runbook seed

The authoritative triage guide — one section per pattern with description, root cause, false-positive sources, and concrete action boxes.

​
See also

Observability commands

Full reference for genie events, log, metrics, and related CLI verbs.

State management

Wish, agent, team, and mailbox state — the tables detectors read from.