feat(session): cut-down session continuity — snapshot + resume

[thehoff]

Background

When the conversation compacts, the agent loses track of which files it was editing, what tasks were in progress, and what the last user prompt was. The user has to recap manually every time.

contextcrawler already has the SQLite tracking substrate (history.db) and owns the hook installation path (contextcrawler init). A scoped-down session-continuity feature is achievable without major new infrastructure.

Problem

Today, after a Claude Code compact, the agent has no idea:

• Which branch / worktree it was on
• Which files it last touched
• What command failed and was being investigated
• What the last user prompt was

The user has to recap manually.

Proposed Design (scoped down)

Start with the 5 highest-value signal categories, drawn from data already in history.db. Resist the temptation to track 20+ event types in v1 — measure usefulness of the smaller set first.

1. Working tree — branch, worktree path, dirty-files list (captured from git status invocations already passing through contextcrawler)
2. Last failures — most recent 5 rows from parse_failures table (already exists)
3. Last commands — most recent 10 rows from commands table with non-trivial exec time
4. Active deps — from cargo/pnpm invocations: which packages were last touched
5. User intent hint — last proxy invocation often indicates what was being debugged

Two new commands:

contextcrawler session snapshot     # build snapshot, store in DB
contextcrawler session resume       # emit Session Guide markdown to stdout

Hook wiring (extends existing contextcrawler init):

{
  "hooks": {
    "PreCompact": [{"command": "contextcrawler session snapshot"}],
    "SessionStart": [{"command": "contextcrawler session resume --if-snapshot"}]
  }
}

Snapshot persists in new session_snapshots table:

CREATE TABLE session_snapshots (
    id INTEGER PRIMARY KEY,
    session_id TEXT,
    captured_at TEXT,
    snapshot_md TEXT
);

--if-snapshot returns empty output (no-op) if no snapshot exists for the session — keeps fresh sessions clean.

Why now

• v0.1.10 release-boundary slicing (PR feat(gain): release-boundary slicing for --weak-filters #150) established the "binary lifecycle hooks update the DB" pattern; session continuity extends it
• All 5 chosen signals are already in history.db — just need to surface them
• Hook install machinery is already in contextcrawler init

Effort

M (1 week) for cut-down. XL (2-3 weeks) for full 23-category version. Start cut-down, expand only if there's empirical demand.

Dependencies

• Soft dep on feat(web): fetch-and-index with FTS5 retrieval layer #159 (fetch-and-index FTS5): the snapshot machinery and FTS5 infrastructure overlap. Build feat(web): fetch-and-index with FTS5 retrieval layer #159 first; reuse the SQLite + FTS5 patterns here.

Out of scope (v1)

• Cross-platform parity beyond Claude Code (defer Codex/Gemini/etc.)
• FTS5 search across session history (defer — gain --history already gives you raw)
• "Intent classification" / "blocker tracking" / "user-decision capture" — defer until v1 proves the cut-down is useful