style: tighten dead-letter inline comments (#1592)

Co-authored-by: Isaac

omnigent/_native_post_delivery.py

@@ -31,9 +31,7 @@ _logger = logging.getLogger(__name__)
 
 # Dead-letter sink for permanently-undeliverable forward payloads (#1120).
 _DEAD_LETTER_FILE = "dead_letter.jsonl"
-# When the active file reaches this size it is rotated to a single ``.1``
-# backup and a fresh file is started, so the most recent drops are always
-# retained (keep-newest). Disk stays bounded at ~2x this size (current + .1).
+# At this size the file rotates to a single .1 backup (keep-newest); disk ~2x this.
 _DEAD_LETTER_MAX_BYTES = 50 * 1024 * 1024  # 50 MB per session
 _DEAD_LETTER_BACKUP_FILE = _DEAD_LETTER_FILE + ".1"
 
@@ -69,14 +67,11 @@ def append_dead_letter(
     try:
         path = bridge_dir / _DEAD_LETTER_FILE
         bridge_dir.mkdir(mode=0o700, parents=True, exist_ok=True)
-        # Keep-newest: at the cap, rotate the full file to a single .1 backup
-        # (overwriting any prior backup) and start fresh. A sustained outage
-        # then retains the most recent items rather than stopping at the oldest.
+        # Keep-newest: at the cap, rotate to a single .1 backup and start fresh.
         if path.exists() and path.stat().st_size >= _DEAD_LETTER_MAX_BYTES:
             path.replace(bridge_dir / _DEAD_LETTER_BACKUP_FILE)
-            # Log the session id rather than the bridge path: the path is
-            # deterministic per session and logging it trips CodeQL's
-            # clear-text-sensitive-data heuristic (a bridge dir is not a secret).
+            # Log session_id, not path (logging a bridge path trips CodeQL's
+            # clear-text-sensitive-data heuristic; a bridge dir is not a secret).
             _logger.warning(
                 "dead-letter file reached cap (%d bytes); rotated to %s and "
                 "started fresh (oldest dead-lettered forwards dropped): session=%s",

omnigent/claude_native_forwarder.py

@@ -1280,8 +1280,7 @@ async def _forward_available_subagents(
                     decision.attempts,
                     _http_status_for_log(exc),
                 )
-                # Persist the dropped start payload so it is recoverable on
-                # disk instead of silently lost (#1120; replay is #1579).
+                # Dead-letter the dropped payload for recovery (#1120; replay #1579).
                 append_dead_letter(
                     bridge_dir,
                     session_id=parent_session_id,
@@ -1390,8 +1389,7 @@ async def _forward_available_subagents(
                         decision.attempts,
                         _http_status_for_log(exc),
                     )
-                    # Persist the dropped item so it is recoverable on disk
-                    # instead of silently lost (#1120; replay is #1579).
+                    # Dead-letter the dropped item for recovery (#1120; replay #1579).
                     append_dead_letter(
                         bridge_dir,
                         session_id=entry.child_conversation_id,
@@ -2880,8 +2878,7 @@ async def _forward_available_items(
                     decision.attempts,
                     _http_status_for_log(exc),
                 )
-                # Persist the dropped item so it is recoverable on disk
-                # instead of silently lost (#1120; replay is #1579).
+                # Dead-letter the dropped item for recovery (#1120; replay #1579).
                 append_dead_letter(
                     bridge_dir,
                     session_id=session_id,

omnigent/codex_native_forwarder.py

@@ -1530,8 +1530,7 @@ async def supervise_forwarder(
     :returns: None. Runs until cancelled or the app-server connection
         closes.
     """
-    # Bind the bridge dir so failed durable-event posts can be dead-lettered
-    # to {bridge_dir}/dead_letter.jsonl instead of being silently lost (#1120).
+    # Bind bridge dir so failed durable-event posts can be dead-lettered (#1120).
     _dead_letter_dir.set(bridge_dir)
     if client is None:
         client = client_for_transport(app_server_url, client_name="omnigent-codex-forwarder")
@@ -5338,12 +5337,10 @@ class _ForwardHealth:
 _FORWARD_DEGRADED_THRESHOLD = 5
 _forward_health = _ForwardHealth()
 
-# Bridge dir for the active forwarder, used to dead-letter permanently
-# undeliverable durable events (#1120). Set per-forwarder at entry.
+# Bridge dir for dead-lettering undeliverable durable events; set per-forwarder (#1120).
 _dead_letter_dir: ContextVar[Path | None] = ContextVar("_codex_dead_letter_dir", default=None)
 
-# Only durable (persisted) event types are worth dead-lettering — ephemeral
-# stream/usage-delta events have no standalone recovery value.
+# Durable event types worth dead-lettering (not ephemeral deltas).
 _DEAD_LETTER_EVENT_TYPES = frozenset({"external_conversation_item", "external_session_usage"})