SKILL.md (5329B)
1 --- 2 name: "session-recovery" 3 description: "Find and resume interrupted Copilot CLI sessions using session_store queries" 4 domain: "workflow-recovery" 5 confidence: "high" 6 source: "earned" 7 tools: 8 - name: "sql" 9 description: "Query session_store database for past session history" 10 when: "Always — session_store is the source of truth for session history" 11 --- 12 13 ## Context 14 15 Squad agents run in Copilot CLI sessions that can be interrupted — terminal crashes, network drops, machine restarts, or accidental window closes. When this happens, in-progress work may be left in a partially-completed state: branches with uncommitted changes, issues marked in-progress with no active agent, or checkpoints that were never finalized. 16 17 Copilot CLI stores session history in a SQLite database called `session_store` (read-only, accessed via the `sql` tool with `database: "session_store"`). This skill teaches agents how to query that store to detect interrupted sessions and resume work. 18 19 ## Patterns 20 21 ### 1. Find Recent Sessions 22 23 Query the `sessions` table filtered by time window. Include the last checkpoint to understand where the session stopped: 24 25 ```sql 26 SELECT 27 s.id, 28 s.summary, 29 s.cwd, 30 s.branch, 31 s.updated_at, 32 (SELECT title FROM checkpoints 33 WHERE session_id = s.id 34 ORDER BY checkpoint_number DESC LIMIT 1) AS last_checkpoint 35 FROM sessions s 36 WHERE s.updated_at >= datetime('now', '-24 hours') 37 ORDER BY s.updated_at DESC; 38 ``` 39 40 ### 2. Filter Out Automated Sessions 41 42 Automated agents (monitors, keep-alive, heartbeat) create high-volume sessions that obscure human-initiated work. Exclude them: 43 44 ```sql 45 SELECT s.id, s.summary, s.cwd, s.updated_at, 46 (SELECT title FROM checkpoints 47 WHERE session_id = s.id 48 ORDER BY checkpoint_number DESC LIMIT 1) AS last_checkpoint 49 FROM sessions s 50 WHERE s.updated_at >= datetime('now', '-24 hours') 51 AND s.id NOT IN ( 52 SELECT DISTINCT t.session_id FROM turns t 53 WHERE t.turn_index = 0 54 AND (LOWER(t.user_message) LIKE '%keep-alive%' 55 OR LOWER(t.user_message) LIKE '%heartbeat%') 56 ) 57 ORDER BY s.updated_at DESC; 58 ``` 59 60 ### 3. Search by Topic (FTS5) 61 62 Use the `search_index` FTS5 table for keyword search. Expand queries with synonyms since this is keyword-based, not semantic: 63 64 ```sql 65 SELECT DISTINCT s.id, s.summary, s.cwd, s.updated_at 66 FROM search_index si 67 JOIN sessions s ON si.session_id = s.id 68 WHERE search_index MATCH 'auth OR login OR token OR JWT' 69 AND s.updated_at >= datetime('now', '-48 hours') 70 ORDER BY s.updated_at DESC 71 LIMIT 10; 72 ``` 73 74 ### 4. Search by Working Directory 75 76 ```sql 77 SELECT s.id, s.summary, s.updated_at, 78 (SELECT title FROM checkpoints 79 WHERE session_id = s.id 80 ORDER BY checkpoint_number DESC LIMIT 1) AS last_checkpoint 81 FROM sessions s 82 WHERE s.cwd LIKE '%my-project%' 83 AND s.updated_at >= datetime('now', '-48 hours') 84 ORDER BY s.updated_at DESC; 85 ``` 86 87 ### 5. Get Full Session Context Before Resuming 88 89 Before resuming, inspect what the session was doing: 90 91 ```sql 92 -- Conversation turns 93 SELECT turn_index, substr(user_message, 1, 200) AS ask, timestamp 94 FROM turns WHERE session_id = 'SESSION_ID' ORDER BY turn_index; 95 96 -- Checkpoint progress 97 SELECT checkpoint_number, title, overview 98 FROM checkpoints WHERE session_id = 'SESSION_ID' ORDER BY checkpoint_number; 99 100 -- Files touched 101 SELECT file_path, tool_name 102 FROM session_files WHERE session_id = 'SESSION_ID'; 103 104 -- Linked PRs/issues/commits 105 SELECT ref_type, ref_value 106 FROM session_refs WHERE session_id = 'SESSION_ID'; 107 ``` 108 109 ### 6. Detect Orphaned Issue Work 110 111 Find sessions that were working on issues but may not have completed: 112 113 ```sql 114 SELECT DISTINCT s.id, s.branch, s.summary, s.updated_at, 115 sr.ref_type, sr.ref_value 116 FROM sessions s 117 JOIN session_refs sr ON s.id = sr.session_id 118 WHERE sr.ref_type = 'issue' 119 AND s.updated_at >= datetime('now', '-48 hours') 120 ORDER BY s.updated_at DESC; 121 ``` 122 123 Cross-reference with `gh issue list --label "status:in-progress"` to find issues that are marked in-progress but have no active session. 124 125 ### 7. Resume a Session 126 127 Once you have the session ID: 128 129 ```bash 130 # Resume directly 131 copilot --resume SESSION_ID 132 ``` 133 134 ## Examples 135 136 **Recovering from a crash during PR creation:** 137 1. Query recent sessions filtered by branch name 138 2. Find the session that was working on the PR 139 3. Check its last checkpoint — was the code committed? Was the PR created? 140 4. Resume or manually complete the remaining steps 141 142 **Finding yesterday's work on a feature:** 143 1. Use FTS5 search with feature keywords 144 2. Filter to the relevant working directory 145 3. Review checkpoint progress to see how far the session got 146 4. Resume if work remains, or start fresh with the context 147 148 ## Anti-Patterns 149 150 - ❌ Searching by partial session IDs — always use full UUIDs 151 - ❌ Resuming sessions that completed successfully — they have no pending work 152 - ❌ Using `MATCH` with special characters without escaping — wrap paths in double quotes 153 - ❌ Skipping the automated-session filter — high-volume automated sessions will flood results 154 - ❌ Assuming FTS5 is semantic search — it's keyword-based; always expand queries with synonyms 155 - ❌ Ignoring checkpoint data — checkpoints show exactly where the session stopped