Recover

$recover — Context Recovery After Compaction

Purpose: Help you get back up to speed after context compaction. Automatically detects in-progress work (RPI runs, evolve cycles), loads relevant knowledge, summarizes what you were doing and what's next, and prefers the Codex hookless lifecycle path when applicable.

YOU MUST EXECUTE THIS WORKFLOW. Do not just describe it.

CLI dependencies: gt, ao, bd — all optional. Shows what's available, skips what isn't.

Quick Start

$recover              # Full recovery dashboard
$recover --json       # Machine-readable JSON output
ao codex status       # Codex hookless lifecycle health
ao codex ensure-start # Rebuild startup context explicitly in Codex

Execution Steps

Step 1: Detect In-Progress Sessions (Parallel)

Run ALL of the following in parallel bash calls:

Call 1 — RPI Phased State:

if [ -f .agents/rpi/phased-state.json ]; then
  echo "=== RPI_STATE ==="
  cat .agents/rpi/phased-state.json
else
  echo "RPI_STATE=NONE"
fi

Call 2 — Evolve Cycle History:

if [ -f .agents/evolve/cycle-history.jsonl ]; then
  echo "=== EVOLVE_STATE ==="
  tail -3 .agents/evolve/cycle-history.jsonl
else
  echo "EVOLVE_STATE=NONE"
fi

Call 3 — Git Recent Changes:

echo "=== GIT_STATUS ==="
git status --short

echo "=== GIT_LOG ==="
git log --oneline -5

echo "=== GIT_BRANCH ==="
git branch --show-current

Call 4 — Work Queue State:

if bd ready --json >/dev/null 2>&1 && bd list --type epic --status open --json >/dev/null 2>&1; then
  echo "=== IN_PROGRESS ==="
  bd list --status in_progress 2>/dev/null | head -3
  echo "=== READY ==="
  bd ready 2>/dev/null | head -3
else
  echo "BD_DEGRADED_OR_UNAVAILABLE"
fi

Call 5 — Knowledge and Messages:

# Knowledge artifacts
echo "=== KNOWLEDGE_COUNT ==="
echo "Learnings=$(ls .agents/learnings/ 2>/dev/null | wc -l | tr -d ' ')"
echo "Patterns=$(ls .agents/patterns/ 2>/dev/null | wc -l | tr -d ' ')"

# Inbox if gt available
if command -v gt &>/dev/null; then
  echo "=== MESSAGES ==="
  gt mail inbox 2>/dev/null | head -3
else
  echo "GT_UNAVAILABLE"
fi

Call 6 — Codex Lifecycle (if available):

if command -v ao &>/dev/null; then
  echo "=== CODEX_STATUS ==="
  ao codex status --json 2>/dev/null || echo "CODEX_STATUS=UNAVAILABLE"
else
  echo "AO_UNAVAILABLE"
fi

Step 2: Load Context from Knowledge Base

If RPI state detected, run:

if command -v ao &>/dev/null; then
  ao lookup --query "rpi recovery context" --limit 5 2>/dev/null || true
fi

Apply retrieved knowledge: If learnings are returned, check each for applicability to the recovery context. Cite applicable learnings by filename and record: ao metrics cite "<path>" --type applied 2>/dev/null || true

If Codex hookless mode is detected, also ensure startup context once for the current thread:

ao codex ensure-start 2>/dev/null || true

Step 3: Parse and Summarize Session State

Extract from collected data:

1. RPI Detection: If .agents/rpi/phased-state.json exists:

   • Extract goal, epic_id, phase, cycle, started_at
   • Map phase number to phase name (1=research, 2=plan, 3=implement, 4=validate)
   • Show elapsed time since started_at

2. Evolve Detection: If .agents/evolve/cycle-history.jsonl exists:

   • Read last entry for most recent cycle
   • Extract goals_fixed, result, timestamp
   • Show latest cycle summary

3. Recent Work: From git log:

   • Last 3 commits (extracted in Call 3)
   • Uncommitted changes count

4. Pending Work: From beads:

   • In-progress issues (up to 3)
   • Ready issues count

5. Knowledge State:

   • Total learnings and patterns available
   • Unread messages count if gt available

Step 4: Render Recovery Dashboard

Assemble gathered data into this format:

══════════════════════════════════════════════════════════════
  Context Recovery Dashboard
══════════════════════════════════════════════════════════════

IN-PROGRESS RPI RUN
  Epic: <epic_id>
  Goal: <first 80 chars of goal>
  Phase: <phase name: research | plan | implement | validate>
  Cycle: <cycle #>
  Started: <time ago (e.g., "2 hours ago")>
  Status: <PHASE_START | IN_PROGRESS | READY_FOR_GATE | ...>

  ─ Next Step: <state-aware suggestion from Step 5>

