cass

# 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.