Session-Boundary Handoff Protocol

A memory-only instruction ("notify Anita before/after /reset") failed because memory is read, not executed. The new session reads the instruction but has no trigger to act on it. The old session can't intercept /reset — it kills the process instantly, no hook to fire a notification from.

The pattern: flag-file handoff

Session A                  Filesystem                  Session B
──────────                 ──────────                  ──────────
  │                          │                           │
  │── writes `.just_reset`   │                           │
  │── runs notify script ───►│                           │
  │── tells user "type /reset"                           │
  │                          │                           │
  │                     [user types /reset]              │
  │                          │                           │
  │                    [agent restarts]                  │
  │                          │                           │
  │                          │── session starts ────────►│
  │                          │                           │── finds .just_reset
  │                          │                           │── runs back-online script
  │                          │                           │── deletes .just_reset
  │                          │                           │── continues normally

When to use this

Any time an action needs to survive these boundaries:

Scenario	Flag file	Pre-boundary action	Post-boundary action
`/reset` notification	`.just_reset`	Notify Anita "resetting in 2min"	Notify both "back online"
Pre-planned maintenance	`.maintenance_mode`	Set config flag, notify users	Re-enable services
Migration check-in	`.migration_phase`	Write current phase + next step	Resume where left off

Design rules

Flag file is a timestamp, not a boolean. Write $(date +%s) so the new session can decide staleness (e.g. a .just_reset older than 10 minutes means the user left and came back — skip notification).
Never persist across reboots — put flags under /run/ or use a tmpfs path when the intent is single-session. Use disk-backed paths (/root/.hermes/) only when the flag must survive a process kill without a reboot.
Clean up always — the consumer script must delete the flag file. If the consumer crashes before cleanup, the flag file should be stale-checked so the next session doesn't re-fire old notifications.
Pre-boundary script is manual — the running session can't intercept /reset, so the pre-action is always "I run the script, then tell the user to type the command." The pre-action script writes the flag, sends notifications, returns success.
Post-boundary script is automatic — the new session MUST check for the flag file on startup as part of its initialization. Add the check to memory so every new session reads it: "On session start, IF /root/.hermes/.just_reset exists → run the back-online script → delete flag."

Existing implementation

Pre-reset: /root/.hermes/scripts/send-reset-notifications.sh — writes .just_reset, notifies Anita
Post-reset: /root/.hermes/scripts/send-back-online.sh — checks .just_reset, notifies both, deletes flag
Memory instruction: "On session start, IF /root/.hermes/.just_reset exists → run send-back-online.sh"

Pitfalls

Timing race: If the user types /reset before the pre-script finishes, the flag file may not exist yet. The pre-script must write the flag FIRST, then send notifications, then tell the user to proceed.
Stale flags: If the user types /reset and walks away, a new session starts days later and fires the back-online notification as if it just happened. Add staleness: if [ $(($(date +%s) - FLAG_TIME)) -gt 600 ]; then rm -f "$FLAG"; exit 0; fi (skip if flag is older than 10 minutes).
Multiple resets in quick succession: The flag file is overwritten every time. The back-online notification fires once per session start. This is correct behavior — each /reset is an independent event.
Logging: Both scripts should log to a file so post-mortem trace is possible. Use /root/.hermes/logs/reset-handoff.log with ISO timestamps.

4.4 KiB Raw Blame History