# 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

1. **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).
2. **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.
3. **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.
4. **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.
5. **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.