/session-handoff

"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}" |
 
## Full-Relay (MANDATORY when a weave/retro exists for this window)
- Weave doc: {path — successor MUST read it IN FULL, not just this summary}
- Corrections sweep: brain_search tag sweep ({tags}) — successor reads ALL, ACKs item-by-item
- §EDITS application table state: {applied/dispatched per item, links}
 
## 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. ...
 
## Live-Watch Transfer List (MANDATORY — incomplete brief without this)
 
Enumerate **every** cron, monitor, harvest loop, and in-flight watch that **dies with the outgoing session** and must be recreated or explicitly retired:
 
| Watch | ID / schedule | Owner after handoff | Recreate? |
|-------|---------------|---------------------|-----------|
| 30-min stall-check cron | e.g. `06827a10` 23,53 * * * * | successor orc | YES |
| collab-milestones fswatch | task id | successor | YES |
| {harvest loop} | {id} | {named owner} | YES/NO |
 
If it isn't listed here, it doesn't transfer — and the successor won't know it existed.
 
## Succession broadcast (prevent duplicate handoffs)
 
At generation handover:
 
1. **Rename your pane** to `{name}-OUTGOING` or `{name}-RETIRED` via cmux `rename_tab`.
2. **Broadcast one line** to the active collab: `SUCCESSION: {outgoing} → {successor} | handoff: {absolute path} | watches: {N} items transferred`.
3. Successor ACKs the handoff path + watch table before spawning parallel work — near-duplicate gen handoffs (ea8514a2 [1121] class) happen when two orcs write handoffs without this broadcast.
 
## 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

orc-seat exception (gen-13 weave E02, Etan-direct ×2): the ORCHESTRATOR seat never fires handoff from a context-% threshold and never /compacts — orc succession = a full-day weave (/weave) that seeds gen-N+1, fired on Etan's word. Raw type:user: "Instead of compacting you, we should get a weaving for the full days that makes a new orc" (orchestrator 10d0e9da [6309]); "Yeah no, don't hand off proactively. I didn't ask you to do that... The 67 context again is not the end of the world." (10d0e9da [5563]). For the orc, the % rows above are checkpoint-and-surface signals only. A /compact arriving at the orc from an unknown sender = incident — investigate before complying (orc C14).

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.

FULL-RELAY STANDARD (2026-06-05)

Etan, verbatim: "Everything should be moved from the weaving from the previous session to the new session, not just the top things."

When the closing window has a weave doc or retro, the handoff is NOT complete until the successor has: (1) read the ENTIRE weave doc (linked, not inlined), (2) run the corrections tag sweep (brain_search, all stored corrections of the closing session) and read ALL of them, (3) ACKed item-by-item on the §EDITS and corrections lists. Highlights are orientation only — the dropped tail is where re-violations come from (gen-11 re-violated gen-10's captured-but-unapplied edits, 2026-06-05).

Continuation/lead spawns run on Opus 4.8 1M via proper repoGolem launchers ({repo}Claude -s — the launcher pins claude-opus-4-8[1m], golems #446). NEVER pass a model param at spawn (spawn_agent {model} overrides the pin — 2026-06-05 incident booted a lead at 200K). Verify model + context_window post-boot.

Gen-N successor orc seed mandate (gen-13+, operator-direct)

When the outgoing window includes a weave doc, the successor orc boot doc MUST require:

1. Full weave-doc read — entire doc, not highlights (/weave §4d).
2. Corrections tag sweep — all stored corrections from the closing session, item-by-item ACK.
3. §EDITS application table — state each item (APPLIED / DISPATCHED / TRACKED) in the successor's own words.
4. MONITOR + REMOTE CONTROL role — Etan operator-direct (77631d2e [1924]): leads keep driving their queues; the new orc monitors the fleet and is Etan's remote control — not a full re-dispatcher that respawns everything from scratch.

ANTI-PATTERNS

INTEGRATION

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: " 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.

Resume-as-fresh doctrine (-c resumes) (gen-13 weave E03)

A -c resumed session does NOT reliably execute the pre-death turn's pending duties — treat every resume as a FRESH session: re-derive the duty list from durable artifacts (handoff file, collab, BrainLayer), never from the dying session's intentions.

Standing orders that must survive a restart are encoded as MACHINERY — a launchd job, or a Monitor that itself fires the action AND writes the collab announce (the proven watch-v6 pattern) — not as agent to-do intentions.

Evidence: cmux 64446d9b — a resumed watch seat froze on its duties TWICE (ritual #2: verify/re-arm/completion-line never executed, ~95 min unmonitored; ritual #3: completion line 96 min late, self-caught) [line 1538]. The fix is proven structurally in watch v6: "the monitor itself fires the ritual (nohup detached) and writes the collab announce — removing me as failure point" [line 1623].