@maudecode/talaria-web 1.18.0 → 1.20.0

package/sidecar/talaria_sidecar/methods/state_db.py

@@ -20,7 +20,7 @@ from contextlib import closing, contextmanager
 from pathlib import Path
 
 from ..errors import InvalidParams, RpcError
-from ..home import profile_home_param
+from ..home import profile_home_param, scoped_home
 from ..rpc import CallContext
 
 log = logging.getLogger("talaria_sidecar.state_db")
@@ -52,30 +52,107 @@ def _session_id(params: dict) -> str:
     return sid
 
 
-def sync_session_start(home: Path, session_id: str, model=None) -> bool:
-    db = _session_db(home)
-    if not db:
-        return False
+# TAL-1191: write RPCs borrow the Agent's shared registry handle for the home's state.db (the one cached chat agents
+# hold) instead of a full writer open and close-time checkpoint per call. One extra reference per home stays pinned for
+# _IDLE_RELEASE_S after its last write; the registry hands out a fresh generation once the file is replaced.
+_IDLE_RELEASE_S = 60.0
+_pins_lock = threading.Lock()
+_pins: dict[str, tuple[object, threading.Timer]] = {}
+
+
+def release_session_db(db) -> None:
+    """Give back a registry reference (a cached agent's or a write pin); the final one closes the handle."""
+    if db is None:
+        return
     try:
-        db.ensure_session(session_id=session_id, source="webui", model=model)
-        return True
+        from hermes_state_registry import release_or_close
+
+        release_or_close(db)
     except Exception:  # noqa: BLE001
-        log.debug("Failed to sync session start", exc_info=True)
+        log.warning("releasing a state.db handle failed", exc_info=True)
+
+
+def _write(home: Path, what: str, op, *, level: int = logging.DEBUG) -> bool:
+    """Run ``op(db)`` on the shared handle; False without a state.db or when it fails. A failed write unpins the handle,
+    so the next one reopens it unless another holder keeps it."""
+    try:
+        from hermes_state_registry import acquire
+    except ImportError as exc:
+        raise RpcError("hermes_state unavailable", condition="state_db_unavailable") from exc
+    db_path = home / "state.db"
+    if not db_path.exists():
         return False
-    finally:
-        _close(db)
+    try:
+        db = acquire(db_path)
+    except Exception as exc:  # noqa: BLE001
+        log.debug("Failed to open state.db at %s: %s", db_path, exc)
+        return False
+    key = os.path.realpath(home)
+    # This call's reference keeps the same generation open; a retired one (replaced file) closes before its replacement
+    # is written, so its close-time checkpoint cannot carry the new rows into the old inode.
+    _pin(key, None)
+    ok = False
+    try:
+        op(db)
+        ok = True
+    except Exception:  # noqa: BLE001
+        log.log(level, "Failed to %s", what, exc_info=True)
+    if ok and db_path.exists():
+        _pin(key, db)
+    else:
+        release_session_db(db)
+    return ok
+
+
+def _pin(key: str, db) -> None:
+    """Make ``db`` (this call's reference) the home's pin with a fresh idle timer, giving back the previous pin."""
+    with _pins_lock:
+        previous = _pins.pop(key, None)
+        if previous is not None:
+            previous[1].cancel()
+        if db is not None:
+            timer = threading.Timer(_IDLE_RELEASE_S, lambda: _expire(key, timer))
+            timer.daemon = True
+            _pins[key] = (db, timer)
+            timer.start()
+    if previous is not None:  # outside the lock: a final release checkpoints
+        release_session_db(previous[0])
+
+
+def _expire(key: str, timer: threading.Timer) -> None:
+    with _pins_lock:
+        pinned = _pins.get(key)
+        if pinned is None or pinned[1] is not timer:
+            return
+        del _pins[key]
+    release_session_db(pinned[0])
+
+
+def release_home(home) -> None:
+    """Give back the pinned handle for ``home`` before its profile is deleted."""
+    _pin(os.path.realpath(home), None)
+
+
+def release_all() -> None:
+    """Shutdown: give back every pinned handle, so the final release still checkpoints once per process."""
+    with _pins_lock:
+        keys = list(_pins)
+    for key in keys:
+        _pin(key, None)
+
+
+def sync_session_start(home: Path, session_id: str, model=None) -> bool:
+    return _write(home, "sync session start", lambda db: db.ensure_session(session_id=session_id, source="webui", model=model))
 
 
 def sync_session_usage(home: Path, session_id: str, *, input_tokens=0, output_tokens=0, estimated_cost=None, model=None, title=None,
                        message_count=None, cache_read_tokens=0, cache_write_tokens=0, api_call_count=None) -> bool:
