Replay From Handoff

Pick up work from a previous session with full state verification and git patch restore.

Lifecycle

The handoff file is a single-use baton. Read it, verify state, restore patches, delete it.

Steps

1. Find handoff files — Search both personal and team directories. Check for own session's handoff first:

   REMEMBRALL_ROOT="${CLAUDE_PLUGIN_ROOT:-$(cat /tmp/remembrall-meta/plugin-root 2>/dev/null)}"
   source "${REMEMBRALL_ROOT}/hooks/lib.sh"
   CWD=$(pwd)
   HANDOFF_DIR=$(remembrall_handoff_dir "$CWD")
   TEAM_DIR=$(remembrall_team_handoff_dir "$CWD")
   FALLBACK_DIRS=""
   # Session ID: env var or published by hook
   OWN_SID="${CLAUDE_SESSION_ID:-$(remembrall_read_session_id "$CWD" 2>/dev/null)}"
   echo "Personal: $HANDOFF_DIR"
   echo "Team: $TEAM_DIR"
   echo "Own session: $OWN_SID"
   # Check own session first
   if [ -n "$OWN_SID" ] && [ -f "$HANDOFF_DIR/handoff-${OWN_SID}.md" ]; then
     echo "OWN SESSION HANDOFF: $HANDOFF_DIR/handoff-${OWN_SID}.md"
   fi
   # List all available
   ls -lt "$HANDOFF_DIR"/handoff-*.md "$TEAM_DIR"/handoff-*.md 2>/dev/null || echo "No handoffs found"
   # Fallback: hash lookup missed (path bug, symlink path, or running /replay from a parent dir)
   if ! compgen -G "$HANDOFF_DIR/handoff-*.md" >/dev/null; then
     FALLBACK_DIRS=$(remembrall_replay_fallback_dirs "$CWD" 2>/dev/null || true)
     if [ -n "$FALLBACK_DIRS" ]; then
       echo "Fallback dirs:"
       printf '%s\n' "$FALLBACK_DIRS"
       HANDOFF_DIR=$(printf '%s\n' "$FALLBACK_DIRS" | head -1)
       TEAM_DIR="$HANDOFF_DIR"
       if [ -n "$OWN_SID" ] && [ -f "$HANDOFF_DIR/handoff-${OWN_SID}.md" ]; then
         echo "OWN SESSION HANDOFF (fallback): $HANDOFF_DIR/handoff-${OWN_SID}.md"
       fi
       ls -lt "$HANDOFF_DIR"/handoff-*.md 2>/dev/null || true
     fi
   fi

   • 0 files: Tell the user: "No handoff found. Nothing to replay."
   • Own session file found: Use it directly.
   • No exact hash match, one fallback dir: Use that directory and repeat the own-session check there.
   • No exact hash match, multiple fallback dirs: List the newest handoff from each matching directory and ask the user which project/session to replay.
   • Only other sessions' files: List them with timestamps. Ask the user which one to replay before consuming — these belong to other Claude instances.
   • Multiple including own: Use own session's handoff, mention others exist.
2. Read the handoff — Read the selected file's contents.
3. Parse frontmatter — If the file starts with ---, extract structured fields:
   • status, branch, commit, patch, files, tasks, team, previous_session
   • If no frontmatter (legacy handoff), skip verification steps and proceed with markdown-only mode.
4. Mark consumed file — Rename instead of delete (preserved for safety; auto-cleaned after 1 hour):

   mv "$HANDOFF_FILE" "${HANDOFF_FILE%.md}.consumed.md"

