session-recovery

Context

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.

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.

Patterns

1. Find Recent Sessions

Query the sessions table filtered by time window. Include the last checkpoint to understand where the session stopped:

SELECT
  s.id,
  s.summary,
  s.cwd,
  s.branch,
  s.updated_at,
  (SELECT title FROM checkpoints
   WHERE session_id = s.id
   ORDER BY checkpoint_number DESC LIMIT 1) AS last_checkpoint
FROM sessions s
WHERE s.updated_at >= datetime('now', '-24 hours')
ORDER BY s.updated_at DESC;

2. Filter Out Automated Sessions

Automated agents (monitors, keep-alive, heartbeat) create high-volume sessions that obscure human-initiated work. Exclude them:

SELECT s.id, s.summary, s.cwd, s.updated_at,
  (SELECT title FROM checkpoints
   WHERE session_id = s.id
   ORDER BY checkpoint_number DESC LIMIT 1) AS last_checkpoint
FROM sessions s
WHERE s.updated_at >= datetime('now', '-24 hours')
  AND s.id NOT IN (
    SELECT DISTINCT t.session_id FROM turns t
    WHERE t.turn_index = 0
      AND (LOWER(t.user_message) LIKE '%keep-alive%'
           OR LOWER(t.user_message) LIKE '%heartbeat%')
  )
ORDER BY s.updated_at DESC;

3. Search by Topic (FTS5)

Use the search_index FTS5 table for keyword search. Expand queries with synonyms since this is keyword-based, not semantic:

SELECT DISTINCT s.id, s.summary, s.cwd, s.updated_at
FROM search_index si
JOIN sessions s ON si.session_id = s.id
WHERE search_index MATCH 'auth OR login OR token OR JWT'
  AND s.updated_at >= datetime('now', '-48 hours')
ORDER BY s.updated_at DESC
LIMIT 10;