pantheon-opencode 1.5.0-beta.1 → 1.5.0-beta.10

package/src/mcp/mcp_persistence_server.py

@@ -16,7 +16,8 @@ import os
 import re
 import sqlite3
 import sys
-import uuid
+import threading
+import time
 from datetime import UTC, datetime, timedelta
 from pathlib import Path
 
@@ -219,10 +220,11 @@ async def kv_store(
     Returns:
         Status dict with namespace and key.
     """
+    validated_ttl = _validate_ttl(ttl)
     conn = _db(scope)
     expires_at: str | None = None
-    if ttl is not None:
-        expires_at = (datetime.now(UTC) + timedelta(seconds=ttl)).isoformat()
+    if validated_ttl is not None:
+        expires_at = (datetime.now(UTC) + timedelta(seconds=validated_ttl)).isoformat()
 
     conn.execute(
         "INSERT INTO kv_store (namespace, key, value, expires_at, "
@@ -565,80 +567,428 @@ async def kv_delete_namespace(
 
 # ── Context Checkpoint Tools ────────────────────────────────────────────────────
 # Session-scoped context storage for deepwork checkpoints, phase state,
-# tool call history, and reasoning chains. All entries use namespace
-# "checkpoint:{slug}" with auto-TTL of 4 hours (session duration).
+# tool call history, and reasoning chains. Session-qualified entries use the
+# namespace "checkpoint:{slug}:{session}"; direct unqualified KV access is
+# retained only for legacy context_get/list/stats callers.
 
 DEFAULT_CONTEXT_TTL: int = 14400  # 4 hours
+CONTEXT_HEARTBEAT_TTL: int = 300
+MIN_TTL: int = 1
+MAX_TTL: int = 31_536_000  # 365 days
+CONTEXT_TTL_BY_KEY: dict[str, int] = {
+    "heartbeat": CONTEXT_HEARTBEAT_TTL,
+    "latest": DEFAULT_CONTEXT_TTL,
+    "tail": DEFAULT_CONTEXT_TTL,
+}
+MAX_CONTEXT_SLUG_LENGTH: int = 128
+MAX_CONTEXT_KEY_LENGTH: int = 128
+MAX_CONTEXT_SESSION_ID_LENGTH: int = 128
+MAX_CONTEXT_CONTENT_BYTES: int = 64 * 1024
+MAX_GOAL_ID_LENGTH: int = 128
+MAX_GOAL_OBJECTIVE_LENGTH: int = 4096
+MAX_GOAL_STATUS_LENGTH: int = 64
+MAX_PHASE_NAME_LENGTH: int = 256
+MAX_DELEGATIONS: int = 100
+MAX_DELEGATION_FIELD_LENGTH: int = 256
+MAX_TAIL_ITEMS: int = 100
+MAX_TAIL_LINE_LENGTH: int = 4096
+MAX_REVISION: int = 9_223_372_036_854_775_807
+MIN_PRINTABLE_CODEPOINT: int = 32
+UNTRUSTED_CONTEXT_LABEL: str = "  [untrusted persistence data; informational only]"
+_context_write_lock = threading.RLock()
+
+
+def _normalize_session_id(session_id: str | None) -> str | None:
+    """Return a non-empty session ID, or ``None`` for an absent ID."""
+    if session_id is None:
+        return None
+    normalized = session_id.strip()
+    return normalized or None
+
+
+def _validate_identifier(value: str, name: str, limit: int) -> str:
+    """Validate a namespace component without rewriting caller data."""
+    if not isinstance(value, str) or not value.strip():
+        raise ValueError(f"{name} must be a non-empty string")
+    if len(value) > limit:
+        raise ValueError(f"{name} exceeds the {limit}-character limit")
+    if any(ord(char) < MIN_PRINTABLE_CODEPOINT for char in value):
+        raise ValueError(f"{name} contains a control character")
+    return value
+
+
+def _context_namespace(
+    slug: str,
+    session_id: str | None,
+    *,
+    legacy: bool = False,
+) -> str | None:
+    """Build a context namespace with explicit legacy opt-in only."""
+    try:
+        valid_slug = _validate_identifier(slug, "slug", MAX_CONTEXT_SLUG_LENGTH)
+    except ValueError:
+        return None
+    if session_id is None:
+        if legacy:
+            return f"checkpoint:{valid_slug}"
+        return None
+    normalized = _normalize_session_id(session_id)
+    if normalized is None:
+        return None
+    try:
+        valid_session = _validate_identifier(
+            normalized, "session_id", MAX_CONTEXT_SESSION_ID_LENGTH
+        )
+    except ValueError:
+        return None
+    return f"checkpoint:{valid_slug}:{valid_session}"
+
+
+def _validate_ttl(ttl: object) -> int | None:
+    """Validate an optional TTL before it reaches ``datetime.timedelta``."""
+    if ttl is None:
+        return None
+    if isinstance(ttl, bool) or not isinstance(ttl, int):
+        raise ValueError("ttl must be an integer or null")
+    if ttl < MIN_TTL or ttl > MAX_TTL:
+        raise ValueError(f"ttl must be between {MIN_TTL} and {MAX_TTL} seconds")
+    return ttl
+
+
+def _context_ttl(key: str, ttl: int | None) -> int:
+    """Return a validated TTL or the explicit policy for a checkpoint key."""
+    validated_ttl = _validate_ttl(ttl)
+    return (
+        validated_ttl
+        if validated_ttl is not None
+        else CONTEXT_TTL_BY_KEY.get(key, DEFAULT_CONTEXT_TTL)
+    )
+
+
+def _validate_revision(revision: int | None) -> int | None:
+    """Validate an optional caller revision used for stale-write rejection."""
+    if revision is None:
+        return None
+    if isinstance(revision, bool) or not isinstance(revision, int):
+        raise ValueError("revision must be an integer")
+    if revision < 1 or revision > MAX_REVISION:
+        raise ValueError(f"revision must be between 1 and {MAX_REVISION}")
+    return revision
+
+
+def _current_context_revision(
+    conn: sqlite3.Connection, namespace: str, key: str
+) -> int:
+    """Read the persisted revision for one context entry."""
+    row = conn.execute(
+        "SELECT updated_at FROM kv_store WHERE namespace = ? AND key = ?",
+        (namespace, key),
+    ).fetchone()
+    return _stored_revision(row[0]) if row else 0
+
+
+def _should_update_latest(key: str) -> bool:
+    """Keep operational metadata from clobbering the recovery checkpoint."""
+    return key not in {"heartbeat", "tail"}
+
+
+def _validate_bounded_text(value: object, field: str, limit: int) -> None:
+    """Validate a string field without changing its contents."""
+    if not isinstance(value, str) or len(value.encode()) > limit:
+        raise ValueError(f"{field} exceeds its size limit")
+
+
+def _validate_goal(goal: object) -> None:
+    """Validate the bounded goal section of a checkpoint."""
+    if not isinstance(goal, dict):
+        raise ValueError("goal must be an object")
+    for field, limit in (
+        ("id", MAX_GOAL_ID_LENGTH),
+        ("objective", MAX_GOAL_OBJECTIVE_LENGTH),
+        ("status", MAX_GOAL_STATUS_LENGTH),
+    ):
+        value = goal.get(field)
+        if value is not None:
+            _validate_bounded_text(value, f"goal.{field}", limit)
+
+
+def _validate_phase(phase: object) -> None:
+    """Validate the bounded phase section of a checkpoint."""
+    if not isinstance(phase, dict):
+        raise ValueError("phase must be an object")
+    for field in ("current", "total"):
+        value = phase.get(field)
+        if value is not None and (
+            isinstance(value, bool) or not isinstance(value, int) or value < 0
+        ):
+            raise ValueError(f"phase.{field} must be a non-negative integer")
+    name = phase.get("name")
+    if name is not None:
+        _validate_bounded_text(name, "phase.name", MAX_PHASE_NAME_LENGTH)
+
+
+def _validate_delegations(delegations: object) -> None:
+    """Validate bounded in-flight delegation records."""
+    if not isinstance(delegations, dict):
+        raise ValueError("delegations must be an object")
+    in_flight = delegations.get("in_flight")
+    if in_flight is None:
+        return
+    if not isinstance(in_flight, list) or len(in_flight) > MAX_DELEGATIONS:
+        raise ValueError("delegations.in_flight exceeds its size limit")
+    for job in in_flight:
+        if not isinstance(job, dict):
+            raise ValueError("delegations.in_flight entries must be objects")
+        for field in ("alias", "agent", "task_id"):
+            value = job.get(field)
+            if value is not None:
+                _validate_bounded_text(
+                    value, f"delegations.in_flight.{field}", MAX_DELEGATION_FIELD_LENGTH
+                )
+
+
+def _validate_tail(tail: object, payload_bytes: int | None = None) -> list[str]:
+    """Validate bounded serialized tail lines."""
+    if not isinstance(tail, list) or len(tail) > MAX_TAIL_ITEMS:
+        raise ValueError("tail exceeds its size limit")
+    for line in tail:
+        if not isinstance(line, str) or len(line.encode()) > MAX_TAIL_LINE_LENGTH:
+            raise ValueError("tail entries exceed their size limit")
+    if payload_bytes is not None and payload_bytes > MAX_CONTEXT_CONTENT_BYTES:
+        raise ValueError("tail payload exceeds its size limit")
+    if sum(len(line.encode()) for line in tail) > MAX_CONTEXT_CONTENT_BYTES:
+        raise ValueError("tail payload exceeds its size limit")
+    return tail
+
+
+def _validate_heartbeat(heartbeat: object) -> None:
+    """Validate bounded heartbeat metadata."""
+    if not isinstance(heartbeat, dict):
+        raise ValueError("heartbeat must be an object")
+    status = heartbeat.get("status")
+    if status is not None:
+        _validate_bounded_text(status, "heartbeat.status", MAX_GOAL_STATUS_LENGTH)
+    turn_count = heartbeat.get("turn_count")
+    if turn_count is not None and (
+        isinstance(turn_count, bool)
+        or not isinstance(turn_count, int)
+        or turn_count < 0
+    ):
+        raise ValueError("heartbeat.turn_count must be a non-negative integer")
+
+
+def _validate_version_metadata(version: object) -> None:
+    """Validate optional checkpoint ``version`` metadata leniently.
+
+    ``version`` is opaque application metadata (rehydrate does not consume it),
+    not a persistence requirement. It may be a positive integer, a JSON float
+    such as ``1.0``, or a version label like ``"1.5.0-beta.2"``. Absent/null
+    versions and any non-empty string remain valid, preserving existing integer
+    checkpoints while allowing forward-compatible labels. Only bools, empty
+    strings, non-finite/zero/negative numbers, and structured values are
+    rejected.
+    """
+    if version is None:
+        return
+    if isinstance(version, bool):
+        raise ValueError("version must be a positive integer or version label")
+    if isinstance(version, (int, float)):
+        if not 1 <= version < float("inf"):
+            raise ValueError("version must be a positive integer or version label")
+        return
+    if not isinstance(version, str) or not version.strip():
+        raise ValueError("version must be a positive integer or version label")
+
+
+def _validate_checkpoint_shape(checkpoint: dict) -> None:
+    """Validate bounded structured checkpoint fields without sanitizing them."""
+    _validate_version_metadata(checkpoint.get("version"))
+    validators = (
+        ("goal", _validate_goal),
+        ("phase", _validate_phase),
+        ("delegations", _validate_delegations),
+        ("tail", _validate_tail),
+        ("heartbeat", _validate_heartbeat),
+    )
+    for field, validator in validators:
+        value = checkpoint.get(field)
+        if value is not None:
+            validator(value)
+
+
+def _validate_context_content(content: str, key: str) -> None:
+    """Bound context content and validate structured JSON when supplied."""
+    if not isinstance(content, str):
+        raise ValueError("content must be a string")
+    if len(content.encode()) > MAX_CONTEXT_CONTENT_BYTES:
+        raise ValueError(f"content exceeds the {MAX_CONTEXT_CONTENT_BYTES}-byte limit")
+    try:
+        parsed = json.loads(content)
+    except (json.JSONDecodeError, TypeError, ValueError):
+        # Raw text remains a compatibility format, but rehydrate never treats
+        # it as a checkpoint. It is still bounded above.
+        return
+    if isinstance(parsed, list) and key == "tail":
+        if len(parsed) > MAX_TAIL_ITEMS or any(
+            not isinstance(line, str) or len(line.encode()) > MAX_TAIL_LINE_LENGTH
+            for line in parsed
+        ):
+            raise ValueError("tail exceeds its size limit")
+        return
+    if not isinstance(parsed, dict):
+        raise ValueError("structured context content must be a JSON object")
+    _validate_checkpoint_shape(parsed)
+
+
+def _safe_untrusted_text(value: object) -> str:
+    """Escape control/markup delimiters while preserving untrusted content."""
+    text = str(value)
+    return (
+        text.replace("<", r"\u003c")
+        .replace(">", r"\u003e")
+        .replace("\r", r"\r")
+        .replace("\n", r"\n")
+        .replace("\x00", r"\u0000")
+    )
+
+
+def _stored_revision(raw: object) -> int:
+    """Parse a context revision; legacy datetime values are revision zero."""
+    try:
+        revision = int(str(raw))
+    except (TypeError, ValueError):
+        return 0
+    return revision if 0 <= revision <= MAX_REVISION else 0
+
+
+def _next_context_revision(
+    conn: sqlite3.Connection, namespace: str, key: str, latest_key: str | None = None
+) -> int:
+    """Choose a persisted monotonic revision while the write lock is held."""
+    if latest_key is None:
+        rows = conn.execute(
+            "SELECT updated_at FROM kv_store WHERE namespace = ? AND key = ?",
+            (namespace, key),
+        ).fetchall()
+    else:
+        rows = conn.execute(
+            "SELECT updated_at FROM kv_store WHERE namespace = ? AND key IN (?, ?)",
+            (namespace, key, latest_key),
+        ).fetchall()
+    current = max((_stored_revision(row[0]) for row in rows), default=0)
+    return min(MAX_REVISION, max(time.time_ns(), current + 1))
+
+
+def _upsert_context_entry(
+    conn: sqlite3.Connection,
+    namespace: str,
+    key: str,
+    content: str,
+    expires_at: str,
+    revision: int,
+) -> None:
+    """Upsert one context row inside the caller's transaction."""
+    conn.execute(
+        "INSERT INTO kv_store (namespace, key, value, expires_at, "
+        "created_at, updated_at) VALUES (?, ?, ?, ?, datetime('now'), ?)"
+        "ON CONFLICT(namespace, key) DO UPDATE SET "
+        "  value = excluded.value, "
+        "  expires_at = excluded.expires_at, "
+        "  updated_at = excluded.updated_at",
+        (namespace, key, content, expires_at, str(revision)),
+    )
 
 
 @mcp.tool(
     name="context_save",
     description="Save a context checkpoint for a session/phase. "
-    "Stores structured JSON in persistence KV with auto-TTL of 4h.",
+    "Stores structured JSON in persistence KV with a key-specific TTL.",
 )
 async def context_save(
     slug: str,
     key: str,
     content: str,
-    session_id: str | None = None,
+    session_id: str,
     ttl: int | None = None,
     scope: str = "project",
+    revision: int | None = None,
 ) -> dict:
     """Save a context checkpoint with session-level isolation.
 
-    If session_id is provided, namespace becomes "checkpoint:{slug}:{session_id}"
-    preventing cross-session reads. If omitted, a random UUID is auto-generated
-    and returned so the caller can pass it to subsequent calls.
+    Namespace is always "checkpoint:{slug}:{session_id}", preventing
+    cross-session reads. The session_id must be supplied by the autonomy
+    caller; this function never generates one.
 
     Args:
         slug: Session identifier (e.g. "auth-refactor").
         key: Checkpoint key (e.g. "phase:3", "latest", "heartbeat").
         content: JSON-serializable string or any text content.
-        session_id: Unique session ID for namespace isolation (auto-generated if None).
-        ttl: TTL in seconds (default 4h / 14400). None = session duration.
+        session_id: Required unique session ID for namespace isolation.
+        ttl: TTL in seconds (defaults to the key-specific context policy).
         scope: 'project' (default) or 'global'.
+        revision: Optional monotonic revision. Older/equal revisions are no-ops.
 
     Returns:
         Status dict with namespace, key, and session_id for subsequent calls.
     """
-    actual_session = session_id or uuid.uuid4().hex[:12]
-    ns = f"checkpoint:{slug}:{actual_session}"
-    actual_ttl = ttl if ttl is not None else DEFAULT_CONTEXT_TTL
+    valid_slug = _validate_identifier(slug, "slug", MAX_CONTEXT_SLUG_LENGTH)
+    valid_key = _validate_identifier(key, "key", MAX_CONTEXT_KEY_LENGTH)
+    actual_session = _normalize_session_id(session_id)
+    if actual_session is None:
+        raise ValueError("session_id is required and must be non-empty")
+    valid_session = _validate_identifier(
+        actual_session, "session_id", MAX_CONTEXT_SESSION_ID_LENGTH
+    )
+    _validate_context_content(content, valid_key)
+    requested_revision = _validate_revision(revision)
+    ns = f"checkpoint:{valid_slug}:{valid_session}"
+    actual_ttl = _context_ttl(valid_key, ttl)
 
     conn = _db(scope)
     expires_at = (datetime.now(UTC) + timedelta(seconds=actual_ttl)).isoformat()
 
-    conn.execute(
-        "INSERT INTO kv_store (namespace, key, value, expires_at, "
-        "created_at, updated_at) VALUES (?, ?, ?, ?, datetime('now'), datetime('now'))"
-        "ON CONFLICT(namespace, key) DO UPDATE SET "
-        "  value = excluded.value, "
-        "  expires_at = excluded.expires_at, "
-        "  updated_at = datetime('now')",
-        (ns, key, content, expires_at),
-    )
-    conn.commit()
-
-    # Also always update "latest" pointer
-    if key != "latest":
-        # Use a larger TTL for "latest" to outlive individual phase entries
-        conn.execute(
-            "INSERT INTO kv_store (namespace, key, value, expires_at, "
-            "created_at, updated_at) VALUES (?, 'latest', ?, ?, datetime('now'), datetime('now'))"
-            "ON CONFLICT(namespace, key) DO UPDATE SET "
-            "  value = excluded.value, "
-            "  expires_at = excluded.expires_at, "
-            "  updated_at = datetime('now')",
-            (ns, content, expires_at),
-        )
-        conn.commit()
+    # BEGIN IMMEDIATE serializes writers in this process and across SQLite
+    # connections. The checkpoint and raw-content latest pointer commit as one
+    # unit; a crash or failed second write therefore cannot expose half a save.
+    with _context_write_lock:
+        try:
+            conn.execute("BEGIN IMMEDIATE")
+            latest_key = "latest" if _should_update_latest(valid_key) else None
+            actual_revision = requested_revision or _next_context_revision(
+                conn, ns, valid_key, latest_key
+            )
+            current_revision = _current_context_revision(conn, ns, valid_key)
+            if actual_revision <= current_revision:
+                conn.rollback()
+                return {
+                    "status": "stale",
+                    "namespace": ns,
+                    "key": valid_key,
+                    "session_id": valid_session,
+                    "ttl": actual_ttl,
+                    "revision": current_revision,
+                }
+            _upsert_context_entry(
+                conn, ns, valid_key, content, expires_at, actual_revision
+            )
+            if latest_key is not None and actual_revision > _current_context_revision(
+                conn, ns, latest_key
+            ):
+                _upsert_context_entry(
+                    conn, ns, latest_key, content, expires_at, actual_revision
+                )
+            conn.commit()
+        except Exception:
+            conn.rollback()
+            raise
 
     return {
         "status": "stored",
         "namespace": ns,
-        "key": key,
-        "session_id": actual_session,
+        "key": valid_key,
+        "session_id": valid_session,
         "ttl": actual_ttl,
+        "revision": actual_revision,
     }
 
 
@@ -651,6 +1001,7 @@ async def context_get(
     slug: str,
     key: str = "latest",
     session_id: str | None = None,
+    legacy: bool = False,
     scope: str = "project",
 ) -> str | None:
     """Get a context checkpoint with session isolation.
@@ -658,14 +1009,22 @@ async def context_get(
     Args:
         slug: Session identifier.
         key: Checkpoint key (default "latest").
-        session_id: Required for isolation. If None, searches without session scope.
+        session_id: Required for session-scoped reads.
+        legacy: Explicitly opt into the unqualified legacy namespace when no
+            session_id is available.
         scope: 'project' (default) or 'global'.
 
     Returns:
         Content string or None if not found/expired.
     """
     conn = _db(scope)
-    ns = f"checkpoint:{slug}:{session_id}" if session_id else f"checkpoint:{slug}"
+    try:
+        _validate_identifier(key, "key", MAX_CONTEXT_KEY_LENGTH)
+    except ValueError:
+        return None
+    ns = _context_namespace(slug, session_id, legacy=legacy)
+    if ns is None:
+        return None
     row = conn.execute(
         "SELECT value FROM kv_store "
         "WHERE namespace = ? AND key = ? "
@@ -684,20 +1043,25 @@ async def context_get(
 async def context_list(
     slug: str,
     session_id: str | None = None,
+    legacy: bool = False,
     scope: str = "project",
 ) -> list[dict]:
     """List all checkpoints for a session.
 
     Args:
         slug: Session identifier.
-        session_id: Optional. If provided, narrows to specific session.
+        session_id: Required for session-scoped reads.
+        legacy: Explicitly opt into the unqualified legacy namespace when no
+            session_id is available.
         scope: 'project' (default) or 'global'.
 
     Returns:
         List of dicts with key, created_at, expires_at.
     """
     conn = _db(scope)
-    ns = f"checkpoint:{slug}:{session_id}" if session_id else f"checkpoint:{slug}"
+    ns = _context_namespace(slug, session_id, legacy=legacy)
+    if ns is None:
+        return []
     rows = conn.execute(
         "SELECT key, created_at, expires_at FROM kv_store "
         "WHERE namespace = ? "
@@ -724,36 +1088,52 @@ async def context_list(
 async def context_stats(
     slug: str,
     session_id: str | None = None,
+    legacy: bool = False,
     scope: str = "project",
 ) -> dict:
     """Return storage statistics for a session's context.
 
     Args:
         slug: Session identifier.
-        session_id: Optional. If provided, narrows to specific session.
+        session_id: Required for session-scoped reads.
+        legacy: Explicitly opt into the unqualified legacy namespace when no
+            session_id is available.
         scope: 'project' (default) or 'global'.
 
     Returns:
         Dict with entry_count, total_bytes, ttl_remaining.
     """
     conn = _db(scope)
-    ns = f"checkpoint:{slug}:{session_id}" if session_id else f"checkpoint:{slug}"
+    ns = _context_namespace(slug, session_id, legacy=legacy)
+    if ns is None:
+        return {
+            "slug": slug,
+            "namespace": None,
+            "entry_count": 0,
+            "expired_entries": 0,
+            "total_bytes": 0,
+            "ttl_remaining_seconds": None,
+        }
 
     count = conn.execute(
-        "SELECT COUNT(*) FROM kv_store WHERE namespace = ? AND deleted_at IS NULL",
+        "SELECT COUNT(*) FROM kv_store "
+        "WHERE namespace = ? AND deleted_at IS NULL "
+        "AND (expires_at IS NULL OR datetime(expires_at) > datetime('now'))",
         (ns,),
     ).fetchone()[0]
 
     expired = conn.execute(
         "SELECT COUNT(*) FROM kv_store "
-        "WHERE namespace = ? AND datetime(expires_at) < datetime('now') "
+        "WHERE namespace = ? AND expires_at IS NOT NULL "
+        "AND datetime(expires_at) <= datetime('now') "
         "AND deleted_at IS NULL",
         (ns,),
     ).fetchone()[0]
 
     size = conn.execute(
         "SELECT COALESCE(SUM(LENGTH(value)), 0) FROM kv_store "
-        "WHERE namespace = ? AND deleted_at IS NULL",
+        "WHERE namespace = ? AND deleted_at IS NULL "
+        "AND (expires_at IS NULL OR datetime(expires_at) > datetime('now'))",
         (ns,),
     ).fetchone()[0]
 
@@ -784,7 +1164,8 @@ async def context_stats(
 
 # ── Post-Compaction Injector (WS2 PR #94) ─────────────────────────────────────
 # Deterministic rehydration after a native compaction event: a long session
-# reads ``latest`` + serialized ``tail`` from ``checkpoint:<slug>`` and
+# reads ``latest`` + serialized ``tail`` from
+# ``checkpoint:<slug>:<session_id>`` and
 # rebuilds its critical context (active goal, in-flight delegations,
 # current phase) WITHOUT any LLM call or generative embedding.
 #
@@ -797,9 +1178,9 @@ async def context_stats(
 #    "heartbeat": {...}}
 # ``tail`` may also live under a separate ``tail`` key (JSON array).
 #
-# Guarantees: kill-switch PANTHEON_COMPACTION=off, TTL-respecting reads,
-# heartbeat TTL refresh (extended, never shortened), idempotent (pure reads
-# + TTL touch — no checkpoint rows are added or duplicated).
+# Guarantees: required session_id, kill-switch PANTHEON_COMPACTION=off,
+# TTL-respecting reads, no sibling fallback, conditional heartbeat TTL refresh,
+# and idempotent recovery (no checkpoint rows are added or duplicated).
 
 COMPACTION_KILL_SWITCH_ENV: str = "PANTHEON_COMPACTION"
 SESSION_END_SUMMARY_ENV: str = "PANTHEON_SESSION_END_SUMMARY"
@@ -826,26 +1207,39 @@ def _read_checkpoint_value(
     return row[0] if row else None
 
 
-def _parse_checkpoint(content: str) -> dict:
-    """Parse checkpoint JSON; unparsable content degrades to {} (fail-open)."""
+def _parse_checkpoint(content: str) -> dict | None:
+    """Parse and validate one checkpoint; invalid JSON fails closed."""
+    if len(content.encode()) > MAX_CONTEXT_CONTENT_BYTES:
+        return None
     try:
         data = json.loads(content)
     except (json.JSONDecodeError, TypeError, ValueError):
-        return {}
-    return data if isinstance(data, dict) else {}
+        return None
+    if not isinstance(data, dict):
+        return None
+    try:
+        _validate_checkpoint_shape(data)
+    except ValueError:
+        return None
+    return data
 
 
 def _checkpoint_tail(checkpoint: dict, tail_raw: str | None) -> list[str]:
     """Tail lines from embedded ``tail`` with fallback to the ``tail`` key."""
     tail = checkpoint.get("tail")
     if isinstance(tail, list):
-        lines = [str(line) for line in tail]
+        try:
+            lines = _validate_tail(tail)
+        except ValueError:
+            return []
     elif isinstance(tail_raw, str):
+        if len(tail_raw.encode()) > MAX_CONTEXT_CONTENT_BYTES:
+            return []
         try:
             parsed = json.loads(tail_raw)
+            lines = _validate_tail(parsed, payload_bytes=len(tail_raw.encode()))
         except (json.JSONDecodeError, TypeError, ValueError):
-            parsed = None
-        lines = [str(line) for line in parsed] if isinstance(parsed, list) else []
+            return []
     else:
         lines = []
     return [line for line in lines if line.strip()][:REHYDRATE_TAIL_CAP]
@@ -861,7 +1255,11 @@ def _mission_block(checkpoint: dict) -> str | None:
     if status == "done" or not objective:
         return None
     gid = str(goal.get("id", "goal")).strip() or "goal"
-    return f"<mission_context>\n  [{gid}] {objective} — {status}"
+    return (
+        f"<mission_context>\n{UNTRUSTED_CONTEXT_LABEL}\n"
+        f"  [{_safe_untrusted_text(gid)}] {_safe_untrusted_text(objective)}"
+        f" — {_safe_untrusted_text(status)}"
+    )
 
 
 def _phase_block(checkpoint: dict) -> str | None:
@@ -873,8 +1271,10 @@ def _phase_block(checkpoint: dict) -> str | None:
     current = phase.get("current")
     span = f"{current}/{total}" if total is not None else str(current)
     name = str(phase.get("name", "")).strip()
-    line = f"  phase {span}" + (f" — {name}" if name else "")
-    return f"<phase_context>\n{line}"
+    line = f"  phase {_safe_untrusted_text(span)}"
+    if name:
+        line += f" — {_safe_untrusted_text(name)}"
+    return f"<phase_context>\n{UNTRUSTED_CONTEXT_LABEL}\n{line}"
 
 
 def _delegation_block(checkpoint: dict) -> str | None:
@@ -892,20 +1292,31 @@ def _delegation_block(checkpoint: dict) -> str | None:
         alias = str(job.get("alias") or job.get("task_id") or "?").strip()
         agent = str(job.get("agent", "?")).strip()
         task_id = str(job.get("task_id", "")).strip()
-        detail = f" — {task_id}" if task_id and task_id != alias else ""
-        lines.append(f"  [{alias}] {agent}{detail} [in-flight]")
+        detail = (
+            f" — {_safe_untrusted_text(task_id)}"
+            if task_id and task_id != alias
+            else ""
+        )
+        lines.append(
+            f"  [{_safe_untrusted_text(alias)}] {_safe_untrusted_text(agent)}"
+            f"{detail} [in-flight]"
+        )
     if not lines:
         return None
-    return "<delegation_context>\n" + "\n".join(lines)
+    return "<delegation_context>\n" + UNTRUSTED_CONTEXT_LABEL + "\n" + "\n".join(lines)
 
 
 def _tail_block(checkpoint: dict) -> str | None:
     """<tail_context> for the serialized tail (already capped on load)."""
     tail_lines = checkpoint.get("_tail_raw")
-    if not isinstance(tail_lines, list) or not tail_lines:
+    try:
+        validated_lines = _validate_tail(tail_lines)
+    except ValueError:
         return None
-    quoted = "\n".join(f"  - {line}" for line in tail_lines)
-    return f"<tail_context>\n{quoted}"
+    if not validated_lines:
+        return None
+    quoted = "\n".join(f"  - {_safe_untrusted_text(line)}" for line in validated_lines)
+    return f"<tail_context>\n{UNTRUSTED_CONTEXT_LABEL}\n{quoted}"
 
 
 def build_rehydration_blocks(checkpoint: dict) -> list[str] | None:
@@ -944,7 +1355,10 @@ def build_session_end_summary(checkpoint: dict) -> str | None:
     if isinstance(goal, dict):
         objective = str(goal.get("objective", "")).strip()
         if objective:
-            parts.append(f"Goal: {objective} ({goal.get('status', '?')})")
+            parts.append(
+                f"Goal: {_safe_untrusted_text(objective)} "
+                f"({_safe_untrusted_text(goal.get('status', '?'))})"
+            )
 
     phase = checkpoint.get("phase")
     if isinstance(phase, dict) and phase.get("current") is not None:
@@ -955,14 +1369,17 @@ def build_session_end_summary(checkpoint: dict) -> str | None:
             else phase.get("current")
         )
         name = str(phase.get("name", "")).strip()
-        parts.append(f"Phase: {span}" + (f" {name}" if name else ""))
+        parts.append(
+            f"Phase: {_safe_untrusted_text(span)}"
+            + (f" {_safe_untrusted_text(name)}" if name else "")
+        )
 
     delegations = checkpoint.get("delegations")
     if isinstance(delegations, dict):
         in_flight = delegations.get("in_flight")
         if isinstance(in_flight, list):
             aliases = [
-                str(job.get("alias") or job.get("task_id") or "?")
+                _safe_untrusted_text(str(job.get("alias") or job.get("task_id") or "?"))
                 for job in in_flight
                 if isinstance(job, dict)
             ]
@@ -971,7 +1388,7 @@ def build_session_end_summary(checkpoint: dict) -> str | None:
 
     tail_raw = checkpoint.get("_tail_raw")
     if isinstance(tail_raw, list) and tail_raw:
-        kept = [str(line) for line in tail_raw[:SUMMARY_TAIL_CAP]]
+        kept = [_safe_untrusted_text(str(line)) for line in tail_raw[:SUMMARY_TAIL_CAP]]
         parts.append("Tail: " + " | ".join(kept))
 
     if not parts:
@@ -984,43 +1401,16 @@ def build_session_end_summary(checkpoint: dict) -> str | None:
 def _load_checkpoint_for_rehydrate(
     conn: sqlite3.Connection, namespace: str
 ) -> dict | None:
-    """Load ``latest`` (+ ``tail`` fallback) or None when expired/absent.
-
-    Resilient to pointer clobbering: ``context_save`` refreshes ``latest``
-    on every write, so a later heartbeat can overwrite the checkpoint
-    pointer. When ``latest`` is not a checkpoint, scan sibling keys
-    newest-first and use the first value that rebuilds critical blocks.
-    Deterministic (created_at DESC, bounded scan).
-    """
+    """Load exactly ``latest``; expired, malformed, or empty data fails closed."""
     tail_raw = _read_checkpoint_value(conn, namespace, "tail")
-
-    def _with_tail(raw: str | None) -> dict | None:
-        if raw is None:
-            return None
-        checkpoint = _parse_checkpoint(raw)
-        if not checkpoint:
-            return None
-        checkpoint["_tail_raw"] = _checkpoint_tail(checkpoint, tail_raw)
-        if build_rehydration_blocks(checkpoint) is None:
-            return None
-        return checkpoint
-
-    found = _with_tail(_read_checkpoint_value(conn, namespace, "latest"))
-    if found is not None:
-        return found
-    rows = conn.execute(
-        "SELECT value FROM kv_store "
-        "WHERE namespace = ? AND key != 'latest' "
-        "AND (expires_at IS NULL OR datetime(expires_at) > datetime('now')) "
-        "AND deleted_at IS NULL "
-        "ORDER BY created_at DESC, key DESC LIMIT 20",
-        (namespace,),
-    ).fetchall()
-    for row in rows:
-        found = _with_tail(row[0] if row else None)
-        if found is not None:
-            return found
-    return None
+    raw = _read_checkpoint_value(conn, namespace, "latest")
+    if raw is None:
+        return None
+    checkpoint = _parse_checkpoint(raw)
+    if checkpoint is None:
+        return None
+    checkpoint["_tail_raw"] = _checkpoint_tail(checkpoint, tail_raw)
+    return checkpoint if build_rehydration_blocks(checkpoint) is not None else None
 
 
 def _refresh_heartbeat_ttl(conn: sqlite3.Connection, namespace: str) -> None:
@@ -1041,41 +1431,53 @@ def _refresh_heartbeat_ttl(conn: sqlite3.Connection, namespace: str) -> None:
     now = datetime.now(UTC)
     if current_exp.tzinfo is None:
         current_exp = current_exp.replace(tzinfo=UTC)
-    fresh_exp = now + timedelta(seconds=DEFAULT_CONTEXT_TTL)
+    fresh_exp = now + timedelta(seconds=CONTEXT_HEARTBEAT_TTL)
     if fresh_exp <= current_exp:
         return
-    conn.execute(
-        "UPDATE kv_store SET expires_at = ?, updated_at = datetime('now') "
-        "WHERE namespace = ? AND key = 'heartbeat'",
-        (fresh_exp.isoformat(), namespace),
+    revision = _next_context_revision(conn, namespace, "heartbeat")
+    cursor = conn.execute(
+        "UPDATE kv_store SET expires_at = ?, updated_at = ? "
+        "WHERE namespace = ? AND key = 'heartbeat' AND expires_at = ? "
+        "AND (expires_at IS NULL OR datetime(expires_at) > datetime('now')) "
+        "AND deleted_at IS NULL",
+        (fresh_exp.isoformat(), str(revision), namespace, row[0]),
     )
-    conn.commit()
+    if cursor.rowcount:
+        conn.commit()
 
 
 @mcp.tool(
     name="context_rehydrate",
     description="Rehydrate critical context after native compaction. "
-    "Reads 'latest' + serialized 'tail' from checkpoint:<slug> and rebuilds "
+    "Reads 'latest' + serialized 'tail' from a session-qualified checkpoint "
+    "namespace and rebuilds "
     "goal/phase/delegation blocks deterministically (no LLM). Refreshes the "
-    "heartbeat TTL. Idempotent. Honors PANTHEON_COMPACTION=off.",
+    "heartbeat TTL. Requires session_id and honors PANTHEON_COMPACTION=off.",
 )
 async def context_rehydrate(
     slug: str,
-    session_id: str | None = None,
+    session_id: str,
     scope: str = "project",
 ) -> list[str] | None:
-    """Post-compaction injector: deterministic rehydration, fail-open."""
+    """Rehydrate one known session; missing IDs fail closed."""
     if _compaction_disabled():
         return None
+    normalized_session = _normalize_session_id(session_id)
+    if normalized_session is None:
+        raise ValueError("session_id is required and must be non-empty")
+    valid_slug = _validate_identifier(slug, "slug", MAX_CONTEXT_SLUG_LENGTH)
+    valid_session = _validate_identifier(
+        normalized_session, "session_id", MAX_CONTEXT_SESSION_ID_LENGTH
+    )
     conn = _db(scope)
-    ns = f"checkpoint:{slug}:{session_id}" if session_id else f"checkpoint:{slug}"
-    checkpoint = _load_checkpoint_for_rehydrate(conn, ns)
+    namespace = f"checkpoint:{valid_slug}:{valid_session}"
+    checkpoint = _load_checkpoint_for_rehydrate(conn, namespace)
     if checkpoint is None:
         return None
     blocks = build_rehydration_blocks(checkpoint)
     if blocks is None:
         return None
-    _refresh_heartbeat_ttl(conn, ns)
+    _refresh_heartbeat_ttl(conn, namespace)
     return blocks
 
 
@@ -1084,19 +1486,26 @@ async def context_rehydrate(
     description="Tier 2 session-end summary without Themis approval. "
     "Compresses the checkpoint (goal, phase, in-flight, tail) into a "
     "memory-bank-ready summary deterministically (no LLM). "
-    "Opt-out via PANTHEON_SESSION_END_SUMMARY=off.",
+    "Requires session_id. Opt-out via PANTHEON_SESSION_END_SUMMARY=off.",
 )
 async def context_session_summary(
     slug: str,
-    session_id: str | None = None,
+    session_id: str,
     scope: str = "project",
 ) -> str | None:
-    """Session-end Tier 2 trigger: automatic, opt-out instead of opt-in."""
+    """Summarize one known session; missing IDs fail closed."""
     if os.environ.get(SESSION_END_SUMMARY_ENV, "").lower() == "off":
         return None
+    normalized_session = _normalize_session_id(session_id)
+    if normalized_session is None:
+        raise ValueError("session_id is required and must be non-empty")
+    valid_slug = _validate_identifier(slug, "slug", MAX_CONTEXT_SLUG_LENGTH)
+    valid_session = _validate_identifier(
+        normalized_session, "session_id", MAX_CONTEXT_SESSION_ID_LENGTH
+    )
     conn = _db(scope)
-    ns = f"checkpoint:{slug}:{session_id}" if session_id else f"checkpoint:{slug}"
-    checkpoint = _load_checkpoint_for_rehydrate(conn, ns)
+    namespace = f"checkpoint:{valid_slug}:{valid_session}"
+    checkpoint = _load_checkpoint_for_rehydrate(conn, namespace)
     if checkpoint is None:
         return None
     return build_session_end_summary(checkpoint)