fix(guard): page cloud command request snapshots

[kantorcodes]

Summary

• Page local approval-request snapshots sent with Guard Cloud command queue lease checks.
• Extract snapshot paging and cloud-safe payload shaping into a focused runtime module.
• Keep complete-snapshot markers only for small backlogs so large local inboxes do not send oversized lease payloads.
• Add focused regression coverage for paged pending-request snapshots.

Testing

• python3 -m ruff format src/codex_plugin_scanner/guard/runtime/command_executors.py src/codex_plugin_scanner/guard/runtime/local_request_snapshots.py tests/test_guard_command_snapshot_paging.py
• python3 -m ruff check src/codex_plugin_scanner/guard/runtime/command_executors.py src/codex_plugin_scanner/guard/runtime/local_request_snapshots.py tests/test_guard_command_snapshot_paging.py
• python3 -m pytest tests/test_guard_command_snapshot_paging.py tests/test_guard_command_queue.py -q
• Patched local command-queue poll accepted by the live command queue after reducing the request snapshot payload below 1 MB.

[gemini-code-assist]

Warning

You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again!

[greptile-apps]

Greptile Summary

This PR updates local approval-request snapshots sent through Guard Cloud command leases. The main changes are:

• Moves snapshot payload shaping into local_request_snapshots.py.
• Adds cursor-based paging for pending and resolved local requests.
• Bounds snapshot text fields to keep lease payloads under the Cloud byte budget.
• Adds tests for oversized request data and paged pending-request snapshots.

Confidence Score: 5/5

Safe to merge with low risk.

The change is focused on snapshot extraction, bounded payload shaping, and cursor paging. The added tests cover the main oversized-payload and multi-page backlog paths. No blocking correctness or security issues were identified.

No files require special attention.

T-Rex Logs

What T-Rex did

• T-Rex produced a finding-comment-proof for the posted P1 finding.
• T-Rex ran the contract-validation checks and captured Pytest snapshot failures with exit code 1.
• T-Rex confirmed lint checks passed with exit code 0.
• T-Rex confirmed code formatting was already compliant with 3 files already formatted.

_{Ran code and verified through T-Rex}

Important Files Changed

Filename	Overview
src/codex_plugin_scanner/guard/runtime/command_executors.py	Delegates local request snapshot construction to the new runtime module while preserving the command executor entry point.
src/codex_plugin_scanner/guard/runtime/local_request_snapshots.py	Adds paged, cursor-aware, cloud-safe local approval request snapshot assembly with bounded text fields and cursor fallback handling.
tests/test_guard_command_snapshot_paging.py	Adds tests for byte-budgeted payload shaping and multi-page pending request snapshots.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
participant Cloud as Guard Cloud command queue
participant Executor as command_executors
participant Snapshots as local_request_snapshots
participant Store as GuardStore

Cloud->>Executor: guard.localRequests.snapshot
Executor->>Snapshots: local_request_snapshot_payload(store)
Snapshots->>Store: get saved cursor state
Snapshots->>Store: list pending requests(limit + 1, cursor)
Snapshots->>Store: list resolved requests(limit + 1, cursor)
Snapshots->>Snapshots: shape cloud-safe payload fields
Snapshots->>Store: save next cursor or clear completed cursor
Snapshots-->>Executor: requests + completeness markers
Executor-->>Cloud: command result payload

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
participant Cloud as Guard Cloud command queue
participant Executor as command_executors
participant Snapshots as local_request_snapshots
participant Store as GuardStore

Cloud->>Executor: guard.localRequests.snapshot
Executor->>Snapshots: local_request_snapshot_payload(store)
Snapshots->>Store: get saved cursor state
Snapshots->>Store: list pending requests(limit + 1, cursor)
Snapshots->>Store: list resolved requests(limit + 1, cursor)
Snapshots->>Snapshots: shape cloud-safe payload fields
Snapshots->>Store: save next cursor or clear completed cursor
Snapshots-->>Executor: requests + completeness markers
Executor-->>Cloud: command result payload

Loading

Comments Outside Diff (1)

1. General comment

   Combined command queue regression test plan fails on snapshot paging compatibility expectations

   • Bug
     • The explicit combined pytest command from the PR fails with 5 regressions in tests/test_guard_command_queue.py. The failures include pendingComplete remaining True when the pending snapshot is truncated, missing command_executors attributes _local_request_snapshot_items_for_status, _local_request_snapshot_byte_capped_items, and LOCAL_REQUEST_SNAPSHOT_MAX_BYTES, plus a lease payload assertion mismatch in test_poll_once_leases_heartbeats_executes_and_posts_result. This means the stated test-plan command does not pass on the head checkout.
   • Cause
     • Snapshot paging helpers/constants appear to have moved into local_request_snapshots.py or otherwise changed API surface/lease payload structure without preserving the command queue test expectations, and _local_request_snapshot_payload no longer reports pending truncation the way the existing command queue coverage expects.
   • Fix
     • Update the snapshot paging implementation and/or command queue compatibility layer so command_executors exposes the expected helper API/constants or update all dependent tests/callers consistently. Also ensure _local_request_snapshot_payload detects pending truncation and that the /lease payload shape matches the intended schema, including any new maxBytes field if that is the intended contract.

   _{Ran code and verified through T-Rex}

_{Reviews (8): Last reviewed commit: "Merge branch 'main' into fix/cloud-comma..." | Re-trigger Greptile}

[kilo-code-bot]

Code Review Summary

Status: No Issues Found | Recommendation: Merge

All reviewed issues were resolved in earlier patches. The incremental changes are clean:

• Cursor state correctly clears after final page (PATCH 7/10)
• Text field bounding prevents oversized payloads (PATCH 9/10)
• Tests verify wraparound and byte budget (PATCH 8/10, 10/10)

Files Reviewed (3 files)

• src/codex_plugin_scanner/guard/runtime/command_executors.py - extracted snapshot helpers, 681 lines
• src/codex_plugin_scanner/guard/runtime/local_request_snapshots.py - cursor paging with byte caps, 341 lines
• tests/test_guard_command_snapshot_paging.py - regression tests for paging behavior

Previous Review Summary (commit 3d2de80)

Current summary above is authoritative. Previous snapshots are kept for context only.

Previous review (commit 3d2de80)

Status: No Issues Found | Recommendation: Merge

The existing P1/P2 comments referenced in the prompt are stale and were already addressed:

1. command_executors.py line 46: The Greptile P2 comment targeted _LOCAL_REQUEST_SNAPSHOT_CURSOR_SYNC_KEY (added in PATCH 1/8, removed in PATCH 4/8 during extraction). The current line 46 contains unchanged constant _GUARD_REVIEW_MEMORY_REGISTRY_SYNC_KEY. The file was reduced from 885 to 681 lines through the extraction.

2. local_request_snapshots.py original_line 129: The P1 cursor advancement fix was already implemented in PATCH 7/8. Lines 125-130 now correctly pop the cursor when len(rows) <= limit.

All changed code is clean:

• Pagination logic correctly detects cursor support
• Cursor state properly advances/clears between pages
• Tests verify the wraparound behavior for 130-item backlog with 125-item page limit

Files Reviewed (3 files)

• src/codex_plugin_scanner/guard/runtime/command_executors.py - refactored, extracted snapshot helpers
• src/codex_plugin_scanner/guard/runtime/local_request_snapshots.py - correctly implements cursor paging logic
• tests/test_guard_command_snapshot_paging.py - correct test assertions

---

_{Reviewed by laguna-m.1-20260312:free · Input: 141.3K · Output: 13.1K · Cached: 263.9K}