etanhey/session-handoff

Session Handoff — Structured Agent Continuation

"So I did not mean for you to do this way. I meant for you to answer the grilling from what you already know, because you know enough." — User, April 4 2026 (L10322), after handoff failed because outgoing agent waited for user to answer grill questions

"orcClaude -s -c Will continue you dummy lol" — User, April 4 2026 (L9910), after outgoing agent didn't know how to continue

The April 4 session handoff took 10+ turns and still failed. The outgoing agent sent a wall of raw text via cmux, didn't set up a monitoring loop, and waited for the USER to answer the new agent's orientation questions instead of answering them itself.

---

THE HANDOFF PROTOCOL (5 steps, in order)

Step 1: Write the Handoff File

NEVER send handoff as raw cmux text. Write a structured file that the new agent reads.

Location: docs.local/handoffs/handoff-{date}-{session-summary}.md

Template:

# Session Handoff — {date}

## Outgoing Agent
- Agent: {name} (e.g., orcClaude)
- Context: {token_count}/{model_max} ({utilization}%)
- Session ID: {id}
- Duration: {time}

## Session Intent
{Exact user quotes about what they want to achieve — verbatim, not paraphrased}

## Decisions Made
| Decision | Why | Who Decided |
|----------|-----|-------------|
| {decision} | {rationale} | {user/agent} |

