Diagnose tbh-meter problems — reader not attaching, AV/blocked state, slow calibration, missing or invalid runs. Use when debugging meter behavior or reading meter.log / live.json / raw run records / logs records (or the legacy runs.jsonl).
The English summary is being prepared. Showing the original description.
See how to installReview the instructions the agent will receive before you install.
Stable build: ~/tbh-meter/ · RC build: ~/tbh-meter-rc/ (variant-aware via app/src/main/settings.ts resolveOutputDir(); user can override with reader --output).
| File | What it is |
|---|---|
meter.log | Timestamped reader event log. Machine-readable phase markers: [[STATUS]] searching|resolving|scanning|ready. Human lines: [ok] attached, [ok] resolved, resolving classes/instances, managers reused, game is not open. Truncates at ~10MB. |
reader-diag.log | Infra / decision-spine log (separate from meter.log, always on; shared/utils.diag). One timestamped line per key decision: [attach], [resolve] (path FAST/SCAN + sanity-fail/calib-miss + counts), [manager-pick] (MSM/LM cands+picked), [save-pick] (PSD/CSD + gold/heroes), [party-pick] (candidates / carriers vs ghosts / picked + ghost samples), [gold], [run-close] (per-run gold_ok/xp_ok/party_degraded/heroes), [reattach] (fp change = game update), [fatal]. First place to look for resolution / instance-pick / party-off problems — the data meter.log lacked in past debugs. |
updater.log | Auto-update flight recorder (auto-update.ts): one line per status TRANSITION (checking, available x.y.z, downloading x.y.z, downloaded x.y.z, up-to-date, error: …), plus boot-gate stale pointer: …; converging when the REST cross-check catches a stale "up to date", and boot-gate updated|proceed anchoring each launch's gate conclusion. Rotates to .old at 64KB. Empty/absent on dev/macOS/RC (updater dormant). |
raw/<id>.json | One RAW record per finished run, written by the reader (id = the run's end-timestamp in ms; raw_schema_version = RAW_SCHEMA_VERSION in meter_windows.py). Pure observation — no dps/partial/session fields (the app derives those). |
logs/<id>.json | The structured record the UI reads: converter/ (convert.ts) turns each raw/<id>.json into one (derives dps, partial, totals; carries gold_source/xp_source — live vs save fallback). Cleared by "clear run history" (RunsSource.clearFile(); logs-archive.ts is only the raw/legacy clear helpers — no age-based cleanup exists). |
live.json | Current-run RAW snapshot, rewritten ~1×/s (Redesign 2 — replaced the old cooked meter_live.txt). Read by live-source.ts (cooks the overlay) and reader-process.ts engagement detection. |
resolve_cache.json | Build-fingerprint-keyed calibration cache (fmt must equal CACHE_FMT in meter_windows.py). Delete it to force a recalibration. |
runs.jsonl | LEGACY, frozen at schema v11 — the reader stopped writing it in Redesign 2; the converter uses it only as the one-time migration source (≤11 = legado). Absent on fresh installs. |
Decision logic is pure and testable: app/src/main/reader-policy.ts; supervisor: reader-process.ts.
spawn-failed (spawn error, EPERM/ENOENT/EACCES): exe locked/quarantined/missing → almost always antivirus. Reported immediately.crashed (signal, or exit code ≠ 0): AV kill, OOM, game crash. Starts exponential backoff: 2^(streak-1) * 5s, capped 60s.clean (code 0): normal "game not open" exit; re-poll after 5s.blocked: 5 consecutive failures (READER_BLOCKED_THRESHOLD). The overlay shows the blocked + Retry message and the supervisor waits for the user to hit retry (retryReader() IPC).READER_HEALTHY_RUN_MS) resets the failure streak.win32 && app.isPackaged && readerExePath() — on macOS dev the file-watching sources still work against existing artifacts.reader/il2cpp/typeinfo.py), gated by build fingerprint, validated by name round-trip.reader/config/calib_seed.json (~8s first launch). Rejected if its fmt ≠ current CACHE_FMT → falls through to cold scan (this bit an RC build once, #199). Re-capture on every fmt bump: scripts/seed_calib_capture.py; CI --selftest fails on stale fmt.reader/il2cpp/resolver.py): ~100s, dominated by the ~62s gold value-scan. Happens on uncalibrated/post-patch builds; self-calibrates into resolve_cache.json (survives game restarts).Game patched → build fingerprint changes → cache misses → seed tried → likely cold scan once. This is expected, not a bug.
tbh-reader.exe --output DIR # artifact dir (default ~/tbh-meter)
--hz N # poll rate, default 10
--debug # per-tick lines to stdout (meter.log stays event-level)
--selftest # validate bundled resources + calib_seed fmt; exit 0/1 (used in CI)
Clear orphans on Windows: taskkill /f /im tbh-reader.exe.
"Meter shows nothing" → check live.json exists/updates → check last [[STATUS]] in meter.log (searching = game not found, resolving/scanning = wait, ready = reader fine, look at the app side) → if app side, check reader status IPC and the activity ring.
"Calibration takes forever" → one cold scan ~100s post-patch is normal. Repeating every launch = cache not persisting: check resolve_cache.json exists and its fmt matches CACHE_FMT.
"Reader keeps dying" → exit codes in app log / activity ring; spawn-failed or repeated crashed = AV → add exclusion, restore exe from quarantine, then retryReader().
"Run missing from the list" → was raw/<endTs>.json written at all (reader side)? → does the converted logs/<id>.json exist (converter side)? → in the logs record check quality (skipped/degraded are hidden by the default display filter — toggle "show ignored"), partial, and totalDamage.
"Gold/XP look wrong" → check gold_source/xp_source: save fallback means the live manager wasn't resolved when the run started (e.g. attached mid-menu); usually fixes itself next run.
"Runs invalid / no team (party off)" → reader-diag.log [party-pick] line: carriers=0 picked=0x.. party_read=0 + a ghost … (hk, 0, 0.0) = pick_live_sm grabbed a non-carrier StageManager (heroKey valid, lvl=0) over the live one → read_live_party reads {} → heroes:err → degraded (no team). meter.log fingerprint: StageManager ok — 0 heroes deployed (pick≠read). Fixed structurally in #413 (pick delegates to read_live_party); see reader/docs/invariants/party-live-resolution.md. carriers≥1 but party_read=0 = the pre-fix freeze on a ghost; carriers=0 in combat = the carrier wasn't captured by the scan (rarer). Methodology (the lesson that found it): don't assume "it's the seed/calibration" — pull the player's CURRENT reader-diag.log/meter.log and let it REFUTE the prior theory (fast-path armed + party still off = NOT calibration, so the #408 reseed couldn't fix it). Then reproduce with a real-code MockReader test (TDD red→green) BEFORE asserting a fix — never theorize. A bug that "works on the dev machine" but not a player's is usually instance-ordering / state-dependent (see instance-selection), not the seed.
"App didn't auto-update on launch" → read updater.log around the boot: up-to-date then boot-gate proceed = both the public pointer AND the REST cross-check said "current" (or REST had no signal — 403/CGNAT/offline); a boot-gate stale pointer … converging line = the cross-check caught a stale answer and the gate re-checked until convergence (meter-3-ship's "Verify players can see it" step should make this rare); error: lines = check/download failed (transient network or AV — boot retries once, focus retries after 30s); boot-gate proceed right after checking = check slower than the 8s gate (update still downloads in background, installs on quit). Mid-session pickup is the 3min interval + focus/resume triggers.
No reviews yet. Tell others what you thought.
No login needed. Share how it worked for you, ask a question, or note where it did not run.
No comments yet. Be the first to write one.
Boot and drive the tbh-meter app + reader locally to see a change working — what runs on macOS (UI only; the reader is win32-only) and how to feed the overlay/list fake data. Use when asked to run/start the meter, verify a change in the running app, screenshot the overlay, or reproduce a bug locally.
The English summary is being prepared. Showing the original description.
The TaskBarHero game updated (new version) and the tbh-meter reader needs re-calibration — symptoms are gold showing 0, stage mode "?", or the live party/XP/stats dropping out (party empty / no live levels / runs degraded) after a patch, or you're prepping a meter release for a new game build. Runs the diagnose→dump→diff→reseed→bump→verify playbook (the fix is usually a reseed, but a build can also change an Obscured encoding with zero offset movement — caught only by the live gate, fixed by a read-strategy change). Use when the game version changed, after a TBH patch, when a player reports gold/stage/party/XP broken following an update, or when asked to re-seed / re-calibrate the reader for a new build.
The English summary is being prepared. Showing the original description.
Generate a polished release video for a tbh-meter release in the Claude-Code motion style (recreated animated UI + real game sprites + synth soundtrack), to post with a launch. Primary input is a GitHub release LINK — the skill turns it into a video named after that release, covering ONLY the features that shipped in that release, version stamped on the intro. Use when asked to make/update a release video, showcase clip, feature trailer, or promo video for a meter release, or "make the video for <release link>".
The English summary is being prepared. Showing the original description.
Adversarial, security-first review of a pull request from an EXTERNAL or untrusted contributor — a fork PR, a first-time or unknown author, anyone without write access — before a maintainer merges it. Use this whenever you're reviewing, triaging, or deciding whether to merge a PR opened against tbh-meter by someone outside the maintainer team: 'review PR #123', 'someone opened a PR — is it safe to merge?', 'check this contributor's changes', 'can we take this fork PR?', 'is this contribution legit?'. This is supply-chain DEFENSE, not ordinary code review: every merged PR auto-updates onto every user's machine and ships a memory-reading .exe plus an unsandboxed Electron app, so the author and the PR description are UNTRUSTED and the diff is the only evidence. It posts its verdict as a real GitHub review — an inline comment pinned to each problematic line (via the pulls/reviews API), not just one summary comment. NOT for your own or a fellow maintainer's branch (use self-review for that), and prefer this over the generic review flow for anything coming from outside the team.
The English summary is being prepared. Showing the original description.
Post-implementation self-review. Use AFTER finishing ANY code implementation or change — before declaring it done, committing, or opening a PR — to critique your own work: re-read the diff adversarially, confirm unit tests cover every branch/edge, kill duplication, follow clean-code/SOLID and the repo's own docs & invariants, decide if something should become documentation, update/prune memory, and strip outdated comments. Trigger it whenever you've just written or modified code and are about to wrap up, even if the user didn't explicitly ask for a review.
The English summary is being prepared. Showing the original description.
Standardized commit + PR workflow for tbh-meter. Analyzes changes, makes conventional commits (subjects feed the release changelog), and for any overlay/UI change captures a seed-driven screenshot to attach to the PR. Use when asked to commit, open a PR, or "commit this".
The English summary is being prepared. Showing the original description.