voodoo-framework 2.0.0__tar.gz → 2.1.0__tar.gz

{voodoo_framework-2.0.0 → voodoo_framework-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: voodoo-framework
-Version: 2.0.0
+Version: 2.1.0
 Summary: The programmable runtime for adaptive applications and operational systems — web, APIs, agents, workers, human workflows, distributed systems, and physical systems in one runtime.
 Author-email: Helder Perez <contact@helderperez.com>
 Maintainer-email: Helder Perez <contact@helderperez.com>
@@ -466,7 +466,7 @@ voodoo auth secret-key
 
 ## Project Status & Roadmap
 
-Voodoo is in active development (v1.16.0, Beta). The core runtime, UI system, AI agents, MCP, durable execution, and adaptive runtime are production-ready. PostgreSQL, S3/R2, and Redis adapters are shipped behind optional extras; the AI runtime (model-provider protocol, memory, durable agents, and durable human-in-the-loop) is the current focus.
+Voodoo is in active development (v2.0.0, Beta). The core runtime, UI system, AI agents, MCP, durable execution, adaptive runtime, model-provider protocol, layered memory, and durable agent registry are production-ready. PostgreSQL, S3/R2, and Redis adapters are shipped behind optional extras; durable human-in-the-loop is the current focus.
 
 ```mermaid
 timeline
@@ -477,26 +477,20 @@ timeline
         Unified Runtime : ExecutionEngine : Planner : Adaptive supervisor
         Durable Local Runtime : SQLite queue : Executions : Scheduler : Objects : Events
         Production Providers : PostgreSQL : S3/R2 : Redis
-    section In Progress (v1.16–v1.19)
+    section Shipped (v1.16–v2.0)
         ModelProvider protocol : Model descriptors : Routing aliases
         Memory capability : Layered memory : SQLite + FTS5
-        Durable Agents & HITL : Agent registry : Resumable approvals
-    section Planned (v2.0+)
-        Capability Security & Secrets : v2.0
-        Observability & Protocol : v2.1–v2.2
-        Local Runtime DX : v2.3
-```
-
-| Milestone | Version | Status |
-|-----------|---------|--------|
-| Core framework — runtime, UI, routing, reactive state | v1.0–v1.1 | ✅ Shipped |
-| AI & unified runtime — agents, tools, MCP, HITL, ExecutionEngine, planner, adaptive runtime | v1.2 | ✅ Shipped |
-| Durable local runtime (zero-infra) — SQLite storage, queue, executions, scheduler, objects, events | v1.3–v1.9 | ✅ Shipped |
-| Adapter contracts & runtime configuration | v1.10–v1.11 | ✅ Shipped |
-| Production providers (optional) — PostgreSQL, S3/R2, Redis | v1.12–v1.15 | ✅ Shipped |
-| AI runtime — model-provider protocol, memory, durable agents, durable HITL | v1.16–v1.19 | 🚧 In Progress |
-| Capability security & secrets | v2.0 | 📋 Planned |
-| Protocol stability & DX — observability, schemas, local runtime | v2.1–v2.3 | 📋 Planned |
+        Durable Agents : Agent registry : v2.0
+    section In Progress (v2.1)
+        Durable HITL : Resumable approvals
+    section Planned (v2.2+)
+        Capability Security & Secrets : v2.2
+        Observability & Protocol : v2.3–v2.4
+        Local Runtime DX : v2.5
+| AI runtime — model-provider protocol, memory, durable agent registry | v1.16–v2.0 | ✅ Shipped |
+| Durable human-in-the-loop — resumable approvals | v2.1 | 🚧 In Progress |
+| Capability security & secrets | v2.2 | 📋 Planned |
+| Protocol stability & DX — observability, schemas, local runtime | v2.3–v2.5 | 📋 Planned |
 
 See the [master roadmap](ROADMAP.md) and [sprint plan](SPRINT_PLAN.md) for details.
 

{voodoo_framework-2.0.0 → voodoo_framework-2.1.0}/README.md

@@ -403,7 +403,7 @@ voodoo auth secret-key
 
 ## Project Status & Roadmap
 
-Voodoo is in active development (v1.16.0, Beta). The core runtime, UI system, AI agents, MCP, durable execution, and adaptive runtime are production-ready. PostgreSQL, S3/R2, and Redis adapters are shipped behind optional extras; the AI runtime (model-provider protocol, memory, durable agents, and durable human-in-the-loop) is the current focus.
+Voodoo is in active development (v2.0.0, Beta). The core runtime, UI system, AI agents, MCP, durable execution, adaptive runtime, model-provider protocol, layered memory, and durable agent registry are production-ready. PostgreSQL, S3/R2, and Redis adapters are shipped behind optional extras; durable human-in-the-loop is the current focus.
 
 ```mermaid
 timeline
@@ -414,26 +414,20 @@ timeline
         Unified Runtime : ExecutionEngine : Planner : Adaptive supervisor
         Durable Local Runtime : SQLite queue : Executions : Scheduler : Objects : Events
         Production Providers : PostgreSQL : S3/R2 : Redis
-    section In Progress (v1.16–v1.19)
+    section Shipped (v1.16–v2.0)
         ModelProvider protocol : Model descriptors : Routing aliases
         Memory capability : Layered memory : SQLite + FTS5
-        Durable Agents & HITL : Agent registry : Resumable approvals
-    section Planned (v2.0+)
-        Capability Security & Secrets : v2.0
-        Observability & Protocol : v2.1–v2.2
-        Local Runtime DX : v2.3
-```
-
-| Milestone | Version | Status |
-|-----------|---------|--------|
-| Core framework — runtime, UI, routing, reactive state | v1.0–v1.1 | ✅ Shipped |
-| AI & unified runtime — agents, tools, MCP, HITL, ExecutionEngine, planner, adaptive runtime | v1.2 | ✅ Shipped |
-| Durable local runtime (zero-infra) — SQLite storage, queue, executions, scheduler, objects, events | v1.3–v1.9 | ✅ Shipped |
-| Adapter contracts & runtime configuration | v1.10–v1.11 | ✅ Shipped |
-| Production providers (optional) — PostgreSQL, S3/R2, Redis | v1.12–v1.15 | ✅ Shipped |
-| AI runtime — model-provider protocol, memory, durable agents, durable HITL | v1.16–v1.19 | 🚧 In Progress |
-| Capability security & secrets | v2.0 | 📋 Planned |
-| Protocol stability & DX — observability, schemas, local runtime | v2.1–v2.3 | 📋 Planned |
+        Durable Agents : Agent registry : v2.0
+    section In Progress (v2.1)
+        Durable HITL : Resumable approvals
+    section Planned (v2.2+)
+        Capability Security & Secrets : v2.2
+        Observability & Protocol : v2.3–v2.4
+        Local Runtime DX : v2.5
+| AI runtime — model-provider protocol, memory, durable agent registry | v1.16–v2.0 | ✅ Shipped |
+| Durable human-in-the-loop — resumable approvals | v2.1 | 🚧 In Progress |
+| Capability security & secrets | v2.2 | 📋 Planned |
+| Protocol stability & DX — observability, schemas, local runtime | v2.3–v2.5 | 📋 Planned |
 
 See the [master roadmap](ROADMAP.md) and [sprint plan](SPRINT_PLAN.md) for details.
 

{voodoo_framework-2.0.0 → voodoo_framework-2.1.0}/src/voodoo/__init__.py

@@ -102,7 +102,7 @@ from .ui.styles import (
 from .ui.styles.theme import Theme, ThemeColors, create_theme
 from .workers import task
 
-__version__ = "2.0.0"
+__version__ = "2.1.0"
 
 __all__ = [
     # Core runtime

{voodoo_framework-2.0.0 → voodoo_framework-2.1.0}/src/voodoo/cli/__init__.py

@@ -3,6 +3,7 @@ import typer
 from voodoo.cli import (
     agents,
     ai,
+    approvals,
     dev,
     doctor,
     executions,
@@ -38,6 +39,7 @@ app.add_typer(schedules.schedules_app, name="schedules")
 app.add_typer(executions.executions_app, name="executions")
 app.add_typer(objects.objects_app, name="objects")
 app.add_typer(agents.agents_app, name="agents")
+app.add_typer(approvals.approvals_app, name="approvals")
 app.add_typer(theme.theme_app, name="theme")
 # Top-level aliases per the Sprint 3 CLI surface: `voodoo execution <id>`
 # (timeline from the journal) and `voodoo events` (recent journal events).

voodoo_framework-2.1.0/src/voodoo/cli/approvals.py

@@ -0,0 +1,283 @@
+"""voodoo approvals — decide pending human approvals from any machine.
+
+Sprint 18: human approval is an execution state that survives process
+death. This CLI reads and decides approvals directly from the durable
+execution store (SQLite by default), so a decision can be made on any
+machine — the waiting execution resumes on whichever worker picks it up.
+
+    voodoo approvals list [--pending] [--json]
+    voodoo approvals show <execution-id> [--json]
+    voodoo approvals approve <execution-id> [--by NAME] [--note TEXT]
+    voodoo approvals deny <execution-id> [--by NAME] [--reason TEXT]
+
+With ``--app`` (e.g. ``main:app``) the application module is imported
+first so registered participants (agents, workflows) re-register and the
+approved execution actually re-runs.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+from pathlib import Path
+
+import typer
+
+from voodoo.cli import terminal
+
+approvals_app = typer.Typer(
+    name="approvals",
+    help="List, approve, and deny human approvals.",
+    no_args_is_help=True,
+    rich_markup_mode="rich",
+)
+
+
+def _resolve_store(store_path: str | None):
+    """Return the configured execution store (SQLite by default)."""
+    from voodoo.config import config
+    from voodoo.runtime.persistence import JSONFileExecutionStore
+    from voodoo.storage.execution import SQLiteExecutionStore
+
+    if store_path is None:
+        store_path = os.environ.get("VOODOO_EXECUTION_STORE", config.db_path).replace(
+            ":memory:", ".voodoo/state/data.db"
+        )
+
+    if Path(store_path).suffix == ".jsonl":
+        return JSONFileExecutionStore(store_path), store_path
+    return SQLiteExecutionStore(store_path), store_path
+
+
+def _load_app(app_str: str | None) -> None:
+    """Import the application module so participants re-register."""
+    if app_str is None:
+        return
+    import importlib
+    import sys
+
+    module_name, _, attr = app_str.partition(":")
+    attr = attr or "app"
+    sys.path.insert(0, os.getcwd())
+    mod = importlib.import_module(module_name)
+    getattr(mod, attr, None)
+
+
+def _list_approvals(store, pending_only: bool) -> list[dict]:
+    """Read approvals from a store, tolerating stores without the seam."""
+    if not hasattr(store, "load_approvals"):
+        return []
+    return store.load_approvals(pending_only=pending_only)
+
+
+@approvals_app.command("list")
+def list_approvals(
+    pending_only: bool = typer.Option(
+        False, "--pending", help="Only show pending approvals"
+    ),
+    store_path: str = typer.Option(
+        None, "--store", help="Path to the execution store (SQLite by default)"
+    ),
+    app_str: str = typer.Option(
+        None, "--app", help="App instance (e.g. main:app) to import first"
+    ),
+    json_mode: bool = typer.Option(
+        False, "--json", help="Machine-readable JSON output"
+    ),
+):
+    """List approvals — pending and decided."""
+    store, resolved = _resolve_store(store_path)
+    _load_app(app_str)
+    approvals = _list_approvals(store, pending_only)
+
+    if json_mode or terminal.is_json_mode():
+        terminal.json_output({"store": resolved, "approvals": approvals})
+        return
+
+    terminal.wordmark()
+    terminal.blank()
+    if not approvals:
+        terminal.muted(
+            f"no {'pending ' if pending_only else ''}approvals in {resolved}"
+        )
+        return
+    for a in approvals:
+        terminal.info(
+            f"  {str(a.get('id', ''))[:8]}  {(a.get('question') or '-')[:60]}"
+        )
+        terminal.muted(
+            f"    execution: {str(a.get('execution_id', ''))[:8]}"
+            f"  status: {a.get('status', '-')}"
+        )
+        terminal.muted(
+            f"    requested_by: {a.get('requested_by') or '-'}"
+            f"  decided_by: {a.get('decided_by') or '-'}"
+        )
+        terminal.blank()
+
+
+@approvals_app.command("show")
+def show_approval(
+    execution_id: str = typer.Argument(..., help="Execution id of the approval"),
+    store_path: str = typer.Option(
+        None, "--store", help="Path to the execution store (SQLite by default)"
+    ),
+    json_mode: bool = typer.Option(
+        False, "--json", help="Machine-readable JSON output"
+    ),
+):
+    """Show one approval in detail."""
+    store, resolved = _resolve_store(store_path)
+    approval = (
+        store.load_approval(execution_id) if hasattr(store, "load_approval") else None
+    )
+    if approval is None:
+        terminal.error(
+            f"approval for execution '{execution_id}' not found in {resolved}"
+        )
+        raise typer.Exit(1)
+
+    if json_mode or terminal.is_json_mode():
+        terminal.json_output(approval)
+        return
+
+    terminal.wordmark()
+    terminal.blank()
+    terminal.status_block(
+        [
+            ("id", str(approval.get("id", ""))),
+            ("execution", str(approval.get("execution_id", ""))),
+            ("trace", str(approval.get("trace_id", "") or "-")),
+            ("status", approval.get("status", "-")),
+            ("requested_by", approval.get("requested_by") or "-"),
+            ("decided_by", approval.get("decided_by") or "-"),
+            ("decided_at", approval.get("decided_at") or "-"),
+            ("participant", approval.get("participant") or "-"),
+        ]
+    )
+    question = approval.get("question")
+    if question:
+        terminal.blank()
+        terminal.label_value("question", question)
+    reason = approval.get("reason")
+    if reason:
+        terminal.label_value("reason", reason)
+    terminal.blank()
+
+
+def _decide(
+    execution_id: str,
+    *,
+    decision: str,
+    by: str,
+    message: str | None,
+    store_path: str | None,
+    app_str: str | None,
+    json_mode: bool,
+) -> None:
+    """Shared approve/deny path: recover waiting executions, then decide."""
+    from voodoo.runtime.engine import engine as runtime_engine
+
+    store, resolved = _resolve_store(store_path)
+    runtime_engine.use_store(store)
+    # Restore waiting executions + rehydrate persisted approvals so the
+    # decision applies to the durable record — not just this process.
+    runtime_engine.recover()
+    _load_app(app_str)
+
+    if runtime_engine.approvals.get(execution_id) is None:
+        if json_mode or terminal.is_json_mode():
+            terminal.json_output(
+                {
+                    "error": "approval not found",
+                    "execution_id": execution_id,
+                    "store": resolved,
+                }
+            )
+        else:
+            terminal.error(f"approval for execution '{execution_id}' not found")
+        raise typer.Exit(1)
+
+    decide_fn = runtime_engine.approve if decision == "approve" else runtime_engine.deny
+    kwargs = {}
+    if decision == "approve":
+        kwargs["note"] = message
+    else:
+        kwargs["reason"] = message or "denied"
+    executed = asyncio.run(decide_fn(execution_id, by=by, **kwargs))
+
+    if json_mode or terminal.is_json_mode():
+        terminal.json_output(
+            {
+                "store": resolved,
+                "decision": decision,
+                "execution_id": execution_id,
+                "by": by,
+                "resumed": executed.describe() if executed is not None else None,
+            }
+        )
+        return
+
+    terminal.wordmark()
+    terminal.blank()
+    icon = "✓" if decision == "approve" else "✗"
+    terminal.info(f"  {icon} {decision}d execution {execution_id[:8]} by {by}")
+    if executed is not None:
+        terminal.muted(f"    execution → {executed.status.value}")
+    else:
+        terminal.muted("    execution not found in engine (record updated only)")
+    terminal.blank()
+
+
+@approvals_app.command("approve")
+def approve_cmd(
+    execution_id: str = typer.Argument(..., help="Execution id to approve"),
+    by: str = typer.Option("human", "--by", help="Who is approving"),
+    note: str = typer.Option(None, "--note", help="Optional note"),
+    store_path: str = typer.Option(
+        None, "--store", help="Path to the execution store (SQLite by default)"
+    ),
+    app_str: str = typer.Option(
+        None, "--app", help="App instance (e.g. main:app) to import first"
+    ),
+    json_mode: bool = typer.Option(
+        False, "--json", help="Machine-readable JSON output"
+    ),
+):
+    """Approve a waiting execution — it resumes on a worker."""
+    _decide(
+        execution_id,
+        decision="approve",
+        by=by,
+        message=note,
+        store_path=store_path,
+        app_str=app_str,
+        json_mode=json_mode,
+    )
+
+
+@approvals_app.command("deny")
+def deny_cmd(
+    execution_id: str = typer.Argument(..., help="Execution id to deny"),
+    by: str = typer.Option("human", "--by", help="Who is denying"),
+    reason: str = typer.Option(None, "--reason", help="Denial reason"),
+    store_path: str = typer.Option(
+        None, "--store", help="Path to the execution store (SQLite by default)"
+    ),
+    app_str: str = typer.Option(
+        None, "--app", help="App instance (e.g. main:app) to import first"
+    ),
+    json_mode: bool = typer.Option(
+        False, "--json", help="Machine-readable JSON output"
+    ),
+):
+    """Deny a waiting execution — it fails with the denial reason."""
+    _decide(
+        execution_id,
+        decision="deny",
+        by=by,
+        message=reason,
+        store_path=store_path,
+        app_str=app_str,
+        json_mode=json_mode,
+    )

{voodoo_framework-2.0.0 → voodoo_framework-2.1.0}/src/voodoo/runtime/engine.py

@@ -117,6 +117,10 @@ class ExecutionEngine:
         self.approvals = ApprovalRegistry()
         self._execution_store: Any = None
         self._checkpoint_sequences: dict[str, int] = {}
+        #: Durable compute registry — named participants that can be
+        #: re-resolved after a restart (Sprint 18). Maps participant
+        #: name → compute callable + metadata.
+        self._participants: dict[str, Any] = {}
 
     # -- persistence / recovery ---------------------------------------------
 
@@ -124,6 +128,35 @@ class ExecutionEngine:
         """Attach an ExecutionStore (persistence seam, Phase 11)."""
         self._execution_store = store
 
+    def register_participant(
+        self,
+        name: str,
+        compute: ComputeFn | None = None,
+        *,
+        execute: Any | None = None,
+        kind: str = "compute",
+        capabilities: list[str] | None = None,
+    ) -> None:
+        """Register a named compute participant for durable resume (Sprint 18).
+
+        Participants registered here can be re-resolved by name after a
+        process restart, making ``WAITING_FOR_HUMAN`` executions fully
+        resumable on any worker (ROADMAP §50).
+        """
+        self._participants[name] = {
+            "compute": compute,
+            "execute": execute,
+            "kind": kind,
+            "capabilities": capabilities or [],
+        }
+
+    def resolve_participant(self, name: str) -> Any | None:
+        """Resolve a registered participant by name.
+
+        Returns the registration dict, or ``None`` when not registered.
+        """
+        return self._participants.get(name)
+
     def _persist(self, execution: Execution) -> None:
         """Checkpoint an execution — raises on failure (spec §51.16)."""
         if self._execution_store is None:
@@ -253,6 +286,7 @@ class ExecutionEngine:
                 else None
             ),
             reason=record["reason"],
+            participant=record.get("participant"),
         )
         self.approvals.records[execution.id] = approval
 
@@ -273,7 +307,7 @@ class ExecutionEngine:
         self._persist_approval(approval)
         self._journal_approval_decision(
             execution_id,
-            "human.approved",
+            "approval.granted",
             {"by": by, "capability": approval.capability},
         )
         waiting = self.executions.get(execution_id)
@@ -283,6 +317,16 @@ class ExecutionEngine:
             "human.approved",
             {"execution_id": execution_id, "by": by, "capability": approval.capability},
         )
+
+        # Durable resume (Sprint 18): when the live compute is gone (e.g.
+        # after a restart) but a registered participant exists, re-resolve
+        # the compute from the participant registry. The waiting execution's
+        # persisted intent supplies the outcome when the approval record
+        # has none (a restarted process serializes no live objects).
+        if approval.compute is None and approval.participant is not None:
+            approval.compute = self._participant_compute(approval)
+        if approval.intent is None and waiting is not None:
+            approval.intent = waiting.intent
         if approval.compute is None or approval.intent is None:
             if waiting is not None:
                 waiting.complete(result={"approved": True, "by": by})
@@ -310,6 +354,15 @@ class ExecutionEngine:
             waiting.complete(result=resumed.result)
         return resumed
 
+    def _participant_compute(self, approval: Any) -> ComputeFn | None:
+        """Synchronously re-resolve compute from the participant registry."""
+        if approval.participant is None:
+            return None
+        participant = self.resolve_participant(approval.participant)
+        if participant is None:
+            return None
+        return participant["compute"]
+
     async def deny(
         self, execution_id: str, *, by: str = "human", reason: str = "denied"
     ) -> Execution | None:
@@ -324,7 +377,7 @@ class ExecutionEngine:
         self._persist_approval(approval)
         self._journal_approval_decision(
             execution_id,
-            "human.denied",
+            "approval.denied",
             {"by": by, "reason": reason},
         )
         waiting = self.executions.get(execution_id)
@@ -526,6 +579,15 @@ class ExecutionEngine:
             # Persist the pending approval so a restart can rehydrate it
             # (spec §30 — decisions recorded as journal events on decide).
             self._persist_approval(approval)
+            self._journal_approval_decision(
+                execution.id,
+                "approval.requested",
+                {
+                    "capability": exc.context.get("capability"),
+                    "question": exc.message,
+                    "requested_by": execution.actor,
+                },
+            )
             await self._emit(
                 "human.approval_required",
                 {

{voodoo_framework-2.0.0 → voodoo_framework-2.1.0}/src/voodoo/runtime/human.py

@@ -54,6 +54,12 @@ class Approval:
     id: str = field(default_factory=lambda: str(uuid4()))
     created_at: datetime = field(default_factory=lambda: datetime.now(UTC))
 
+    #: Registered participant name — the durable handle to what re-runs
+    #: once approved (resolved through the engine's planner registry;
+    #: Sprint 18). Takes precedence over the live ``compute`` callable
+    #: when resuming after a restart.
+    participant: str | None = None
+
     # resumable payload — what to re-run once approved
     intent: Intent | None = None
     compute: ComputeFn | None = None
@@ -96,6 +102,7 @@ class ApprovalRegistry:
         compute: ComputeFn | None = None,
         output_type: type | None = None,
         context: ExecutionContext | None = None,
+        participant: str | None = None,
     ) -> Approval:
         approval = Approval(
             execution_id=execution.id,
@@ -112,6 +119,7 @@ class ApprovalRegistry:
             compute=compute,
             output_type=output_type,
             context=context,
+            participant=participant,
         )
         self.records[execution.id] = approval
         return approval

{voodoo_framework-2.0.0 → voodoo_framework-2.1.0}/src/voodoo/storage/execution/migrations.py

@@ -15,7 +15,8 @@ from voodoo.storage.database.interfaces import Migration
 from voodoo.storage.database.sqlite import register_framework_migration
 
 # Versions follow the global framework namespace: … 6 events, 7 artifacts,
-# 8 approvals.
+# 8 approvals (Sprint 18 added the `participant` column to the v8 CREATE —
+# existing databases add it via a guarded ALTER in each store's setup).
 EXECUTION_ARTIFACTS_MIGRATION_VERSION = 7
 EXECUTION_APPROVALS_MIGRATION_VERSION = 8
 
@@ -47,6 +48,7 @@ EXECUTION_APPROVALS_MIGRATION = Migration(
     name="execution_approvals",
     statements=(
         # Approvals (Sprint 4) — pending human decisions survive restarts.
+        # `participant` (Sprint 18) — durable compute handle for resume.
         """
         CREATE TABLE IF NOT EXISTS approvals (
             id TEXT PRIMARY KEY,
@@ -59,7 +61,8 @@ EXECUTION_APPROVALS_MIGRATION = Migration(
             decided_by TEXT,
             decided_at TEXT,
             reason TEXT,
-            created_at TEXT NOT NULL
+            created_at TEXT NOT NULL,
+            participant TEXT
         )
         """,
         "CREATE INDEX IF NOT EXISTS idx_approvals_execution "

{voodoo_framework-2.0.0 → voodoo_framework-2.1.0}/src/voodoo/storage/execution/postgres.py

@@ -81,6 +81,17 @@ class PostgresExecutionStore:
                     cur.execute(
                         _translate("ALTER TABLE executions ADD COLUMN checkpoint TEXT")
                     )
+            # Sprint 18: durable participant column for approvals — guarded
+            # because databases created at v8 already lack it.
+            with self._conn.cursor() as cur:
+                cur.execute(
+                    "SELECT column_name FROM information_schema.columns "
+                    "WHERE table_name = 'approvals' AND column_name = 'participant'"
+                )
+                if cur.fetchone() is None:
+                    cur.execute(
+                        _translate("ALTER TABLE approvals ADD COLUMN participant TEXT")
+                    )
             self._conn.commit()
 
     # -- ExecutionStore protocol (sync) ------------------------------------
@@ -230,13 +241,14 @@ class PostgresExecutionStore:
                 _translate(
                     "INSERT INTO approvals ("
                     "id, execution_id, trace_id, capability, question, requested_by, "
-                    "status, decided_by, decided_at, reason, created_at"
-                    ") VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s) "
+                    "status, decided_by, decided_at, reason, created_at, participant"
+                    ") VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s) "
                     "ON CONFLICT (id) DO UPDATE SET "
                     "status = excluded.status, "
                     "decided_by = excluded.decided_by, "
                     "decided_at = excluded.decided_at, "
-                    "reason = excluded.reason"
+                    "reason = excluded.reason, "
+                    "participant = excluded.participant"
                 ),
                 (
                     approval.id,
@@ -252,6 +264,7 @@ class PostgresExecutionStore:
                     approval.created_at.isoformat()
                     if approval.created_at
                     else datetime.now(UTC).isoformat(),
+                    getattr(approval, "participant", None),
                 ),
             )
         self._conn.commit()
@@ -268,6 +281,17 @@ class PostgresExecutionStore:
             row = cur.fetchone()
         return dict(row) if row is not None else None
 
+    def load_approvals(self, pending_only: bool = False) -> list[dict[str, Any]]:
+        """List approvals — newest first, optionally pending only (Sprint 18)."""
+        query = "SELECT * FROM approvals"
+        if pending_only:
+            query += " WHERE status = 'pending'"
+        query += " ORDER BY created_at DESC"
+        with self._lock, self._conn.cursor() as cur:
+            cur.execute(_translate(query))
+            rows = cur.fetchall()
+        return [dict(row) for row in rows]
+
     # -- internals ---------------------------------------------------------
 
     def _upsert_materialized(self, execution: Execution) -> None: