codex-autorunner 1.2.0__py3-none-any.whl → 1.3.0__py3-none-any.whl

codex_autorunner/surfaces/web/routes/pma.py

@@ -8,6 +8,7 @@ import asyncio
 import hashlib
 import json
 import logging
+import uuid
 from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any, Optional
@@ -38,12 +39,26 @@ from ....core.pma_context import (
     format_pma_prompt,
     load_pma_prompt,
 )
+from ....core.pma_delivery import deliver_pma_output_to_active_sink
+from ....core.pma_dispatches import (
+    find_pma_dispatch_path,
+    list_pma_dispatches,
+    list_pma_dispatches_for_turn,
+    resolve_pma_dispatch,
+)
+from ....core.pma_lane_worker import PmaLaneWorker
 from ....core.pma_lifecycle import PmaLifecycleRouter
 from ....core.pma_queue import PmaQueue, QueueItemState
 from ....core.pma_safety import PmaSafetyChecker, PmaSafetyConfig
+from ....core.pma_sink import PmaActiveSinkStore
 from ....core.pma_state import PmaStateStore
+from ....core.pma_transcripts import PmaTranscriptStore
 from ....core.time_utils import now_iso
 from ....core.utils import atomic_write
+from ....integrations.telegram.adapter import chunk_message
+from ....integrations.telegram.config import DEFAULT_STATE_FILE
+from ....integrations.telegram.constants import TELEGRAM_MAX_MESSAGE_LENGTH
+from ....integrations.telegram.state import OutboxRecord, TelegramStateStore
 from .agents import _available_agents, _serialize_model_catalog
 from .shared import SSE_HEADERS
 
@@ -69,8 +84,7 @@ def build_pma_routes() -> APIRouter:
     pma_audit_log: Optional[PmaAuditLog] = None
     pma_queue: Optional[PmaQueue] = None
     pma_queue_root: Optional[Path] = None
-    lane_workers: dict[str, asyncio.Task] = {}
-    lane_cancel_events: dict[str, asyncio.Event] = {}
+    lane_workers: dict[str, PmaLaneWorker] = {}
     item_futures: dict[str, asyncio.Future[dict[str, Any]]] = {}
 
     def _normalize_optional_text(value: Any) -> Optional[str]:
@@ -127,6 +141,12 @@ def build_pma_routes() -> APIRouter:
     def _get_safety_checker(request: Request) -> PmaSafetyChecker:
         nonlocal pma_safety_checker, pma_safety_root, pma_audit_log
         hub_root = request.app.state.config.root
+        supervisor = getattr(request.app.state, "hub_supervisor", None)
+        if supervisor is not None:
+            try:
+                return supervisor.get_pma_safety_checker()
+            except Exception:
+                pass
         if pma_safety_checker is None or pma_safety_root != hub_root:
             raw = getattr(request.app.state.config, "raw", {})
             pma_config = raw.get("pma", {}) if isinstance(raw, dict) else {}
@@ -160,6 +180,116 @@ def build_pma_routes() -> APIRouter:
             pma_queue_root = hub_root
         return pma_queue
 
+    def _resolve_telegram_state_path(request: Request) -> Path:
+        hub_root = request.app.state.config.root
+        raw = getattr(request.app.state.config, "raw", {})
+        telegram_cfg = raw.get("telegram_bot") if isinstance(raw, dict) else {}
+        if not isinstance(telegram_cfg, dict):
+            telegram_cfg = {}
+        state_file = telegram_cfg.get("state_file")
+        if not isinstance(state_file, str) or not state_file.strip():
+            state_file = DEFAULT_STATE_FILE
+        state_path = Path(state_file)
+        if not state_path.is_absolute():
+            state_path = (hub_root / state_path).resolve()
+        return state_path
+
+    async def _deliver_to_active_sink(
+        *,
+        request: Request,
+        result: dict[str, Any],
+        current: dict[str, Any],
+        lifecycle_event: Optional[dict[str, Any]],
+        turn_id: Optional[str] = None,
+    ) -> None:
+        if not lifecycle_event:
+            return
+        status = result.get("status") or "error"
+        if status != "ok":
+            return
+        assistant_text = _resolve_transcript_text(result)
+        if not assistant_text.strip():
+            return
+
+        hub_root = request.app.state.config.root
+        if not isinstance(turn_id, str) or not turn_id:
+            turn_id = _resolve_transcript_turn_id(result, current)
+        state_path = _resolve_telegram_state_path(request)
+        await deliver_pma_output_to_active_sink(
+            hub_root=hub_root,
+            assistant_text=assistant_text,
+            turn_id=turn_id,
+            lifecycle_event=lifecycle_event,
+            telegram_state_path=state_path,
+        )
+
+    async def _deliver_dispatches_to_active_sink(
+        *,
+        request: Request,
+        turn_id: Optional[str],
+    ) -> None:
+        if not isinstance(turn_id, str) or not turn_id:
+            return
+        hub_root = request.app.state.config.root
+        dispatches = list_pma_dispatches_for_turn(hub_root, turn_id)
+        if not dispatches:
+            return
+
+        sink_store = PmaActiveSinkStore(hub_root)
+        sink = sink_store.load()
+        if not isinstance(sink, dict) or sink.get("kind") != "telegram":
+            return
+
+        chat_id = sink.get("chat_id")
+        thread_id = sink.get("thread_id")
+        if not isinstance(chat_id, int):
+            return
+        if thread_id is not None and not isinstance(thread_id, int):
+            thread_id = None
+
+        state_path = _resolve_telegram_state_path(request)
+        store = TelegramStateStore(state_path)
+        try:
+            for dispatch in dispatches:
+                title = dispatch.title or "PMA dispatch"
+                priority = dispatch.priority or "info"
+                header = f"**PMA dispatch** ({priority})\n{title}"
+                body = dispatch.body.strip()
+                link_lines = []
+                for link in dispatch.links:
+                    label = link.get("label", "")
+                    href = link.get("href", "")
+                    if label and href:
+                        link_lines.append(f"- {label}: {href}")
+                details = "\n".join(
+                    line for line in [body, "\n".join(link_lines)] if line
+                ).strip()
+                message = header
+                if details:
+                    message = f"{header}\n\n{details}"
+
+                chunks = chunk_message(
+                    message, max_len=TELEGRAM_MAX_MESSAGE_LENGTH, with_numbering=True
+                )
+                for idx, chunk in enumerate(chunks, 1):
+                    record_id = f"pma-dispatch:{dispatch.dispatch_id}:{idx}"
+                    record = OutboxRecord(
+                        record_id=record_id,
+                        chat_id=chat_id,
+                        thread_id=thread_id,
+                        reply_to_message_id=None,
+                        placeholder_message_id=None,
+                        text=chunk,
+                        created_at=now_iso(),
+                        operation="send",
+                        outbox_key=record_id,
+                    )
+                    await store.enqueue_outbox(record)
+        except Exception:
+            logger.exception("Failed to enqueue PMA dispatch to Telegram outbox")
+        finally:
+            await store.close()
+
     async def _persist_state(store: Optional[PmaStateStore]) -> None:
         if store is None:
             return
@@ -207,6 +337,104 @@ def build_pma_routes() -> APIRouter:
             "finished_at": now_iso(),
         }
 