OR

RECENT EVOLVE CYCLE (IF NO RPI)
  Cycle: <cycle #>
  Latest Goal: <goal_id or summary>
  Result: <result>
  Items Completed: <count or "—">
  Timestamp: <time ago>

  ─ Next Step: <state-aware suggestion from Step 5>

OR

[NO ACTIVE SESSION]
  No RPI run or evolve cycle in progress.
  Last activity: <time of last commit or "unknown">

IN-PROGRESS WORK
  <list up to 3 in-progress issues with IDs>
  <or "No in-progress work">

READY TO WORK
  <count of ready issues>
  <or "No ready issues">

RECENT COMMITS
  <last 3 commits>

PENDING CHANGES
  <uncommitted file count or "clean">

KNOWLEDGE AVAILABLE
  Learnings: <count>  Patterns: <count>

INBOX
  <message count or "No messages" or "gt not installed">

──────────────────────────────────────────────────────────────
SUGGESTED NEXT ACTION
  <state-aware command from Step 5>
──────────────────────────────────────────────────────────────

QUICK COMMANDS
  $status       Current workflow dashboard
  $research     Deep codebase exploration
  $plan         Decompose work into issues
  $implement    Execute a single issue
  $crank        Autonomous epic execution
  $validation   Full close-out and learnings
══════════════════════════════════════════════════════════════

Step 5: Suggest Next Action (State-Aware)

Evaluate context top-to-bottom. Use the FIRST matching condition:

Step 6: JSON Output (--json flag)

If the user passed --json, output all recovery data as structured JSON:

{
  "session_type": "rpi|evolve|none",
  "rpi": {
    "epic_id": "ag-l2pu",
    "goal": "Implement...",
    "phase": 2,
    "phase_name": "plan",
    "cycle": 1,
    "started_at": "2026-02-15T14:33:36-05:00",
    "elapsed_minutes": 120
  },
  "evolve": {
    "cycle": 3,
    "result": "improved",
    "goals_fixed": ["goal1", "goal2"],
    "timestamp": "2026-02-15T22:00:00-05:00"
  },
  "work_state": {
    "in_progress_count": 3,
    "in_progress_issues": ["ag-042.1", "ag-042.2"],
    "ready_count": 5,
    "uncommitted_changes": 2
  },
  "git": {
    "branch": "main",
    "recent_commits": [
      "7de51c8 feat: wave 2 — structural assertions",
      "25004f8 fix: replace per-wave vibe gate"
    ]
  },
  "knowledge": {
    "learnings_count": 12,
    "patterns_count": 5
  },
  "inbox": {
    "unread_count": 0
  },
  "suggestion": {
    "priority": 4,
    "message": "Resume implementation: $implement ag-042.1"
  }
}

Render this with a single code block. No visual dashboard when --json is active.

Examples

Recovery After Compaction Mid-RPI

User says: $recover

What happens:

1. Agent runs 5 parallel bash calls to gather state
2. Agent detects RPI run in phased-state.json (phase=2, epic ag-l2pu)
3. Agent runs ao lookup --query "rpi recovery context" to load relevant knowledge
4. Agent shows goal, current phase (plan), cycle 1, started 2 hours ago
5. Agent lists 2 in-progress issues and 3 ready issues
6. Agent shows clean git state, recent commit
7. Agent suggests: "Review plan: $pre-mortem to validate before coding"

Result: Dashboard confirms in-progress RPI session, loads context, suggests next step.

Recovery After Compaction With Evolve Cycle

User says: $recover

What happens:

1. Agent gathers state in parallel
2. Agent finds no RPI run
3. Agent detects evolve cycle (most recent: cycle 3, result "improved", goals_fixed=["goal1", "goal2"])
4. Agent shows timestamp (1 hour ago), items_completed (8)
5. Agent loads knowledge with ao lookup --query "evolve cycle recovery"
6. Agent suggests: "Continue autonomous improvements: $evolve --resume"

Result: Dashboard confirms evolve cycle, shows progress, offers resume command.

Recovery in Clean State (No Active Session)

User says: $recover

What happens:

1. Agent gathers state in parallel
2. Agent finds no RPI run, no evolve cycle
3. Agent shows last 3 commits only
4. Agent finds no in-progress work, no ready issues
5. Agent shows 12 learnings available from knowledge base
6. Agent suggests: "Session recovered. Start with $status to plan next work"

Result: Dashboard confirms clean state, points user to entry points.

Troubleshooting

Local Resources

scripts/

• scripts/validate.sh