Add structured log cursor reads

[Clubhouse1661]

Summary

This adds a reliable cursor API for structured log buffers. The main goal is to make editor diagnostics safe to read from a known point in time, even when the log ring fills up or gets cleared.

Before this change, McpEditorLogBuffer.total_count() only represented the number of entries currently retained in the ring. Once the ring reached its max size, that value stopped increasing. That makes it unsafe to use as a cursor for “show me entries after this point,” especially during an error storm, where old entries may be overwritten.

This change adds a separate monotonic append counter that keeps moving forward on every append.

What Changed

• Added _appended_total to McpStructuredLogRing.

  • It increments on every append.
  • It does not reset when the ring is cleared.
  • It is separate from retained size and dropped count.

• Added appended_total().

  • Callers can use this as a cursor before doing work that may produce diagnostics.

• Added get_since(cursor, limit).

  • Returns entries appended after the cursor.
  • Reports truncated: true if the cursor is older than the oldest retained entry.
  • Supports pagination with limit and has_more.
  • Returns next_cursor so callers can continue from the right point.

• Added mutex-wrapped appended_total() and get_since() methods to McpEditorLogBuffer.

  • This keeps the editor diagnostics buffer thread-safe, matching the existing locking pattern.

• Added regression tests for:

  • normal cursor reads
  • overflow/truncation during an error storm
  • pagination
  • future cursor clamping
  • clear() preserving the append counter
  • stale cursors after clear() reporting truncation instead of looking clean

Why

This is groundwork for attaching diagnostics directly to write operations.

For example, a future script or resource write can:

1. Take a cursor from the editor diagnostics buffer.
2. Run validation.
3. Read only diagnostics that arrived after that cursor.
4. Detect whether the window was incomplete because entries were overwritten or cleared.

That avoids treating the retained ring size as a clock, which breaks once the ring is full.

Validation

• test_run suite="editor": 119 passed, 0 failed, 2 skipped
• uv run python -m pytest tests/unit -q --ignore=tests/unit/test_orphan_reaper.py: 862 passed, 6 skipped
• Godot 4.6.3 --headless --path test_project --import: passed
• git diff --check: clean

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!