+    def _resolve_transcript_turn_id(
+        result: dict[str, Any], current: dict[str, Any]
+    ) -> str:
+        for candidate in (
+            result.get("turn_id"),
+            current.get("turn_id"),
+            current.get("client_turn_id"),
+        ):
+            if isinstance(candidate, str) and candidate.strip():
+                return candidate.strip()
+        return f"local-{uuid.uuid4()}"
+
+    def _resolve_transcript_text(result: dict[str, Any]) -> str:
+        message = result.get("message")
+        if isinstance(message, str) and message.strip():
+            return message
+        detail = result.get("detail")
+        if isinstance(detail, str) and detail.strip():
+            return detail
+        return ""
+
+    def _build_transcript_metadata(
+        *,
+        result: dict[str, Any],
+        current: dict[str, Any],
+        prompt_message: Optional[str],
+        lifecycle_event: Optional[dict[str, Any]],
+        model: Optional[str],
+        reasoning: Optional[str],
+        duration_ms: Optional[int],
+        finished_at: str,
+    ) -> dict[str, Any]:
+        trigger = "lifecycle_event" if lifecycle_event else "user_prompt"
+        metadata: dict[str, Any] = {
+            "status": result.get("status") or "error",
+            "agent": current.get("agent"),
+            "thread_id": result.get("thread_id") or current.get("thread_id"),
+            "turn_id": _resolve_transcript_turn_id(result, current),
+            "client_turn_id": current.get("client_turn_id") or "",
+            "lane_id": current.get("lane_id") or "",
+            "trigger": trigger,
+            "model": model,
+            "reasoning": reasoning,
+            "started_at": current.get("started_at"),
+            "finished_at": finished_at,
+            "duration_ms": duration_ms,
+            "user_prompt": prompt_message or "",
+        }
+        if lifecycle_event:
+            metadata["lifecycle_event"] = dict(lifecycle_event)
+            metadata["event_id"] = lifecycle_event.get("event_id")
+            metadata["event_type"] = lifecycle_event.get("event_type")
+            metadata["repo_id"] = lifecycle_event.get("repo_id")
+            metadata["run_id"] = lifecycle_event.get("run_id")
+            metadata["event_timestamp"] = lifecycle_event.get("timestamp")
+        return metadata
+
+    async def _persist_transcript(
+        *,
+        request: Request,
+        result: dict[str, Any],
+        current: dict[str, Any],
+        prompt_message: Optional[str],
+        lifecycle_event: Optional[dict[str, Any]],
+        model: Optional[str],
+        reasoning: Optional[str],
+        duration_ms: Optional[int],
+        finished_at: str,
+    ) -> Optional[dict[str, Any]]:
+        hub_root = request.app.state.config.root
+        store = PmaTranscriptStore(hub_root)
+        assistant_text = _resolve_transcript_text(result)
+        metadata = _build_transcript_metadata(
+            result=result,
+            current=current,
+            prompt_message=prompt_message,
+            lifecycle_event=lifecycle_event,
+            model=model,
+            reasoning=reasoning,
+            duration_ms=duration_ms,
+            finished_at=finished_at,
+        )
+        try:
+            pointer = store.write_transcript(
+                turn_id=metadata["turn_id"],
+                metadata=metadata,
+                assistant_text=assistant_text,
+            )
+        except Exception:
+            logger.exception("Failed to write PMA transcript")
+            return None
+        return {
+            "turn_id": pointer.turn_id,
+            "metadata_path": pointer.metadata_path,
+            "content_path": pointer.content_path,
+            "created_at": pointer.created_at,
+        }
+
     async def _get_interrupt_event() -> asyncio.Event:
         nonlocal pma_event
         async with pma_lock:
@@ -265,6 +493,10 @@ def build_pma_routes() -> APIRouter:
         *,
         request: Request,
         store: Optional[PmaStateStore] = None,
+        prompt_message: Optional[str] = None,
+        lifecycle_event: Optional[dict[str, Any]] = None,
+        model: Optional[str] = None,
+        reasoning: Optional[str] = None,
     ) -> None:
         nonlocal pma_current, pma_last_result, pma_active, pma_event
         async with pma_lock:
@@ -277,6 +509,7 @@ def build_pma_routes() -> APIRouter:
         status = result.get("status") or "error"
         started_at = current_snapshot.get("started_at")
         duration_ms = None
+        finished_at = now_iso()
         if started_at:
             try:
                 start_dt = datetime.fromisoformat(started_at.replace("Z", "+00:00"))
@@ -286,6 +519,23 @@ def build_pma_routes() -> APIRouter:
             except Exception:
                 pass
 
+        transcript_pointer = await _persist_transcript(
+            request=request,
+            result=result,
+            current=current_snapshot,
+            prompt_message=prompt_message,
+            lifecycle_event=lifecycle_event,
+            model=model,
+            reasoning=reasoning,
+            duration_ms=duration_ms,
+            finished_at=finished_at,
+        )
+        if transcript_pointer is not None:
+            pma_last_result = dict(pma_last_result or {})
+            pma_last_result["transcript"] = transcript_pointer
+            if not pma_last_result.get("turn_id"):
+                pma_last_result["turn_id"] = transcript_pointer.get("turn_id")
+
         log_event(
             logger,
             logging.INFO,
@@ -316,11 +566,33 @@ def build_pma_routes() -> APIRouter:
             status=status,
             error=result.get("detail") if status == "error" else None,
         )
+
+        delivery_turn_id = None
+        if isinstance(pma_last_result, dict):
+            candidate = pma_last_result.get("turn_id")
+            if isinstance(candidate, str) and candidate:
+                delivery_turn_id = candidate
+        await _deliver_to_active_sink(
+            request=request,
+            result=result,
+            current=current_snapshot,
+            lifecycle_event=lifecycle_event,
+            turn_id=delivery_turn_id,
+        )
+        await _deliver_dispatches_to_active_sink(
+            request=request,
+            turn_id=delivery_turn_id,
+        )
         _get_safety_checker(request).record_chat_result(
             agent=current_snapshot.get("agent") or "",
             status=status,
             error=result.get("detail") if status == "error" else None,
         )
