kanban_resume_guard.py 3.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869
  1. """Centralized resume-time guard for Kanban-owned sessions (#68779) — the ONE place that
  2. decides whether a Kanban worker transcript may resume as an ordinary session.
  3. A Kanban dispatcher worker transcript must never continue as a write-capable ordinary
  4. CLI / Desktop / TUI session: the resumed process carries none of the dispatcher-granted
  5. ownership env (``HERMES_KANBAN_TASK`` / ``HERMES_KANBAN_RUN_ID`` / ``HERMES_KANBAN_BOARD`` /
  6. ``HERMES_KANBAN_CLAIM_LOCK``), so the board cannot observe or supervise it — and unblocking
  7. the card can then dispatch a second writer into the same workspace. Every surface that makes
  8. a resumed session WRITE-CAPABLE asks this guard before loading history:
  9. - interactive CLI ``--resume`` / ``-c`` (``HermesCLI._preload_resumed_session``),
  10. - mid-chat ``/resume`` / ``/sessions <id>`` (``_handle_resume_command``),
  11. - quiet one-shot resume (``hermes_cli/oneshot.py``),
  12. - gateway ``session.resume`` — Desktop session history and the TUI picker
  13. (``tui_gateway/methods_session.py``).
  14. Detection is persisted provenance (``SessionDB.is_kanban_owned_session``: the session row's
  15. ``kanban`` source, checked across the compression lineage a resume would materialize) plus
  16. dispatch-time env for the exemption: a process that itself holds ``HERMES_KANBAN_TASK`` is a
  17. dispatcher-owned run — the one legitimate supervised continuation — and may proceed.
  18. """
  19. import logging
  20. import os
  21. logger = logging.getLogger(__name__)
  22. def _dispatcher_owned_run() -> bool:
  23. """This process holds a dispatcher-granted Kanban task (``HERMES_KANBAN_TASK``, exactly
  24. what ``_default_spawn`` injects into worker children). That is the grant boundary: only a
  25. run the dispatcher owns — task, run id, claim, heartbeat — may continue a worker
  26. transcript, so it is exempt from the guard."""
  27. try:
  28. from gateway.session_context import get_session_env
  29. except ImportError: # no gateway context (plain CLI child) — read the process env
  30. get_session_env = os.environ.get
  31. return bool(str(get_session_env("HERMES_KANBAN_TASK", "") or "").strip())
  32. def kanban_resume_refusal(db, session_id: str):
  33. """Human-readable refusal reason when ``session_id`` is a Kanban-owned session that must
  34. NOT resume as an ordinary write-capable session, or ``None`` when the resume may proceed.
  35. Fails open ONLY for a store that cannot classify at all (a probe error must never block
  36. an ordinary session); a POSITIVE kanban-provenance match always refuses. Read failures
  37. are logged, not surfaced to the user as success.
  38. """
  39. if not session_id:
  40. return None
  41. if _dispatcher_owned_run():
  42. return None
  43. probe = getattr(db, "is_kanban_owned_session", None)
  44. if probe is None: # lightweight adaptor DB without the method — cannot classify
  45. return None
  46. try:
  47. owned = probe(session_id)
  48. except Exception:
  49. # Deliberate fail-open boundary: an ordinary session must never be blocked by a
  50. # broken probe, so classify as unknown and log the full traceback for diagnosis.
  51. logger.warning("kanban resume probe failed for %s (proceeding unclassified)",
  52. session_id, exc_info=True)
  53. return None
  54. # Strict True: SessionDB answers a real bool; anything else (a test double, an adaptor
  55. # quirk) is treated as unclassified, keeping the guard open for every non-worker store.
  56. if owned is not True:
  57. return None
  58. from agent.i18n import t
  59. return t("cli.resume.kanban_owned", session_id=session_id)