-
Notifications
You must be signed in to change notification settings - Fork 8
Tooling Doctor
evener-doctor is a read-only forensic inspector for evener sessions, jobs, watches, and the session tree. It reads settled on-disk state (transcript.jsonl, api.jsonl, meta.json, jobs.jsonl, mutations/<sid>.json) through the same folds and types the evener runtime uses — so a schema change either flows through automatically or fails to compile, and the numbers it reports are the runtime's numbers, never hand-parsed. (The one deliberate exception is the client-mutation store: the runtime's snapshot types are unexported, so mutations mirrors the persisted shape and refuses anything it does not recognize.)
Build: make build-doctor (or go build ./cmd/evener-doctor). Agent-facing usage and the diagnose→findings workflow live in the bundled doctoring-evener skill.
(Source: cmd/evener-doctor/README.md)
Every session-scoped subcommand takes a session selector first: local:<id>, proj:<project-id>:<id>, or a bare <id> (searched across buckets; a bare id found in more than one bucket is reported as ambiguous). The state-root sweeps (turnids) take no selector.
Common flags: --state-dir <path> (state root; default EVENER_STATE_DIR → XDG_STATE_HOME → ~/.local/state) and --json. Run evener-doctor <subcommand> -h for the full flag list.
(Source: cmd/evener-doctor/README.md)
| Tool | What it does | Key flags |
|---|---|---|
locate <sel> |
Resolve a selector to its on-disk transcript / API-log / meta / jobs / client-mutation paths and bucket. | — |
transcript <sel> |
Render a session's logical turns; answer "how many real X calls?" structurally (calls vs. textual mentions). Turn text renders capped at 200 bytes; --full-text lifts the cap, --text-max N raises it. |
--count <tool>, --format outline|markdown, --range last:N|start:N|A-B, --text-max N, --full-text
|
apilog <sel> |
Canonical provider-attempt diagnostics: identity, grouping, finality, settlement, tokens/latency, empty responses, errors, cache spikes, whole-session token spend. --validate runs a whole-history structural-integrity scan; --health prints a one-line API-health verdict. |
--empty, --errors, --cache-spikes [--threshold N], --summary, --validate, --health
|
jobs <sel> |
Every job the session ran, folded from jobs.jsonl: status, reason, exit code, output bytes, start/end times, and delegate/transcript/parent links. |
--job <id> |
mutations <sel> |
Did the user's input reach the daemon? Renders the journal of every client mutation the daemon accepted and every one it rejected, plus the durable input queue and pending executions. Absence from the journal means the request never arrived. | — |
watches <sel> |
Watch/delivery inspector: distinct deliveries, provenance, lifecycle, the self-loop verdict, and the target job's state joined from the same jobs.jsonl. |
--watch <id>, --self-loops
|
tree <sel> |
Parent ↔ delegate/observer session tree across buckets. |
--depth N, --observers
|
turnids |
State-root sweep (no selector): which sessions persisted a reserved turn id that collides with an entry's position in the transcript's index namespace. | — |
(Source: cmd/evener-doctor/README.md)
evener-doctor locate local:01KV8MVQ7BZHX0EN8D7ZH5QDE4
evener-doctor transcript <id> --count delegate_send # real invocations, not mentions
evener-doctor transcript <id> --range last:1 --full-text # whole turn text
evener-doctor apilog <id> --summary # token spend + empties + errors
evener-doctor apilog <id> --validate # integrity scan; nonzero exit if any record is bad
evener-doctor jobs <id> # what jobs ran and how each ended
evener-doctor mutations <id> # did the user's message reach the daemon?
evener-doctor watches <id> --self-loops
evener-doctor tree <id> --observers
evener-doctor turnids(Source: cmd/evener-doctor/README.md)