+        if lifecycle_event:
+            _get_safety_checker(request).record_reactive_result(
+                status=status,
+                error=result.get("detail") if status == "error" else None,
+            )
 
         await _persist_state(store)
 
@@ -376,43 +648,45 @@ def build_pma_routes() -> APIRouter:
         }
 
     async def _ensure_lane_worker(lane_id: str, request: Request) -> None:
-        nonlocal lane_workers, lane_cancel_events
-        if lane_id in lane_workers and not lane_workers[lane_id].done():
+        nonlocal lane_workers
+        existing = lane_workers.get(lane_id)
+        if existing is not None and existing.is_running:
             return
 
-        cancel_event = asyncio.Event()
-        lane_cancel_events[lane_id] = cancel_event
+        async def _on_result(item, result: dict[str, Any]) -> None:
+            result_future = item_futures.get(item.item_id)
+            if result_future and not result_future.done():
+                result_future.set_result(result)
+            item_futures.pop(item.item_id, None)
 
-        async def lane_worker():
-            queue = _get_pma_queue(request)
-            await queue.replay_pending(lane_id)
-            while not cancel_event.is_set():
-                item = await queue.dequeue(lane_id)
-                if item is None:
-                    await queue.wait_for_lane_item(lane_id, cancel_event)
-                    continue
+        queue = _get_pma_queue(request)
+        worker = PmaLaneWorker(
+            lane_id,
+            queue,
+            lambda item: _execute_queue_item(item, request),
+            log=logger,
+            on_result=_on_result,
+        )
+        lane_workers[lane_id] = worker
+        await worker.start()
 
-                if cancel_event.is_set():
-                    await queue.fail_item(item, "cancelled by lane stop")
-                    continue
+    async def _stop_lane_worker(lane_id: str) -> None:
+        worker = lane_workers.get(lane_id)
+        if worker is None:
+            return
+        await worker.stop()
+        lane_workers.pop(lane_id, None)
 
-                result_future = item_futures.get(item.item_id)
-                try:
-                    result = await _execute_queue_item(item, request)
-                    await queue.complete_item(item, result)
-                    if result_future and not result_future.done():
-                        result_future.set_result(result)
-                except Exception as exc:
-                    logger.exception("Failed to process queue item %s", item.item_id)
-                    error_result = {"status": "error", "detail": str(exc)}
-                    await queue.fail_item(item, str(exc))
-                    if result_future and not result_future.done():
-                        result_future.set_result(error_result)
-                finally:
-                    item_futures.pop(item.item_id, None)
-
-        task = asyncio.create_task(lane_worker())
-        lane_workers[lane_id] = task
+    class _AppRequest:
+        def __init__(self, app: Any) -> None:
+            self.app = app
+
+    async def _ensure_lane_worker_for_app(app: Any, lane_id: str) -> None:
+        await _ensure_lane_worker(lane_id, _AppRequest(app))
+
+    async def _stop_lane_worker_for_app(app: Any, lane_id: str) -> None:
+        _ = app
+        await _stop_lane_worker(lane_id)
 
     async def _execute_queue_item(item: Any, request: Request) -> dict[str, Any]:
         hub_root = request.app.state.config.root
@@ -423,6 +697,9 @@ def build_pma_routes() -> APIRouter:
         agent = payload.get("agent")
         model = _normalize_optional_text(payload.get("model"))
         reasoning = _normalize_optional_text(payload.get("reasoning"))
+        lifecycle_event = payload.get("lifecycle_event")
+        if not isinstance(lifecycle_event, dict):
+            lifecycle_event = None
 
         store = _get_state_store(request)
         agents, available_default = _available_agents(request)
@@ -479,14 +756,30 @@ def build_pma_routes() -> APIRouter:
                 "client_turn_id": client_turn_id or "",
             }
             if started:
-                await _finalize_result(error_result, request=request, store=store)
+                await _finalize_result(
+                    error_result,
+                    request=request,
+                    store=store,
+                    prompt_message=message,
+                    lifecycle_event=lifecycle_event,
+                    model=model,
+                    reasoning=reasoning,
+                )
             return error_result
 
         interrupt_event = await _get_interrupt_event()
         if interrupt_event.is_set():
             result = {"status": "interrupted", "detail": "PMA chat interrupted"}
             if started:
