DC-132: Plan plugin + agent metrics report scaffold

[Fede654]

Implements DC-132 (Observability) from the DC-124 epic. Stacks on top of #4 (DC-131 Safety) which stacks on #3 (Server Setup Overhaul). Each PR's MODRINTH_PROJECTS line extends the previous one — merge in order or rebase will be needed.

What's in

• Plan plugin (Modrinth pin plan:egk2fxRL, 5.7+build.3306). Webserver bound to 127.0.0.1:8804 — not exposed publicly. SQLite backend (default). LuckPerms extension auto-registers. GeoLite2 deliberately not enabled (city geolocation isn't useful at single-server scale and adds an EULA + external dependency).
• scripts/agent-metrics-report.py reads ~/.hermes/metrics/<cast>/<YYYY-MM-DD>.jsonl and aggregates four metric families: turns/tokens, tool distribution (top 5), heartbeats with per-minute rate, tool failures. JSONL schema documented in the script docstring (single source of truth).

What's deliberately deferred

• Metric emission hooks in agent_loop.py and gateway/platforms/daemoncraft.py cross repo boundaries (daemoncraft + hermes-agent). These will land alongside the gateway DC-123 fix so the schema between emitter and reader stays consistent. The report script gracefully prints "no events" until the emitters land.
• GeoLite2.
• Prometheus / real-time alerting (out of scope per plan).

Test plan

• docker compose up -d minecraft — Plan loads cleanly on Purpur 1.21.11.
• curl http://127.0.0.1:8804/ returns 302 (dashboard live).
• Plan webserver only reachable on the loopback (Internal_IP=127.0.0.1).
• scripts/agent-metrics-report.py with synthetic JSONL aggregates turns, tokens, tools, heartbeats, failures (verified against a 7-event fixture).
• Same script with empty metrics dir: prints helpful stub message instead of crashing.

🤖 Generated with Claude Code

[nicoechaniz]

Review — DC-132 Plan plugin + agent metrics report scaffold

Solid scaffold. Two risks and one cross-repo dependency note.

---

Risk — gateway-side metric events missing

The report script (agent-metrics-report.py) expects four metric families:

• turn (tokens, latency)
• tool (tool name, ok/fail)
• heartbeat (count)
• failures

This PR only wires the heartbeat emitter in agent_loop.py. The turn and tool emitters belong in gateway/platforms/daemoncraft.py which lives in the hermes-agent repo, not DaemonCraft.

Until those emitters land, the daily report will show heartbeats but zero turn/tool data. This is documented in plans/DC-132.md (good), but there is no tracking ticket or PR link for the hermes-agent side. Please create a follow-up task in the DaemonCraft lattice (or a hermes-agent PR) so the dependency does not get dropped.

---

Risk — JSONL append is not atomic

_emit_metric in agent_loop.py does:

with path.open("a") as f:
    f.write(json.dumps(record) + "\n")

If the agent_loop process is killed mid-write, the file may contain a truncated line. The report script skips JSONDecodeError, so the failure mode is silent data loss rather than a crash.

Fix (optional, low priority): write to a temp file in the same directory, then os.replace() for atomic append. Or accept the current best-effort approach and document the limitation.

---

Risk — Plan plugin default bind address

Same note as in PR #3 review: please confirm that Plan binds to 127.0.0.1 by default. If it binds to 0.0.0.0, the player-analytics dashboard becomes publicly reachable. A plugins/Plan/config.yml pinned to 127.0.0.1 would eliminate this risk.

---

Nits

• MC_METRICS_CAST injected by the launcher is the right pattern — no hardcoded cast names.
• The bare except: pass around the emitter is correct for a non-critical sidecar.
• agent-metrics-report.py handles empty dirs gracefully. Good UX.

LGTM once the cross-repo dependency is tracked.

[Fede654]

Thanks for the review — all three points addressed.

Finding	Status	Commit / link
🟡 Gateway-side metric events missing	Tracked + landed	The cross-repo work is in nicoechaniz/hermes-agent#2. That PR adds the _emit_metric() helper in gateway/platforms/daemoncraft.py with turn (one per cognition cycle, with tool_call_count) and tool (one per tool_use block) events, gated on DAEMONCRAFT_METRICS_CAST env var. Same JSONL schema, same ~/.hermes/metrics/<cast>/<date>.jsonl path. Once that lands, the report populates fully.
🟡 JSONL append not atomic	Fixed	9451a9c — switched to os.O_APPEND + single os.write(). POSIX guarantees writes shorter than PIPE_BUF (typically 4 KB on Linux) are atomic with O_APPEND, which covers all our line lengths. Better than temp+rename for our case (no rename storm under high cadence). The hermes-agent PR has the matching fix in the gateway emitter.
🟡 Plan plugin default bind	Fixed	c0f954f — server/plugins/plan/README.md ships the apply procedure for Internal_IP: 127.0.0.1. Snippet pattern (rather than committing the whole 100-line config.yml) so we don't churn on every Plan version bump. The plan progress note has a ⚠️ flag pointing at this.

Live validation: with Pamplinas running for ~2 min on the integration branch, scripts/agent-metrics-report.py aggregates 47 real heartbeats from ~/.hermes/metrics/rolemaster/2026-05-03.jsonl. Once the hermes-agent PR merges, the same report will start showing turn/tool families.

[nicoechaniz]

Re-review — PR #5 (DC-132 Plan plugin + metrics)

All audit findings from the first review are addressed.

1. Plan bind address secured — server/plugins/plan/README.md documents the one-line sed override (Internal_IP: 0.0.0.0 → 127.0.0.1) and verification commands. Following the same "track snippet, not whole config" pattern as LuckPerms is the right call.
2. JSONL atomicity — _emit_metric now uses os.open(..., O_APPEND) + single os.write(). POSIX-atomic for lines under PIPE_BUF (4 KB), which covers all JSONL records here. The finally: os.close(fd) is correct.
3. Cross-repo dependency tracked — plans/DC-132.md documents that gateway-side turn/tool emitters live in hermes-agent and links to the shared schema docstring. Please make sure a corresponding task exists in the hermes-agent project so it doesn't fall through the cracks.

LGTM. No blockers.