5. Check chain history — If previous_session is present, note it for the briefing. Optionally check if the previous session's handoff still exists (it usually won't — consumed on resume). This gives the user awareness of how many sessions deep they are.
6. Validate freshness — Check the created timestamp. If older than the configured retention period, warn the user it may be stale and ask if they want to continue.
7. Verify git state (if frontmatter has branch/commit):

   CURRENT_BRANCH=$(git branch --show-current 2>/dev/null)
   CURRENT_COMMIT=$(git rev-parse --short HEAD 2>/dev/null)
   echo "Handoff: branch=$BRANCH commit=$COMMIT"
   echo "Current: branch=$CURRENT_BRANCH commit=$CURRENT_COMMIT"
   if [ "$CURRENT_COMMIT" != "$COMMIT" ]; then
     git log --oneline "$COMMIT..HEAD" 2>/dev/null || echo "Could not compare commits"
   fi

   • Branch mismatch: Warn user, ask if they want to switch.
   • Commit mismatch: Show what changed since handoff with git log --oneline.
   • Match: Confirm state is unchanged.
8. Verify files — For each file in the frontmatter files list:
   • Check if it exists on disk
   • If commit is available, check git diff $COMMIT -- $FILE to see if modified since handoff
   • Summarize: "N files unchanged, N modified since handoff, N missing"
9. Restore git patches (if patch field exists and the file is present):

   # Check if patch applies cleanly
   git apply --check "$PATCH_PATH" 2>&1

   • Clean apply: Ask user: "Apply saved changes from previous session? (X files, Y lines changed)"
   • If yes: Run git apply "$PATCH_PATH" then rm -f "$PATCH_PATH"
   • If conflicts: Show which files conflict, suggest manual review. Do NOT force-apply.
   • No patch file: Skip silently.

10. Present structured briefing — Show a clear summary to the user:

    ## Session Replay
    
    **Task:** [from handoff]
    **Active Skill:** [skill and phase/step from handoff, or "none"]
    **Status:** [status] | branch: [match/mismatch] | commit: [match/N new commits]
    **Files:** [N unchanged, N modified, N missing since handoff]
    **Patches:** [applied / skipped / none]
    **Chain:** [session N → this session] or [first session] if no previous_session
    
    ### Completed
    - [items from handoff]
    
    ### Remaining (priority-ordered)
    1. [blockers first — anything marked as blocked, erroring, or prerequisite]
    2. [in-progress items — partially done work from previous session]
    3. [not-started items — new tasks that haven't been touched]
    
    ### Key Decisions (preserved from previous session)
    - [decisions]
    
    ### Open Questions
    - [unresolved items]

11. Create task list with priority ordering — For each remaining item from the handoff, create a task. Order them by priority:

    1. Blockers — items flagged as blocked, failing, or prerequisite for other work
    2. In-progress — items partially completed in the previous session
    3. Not-started — items that haven't been touched yet

    Infer priority from context clues in the handoff:

    • Words like "blocked", "failing", "error", "prerequisite", "depends on", "must fix first" → blocker
    • Words like "started", "partial", "WIP", "halfway", "begun" → in-progress
    • Everything else → not-started
12. Resume active skill — If the handoff specifies an Active Skill (e.g., /plan-guarded Phase 2 step 3), invoke that skill before proceeding. The skill will pick up from the documented phase/step. If no active skill, proceed normally.
13. Ask to proceed — "Ready to continue with [next remaining item]?" Don't charge ahead — the user may have changed priorities.

Rules

• Delete only the consumed handoff file — leave other sessions' files alone
• Delete consumed patch file only after successful git apply
• NEVER force-apply patches — if git apply --check fails, warn and skip
• Verify file state before modifying anything
• Respect decisions documented in the handoff — don't re-debate unless the user asks
• Legacy handoffs (no YAML frontmatter) still work — just skip verification steps 7-9
• If the handoff mentions blockers, address those first
• The handoff may have been written by a different Claude model — don't critique the approach, just continue it
• If this instance later needs to hand off, use /handoff — it will write a fresh one
• Do NOT re-read or re-analyze files just because they appear in a "Files Modified" list — those are for reference only. Only read files needed for the specific Next Step.
• If a "Do NOT Do" section exists, follow it strictly — it documents dead ends and completed work that must not be revisited
• If a "Next Step" section exists, that is the ONLY thing to propose — not a re-exploration of the entire task