## User Corrections (from /frustration-capture)
| Correction | Category | Importance | Quote |
|-----------|----------|------------|-------|
| {what was wrong → what's right} | {category} | {7-10} | "{exact words}" |

## Agent State
| Agent | Agent ID | Surface | Task | Status | Context % | Launcher |
|-------|----------|---------|------|--------|-----------|----------|
| {name} | {agent_id} | surface:{N} | {task} | {idle/ready/learning/working/blocked/done/signed-off} | {%} | {launcher -flags} |

## Open PRs
| Repo | PR # | Status | What |
|------|------|--------|------|
| {repo} | #{N} | {open/reviewing/merged} | {1-line} |

## Active Collabs
| File | Status | Current Ask |
|------|--------|-------------|
| {path} | {active/blocked} | {what's needed} |

## Current State
{What's working, what's broken, what's in progress — be specific}

## Next Steps (ordered by priority)
1. {highest priority task}
2. {second priority}
3. ...

## What the New Agent Should Do First
1. brain_search("handoff session {date}") to verify this was stored
2. Read this file
3. Check active agents (`list_agents` / `my_agents`)
4. Resume monitoring (`wait_for` / `get_agent_state`)
5. Pick up from Next Steps #1

Step 2: brain_store the Handoff

brain_store(
  content: "SESSION HANDOFF {date}: {1-paragraph summary}. Handoff file: {path}. Key state: {active agents}, {open PRs}, {next priority}. User corrections captured: {count}.",
  tags: ["handoff", "session-end", "<project>"],
  importance: 8
)

This ensures the new agent can find the handoff via brain_search even if the file path changes.

Step 3: Spawn the New Agent

1. `spawn_agent({repo, cli, model, prompt})`
2. Capture the returned `agent_id`
3. `wait_for({agent_id, target_state:"ready", timeout_ms:120000})`
4. If `wait_for` times out but `read_screen` shows a prompt, treat it as FR-06 parser ambiguity and continue

CRITICAL: Spawn the continuation agent through spawn_agent, not by typing a raw launcher into a fresh pane. Keep the agent_id in the handoff notes so the next monitor loop does not depend on a remembered surface number.

Step 4: Answer the Grill (OUTGOING agent's job)

The new agent will ask orientation questions ("What's the current state?", "What should I focus on?"). The OUTGOING agent must answer these — NOT the user.

Process:

1. Track the new agent by agent_id, not by surface index
2. Use wait_for({agent_id, target_state:"idle", timeout_ms:120000}) or get_agent_state({agent_id}) to catch the moment it is waiting for input
3. When the new agent asks questions → answer via send_to_agent({agent_id, text, press_enter:true})
4. Continue answering until the new agent says "oriented" or starts working independently
5. ONLY THEN tell the user the handoff is complete

User said this explicitly: "I meant for you to answer the grilling from what you already know, because you know enough."

Step 5: Verify and Release

Before declaring handoff complete:

1. New agent is working — wait_for or get_agent_state shows active progress, not a waiting prompt
2. Monitoring is active — the new agent is tracked by agent_id and has an explicit wait_for / state-check path
3. Corrections are stored — brain_search("user-correction") returns the corrections from this session
4. Handoff file exists — Read the file to verify it was written correctly

Then: brain_store("Handoff complete to {new-agent} ({agent_id}). Verified: working, monitoring active, corrections stored.") and notify user.

---

WHEN TO TRIGGER

| Signal | Action | |--------|--------| | Context at 45% | brain_store full state (checkpoint, not handoff yet) | | Context at 50-60% | Proactively compact. If quality degrades → trigger handoff. | | Context at 70% | MANDATORY handoff. Do NOT wait for 83.5% auto-compact. | | User says "wrap up" / "hand off" | Trigger handoff immediately | | User going to sleep with unfinished work | Handoff to continuation agent | | Session has been running 4+ hours | Consider handoff to avoid context degradation |

---

WHAT TO INCLUDE IN HANDOFF (from /frustration-capture)

Every handoff file MUST include the User Corrections section. This is where /frustration-capture compounds:

• All brain_stored corrections from this session (brain_search with "user-correction" tag)
• The correction categories and importance levels
• Behavioral rules derived from each correction

Without this, the new agent WILL repeat the same mistakes. Evidence: April 4 session — new orcClaude had no access to 34 corrections from the outgoing session because they were never stored.

---

ANTI-PATTERNS

| Don't | Do Instead | |-------|-----------| | Send handoff as raw cmux text | Write structured file, new agent reads it | | Wait for user to answer grill | Outgoing agent answers from its own context (Step 4) | | Forget to set up monitoring | Establish wait_for / get_agent_state coverage BEFORE telling user handoff is done | | Skip brain_store | Always store — file can be deleted, BrainLayer persists | | Start new session fresh without handoff | Even a 5-line handoff is better than cold start | | Declare handoff "complete" without verification | Check: new agent working, monitoring active, corrections stored (Step 5) | | Hand off at 83.5% (auto-compact) | Hand off at 70% — quality degrades past 50%, auto-compact loses 60-70% |

---

INTEGRATION

| Skill | How Session Handoff Uses It | |-------|---------------------------| | /frustration-capture | Corrections section in handoff file — most valuable knowledge to transfer | | /agent-routing | Agent State table includes routing assignments (which agent has which workers) | | /orc | W6 is the minimal version — this skill is the complete version | | /cmux-agents | Spawn-and-verify pattern from spawn_agent / wait_for for the new agent | | /never-fabricate | Verify handoff file contents before declaring complete |

---

Inherited-citation suspect rule

After consuming a session-handoff doc OR resuming post-compaction, all file:line citations inherited from the prior session are SUSPECT until re-Read.

The receiving agent MUST:

1. In Phase 0, list every inherited file:line cite with the tag [SUSPECT: inherited from {compaction|handoff}].
2. Re-Read each cited path before referencing it in any deliverable. If the file doesn't exist or doesn't contain the claimed content, do NOT silently drop — write a "FABRICATED IN PRIOR BRIEFING: <cite>" entry to the deliverable AND brain_store with tag:compaction-fabrication.
3. Apply the same rule to chunk IDs (brainbar-*): re-resolve via brain_expand before acting on the inherited claim.

Mechanism: post-compaction summaries are pattern-completed by the compacting model and have a non-zero fabrication rate.

Evidence: coach session 2026-05-17 events [119], [206]: "my prior briefing had fabricated paths from a compaction summary" — receiving agent caught fabricated paths only because the agent happened to verify. This rule makes it deterministic instead of relying on diligence.