@jaguilar87/gaia 5.0.8 → 5.0.9

package/gaia/approvals/store.py

@@ -29,8 +29,16 @@ Public API::
     reject(approval_id, approver_session, *, agent_id=None, con=None)
         -> None  -- convenience wrapper: pending -> rejected
 
+    revoke(approval_id, revoker_session, *, agent_id=None, event_payload=None,
+           metadata_json=None, con=None)
+        -> None  -- convenience wrapper: pending -> revoked (user/admin cancel)
+
+    expire(approval_id, expirer_session=None, *, agent_id=None,
+           event_payload=None, metadata_json=None, con=None)
+        -> None  -- convenience wrapper: pending -> expired (TTL-sweep terminal)
+
     transition(approval_id, from_status, to_status, event_payload, *,
-               agent_id, session_id, con=None)
+               agent_id, session_id, metadata_json=None, con=None)
         -> None  -- state machine wrapper; raises if from_status does not match
 
     replay_for_approval(approval_id, con=None)
@@ -500,6 +508,7 @@ def transition(
     *,
     agent_id: Optional[str] = None,
     session_id: Optional[str] = None,
+    metadata_json: Optional[str] = None,
     con: Optional[sqlite3.Connection] = None,
 ) -> None:
     """State machine wrapper for approval status transitions.
@@ -512,21 +521,34 @@ def transition(
         approval_id: The P-{uuid4} approval identifier.
         from_status: Expected current status (guard). Must match the actual
             stored status or this function raises ValueError.
-        to_status: New status to write.
+        to_status: New status to write. Recognized: 'approved', 'rejected',
+            'revoked', 'expired'. The 'expired' status is the TTL-sweep
+            terminal status (schema.sql, bu_approvals_status_has_event excludes
+            it); it has no dedicated event_type in approval_events, so its audit
+            event is recorded as a REVOKED event carrying a reason in
+            metadata_json to distinguish a TTL expiry from a user/admin revoke.
         event_payload: Optional dict for the event's payload_json and fingerprint.
-        agent_id: Optional agent identifier for the event.
+        agent_id: Optional agent identifier for the event -- restores provenance
+            on auto-transitions (cleanup/expiry) that previously wrote null.
         session_id: Optional session identifier for the event.
+        metadata_json: Optional free-form JSON forwarded to the event's
+            metadata_json column (e.g. {"reason": "expired_ttl", ...}). Mirrors
+            record_event(); the canonical way to tag WHY an auto-transition fired.
         con: Optional open connection.
 
     Raises:
         ValueError: If the stored status does not match from_status.
         ValueError: If the approval_id does not exist.
     """
-    # Derive the event_type from the to_status transition.
+    # Derive the event_type from the to_status transition. 'expired' has no
+    # event_type of its own (the approval_events CHECK has no EXPIRED value and
+    # the status-has-event trigger does not gate it), so its audit trail is a
+    # REVOKED event distinguished by metadata_json reason="expired_ttl".
     _STATUS_TO_EVENT: dict[str, str] = {
         "approved": "APPROVED",
         "rejected": "REJECTED",
         "revoked": "REVOKED",
+        "expired": "REVOKED",
     }
     event_type = _STATUS_TO_EVENT.get(to_status, to_status.upper())
 
@@ -549,10 +571,10 @@ def transition(
                 f"Cannot transition approval {approval_id!r}: "
                 f"expected status={from_status!r} but found {actual_status!r}"
             )
