docs(gateway): precise watchdog scope, explicit import-resets-activity contract (review S4)

- Config docs now describe session_stall_timeout precisely: a RECOVERY
  notifier for an in-process AIAgent with an adapter-queued follow-up —
  not a general gateway/session stall detector — with a per-AIAgent scan
  cadence (not globally coordinated per durable session).
- import_sessions documents the deliberate export-includes /
  import-resets asymmetry for the activity fields (no resurrected
  'working' labels on machines where no agent runs), with a regression
  pinning both halves.
- Strip trailing whitespace in contributors/emails/fangliquan@qq.com
  (git diff --check housekeeping).

PR #76354 review, scope/contract items + housekeeping.
This commit is contained in:
Teknium
2026-08-01 15:21:04 -07:00
parent 89c4e26e23
commit 038c1ad872
4 changed files with 52 additions and 6 deletions
+9
View File
@@ -332,6 +332,15 @@ class SessionPortabilityMixin:
fail foreign-key validation. Gateway routing, handoff, rewind, and other
live runtime state are intentionally reset: this restores conversation
history, not ownership of a live channel or process.
Activity contract (#76354 review S4): export INCLUDES the live
activity fields (``last_activity_at`` / ``last_activity_description``
/ ``last_activity_provenance``) because they are part of the durable
row, but import deliberately RESETS them to NULL. Resurrecting a
stale "working ..." label on a machine where no agent is running
would fabricate activity the watchdog and session listings act on.
This asymmetry is intentional and covered by regression
(tests/gateway/test_watchdog_review_76354.py::test_s4_export_includes_activity_import_resets_it).
"""
if not isinstance(sessions, list):
raise ValueError("sessions must be a list")