cass

What this skill does

# cass Session Search

## Table of Contents

- [The Goldmine Principle](#the-goldmine-principle)
- [THE EXACT PROMPT — Discovery Workflow](#the-exact-prompt--discovery-workflow)
- [Version Pinning Caveat](#version-pinning-caveat)
- [Two-Step Bootstrap (Replaces "ALWAYS first")](#two-step-bootstrap-replaces-always-first)
- [Stuck-Index & Recovery Decision Tree](#stuck-index--recovery-decision-tree)
- [Quick Reference](#quick-reference)
- [When to Use What](#when-to-use-what)
- [Critical Rules](#critical-rules)
- [Agent Harness Exclusion](#agent-harness-exclusion)
- [Search Modes](#search-modes)
- [Cross-Machine Search (Multi-Workstation Corpus)](#cross-machine-search-multi-workstation-corpus)
- [Anti-Patterns (Don't Do These)](#anti-patterns-dont-do-these)
- [Resume a Past Session in Its Native Harness](#resume-a-past-session-in-its-native-harness)
- [The Heuristics](#the-heuristics)
- [jq Essentials](#jq-essentials)
- [Hidden Power: Capabilities the Old Skill Missed](#hidden-power-capabilities-the-old-skill-missed)
- [Token & Cost Analytics (Bonus Use Case)](#token--cost-analytics-bonus-use-case)
- [Recovery Cheat Sheet (No-Permission Moves)](#recovery-cheat-sheet-no-permission-moves)
- [Reference Index](#reference-index)
- [Quick Search (Grep Recipes for References)](#quick-search-grep-recipes-for-references)
- [Scripts](#scripts)
- [Validation](#validation)

> **Core Insight:** Your repeated prompts are your best prompts. If you typed it 10+ times, it works. Mine your history.

## The Goldmine Principle

Your conversation history contains:
- **Refined prompts** — Every rephrase that worked better was captured
- **Working rituals** — Prompts repeated 10+ times ARE your methodology
- **Scope decisions** — "When did we decide NOT to do X?"
- **Recovery moments** — What you searched for after context loss = what mattered

**The insight:** Mining your past beats inventing new approaches.

---

## THE EXACT PROMPT — Discovery Workflow

```
1. Bootstrap: Check health, refresh index, get project overview
   cass status --json && cass index --json
   cass search "*" --workspace /data/projects/PROJECT --aggregate agent,date --limit 1 --json

2. Find prompts: Search for keywords, filter to user prompts (lines 1-3)
   cass search "KEYWORD" --workspace /data/projects/PROJECT --json --fields minimal --limit 50 \
     | jq '[.hits[] | select(.line_number <= 3)]'

3. Follow hits: View the actual content
   cass view /path/from/source_path.jsonl -n LINE -C 20

4. Expand context: See the full conversation flow
   cass expand /path/from/source_path.jsonl --line LINE --context 3

5. Discover related: Find the whole work cluster
   cass context /path/from/source_path.jsonl --json
```

### Why This Workflow Works

- **Aggregations first** — Know the terrain before diving in
- **`--fields minimal`** — 5x smaller output, preserves context window
- **`line_number <= 3`** — User prompts live at the top of sessions
- **Context clustering** — Work happens in clusters; one good hit → many related sessions

---

## Version Pinning Caveat

cass evolves quickly. The skill describes **HEAD behavior** (latest source in `/dp/coding_agent_session_search`). The released **v0.3.6 binary** lacks several features added since:

- `cass sources agents {list,exclude,include}` — added 2026-04-20 (commit `82d8d70e`)
- Tail-end writer-race tolerance for full rebuilds — fixed 2026-04-22 (commit `e06342f2`, bead `zz8ni`)
- Lexical generation manifests for federated installs (commits `2b7b86a1`, `683ccd03`, `cf76fe15`)
- Rebuild producer stall telemetry (commit `73a86604`)

When a flag/subcommand returns "unrecognized" or behaves differently than documented, run `cass --version` and check `git log -- src/lib.rs` for the relevant commit. Each affected section calls out which commit/version it depends on.

Probe what your installed binary actually supports:
```bash
cass capabilities --json | jq '{version: .crate_version, features, connectors}'
cass introspect --json   | jq '.commands[].name'
```

---

## Two-Step Bootstrap (Replaces "ALWAYS first")

**Three states matter — never conflate them.**

| State | What it means | What to do |
|-------|---------------|------------|
| `cass health` exit 0 | Sub-50ms preflight passed | Search immediately |
| `cass health` exit 1 + `index.stale=true` | Index is **usable but old** | Search now, refresh in background with a wall-clock cap: `( timeout 600 cass index --json &>/tmp/cass-bg.log </dev/null & )` (NEVER bare `&` — cass index can hang) |
| `cass status` returns `database.exists=false` OR `documents=0` | Truly **broken/uninitialized** | Run `cass doctor --fix --json`, then `cass index --full --json` |

**The trap:** Treating a stale index as broken triggers an unneeded full rebuild (8–25s cost) when an incremental refresh (1–3s) or even a stale-but-correct query would have worked.

```bash
# Robust two-step bootstrap that never blocks the user.
# IMPORTANT: every cass index call gets a wall-clock cap. cass index has been
# observed to hang indefinitely under contention — without `timeout`, the
# bootstrap itself becomes the symptom.
cass status --json | jq '{healthy, fresh: .index.fresh, stale: .index.stale, db: .database.exists, sem: .semantic.available}'

# Refresh policy: stale → bg refresh (capped); never block search
if [ "$(cass status --json | jq -r '.index.stale')" = "true" ]; then
  ( timeout 600 cass index --json >"/tmp/cass-index.$$.log" 2>&1 </dev/null & ) 2>/dev/null
fi
# Search even with stale index — results are still useful
cass search "KEYWORD" --workspace /path --json --fields minimal --limit 10
```

For the production-quality version of this logic (cap-on-every-call, broken-state escalation, exit-code semantics for hooks), use `scripts/recover.sh` — it implements the full decision tree with timeouts and per-PID logs.

`cass health` returning exit 1 on stale is a *deliberate* preflight signal for cron/CI. In an interactive agent loop, prefer `cass status --json` and decide.

---

## Stuck-Index & Recovery Decision Tree

Real-world bugs we've hit (all observed in mined sessions). Walk top-down — **first match wins**.

| Symptom | Likely cause | Autonomous fix (no user prompt needed) |
|---------|--------------|----------------------------------------|
| `cass index --json` streams `phase: indexing, current: 0, total: N` for >2 min | OPEN issue #196 in v0.3.6: incremental hangs after prior `--force-rebuild` | Kill the run, then `cass index --full --force-rebuild --json` (25s typical) |
| `cass status` shows `index.rebuilding=true` and `pid` is stale (>1h) | Crashed indexer left lock | `cass doctor --fix --json` (removes stale `.index.lock` automatically) |
| `cass search` returns 0 hits but the file plainly contains the term | Term lives in tool stdout/stderr (skipped at index time) | Fall back to `rg -n "TERM" /path/to/session.jsonl` |
| `cass search --workspace /X` returns 0; same query without `--workspace` works | Workspace string mismatch | `cass search "KEYWORD" --aggregate workspace --limit 1 --json` to discover the canonical path, then re-run |
| `vtable constructor failed: fts_messages` (older bug, fixed in 0.3.0+) | DB↔FTS schema drift after upgrade | `cass doctor --fix --json` rebuilds the Tantivy side from SQLite |
| `--limit 0 panic` | Earlier cass versions panicked on limit=0 | Always pass `--limit 1` (or `--limit 5`) for aggregations |
| Massive `core.NNNNN` files in cass project dir | Past indexer crash recorded a coredump | They're SAFE to leave; they don't affect search. Only delete with explicit user permission. |
| `cass models install` fails with WSAENOTCONN on Windows (closed #193) | Network blip during huggingface download | Retry once; if it persists, use `--mirror <URL>` to point at a different HF mirror, or `--from-file <DIR>` if you have the model cached locally. Then `cass models verify`. |
| `cass index` says "Index rebuild is already in progress" but nothing visible | Concurrent agent triggered a rebuild |