-    db = _session_db(home)
-    if not db:
-        return False
-    try:
-        db.ensure_session(session_id=session_id, source="webui", model=model)
+    def op(db) -> None:
+        # The token update's own row guard creates the session with this source, like ``ensure_session``.
         db.update_token_counts(
             session_id=session_id, input_tokens=input_tokens, output_tokens=output_tokens, cache_read_tokens=cache_read_tokens,
             cache_write_tokens=cache_write_tokens, api_call_count=api_call_count or 0, estimated_cost_usd=estimated_cost, model=model, absolute=True,
+            source="webui",
         )
         if title:
             try:
@@ -87,22 +164,16 @@ def sync_session_usage(home: Path, session_id: str, *, input_tokens=0, output_to
                 db._execute_write(lambda conn: conn.execute("UPDATE sessions SET message_count = ? WHERE id = ?", (message_count, session_id)))
             except Exception:  # noqa: BLE001
                 log.debug("Failed to sync message count", exc_info=True)
-        return True
-    except Exception:  # noqa: BLE001
-        log.debug("Failed to sync session usage", exc_info=True)
-        return False
-    finally:
-        _close(db)
+
+    return _write(home, "sync session usage", op)
 
 
 def sync_session_title(home: Path, session_id: str, title: str, *, manual: bool = False) -> bool:
     """A manual (user-requested) title lands with ``user`` provenance; an auto title is ``llm`` and never replaces a user name."""
     if not title:
         return False
-    db = _session_db(home)
-    if not db:
-        return False
-    try:
+
+    def op(db) -> None:
         db.ensure_session(session_id=session_id, source="webui")
         source = getattr(db, "TITLE_SOURCE_LLM", "llm")
 
@@ -118,28 +189,16 @@ def sync_session_title(home: Path, session_id: str, title: str, *, manual: bool
             alt = db.get_next_title_in_lineage(title)
             if alt and alt != title:
                 write(alt)
-        return True
-    except Exception:  # noqa: BLE001
-        log.debug("Failed to sync session title", exc_info=True)
-        return False
-    finally:
-        _close(db)
+
+    return _write(home, "sync session title", op)
 
 
 def append_message(home: Path, session_id: str, *, role: str, content: str, tool_name=None, timestamp=None) -> bool:
     """TAL-258 (predecessor ``_persist_handoff_summary_to_state_db``): one row through ``SessionDB.append_message``,
     which also bumps the session's ``message_count``. False without a state.db or when the write fails."""
-    db = _session_db(home)
-    if not db:
-        return False
-    try:
-        db.append_message(session_id, role, content=content, tool_name=tool_name or None, timestamp=timestamp)
-        return True
-    except Exception:  # noqa: BLE001
-        log.warning("Failed to append a %s row to state.db for %s", role, session_id, exc_info=True)
-        return False
-    finally:
-        _close(db)
+    return _write(home, f"append a {role} row to state.db for {session_id}",
+                  lambda db: db.append_message(session_id, role, content=content, tool_name=tool_name or None, timestamp=timestamp),
+                  level=logging.WARNING)
 
 
 def _close(db) -> None:
@@ -181,12 +240,15 @@ def _is_safe_session_id(sid) -> bool:
     return isinstance(sid, str) and bool(_SAFE_SESSION_ID.match(sid))
 
 
-def _clean_artifacts(sessions_dir: Path, removed_id: str) -> bool:
+def _clean_artifacts(sessions_dir: Path, removed_id: str, *, keep_legacy: bool) -> bool:
     if not _is_safe_session_id(removed_id):
         return False
     ok = True
-    for suffix in (".json", ".jsonl"):
-        artifact = sessions_dir / f"{removed_id}{suffix}"
+    # ``session_<id>.json`` is the legacy snapshot older Agents wrote; it can carry plaintext secrets. It is kept while a
+    # live session's id is ``session_<id>``, because then it is that session's own transcript.
+    names = [f"{removed_id}.json", f"{removed_id}.jsonl"] + ([] if keep_legacy else [f"session_{removed_id}.json"])
+    for name in names:
+        artifact = sessions_dir / name
         if artifact.exists():
             try:
                 artifact.unlink(missing_ok=True)
@@ -219,13 +281,13 @@ def _process_manifests(conn, sessions_dir: Path, *, alive_query) -> bool:
             mp.unlink(missing_ok=True)
             continue
         try:
-            alive = alive_query(conn, pending_ids)
+            alive = alive_query(conn, pending_ids + [f"session_{i}" for i in pending_ids])
         except Exception:  # noqa: BLE001 - fail closed, retry later
             complete = False
             continue
         still_pending = []
         for removed_id in pending_ids:
-            if removed_id in alive or not _clean_artifacts(sessions_dir, removed_id):
+            if removed_id in alive or not _clean_artifacts(sessions_dir, removed_id, keep_legacy=f"session_{removed_id}" in alive):
                 still_pending.append(removed_id)
         if still_pending:
             tmp = mp.with_suffix(".tmp")
@@ -288,19 +350,174 @@ def _timestamp_value(value):
     return numeric if math.isfinite(numeric) else None
 
 
-def _delete_locked(sid: str, home: Path) -> bool:
+def _is_continuation(parent: dict, child: dict) -> bool:
+    """The server's ``isContinuationSession``: ``child`` resumes ``parent`` after a compression or CLI close."""
+    lower = lambda v: str(v or "").strip().lower()  # noqa: E731
+    if lower(child.get("session_source")) == "fork":
+        return False
+    if child.get("source") == "tool" or any(child.get(k) is not None for k in ("branched_from", "delegate_from", "reset_from")):
+        return False
+    if lower(parent.get("source")) and lower(child.get("source")) and lower(parent.get("source")) != lower(child.get("source")):
+        return False
+    if parent.get("end_reason") not in ("compression", "cli_close"):
+        return False
+    if parent.get("ended_at") is None:
+        return True
+    try:
+        started, ended = float(child.get("started_at") or 0), float(parent["ended_at"])
+    except (TypeError, ValueError):
+        return False
+    return math.isfinite(started) and math.isfinite(ended) and started + 1.0 >= ended
+
+
+# The Agent's ``_CHAIN_CAP`` and the server's ``COMPRESSION_CHAIN_CAP``: the most hops a compression-chain walk takes.
+_COMPRESSION_CHAIN_CAP = 1000
+
+
+def _compression_lineage(records: list[dict], sid: str) -> list[str]:
+    """The server's ``stateDbCompressionLineage``: ``sid`` then each single continuation, up to ``_COMPRESSION_CHAIN_CAP``
+    hops, root first."""
+    by_id = {r["id"]: r for r in records}
+    children: dict[str, list[dict]] = {}
+    for r in records:
+        children.setdefault(r["parent_id"], []).append(r)
+    lineage, current = [sid], by_id.get(sid)
+    for _ in range(_COMPRESSION_CHAIN_CAP):
+        if current is None:
+            break
+        nxt = [r for r in children.get(current["id"], []) if _is_continuation(current, r)]
+        if len(nxt) != 1 or nxt[0]["id"] in lineage:
+            break
+        current = nxt[0]
+        lineage.append(current["id"])
+    return lineage
+
+
+class _ActiveWriteGuard(Exception):
+    """Another Agent process holds a live turn lease or compression lock on a row the delete would remove."""
+
+
+def _delete_locked(sid: str, home: Path, include_lineage: bool) -> dict:
     stale_complete = _process_stale_manifests(home)
     db_path = home / "state.db"
     if not db_path.exists():
-        return False
+        return {"ok": False}
+    agent_db = _session_db(home)
+    if agent_db is None:
+        return {"ok": False}
+    try:
+        guarded = _write_guard_check(agent_db)
+        if guarded is None:  # fail closed: without the Agent's guard, a live writer's rows cannot be told apart
+            log.warning("Agent has no session write-guard check; state.db rows are kept")
+            return {"ok": False}
+        try:
+            from hermes_state_mutation_retirement import delete_in_transaction
+        except ModuleNotFoundError as exc:
+            if exc.name != "hermes_state_mutation_retirement":
+                raise
+            result = _delete_rows(sid, include_lineage, home, db_path, guarded)
+        else:
+            result = _delete_runtime_rows(sid, home, agent_db, guarded, delete_in_transaction)
+        return {**result, "ok": result["ok"] and stale_complete}
+    finally:
+        _close(agent_db)
+
+
+def _write_guard_check(agent_db):
+    """The Agent's own user-delete guard, ``(conn, ids) -> bool``: true when a live turn lease or compression lock protects
+    any id; expired or dead-holder guards are reclaimed. ``_guarded_ids`` from v0.21.6, the per-row check before it."""
+    guarded_ids = getattr(agent_db, "_guarded_ids", None)
+    if guarded_ids is not None:
+        return lambda conn, ids: bool(guarded_ids(conn, ids))
+    rejects = getattr(agent_db, "_write_guards_reject", None)
+    if rejects is not None:
+        return lambda conn, ids: any(rejects(conn, i, allow_closed_compression_parent=True) for i in ids)
+    return None
+
+
+def _write_cleanup_manifest(home: Path, removed_ids: list[str]) -> None:
+    sessions_dir = home / "sessions"
+    sessions_dir.mkdir(parents=True, exist_ok=True)
+    base = f".cleanup_manifest_{uuid.uuid4().hex}"
+    manifest, tmp = sessions_dir / f"{base}.json", sessions_dir / f"{base}.tmp"
+    try:
+        tmp.write_text(json.dumps(sorted(removed_ids)), encoding="utf-8")
+        tmp.rename(manifest)
+    except OSError:
+        tmp.unlink(missing_ok=True)
+        raise
+
+
+def _delete_runtime_rows(requested: str, home: Path, agent_db, guarded, delete_in_transaction) -> dict:
+    """Extend the legacy delete with the Agent's canonical target/retirement transaction.
+
+    Compression and receipt-backed reset segments are one conversation, even when the caller names its tip.
+    The Agent owns delegate/fork boundaries, live-ledger refusals, receipt compaction and tombstones.
+    """
+    from hermes_state_mutation_guards import delete_targets
+    from hermes_state_runtime import RuntimeStoreError
+    from hermes_state_media import collect_retired_media
+
+    def write(conn):
+        # The Agent's owner lookup falls back to the physical id on an unreadable receipt; refuse before that loses its owner.
+        row = conn.execute("SELECT chat_id FROM sessions WHERE id=?", (requested,)).fetchone()
+        owner = row[0] if row else None
+        saved = conn.execute("SELECT value FROM state_meta WHERE key=?", ("gateway.local_policy.v1:" + owner,)).fetchone() if owner else None
+        if saved is not None:
+            from hermes_state_local_lineage import validate_local_lineage
+            raw = saved[0]
+            if len(raw) > 1_000_000:
+                raise ValueError("local receipt exceeds read budget")
+            receipt = json.loads(raw)
+            ids = receipt.get("lineage", [owner])
+            if (receipt.get("session_id") != owner or not isinstance(ids, list) or not ids
+                    or len(ids) > _COMPRESSION_CHAIN_CAP or not all(isinstance(sid, str) and sid for sid in ids)):
+                raise ValueError("invalid local receipt")
+            validate_local_lineage(conn, receipt)
+            members = conn.execute("SELECT id,chat_id,user_id,session_key,source,model_config FROM sessions WHERE id IN (SELECT value FROM json_each(?))",
+                                   (json.dumps(ids),)).fetchall()
+            if len(members) != len(ids) or any(tuple(member)[1:4] != (owner, receipt["principal_id"], receipt["route"]) for member in members):
+                raise ValueError("local receipt owner mismatch")
+            for member in members:
+                config = json.loads(member[5] or '{}')
+                if member[0] != owner and (member[4] == 'tool' or any(config.get(key) is not None for key in ('_branched_from', '_delegate_from'))):
+                    raise ValueError("explicit child is not a local continuation")
+        # Preserve the older user-delete guard over the complete canonical set, including closed ancestors.
+        if guarded(conn, delete_targets(conn, requested)):
+            raise _ActiveWriteGuard
+        try:
+            _, result = delete_in_transaction(agent_db, conn, requested, {})
+        except RuntimeStoreError as exc:
+            if exc.reason in ("session_busy", "unknown_execution"):
+                raise _ActiveWriteGuard from exc
+            raise
+        # Publish cleanup intent before the database commit; a failed manifest rolls back retirement too.
+        _write_cleanup_manifest(home, result["deleted_ids"])
+        return result["deleted_ids"]
+
+    deleted_ids = agent_db._execute_write(write)
+    # Agent v0.22.3+ tells the profile's plugins after the commit, like its own deletes; the emitter is fail-open.
+    import hermes_state_common
+    emit_session_deleted = getattr(hermes_state_common, "emit_session_deleted", None)
+    if emit_session_deleted is not None:
+        emit_session_deleted(agent_db, deleted_ids, reason="delete", primary=requested, sessions_dir=home / "sessions")
+    try:
+        collect_retired_media(agent_db)
+    except Exception:  # noqa: BLE001 - retirement committed; retain its targets for caller cleanup and manifest retry
+        log.warning("Failed to collect retired session media", exc_info=True)
+        return {"ok": False, "deleted_ids": deleted_ids}
+    return {"ok": _process_stale_manifests(home), "deleted_ids": deleted_ids}
+
+
+def _delete_rows(requested: str, include_lineage: bool, home: Path, db_path: Path, guarded) -> dict:
     with closing(sqlite3.connect(str(db_path))) as conn:
         conn.row_factory = sqlite3.Row
         conn.execute("PRAGMA foreign_keys = ON")
         conn.execute("BEGIN IMMEDIATE")
         columns = {row[1] for row in conn.execute("PRAGMA table_info(sessions)").fetchall()}
         if not {"id", "parent_session_id"}.issubset(columns):
-            return False
-        selected = ["id", "parent_session_id"] + [c if c in columns else f"NULL AS {c}" for c in ("model_config", "source", "end_reason", "started_at", "ended_at")]
+            return {"ok": False}
+        selected = ["id", "parent_session_id"] + [c if c in columns else f"NULL AS {c}" for c in ("model_config", "source", "session_source", "end_reason", "started_at", "ended_at", "chat_id")]
         rows = conn.execute(f"SELECT {', '.join(selected)} FROM sessions").fetchall()
         records = []
         for row in rows:
@@ -316,7 +533,8 @@ def _delete_locked(sid: str, home: Path) -> bool:
                     model_config, known = parsed, True
             records.append({
                 "id": row["id"], "parent_id": row["parent_session_id"], "delegate_from": model_config.get("_delegate_from"),
-                "branched_from": model_config.get("_branched_from"), "model_config_known": known, "source": row["source"],
+                "branched_from": model_config.get("_branched_from"), "model_config_known": known, "source": row["source"], "session_source": row["session_source"],
+                "reset_from": model_config.get("_reset_from"), "chat_id": row["chat_id"],
                 "end_reason": row["end_reason"], "started_at": row["started_at"], "ended_at": row["ended_at"],
             })
         by_id = {r["id"]: r for r in records}
@@ -339,82 +557,151 @@ def _delete_locked(sid: str, home: Path) -> bool:
                 return by_id.get(record["delegate_from"]) or {}
             return by_id.get(record["parent_id"]) or {}
 
-        preserved = {r["id"] for r in records if r["id"] != sid and must_preserve(r, lineage_parent(r))}
-        while True:
-            descendants = {r["id"] for r in records if r["id"] != sid and r["parent_id"] in preserved}
-            new_ids = descendants - preserved
-            if not new_ids:
-                break
-            preserved.update(new_ids)
-        found, frontier = {sid}, {sid}
-        while frontier:
-            next_frontier = set()
-            for record in records:
-                row_id = record["id"]
-                if row_id in found or row_id in preserved:
-                    continue
-                parent_id, delegate_from = record["parent_id"], record["delegate_from"]
-                if delegate_from not in frontier and parent_id not in frontier:
-                    continue
-                if must_preserve(record, lineage_parent(record)):
-                    continue
-                if delegate_from is not None:
-                    if delegate_from in frontier:
+        def delegates_of(sid: str) -> list[str]:
+            preserved = {r["id"] for r in records if r["id"] != sid and must_preserve(r, lineage_parent(r))}
+            while True:
+                descendants = {r["id"] for r in records if r["id"] != sid and r["parent_id"] in preserved}
+                new_ids = descendants - preserved
+                if not new_ids:
+                    break
+                preserved.update(new_ids)
+            found, frontier = {sid}, {sid}
+            while frontier:
+                next_frontier = set()
+                for record in records:
+                    row_id = record["id"]
+                    if row_id in found or row_id in preserved:
+                        continue
+                    parent_id, delegate_from = record["parent_id"], record["delegate_from"]
+                    if delegate_from not in frontier and parent_id not in frontier:
+                        continue
+                    if must_preserve(record, lineage_parent(record)):
+                        continue
+                    if delegate_from is not None:
+                        if delegate_from in frontier:
+                            next_frontier.add(row_id)
+                        continue
+                    if record["source"] != "subagent":
+                        continue
+                    if parent_id in frontier and record["model_config_known"]:
                         next_frontier.add(row_id)
-                    continue
-                if record["source"] != "subagent":
-                    continue
-                if parent_id in frontier and record["model_config_known"]:
-                    next_frontier.add(row_id)
-            found.update(next_frontier)
-            frontier = next_frontier
-        delegate_ids = sorted(found - {sid})
-        all_removed = [sid, *delegate_ids]
+                found.update(next_frontier)
+                frontier = next_frontier
+            return sorted(found - {sid})
+
+        # TAL-792: the compression continuations are resolved here, in the delete transaction, so one that a compression
+        # finished after the caller looked is guarded and removed too; one transaction removes them all, tip first.
+        sids = _compression_lineage(records, requested) if include_lineage else [requested]
+        plan = [(sid, delegates_of(sid)) for sid in reversed(sids)]
+        all_removed = list(dict.fromkeys(i for sid, delegate_ids in plan for i in (sid, *delegate_ids)))
+        if _has_retained_runtime_history(conn, records, all_removed):
+            return {"ok": False, "refused": "runtime_history_unsupported"}
+        # The Agent's own user-delete guard, checked over every row before any is removed. A live writer's turn lease or
+        # compression lock refuses the whole delete; expired or dead-holder guards are reclaimed.
+        if guarded(conn, all_removed):
+            raise _ActiveWriteGuard
         placeholders = ",".join("?" * len(all_removed))
-        for child_id in delegate_ids:
-            conn.execute("DELETE FROM messages WHERE session_id = ?", (child_id,))
-        for child_id in delegate_ids:
-            conn.execute("UPDATE sessions SET parent_session_id = NULL WHERE parent_session_id = ?", (child_id,))
-        for child_id in delegate_ids:
-            conn.execute("DELETE FROM sessions WHERE id = ?", (child_id,))
-        conn.execute("UPDATE sessions SET parent_session_id = NULL WHERE parent_session_id = ?", (sid,))
-        conn.execute("DELETE FROM messages WHERE session_id = ?", (sid,))
-        conn.execute("DELETE FROM sessions WHERE id = ?", (sid,))
+        for sid, delegate_ids in plan:
+            for child_id in delegate_ids:
+                conn.execute("DELETE FROM messages WHERE session_id = ?", (child_id,))
+            for child_id in delegate_ids:
+                conn.execute("UPDATE sessions SET parent_session_id = NULL WHERE parent_session_id = ?", (child_id,))
+            for child_id in delegate_ids:
+                conn.execute("DELETE FROM sessions WHERE id = ?", (child_id,))
+            conn.execute("UPDATE sessions SET parent_session_id = NULL WHERE parent_session_id = ?", (sid,))
+            conn.execute("DELETE FROM messages WHERE session_id = ?", (sid,))
+            conn.execute("DELETE FROM sessions WHERE id = ?", (sid,))
         tables = {row[0] for row in conn.execute("SELECT name FROM sqlite_master WHERE type='table'").fetchall()}
         for table in ("compression_locks", "session_model_usage", "telegram_dm_topic_bindings"):
             if table in tables:
                 conn.execute(f"DELETE FROM {table} WHERE session_id IN ({placeholders})", all_removed)
-        sessions_dir = home / "sessions"
-        sessions_dir.mkdir(parents=True, exist_ok=True)
-        base = f".cleanup_manifest_{uuid.uuid4().hex}"
-        manifest, tmp = sessions_dir / f"{base}.json", sessions_dir / f"{base}.tmp"
         try:
-            tmp.write_text(json.dumps(sorted(str(i) for i in all_removed)), encoding="utf-8")
-            tmp.rename(manifest)
+            _write_cleanup_manifest(home, all_removed)
         except OSError:
             log.warning("Failed to write cleanup manifest", exc_info=True)
-            tmp.unlink(missing_ok=True)
             conn.rollback()
-            return False
+            return {"ok": False}
         conn.commit()
-
-        def alive_after_commit(c, ids):
-            try:
-                return _alive_set(c, ids)
-            except Exception:  # noqa: BLE001 - fail closed: treat as alive
-                return set(ids)
-
-        cleanup_complete = _process_manifests(conn, sessions_dir, alive_query=alive_after_commit)
-        return stale_complete and cleanup_complete
+        return {"ok": _process_stale_manifests(home), "deleted_ids": all_removed}
+
+
+def _has_retained_runtime_history(conn, records: list[dict], removed_ids: list[str]) -> bool:
+    """Read-only downgrade fence, never a replacement for the Agent's retirement/receipt validator."""
+    targets = set(removed_ids)
+    by_id = {r["id"]: r for r in records}
+    # Inspect the logical family, including compressed delegates the legacy plan would detach.
+    # This only refuses deletion; the installed Agent remains the sole canonical retirement implementation.
+    while True:
+        connected = set()
+        for child in records:
+            parent = by_id.get(child["parent_id"])
+            if parent and (child['id'] in targets or parent['id'] in targets):
+                # Only markers actually copied from this parent are known to be inherited.
+                edge = {**child, **{k: None for k in ('branched_from', 'delegate_from', 'reset_from') if child[k] == parent[k]}}
+                if _is_continuation(parent, edge):
+                    connected.update((parent['id'], child['id']))
+            if child['branched_from'] is None and child['reset_from'] is None and (child['delegate_from'] in targets
+                    or (child['delegate_from'] is None and child['source'] == 'subagent' and child['parent_id'] in targets
+                        and child['model_config_known'])):
+                connected.add(child['id'])
+        if connected.issubset(targets):
+            break
+        targets.update(connected)
+    tables = {r[0] for r in conn.execute("SELECT name FROM sqlite_master WHERE type='table'")}
+    placeholders = ','.join('?' for _ in targets)
+    for table, column in (("session_admissions", "target_session_id"), ("worker_executions", "session_id")):
+        if table in tables and conn.execute(f"SELECT 1 FROM {table} WHERE {column} IN ({placeholders}) LIMIT 1", tuple(targets)).fetchone():
+            return True
+    if 'state_meta' not in tables:
+        return False
+    # The key and stored chat owner still identify a reset receipt when its JSON is unreadable.
+    owners = targets | {r["chat_id"] for r in records if r["id"] in targets and isinstance(r["chat_id"], str)}
+    for key, raw in conn.execute("SELECT key,value FROM state_meta WHERE key GLOB 'gateway.*'"):
+        if key.startswith('gateway.local_policy.v1:') and key.removeprefix('gateway.local_policy.v1:') in owners:
+            return True
+        if key.startswith('gateway.retired_session.v1.') and key.removeprefix('gateway.retired_session.v1.') in targets:
+            return True
+        try:
+            receipt = json.loads(raw)
+        except (TypeError, ValueError):
+            continue
+        if not isinstance(receipt, dict):
+            continue
+        lineage = receipt.get('lineage')
+        entry = receipt.get('entry')
+        ids = [receipt.get('session_id'), receipt.get('target_session_id'),
+               entry.get('session_id') if isinstance(entry, dict) else None,
+               *(lineage if isinstance(lineage, list) else [])]
+        if any(isinstance(sid, str) and sid in targets for sid in ids):
+            return True
+    return False
 
 
-def delete_cli_session(home: Path, sid: str) -> bool:
+def delete_cli_session(home: Path, sid: str, include_lineage: bool = False) -> dict:
     try:
         with _thread_lock(home), _process_lock(home):
-            return _delete_locked(sid, home)
+            return _delete_locked(sid, home, include_lineage)
+    except _ActiveWriteGuard:  # the uncommitted transaction rolls back on close: nothing is removed
+        return {"ok": False, "refused": "active_turn"}
     except Exception:  # noqa: BLE001
         log.warning("Failed to delete CLI session %s from state.db", sid, exc_info=True)
-        return False
+        return {"ok": False}
+
+
+def prune_advice(home: Path) -> dict | None:
+    """The Agent's low-disk session auto-prune question for ``home`` (v0.22.3 ``hermes_cli.prune_advisor``) in its own
+    words; None while the Agent would not ask (disk not low, ``sessions.auto_prune`` set, snoozed) or has no advisor."""
+    try:
+        from hermes_cli import prune_advisor
+    except ImportError:
+        return None
+    advice, stale = prune_advisor.cached_advice(home)
+    if advice is None and not stale:
+        return None
+    if advice is None or stale:
+        # Measures state.db (seconds on a large store), on this request's own worker thread.
+        advice = prune_advisor.advise(home)
+    return {"lines": prune_advisor.advice_lines(advice, command_prefix="/")} if advice else None
 
 
 def register(registry) -> None:
@@ -449,4 +736,10 @@ def register(registry) -> None:
         sid = _session_id(params)
         if not _is_safe_session_id(sid):
             raise InvalidParams("unsafe session_id")
-        return {"ok": delete_cli_session(profile_home_param(params).resolve(), sid)}
+        return delete_cli_session(profile_home_param(params).resolve(), sid, params.get("include_compression_lineage") is True)
+
+    @registry.method("state_db.prune_advice")
+    def prune_advice_(ctx: CallContext, params: dict) -> dict:
+        home = profile_home_param(params)
+        with scoped_home(home):
+            return {"advice": prune_advice(home)}