-        _con.execute(
-            "UPDATE approvals SET status = ?, decided_at = ? WHERE id = ?",
-            (to_status, _now_iso(), approval_id),
-        )
+        # Insert the event FIRST so the DB trigger bu_approvals_status_has_event
+        # (schema.sql) can verify the event exists before the status UPDATE fires.
+        # The trigger fires BEFORE UPDATE, reading the transaction-visible
+        # approval_events rows; inserting the event first satisfies the guard.
         insert_event(
             _con,
             approval_id,
@@ -561,6 +583,11 @@ def transition(
             session_id=session_id,
             payload_json=payload_json_str,
             fingerprint=fp,
+            metadata_json=metadata_json,
+        )
+        _con.execute(
+            "UPDATE approvals SET status = ?, decided_at = ? WHERE id = ?",
+            (to_status, _now_iso(), approval_id),
         )
         if owned:
             _con.commit()
@@ -610,6 +637,8 @@ def revoke(
     revoker_session: str,
     *,
     agent_id: Optional[str] = None,
+    event_payload: Optional[Dict[str, Any]] = None,
+    metadata_json: Optional[str] = None,
     con: Optional[sqlite3.Connection] = None,
 ) -> None:
     """Revoke a pending approval (user or admin cancellation before execution).
@@ -621,7 +650,11 @@ def revoke(
     Args:
         approval_id: The P-{uuid4} approval identifier.
         revoker_session: The session_id of the revoking session.
-        agent_id: Optional agent identifier for the REVOKED event.
+        agent_id: Optional agent identifier for the REVOKED event -- pass this on
+            automated revocations so the event carries provenance instead of null.
+        event_payload: Optional dict for the event's payload_json and fingerprint.
+        metadata_json: Optional free-form JSON tagging WHY the revoke fired
+            (e.g. {"reason": "...", "source": "..."}), forwarded to the event.
         con: Optional open connection.
 
     Raises:
@@ -632,8 +665,53 @@ def revoke(
         approval_id,
         from_status="pending",
         to_status="revoked",
+        event_payload=event_payload,
         agent_id=agent_id,
         session_id=revoker_session,
+        metadata_json=metadata_json,
+        con=con,
+    )
+
+
+def expire(
+    approval_id: str,
+    expirer_session: Optional[str] = None,
+    *,
+    agent_id: Optional[str] = None,
+    event_payload: Optional[Dict[str, Any]] = None,
+    metadata_json: Optional[str] = None,
+    con: Optional[sqlite3.Connection] = None,
+) -> None:
+    """Expire a pending approval whose TTL has elapsed (cleanup-layer sweep).
+
+    Transitions approvals.status to 'expired' -- the schema's TTL-sweep terminal
+    status (schema.sql). 'expired' is deliberately distinct from 'revoked': a
+    revoke is a user/admin cancellation, an expire is the 24h pending window
+    (DEFAULT_PENDING_TTL_MINUTES) lapsing without a decision. Because the
+    approval_events schema has no EXPIRED event_type and the status-has-event
+    trigger does not gate 'expired', the audit event is recorded as REVOKED and
+    distinguished by metadata_json (reason="expired_ttl").
+
+    Args:
+        approval_id: The P-{uuid4} approval identifier.
+        expirer_session: The session_id under which the sweep ran (event session).
+        agent_id: Optional agent identifier for the event (provenance).
+        event_payload: Optional dict for the event's payload_json and fingerprint.
+        metadata_json: Optional free-form JSON tagging the expiry reason.
+        con: Optional open connection.
+
+    Raises:
+        ValueError: If the approval is not in 'pending' status.
+        ValueError: If the approval_id does not exist.
+    """
+    transition(
+        approval_id,
+        from_status="pending",
+        to_status="expired",
+        event_payload=event_payload,
+        agent_id=agent_id,
+        session_id=expirer_session,
+        metadata_json=metadata_json,
         con=con,
     )
 

package/gaia/store/schema.sql

@@ -785,7 +785,9 @@ CREATE TABLE IF NOT EXISTS approval_grants (
     status               TEXT NOT NULL DEFAULT 'PENDING',  -- PENDING|CONSUMED|REVOKED|EXPIRED
     consumed_indexes_json TEXT,                      -- JSON array of consumed command_set indexes
     consumed_at          TEXT,                       -- ISO8601 when all items consumed
-    revoked_at           TEXT                        -- ISO8601 when explicitly revoked
+    revoked_at           TEXT,                       -- ISO8601 when explicitly revoked
+    multi_use            INTEGER NOT NULL DEFAULT 0, -- 1 = multi-use grant, 0 = single-use (BOOLEAN)
+    confirmed            INTEGER NOT NULL DEFAULT 0  -- 1 = grant confirmed by user, 0 = pending (BOOLEAN)
 );
 
 CREATE INDEX IF NOT EXISTS idx_approval_grants_agent   ON approval_grants(agent_id);
@@ -950,6 +952,41 @@ BEGIN
     SELECT RAISE(ABORT, 'approval_events is append-only');
 END;
 
+-- BEFORE UPDATE trigger: enforce that every approvals.status transition has a
+-- preceding event in the append-only approval_events chain (Task B audit-
+-- immutability gap closure).
+--
+-- Fires when status changes TO one of the three user-visible terminal statuses
+-- (approved / rejected / revoked). For each new status it checks that an event
+-- row with the matching event_type exists for this approval_id. Because the
+-- canonical write path (store.transition) inserts the event FIRST and then
+-- UPDATEs status, the event row is already in the transaction-visible table by
+-- the time this trigger fires -- and the check passes. A direct UPDATE that
+-- bypasses the write path (no preceding insert_event call) will find COUNT=0
+-- and RAISE(ABORT), rolling back the update.
+--
+-- 'expired' is intentionally excluded: it is a cleanup-layer status (TTL
+-- sweep) with no corresponding event_type in the approval_events schema. All
+-- other status values ('pending') are only ever written by INSERT in
+-- insert_requested(), not by UPDATE, so they are not reachable here.
+CREATE TRIGGER IF NOT EXISTS bu_approvals_status_has_event
+BEFORE UPDATE OF status ON approvals
+WHEN NEW.status != OLD.status AND NEW.status IN ('approved', 'rejected', 'revoked')
+BEGIN
+    SELECT CASE
+        WHEN (
+            SELECT COUNT(*) FROM approval_events
+             WHERE approval_id = NEW.id
+               AND event_type = CASE NEW.status
+                                    WHEN 'approved' THEN 'APPROVED'
+                                    WHEN 'rejected' THEN 'REJECTED'
+                                    WHEN 'revoked'  THEN 'REVOKED'
+                                END
+        ) = 0
+        THEN RAISE(ABORT, 'approvals: status change requires a preceding event in approval_events')
+    END;
+END;
+
 -- ---------------------------------------------------------------------------
 -- schema_version: migration ledger.
 -- One row per applied schema migration; the highest version is the current

package/gaia/store/writer.py

@@ -28,6 +28,7 @@ Public API::
 from __future__ import annotations
 
 import hashlib
+import json
 import os
 import sqlite3
 from datetime import datetime, timezone
@@ -943,6 +944,90 @@ def save_integration(
         con.close()
 
 
+# ---------------------------------------------------------------------------
+# Public API: write_harness_event
+# ---------------------------------------------------------------------------
+#
+# Brief 54 / Task 2.2: the harness event pipeline (every hook firing) writes
+# here instead of the legacy events.jsonl file. This is the hot path -- every
+# AGENT_DISPATCH / COMMAND_EXECUTED / AGENT_COMPLETE / SESSION_END event flows
+# through it -- so the contract is: non-blocking and silent-on-failure at the
+# call site (the hook wraps this in try/except: pass), append-only INSERT, no
+# permission gate (episodic audit events are not curated memory).
+#
+# Column mapping (harness_events, schema.sql ~L756):
+#   type      <- event_type
+#   source    <- source
+#   agent     <- agent
+#   result    <- result
+#   severity  <- severity
+#   payload   <- json.dumps(meta)   (NULL when meta is falsy)
+#   workspace <- workspace          (None-safe; column is nullable, no FK)
+#   ts        <- _now_iso()
+#
+# No _ensure_workspace_row call: harness_events.workspace is a plain nullable
+# TEXT column with no FK to workspaces, so an arbitrary or NULL workspace is
+# valid and must not trigger workspace-row creation.
+# ---------------------------------------------------------------------------
+
+def write_harness_event(
+    *,
+    event_type: str,
+    source: str | None = None,
+    agent: str | None = None,
+    result: str | None = None,
+    severity: str | None = "info",
+    meta: Mapping[str, Any] | None = None,
+    workspace: str | None = None,
+    db_path: Path | None = None,
+) -> int:
+    """Append one row to ``harness_events`` and return its id.
+
+    This is the DB cutover of the historical ``EventWriter.write_event`` file
+    writer. It is append-only and not permission-gated. Callers in the hook
+    pipeline wrap it in ``try/except: pass`` -- this function itself does not
+    swallow exceptions, so tests and direct callers see real failures.
+
+    Args:
+        event_type: Dotted event category -> ``type`` column (NOT NULL).
+        source:     Who emitted the event (e.g. "hook").
+        agent:      Agent involved, or empty/None for non-agent events.
+        result:     Outcome summary string.
+        severity:   info | warning | error.
+        meta:       Optional structured data; serialized to JSON into the
+                    ``payload`` column. Falsy meta -> NULL payload.
+        workspace:  Workspace name or None (column is nullable, no FK).
+        db_path:    Optional explicit DB path (used by tests).
+
+    Returns:
+        Integer primary key of the inserted row.
+    """
+    payload = json.dumps(meta, separators=(",", ":")) if meta else None
+    con = _connect(db_path)
+    try:
+        cur = con.execute(
+            """
+            INSERT INTO harness_events
+                (workspace, ts, type, source, agent, result, severity, payload)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+            """,
+            (
+                workspace,
+                _now_iso(),
+                event_type,
+                source,
+                agent,
+                result,
+                severity,
+                payload,
+            ),
+        )
+        con.commit()
+        return cur.lastrowid
+    finally:
+        con.close()
+
+
 # ---------------------------------------------------------------------------
 # Public API: upsert_memory
 # ---------------------------------------------------------------------------
@@ -3210,6 +3295,321 @@ def consume_db_semantic_grant(
         con.close()
 
 
+# ---------------------------------------------------------------------------
+# Public API: insert_file_path_grant / check_db_file_path_grant /
+#             consume_db_file_path_grant (SCOPE_FILE_PATH DB migration)
+# ---------------------------------------------------------------------------
+#
+# Mirrors the SCOPE_SEMANTIC_SIGNATURE grant triplet above but for protected-
+# path Write/Edit approvals.  Uses scope='SCOPE_FILE_PATH' in the same
+# approval_grants table so all grant lifecycle is visible in one place.
+#
+# Lifecycle:
+#   insert_file_path_grant()       -- called by activate_db_pending_by_prefix()
+#                                     SCOPE_FILE_PATH branch; writes status=PENDING.
+#   check_db_file_path_grant()     -- called by check_approval_grant_for_file();
+#                                     returns the matching row dict.
+#   consume_db_file_path_grant()   -- called by _adapt_write_edit after allowing
+#                                     the protected-path write; sets CONSUMED.
+# ---------------------------------------------------------------------------
+
+
+def insert_file_path_grant(
+    approval_id: str,
+    file_path: str,
+    scope_signature: dict,
+    *,
+    agent_id: str | None = None,
+    session_id: str | None = None,
+    ttl_minutes: int = APPROVAL_GRANT_TTL_MINUTES,
+    db_path: Path | None = None,
+) -> dict:
+    """Insert a SCOPE_FILE_PATH row into approval_grants (status=PENDING).
+
+    Called by activate_db_pending_by_prefix() when a SCOPE_FILE_PATH pending
+    approval is activated (user approved the protected-path write).  The row
+    is later found by check_db_file_path_grant() on the subagent retry.
+
+    Args:
+        approval_id: The P-{hex} approval id that was activated.  Used as PK.
+        file_path: The absolute file path approved for write/edit.
+        scope_signature: Dict from ApprovalSignature.to_dict() -- stored in
+            command_set_json so check_db_file_path_grant() can match.
+        agent_id: Requesting agent identifier (audit only).
+        session_id: CLAUDE_SESSION_ID at grant time (audit only -- the check
+            side is cross-session, same as SCOPE_SEMANTIC_SIGNATURE).
+        ttl_minutes: Grant lifetime in minutes.
+        db_path: Optional explicit DB path (used by tests).
+
+    Returns:
+        {"status": "applied"} on success, {"status": "error", "reason": ...} otherwise.
+    """
+    from datetime import datetime, timezone, timedelta
+
+    expires_at = (
+        datetime.now(timezone.utc) + timedelta(minutes=ttl_minutes)
+    ).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+    grant_data = {
+        "file_path": file_path,
+        "scope_signature": scope_signature,
+    }
+
+    con = _connect(db_path)
+    try:
+        con.execute("BEGIN")
+        try:
+            con.execute(
+                """
+                INSERT OR IGNORE INTO approval_grants
+                    (approval_id, agent_id, session_id, command_set_json,
+                     scope, created_at, expires_at, status,
+                     consumed_indexes_json)
+                VALUES (?, ?, ?, ?, 'SCOPE_FILE_PATH', ?, ?, 'PENDING', '[]')
+                """,
+                (
+                    approval_id,
+                    agent_id,
+                    session_id,
+                    _json.dumps(grant_data),
+                    _now_iso(),
+                    expires_at,
+                ),
+            )
+            con.commit()
+        except Exception:
+            con.rollback()
+            raise
+        return _applied()
+    except Exception as exc:
+        return {"status": "error", "reason": str(exc)}
+    finally:
+        con.close()
+
+
+def check_db_file_path_grant(
+    file_path: str,
+    *,
+    db_path: Path | None = None,
+) -> dict | None:
+    """Find an active SCOPE_FILE_PATH grant for file_path in the DB.
+
+    Called by check_approval_grant_for_file() as the primary (DB) check path.
+    Matching uses the scope_signature stored in command_set_json via
+    matches_file_path_approval().
+
+    Grant must:
+    - Have scope='SCOPE_FILE_PATH'
+    - Have status='PENDING'
+    - Not be past its expires_at timestamp
+
+    The lookup is session-agnostic (same rationale as check_db_semantic_grant):
+    the activate-approve-retry flow crosses sessions, so a session_id constraint
+    would prevent the subagent from finding the grant the orchestrator created.
+
+    Args:
+        file_path: The file path to match.
+        db_path: Optional explicit DB path (used by tests).
+
+    Returns:
+        Dict with grant row data when a matching grant is found, None otherwise.
+    """
+    from datetime import datetime, timezone
+    from pathlib import Path as _Path
+
+    try:
+        import sys as _sys
+        _hooks_root = str(_Path(__file__).resolve().parents[2] / "hooks")
+        if _hooks_root not in _sys.path:
+            _sys.path.insert(0, _hooks_root)
+        from modules.security.approval_scopes import (
+            ApprovalSignature,
+            matches_file_path_approval,
+        )
+    except ImportError:
+        return None
+
+    now_iso = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+    con = _connect(db_path)
+    try:
+        rows = con.execute(
+            "SELECT * FROM approval_grants "
+            "WHERE scope = 'SCOPE_FILE_PATH' AND status = 'PENDING' "
+            "ORDER BY created_at DESC",
+        ).fetchall()
+
+        for row in rows:
+            row_dict = dict(row)
+            expires_at = row_dict.get("expires_at")
+            if expires_at and expires_at < now_iso:
+                continue
+
+            command_set_json = row_dict.get("command_set_json") or "{}"
+            try:
+                grant_data = _json.loads(command_set_json)
+            except Exception:
+                continue
+
+            sig_dict = grant_data.get("scope_signature")
+            if not sig_dict:
+                continue
+
+            try:
+                signature = ApprovalSignature.from_dict(sig_dict)
+                if matches_file_path_approval(signature, file_path):
+                    return row_dict
+            except Exception:
+                continue
+
+        return None
+    except Exception:
+        return None
+    finally:
+        con.close()
+
+
+def consume_db_file_path_grant(
+    approval_id: str,
+    *,
+    db_path: Path | None = None,
+) -> bool:
+    """Mark a SCOPE_FILE_PATH grant as CONSUMED (replay protection).
+
+    Called by _adapt_write_edit immediately after a protected-path write is
+    allowed via a DB file-path grant.  Setting status=CONSUMED prevents reuse.
+
+    Args:
+        approval_id: The grant to consume.
+        db_path: Optional explicit DB path (used by tests).
+
+    Returns:
+        True if the grant was found and consumed, False otherwise.
+    """
+    now = _now_iso()
+    con = _connect(db_path)
+    try:
+        con.execute("BEGIN")
+        try:
+            cur = con.execute(
+                """
+                UPDATE approval_grants
+                SET status = 'CONSUMED', consumed_at = ?
+                WHERE approval_id = ?
+                  AND scope = 'SCOPE_FILE_PATH'
+                  AND status = 'PENDING'
+                """,
+                (now, approval_id),
+            )
+            con.commit()
+            return cur.rowcount > 0
+        except Exception:
+            con.rollback()
+            raise
+    except Exception:
+        return False
+    finally:
+        con.close()
+
+
+# ---------------------------------------------------------------------------
+# Public API: confirm_db_grant / cleanup_expired_db_grants (v20 / grant-lifecycle)
+# ---------------------------------------------------------------------------
+#
+# Foundation scaffolding for the grant-lifecycle FS-to-DB migration (v20).
+# These helpers are called by the upcoming confirm_grant and
+# consume_session_grants migration; callers are NOT wired yet -- only the DB
+# write path is provided here.
+#
+#   confirm_db_grant()          -- sets confirmed=1 on a PENDING grant row;
+#                                  used when the user explicitly confirms a
+#                                  multi-use grant.
+#   cleanup_expired_db_grants() -- marks EXPIRED (or hard-deletes) any grant
+#                                  whose expires_at is in the past and whose
+#                                  status is still PENDING.  Idempotent.
+# ---------------------------------------------------------------------------
+
+
+def confirm_db_grant(
+    approval_id: str,
+    *,
+    db_path: Path | None = None,
+) -> dict:
+    """Set confirmed=1 on a PENDING approval_grants row.
+
+    Called when the user explicitly confirms a multi-use grant.  Only rows
+    with status='PENDING' are touched -- a CONSUMED or REVOKED grant cannot
+    be retroactively confirmed.
+
+    Args:
+        approval_id: The grant to confirm (PK of approval_grants).
+        db_path: Optional explicit DB path (used by tests).
+
+    Returns:
+        {"status": "applied"} when the row was updated.
+        {"status": "not_found"} when no PENDING row with that id exists.
+        {"status": "error", "reason": ...} on unexpected failure.
+    """
+    con = _connect(db_path)
+    try:
+        con.execute("BEGIN")
+        try:
+            cur = con.execute(
+                "UPDATE approval_grants SET confirmed = 1 "
+                "WHERE approval_id = ? AND status = 'PENDING'",
+                (approval_id,),
+            )
+            con.commit()
+        except Exception:
+            con.rollback()
+            raise
+        if cur.rowcount == 0:
+            return {"status": "not_found"}
+        return _applied()
+    except Exception as exc:
+        return {"status": "error", "reason": str(exc)}
+    finally:
+        con.close()
+
+
+def cleanup_expired_db_grants(
+    *,
+    db_path: Path | None = None,
+) -> int:
+    """Mark EXPIRED any PENDING approval_grants rows whose expires_at has passed.
+
+    Idempotent: rows already in a terminal status (CONSUMED, REVOKED, EXPIRED)
+    are not touched.  Rows with expires_at=NULL are skipped (no TTL set).
+
+    Args:
+        db_path: Optional explicit DB path (used by tests).
+
+    Returns:
+        Number of rows marked EXPIRED.
+    """
+    now = _now_iso()
+    con = _connect(db_path)
+    try:
+        con.execute("BEGIN")
+        try:
+            cur = con.execute(
+                "UPDATE approval_grants SET status = 'EXPIRED' "
+                "WHERE status = 'PENDING' "
+                "  AND expires_at IS NOT NULL "
+                "  AND expires_at < ?",
+                (now,),
+            )
+            con.commit()
+            return cur.rowcount
+        except Exception:
+            con.rollback()
+            raise
+    except Exception:
+        return 0
+    finally:
+        con.close()
+
+
 # ---------------------------------------------------------------------------
 # Public API: agent_contract_handoffs (v9 / M4)
 # ---------------------------------------------------------------------------