-                await _finalize_result(result, request=request, store=store)
+                await _finalize_result(
+                    result,
+                    request=request,
+                    store=store,
+                    prompt_message=message,
+                    lifecycle_event=lifecycle_event,
+                    model=model,
+                    reasoning=reasoning,
+                )
             return result
 
         meta_future: asyncio.Future[tuple[str, str]] = (
@@ -541,7 +834,15 @@ def build_pma_routes() -> APIRouter:
                 if opencode is None:
                     result = {"status": "error", "detail": "OpenCode unavailable"}
                     if started:
-                        await _finalize_result(result, request=request, store=store)
+                        await _finalize_result(
+                            result,
+                            request=request,
+                            store=store,
+                            prompt_message=message,
+                            lifecycle_event=lifecycle_event,
+                            model=model,
+                            reasoning=reasoning,
+                        )
                     return result
                 result = await _execute_opencode(
                     opencode,
@@ -559,7 +860,15 @@ def build_pma_routes() -> APIRouter:
                 if supervisor is None or events is None:
                     result = {"status": "error", "detail": "App-server unavailable"}
                     if started:
-                        await _finalize_result(result, request=request, store=store)
+                        await _finalize_result(
+                            result,
+                            request=request,
+                            store=store,
+                            prompt_message=message,
+                            lifecycle_event=lifecycle_event,
+                            model=model,
+                            reasoning=reasoning,
+                        )
                     return result
                 result = await _execute_app_server(
                     supervisor,
@@ -580,12 +889,28 @@ def build_pma_routes() -> APIRouter:
                     "detail": str(exc),
                     "client_turn_id": client_turn_id or "",
                 }
-                await _finalize_result(error_result, request=request, store=store)
+                await _finalize_result(
+                    error_result,
+                    request=request,
+                    store=store,
+                    prompt_message=message,
+                    lifecycle_event=lifecycle_event,
+                    model=model,
+                    reasoning=reasoning,
+                )
             raise
 
         result = dict(result or {})
         result["client_turn_id"] = client_turn_id or ""
-        await _finalize_result(result, request=request, store=store)
+        await _finalize_result(
+            result,
+            request=request,
+            store=store,
+            prompt_message=message,
+            lifecycle_event=lifecycle_event,
+            model=model,
+            reasoning=reasoning,
+        )
         return result
 
     @router.get("/active")
@@ -626,6 +951,28 @@ def build_pma_routes() -> APIRouter:
                 current = {}
         return {"active": active, "current": current, "last_result": last_result}
 
+    @router.get("/history")
+    def list_pma_history(request: Request, limit: int = 50) -> dict[str, Any]:
+        pma_config = _get_pma_config(request)
+        if not pma_config.get("enabled", True):
+            raise HTTPException(status_code=404, detail="PMA is disabled")
+        hub_root = request.app.state.config.root
+        store = PmaTranscriptStore(hub_root)
+        entries = store.list_recent(limit=limit)
+        return {"entries": entries}
+
+    @router.get("/history/{turn_id}")
+    def get_pma_history(turn_id: str, request: Request) -> dict[str, Any]:
+        pma_config = _get_pma_config(request)
+        if not pma_config.get("enabled", True):
+            raise HTTPException(status_code=404, detail="PMA is disabled")
+        hub_root = request.app.state.config.root
+        store = PmaTranscriptStore(hub_root)
+        transcript = store.read_transcript(turn_id)
+        if not transcript:
+            raise HTTPException(status_code=404, detail="Transcript not found")
+        return transcript
+
     @router.get("/agents")
     def list_pma_agents(request: Request) -> dict[str, Any]:
         pma_config = _get_pma_config(request)
@@ -969,6 +1316,10 @@ def build_pma_routes() -> APIRouter:
             )
 
         hub_root = request.app.state.config.root
+        try:
+            PmaActiveSinkStore(hub_root).set_web()
+        except Exception:
+            logger.exception("Failed to update PMA active sink for web")
         queue = _get_pma_queue(request)
 
         lane_id = "pma:default"
@@ -1045,8 +1396,7 @@ def build_pma_routes() -> APIRouter:
         if result.status != "ok":
             raise HTTPException(status_code=500, detail=result.error)
 
-        if lane_id in lane_cancel_events:
-            lane_cancel_events[lane_id].set()
+        await _stop_lane_worker(lane_id)
 
         await _interrupt_active(request, reason="Lane stopped", source="user_request")
 
@@ -1464,11 +1814,18 @@ def build_pma_routes() -> APIRouter:
             reset = bool(body.get("reset", False))
 
         pma_dir = hub_root / ".codex-autorunner" / "pma"
-        active_context_path = pma_dir / "active_context.md"
-        context_log_path = pma_dir / "context_log.md"
+        docs_dir = _pma_docs_dir(hub_root)
+        docs_dir.mkdir(parents=True, exist_ok=True)
+        active_context_path = docs_dir / "active_context.md"
+        context_log_path = docs_dir / "context_log.md"
+        legacy_active_context_path = pma_dir / "active_context.md"
+        legacy_context_log_path = pma_dir / "context_log.md"
 
         try:
-            active_content = active_context_path.read_text(encoding="utf-8")
+            if active_context_path.exists():
+                active_content = active_context_path.read_text(encoding="utf-8")
+            else:
+                active_content = legacy_active_context_path.read_text(encoding="utf-8")
         except Exception as exc:
             raise HTTPException(
                 status_code=500, detail=f"Failed to read active_context.md: {exc}"
@@ -1490,6 +1847,9 @@ def build_pma_routes() -> APIRouter:
         try:
             with context_log_path.open("a", encoding="utf-8") as f:
                 f.write(snapshot_content)
+            if legacy_context_log_path.exists():
+                with legacy_context_log_path.open("a", encoding="utf-8") as f:
+                    f.write(snapshot_content)
         except Exception as exc:
             raise HTTPException(
                 status_code=500, detail=f"Failed to append context_log.md: {exc}"
@@ -1498,6 +1858,10 @@ def build_pma_routes() -> APIRouter:
         if reset:
             try:
                 atomic_write(active_context_path, pma_active_context_content())
+                if legacy_active_context_path.exists():
+                    atomic_write(
+                        legacy_active_context_path, pma_active_context_content()
+                    )
             except Exception as exc:
                 raise HTTPException(
                     status_code=500, detail=f"Failed to reset active_context.md: {exc}"
@@ -1539,6 +1903,55 @@ def build_pma_routes() -> APIRouter:
         "prompt.md": pma_prompt_content,
     }
 
+    def _pma_docs_dir(hub_root: Path) -> Path:
+        return hub_root / ".codex-autorunner" / "pma" / "docs"
+
+    def _pma_legacy_doc_path(hub_root: Path, name: str) -> Path:
+        return hub_root / ".codex-autorunner" / "pma" / name
+
+    def _normalize_doc_name(name: str) -> str:
+        try:
+            return sanitize_filename(name)
+        except ValueError as exc:
+            raise HTTPException(
+                status_code=400, detail=f"Invalid doc name: {name}"
+            ) from exc
+
+    def _sorted_doc_names(docs_dir: Path) -> list[str]:
+        names: set[str] = set()
+        if docs_dir.exists():
+            try:
+                for path in docs_dir.iterdir():
+                    if not path.is_file():
+                        continue
+                    if path.name.startswith("."):
+                        continue
+                    names.add(path.name)
+            except OSError:
+                pass
+        ordered: list[str] = []
+        for doc_name in PMA_DOC_ORDER:
+            if doc_name in names:
+                ordered.append(doc_name)
+        remaining = sorted(name for name in names if name not in ordered)
+        ordered.extend(remaining)
+        return ordered
+
+    def _write_doc_history(
+        hub_root: Path, doc_name: str, content: str
+    ) -> Optional[Path]:
+        docs_dir = _pma_docs_dir(hub_root)
+        history_root = docs_dir / "_history" / doc_name
+        try:
+            history_root.mkdir(parents=True, exist_ok=True)
+            timestamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%S%fZ")
+            history_path = history_root / f"{timestamp}.md"
+            atomic_write(history_path, content)
+            return history_path
+        except Exception:
+            logger.exception("Failed to write PMA doc history for %s", doc_name)
+            return None
+
     @router.get("/docs/default/{name}")
     def get_pma_doc_default(name: str, request: Request) -> dict[str, str]:
         pma_config = _get_pma_config(request)
@@ -1557,10 +1970,16 @@ def build_pma_routes() -> APIRouter:
         if not pma_config.get("enabled", True):
             raise HTTPException(status_code=404, detail="PMA is disabled")
         hub_root = request.app.state.config.root
-        pma_dir = hub_root / ".codex-autorunner" / "pma"
+        try:
+            ensure_pma_docs(hub_root)
+        except Exception as exc:
+            raise HTTPException(
+                status_code=500, detail=f"Failed to ensure PMA docs: {exc}"
+            ) from exc
+        docs_dir = _pma_docs_dir(hub_root)
         result: list[dict[str, Any]] = []
-        for doc_name in PMA_DOC_ORDER:
-            doc_path = pma_dir / doc_name
+        for doc_name in _sorted_doc_names(docs_dir):
+            doc_path = docs_dir / doc_name
             entry: dict[str, Any] = {"name": doc_name}
             if doc_path.exists():
                 entry["exists"] = True
@@ -1591,13 +2010,16 @@ def build_pma_routes() -> APIRouter:
         pma_config = _get_pma_config(request)
         if not pma_config.get("enabled", True):
             raise HTTPException(status_code=404, detail="PMA is disabled")
-        if name not in PMA_DOC_SET:
-            raise HTTPException(status_code=400, detail=f"Unknown doc name: {name}")
+        name = _normalize_doc_name(name)
         hub_root = request.app.state.config.root
-        pma_dir = hub_root / ".codex-autorunner" / "pma"
-        doc_path = pma_dir / name
+        docs_dir = _pma_docs_dir(hub_root)
+        doc_path = docs_dir / name
         if not doc_path.exists():
-            raise HTTPException(status_code=404, detail=f"Doc not found: {name}")
+            legacy_path = _pma_legacy_doc_path(hub_root, name)
+            if legacy_path.exists():
+                doc_path = legacy_path
+            else:
+                raise HTTPException(status_code=404, detail=f"Doc not found: {name}")
         try:
             content = doc_path.read_text(encoding="utf-8")
         except Exception as exc:
@@ -1613,7 +2035,15 @@ def build_pma_routes() -> APIRouter:
         pma_config = _get_pma_config(request)
         if not pma_config.get("enabled", True):
             raise HTTPException(status_code=404, detail="PMA is disabled")
-        if name not in PMA_DOC_SET:
+        name = _normalize_doc_name(name)
+        hub_root = request.app.state.config.root
+        pma_dir = hub_root / ".codex-autorunner" / "pma"
+        docs_dir = _pma_docs_dir(hub_root)
+        if (
+            name not in PMA_DOC_SET
+            and not (docs_dir / name).exists()
+            and not (pma_dir / name).exists()
+        ):
             raise HTTPException(status_code=400, detail=f"Unknown doc name: {name}")
         content = body.get("content", "")
         if not isinstance(content, str):
@@ -1623,16 +2053,21 @@ def build_pma_routes() -> APIRouter:
             raise HTTPException(
                 status_code=413, detail=f"Content too large (max {MAX_DOC_SIZE} bytes)"
             )
-        hub_root = request.app.state.config.root
-        pma_dir = hub_root / ".codex-autorunner" / "pma"
         pma_dir.mkdir(parents=True, exist_ok=True)
-        doc_path = pma_dir / name
+        docs_dir.mkdir(parents=True, exist_ok=True)
+        doc_path = docs_dir / name
         try:
             atomic_write(doc_path, content)
         except Exception as exc:
             raise HTTPException(
                 status_code=500, detail=f"Failed to write doc: {exc}"
             ) from exc
+        try:
+            if name in PMA_DOC_SET or (pma_dir / name).exists():
+                atomic_write(pma_dir / name, content)
+        except Exception:
+            logger.exception("Failed to update legacy PMA doc %s", name)
+        _write_doc_history(hub_root, name, content)
         details = {
             "name": name,
             "size": len(content.encode("utf-8")),
@@ -1646,6 +2081,152 @@ def build_pma_routes() -> APIRouter:
         )
         return {"name": name, "status": "ok"}
 
+    @router.get("/docs/history/{name}")
+    def list_pma_doc_history(
+        name: str, request: Request, limit: int = 50
+    ) -> dict[str, Any]:
+        pma_config = _get_pma_config(request)
+        if not pma_config.get("enabled", True):
+            raise HTTPException(status_code=404, detail="PMA is disabled")
+        name = _normalize_doc_name(name)
+        hub_root = request.app.state.config.root
+        docs_dir = _pma_docs_dir(hub_root)
+        history_dir = docs_dir / "_history" / name
+        entries: list[dict[str, Any]] = []
+        if history_dir.exists():
+            try:
+                for path in sorted(
+                    (p for p in history_dir.iterdir() if p.is_file()),
+                    key=lambda p: p.name,
+                    reverse=True,
+                ):
+                    if len(entries) >= limit:
+                        break
+                    try:
+                        stat = path.stat()
+                        entries.append(
+                            {
+                                "id": path.name,
+                                "size": stat.st_size,
+                                "mtime": datetime.fromtimestamp(
+                                    stat.st_mtime, tz=timezone.utc
+                                ).isoformat(),
+                            }
+                        )
+                    except OSError:
+                        continue
+            except OSError:
+                pass
+        return {"name": name, "entries": entries}
+
+    @router.get("/docs/history/{name}/{version_id}")
+    def get_pma_doc_history(
+        name: str, version_id: str, request: Request
+    ) -> dict[str, str]:
+        pma_config = _get_pma_config(request)
+        if not pma_config.get("enabled", True):
+            raise HTTPException(status_code=404, detail="PMA is disabled")
+        name = _normalize_doc_name(name)
+        version_id = _normalize_doc_name(version_id)
+        hub_root = request.app.state.config.root
+        docs_dir = _pma_docs_dir(hub_root)
+        history_path = docs_dir / "_history" / name / version_id
+        if not history_path.exists():
+            raise HTTPException(status_code=404, detail="History entry not found")
+        try:
+            content = history_path.read_text(encoding="utf-8")
+        except Exception as exc:
+            raise HTTPException(
+                status_code=500, detail=f"Failed to read history entry: {exc}"
+            ) from exc
+        return {"name": name, "version_id": version_id, "content": content}
+
+    @router.get("/dispatches")
+    def list_pma_dispatches_endpoint(
+        request: Request, include_resolved: bool = False, limit: int = 100
+    ) -> dict[str, Any]:
+        pma_config = _get_pma_config(request)
+        if not pma_config.get("enabled", True):
+            raise HTTPException(status_code=404, detail="PMA is disabled")
+        hub_root = request.app.state.config.root
+        dispatches = list_pma_dispatches(
+            hub_root, include_resolved=include_resolved, limit=limit
+        )
+        return {
+            "items": [
+                {
+                    "id": item.dispatch_id,
+                    "title": item.title,
+                    "body": item.body,
+                    "priority": item.priority,
+                    "links": item.links,
+                    "created_at": item.created_at,
+                    "resolved_at": item.resolved_at,
+                    "source_turn_id": item.source_turn_id,
+                }
+                for item in dispatches
+            ]
+        }
+
+    @router.get("/dispatches/{dispatch_id}")
+    def get_pma_dispatch(dispatch_id: str, request: Request) -> dict[str, Any]:
+        pma_config = _get_pma_config(request)
+        if not pma_config.get("enabled", True):
+            raise HTTPException(status_code=404, detail="PMA is disabled")
+        hub_root = request.app.state.config.root
+        path = find_pma_dispatch_path(hub_root, dispatch_id)
+        if not path:
+            raise HTTPException(status_code=404, detail="Dispatch not found")
+        # Use list helper to normalize output
+        items = list_pma_dispatches(hub_root, include_resolved=True)
+        match = next((item for item in items if item.dispatch_id == dispatch_id), None)
+        if not match:
+            raise HTTPException(status_code=404, detail="Dispatch not found")
+        return {
+            "dispatch": {
+                "id": match.dispatch_id,
+                "title": match.title,
+                "body": match.body,
+                "priority": match.priority,
+                "links": match.links,
+                "created_at": match.created_at,
+                "resolved_at": match.resolved_at,
+                "source_turn_id": match.source_turn_id,
+            }
+        }
+
+    @router.post("/dispatches/{dispatch_id}/resolve")
+    def resolve_pma_dispatch_endpoint(
+        dispatch_id: str, request: Request
+    ) -> dict[str, Any]:
+        pma_config = _get_pma_config(request)
+        if not pma_config.get("enabled", True):
+            raise HTTPException(status_code=404, detail="PMA is disabled")
+        hub_root = request.app.state.config.root
+        path = find_pma_dispatch_path(hub_root, dispatch_id)
+        if not path:
+            raise HTTPException(status_code=404, detail="Dispatch not found")
+        dispatch, errors = resolve_pma_dispatch(path)
+        if errors or dispatch is None:
+            raise HTTPException(
+                status_code=500,
+                detail="Failed to resolve dispatch: " + "; ".join(errors),
+            )
+        return {
+            "dispatch": {
+                "id": dispatch.dispatch_id,
+                "title": dispatch.title,
+                "body": dispatch.body,
+                "priority": dispatch.priority,
+                "links": dispatch.links,
+                "created_at": dispatch.created_at,
+                "resolved_at": dispatch.resolved_at,
+                "source_turn_id": dispatch.source_turn_id,
+            }
+        }
+
+    router._pma_start_lane_worker = _ensure_lane_worker_for_app
+    router._pma_stop_lane_worker = _stop_lane_worker_for_app
     return router