@jaguilar87/gaia 5.0.7 → 5.0.9

package/dist/gaia-security/hooks/modules/agents/handoff_persister.py

@@ -170,19 +170,30 @@ def _intake_command_set_pending(
     }
 
     try:
-        from gaia.approvals.store import insert_requested
+        from gaia.approvals.store import derive_command_set_id, insert_requested
     except ImportError:
         import pathlib as _pl
         import sys as _sys
 
         _repo_root = _pl.Path(__file__).resolve().parent.parent.parent.parent
         _sys.path.insert(0, str(_repo_root))
-        from gaia.approvals.store import insert_requested
+        from gaia.approvals.store import derive_command_set_id, insert_requested
+
+    # Derive the PUBLIC approval_id deterministically from the post-filter
+    # mutative command strings. Because the id is content-derived (not uuid4),
+    # the orchestrator reproduces the SAME id from the command_set it reads in
+    # the contract via `gaia approvals derive-id` -- no DB search, no
+    # cross-session miss. The list passed here is the SAME list the CLI helper
+    # derives over (post-mutative-filter), so both sides agree.
+    derived_id = derive_command_set_id(
+        [it["command"] for it in command_set_items]
+    )
 
     approval_id = insert_requested(
         sealed_payload,
         agent_id=agent_id,
         session_id=session_id or None,
+        approval_id=derived_id,
     )
     logger.info(
         "INTAKE: plan-first COMMAND_SET pending created approval_id=%s items=%d",

package/dist/gaia-security/hooks/modules/context/context_injector.py

@@ -450,17 +450,33 @@ def build_project_context(
         if critical_summary:
             context_string += critical_summary
 
-        # Inject recent operational events (non-blocking)
+        # Inject recent operational events (non-blocking).
+        # Brief 54 / Task 2.2: read from the harness_events DB table via
+        # gaia.store.reader.cross_surface_query instead of the legacy
+        # events.jsonl reader. The reader returns rows shaped as
+        # {surface, timestamp, type, agent, summary, raw} -- NOT the old
+        # {ts, type, agent, result} JSONL shape -- so the formatting loop
+        # below is remapped to those keys (audit Risk 4: without the remap
+        # the "Recent Events" block silently goes blank).
         try:
-            from ..events.event_writer import read_events
-            recent = read_events(hours=24, limit=20)
+            import sys as _sys
+            from pathlib import Path as _Path
+            try:
+                from gaia.store import reader as _reader
+            except ImportError:
+                _repo_root = _Path(__file__).resolve().parents[3]
+                _sys.path.insert(0, str(_repo_root))
+                from gaia.store import reader as _reader
+            recent = _reader.cross_surface_query(
+                surface="harness_events", since="24h", last=20,
+            )
             if recent:
                 lines = ["\n# Recent Events (last 24h)"]
                 for evt in recent:
-                    ts_short = evt.get("ts", "")[:16]
-                    etype = evt.get("type", "")
-                    agent_name = evt.get("agent", "")
-                    result_str = evt.get("result", "")
+                    ts_short = (evt.get("timestamp") or "")[:16]
+                    etype = evt.get("type") or ""
+                    agent_name = evt.get("agent") or ""
+                    result_str = evt.get("summary") or ""
                     label = f"{agent_name}: " if agent_name else ""
                     lines.append(f"- [{ts_short}] {etype}: {label}{result_str}")
                 context_string += "\n".join(lines) + "\n"

package/dist/gaia-security/hooks/modules/events/event_writer.py

@@ -1,16 +1,27 @@
-"""Event writer and reader for the GAIA Event Context system.
+"""Event writer for the GAIA Event Context system.
+
+As of Brief 54 / Task 2.2 the event pipeline writes to the ``harness_events``
+table in the Gaia SQLite substrate (``~/.gaia/gaia.db``) instead of the legacy
+``events.jsonl`` file. This is an ATOMIC cutover: ``write_event`` no longer
+touches ``events.jsonl`` in any code path -- there is NO dual-write.
 
 Provides:
-    - EventWriter: append-only JSONL writer with file locking
-    - read_events(): read events from last N hours with optional filtering
-    - cleanup_old_events(): remove events older than N days
+    - EventWriter: non-blocking, silent-on-failure DB event writer
+    - read_events(): legacy JSONL reader (read-only; retained until Task 2.3
+      removes events.jsonl entirely -- no longer the canonical read path)
     - Event type constants
+
+The DB write delegates to ``gaia.store.writer.write_harness_event``, which
+resolves the DB path the same way every other gaia DB writer does (via
+``gaia.paths.db_path()`` -> ``GAIA_DATA_DIR`` / ``gaia.db``, falling back to
+``~/.gaia/gaia.db``). The hook subprocess imports the ``gaia`` package via the
+repo-root fallback already established by handoff_persister.
 """
 
-import fcntl
 import json
 import logging
 import os
+import sys
 from datetime import datetime, timedelta, timezone
 from pathlib import Path
 from typing import Any, Dict, List, Optional
@@ -32,17 +43,36 @@ HEARTBEAT = "heartbeat"
 USER_NOTE = "user.note"
 
 
+def _import_store_writer():
+    """Import gaia.store.writer, falling back to the repo layout.
+
+    Mirrors the import contract used by
+    hooks/modules/agents/handoff_persister.py: prefer a sibling ``gaia``
+    package if installed; otherwise add the repo root (two levels above
+    ``hooks/``) to ``sys.path`` and import from there.
+    """
+    try:
+        from gaia.store import writer as _writer
+    except ImportError:
+        _repo_root = Path(__file__).resolve().parents[3]
+        sys.path.insert(0, str(_repo_root))
+        from gaia.store import writer as _writer
+    return _writer
+
+
 class EventWriter:
-    """Append-only JSONL event writer with file locking.
+    """Non-blocking DB event writer.
 
-    All writes are wrapped in try/except -- events are non-critical and
-    must never block the hook pipeline.
+    All writes are wrapped in try/except -- events are non-critical and must
+    never block the hook pipeline. The ``events_dir`` argument is retained for
+    backward compatibility (legacy JSONL reads still resolve it) but is no
+    longer used for writes, which target the ``harness_events`` DB table.
     """
 
     def __init__(self, events_dir: Optional[Path] = None):
+        # Retained for compatibility with the legacy reader; not used for
+        # writes. Resolved lazily-safe (never raises here).
         self.events_dir = events_dir or get_events_dir()
-        self.events_file = self.events_dir / "events.jsonl"
-        self.lock_file = self.events_dir / "events.jsonl.lock"
 
     def write_event(
         self,
@@ -53,10 +83,10 @@ class EventWriter:
         severity: str = "info",
         meta: Optional[Dict[str, Any]] = None,
     ) -> None:
-        """Append a single event to the JSONL log.
+        """Append a single event to the ``harness_events`` DB table.
 
-        Thread-safe via exclusive file lock.  Fails silently on any error
-        to avoid disrupting the hook pipeline.
+        Fails silently on any error to avoid disrupting the hook pipeline --
+        same contract as the historical file writer.
 
         Args:
             event_type: Dotted event category (e.g. "agent.dispatch").
@@ -64,30 +94,21 @@ class EventWriter:
             agent: Agent involved, or empty string for non-agent events.
             result: Outcome summary string.
             severity: info | warning | error.
-            meta: Optional type-specific structured data.
+            meta: Optional type-specific structured data (stored as JSON in
+                the ``payload`` column).
         """
         try:
-            self.events_dir.mkdir(parents=True, exist_ok=True)
-
-            record: Dict[str, Any] = {
-                "ts": datetime.now(timezone.utc).isoformat(),
-                "type": event_type,
-                "source": source,
-                "agent": agent,
-                "result": result,
-                "severity": severity,
-            }
-            if meta:
-                record["meta"] = meta
-
-            with open(self.lock_file, "w") as lf:
-                fcntl.flock(lf.fileno(), fcntl.LOCK_EX)
-                try:
-                    with open(self.events_file, "a") as f:
-                        f.write(json.dumps(record, separators=(",", ":")) + "\n")
-                finally:
-                    fcntl.flock(lf.fileno(), fcntl.LOCK_UN)
-
+            writer = _import_store_writer()
+            workspace = os.environ.get("GAIA_WORKSPACE") or None
+            writer.write_harness_event(
+                event_type=event_type,
+                source=source,
+                agent=agent,
+                result=result,
+                severity=severity,
+                meta=meta,
+                workspace=workspace,
+            )
         except Exception as exc:
             logger.debug("Event write failed (non-fatal): %s", exc)
 
@@ -98,7 +119,13 @@ def read_events(
     limit: int = 50,
     events_dir: Optional[Path] = None,
 ) -> List[Dict[str, Any]]:
-    """Read recent events from the JSONL log.
+    """Read recent events from the legacy JSONL log.
+
+    NOTE: As of Task 2.2 this is no longer the canonical read path -- new
+    events are written to the ``harness_events`` DB table. This reader is
+    retained read-only until Task 2.3 removes ``events.jsonl`` entirely, so
+    historical pre-cutover events remain consultable. New callers should use
+    ``gaia.store.reader.cross_surface_query(surface="harness_events")``.
 
     Args:
         hours: How far back to look (default 24h).
@@ -148,63 +175,3 @@ def read_events(
     except Exception as exc:
         logger.debug("Event read failed (non-fatal): %s", exc)
         return []
-
-
-def cleanup_old_events(
-    days: int = 7,
-    events_dir: Optional[Path] = None,
-) -> int:
-    """Remove events older than *days* from the JSONL log.
-
-    Uses file locking to avoid conflicts with concurrent writers.
-    Retains lines that cannot be parsed (conservative).
-
-    Args:
-        days: Retention window in days (default 7).
-        events_dir: Override events directory (for testing).
-
-    Returns:
-        Number of events removed.
-    """
-    try:
-        edir = events_dir or get_events_dir()
-        events_file = edir / "events.jsonl"
-        lock_file = edir / "events.jsonl.lock"
-
-        if not events_file.exists():
-            return 0
-
-        retention_days = int(os.environ.get("GAIA_EVENT_RETENTION_DAYS", str(days)))
-        cutoff = datetime.now(timezone.utc) - timedelta(days=retention_days)
-        kept: List[str] = []
-        removed = 0
-
-        with open(lock_file, "w") as lf:
-            fcntl.flock(lf.fileno(), fcntl.LOCK_EX)
-            try:
-                with open(events_file, "r") as f:
-                    for line in f:
-                        line = line.strip()
-                        if not line:
-                            continue
-                        try:
-                            evt = json.loads(line)
-                            ts = datetime.fromisoformat(evt["ts"])
-                            if ts < cutoff:
-                                removed += 1
-                                continue
-                        except (json.JSONDecodeError, KeyError, ValueError):
-                            pass  # Keep unparseable lines
-                        kept.append(line)
-
-                with open(events_file, "w") as f:
-                    for line in kept:
-                        f.write(line + "\n")
-            finally:
-                fcntl.flock(lf.fileno(), fcntl.LOCK_UN)
-
-        return removed
-
-    except Exception as exc:
-        logger.debug("Event cleanup failed (non-fatal): %s", exc)
-        return 0

package/dist/gaia-security/hooks/modules/security/__init__.py

@@ -45,7 +45,6 @@ from .approval_scopes import (
 from .approval_grants import (
     check_approval_grant,
     cleanup_expired_grants,
-    get_latest_pending_approval,
     last_check_found_expired,
     ApprovalGrant,
 )
@@ -93,7 +92,6 @@ __all__ = [
     # Approval Grants
     "check_approval_grant",
     "cleanup_expired_grants",
-    "get_latest_pending_approval",
     "last_check_found_expired",
     "ApprovalGrant",
     # Shell unwrapper

package/dist/gaia-security/hooks/modules/security/approval_cleanup.py

@@ -1,14 +1,33 @@
 """
-Approval file cleanup for the subagent stop hook.
-
-Cleans up pending approval files after an agent completes, using the current
-per-nonce file layout under .claude/cache/approvals/pending-{nonce}.json.
+Approval cleanup for the subagent stop hook.
+
+DB-only since Task E FS retirement:
+  All pending approvals are stored exclusively in gaia.db (approvals table).
+
+P-3d23 invariant (Fix A): a pending younger than its TTL MUST survive ANY
+subagent's SubagentStop, regardless of that subagent's final plan_status.
+SubagentStop is the normal lifecycle of the documented block -> approve ->
+retry flow, and because subagents share the main session_id, revoking pendings
+by session-membership at SubagentStop wiped out every other outstanding pending
+in the session whenever any subagent finished as COMPLETE. cleanup() therefore
+no longer revokes fresh pendings by session membership; it only EXPIRES pendings
+that have genuinely aged past DEFAULT_PENDING_TTL_MINUTES (the 24h user-wait
+window). Expiry transitions the row to the schema 'expired' terminal status,
+distinct from a user/admin 'revoked'.
+
+The EXPIRE sweep is GLOBAL across sessions (list_pending(all_sessions=True)):
+SubagentStop is the only periodic sweep trigger, so a session-scoped sweep
+would never reap past-TTL pendings orphaned by dead/other sessions and they
+accumulate forever. The age gate (age_seconds >= TTL) is the sole guard and is
+session-independent, so a FRESH pending in ANY session always survives -- the
+widening to all sessions cannot regress the P-3d23 invariant.
 
 Also performs DB-backed soft-expire of PENDING approval_grants rows whose
 expires_at timestamp has passed (M3 addition).
 
 Provides:
-    - cleanup(): Delete pending approval files that match agent session
+    - cleanup(): Expire genuinely-aged pending DB approvals for the session
+    - expire_db_pendings(): TTL-sweep PENDING approvals past their pending TTL
     - expire_db_grants(): Soft-expire PENDING DB grants past their expires_at
     - consume_approval_file(): Backward-compatible alias for cleanup()
 """
@@ -16,20 +35,13 @@ Provides:
 import json
 import logging
 from datetime import datetime, timezone
-from pathlib import Path
 from typing import Optional, Set
 
-from ..core.paths import find_claude_dir
 from ..core.state import get_session_id
 
 logger = logging.getLogger(__name__)
 
 
-def _get_approvals_dir() -> Path:
-    """Return the approvals cache directory."""
-    return find_claude_dir() / "cache" / "approvals"
-
-
 def expire_db_grants(session_id: Optional[str] = None) -> int:
     """Soft-expire PENDING approval_grants rows whose expires_at has passed.
 
@@ -76,82 +88,239 @@ def expire_db_grants(session_id: Optional[str] = None) -> int:
         return 0
 
 
+def expire_db_pendings(
+    agent_type: str,
+    session_id: Optional[str] = None,
+) -> int:
+    """TTL-sweep: expire PENDING approvals aged past DEFAULT_PENDING_TTL_MINUTES.
+
+    Mirrors expire_db_grants() but for the pending plane. A pending row is
+    eligible for expiry only when its age (list_pending enriches each row with
+    age_seconds) is >= the 24h pending window. Fresh pendings are left
+    untouched -- this is the P-3d23 invariant: a pending within its TTL survives
+    any SubagentStop.
+
+    Each expiry transitions the row to the schema 'expired' terminal status via
+    store.expire(), carrying provenance: agent_id = the agent that triggered the
+    sweep and metadata reason="expired_ttl" so the auto-transition event is never
+    null-provenance.
+
+    Args:
+        agent_type: The agent whose SubagentStop drove the sweep (provenance +
+            logging).
+        session_id: Recorded as the expirer_session provenance on each expiry
+            event (the session whose SubagentStop drove the sweep). The sweep
+            itself is GLOBAL (all_sessions=True): TTL is the only gate, so
+            past-TTL pendings from any session -- including dead/other sessions
+            -- are reaped, while fresh pendings in any session survive.
+
+    Returns:
+        Number of pendings transitioned to 'expired'.
+    """
+    if session_id is None:
+        session_id = get_session_id()
+
+    try:
+        from gaia.approvals.store import list_pending, expire
+        from modules.security.approval_grants import DEFAULT_PENDING_TTL_MINUTES
+    except ImportError:
+        import pathlib as _pl
+        import sys as _sys
+        _repo = _pl.Path(__file__).resolve().parent.parent.parent.parent.parent
+        _sys.path.insert(0, str(_repo))
+        try:
+            from gaia.approvals.store import list_pending, expire
+            from modules.security.approval_grants import DEFAULT_PENDING_TTL_MINUTES
+        except ImportError as exc:
+            logger.debug(
+                "expire_db_pendings: dependencies unavailable (non-fatal): %s", exc
+            )
+            return 0
+
+    try:
+        # all_sessions=True: the TTL sweep is global. SubagentStop is the only
+        # periodic trigger we have, so it must expire EVERY past-TTL pending --
+        # including stale pendings from dead or other sessions, which would
+        # otherwise accumulate forever (no session-scoped Stop ever fires for
+        # them). The age gate below is what protects fresh pendings; widening
+        # the scope to all sessions does not touch any pending under its TTL.
+        pending_rows = list_pending(session_id=session_id, all_sessions=True)
+    except Exception as exc:
+        logger.debug("expire_db_pendings: list_pending failed (non-fatal): %s", exc)
+        return 0
+
+    ttl_seconds = DEFAULT_PENDING_TTL_MINUTES * 60
+    metadata = json.dumps(
+        {"reason": "expired_ttl", "source": "approval_cleanup.cleanup"}
+    )
+
+    expired = 0
+    for row in pending_rows:
+        approval_id = row.get("id", "")
+        if not approval_id:
+            continue
+
+        age_seconds = row.get("age_seconds", 0.0) or 0.0
+        if age_seconds < ttl_seconds:
+            # Fresh pending -- MUST survive (P-3d23 invariant).
+            continue
+
+        try:
+            expire(
+                approval_id,
+                expirer_session=session_id,
+                agent_id=agent_type,
+                metadata_json=metadata,
+            )
+            logger.info(
+                "Expired pending DB approval past TTL for agent '%s' "
+                "(approval_id: %s, age=%.0fs >= %ds)",
+                agent_type,
+                approval_id[:20],
+                age_seconds,
+                ttl_seconds,
+            )
+            expired += 1
+        except ValueError as exc:
+            # Already transitioned (race or double-call) -- not an error.
+            logger.debug(
+                "expire_db_pendings: expire skipped for approval_id=%s "
+                "(non-fatal): %s",
+                approval_id[:20], exc,
+            )
+        except Exception as exc:
+            logger.debug(
+                "expire_db_pendings: expire error for approval_id=%s "
+                "(non-fatal): %s",
+                approval_id[:20], exc,
+            )
+
+    return expired
+
+
 def cleanup(
     agent_type: str,
     session_id: Optional[str] = None,
     preserve_nonces: Optional[Set[str]] = None,
 ) -> bool:
-    """
-    Delete pending-{nonce}.json files for the current session after agent completion.
+    """Expire genuinely-aged pending DB approvals at subagent stop.
+
+    P-3d23 invariant (Fix A): cleanup() no longer revokes fresh pendings by
+    session-membership. SubagentStop is the normal lifecycle of the documented
+    block -> approve -> retry flow, and subagents share the main session_id, so
+    revoking every session pending at Stop wiped out outstanding approvals the
+    user still needed to act on. cleanup() now only EXPIRES pendings that have
+    aged past DEFAULT_PENDING_TTL_MINUTES (the 24h user-wait window); a pending
+    within its TTL ALWAYS survives, regardless of the stopping subagent's
+    plan_status.
 
-    Scans .claude/cache/approvals/ for pending files scoped to the current
-    session and removes them, preventing stale pending approvals from
-    accumulating after the agent run finishes.
+    DB-only since Task E FS retirement. No filesystem files are scanned or
+    deleted.
 
     Args:
-        agent_type: The agent type that just completed (for logging).
-        session_id: Session ID to scope cleanup (defaults to CLAUDE_SESSION_ID).
-        preserve_nonces: Optional set of nonce strings to skip during cleanup.
-            Used when an agent's final agent_contract_handoff still carries an
-            APPROVAL_REQUEST so that the pending file remains available for
-            the user to approve or reject. When None or empty, all session
-            pendings are eligible for deletion (legacy behaviour).
+        agent_type: The agent type that just completed (provenance + logging).
+        session_id: Session ID to scope the TTL sweep (defaults to
+            CLAUDE_SESSION_ID).
+        preserve_nonces: Optional set of approval_id strings the agent's final
+            agent_contract_handoff still references via APPROVAL_REQUEST. With
+            Fix A these are protected by their TTL already (they are fresh by
+            construction), so this set is now belt-and-suspenders: it guarantees
+            an explicitly-referenced pending is never expired even at a TTL edge.
+            It is no longer the only thing protecting a fresh pending.
 
     Returns:
-        True if any pending approval files were consumed, False otherwise.
+        True if any pending DB approvals were expired, False otherwise.
     """
     if session_id is None:
         session_id = get_session_id()
 
     preserve_nonces = preserve_nonces or set()
 
-    approvals_dir = _get_approvals_dir()
-    if not approvals_dir.exists():
-        return False
+    try:
+        from gaia.approvals.store import list_pending, expire
+        from modules.security.approval_grants import DEFAULT_PENDING_TTL_MINUTES
+    except ImportError:
+        import pathlib as _pl
+        import sys as _sys
+        _repo = _pl.Path(__file__).resolve().parent.parent.parent.parent.parent
+        _sys.path.insert(0, str(_repo))
+        try:
+            from gaia.approvals.store import list_pending, expire
+            from modules.security.approval_grants import DEFAULT_PENDING_TTL_MINUTES
+        except ImportError as exc:
+            logger.debug("cleanup: gaia.approvals.store unavailable (non-fatal): %s", exc)
+            return False
 
-    consumed = False
     try:
-        for pending_file in approvals_dir.glob("pending-*.json"):
-            # Skip the per-session index files
-            if pending_file.name.startswith("pending-index-"):
-                continue
-            try:
-                data = json.loads(pending_file.read_text())
-                if data.get("session_id") != session_id:
-                    continue
-
-                nonce = data.get("nonce", "")
-                if nonce and nonce in preserve_nonces:
-                    logger.info(
-                        "Preserving pending nonce=%s (still in APPROVAL_REQUEST)",
-                        nonce[:12],
-                    )
-                    continue
-
-                pending_file.unlink(missing_ok=True)
-                logger.info(
-                    "Consumed pending approval for agent '%s' "
-                    "(nonce: %s, command: %s)",
-                    agent_type,
-                    nonce or "unknown",
-                    data.get("command", "unknown"),
-                )
-                consumed = True
-
-            except (json.JSONDecodeError, TypeError):
-                # Corrupt file -- remove it (corrupt files are never
-                # preserve-eligible because we cannot read their nonce).
-                pending_file.unlink(missing_ok=True)
-                consumed = True
-            except Exception as e:
-                logger.debug(
-                    "Failed to process pending file %s (non-fatal): %s",
-                    pending_file.name, e,
-                )
-    except Exception as e:
-        logger.debug("Failed to scan approvals dir (non-fatal): %s", e)
+        # all_sessions=True: the stale-pending EXPIRE sweep is GLOBAL, not
+        # session-scoped. SubagentStop is our only periodic sweep trigger, so a
+        # session-scoped sweep never reaps past-TTL pendings left by dead or
+        # other sessions -- they accumulate forever (we had to drain 102 by
+        # hand). The age gate below (age_seconds >= ttl_seconds) is the sole
+        # guard: a FRESH pending in ANY session is < TTL and is skipped, so
+        # widening to all_sessions cannot expire a fresh pending. This stays
+        # EXPIRE-only and age-gated -- no session-membership revoke is
+        # reintroduced (the P-3d23 invariant holds at global scope).
+        pending_rows = list_pending(session_id=session_id, all_sessions=True)
+    except Exception as exc:
+        logger.debug("cleanup: list_pending failed (non-fatal): %s", exc)
+        return False
 
-    return consumed
+    ttl_seconds = DEFAULT_PENDING_TTL_MINUTES * 60
+    metadata = json.dumps(
+        {"reason": "expired_ttl", "source": "approval_cleanup.cleanup"}
+    )
+
+    expired = False
+    for row in pending_rows:
+        approval_id = row.get("id", "")
+        if not approval_id:
+            continue
+
+        age_seconds = row.get("age_seconds", 0.0) or 0.0
+        if age_seconds < ttl_seconds:
+            # Fresh pending -- MUST survive (P-3d23 invariant). preserve_nonces
+            # is no longer load-bearing here; the TTL gate already protects it.
+            continue
+
+        if approval_id in preserve_nonces:
+            # Belt-and-suspenders: an explicitly APPROVAL_REQUEST-referenced
+            # pending is never expired, even at the TTL edge.
+            logger.info(
+                "Preserving pending approval_id=%s (still in APPROVAL_REQUEST)",
+                approval_id[:20],
+            )
+            continue
+
+        try:
+            expire(
+                approval_id,
+                expirer_session=session_id,
+                agent_id=agent_type,
+                metadata_json=metadata,
+            )
+            logger.info(
+                "Expired pending DB approval past TTL for agent '%s' "
+                "(approval_id: %s, age=%.0fs >= %ds)",
+                agent_type,
+                approval_id[:20],
+                age_seconds,
+                ttl_seconds,
+            )
+            expired = True
+        except ValueError as exc:
+            # Approval was already transitioned (race or double-call) -- not an error.
+            logger.debug(
+                "cleanup: expire skipped for approval_id=%s (non-fatal): %s",
+                approval_id[:20], exc,
+            )
+        except Exception as exc:
+            logger.debug(
+                "cleanup: expire error for approval_id=%s (non-fatal): %s",
+                approval_id[:20], exc,
+            )
+
+    return expired
 
 
 # Backward-compatible alias