Summary

Adds an optional active-session marker file so suspend_recently_active() can precisely target sessions that were mid-turn at shutdown, instead of broadly sweeping anything updated in the last 120 seconds. Resume semantics are unchanged — only the targeting is sharper.

Why

suspend_recently_active() today uses a 120s time-based sweep (#7536). It catches the in-flight sessions correctly, but it also catches false-positives: sessions that received a message recently but had already finished processing it before the gateway stopped. Each false-positive forces an unnecessary auto-resume on the user's next message.

For clean stops / fast restarts (which account for the bulk of restarts in practice), the gateway already knows exactly which sessions had running agents at shutdown — self._running_agents. Persisting that set across the restart lets the next startup mark the precise set instead of guessing from timestamps.

For unclean exits (crash, OOM, power loss), the marker is absent and the existing time-based sweep runs unchanged.

Implementation

Three pieces:

1. SessionStore.save_active_sessions(active_session_keys: set) — new method that writes a .active_sessions_at_shutdown JSON marker atomically (tmpfile + fsync + os.replace) into sessions_dir. Atomic write so a crash mid-write can't leave a half-written marker that the next startup misinterprets.

2. Gateway shutdown call site in GatewayRunner.stop() — right after _notify_active_sessions_of_shutdown() and before _drain_active_agents(), persist set(self._running_agents.keys()). Wrapped in try/except-with-warning-log so a marker-write failure can't block a shutdown that was already in progress.

3. SessionStore.suspend_recently_active() — check for the marker first. If present: mark only the sessions in the marker as resume_pending, then unlink the marker. If absent: existing time-based sweep runs unchanged.

Why these specific design choices

• Marker file vs. database column: A file in sessions_dir requires no schema migration, no from_dict/to_dict changes, and is trivially inspectable / removable for debugging.
• Atomic write: A crash between open() and write() would otherwise leave a marker that says "no sessions were active" — worse than no marker, because the time-based fallback wouldn't run. tmpfile + os.replace eliminates that window.
• Consume-on-read: Deleting the marker after read means a second startup without an intervening shutdown reverts to the time-based path — protects against the marker becoming stale (e.g. if the second restart was caused by a crash that the first startup didn't see coming).
• Resume semantics unchanged: Existing users who rely on resume_pending=True → auto-resume get exactly that behaviour, just with fewer false-positives. No new fields on SessionEntry. No config option. Pure improvement on the existing contract.

Compatibility

• No schema migration needed.
• Any installation that doesn't write the marker (e.g. an unclean exit, or an external embedder that calls SessionStore outside the gateway lifecycle) gets the existing time-based sweep — fully backward-compatible.
• The marker file is in sessions_dir and prefixed with . so it doesn't show up in normal listings; it never collides with a session JSON file.

Test plan

• Clean shutdown writes marker; next startup marks only marker-listed sessions as resume_pending
• Marker is deleted after consumption
• No marker (simulated crash) → time-based sweep runs as today
• resume_pending and suspended entries skipped (existing behaviour preserved)
• Atomic write — interrupting between tmp-write and os.replace doesn't corrupt the marker

🤖 Generated with Claude Code