# System Enhancement: Activity/Handoff Lifecycle Management

**Status:** Proposed  
**Owner:** Wadsworth 📋  
**Priority:** High  
**Date:** 2026-04-28

## Problem

Subagent sessions go stale or cycle without completing handoffs. We have:
- Sessions timing out (Daedalus)
- Sessions running idle (Socrates — "standing by unless @mentioned")
- Handoff docs sitting unread in `shared/`
- No systematic tracking of dispatched work

This creates silent failures where Matt thinks work is in progress but nothing is happening.

## Proposed Solution

### Phase 1: Handoff Tracking System

Create `memory/dispatches/` directory with structured dispatch records:

```
memory/dispatches/
  2026-04-28-imap-proxy-socrates.md    # Active dispatch
  2026-04-28-dashboard-css-daedalus.md # Stale dispatch
  DISPATCH-INDEX.md                    # Master list
```

Each dispatch record:
```yaml
---
dispatch_id: "disp-20260428-001"
agent: "socrates"
task: "IMAP Proxy Integration"
handoff_doc: "shared/project-docs/handoffs/imap-proxy-phase6.2.md"
dispatched_at: "2026-04-28T20:58:00Z"
status: "pending"  # pending | acknowledged | in_progress | blocked | complete
last_check: "2026-04-28T21:56:00Z"
blocker: null
next_check: "2026-04-28T22:30:00Z"
---
```

### Phase 2: Automated Health Checks

Cron job every 30 minutes:
1. Read `DISPATCH-INDEX.md`
2. For each active dispatch:
   - Check if agent session is alive
   - Check if files were modified after handoff
   - Check if task keywords appear in agent memory
3. Update status: `active` | `stale` | `blocked` | `dead`
4. Alert Matt if:
   - Dispatch stale > 2 hours
   - Session dead with incomplete work
   - Agent acknowledges but doesn't start within 1 hour

### Phase 3: Session Lifecycle Rules

**For Wadsworth (me):**
- Before dispatching: check if agent already has active session
- Before accepting "standing by" — require explicit acknowledgment with ETA
- After dispatch: set check-in reminder at T+30min, T+2hr, T+24hr
- On stale detection: escalate to Matt with options (reassign, reprioritize, abort)

**For Subagents:**
- On receiving handoff: MUST acknowledge within 5 minutes with ETA or blocker
- MUST update dispatch record on status change
- Session timeout = automatic "abandoned" status

### Phase 4: Integration with Existing Memory

- Hook into `memory/HEARTBEAT.md` — add dispatch checks to heartbeat
- Extend `memory/YYYY-MM-DD.md` with dispatch log section
- Link to `shared/project-docs/handoffs/` for durable artifacts

## Implementation Plan

1. **Now:** Create `memory/dispatches/` + `DISPATCH-INDEX.md`
2. **Today:** Add cron job for dispatch health checks
3. **This week:** Update AGENTS.md with session lifecycle rules
4. **Ongoing:** Wadsworth checks dispatches at every heartbeat

## Files to Create/Modify

- NEW: `memory/dispatches/DISPATCH-INDEX.md`
- NEW: `memory/dispatches/2026-04-28-imap-proxy-socrates.md`
- NEW: `memory/dispatches/2026-04-28-dashboard-css-daedalus.md`
- MOD: `AGENTS.md` — add "Inter-Agent Dispatch Protocol" section
- MOD: `HEARTBEAT.md` — add dispatch health check tasks
- MOD: `memory/2026-04-28.md` — document dispatch system

## Acceptance Criteria

- [ ] Matt can ask "status of dispatches" and get real answer
- [ ] Stale dispatches auto-detected within 2 hours
- [ ] No handoff doc sits unread without escalation
- [ ] Agent session death = immediate alert, not silent failure

## Notes

This is a meta-system improvement. It's about making the multi-agent setup actually work, not just theoretically work. The current pattern of "dispatch and hope" is brittle.

**Trigger:** Realized Socrates was idle for 1+ hour with unread handoff while Matt waited.
**Priority:** High — affects every future dispatch.