# Token, Tool & Model Analytics

> **One-liner:** cass already has every Claude/Codex/Gemini API call you've made. `cass analytics` rolls them up into per-day, per-tool, per-model usage tables — no separate billing pipeline needed.

## Contents

- [Five Subcommands](#five-subcommands)
- [Status First](#status-first)
- [Token Usage Reports](#token-usage-reports)
- [Tool Usage](#tool-usage)
- [Model Usage](#model-usage)
- [Rebuild Strategy](#rebuild-strategy)
- [Validation](#validation)
- [Pitfalls](#pitfalls)

---

## Five Subcommands

```bash
cass analytics status --json     # Coverage + freshness of rollup tables
cass analytics tokens --json     # Token usage time-series + dim breakdowns
cass analytics tools --json      # Per-tool invocation counts
cass analytics models --json     # Top models + coverage stats
cass analytics rebuild --json    # Backfill / rebuild rollup tables
cass analytics validate --json   # Drift detection between raw rows and aggregates
```

---

## Status First

```bash
cass analytics status --json | jq '.data'
```

Look for:
- `coverage.api_token_coverage_pct` — % of messages with real API token data (vs estimate)
- `coverage.estimate_only_pct` — inverse; <10% is healthy
- `coverage.message_metrics_coverage_pct` — % with full per-message stats
- `drift.signals` — empty array means rollups match raw data
- `drift.track_a_fresh` / `track_b_fresh` — are both rollup tracks current
- `recommended_action` — "none" or specific (`"rebuild"`, `"validate"`)

If `track_a_fresh=false` or `coverage.api_token_coverage_pct < 90`, run:

```bash
cass analytics rebuild --json | jq '.data.summary'
```

---

## Token Usage Reports

`--group-by` is **time-only** (`hour|day|week|month`). To slice by agent or model, use the dedicated subcommands or filter flags.

```bash
# Last 30 days, daily buckets
cass analytics tokens --days 30 --group-by day --json | jq '.data.buckets'

# Hour granularity for the past day
cass analytics tokens --days 1 --group-by hour --json | jq '.data.buckets'

# Filter to one agent (slug from cass capabilities --json | jq '.connectors')
cass analytics tokens --days 30 --agent claude_code --json | jq '.data.totals'

# Specific date range
cass analytics tokens --since 2026-04-01 --until 2026-04-22 --json
```

### Real Output Shape

```json
{ "data": {
    "bucket_count": 30,
    "buckets": [{
      "bucket": "2026-04-22",
      "counts":         {"message_count": 4374, "user_message_count": 74, "assistant_message_count": 0, "tool_call_count": 681, "plan_message_count": 0},
      "content_tokens": {"est_total": 45724, "est_user": 612, "est_assistant": 0},
      "api_tokens":     {"total": 145060939, "input": 1670, "output": 160042, "cache_read": 143693750, "cache_creation": 1205477, "thinking": 0},
      "plan_tokens":    {"content_est_total": 0, "api_total": 0},
      "coverage":       {"api_coverage_message_count": 1052, "api_coverage_pct": 24.05},
      "derived":        {"api_tokens_per_assistant_msg": null, "tool_calls_per_1k_api_tokens": 0.0047, ...}
    }, ...],
    "totals": {...}
}}
```

Note: `input/output/cache_read/cache_creation` live under `.api_tokens`, not flat at the row level. `cache_read` typically dwarfs `input` for active prompt-caching workloads — count it when estimating spend.

### Cost Estimation Pattern (per-day across all models)

```bash
# Rough $ across all activity at Sonnet-4 list prices
# (cache_read is ~10% the price of input; check current Anthropic pricing)
cass analytics tokens --days 30 --group-by day --json \
  | jq '.data.buckets[] | {
      day: .bucket,
      input_M:  (.api_tokens.input // 0) / 1e6,
      output_M: (.api_tokens.output // 0) / 1e6,
      cache_read_M: (.api_tokens.cache_read // 0) / 1e6
    }'
```

For per-model spend, use `cass analytics models --json` (next section); `tokens` does not break down by model. For Claude Max / GPT Pro flat-rate accounts, the dollar number is irrelevant — what matters is *throughput per account* (use `caam` to plan account allocation).

---

## Tool Usage

```bash
cass analytics tools --days 30 --json | jq '.data.rows[0:20]'
```

Returns rows with: `key` (agent slug), `tool_call_count`, `message_count`, `api_tokens_total`, `tool_calls_per_1k_api_tokens`, `tool_calls_per_1k_content_tokens`. Note: rows are keyed by **agent**, not by tool name — this is "tool-use intensity per agent." Useful for:

- Finding which tools dominate your workflow
- Detecting newly broken tools (sudden error spike)
- Justifying which `--allowedTools` to pre-approve in `.claude/settings.json`

---

## Model Usage

```bash
cass analytics models --json \
  | jq '.data.by_api_tokens.rows[0:10] | map({model: .key, tokens: .value, msgs: .message_count, derived})'
```

Returns under `.data.by_api_tokens.rows[]` with: `key` (model name), `value` (api_total tokens), `message_count`, `derived{api_coverage_pct, tool_calls_per_1k_api_tokens, plan_message_pct}`. There's also `.data.timeseries.buckets[]` for time-aware model usage.

Spot patterns like "Haiku is doing 80% of the work but Opus is doing all the spending" — then tune your skill triggers accordingly.

---

## Rebuild Strategy

After bulk operations that shuffle data:

```bash
# After cass sources sync
cass sources sync --source css --json
cass analytics rebuild --json

# After cass import chatgpt
cass import chatgpt /path/to/conversations.json --json
cass analytics rebuild --json

# After a long indexing campaign
cass index --full --force-rebuild --json
cass analytics rebuild --json
```

`rebuild` accepts `--since/--until/--days` to scope the backfill window, plus `--agent`, `--workspace`, and `--source local|remote|all|<host>` filters. There's no `--force` flag — to fully recompute, use a wide window like `--days 9999`. `cass analytics validate --json` afterward confirms invariants.

---

## Validation

```bash
cass analytics validate --json | jq '.data.invariants'
```

Checks:
- Sum(daily) == raw_messages_count for each day
- Token totals match cross-track
- No orphan rollup rows for missing conversations

If `signals` is non-empty, run `analytics rebuild --force` and re-validate.

---

## Pitfalls

- **Wrong field path is the #1 mistake.** `tokens` returns `.data.buckets[]`, `tools` returns `.data.rows[]`, `models` returns `.data.by_api_tokens.rows[]`. They are **not consistent** — always probe with `jq 'keys'` first when scripting against a new subcommand.
- **No `--group-by model` / `--group-by agent`.** Time-only enum (`hour|day|week|month`). For per-model breakdowns use `cass analytics models`; for per-agent use `cass analytics tools` (rows are keyed by agent slug despite the name).
- Analytics rollups are derived data. `cass doctor --fix` does NOT rebuild analytics rollups — only the lexical/FTS index. To repair analytics, use `cass analytics rebuild --json`.
- Coverage <90% usually means legacy sessions before the agent emitted token-usage events. Estimates fill the gap; rebuild can't recover what was never recorded.
- `cass analytics tokens` reads from the rollup tables; it won't reflect sessions added in the last few minutes until the next rollup tick. Run `cass analytics rebuild --days 1` for a fresh view.

# Anti-Patterns (Long Form)

> **Why this exists:** Mined sessions show the same wasteful behaviors repeating across hundreds of agent runs. Each item below has a real-world cost; the "instead" is the move that actually works.

## Contents

- [1. Asking the User to Do What You're Authorized To Do](#1-asking-the-user-to-do-what-youre-authorized-to-do)
- [2. Dropping the Whole Index](#2-dropping-the-whole-index)
- [3. Treating "Stale" as "Broken"](#3-treating-stale-as-broken)
- [4. `--limit 0` for "no limit"](#4---limit-0-for-no-limit)
- [5. Piping `cass export` Into Anything](#5-piping-cass-export-into-anything)
- [6. Searching Without a Workspace, Then Filtering Client-Side](#6-searching-without-a-workspace-then-filtering-client-side)
- [7. Workspace Path Drift](#7-workspace-path-drift)
- [8. Searching for Tool Output](#8-searching-for-tool-output)
- [9. Default Fields on Wide Scans](#9-default-fields-on-wide-scans)
- [10. Ignoring `_meta` and `_warning`](#10-ignoring-_meta-and-_warning)
- [11. Bare `cass`](#11-bare-cass)
- [12. Running `cass index --full` Every Loop](#12-running-cass-index---full-every-loop)
- [Summary](#summary)

---

## 1. Asking the User to Do What You're Authorized To Do

**Bad:**
> "Your cass index is stale. Could you run `cass index --full` and let me know when it's done?"

**Why bad:** Delegating an already authorized repair back to the user creates
unnecessary work. But staleness alone does not require repair.

**Instead:** Search healthy or stale-but-usable state immediately. If a concrete
recovery need is already authorized, use the bounded helper in
[RECOVERY.md](RECOVERY.md). Do not infer mutation authority from a search-only
request or from where the derived index lives. Sources, metadata, destinations
and model access retain their authorization boundaries.

---

## 2. Dropping the Whole Index

**Bad:**
```bash
rm -rf ~/.local/share/coding-agent-search
cass index --full --json   # rebuild from scratch
```

**Why bad:** Throws away 4M+ messages of indexed history. Rebuild from raw sessions takes 25min on a typical fleet. Loses analytics rollups (no easy recovery).

**Instead:**
```bash
cass doctor --fix --json   # rebuilds only what's broken
```

`doctor --fix` already backs up corrupt DBs, so you never lose data even when the original is bad.

---

## 3. Treating "Stale" as "Broken"

**Bad:** Seeing `cass status` say `healthy: false, recommended_action: "Run cass index"` and immediately running `cass index --full --force-rebuild` (25s blocking).

**Why bad:** The index is stale only because it's older than the threshold (default 30 min). The data is still **correct** — it just doesn't have sessions from the last 30 min indexed yet.

**Instead:** Search the usable index and retain observed freshness. Refresh only
when the task needs newer records and its indexing scope is authorized, using
a bounded invocation from [RECOVERY.md](RECOVERY.md). Do not start a second
indexer while an earlier authorized rebuild is progressing. A failed status
read is unknown, not evidence that the index is empty or corrupt.

---

## 4. `--limit 0` for "no limit"

**Bad:** `cass search "X" --limit 0 --json` (worked in earlier cass versions; no-ops or returns RAM-capped result in v0.3+, panicked before).

**Why bad:** Unbounded scans burn context. Even with the modern RAM cap, you get random truncation.

**Instead:** Pick a real number.
- Aggregations: `--limit 1` and parse `.aggregations.*` only
- Wide scans: `--limit 50` + `--fields minimal` + iterate via `--cursor`
- Sampling: `--limit 5 --fields summary`

---

## 5. Piping `cass export` Into Anything

**Bad:**
```bash
cass export /path.jsonl --format json | jq '.[0:50]'
```

**Why bad:** Large exports trigger broken-pipe panic when the consumer closes early.

**Instead:**
```bash
cass export /path.jsonl --format json --include-tools -o /tmp/export.json
jq '.[0:50]' /tmp/export.json
```

Always `-o`. The file is cheap; the panic isn't.

---

## 6. Searching Without a Workspace, Then Filtering Client-Side

**Bad:**
```bash
cass search "auth" --json --limit 500 \
  | jq '[.hits[] | select(.workspace == "/data/projects/myrepo")]'
```

**Why bad:** Server returned 500 hits, you keep maybe 50. 10x context waste.

**Instead:**
```bash
cass search "auth" --workspace /data/projects/myrepo --json --limit 50
```

Server-side filtering is free. Client-side filtering is paid in tokens.

---

## 7. Workspace Path Drift

**Bad:** `cass search "X" --workspace /data/projects/myrepo/` — note trailing slash. Returns 0 hits. You assume the corpus is empty.

**Why bad:** Workspace strings are case-sensitive and trailing-slash-sensitive. The canonical key may be `/data/projects/myrepo` (no slash) or different case.

**Instead:** Probe first.
```bash
cass search "X" --aggregate workspace --limit 1 --json \
  | jq '.aggregations.workspace.buckets[] | select(.key | contains("myrepo"))'
```
Use the exact key from the bucket.

---

## 8. Searching for Tool Output

**Bad:** Looking for the exact bytes of a `Bash` tool's stdout via `cass search`. Finds nothing. Concludes the session doesn't exist.

**Why bad:** cass deliberately skips large tool outputs at index time to keep the corpus searchable on prompts and replies. Tool outputs are still **in the source file**.

**Instead:** Find the episode using a nearby prompt phrase, then use CASS
pack/view/expand to inspect bounded context. If the actual required tool bytes
remain omitted, use a selected authorized raw excerpt as described in
[RAW_SOURCE_READS.md](RAW_SOURCE_READS.md). Missing source files and mismatched
returned locators remain retrieval gaps; do not bulk-read every search hit.

---

## 9. Default Fields on Wide Scans

**Bad:** `cass search "X" --json --limit 100` (no `--fields`). Returns ~3KB per hit × 100 = 300KB of context. With a 200K context budget, you've burned 1.5% on one tool call.

**Instead:**
```bash
cass search "X" --json --fields minimal --limit 100   # ~60KB total
```

Upgrade to `--fields summary` only for the few hits you decide to inspect.

---

## 10. Ignoring `_meta` and `_warning`

**Bad:** Reading `.hits` and reporting confidently — without checking that the index was fresh, the search wasn't truncated, and no fallback happened.

**Instead:**
```bash
cass search "X" --robot-meta --json | jq '{
  warning: ._warning,
  fresh: ._meta.index_freshness.fresh,
  fallback: ._meta.fallback_mode,
  clamped: ._meta.hits_clamped,
  total: .total_matches,
  shown: .count
}'
```

If `_warning` is non-null, mention it. If `hits_clamped: true`, paginate. If `fallback_mode != null`, your `--mode hybrid` actually ran lexical-only.

---

## 11. Bare `cass`

**Bad:** Running `cass` with no args inside an agent session. Launches the interactive TUI, blocks the agent's terminal, requires the user to Ctrl+C.

**Instead:** **Always** use `--json` or `--robot`. If you genuinely need TUI semantics from automation, `cass tui --once --asciicast /tmp/snap.cast` renders a single frame and exits.

---

## 12. Running `cass index --full` Every Loop

**Bad:** Pre-flight in a tight loop runs `cass index --full --json` every iteration. 25s × 60 iter = 25 min wasted.

**Instead:** Search immediately when the index is usable. Staleness is a coverage
limit to report; an authorized bounded refresh is optional when newer records
are needed. Do not add a startup refresh, watch process or preflight hook to an
ordinary history query.

---

## Summary

Use CASS's native retrieval surface, distinguish stale from unavailable, and
verify selected source context. Recovery is a separate bounded operation within
the caller's authority; search hits and citation flags do not prove source
continuity, message roles or successful outcomes.

# cass Command Reference

> **Freedom Key:** LOW = exact syntax required | MEDIUM = some flexibility | HIGH = multiple approaches

## Contents

- [Lifecycle Commands [LOW freedom]](#lifecycle-commands-low-freedom)
- [Search Command [MEDIUM freedom]](#search-command-medium-freedom)
- [View & Expand [LOW freedom]](#view--expand-low-freedom)
- [Export [LOW freedom]](#export-low-freedom)
- [Context [MEDIUM freedom]](#context-medium-freedom)
- [Timeline [MEDIUM freedom]](#timeline-medium-freedom)
- [Pagination [LOW freedom]](#pagination-low-freedom)
- [Chained Searches [MEDIUM freedom]](#chained-searches-medium-freedom)
- [Output Schemas](#output-schemas)
- [Exit Codes](#exit-codes)

---

## Lifecycle Commands [LOW freedom]

```bash
cass status --json              # Health check — is index current?
timeout 600 cass index --json   # Optional authorized refresh when needed
timeout 600 cass index --full --json # Selected recovery only; staleness is not enough
cass capabilities --json        # What this install supports
cass diag --json                # Detailed diagnostics
cass doctor                     # Repair (safe, won't delete sources)
```

### Status Output

```json
{
  "database": {"conversations": 4827, "messages": 664027},
  "index": {"fresh": true, "stale": false},
  "recommended_action": "Index is up to date"
}
```

---

## Search Command [MEDIUM freedom]

### Basic Form

```bash
cass search "QUERY" --workspace /path --json --fields minimal --limit N
```

**Every search needs:** `--json`, `--fields minimal`, `--limit N` (N > 0)

### Filtering

| Filter | Example |
|--------|---------|
| By workspace | `--workspace /data/projects/foo` |
| By agent | `--agent claude_code` |
| By mode | `--mode lexical` (default), `semantic`, `hybrid` |
| From session list | `--sessions-from /tmp/sessions.txt` |

### Output Control

| Flag | Effect | Token Impact |
|------|--------|--------------|
| `--fields minimal` | source_path, line_number, agent | **5x smaller** |
| `--fields summary` | + title, score | 2x smaller |
| `--max-content-length N` | Truncate snippets | Reduces size |
| `--max-tokens N` | Soft token budget | Caps output |

### Aggregations [LOW freedom]

```bash
cass search "*" --workspace /path --aggregate agent,date --limit 1 --json
```

**MUST use `--limit 1`** (not 0). Ignore `.hits`, parse `.aggregations` only.

```json
{
  "aggregations": {
    "agent": {"buckets": [{"key": "claude_code", "count": 925}]},
    "date": {"buckets": [{"key": "2026-01-16", "count": 112}]}
  }
}
```

Available: `agent`, `date`, `workspace`

### Robot Formats

| Flag | Output | Use Case |
|------|--------|----------|
| `--robot-format sessions` | Session paths only | Chaining searches |
| `--robot-format jsonl` | Streaming NDJSON | Large result sets |
| `--robot-meta` | Include `_meta` block | Check freshness |

### Debug

```bash
cass search "QUERY" --workspace /path --dry-run --explain
```

---

## View & Expand [LOW freedom]

### View (Line-Oriented)

```bash
cass view /path/to/session.jsonl -n LINE -C CONTEXT
```

| Flag | Meaning |
|------|---------|
| `-n LINE` | Center on this line |
| `-C N` | N lines before AND after |
| `-A N` | N lines after only |
| `-B N` | N lines before only |

### Expand (Message-Oriented)

```bash
cass expand /path/to/session.jsonl --line LINE --context N
```

**Use `expand` for conversation flow, `view` for raw debugging.**

---

## Export [LOW freedom]

```bash
cass export /path.jsonl --format json --include-tools -o /tmp/output.json
```

**CRITICAL:** Always export to file first. Piping causes broken pipe panic.

```bash
# WRONG (may panic):
cass export /path.jsonl --format json | head -100

# RIGHT:
cass export /path.jsonl --format json -o /tmp/out.json
jq '.[0:100]' /tmp/out.json
```

| Flag | Effect |
|------|--------|
| `--format json` | Machine parsing |
| `--format markdown` | Human review |
| `--include-tools` | Include tool calls (hidden by default) |
| `-o FILE` | Output file (required) |

---

## Context [MEDIUM freedom]

```bash
cass context /path/to/session.jsonl --json
```

Finds related sessions: same workspace, same day, same agent.

```json
{
  "related_sessions": [...],
  "same_workspace": 12,
  "same_day": 8,
  "same_agent": 15
}
```

---

## Timeline [MEDIUM freedom]

```bash
cass timeline --since 2026-01-14 --until 2026-01-17 --workspace /path --json
cass timeline --since 7d --json
```

**Prefer aggregations** — more predictable JSON:
```bash
cass search "*" --workspace /path --aggregate date --limit 1 --json
```

---

## Pagination [LOW freedom]

```bash
# First page
cass search "KEYWORD" --json --robot-meta --limit 50 --request-id run-1

# Next page (use _meta.next_cursor)
cass search "KEYWORD" --json --robot-meta --limit 50 --cursor "eyJ..." --request-id run-1b
```

---

## Chained Searches [MEDIUM freedom]

```bash
# Step 1: Get sessions matching coarse filter
cass search "COARSE" --workspace /path --robot-format sessions > /tmp/sessions.txt

# Step 2: Search within only those
cass search "SPECIFIC" --sessions-from /tmp/sessions.txt --json --fields minimal

# Or via pipe:
cass search "COARSE" --robot-format sessions | cass search "SPECIFIC" --sessions-from -
```

---

## Output Schemas

### Search Response

```json
{
  "hits": [
    {
      "source_path": "/path/to/session.jsonl",
      "line_number": 42,
      "agent": "claude_code",
      "title": "First few words...",
      "score": 15.234,
      "created_at": "2026-01-16T10:30:00Z"
    }
  ],
  "total_matches": 125,
  "aggregations": {...}
}
```

### Field Presets

| Preset | Fields |
|--------|--------|
| `minimal` | source_path, line_number, agent |
| `summary` | source_path, line_number, agent, title, score |
| `full` | All fields including content |

---

## Exit Codes

| Code | Meaning | Action |
|------|---------|--------|
| `0` | Success | Continue |
| `1` | Error (index, query) | Check `cass status`, re-index |
| `2` | Invalid args, special chars | Quote query, simplify |

# Persistent Harness / Connector Exclusion

> **One-liner:** When a connector (e.g., `openclaw`, `chatgpt`) floods the index with low-value or looped sessions, persistently exclude it via `cass sources agents`. The setting survives across runs.

## Contents

- [The Three Subcommands](#the-three-subcommands)
- [Connector Slugs](#connector-slugs)
- [What Exclude Actually Does](#what-exclude-actually-does)
- [When to Use](#when-to-use)
- [Verifying](#verifying)
- [Manual sources.toml Edit (Fallback)](#manual-sourcestoml-edit-fallback)
- [Pitfalls](#pitfalls)

---

## The Three Subcommands

```bash
cass sources agents list --json
cass sources agents exclude <agent-slug>
cass sources agents exclude <agent-slug> --keep-indexed-data
cass sources agents include <agent-slug>
```

---

## Connector Slugs

`cass capabilities --json | jq '.connectors'` returns the canonical list. As of v0.3.6:

```
codex, claude_code, gemini, clawdbot, vibe, opencode, amp,
cline, aider, cursor, chatgpt, pi_agent, factory, openclaw,
kimi, copilot, copilot_cli, qwen, crush
```

Use those exact slugs. Aliases (`claude` → `claude_code`) are accepted but get normalized.

---

## What Exclude Actually Does

`cass sources agents exclude openclaw`:

1. Writes `disabled_agents = ["openclaw"]` to `~/.config/cass/sources.toml` (creating the file if absent)
2. Halts indexing of openclaw sessions on **future** scans, syncs, and watch cycles
3. By default **purges already-indexed openclaw data** from the local archive and rebuilds lexical search → reclaims space immediately
4. With `--keep-indexed-data`: leaves prior data alone, only blocks future ingestion

The setting survives upgrades, restarts, and machine reboots. To unset: `cass sources agents include openclaw`.

---

## When to Use

| Trigger | Action |
|---------|--------|
| One harness is producing 80% of the index volume with low-value content | `exclude` it |
| openclaw / vibe / experimental agent is looping | `exclude` immediately |
| You only care about Claude+Codex on this machine | `exclude` everything else |
| You're temporarily debugging that harness | `exclude --keep-indexed-data` so a re-include restores quickly |

---

## Verifying

```bash
# Current exclusions
cass sources agents list --json | jq '.disabled_agents'

# Confirm new sessions from excluded harness are skipped
cass index --json 2>&1 | grep -i "skipping excluded"

# Confirm searches no longer return excluded-agent hits
cass search "*" --aggregate agent --limit 1 --json | jq '.aggregations.agent.buckets'
# excluded slugs should be absent
```

---

## Manual sources.toml Edit (Fallback)

The `cass sources agents` subcommand landed in commit `82d8d70e` (2026-04-20). It is **not present in the v0.3.6 release binary** but is in source HEAD. If `cass sources agents` errors with "unrecognized subcommand 'agents'", you're on a build older than that commit — edit the config directly:

```toml
# ~/.config/cass/sources.toml
disabled_agents = ["openclaw", "vibe"]

[[sources]]
name = "..."
# ...
```

Then trigger a one-off cleanup of already-indexed data:
```bash
cass index --full --force-rebuild --json   # rebuilds excluding the disabled list
```

To check what version added the subcommand:
```bash
cd /dp/coding_agent_session_search && git log --oneline --all -- src/lib.rs | grep -i "agents\|disabled_agents" | head -5
```

---

## Pitfalls

- `disabled_agents` is **case-sensitive** in normalization. The CLI normalizes; manual edits should use lowercase slugs.
- Excluding an agent **does not delete the source files** on disk — only the indexed copies. The user can always re-include and re-index without data loss.
- If you exclude a harness whose sessions live in an indexed remote source (`cass sources sync`), the remote sessions are still rsync'd to disk; only the indexing step skips them. Use `cass sources remove --purge` to stop syncing entirely.
- The default purge-on-exclude triggers a lexical rebuild. On big corpora that's a 25s blocking step. Pass `--keep-indexed-data` if you want exclude to be instant.

# Schema Introspection & Robot-Mode Contracts

> **One-liner:** cass is **fully self-describing**. Every command, flag, response, and error code is queryable at runtime. Use this when the skill or your memory is uncertain.

## Contents

- [The Discovery Trinity](#the-discovery-trinity)
- [introspect Schema](#introspect-schema)
- [capabilities Schema](#capabilities-schema)
- [Robot Output Conventions](#robot-output-conventions)
- [Robot-Format Output Modes](#robot-format-output-modes)
- [Response `_meta` Fields](#response-_meta-fields)
- [Agent Self-Configuration Pattern](#agent-self-configuration-pattern)

---

## The Discovery Trinity

```bash
cass --robot-help                  # Top-level machine help
cass robot-docs <topic>            # Topic-scoped docs
cass introspect --json             # Full schema dump (commands + responses)
cass capabilities --json           # Static features + limits
```

### `robot-docs` Topics

```
guide       — Quickstart for automation
commands    — Every subcommand + arg
examples    — Copy-paste workflows
schemas     — Auto-generated response schemas
contracts   — Output stream conventions (stdout=data, stderr=diag)
```

If a topic returns "Could not parse arguments", that topic is unsupported in your installed cass version.

---

## introspect Schema

```bash
cass introspect --json | jq '{
  api_version,
  contract_version,
  commands: .commands | map(.name),
  responses: .response_schemas | keys
}'
```

Returns:
- `commands[]` — every command with `name`, `description`, `arguments[]`, `has_json_output`
- `arguments[]` per command — `name`, `description`, `arg_type` (flag/option), `value_type`, `required`, `default`, `enum_values`, `repeatable`
- `response_schemas` — declared field shapes for every JSON-emitting command
- `global_flags` — top-level flags valid for all subcommands

This is the source of truth — newer than any handwritten skill.

### Programmatic Discovery

```bash
# What commands have a JSON response?
cass introspect --json | jq '.commands[] | select(.has_json_output) | .name'

# Find commands that accept --workspace
cass introspect --json | jq '.commands[] | select(.arguments[]?.name == "workspace") | .name'

# What enum values does --mode accept?
cass introspect --json \
  | jq '.commands[] | select(.name == "search") | .arguments[] | select(.name == "mode") | .enum_values'
```

---

## capabilities Schema

```json
{
  "crate_version": "0.3.6",
  "api_version": 1,
  "contract_version": "1",
  "features": [
    "json_output", "jsonl_output", "robot_meta", "time_filters",
    "field_selection", "content_truncation", "aggregations",
    "wildcard_fallback", "timeout", "cursor_pagination",
    "request_id", "dry_run", "query_explain", "view_command",
    "status_command", "state_command", "api_version_command",
    "introspect_command", "export_command", "expand_command",
    "timeline_command", "highlight_matches"
  ],
  "connectors": [...],
  "limits": {
    "max_limit": 0,
    "max_content_length": 0,
    "max_fields": 50,
    "max_agg_buckets": 10
  }
}
```

`max_limit: 0` means **no enforced cap** (RAM-clamped at runtime). `max_*: 0` consistently means "uncapped".

### Version-Aware Patterns

`features[]` enumerates capabilities; output formats are NOT in `features[]` — they live in each subcommand's per-arg enum. `--robot-format` is **per-subcommand, not global** (`global_flags` only contains `db`, `robot-help`, `trace-file`, `quiet`, `verbose`, `color`, `progress`, `wrap`, `nowrap`).

```bash
# Probe a feature (real entry in features[])
HAS_AGG=$(cass capabilities --json | jq -r '.features | index("aggregations") != null')

# Probe a robot-format value for `cass search` specifically
cass introspect --json \
  | jq -r '.commands[]
            | select(.name=="search")
            | .arguments[]
            | select(.name=="robot-format")
            | .enum_values[]'
# json jsonl compact sessions toon
```

---

## Robot Output Conventions

```
stdout = data only (parseable by --json)
stderr = diagnostics, progress events, warnings
exit 0 = success
exit 1 = recoverable error (retry with different args)
exit 2 = invalid args / contract violation
```

Always `2>/dev/null` when you need clean JSON on stdout, **unless** you're consuming progress events from stderr (during indexing).

---

## Robot-Format Output Modes

```bash
--robot-format json       # default; pretty-printed
--robot-format jsonl      # one event per line; streams big result sets
--robot-format compact    # single-line JSON; smallest token cost
--robot-format sessions   # one source_path per line; pipe into `cass search --sessions-from -`
--robot-format toon       # token-optimized object notation (saves ~30% vs JSON)
```

### Chained Searches via `sessions` format

```bash
# Step 1: get sessions matching a coarse filter
cass search "auth" --workspace /repo --robot-format sessions > /tmp/auth-sessions.txt

# Step 2: search within only those sessions
cass search "JWT" --sessions-from /tmp/auth-sessions.txt --json --fields minimal

# Or pipe directly:
cass search "auth" --robot-format sessions | cass search "JWT" --sessions-from -
```

Two-pass is a 10x speedup vs one big query when your filter is narrow.

---

## Response `_meta` Fields

When you pass `--robot-meta`, every search response gets:

```json
"_meta": {
  "elapsed_ms": 42,
  "wildcard_fallback": false,
  "cache_stats": {"hits": 12, "misses": 3, "shortfall": 0},
  "tokens_estimated": 850,
  "max_tokens": 1200,
  "next_cursor": "eyJ...",
  "hits_clamped": false,
  "fallback_mode": null,           // "lexical" if --mode hybrid degraded
  "index_freshness": {
    "fresh": true,
    "age_seconds": 122,
    "stale": false,
    "last_indexed_at": "2026-04-22T19:45:06Z",
    "pending_sessions": 0
  },
  "state": {"index": "...", "database": "..."},
  "request_id": "run-1"
}
```

`_warning` (top-level) is set when the index is stale enough to cast doubt on results. Always check it; surface to the user verbatim.

---

## Agent Self-Configuration Pattern

Use introspection to auto-tune behavior to whatever cass version is installed:

```bash
caps=$(cass capabilities --json)
intro=$(cass introspect --json)

VERSION=$(jq -r '.crate_version' <<< "$caps")
HAS_HYBRID=$(jq -r '.features | index("hybrid_search") != null' <<< "$caps")
SEARCH_FIELDS=$(jq -r '.commands[] | select(.name=="search") | .arguments[] | select(.name=="fields") | .description' <<< "$intro")

echo "Running cass $VERSION; hybrid=$HAS_HYBRID; fields-help=$SEARCH_FIELDS"
```

This way a single skill file works across cass versions — the agent adapts.

# Health, Status, and Index Freshness

> **One-liner:** cass exposes three overlapping health surfaces. Knowing which to use prevents the #1 mistake (treating "stale" as "broken").

## Contents

- [The Four Commands](#the-four-commands)
- [Status Schema (the one you'll actually parse)](#status-schema-the-one-youll-actually-parse)
- [The Three States, Read Off Status](#the-three-states-read-off-status)
- [NDJSON Progress on stderr](#ndjson-progress-on-stderr)
- [Authoritative Fallback and Concurrent Read Latency](#authoritative-fallback-and-concurrent-read-latency)
- [Liveness Stack](#liveness-stack)
- [Capabilities Self-Check](#capabilities-self-check)

---

## The Four Commands

| Command | Latency | Output | Best For |
|---------|---------|--------|----------|
| `cass health` | <50ms | Exit code 0/1 | Pre-flight gating in hooks/cron |
| `cass status --json` | ~100-700ms | Full JSON | Branching agent logic |
| `cass diag --json` | ~500ms-2s | Path/size diagnostics | Bug reports, deep triage |
| `cass capabilities --json` | <10ms | Static feature list | Version-aware fallbacks |

`status` and `state` are aliases for the same command.

---

## Status Schema (the one you'll actually parse)

```json
{
  "status": "healthy|unhealthy|rebuilding|initializing",
  "healthy": true,
  "initialized": true,
  "explanation": "...",            // null when healthy
  "recommended_action": "...",     // null when nothing to do

  "index": {
    "exists": true,
    "status": "fresh|stale|missing|rebuilding",
    "fresh": true,
    "stale": false,
    "age_seconds": 1234,
    "stale_threshold_seconds": 1800,
    "rebuilding": false,
    "documents": 51214,
    "fingerprint": {
      "current_db_fingerprint": "content-v1:51214:51214:4711459",
      "checkpoint_fingerprint": "content-v1:51214:51214:4711459",
      "matches_current_db_fingerprint": true
    },
    "checkpoint": {
      "present": true,
      "completed": true,
      "db_matches": true,
      "schema_matches": true,
      "page_size_compatible": true
    }
  },

  "database": {
    "exists": true,
    "opened": true,
    "conversations": 4827,
    "messages": 664027,
    "open_error": null,
    "open_retryable": false,
    "counts_skipped": false
  },

  "pending": {
    "sessions": 0,
    "watch_active": true,
    "orphaned": false
  },

  "rebuild": {
    "active": true,
    "orphaned": false,
    "pid": 3472773,
    "mode": "incremental",
    "job_id": "lexical_refresh-...",
    "job_kind": "lexical_refresh",
    "phase": "indexing",
    "started_at": "2026-04-22T20:18:45Z",
    "updated_at": "2026-04-22T20:21:09Z",
    "processed_conversations": 12,
    "total_conversations": 145,
    "indexed_docs": 410
  },

  "semantic": {
    "status": "missing|partial|installed",
    "available": false,
    "can_search": false,
    "fallback_mode": "lexical",
    "preferred_backend": "fastembed",
    "embedder_id": "minilm-384",
    "hint": "Run 'cass models install'..."
  },

  // active_index appears ONLY while a rebuild is running.
  // For the always-present pid/phase, read .rebuild instead.
  "active_index": {
    "pid": 3472773,
    "data_dir": "/home/.../coding-agent-search",
    "db_path": "/home/.../agent_search.db",
    "started_at": "2026-04-22T20:18:45.804+00:00",
    "job_id": "lexical_refresh-...",
    "job_kind": "lexical_refresh",
    "phase": "index"
  }
}
```

---

## The Three States, Read Off Status

```bash
# Fresh & ready
.healthy=true && .index.fresh=true

# Stale-but-usable (most common — DON'T panic)
.healthy=false && .index.stale=true && .database.exists=true && .database.messages > 0

# Truly broken
.database.exists=false  # never indexed
   OR .database.open_error != null
   OR .index.documents=0 && .database.messages > 0
   OR .index.fingerprint.matches_current_db_fingerprint=false
```

### Decision Function (Bash)

```bash
cass_classify() {
  local s=$(cass status --json)
  local fresh=$(echo "$s" | jq -r '.index.fresh')
  local db_exists=$(echo "$s" | jq -r '.database.exists')
  local docs=$(echo "$s" | jq -r '.index.documents // 0')
  local msgs=$(echo "$s" | jq -r '.database.messages // 0')

  if [ "$fresh" = "true" ]; then
    echo "READY"
  elif [ "$db_exists" = "true" ] && [ "$msgs" != "0" ] && [ "$docs" != "0" ]; then
    echo "STALE_BUT_USABLE"
  else
    echo "BROKEN"
  fi
}
```

---

## NDJSON Progress on stderr

When you run `cass index --json`, **stderr** streams progress events:

```
{"event":"started","mode":"incremental","full":false}
{"event":"phase","phase":"preparing","elapsed_ms":6000}
{"event":"phase","phase":"indexing","total":145,"current":12,"elapsed_ms":12000,"rate_per_sec":1.0,"eta_seconds":133}
{"event":"completed","conversations":145,"elapsed_ms":25000}
```

Tune the cadence: `--progress-interval-ms 1000` (clamped 250–60000). Disable: `--no-progress-events` or `CASS_INDEX_NO_PROGRESS_EVENTS=1`.

**This is how you detect issue #196 (stuck indexing):** if `current` doesn't advance for >30s of progress events, kill and retry with `--full --force-rebuild`.

## Authoritative Fallback and Concurrent Read Latency

`cass index --json` names the requested mode, not a guarantee that every source
can be reconciled incrementally. The indexer may discover an incompatible or
incomplete derived checkpoint and expand into an authoritative rebuild across
the full conversation corpus. A suddenly large `.rebuild.total_conversations`
therefore describes the chosen recovery work; by itself it says nothing about
loss of the source session files.

The active writer can also make concurrent `status` and `search` calls slower
than the normal latency table above. Keep observations bounded and preserve the
difference between timeout, command failure, and an actual empty result:

```bash
status_rc=0
timeout 15 cass status --json > /tmp/cass-status.json || status_rc=$?
search_rc=0
timeout 30 cass search "QUERY" --json --fields minimal --limit 20 \
  > /tmp/cass-search.json || search_rc=$?

case "$status_rc" in
  0) jq '{index, rebuild}' /tmp/cass-status.json ;;
  124) echo 'status not observed within 15s' ;;
  *) echo "status failed with exit $status_rc" ;;
esac

case "$search_rc" in
  0) jq '{total_matches, hits}' /tmp/cass-search.json ;;
  124) echo 'search not observed within 30s (not a zero-hit result)' ;;
  *) echo "search failed with exit $search_rc" ;;
esac
```

When status succeeds, compare `.rebuild.updated_at` and
`.rebuild.processed_conversations` across bounded observations. Movement means
the authoritative run is progressing; let that single writer converge. If the
values do not move, follow the existing issue #196 recovery guidance. Never use
a timed-out read, a large rebuild total, or a temporary `rebuilding` state as a
claim that data was lost.

---

## Liveness Stack

Layer 1 — The Trinity:
```bash
cass health --json     # 50ms, exit-code only
cass status --json     # ~500ms, structured JSON
cass diag --json       # ~1-2s, paths/sizes/disk
```

Layer 2 — The Process:
```bash
# .rebuild is always present (active=false when idle); .active_index appears only during a run
cass status --json | jq '{rebuild, active_index: (.active_index // null)}'
PID=$(cass status --json | jq -r '.rebuild.pid // empty')
[ -n "$PID" ] && ps -p "$PID" || echo "no rebuild running"
```

Layer 3 — Observability hooks:
```bash
cass --trace-file /tmp/cass-trace.jsonl search "X" --json   # span timing
```

---

## Capabilities Self-Check

Before issuing a flag your agent isn't sure exists, gate on `capabilities`:

```bash
HAS_HYBRID=$(cass capabilities --json | jq -r '.features | index("hybrid_search") != null')
if [ "$HAS_HYBRID" = "true" ]; then
  cass search "X" --mode hybrid --json
else
  cass search "X" --json   # fall back to lexical
fi
```

`features[]` enumerates: `json_output, jsonl_output, robot_meta, time_filters, field_selection, content_truncation, aggregations, wildcard_fallback, timeout, cursor_pagination, request_id, dry_run, query_explain, view_command, status_command, state_command, api_version_command, introspect_command, export_command, expand_command, timeline_command, highlight_matches, ...`.

Limits live in `limits{max_limit, max_content_length, max_fields, max_agg_buckets}`. `max_limit=0` means "no enforced cap" (clamped at runtime by RAM).

# Encrypted Archives & HTML Export

> **One-liner:** `cass export-html` makes one shareable, optionally-password-protected HTML file. `cass pages` makes a fully-encrypted searchable archive that can be hosted on GitHub Pages with no server.

## Contents

- [HTML Export (One Session, Easy)](#html-export-one-session-easy)
- [Pages — Encrypted Searchable Archive](#pages--encrypted-searchable-archive-many-sessions-static-hosting)
- [Disaster Recovery](#disaster-recovery)
- [When to Use Which](#when-to-use-which)
- [Pitfalls](#pitfalls)

---

## HTML Export (One Session, Easy)

```bash
# Plain HTML
cass export-html /path/to/session.jsonl -o /tmp/session.html

# Password-protected (AES-256-GCM, PBKDF2 600k iter)
cass export-html /path/to/session.jsonl -o /tmp/session.html --password "use-strong-passwords"

# Read password from stdin to keep it out of shell history
read -rs PW && cass export-html /path/to/session.jsonl -o /tmp/session.html --password-stdin <<< "$PW"
```

The output is a **single self-contained HTML file**:
- Inlined CSS / JS, opens offline
- Tailwind + Prism enhanced via CDN when online (graceful degrade)
- Markdown rendering, syntax highlighting, role-colored bubbles

Use case: hand a teammate "the conversation that solved X" as one file, no installation needed.

---

## Pages — Encrypted Searchable Archive (Many Sessions, Static Hosting)

```bash
cass pages encrypt ~/.local/share/coding-agent-search/agent_search.db \
  --output /tmp/cass-archive \
  --with-recovery
```

This produces a directory:
```
cass-archive/
├── config.json           # key slots, payload metadata
├── payload/
│   ├── chunk-00000.bin   # AES-256-GCM encrypted, content-addressed
│   ├── chunk-00001.bin
│   └── ...
├── search/               # client-side search index
└── viewer/               # static HTML+JS viewer
```

Drop the whole directory under any static host (GitHub Pages, S3, Netlify). Visitors authenticate in the browser with the password (or recovery key) and get a fully searchable view of the corpus.

### Key Architecture

| Layer | Crypto |
|-------|--------|
| Per-slot KEK from password | Argon2id (64MB, 3 iter, parallelism 4) |
| Per-slot KEK from recovery secret | HKDF-SHA256 |
| Wrapped DEK | AES-256-GCM |
| Payload chunks | AES-256-GCM, per-chunk nonce |

### Multi-Slot Operations

```bash
cass pages key list --archive ./archive
cass pages key add-password --archive ./archive
cass pages key add-recovery --archive ./archive
cass pages key revoke --archive ./archive --slot 1
cass pages key rotate --archive ./archive --keep-recovery
cass pages key show-recovery --archive ./archive --qr   # printable backup
```

Constraints:
- Cannot revoke the only remaining slot
- Cannot revoke the slot you're authenticating with
- Revoked slot IDs are never reused

### Verification

```bash
cass pages verify --archive ./archive --check-integrity
```

Validates that all files in `config.json` exist and SHA-256 hashes match `integrity.json`.

---

## Disaster Recovery

| Scenario | Move |
|----------|------|
| Forgot password, have recovery key | `cass pages decrypt ./archive --recovery` |
| Corrupted `config.json` | Restore from backup (no backup = unrecoverable) |
| Corrupt payload chunks | `cass pages verify --archive ./archive` to identify; restore from backup |
| Need to share access | `cass pages key add-password` (requires existing auth first) |

Full recovery procedures: see source-of-truth at `/dp/coding_agent_session_search/docs/RECOVERY.md`.

---

## When to Use Which

| Goal | Tool |
|------|------|
| Share one conversation | `cass export-html --password` |
| Publish a redacted corpus on GitHub Pages | `cass pages encrypt --with-recovery` |
| Internal team archive | `cass pages` + corp SSO at the storage layer |
| Estate-planning backup of work history | `cass pages` + recovery key in safe deposit box |
| Quick markdown handoff | `cass export FILE --format markdown -o /tmp/x.md` (no encryption) |

---

## Pitfalls

- `cass pages encrypt` indexes the entire DB. For a 4M-message corpus expect 5–15 min and ~1.5x DB size in chunks.
- The static viewer requires JavaScript and ~50ms of in-browser key derivation per session load — slow on low-end devices.
- Recovery keys provide **full access**. Treat them like the password — print + safe deposit box, not in email.
- Never use `--password` with the literal password on the command line in a shared shell — use `--password-stdin` or password manager integration. Shell history leaks.
- `cass export` (markdown/json) is **plaintext**. Use `cass export-html --password` if confidentiality matters.

# jq Extraction Patterns

> **Copy-paste reference** for parsing cass output and raw session files.

## Contents

- [Quick Reference Card](#quick-reference-card)
- [cass Search Output](#cass-search-output)
- [Pattern Detection](#pattern-detection)
- [Raw Session File Parsing](#raw-session-file-parsing)
- [Tool Call Extraction](#tool-call-extraction)
- [Subagent Prompt Extraction](#subagent-prompt-extraction)
- [Safe Access Patterns](#safe-access-patterns)
- [Composite Recipes](#composite-recipes)
- [Debugging jq](#debugging-jq)
- [One-Liners for Common Tasks](#one-liners-for-common-tasks)

---

## Quick Reference Card

| Goal | Pattern |
|------|---------|
| User prompts | Inspect source record roles; line positions and titles are not roles |
| Candidate subagent paths | `contains("subagent")`; verify native parent/child metadata |
| Total match count | `.total_matches` |
| Safe access with default | `// []` or `// "default"` |
| Sort descending | `sort_by(-.field)` |
| Group and count | `group_by(.) \| map({key: .[0], count: length})` |
| Claude Code user message | `.type == "user"` |
| Codex/Gemini user message | `.role == "user"` |
| Tool call | `.type == "tool_use"` |

---

## cass Search Output

### Basic Hit Extraction

```bash
# First 5 hits
| jq '.hits[0:5]'

# Just source paths (for follow-up)
| jq '.hits[].source_path' -r

# Path, line number, title
| jq '[.hits[] | {path: .source_path, line: .line_number, title: .title[0:80]}]'

# Total match count
| jq '.total_matches'
```

### User Prompt Extraction

Search hits locate candidates; they are not a role filter. Use the returned
path and line with bounded `cass pack`, `view` or `expand`, then identify the
role from the actual record. Early lines can be metadata or assistant content,
and user messages can occur anywhere. Verify that the returned path/line
matches the requested hit; missing files, absent roles and clamped windows
remain retrieval gaps.

```bash
cass search "KEYWORD" --workspace /path --mode lexical --json --fields minimal --limit 20
cass view /path/from/hit.jsonl -n LINE -C 3 --json
cass expand /path/from/hit.jsonl --line LINE --context 3 --json
```

See [Raw Session File Parsing](#raw-session-file-parsing) for role-based
examples over an already selected, authorized excerpt. A title count is not a
count of user prompts.

### Subagent Session Extraction

```bash
# Find subagent sessions
| jq '[.hits[] | select(.source_path | contains("subagent"))]'

# Just paths (unique)
| jq '[.hits[] | select(.source_path | contains("subagent"))] | .[].source_path' -r | sort -u

# Candidate locations to inspect for native roles
| jq '[.hits[] | select(.source_path | contains("subagent")) | {source_path, line_number}]'
```

### Aggregation Parsing

```bash
# Agent breakdown
cass search "*" --workspace /path --aggregate agent --limit 1 --json \
  | jq '.aggregations.agent.buckets'

# Date breakdown
cass search "*" --workspace /path --aggregate date --limit 1 --json \
  | jq '.aggregations.date.buckets'

# Formatted timeline
| jq '.aggregations.date.buckets | sort_by(.key) | .[] | "\(.key): \(.count) hits"' -r

# Multiple aggregations
| jq '{agents: .aggregations.agent.buckets, dates: .aggregations.date.buckets}'
```

---

## Pattern Detection

### Find Recurring Candidate Titles

```bash
# Count titles within this limited hit set; retain locations for review.
cass search "KEYWORD" --workspace /path --json --fields summary --limit 50 \
  | jq '[.hits[] | {title, source_path, line_number}]
    | group_by(.title)
    | map({title: .[0].title, hit_count: length, locations: .})
    | sort_by(-.hit_count) | .[0:20]'
```

Repeated titles can represent multiple hits in one session, copied text or
retries. They do not establish distinct prompt counts, user roles or success.
Inspect a selected candidate's intent, outcome and corrections before reuse.
Rare failures and scope decisions can matter even when the count is one.

---

## Raw Session File Parsing

Prefer CASS pack/view/expand. These examples apply only to an already selected,
authorized and bounded native excerpt named `excerpt.jsonl`, when a demonstrated
precision gap requires raw records. Never run them over an entire session by
default. The [source-format reference](SESSION_FORMATS.md) owns harness details;
unknown formats remain unknown.

### Claude Code Format

```bash
# Extract user messages
jq 'select(.type == "user") | .message.content' excerpt.jsonl

# Handle content arrays (common)
jq 'select(.type == "user") | .message.content | if type == "array" then [.[] | select(.type == "text") | .text] | join(" ") else . end' excerpt.jsonl

# With timestamps
jq 'select(.type == "user") | {ts: .timestamp, content: .message.content}' excerpt.jsonl

# First user record in this excerpt (not necessarily the session opener)
jq -s '[.[] | select(.type == "user")][0] | .message.content' excerpt.jsonl

# All user messages sorted
jq -s '[.[] | select(.type == "user")] | sort_by(.timestamp)' excerpt.jsonl
```

### Flat Codex/Gemini Format

```bash
# Extract user messages
jq 'select(.role == "user") | .content' excerpt.jsonl

# With timestamp
jq 'select(.role == "user") | {ts: (.timestamp // .created_at), content}' excerpt.jsonl

# First user prompt
jq -s '[.[] | select(.role == "user")][0] | .content' excerpt.jsonl
```

### Current Codex Records

```bash
jq 'select(.type == "response_item" and .payload.type == "message" and .payload.role == "user")
  | {ts: .timestamp, content: .payload.content}' excerpt.jsonl
```

Inspect record shape before selecting a parser. A metadata record at the start
cannot determine the role of subsequent messages. Avoid counting both a native
message and a duplicated event representation as separate user turns.

---

## Tool Call Extraction

### Find Tool Usage in Claude Code

```bash
# All tool calls
jq 'select(.type == "assistant") | .message.content[] | select(.type == "tool_use") | {name, input}' excerpt.jsonl

# Specific tool (e.g., Write)
jq 'select(.type == "assistant") | .message.content[] | select(.type == "tool_use" and .name == "Write")' excerpt.jsonl

# Tool results
jq 'select(.type == "tool_result")' excerpt.jsonl

# Count tool calls by type
jq -s '[.[] | select(.type == "assistant") | .message.content[]? | select(.type == "tool_use") | .name] | group_by(.) | map({tool: .[0], count: length}) | sort_by(-.count)' excerpt.jsonl
```

---

## Subagent Prompt Extraction

Use the selected hit's locator, not a fixed line number. A subagent filename is
a discovery clue; confirm native identity and relationships before attribution.

```bash
cass view /path/to/subagents/agent-XXXXX.jsonl -n LINE -C 3 --json
cass expand /path/to/subagents/agent-XXXXX.jsonl --line LINE --context 3 --json
```

Verify the record role and returned locator. Then apply the appropriate
role-based parser to a selected authorized excerpt if necessary.

---

## Safe Access Patterns

### Avoid null Errors

```bash
# With default
| jq '.hits // []'
| jq '.aggregations.agent.buckets // []'
| jq '.total_matches // 0'

# Check before access
| jq 'if .hits | length == 0 then "no results" else .hits[0:5] end'

# Safe iterate
| jq '(.hits // [])[]'
```

### Check JSON Structure

```bash
# Top-level keys
| jq 'keys'

# First hit structure
| jq '.hits[0] | keys'

# Check field exists
| jq '.hits[0] | has("source_path")'
```

---

## Composite Recipes

### Bounded Evidence Pack

```bash
timeout 30 cass pack "KEYWORD" --workspace /path --mode lexical --json \
  --limit 20 --max-sessions 3 --max-evidence 6 --max-tokens 4000
```

Inspect selection and omission markers and actual returned locators. A citation
verification flag is not proof that the source still exists, that a requested
record was returned or that the excerpt establishes an outcome.

### Extract Conversation Flow from Session

```bash
jq -s '[.[] | {
  type: (.type // .role),
  ts: (.timestamp // .created_at),
  preview: (if .message then .message.content else .content end | tostring[0:100])
}]' excerpt.jsonl
```

### Find Sessions with Specific Tool Usage

```bash
cass search "Write" --workspace /path --json --fields minimal --limit 50 \
  | jq '[.hits[] | .source_path] | unique'
```

### Follow a Selected Hit

```bash
cass search "KEYWORD" --workspace /path --json --fields minimal --limit 20
# Select a relevant hit within the authorized source scope, then inspect it.
cass expand /path/from/selected-hit.jsonl --line LINE --context 3 --json
```

Do not bulk-open every returned path or assume the first user message is the
relevant prompt. Report missing or mismatched source records explicitly.

---

## Debugging jq

### The Golden Rule: Simplify Rather Than Debug

When a complex jq command fails silently or returns nothing:

**Don't:** Spend time debugging the complex filter.
**Do:** Simplify to basics, verify data exists, then rebuild.

```bash
# Complex filter fails silently:
| jq '[.hits[] | select(.source_path | contains("subagent"))] | ...'
# No output, no error. Now what?

# SIMPLIFY FIRST:
| jq '.hits | length'           # Do we have hits at all?
| jq '.hits[0]'                 # What does a hit look like?
| jq '.hits[0] | keys'          # What fields exist?

# THEN rebuild step by step
```

**Why this works:** The JSON structure varies slightly between cass versions. Complex filters compound errors. Simple filters reveal the actual structure.

### Build Up Incrementally

```bash
# Start simple
| jq '.hits[0:5]'

# Add projection
| jq '[.hits[] | {path: .source_path, line: .line_number}]'

# Add a candidate path filter
| jq '[.hits[] | select(.source_path | contains("subagent"))]'
```

### Check Intermediate Counts

```bash
| jq '.hits | length'                        # Total hits
| jq '[.hits[] | select(.source_path | contains("subagent"))] | length'  # After path filter
```

---

## One-Liners for Common Tasks

| Task | One-Liner |
|------|-----------|
| Candidate titles | `jq '[.hits[].title]'`; not role or outcome evidence |
| Source paths only | `jq '.hits[].source_path' -r` |
| Agent counts | `jq '.aggregations.agent.buckets'` |
| Date counts | `jq '.aggregations.date.buckets'` |
| First hit details | `jq '.hits[0]'` |
| Total matches | `jq '.total_matches'` |
| Unique titles | `jq '[.hits[].title] \| unique'` |
| Subagent paths | `jq '[.hits[] \| select(.source_path \| contains("subagent"))] \| .[].source_path' -r` |

# cass Pitfalls & Troubleshooting

> **Quick lookup:** Ctrl+F for your error message or symptom.

## Contents

- [Quick Diagnosis](#quick-diagnosis)
- [Index Problems](#index-problems)
- [Query Errors](#query-errors)
- [Output Problems](#output-problems)
- [Content Not Found](#content-not-found)
- [jq Problems](#jq-problems)
- [Diagnostic Workflow](#diagnostic-workflow)
- [Exit Codes](#exit-codes)
- [Pro Tips](#pro-tips)

---

## Quick Diagnosis

| Symptom | Likely Cause | Fix |
|---------|--------------|-----|
| 0 results but content exists | Workspace path mismatch | Use `--aggregate workspace` to find exact path |
| `--limit 0` panic | Invalid limit | Always use `--limit 1` minimum |
| Exit code 2 | Special characters in query | Quote query or use nearby anchor |
| Broken pipe on export | Piping large output | Export to file first with `-o` |
| Tool calls hidden | Missing flag | Add `--include-tools` to export |
| Stale results | Newer records may be missing | Search usable state now; refresh only if needed and authorized, with a time cap |
| jq returns null | Wrong field name | Use `jq 'keys'` to check structure |
| Can see in file, cass finds nothing | Content not indexed | Fallback to `rg` on raw file |

---

## Index Problems

### "Index is stale" / Missing Recent Sessions

```bash
cass status --json              # Check state
# Search stale-but-usable state now; record its freshness.
# Optional only when needed and authorized:
timeout 600 cass index --json
# Persistent staleness alone does not justify a full rebuild.
```

### Index Shows 0 Conversations

```bash
# Find session files
find ~/.claude/projects -name "*.jsonl" | head -5

# Full rebuild
cass index --full --json

# Check capabilities
cass capabilities --json
```

### Database Corruption

```bash
cass doctor    # Safe repair — won't delete source sessions
cass index --full --json
```

---

## Query Errors

### `--limit 0` Panic

```bash
# WRONG:
cass search "*" --workspace /path --aggregate agent --limit 0 --json

# RIGHT:
cass search "*" --workspace /path --aggregate agent --limit 1 --json
```

### Workspace Path Mismatch (0 Results)

Paths must match exactly — case-sensitive, no trailing slash.

```bash
# Discover exact path:
cass search "your_keyword" --aggregate workspace --json
```

### Special Characters Fail

**Problem chars:** `--`, `|`, `"`, `'`, `*`, `?`, `\`

```bash
# Quote the term
cass search '"--fields"' --workspace /path --json

# Use nearby anchor without special chars
cass search "fields minimal" --workspace /path --json

# Escape in double-quotes
cass search "\"role\":\"user\"" --workspace /path --json
```

### Query With Leading Dashes Fails

```bash
# Wrap in quotes
cass search '"--workspace"' --workspace /path --json

# Or search without dashes
cass search "workspace /data" --workspace /path --json
```

---

## Output Problems

### Export Piping Causes Broken Pipe Panic

```bash
# WRONG (may panic):
cass export /path.jsonl --format json | head -100

# RIGHT:
cass export /path.jsonl --format json -o /tmp/out.json
jq '.[0:100]' /tmp/out.json
```

### Output Too Large

```bash
--fields minimal          # 5x smaller
--fields summary          # 2x smaller
--max-content-length 200  # Truncate snippets
--max-tokens 1200         # Soft cap
--aggregate date,agent    # Counts only
```

---

## Content Not Found

### String Exists But cass Returns 0 Hits

cass doesn't index everything. Large tool outputs (stdout/stderr) are skipped.

```bash
# Fallback to direct grep:
rg -n "the exact string" /path/from/source_path.jsonl
```

### Subagent Content Not Found

Subagent sessions are separate files.

```bash
cass search "KEYWORD" --workspace /path --json --fields minimal \
  | jq '[.hits[] | select(.source_path | contains("subagent"))]'
```

---

## jq Problems

### jq Returns null

```bash
| jq 'keys'                    # Top-level keys
| jq '.hits[0] | keys'         # Hit structure
| jq '.hits // []'             # Safe access with default
```

### Complex Filter Fails Silently

**Simplify rather than debug:**

```bash
| jq '.hits | length'          # Do we have hits?
| jq '.hits[0]'                # What does a hit look like?
| jq '.hits[0] | keys'         # What fields exist?
```

---

## Diagnostic Workflow

When cass isn't working:

```bash
# 1. Health check
cass status --json

# 2. Refresh index
cass index --json

# 3. Diagnostics
cass diag --json

# 4. Simple query test
cass search "*" --workspace /path --limit 5 --json

# 5. Check workspace paths
cass search "test" --aggregate workspace --json

# 6. Fallback to raw grep
rg -n "exact string" /path/to/session.jsonl
```

### Timestamp Reality Check

```bash
cass search "*" --workspace /path --aggregate date --limit 1 --json \
  | jq '.aggregations.date.buckets | sort_by(.key) | reverse | .[0]'
# Should show today's date if you've been working today
```

---

## Exit Codes

| Code | Meaning | Action |
|------|---------|--------|
| `0` | Success | Continue |
| `1` | Error (index, query) | Check `cass status`, review query |
| `2` | Invalid args, special chars | Quote query, simplify, check flags |

---

## Pro Tips

### Parallel Searches Find More

Lexical matching is literal. Different phrasings = different hits.

```bash
cass search "cass search" --workspace /path --json --fields minimal &
cass search "aggregate" --workspace /path --json --fields minimal &
cass search "line_number" --workspace /path --json --fields minimal &
wait
```

Together = full coverage.

# Example Discovery Prompts

> Adapt these examples to an authorized source scope and a bounded question. Reuse counts do not establish success; inspect source roles, outcomes and corrections.

## Contents

- [Discovery Openers](#discovery-openers)
- [Compile-A-File Prompts (Aggregation Tasks)](#compile-a-file-prompts-aggregation-tasks)
- [Subagent Mining](#subagent-mining)
- [Cross-Machine Recall](#cross-machine-recall)
- ["What Worked Last Time?"](#what-worked-last-time)
- [Decision Archaeology](#decision-archaeology)
- [Recurring Candidates](#recurring-candidates)
- [Cost & Usage Reports](#cost--usage-reports)
- [Sentinel Phrases (Triggers for /cass)](#sentinel-phrases-triggers-for-cass)
- [Anti-Templates](#anti-templates)

---

## Discovery Openers

```
read AGENTS.md and use /cass to find the session history with codex for this project
```

```
Use /cass to search session history for context on issues that were closed but never actually fixed.
```

```
i distinctly recall making a project called <NAME> ; can you look on /cass for what happened with it
```

```
read AGENTS.md ; /cass-session-search use cass to see how I used <TOOL> for <PROJECT>
```

```
Reread AGENTS.md so it's still fresh in your mind. Use /cass to search the project sessions history for ...
```

---

## Compile-A-File Prompts (Aggregation Tasks)

```
read AGENTS.md. I need you to use /cass to compile a file LIST_OF_INPUT_MESSAGES.md that contains all the user prompts for project X, in chronological order.
```

```
Use cass to extract every "first read ALL of AGENTS.md" prompt across this workspace and group by week.
```

---

## Subagent Mining

```
Use cass to find up to three relevant subagent sessions in the last 30 days
where the prompt mentions <TASK>. Verify the message roles and native
relationships; show cited excerpts and disclose missing or mismatched sources.
```

Implementation:
```bash
cass search "<TASK>" --workspace /path --days 30 --mode lexical --json --fields minimal --limit 20
cass pack "<TASK>" --workspace /path --days 30 --mode lexical --json \
  --limit 20 --max-sessions 3 --max-evidence 6 --max-tokens 4000
# Follow a selected candidate's actual locator; there is no fixed prompt line.
cass expand /path/from/selected-hit.jsonl --line LINE --context 3 --json
```

---

## Cross-Machine Recall

```
Search cass on css, csd, ts1, and ts2 for any mention of <KEYWORD> and dedup by source_path.
```

(For execution see SKILL.md → "Cross-Machine Search" or the `REMOTE_SOURCES.md` reference, Approach C — load it explicitly with the Read tool when you need the full recipe.)

---

## "What Worked Last Time?"

```
Use cass to find a recent run of <TASK>. Inspect intent, outcome and later
corrections before calling it successful. Show enough source context to judge
whether it applies now; only resume a verified native session when requested.
```

```bash
cass pack "<TASK>" --workspace /repo --mode lexical --json \
  --limit 20 --max-sessions 3 --max-evidence 6 --max-tokens 4000
```

A relevance-ranked first hit is not necessarily recent or successful. Check
returned timestamps and source records. Use [RESUME.md](RESUME.md) only for a
selected resume request.

---

## Decision Archaeology

```
When did we decide NOT to support <X>? Use cass with terms like "EXCLUDE", "out of scope", "skip for now".
```

```
Find the earliest session where we discussed adopting <LIBRARY>, and the conversation that finalized the choice.
```

---

## Recurring Candidates

```
Within this project, find recurring prompts relevant to <TASK>. Review up to
three episodes for intent, outcome and corrections. Include a competing
explanation or counterexample; do not infer success from repetition.
```

```bash
cass search "<TASK>" --workspace /path --mode lexical --json --fields summary --limit 20
```

See [PATTERNS.md](PATTERNS.md#pattern-detection) for limited hit counts. Titles
and repeated indexed hits are not counts of distinct user messages. Check native
roles and observed results before proposing reuse; rule changes need separate
authority and later task evidence is needed to establish usefulness.

---

## Cost & Usage Reports

```
What did I spend on Claude API across all projects last month? Break down by model.
```

```bash
# Per-model token totals (`cass analytics tokens` is time-only; use `models` for per-model)
cass analytics models --json | jq '.data.by_api_tokens.rows[0:10]'
```

```
Which agent is doing most of the tool-calling? Pull the top 10 over the last 60 days.
```

---

## Sentinel Phrases (Triggers for /cass)

These literal phrases are reliable triggers for the skill in this user's vocabulary:

- "Use /cass to ..."
- "use cass to find ..."
- "look on /cass for ..."
- "session history" + "<TASK>"
- "find that prompt"
- "what did I ask"
- "scope archaeology"
- "what worked last time"

When the caller requests this work, use the [bounded discovery workflow](../SKILL.md#discovery-workflow) within the authorized scope. Ordinary work has no mandatory history step.

---

## Anti-Templates

These prompts trigger /cass but produce *poor* results — rewrite them before executing:

| Bad prompt | Why bad | Better |
|------------|---------|--------|
| "Search cass for everything about X" | unbounded; will return 10k hits | Add `--workspace /repo` and `--days 30` |
| "Find all sessions" | no filter; useless | Pick a keyword OR an aggregate (`--aggregate agent,date`) |
| "What's in the index?" | not actionable | `cass status --json` + `cass search "*" --aggregate workspace --limit 1 --json` |
| "Re-extract all my prompts" | an indexed sample does not prove full source coverage | Select a scope and budget; use CASS pack/view/expand and verify native roles, reporting unread or unavailable portions |

# Bounded raw source reads

Use installed CASS search/pack/view/expand first for discovery and cited excerpts.
Choose this optional AO route only for a demonstrated precision gap, such as
required raw tool-output bytes or a consumer's frozen-span requirement. A missing
original or mismatched locator remains a retrieval gap; raw extraction cannot
reconstruct unavailable source content. `ao session read-source`
returns explicit raw bytes after checking caller-selected policy; it does not
parse records or replace the existing `ao provenance mine-session` tool-call
contract. Raw bytes include prose, operator corrections, malformed records and
Unicode line/paragraph separators. If a later consumer parses JSONL, split on
the byte `\n`, not Unicode line boundaries, and retain rejected records in raw
coverage accounting.

## Select access before opening bytes

The caller independently supplies the expected native source/project, owner,
task, model and destination. Existing T05 configuration and its native BD 1.2.2
maintenance anchor must resolve successfully. The access-policy reference is an
identity, not permission by its presence. Missing or mismatched context denies
the read; no source content is included in the error.

The resolved `task_policy_ref` selects a `source-read-policy.v1` JSON document.
It binds the same source/project/owner/task/model/destination to exact canonical
file permissions and a measured output profile. The caller, not the source
record or a knowledge candidate, owns this document. For example, replacing
these illustrative identities and paths with the independently authorized ones:

```json
{
  "schema_version": "source-read-policy.v1",
  "source_id": "/native/tracker/.beads",
  "project_id": "native-project-id",
  "owner_scope": "selected-owner",
  "task_ref": "selected-task",
  "model_ref": "selected-model",
  "destination_ref": "selected-destination",
  "files": [
    {"path": "/authorized/source.jsonl", "content_scope": "already-cleared"}
  ],
  "output_profile": {
    "id": "caller-selected-measured-profile",
    "model_ref": "selected-model",
    "destination_ref": "selected-destination",
    "max_serialized_bytes": 2048,
    "observation_ref": "/protected/host-output-observation.json",
    "observation_sha256": "replace-with-the-actual-64-character-lowercase-sha256"
  }
}
```

The example size is illustrative, not a default or a universal safe limit.
Select a limit measured on the actual native tool-result surface and preserve
its observation bytes/digest. The reader verifies the selected observation's
integrity; it does not attest its truth or observe host delivery. Policy and
observation documents have a separate 1 MiB parser resource bound. No source
locator, task, model, destination or profile has an inferred public default.

Allowed `content_scope` values are `synthetic`, `already-cleared` and `restricted`.
Current T05 reports `access_enforcement: not_attested`; restricted source reads
are therefore unavailable. The first two scopes support explicitly authorized
mechanism checks only. A policy label, file permission or worktree cannot supply
the native runtime/OS and egress enforcement owned by T39.

## Read and continue the same frozen prefix

```sh
ao session read-source \
  --file /authorized/source.jsonl \
  --access-policy-ref /protected/access-policy.json \
  --source-id /native/tracker/.beads --project-id native-project-id \
  --owner-scope selected-owner --task-ref selected-task \
  --model-ref selected-model --destination-ref selected-destination \
  --consumer-root /consumer/checkout --native-directory /native/workspace \
  --start-byte 0 --max-bytes 64 --json
```

The first invocation freezes the observed file size as `captured_through`.
Continue with `--start-byte` equal to `next_byte`, and pair
`--through-byte` with `--expect-prefix-sha256` from that result. The expected
hash covers **all bytes in `[0, captured_through)`**, not just the previous
span. Appends after that boundary are allowed. Any changed prefix, including
only an operator correction between identical tool calls, invalidates it.

Pass the previous `file_before.identity` as `--expect-file-identity` to check
replacement across invocations, even when a new file has identical contents.
Without that expectation, the response explicitly says cross-invocation
replacement was not checked. Within each invocation the reader compares the
opened file identity with the path before/after reading, rejects short reads,
and hashes the frozen prefix again to detect concurrent changes. These are
observations, not an atomic snapshot or a lock against a malicious concurrent
writer. Native files remain authoritative; no new source/state store is created.

## Interpret output honestly

`source-read.v1` is one compact JSON document, including a trailing newline.
`start_byte`, `end_byte` and `next_byte` identify the returned half-open span.
`prefix_sha256` hashes the entire frozen prefix; `span_sha256` hashes exactly
the returned bytes. `bytes_base64` is reversible and authoritative. `text_view`
is separately labelled with `text_view_encoding`; invalid or split UTF-8 uses
a replacement view and must never replace the raw bytes for integrity.

The reader checks the **actual serialized document length**, including metadata,
base64 expansion, text escapes and newline. Oversize output emits no source
bytes unless the caller explicitly sets `--allow-oversize`; that override is
recorded and never establishes complete reading. `profile_bound_satisfied`
reports the size comparison, not delivery. JSON is the measured output format;
YAML is rejected rather than silently bypassing its size contract.

Every result reports `host_delivery: host-delivery-unverified`,
`semantic_processing: not-established` and `complete_reading: false`.
`serialized_bytes` records emitted document size, not what a tool wrapper
actually delivered. Preserve the native transcript's actual result and any
truncation/omission markers. Even a successful producer and an observed final
sentinel cannot prove the omitted middle was delivered or processed. T09 owns
later identity-bound coverage/acknowledgement verification; a head-and-tail
read still leaves the middle unread.

# Workflow Recipes

> **Priority:** Resolve a concrete uncertainty with cited intent, action and outcome evidence.

## Contents

| Recipe | When |
|--------|------|
| [Search Readiness](#search-readiness) | Observe state when needed |
| [Recurring Candidates](#recurring-candidates) | Investigate repeated prompts |
| [User Prompt Extraction](#user-prompt-extraction) | What did I ask? |
| [Subagent Mining](#subagent-mining) | Find extraction prompts |
| [Scope Archaeology](#scope-archaeology) | When did we decide X? |
| [Multi-Agent Analysis](#multi-agent-analysis) | Who did what? |
| [Timeline Construction](#timeline-construction) | What happened when? |
| [Session Clustering](#session-clustering) | Find related work |
| [Context Recovery](#context-recovery) | Where did forgotten context resurface? |
| [Artifact Origin Tracing](#artifact-origin-tracing) | When was this doc created? |
| [Meta-Pattern: cass-on-cass](#meta-pattern-cass-on-cass) | Find which cass queries worked |
| [Full Example](#full-example) | End-to-end workflow demo |

---

## Search Readiness

After source, task, model and destination authorization, search a healthy or
stale-but-usable index immediately. Record freshness; do not automatically
refresh, rebuild or add `--refresh`. If unavailable, report that state or use
[bounded recovery](RECOVERY.md) only when needed and authorized.

```bash
timeout 15 cass status --json
# Optional overview when useful to the question
timeout 30 cass search "*" --workspace /data/projects/PROJECT --mode lexical \
  --aggregate agent,date --fields minimal --limit 1 --json
```

---

## Recurring Candidates

**Goal:** Investigate a recurring prompt without assuming that repetition means
it worked. Search for a task-relevant phrase, then review selected episodes.

```bash
timeout 30 cass search "TASK PHRASE" --workspace /path --mode lexical \
  --json --fields summary --limit 20
timeout 30 cass pack "TASK PHRASE" --workspace /path --mode lexical --json \
  --limit 20 --max-sessions 3 --max-evidence 6 --max-tokens 4000
```

Compare the user intent, action, result and later corrections. Recurrence may
come from copied instructions, repeated failure or retries. Check a competing
explanation or counterexample before reuse; later task evidence is needed to
show usefulness. No count threshold promotes a prompt into a rule.

---

## User Prompt Extraction

**Goal:** Find what the user asked and preserve its actual source identity.

```bash
cass search "KEYWORD" --workspace /path --mode lexical --json --fields minimal --limit 20
# Use the selected hit's path and line, not a presumed session opener.
cass view /path/from/hit.jsonl -n LINE -C 3 --json
cass expand /path/from/hit.jsonl --line LINE --context 3 --json
```

User roles come from native message records, including nested harness fields.
Line numbers and titles are not role evidence. Confirm that the returned
locator matches the request; unknown roles, absent sources and clamped windows
remain gaps. Selected excerpts do not establish all prompts or chronology for
unread parts of a session.

---

## Subagent Mining

**Goal:** Inspect a relevant subagent prompt and its observed outcome.

```bash
cass search "TASK PHRASE" --workspace /path --json --fields minimal --limit 20 \
  | jq '[.hits[] | select(.source_path | contains("subagent")) | {source_path, line_number}]'
cass expand /path/from/selected-hit.jsonl --line LINE --context 3 --json
```

The filename is only a candidate filter. Verify the actual record role and
native parent/child metadata; the prompt is not guaranteed to occupy line 2.

---

## Scope Archaeology

**Goal:** Find where scope decisions were made.

### Exclusion Decisions

```bash
cass search "EXCLUDE" --workspace /path --json --limit 50
cass search "NOT porting" --workspace /path --json --limit 50
cass search "skip for now" --workspace /path --json --limit 50
cass search "out of scope" --workspace /path --json --limit 50
```

### Inclusion Decisions

```bash
cass search "we DO need" --workspace /path --json --limit 50
cass search "must include" --workspace /path --json --limit 50
cass search "actually necessary" --workspace /path --json --limit 50
```

### Scope Reduction

```bash
cass search "less invasive" --workspace /path --json --limit 50
cass search "simplify" --workspace /path --json --limit 50
cass search "reduce scope" --workspace /path --json --limit 50
```

---

## Multi-Agent Analysis

**Goal:** Understand which agent did which work.

```bash
# Overview by agent
cass search "*" --workspace /path --aggregate agent --limit 1 --json \
  | jq '.aggregations.agent.buckets'

# Search within specific agent
cass search "KEYWORD" --workspace /path --agent claude_code --json --limit 50
cass search "KEYWORD" --workspace /path --agent codex --json --limit 50

# Compare activity over time
cass search "*" --workspace /path --agent claude_code --aggregate date --limit 1 --json
```

### Agent Patterns

| Agent | Typical Work |
|-------|--------------|
| Claude Code (Opus) | Complex reasoning, architecture, specs |
| Codex | Fast extraction, high-volume, code gen |
| Gemini | Research, varied tasks |

---

## Timeline Construction

**Goal:** Build chronological understanding of work.

### Method 1: Date Aggregation (Recommended)

```bash
cass search "*" --workspace /path --aggregate date --limit 1 --json \
  | jq '.aggregations.date.buckets | sort_by(.key) | .[] | "\(.key): \(.count) hits"' -r
```

### Method 2: Timeline Command

```bash
cass timeline --since 2026-01-14 --until 2026-01-17 --workspace /path --json
cass timeline --since 7d --json
```

**Note:** Aggregations usually have simpler, more predictable JSON.

### Method 3: Manual Grouping

```bash
cass search "*" --workspace /path --json --limit 200 \
  | jq '[.hits[] | {date: .created_at[0:10], path: .source_path}] | group_by(.date) | .[] | {date: .[0].date, count: length}'
```

---

## Session Clustering

**Goal:** Discover candidate related work from one relevant hit.

```bash
# 1. Find one relevant session
cass search "KEYWORD" --workspace /path --json --fields summary --limit 5
# Get source_path

# 2. Discover related
cass context /path/from/hit.jsonl --json

# 3. Iterate over related_sessions
```

Related-session output is not a complete cluster or proof of native parentage.

---

## Context Recovery

**Goal:** Find where forgotten context was recovered (reveals what mattered).

```bash
cass search "we already DID" --workspace /path --json --limit 50
cass search "wait we already" --workspace /path --json --limit 50
cass search "I think we discussed" --workspace /path --json --limit 50
cass search "earlier session" --workspace /path --json --limit 50
cass search "use cass to find" --workspace /path --json --limit 50
```

---

## Artifact Origin Tracing

**Goal:** Find when/how specific documents were created.

### Find References to Spec Documents

```bash
cass search "PLAN_TO_PORT_" --workspace /path --json --fields summary
cass search "EXISTING_" --workspace /path --json --fields summary
cass search "PROPOSED_ARCHITECTURE" --workspace /path --json --fields summary
```

### Find Creation Prompts

```bash
cass search "create a spec" --workspace /path --json
cass search "document this" --workspace /path --json
cass search "write to file" --workspace /path --json
```

---

## Meta-Pattern: cass-on-cass

**Goal:** Find which cass queries worked.

```bash
cass search "cass search" --workspace /path --json --fields minimal
cass search "aggregate" --workspace /path --json --fields minimal
```

Repeated queries are candidates. Inspect the resulting hits and the task outcome; repetition alone may indicate failed searches.

---

## Full Example

```bash
# 1. Discover within a selected authorized workspace and bounded query family.
timeout 30 cass search "scope decision" --workspace /data/projects/PROJECT \
  --mode lexical --json --fields minimal --limit 20

# 2. Ask CASS for a small cited selection.
timeout 30 cass pack "scope decision" --workspace /data/projects/PROJECT \
  --mode lexical --json --limit 20 --max-sessions 3 --max-evidence 6 --max-tokens 4000

# 3. Follow a relevant returned locator and check native role/intent/outcome.
timeout 15 cass expand /path/from/selected-hit.jsonl --line LINE --context 3 --json
```

Retain query, filters, limit, freshness, selected locators and omissions. Missing
sources or mismatched returned locations are not repaired by assuming an indexed
snippet is the original record. Reuse only what the observed evidence supports;
a justified no-change or insufficient-evidence result is valid.

# Doctor & Bounded Authorized Recovery

> **The contract:** Select recovery only when needed and authorized for its sources, model, destination and derived-state writes. Healthy and stale-but-usable indexes can be searched immediately. A search-only request does not authorize refresh/rebuild; unknown status is not proof of corruption. Preserve source sessions and bound recovery commands with a wall-clock cap.

## Contents

- [When to Run Each Doctor Mode](#when-to-run-each-doctor-mode)
- [Output Schema (top-level keys, no `.summary` wrapper)](#output-schema-top-level-keys-no-summary-wrapper)
- [Real-World Recovery Recipes](#real-world-recovery-recipes)
- [What `--fix` Does NOT Do](#what---fix-does-not-do)
- [Disk Cleanup (ALWAYS ask first)](#disk-cleanup-always-ask-first)
- [Optional Recovery Invocation](#optional-recovery-invocation)

---

## When to Run Each Doctor Mode

```bash
cass doctor --json                       # Read-only diagnosis
cass doctor --json --verbose             # Show passed checks too
timeout 600 cass doctor --fix --json     # Apply selected authorized repairs
timeout 600 cass doctor --fix --force-rebuild --json # Force only for a diagnosed need
```

`--fix` runs a 7-step protocol:

1. **Data directory** — Create if missing
2. **Stale lock files** — Remove `.index.lock` if older than 1h
3. **Database open + quick_check** — Backup to `.corrupt.<ts>` and rebuild if quick_check fails
4. **FTS table** — Verify `fts_messages` is queryable via frankensqlite
5. **Tantivy index** — Rebuild from SQLite if empty/missing/stale
6. **Config files** — Validate `config.toml` and `sources.toml` parse
7. **Session directories** — Detect `~/.claude`, `~/.codex`, etc. for visibility

Backup format: `agent_search.db.corrupt.20260315_154822_759` (sortable timestamp). Corruption salvage is preserved for forensic review.

---

## Output Schema (top-level keys, no `.summary` wrapper)

```json
{
  "status": "healthy|unhealthy",
  "healthy": true,
  "initialized": true,
  "explanation": null,
  "recommended_action": null,
  "needs_rebuild": false,
  "issues_found": 0,
  "issues_fixed": 0,
  "warnings": [],
  "failures": [],
  "auto_fix_applied": false,
  "auto_fix_actions": [],
  "checks": [
    {"name": "database", "status": "pass|warn|fail",
     "message": "...", "fix_available": true, "fix_applied": false},
    ...
  ],
  "_meta": {...}
}
```

Parse `failures[]` (top-level array of failed check names) for blocking issues. Anything in `auto_fix_actions` happened automatically. **Do not look for a `.summary` key — it doesn't exist.**

```bash
timeout 600 cass doctor --fix --json | jq '{
  ok: .healthy,
  issues_found, issues_fixed,
  applied: .auto_fix_actions,
  failed: [.checks[] | select(.status=="fail") | .name]
}'
```

---

## Real-World Recovery Recipes

### Index empty but DB has rows

```bash
# Symptom
cass status --json | jq '.database.messages, .index.documents'
# 664027  0

# Fix
timeout 600 cass doctor --fix --json | jq '.auto_fix_actions'
# ["Rebuilt search index from database"]
```

### Database file unreadable

```bash
# Symptom: cass status returns counts_skipped=true and open_error
cass status --json | jq '.database.open_error'
# "database disk image is malformed"

# Fix
timeout 600 cass doctor --fix --json
# Backs up bad DB to .corrupt.<ts>, then rebuilds index from corrupt-salvage if possible
```

### Stale lock from crashed indexer

```bash
# Symptom: "Index rebuild is already in progress" but no cass process exists
ps -p $(cass status --json | jq -r '.active_index.pid // empty')
# (no such process)

# Fix (doctor handles >1h-old locks; for fresher locks, force it)
timeout 600 cass doctor --fix --force-rebuild --json
```

### Incremental index hangs at current:0 (OPEN issue #196)

```bash
# Workaround until fixed upstream
pkill -f "cass index"
timeout 600 cass index --full --force-rebuild --json
```

`cass status` keeps showing `rebuilding` after the kill? `cass doctor --fix` clears the run lock.

### Full rebuild "succeeds" then fails on `last_indexed_at` write (FIXED at HEAD as of 2026-04-22)

**Status:** Fixed by commit `e06342f2` (bead `coding_agent_session_search-zz8ni`, closed). Affects **v0.3.6 and earlier**. Once you're on a build that includes the fix, the rebuild reports `{"success": true}` and the missing-marker case logs a deferred-update warning instead of bubbling out as failure. The recovery recipe below remains valid as a workaround for older binaries.



**Symptom:** `cass index --full --force-rebuild --json` runs for 3–5 minutes processing all 51k+ docs, then exits with:

```json
{"success": false,
 "error": "index failed: updating last_indexed_at after index run ... database is busy",
 "code": 9, "kind": "index", "retryable": true}
```

**Diagnosis:** The index *data* committed successfully. Only `persist_final_index_run_metadata` (src/indexer/mod.rs:6295) lost the writer race against a concurrent cass process. `cass status` keeps reporting "stale" because the freshness marker never landed.

**Verify the index is actually good:**

```bash
cass search "common-term-from-your-corpus" --limit 1 --json --robot-meta \
  | jq '{total: .total_matches, fresh_at_query_time: ._meta.index_freshness.fresh}'
# total > 0 means the data is committed and queryable
```

**Fix without re-running the 5-minute rebuild:**

```bash
# Wait for any concurrent cass processes to settle
sleep 30
# A trivial incremental run is usually enough to land the timestamp
timeout 600 cass index --json
```

If a concurrent rebuild is still active (`cass status --json | jq '.rebuild.active'`), the timestamp will be written when it completes. Don't fight it.

**Root cause** (for future fixers): the `with_concurrent_retry` wrapper at line 6302 uses `begin_concurrent_retry_limit()` retries — under sustained contention from peer cass processes, all retries exhaust and the metadata write fails *after* the index data has already been committed. A graceful path would log a warning and return Ok rather than discarding the whole run's success.

---

## What `--fix` Does NOT Do

- **Delete source session files** (`~/.claude/projects/*.jsonl` etc.) — these are user data, never touched
- **Delete corrupt DB backups** — preserved as `.corrupt.<ts>` and `.salvage-<ts>.{sql,sqlite3}`
- **Modify `sources.toml`** — config changes require explicit `cass sources` commands
- **Re-download semantic models** — that requires `cass models install`
- **Cross network boundaries** — only operates on local data dir

When recovery is already authorized, run the selected bounded repair and report the result without asking again. Source preservation alone does not grant recovery scope or permission to read additional sources.

---

## Disk Cleanup (ALWAYS ask first)

The cass project dir can accumulate large artifacts after crashes:

```bash
# Surface what's eating disk; do not delete anything yourself
du -sh ~/.local/share/coding-agent-search/* | sort -hr
# Plus historical core dumps in /dp/coding_agent_session_search/core.NNNNN
```

Per the project rule **"NEVER delete a file without express permission"** (AGENTS.md), every deletion below requires explicit user approval — even backups you suspect are stale:

| File pattern | Why kept | Ask before deleting |
|--------------|----------|---------------------|
| `*.corrupt.<ts>` | Salvage source for past corruption | Yes |
| `*.salvage-<ts>.{sql,sqlite3}` | Forensic snapshot | Yes |
| `core.NNNNN` (multi-GB) | Debugging crashes | Yes |
| `agent_search.db.bak-*` | Manual backups | Yes |
| `agent_search.db` (active) | Live data | Always (and almost never) |

Surface the disk usage, list candidates with sizes/ages, and let the user decide. They have the context for what's safe.

---

## Optional Recovery Invocation

Do not install a search hook or start an index watcher as part of retrieval.
When recovery is needed and its full derived-state scope is already authorized,
inspect and invoke the existing helper:

```bash
# This may refresh a stale index or repair/rebuild derived state.
CASS_STATUS_TIMEOUT=15 CASS_REBUILD_TIMEOUT=600 ./scripts/recover.sh
```

The helper's individual index calls are capped. A stale usable index is still
searchable; refreshing is an optional selected operation, not a prerequisite.
If a status read is unavailable or an existing rebuild is progressing, retain
that uncertainty rather than stacking another repair. See
[OBSERVABILITY.md](OBSERVABILITY.md#authoritative-fallback-and-concurrent-read-latency).

# Remote Sources & Multi-Machine Search

> **One-liner:** `cass sources` lets you treat sessions on `css`, `csd`, `ts1`, `ts2`, etc. as part of your local searchable corpus. Three approaches, ordered by long-term value.

## Contents

- [Approach A — Configured Sources (preferred)](#approach-a--configured-sources-preferred)
- [Approach B — One-Shot SSH Query (no setup)](#approach-b--one-shot-ssh-query-no-setup)
- [Approach C — Parallel Fan-Out](#approach-c--parallel-fan-out-when-speed-matters)
- [Diagnostics](#diagnostics)
- [When to Use Which](#when-to-use-which)
- [Pitfalls](#pitfalls)

---

## Approach A — Configured Sources (preferred)

Persist remote machines so every `cass search` automatically spans them.

```bash
# 1. Discover SSH hosts and probe each one
cass sources discover --json
cass sources setup            # interactive wizard; auto-skips configured hosts

# 2. Or add manually
cass sources add ssh://ubuntu@css --name css --preset linux-defaults
cass sources add ssh://ubuntu@csd --name csd --preset linux-defaults
cass sources add ssh://ubuntu@ts1 --name ts1 --preset linux-defaults
cass sources add ssh://ubuntu@ts2 --name ts2 --preset linux-defaults

# 3. Sync (rsync remote → local + reindex)
cass sources sync --json                    # all sources
cass sources sync --source css --json       # one source
cass sources sync --dry-run --json          # preview only

# 4. Confirm
cass sources list --json
cass sources doctor --json                  # connectivity + path probe
```

After sync, `cass search` queries return hits with `origin_host: "css"` mixed in. Always preserve `origin_host` when reporting back to the user — it tells them which machine the prompt lives on.

### Source Schedule

```toml
# ~/.config/cass/sources.toml
[[sources]]
name = "css"
type = "ssh"
host = "css"
paths = ["~/.claude/projects", "~/.codex/sessions"]
sync_schedule = "manual"          # or "hourly", "daily"
platform = "linux"
```

### Path Mappings

When a workspace path differs between machines (e.g., `/home/user1/dp` ↔ `/data/projects`):

```bash
cass sources mappings list css --json
cass sources mappings add css --from /home/user1/dp --to /data/projects
```

Mapped paths are rewritten so `--workspace /data/projects/foo` matches both local and remote sessions.

---

## Approach B — One-Shot SSH Query (no setup)

Fastest path when you only need one query against one host.

```bash
ssh css 'cass search "KEYWORD" --json --fields minimal --limit 10' \
  | jq '[.hits[] | {host: "css", path: .source_path, line: .line_number}]'
```

Trade-off: every query incurs SSH latency (~300ms cold) + remote `cass` startup. Use Approach A for >3 queries per session.

---

## Approach C — Parallel Fan-Out (when speed matters)

Run identical query against the whole fleet simultaneously.

```bash
HOSTS="css csd ts1 ts2"
for h in $HOSTS; do
  ssh "$h" 'cass search "KEYWORD" --json --fields minimal --limit 20' > "/tmp/cass-$h.json" &
done
wait

# Merge + dedup (same source_path + line counts as the same hit)
jq -s '
  [.[] | .hits[] // empty]
  | unique_by(.source_path + ":" + (.line_number|tostring))
  | sort_by(-.score)
  | .[0:30]
' /tmp/cass-*.json
```

Use this when you don't want to write to local disk (`sources sync` writes ~tens of MB per host) or when you're ok with snapshot-in-time results.

---

## Diagnostics

```bash
cass sources list --verbose --json    # full config + sync state
cass sources doctor --source css --json
# Common failures:
#   - "host unreachable" → check ssh connectivity
#   - "remote cass not found" → ssh in and `install.sh`
#   - "rsync arg protection mismatch" → CLOSED issue #191; update macOS rsync to 3.4.1+

# Per-host probe (lightweight)
ssh css 'cass health --json'
```

---

## When to Use Which

| Need | Approach |
|------|----------|
| One query, exploratory | B (ssh one-shot) |
| Mining a project across the fleet over a session | A (configured sources) |
| Latency matters more than dedup | C (parallel fan-out) |
| Building cross-machine analytics | A + `cass analytics rebuild` after sync |

---

## Pitfalls

- `cass sources sync` rsyncs **session files**, not the index. Re-indexing happens automatically; if you pass `--no-index`, you must run `cass index --json` yourself.
- Path mappings rewrite *workspace* paths only. The `source_path` of remote hits still references the **remote** filesystem — pass back to the user verbatim, don't try to open them locally.
- Removing a source: `cass sources remove NAME --purge` deletes the synced data too. Without `--purge`, it just stops future syncs but keeps already-indexed sessions.
- If `sources doctor` reports paths as missing on macOS but they exist on the remote, that's CLOSED issue #190 — update cass past v0.3.1.

# Cross-Harness Session Resume

> **One-liner:** `cass resume PATH` resolves any indexed session into the exact command its native CLI uses to continue the conversation. Works across Claude Code, Codex, Gemini CLI, OpenCode, pi_agent.

## Contents

- [The Three Modes](#the-three-modes)
- [Per-Harness Behavior](#per-harness-behavior)
- [The Subagent Trap](#the-subagent-trap)
- [The Resume → Search Loop](#the-resume--search-loop)
- [When Resume Won't Work](#when-resume-wont-work)
- [What `cass resume` is NOT](#what-cass-resume-is-not)

---

## Authorization and startup evidence

Resolving a command does not authorize executing it. Before reading a source or
resuming, verify task/source-owner/model/provider/destination authorization and
that the caller selected this runtime operation. Cross-harness conversion sends
content to a new recipient and requires its own applicable authorization.

Before execution, pass source-store/project/work identity and permitted intent
locators, and have the caller record the dispatch/resume request in native
comments/metadata or runtime facts. Keep the requested predecessor separate
from the actual resumed context. At startup, record the selected runtime's
observed session/context ID and resume relation with observation provenance;
it may reuse an ID or create another context. Until observed, use explicit
unknowns. Command text, a filename and successful command resolution do not
prove that resumption occurred. Preserve failed starts and unresolved links
without waiting for handoff. Follow
[session associations](SESSION_FORMATS.md#work-to-session-associations) for
supported spans and available frozen source boundaries/digests; never transfer
all work associations from a predecessor automatically.

## The Three Modes

```bash
# 1. Print argv tokens, one per line (for the caller to wrap)
cass resume /path/to/session.jsonl
# claude
# resume
# 8efcc298-90d8-4764-9144-944c40f1a321

# 2. Emit a single shell-escaped command line
cass resume /path/to/session.jsonl --shell
# claude resume '8efcc298-90d8-4764-9144-944c40f1a321'
# Inspect the emitted command; execute only the caller-authorized native resume.

# 3. Replace the current process (mutually exclusive with --shell/--json)
cass resume /path/to/session.jsonl --exec
```

---

## Per-Harness Behavior

`cass resume` detects the harness from the file path and emits the **command its native CLI expects**. Don't memorize the argv shape — just read what `cass resume PATH --shell` prints.

| Detected Agent | Source path layout | --agent override |
|----------------|--------------------|------------------|
| Claude Code | `~/.claude/projects/<workspace>/<uuid>.jsonl` | `claude` / `claude-code` / `claude_code` |
| Codex | `~/.codex/sessions/<YYYY/MM/DD>/rollout-*.jsonl` | `codex` |
| OpenCode | `~/.opencode/...` | `opencode` |
| Gemini | `~/.gemini/...` | `gemini` |
| pi_agent (mono) | `~/.pi/...` | `pi_agent` / `pi-agent` (auto) or `pi` (force) |
| Oh My Pi | `~/.pi/...` | `omp` / `oh-my-pi` / `ohmypi` |

Override the auto-detected harness with `--agent`:

```bash
cass resume /weird/path.jsonl --agent claude   # force Claude Code resume form
cass resume /weird/path.jsonl --agent omp      # force Oh My Pi
```

---

## The Subagent Trap

Subagent files are **NOT resumable** — they're orchestrated by a parent session.

```bash
cass resume /home/x/.claude/projects/<ws>/subagents/agent-a0b4d4b58a1fd73da.jsonl --json
# {"error":{"code":5,"kind":"session_id_not_found",
#  "message":"filename stem 'agent-a0b4d4b58a1fd73da' does not look like a Claude Code session UUID (expected 8-4-4-4-12 hex)",
#  "hint":"Did you pass a project directory or notes file instead..."}}
```

Use `cass context` only to discover candidate sessions. Its `related` object
contains `same_workspace`, `same_day` and `same_agent` lists; their entries use
`.path`, not `.source_path`. These are similarity groups, not parent edges.

```bash
# Bounded candidate discovery for an authorized source; do not select a parent.
cass context /path/to/subagents/agent-XXXXX.jsonl --json
```

Verify parentage using an authorized native startup/dispatch observation or
explicit parent link in native runtime metadata, with its exact permitted
source locator. A dispatch-attested controller relation is distinct from a
native parent relation. The first non-subagent workspace hit, a matching title,
a filename or a guessed prompt line is never proof. If no link is observable,
record parent unknown and stop parent-based resume selection. Only after the
link is verified and the caller selects execution may `cass resume` target the
verified parent; do not erase the child's separate source/work association.

---

## The Resume → Search Loop

A common pattern: search for a past task, resume the agent that did it, hand off the next prompt.

```bash
# 1. Find the right past session
HIT=$(cass search "implement auth flow" --workspace /myrepo --json --fields summary --limit 1 \
       | jq -r '.hits[0].source_path')

# 2. Print the command without executing
cass resume "$HIT" --shell

# 3. Only after caller authorization and pre-execution association recording
cass resume "$HIT" --exec
```

Or for inspection only:

```bash
cass expand "$HIT" --line 1 --context 5    # see the original prompt
```

---

## When Resume Won't Work

| Symptom | Cause | Fix |
|---------|-------|-----|
| `session_id_not_found` for `agent-*.jsonl` | Subagent file | Discover candidates with `cass context`; verify a native parent link or leave parent unknown |
| `unknown harness` | Path doesn't match any connector layout | Pass `--agent` explicitly |
| Resumed session won't open | The native CLI was upgraded and changed its session schema | Try the harness's own `--list` to see if the ID is still valid; the source jsonl is your fallback |
| `cross_agent_session_resumer#9` style: Codex → Pi resumption broken | Cross-harness resume requires casr (separate tool) | Use the matching native CLI; cass resume only does *same-harness* |

---

## What `cass resume` is NOT

It is **not** a cross-CLI translator. Resuming a Codex conversation always uses the Codex CLI; Claude → Claude; etc. Genuine cross-CLI continuation is the job of `casr` (Cross Agent Session Resumer) — a separate upstream tool, not an AgentOps skill under `skills/` — while `cass resume` only does same-harness resume.

# Semantic & Hybrid Search

> **One-liner:** Lexical (BM25) is the default and is sufficient for >90% of agent queries. Enable semantic only when you don't know the exact wording.

## Contents

- [Decision Tree](#decision-tree)
- [Models — Three States](#models--three-states)
- [Building & Refreshing the Vector Index](#building--refreshing-the-vector-index)
- [Querying](#querying)
- [Background Backfill](#background-backfill)
- [Pitfalls](#pitfalls)

---

## Decision Tree

```
Need to find something?
│
├─ I know exact words / file names / IDs    → --mode lexical (default; do nothing)
├─ I want "things conceptually like X"       → --mode semantic   (needs MiniLM)
├─ Mix of both / not sure                    → --mode hybrid     (RRF combines results)
```

cass uses Reciprocal Rank Fusion for hybrid: `score = Σ 1 / (60 + rank_i)`. Top-of-list lexical hits stay near the top, but conceptually similar items the lexical index missed get surfaced.

---

## Models — Three States

```bash
cass models status --json | jq '{state, installed_size_bytes, total_size_bytes}'
```

| State | Meaning | Action |
|-------|---------|--------|
| `not_installed` | No model files; semantic falls back to **hash embedder** (lexical-overlap only) | `cass models install` to enable real semantic |
| `partial` | Some files present, others missing | `cass models verify` then re-install missing |
| `installed` | All files present and SHA256 verified | Use freely |

The hash embedder is **deterministic and instant** but only matches token overlap — it doesn't know "car ≈ automobile". For real semantic understanding you need the MiniLM bundle (~90MB).

### Install / Verify / Remove

```bash
cass models install                    # downloads from HuggingFace (default model)
cass models install --mirror <URL>     # use a different mirror (HF flaky on Windows / corp networks)
cass models install --from-file <DIR>  # air-gapped: install from a pre-downloaded model dir
cass models verify                     # SHA256 check, no network
cass models remove -y                  # frees ~90MB; semantic falls back to hash
cass models check-update               # see if a newer model rev exists
```

If `cass models install` fails on Windows with WSAENOTCONN (closed issue #193), retry once. If still failing, use `--mirror` to switch endpoints or `--from-file` with a model dir you copied from a working host. The required files are listed in the README's Semantic Search section.

---

## Building & Refreshing the Vector Index

```bash
# After install, build the FSVI vector index
cass index --semantic --json

# Add HNSW for O(log n) approximate search (recommended for >10k sessions)
cass index --semantic --build-hnsw --json

# Subsequent runs are incremental
cass index --semantic --json     # only new conversations get embedded
```

The vector index lives at `~/.local/share/coding-agent-search/vector_index/index-minilm-384.fsvi`. It's memory-mapped — opening a 1GB index doesn't read 1GB into RAM.

---

## Querying

```bash
# Lexical (default; fastest)
cass search "tantivy index" --mode lexical --json

# Semantic (requires --semantic-built index OR falls back to hash)
cass search "ways to make search faster" --mode semantic --json

# Hybrid (best for "I'll know it when I see it")
cass search "stuck index recovery" --mode hybrid --json

# Approximate semantic via HNSW (10–100x faster on big corpora)
cass search "QUERY" --mode semantic --approximate --json
```

If `--mode semantic` is used but no model is installed and `CASS_SEMANTIC_EMBEDDER=hash` is unset, cass **silently degrades to lexical** — the response includes `_meta.fallback_mode: "lexical"`. Always check that field before claiming semantic worked.

---

## Background Backfill

For very large corpora, semantic embedding can take minutes. cass schedules **low-impact background backfill** that respects idle/load budgets:

```bash
# Status of backfill (in-progress, completed, idle)
cass status --json | jq '.semantic'

# Force foreground build (skip backfill scheduler)
cass index --semantic --json
```

When `semantic.progressive_ready=true` but `hnsw_ready=false`, you can still query with `--mode semantic`; it'll do a brute-force vector scan (slower but correct).

---

## Pitfalls

- **Always check fallback mode.** A query that *looks* semantic may have run lexically:
  ```bash
  cass search "X" --mode hybrid --robot-meta --json | jq '._meta.fallback_mode // "ok"'
  ```
- **Hash embedder ≠ semantic.** It's deterministic and lexical-overlap only. Useful for env-pinning tests; not a substitute for MiniLM.
- **Vector index is per-embedder.** Switching embedders requires a rebuild: `cass index --semantic --embedder fastembed --json`.
- **Disk pressure**: the FSVI index can grow to ~1.5x the source SQLite size. If `df -h ~/.local/share` is tight, semantic backfill silently pauses.
- **Daemon mode (Unix only)**: `cass daemon` runs the model in-memory across queries to avoid 500ms model-load cost per call. Worth it if you're running >50 semantic queries/min.

# Session File Formats by Agent

> Format examples are connector/version-specific inspection aids, not identity
> or completeness guarantees. Read only sources authorized for the task, owner,
> model/provider and destination; raw native stores retain authority.

## Contents

- [Work-to-session associations](#work-to-session-associations)
- [Bounded raw source reads](RAW_SOURCE_READS.md)
- [Quick Detection](#quick-detection)
- [Claude Code Format](#claude-code-format)
- [Codex CLI Format](#codex-cli-format)
- [Gemini CLI Format](#gemini-cli-format)
- [Subagent Sessions (Critical)](#subagent-sessions-critical)
- [Universal Extraction Patterns](#universal-extraction-patterns)
- [File Location Cheat Sheet](#file-location-cheat-sheet)
- [Quick Reference](#quick-reference)

---

## Work-to-session associations

The caller passes work identity at dispatch/start before execution can fail,
and records the dispatch reference in native work comments/metadata or existing
runtime facts. At startup, record observed identity in that caller-owned channel
before substantive work, independently of final handoff. These are versioned
facts under their source owners, not a new AO association database, lifecycle,
packet schema or permanent writer. Core skills return facts; tracker mutation
requires the caller's authority. No memory/evidence file belongs in a consumer
checkout by default; requested CDLC evidence uses owner-selected protected
external non-Git storage.

Keep these facts distinct in the native record or its permitted evidence:

| Fact | Required distinction |
|---|---|
| Source work | Backend/store identity, database/project identity where available, native work ID and permitted source revision/intent locator; a bead ID alone or workspace basename is not globally unique. |
| Execution | Selected runtime and requested model/ID separately from actual observed model/session/context IDs; absent observations are explicit unknowns, never synthetic UUIDs. |
| Relations | Native parent, dispatch controller and resume predecessor are separate links, each with its observation source. Record the selected runtime's actual resume identity even when it reuses a session ID. Unknown is distinct from an observed absence of parent. |
| Provenance | Who or which runtime observed the fact, when, through which native operation/record, and its permitted locator. Caller-supplied facts remain labeled as supplied; do not upgrade inference to observation. |
| Discovery | Exact query/filters/limits, index freshness, observed cutoff and missing/unavailable/restricted sources. CASS results discover candidates, not every episode member. |
| Source extent | Permitted native locator plus available frozen byte length/bounds and digest, with the cutoff and digest scope. Unknown or unreadable extent/digest remains unknown, never zero or a hash of an excerpt represented as the full source. |
| Work span | Only the source interval supported by explicit work/start/switch observations. Where frozen byte offsets are available use half-open `[start, end)` ranges tied to that source identity/digest. A search line is a locator, not an inferred byte boundary. |

For a child, pass its work identity before launch, then record the child's
observed ID and independently supported parent link at startup. For resume,
retain the predecessor reference and add the observed resume relation; a
requested resume ID does not prove a resumed execution. Workspace adjacency,
matching task titles, filenames and guessed line numbers establish neither
identity nor parentage. A native session can cover multiple work items: record
only supported spans for each, preserve unrelated and unassigned spans, and
leave an unknown end unknown until an observation supports it. Never assign a
whole session to a work item because one hit names that work.

If launch, startup observation or native recording fails, retain the caller's
pre-execution record, available bounded failure facts and explicit unknowns;
report any recording gap. Recovery reopens permitted startup/native sources
without depending on a final handoff, preserving earlier failures/unknowns as
history when later observations resolve them. Do not fill gaps with invented
IDs, inferred edges or unrelated source spans.

All metadata follows source-owner and recipient/model/destination authorization,
including locators, native comments, filenames and diagnostics. BD/Dolt is
versioned and is not a secret store. Use permitted opaque locators rather than
restricted paths/excerpts or credentials; opacity grants no clearance. Check
access before resolving a locator, never retrieve denied bytes and redact later.

Association is not coverage: CASS discovery, `view`/`expand` windows and tool-call
mining do not prove full prose/outcome reading. Preserve missing sources and
unknown lengths. Frozen bounds/digests identify available evidence; they do not
prove bytes were emitted, delivered to the host or semantically processed.
Head/tail excerpts leave the middle unread; new tails or children belong to a
later observation, not a rewritten completed denominator. T09 owns the later
coverage verifier; no coverage command or acceptance claim is introduced here.

For byte-preserving reads of explicitly authorized sources, follow
[bounded raw source reads](RAW_SOURCE_READS.md). The source reader checks native
policy before opening bytes and reports frozen prefix/span digests, reversible
content and delivery limits; emitted stdout does not establish full reading.

## Quick Detection

These probes illustrate older formats only. Metadata may precede messages;
unknown format stays unknown until the selected connector/version is observed.
Do not infer a native session ID from either probe.

```bash
# Detect agent type from first line
head -1 /path/to/session.jsonl | jq -e '.type == "user"' && echo "claude_code"
head -1 /path/to/session.jsonl | jq -e '.role == "user"' && echo "codex_or_gemini"
```

---

## Claude Code Format

**Location:** `~/.claude/projects/<escaped-workspace-path>/*.jsonl`

**Path encoding:** Workspace `/data/projects/foo` becomes `-data-projects-foo`

**Example path:**
```
~/.claude/projects/-data-projects-beads_rust-2d7a3b1/session-20260116-143022.jsonl
```

### Message Structure

```json
{"type": "user", "message": {"content": "...", "role": "user"}, "timestamp": "2026-01-16T14:30:22Z"}
{"type": "assistant", "message": {"content": [...], "role": "assistant"}, "timestamp": "..."}
{"type": "tool_result", "tool_use_id": "...", "content": "...", "timestamp": "..."}
```

### Content Formats

**User content** — can be string OR array:
```json
// Simple string
{"type": "user", "message": {"content": "Help me fix this bug"}}

// Array with text blocks (common with images/files)
{"type": "user", "message": {"content": [{"type": "text", "text": "Help me fix this bug"}]}}
```

**Assistant content** — always array with mixed types:
```json
{"type": "assistant", "message": {"content": [
  {"type": "text", "text": "I'll help you fix that..."},
  {"type": "tool_use", "id": "toolu_01...", "name": "Read", "input": {"file_path": "/path/to/file"}}
]}}
```

### Extract User Messages

```bash
# Simple extraction (handles both string and array content)
jq 'select(.type == "user") | .message.content | if type == "array" then [.[] | select(.type == "text") | .text] | join(" ") else . end' session.jsonl
```

### Extract Tool Calls

```bash
# All tool calls
jq 'select(.type == "assistant") | .message.content[] | select(.type == "tool_use") | {name, input}' session.jsonl

# Specific tool (e.g., Write)
jq 'select(.type == "assistant") | .message.content[] | select(.type == "tool_use" and .name == "Write")' session.jsonl

# Tool results
jq 'select(.type == "tool_result")' session.jsonl
```

### First User Prompt (The Ritual Opener)

```bash
# Line 1-3 typically contains the opening prompt
jq -s '[.[] | select(.type == "user")][0] | .message.content' session.jsonl
```

---

## Codex CLI Format

**Location:** `~/.codex/**/*.jsonl` (varies by installation)

### Message Structure

```json
{"role": "user", "content": "...", "timestamp": "2026-01-16T14:30:22Z"}
{"role": "assistant", "content": "...", "created_at": "..."}
```

### Key Differences from Claude Code

| Aspect | Claude Code | Codex |
|--------|-------------|-------|
| Type field | `.type == "user"` | `.role == "user"` |
| Timestamp | `.timestamp` | `.timestamp` or `.created_at` |
| Content structure | Often array | Usually string |
| Tool calls | Embedded in `.content[]` | Varies |

### Extract User Messages

```bash
jq 'select(.role == "user") | .content' session.jsonl
```

### Extract with Timestamp

```bash
jq 'select(.role == "user") | {ts: (.timestamp // .created_at), content}' session.jsonl
```

---

## Gemini CLI Format

**Location:** `~/.gemini/**/*.jsonl` (varies by installation)

Similar to Codex format. Uses `.role` instead of `.type`.

```bash
jq 'select(.role == "user") | .content' session.jsonl
```

---

## Subagent Sessions (Critical)

**What:** When Claude Code spawns a Task agent, it creates a separate session log.

**Location:** `~/.claude/projects/<workspace>/subagents/agent-<id>.jsonl`

### Subagent Structure

```
Possible older layout, not guaranteed:
Line 1: Session metadata (type, model info)
Line 2: User prompt
Line 3+: Agent execution and responses
```

### Why Subagents Matter

Subagent prompts may live here. Inspect the actual authorized message type and
source position before citing a prompt; line 2 is only a legacy heuristic and
never evidence of identity, parentage or complete reading.

### Extract Subagent Prompt

```bash
# Inspect the possible prompt position; verify the actual message before use
cass view /path/subagents/agent-XXXXX.jsonl -n 2 -C 1

# Legacy-layout excerpt only, after verifying the actual prompt position
sed -n '2p' /path/subagents/agent-XXXXX.jsonl | jq '.message.content'

# Or with jq slurp
jq -s '.[1].message.content' /path/subagents/agent-XXXXX.jsonl
```

### Discover Candidate Subagent Sessions

```bash
# Via cass search
cass search "KEYWORD" --workspace /path --json --fields minimal \
  | jq '[.hits[] | select(.source_path | contains("subagent"))] | .[].source_path' -r | sort -u

# Via filesystem
find ~/.claude/projects -path "*/subagents/*.jsonl" | head -20
```

---

## Universal Extraction Patterns

### Detect and Extract (Legacy Examples)

```bash
#!/bin/bash
# Legacy-format example; unsupported formats remain unknown

FILE="$1"

# Detect format and extract
if jq -se '.[0].type == "user"' "$FILE" >/dev/null 2>&1; then
    # Claude Code format
    jq -s '[.[] | select(.type == "user")] | .[] | .message.content' "$FILE"
elif jq -se '.[0].role == "user"' "$FILE" >/dev/null 2>&1; then
    # Codex/Gemini format
    jq -s '[.[] | select(.role == "user")] | .[] | .content' "$FILE"
else
    echo "Unknown format"
fi
```

### Count Messages by Type

```bash
# Claude Code
jq -s 'group_by(.type) | map({type: .[0].type, count: length})' session.jsonl

# Codex/Gemini
jq -s 'group_by(.role) | map({role: .[0].role, count: length})' session.jsonl
```

### Extract Conversation Flow

```bash
# Timeline of who said what
jq -s '[.[] | {
  type: (.type // .role),
  ts: (.timestamp // .created_at),
  preview: (if .message then .message.content else .content end | tostring[0:100])
}]' session.jsonl
```

---

## File Location Cheat Sheet

| Agent | Session Location | Subagent Location |
|-------|------------------|-------------------|
| Claude Code | `~/.claude/projects/<escaped-path>/*.jsonl` | `.../subagents/agent-*.jsonl` |
| Codex | `~/.codex/**/*.jsonl` | Varies |
| Gemini | `~/.gemini/**/*.jsonl` | Varies |

### Find Session Files for a Workspace

```bash
# Claude Code: convert workspace to escaped pattern
WORKSPACE="/data/projects/beads_rust"
ESCAPED=$(echo "$WORKSPACE" | tr '/' '-' | sed 's/^-//')
find ~/.claude/projects -name "*.jsonl" | grep -i "$ESCAPED"
```

---

## Quick Reference

| Task | Claude Code | Codex/Gemini |
|------|-------------|--------------|
| Is user message? | `.type == "user"` | `.role == "user"` |
| Get content | `.message.content` | `.content` |
| Get timestamp | `.timestamp` | `.timestamp` or `.created_at` |
| Tool call? | `.type == "tool_use"` | Varies |
| First prompt | `jq -s '[.[] \| select(.type=="user")][0]'` | `jq -s '[.[] \| select(.role=="user")][0]'` |

#!/usr/bin/env bash
# multi_machine_search.sh — fan-out a cass search across the fleet
#
# Usage: ./multi_machine_search.sh "QUERY" [host1 host2 ...]
# Default hosts: css csd ts1 ts2
#
# - Local + remote searches run in parallel
# - One bad/unreachable host doesn't kill the rest (set -e disabled)
# - Query is passed via stdin to ssh, never interpolated into the command line,
#   so quotes/specials in the query are safe

set -uo pipefail
shopt -s nullglob   # unmatched globs expand to empty so `jq -s "$FANOUT_DIR"/*.json` is safe

QUERY="${1:?usage: $0 \"QUERY\" [host1 host2 ...]}"
shift
HOSTS=("$@")
[ ${#HOSTS[@]} -eq 0 ] && HOSTS=(css csd ts1 ts2)

# Per-host wall-clock cap (post-connect). ssh's ConnectTimeout only covers TCP
# handshake; if the remote `cass search` hangs we'd block indefinitely.
PER_HOST_TIMEOUT="${CASS_FANOUT_TIMEOUT:-30}"

# Required tools.
for tool in jq timeout ssh; do
  if ! command -v "$tool" >/dev/null 2>&1; then
    echo "error: '$tool' not on PATH" >&2
    exit 2
  fi
done

# Refuse multi-line queries early — `read -r q` on the remote only sees the first line.
case "$QUERY" in
  *$'\n'*)
    echo "error: multi-line queries are not supported (only the first line would be sent to remotes)" >&2
    exit 2
    ;;
esac

# Do NOT name this TMPDIR — that shadows the standard temp-dir env var for cass,
# jq, and ssh spawned below. Use a private name and ALWAYS remove it on exit
# (the old cleanup only printed a path and leaked the dir every run). No
# retention path: the skill's output contract states no artifact directory
# persists, and per-host errors are already surfaced to stderr before this trap.
FANOUT_DIR=$(mktemp -d -t cass-fanout-XXXXXX)
cleanup() {
  rm -rf "$FANOUT_DIR"
}
trap cleanup EXIT

# Local-host search runs in a function so a local cass failure produces "[]"
# rather than a missing file (which would later break the merge glob).
# Wrap every cass invocation in `timeout` — cass search has been observed
# to hang on certain inputs (e.g. --limit 0).
local_search() {
  local raw
  raw=$(timeout "$PER_HOST_TIMEOUT" cass search "$QUERY" --json --fields summary --limit 20 2>/dev/null) || raw=""
  if [ -z "$raw" ]; then
    echo "[]" > "$FANOUT_DIR/local.json"
    return
  fi
  printf '%s' "$raw" \
    | jq '[(.hits // [])[] | . + {origin_host: "local"}]' > "$FANOUT_DIR/local.json" \
    || echo "[]" > "$FANOUT_DIR/local.json"
}

# Pass the query via stdin so it's never spliced into the command line.
# `timeout` here covers post-connect hangs (ssh ConnectTimeout only covers TCP).
remote_search() {
  local h="$1"
  local raw
  # shellcheck disable=SC2016 # Remote shell expands $q after reading it from stdin.
  raw=$(timeout "$PER_HOST_TIMEOUT" ssh -o ConnectTimeout=5 -o BatchMode=yes "$h" \
        'IFS= read -r q && cass search "$q" --json --fields summary --limit 20 2>/dev/null' \
        <<<"$QUERY" 2>"$FANOUT_DIR/$h.err") || raw=""
  if [ -z "$raw" ]; then
    echo "[]" > "$FANOUT_DIR/$h.json"
    return
  fi
  printf '%s' "$raw" \
    | jq --arg h "$h" '[(.hits // [])[] | . + {origin_host: $h}]' > "$FANOUT_DIR/$h.json" \
    || echo "[]" > "$FANOUT_DIR/$h.json"
}

echo "→ local" >&2
local_search &

for h in "${HOSTS[@]}"; do
  echo "→ $h" >&2
  remote_search "$h" &
done

wait

# Surface ssh errors (don't fail; just inform)
for h in "${HOSTS[@]}"; do
  if [ -s "$FANOUT_DIR/$h.err" ]; then
    echo "  ! $h: $(head -c 200 "$FANOUT_DIR/$h.err" | tr '\n' ' ')" >&2
  fi
done

# Merge + dedup by source_path:line, sort by score
files=( "$FANOUT_DIR"/*.json )
if [ ${#files[@]} -eq 0 ]; then
  echo "[]"
  exit 0
fi

jq -s '
  (add // [])
  | map(select(type == "object"))
  | unique_by((.source_path // "") + ":" + ((.line_number // 0)|tostring))
  | sort_by(-(.score // 0))
  | .[0:50]
  | map({
      host:  (.origin_host // "?"),
      agent: (.agent       // ""),
      line:  (.line_number // null),
      score: (.score       // null),
      title: ((.title      // "") | .[0:100]),
      path:  (.source_path // "")
    })
' "${files[@]}"

#!/usr/bin/env python3
"""
Prompt Miner — Extract and cluster prompts across agent session logs.

Mines user prompts from Claude Code, Codex CLI, and Gemini CLI sessions,
groups identical text after whitespace normalization, and reports recurring
candidates. Counts do not establish success; retries and copied instructions
can recur too. Prefer CASS search/pack for discovery and cited evidence.

Usage:
    python prompt_miner.py --workspace /data/projects/PROJECT [OPTIONS]

Examples:
    # Find repeated prompts in a project
    python prompt_miner.py --workspace /data/projects/beads_rust --top 30

    # Mine all sessions with custom glob
    python prompt_miner.py --glob "~/.claude/projects/**/*.jsonl" --top 50

    # Only show frequent candidates (10+ occurrences; outcomes unassessed)
    python prompt_miner.py --workspace /path --min-count 10

    # Output as JSON for further processing
    python prompt_miner.py --workspace /path --json

    # Filter by agent
    python prompt_miner.py --workspace /path --agent claude_code
"""

import json
import re
import glob
import argparse
import os
import sys
from datetime import datetime, timezone
from typing import Optional


def normalize(s: str) -> str:
    """Normalize whitespace for clustering."""
    return re.sub(r"\s+", " ", s.strip())


def truncate(s: str, max_len: int = 100) -> str:
    """Truncate string with ellipsis."""
    if len(s) <= max_len:
        return s
    return s[:max_len-3] + "..."


def parse_iso(ts: str) -> Optional[datetime]:
    """Parse ISO timestamp, handling various formats."""
    if not ts:
        return None
    # Handle Z suffix
    if ts.endswith("Z"):
        ts = ts[:-1] + "+00:00"
    # Handle missing timezone
    if "+" not in ts and "-" not in ts[-6:]:
        ts = ts + "+00:00"
    try:
        dt = datetime.fromisoformat(ts)
        if dt.tzinfo is None:
            return dt.replace(tzinfo=timezone.utc)
        return dt
    except ValueError:
        return None


def extract_text_from_content(content) -> str:
    """Extract explicit user text, excluding tool results nested in user envelopes."""
    if isinstance(content, str):
        return content
    elif isinstance(content, list):
        parts = []
        for c in content:
            if isinstance(c, dict) and c.get("type") in ("text", "input_text"):
                if isinstance(c.get("text"), str):
                    parts.append(str(c["text"]))
        return " ".join(parts)
    elif isinstance(content, dict):
        if content.get("type") in ("text", "input_text") and isinstance(content.get("text"), str):
            return str(content["text"])
    return ""


def detect_agent(path: str, obj: dict) -> str:
    """Detect which agent produced this session."""
    path_lower = path.lower()
    if ".claude" in path_lower:
        return "claude_code"
    elif "codex" in path_lower:
        return "codex"
    elif "gemini" in path_lower:
        return "gemini"
    # Fallback: check object structure
    if obj.get("type") == "user":
        return "claude_code"
    elif obj.get("role") == "user":
        return "codex"  # or gemini
    return "unknown"


def mine_prompts(
    glob_pattern: str,
    agent_filter: Optional[str] = None
) -> list[tuple[datetime, str, str, str]]:
    """
    Mine user prompts from session logs.

    Returns list of (timestamp, source_path, prompt_text, agent).
    """
    items = []
    expanded_pattern = os.path.expanduser(glob_pattern)

    for path in glob.glob(expanded_pattern, recursive=True):
        try:
            with open(path, "r", encoding="utf-8") as f:
                for line in f:
                    try:
                        obj = json.loads(line)
                    except json.JSONDecodeError:
                        continue
                    if not isinstance(obj, dict):
                        continue

                    try:
                        agent = detect_agent(path, obj)
                        if agent_filter and agent != agent_filter:
                            continue

                        text = None
                        ts = None

                        # Claude Code format
                        if obj.get("type") == "user":
                            msg = obj.get("message", {})
                            if not isinstance(msg, dict):
                                continue
                            if msg.get("role", "user") != "user":
                                continue
                            content = msg.get("content", "")
                            text = extract_text_from_content(content)
                            ts = obj.get("timestamp")

                        # Current Codex response_item records carry the role in payload.
                        elif obj.get("type") == "response_item":
                            payload = obj.get("payload", {})
                            if not isinstance(payload, dict) or payload.get("role") != "user":
                                continue
                            if payload.get("type") != "message":
                                continue
                            text = extract_text_from_content(payload.get("content", ""))
                            ts = obj.get("timestamp")

                        # Flat Codex/Gemini format
                        elif obj.get("role") == "user" and "content" in obj:
                            text = extract_text_from_content(obj["content"])
                            ts = obj.get("timestamp") or obj.get("created_at")

                        if text and text.strip():
                            dt = parse_iso(ts) or datetime.now(timezone.utc)
                            items.append((dt, path, text.strip(), agent))
                    except Exception:
                        continue

        except Exception:
            # Skip unreadable files
            pass

    items.sort(key=lambda x: x[0])
    return items


def find_repeated_prompts(
    items: list[tuple],
    top_n: int = 30,
    min_count: int = 2
) -> list[dict]:
    """Find most repeated prompts with metadata."""
    # Group by normalized text
    groups = {}
    for dt, path, text, agent in items:
        key = normalize(text)
        if key not in groups:
            groups[key] = {
                "text": text,  # Keep original (first occurrence)
                "count": 0,
                "agents": set(),
                "first_seen": dt,
                "last_seen": dt,
                "paths": []
            }
        groups[key]["count"] += 1
        groups[key]["agents"].add(agent)
        groups[key]["last_seen"] = max(groups[key]["last_seen"], dt)
        if path not in groups[key]["paths"] and len(groups[key]["paths"]) < 3:  # Keep first 3 unique paths
            groups[key]["paths"].append(path)

    # Convert to list and sort
    results = []
    for key, data in groups.items():
        if data["count"] >= min_count:
            results.append({
                "prompt": data["text"],
                "count": data["count"],
                "agents": sorted(data["agents"]),
                "first_seen": data["first_seen"].isoformat() if data["first_seen"] else None,
                "last_seen": data["last_seen"].isoformat() if data["last_seen"] else None,
                "example_paths": data["paths"],
                "outcome": "unassessed"
            })

    results.sort(key=lambda x: -x["count"])
    return results[:top_n]


def workspace_to_glob(workspace: str) -> str:
    """Convert workspace path to glob pattern for session files."""
    workspace = os.path.expanduser(workspace)
    # Claude Code stores sessions in ~/.claude/projects/-path-to-project/
    # Convert /data/projects/foo to -data-projects-foo pattern
    escaped = workspace.replace("/", "-").lstrip("-")
    return f"~/.claude/projects/*{escaped}*/**/*.jsonl"


def main():
    parser = argparse.ArgumentParser(
        description="Mine prompts from agent session logs",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog="""
Examples:
    %(prog)s --workspace /data/projects/beads_rust --top 30
    %(prog)s --glob "~/.claude/**/*.jsonl" --min-count 10
    %(prog)s --workspace /path --json > prompts.json
        """
    )
    parser.add_argument(
        "--workspace",
        help="Project workspace path (auto-generates glob pattern)"
    )
    parser.add_argument(
        "--glob",
        help="Glob pattern for session files (overrides --workspace)"
    )
    parser.add_argument(
        "--top",
        type=int,
        default=30,
        help="Number of top repeated prompts to show (default: 30)"
    )
    parser.add_argument(
        "--min-count",
        type=int,
        default=2,
        help="Minimum repetition count to include (default: 2)"
    )
    parser.add_argument(
        "--agent",
        choices=["claude_code", "codex", "gemini"],
        help="Filter by agent type"
    )
    parser.add_argument(
        "--json",
        action="store_true",
        help="Output as JSON"
    )
    parser.add_argument(
        "--rituals-only",
        action="store_true",
        help="Legacy alias for --min-count 10; recurrence does not establish success"
    )

    args = parser.parse_args()

    if args.top <= 0:
        print("ERROR: --top must be greater than 0", file=sys.stderr)
        return 1
    if args.min_count <= 0:
        print("ERROR: --min-count must be greater than 0", file=sys.stderr)
        return 1

    # Determine glob pattern
    if args.glob:
        glob_pattern = args.glob
    elif args.workspace:
        glob_pattern = workspace_to_glob(args.workspace)
    else:
        glob_pattern = "~/.claude/projects/**/*.jsonl"

    # Set min count for rituals-only mode
    min_count = args.min_count
    if args.rituals_only:
        min_count = max(min_count, 10)

    # Mine prompts
    if not args.json:
        print(f"Mining prompts from: {glob_pattern}")

    items = mine_prompts(glob_pattern, args.agent)

    if not args.json:
        print(f"Found {len(items)} user prompts")

    # Find repeated prompts
    repeated = find_repeated_prompts(items, args.top, min_count)

    # Output
    if args.json:
        print(json.dumps({
            "glob_pattern": glob_pattern,
            "total_prompts": len(items),
            "repeated_prompts": repeated
        }, indent=2, default=str))
    else:
        print(f"\nTop {len(repeated)} recurring candidates (count >= {min_count}; outcomes unassessed):\n")
        for item in repeated:
            display = truncate(item["prompt"], 100)
            agents = ", ".join(item["agents"])
            print(f"{item['count']:3d}x ({agents}): {display}")


if __name__ == "__main__":
    sys.exit(main())

#!/bin/bash
#
# Quick Analysis — One-command project overview using cass
#
# Usage:
#     ./quick_analysis.sh /data/projects/PROJECT_NAME
#
# Output:
#     - Index health
#     - Indexed hits by agent
#     - Activity by date
#
# Read-only. Requires: cass, jq, GNU timeout (or gtimeout).

set -euo pipefail

WORKSPACE="${1:-}"

if [ -z "$WORKSPACE" ]; then
    echo "Usage: $0 /data/projects/PROJECT_NAME"
    echo ""
    echo "Examples:"
    echo "  $0 /data/projects/beads_rust"
    echo "  $0 /data/projects/rich_rust"
    exit 1
fi

# Expand path
WORKSPACE=$(realpath "$WORKSPACE" 2>/dev/null || echo "$WORKSPACE")

if ! command -v cass >/dev/null 2>&1; then
    echo "Error: cass is not installed or not in PATH"
    exit 1
fi

if ! command -v jq >/dev/null 2>&1; then
    echo "Error: jq is not installed or not in PATH"
    exit 1
fi

if command -v timeout >/dev/null 2>&1; then
    CASS_TIMEOUT=timeout
elif command -v gtimeout >/dev/null 2>&1; then
    CASS_TIMEOUT=gtimeout
else
    echo "Error: GNU timeout or gtimeout is required for bounded reads" >&2
    exit 1
fi

failed=0
read_cass() {
    local rc
    "$CASS_TIMEOUT" 15 cass "$@" || {
        rc=$?
        echo "CASS observation unavailable (exit $rc): $1" >&2
        return "$rc"
    }
}

echo "=============================================="
echo "CASS QUICK ANALYSIS: $WORKSPACE"
echo "=============================================="
echo ""

# 1. Health check
echo "--- Index Health ---"
read_cass status --robot-format json | jq -e '{
    conversations: .database.conversations,
    messages: .database.messages,
    index_fresh: .index.fresh,
    rebuilding: (.index.rebuilding // .rebuild.active // false),
    recommended: .recommended_action
}' || { echo "Index state unavailable; no recovery attempted" >&2; failed=1; }
echo ""

# 2. Agent breakdown (aggregation counts are hits, not distinct sessions)
echo "--- Indexed Hits by Agent ---"
read_cass search "*" --workspace "$WORKSPACE" --mode lexical --aggregate agent --limit 1 --fields minimal --json \
    | jq -r '.aggregations.agent.buckets[] | "\(.key): \(.count) hits"' \
    || { echo "Agent counts unavailable" >&2; failed=1; }
echo ""

# 3. Date breakdown (last 7 days of activity)
echo "--- Recent Activity (by date) ---"
read_cass search "*" --workspace "$WORKSPACE" --mode lexical --aggregate date --limit 1 --fields minimal --json \
    | jq -r '.aggregations.date.buckets | sort_by(.key) | reverse | .[0:7] | .[] | "\(.key): \(.count) hits"' \
    || { echo "Date counts unavailable" >&2; failed=1; }
echo ""

# 4. Quick tips
echo "--- Next Steps ---"
echo "Search a task-relevant keyword with an explicit workspace, limit and time cap."
echo "Use cass pack/view/expand for cited excerpts; verify user roles in native records."
echo "Repetition is a candidate signal, not evidence that an approach worked."
echo "Empty aggregates describe this indexed workspace only; failed reads are unavailable."
echo ""
echo "=============================================="
exit "$failed"

#!/usr/bin/env bash
# recover.sh — selected authorized cass recovery
#
# Decision tree:
#   1) If healthy: exit 0
#   2) If stale-but-usable: refresh in background, exit 0
#   3) If broken: doctor --fix, then verify
#   4) If still broken after fix: print actionable diagnostic and exit 1
#
# Invoke only for a diagnosed recovery/refresh need with indexing authorized.
# Search-only requests do not need this helper.
#
# Preserves source session files; may refresh or rebuild derived index state.

set -uo pipefail
# NOT -e: a non-zero exit from cass/jq is informational, not fatal — we want
# to fall through to the next recovery step rather than abort silently.

# Unique log files so concurrent agents don't clobber each other.
REFRESH_LOG=$(mktemp /tmp/cass-refresh.XXXXXX) || { echo "BROKEN: could not create refresh log" >&2; exit 2; }
REBUILD_LOG=$(mktemp /tmp/cass-rebuild.XXXXXX) || { echo "BROKEN: could not create rebuild log" >&2; exit 2; }

# Wall-clock caps. cass index has been observed to hang (see issue #196 and
# the limit-0 freeze); without these the script itself becomes the symptom.
STATUS_TIMEOUT="${CASS_STATUS_TIMEOUT:-15}"          # status / doctor / diag
REBUILD_TIMEOUT="${CASS_REBUILD_TIMEOUT:-900}"       # 15 min — covers ~1M-msg corpora

# Run cass binary check up front; if missing, fail loudly with a useful message.
if ! command -v cass >/dev/null 2>&1; then
  echo "BROKEN: cass binary not on PATH" >&2
  exit 2
fi
if ! command -v timeout >/dev/null 2>&1; then
  echo "BROKEN: GNU 'timeout' not on PATH (install coreutils; on macOS: brew install coreutils + use gtimeout)" >&2
  exit 2
fi
if ! command -v jq >/dev/null 2>&1; then
  echo "BROKEN: 'jq' not on PATH" >&2
  exit 2
fi

cass_state() {
  # Unobserved state must not be converted into an empty/corrupt database.
  local out
  out=$(timeout "$STATUS_TIMEOUT" cass status --json 2>/dev/null) || return 2
  if [ -z "$out" ]; then
    return 2
  fi
  printf '%s' "$out" \
    | jq -er 'select(
        type == "object"
        and (.index | type == "object")
        and (.database | type == "object")
        and (.index.fresh | type == "boolean")
        and (.database.exists | type == "boolean")
        and (.index.documents | type == "number" and . >= 0 and floor == .)
        and (.database.messages | type == "number" and . >= 0 and floor == .)
      ) | [
        .index.fresh,
        .database.exists,
        .index.documents,
        .database.messages,
        (.recommended_action // "")
      ] | @tsv' 2>/dev/null \
    || return 2
}

# Read state once. Use || true so an empty stream doesn't trip downstream.
state_line=$(cass_state) || { echo "UNAVAILABLE: index state not observed; no repair attempted" >&2; exit 2; }
IFS=$'\t' read -r FRESH DB_EXISTS DOCS MSGS REC <<< "$state_line" || true
FRESH=${FRESH:-false}
DB_EXISTS=${DB_EXISTS:-false}
DOCS=${DOCS:-0}
MSGS=${MSGS:-0}

case "$FRESH:$DB_EXISTS" in
  true:*)
    echo "READY: index fresh" >&2
    exit 0
    ;;
  false:true)
    if [ "$DOCS" != "0" ] && [ "$MSGS" != "0" ]; then
      echo "STALE_BUT_USABLE: refreshing in background (log: $REFRESH_LOG, hint: ${REC:-none})" >&2
      # Detached refresh that can't hang forever. Use setsid when available
      # (Linux/util-linux); on macOS without coreutils-setsid the inner
      # subshell + nohup-equivalent (`</dev/null` + `&` + parent exit) still
      # orphans the child to init and survives our exit.
      if command -v setsid >/dev/null 2>&1; then
        ( setsid timeout "$REBUILD_TIMEOUT" cass index --json >"$REFRESH_LOG" 2>&1 </dev/null & ) 2>/dev/null
      else
        ( trap '' HUP; timeout "$REBUILD_TIMEOUT" cass index --json >"$REFRESH_LOG" 2>&1 </dev/null & ) 2>/dev/null
      fi
      exit 0
    fi
    ;;
esac

# Got here = broken or empty index with non-empty DB
echo "RECOVERING: doctor --fix --json" >&2
# Doctor exits 0 even when checks fail — never abort on its exit code.
# Cap wall time to avoid hanging on a degraded DB.
doctor_json=$(timeout "$REBUILD_TIMEOUT" cass doctor --fix --json 2>/dev/null || true)
if [ -n "$doctor_json" ]; then
  printf '%s' "$doctor_json" \
    | jq -c '{healthy, status, fixed: .auto_fix_actions, issues_found, issues_fixed,
              failures: [.checks[]? | select(.status=="fail") | .name]}' >&2 \
    || echo '{"warning":"doctor output not parseable as JSON"}' >&2
else
  echo '{"warning":"doctor produced no output"}' >&2
fi

# Verify
state_line=$(cass_state) || { echo "UNAVAILABLE: state after doctor not observed; no further repair attempted" >&2; exit 2; }
IFS=$'\t' read -r FRESH DB_EXISTS DOCS MSGS REC <<< "$state_line" || true

if [ "${DB_EXISTS:-false}" = "true" ] && [ "${DOCS:-0}" != "0" ]; then
  echo "RECOVERED: doctor succeeded" >&2
  exit 0
fi

# Last resort: full force rebuild (workaround for OPEN issue #196).
# `timeout` here is critical — `cass index --full` has been observed to hang
# indefinitely under contention. Treat exit 124 (timeout) as a definite failure.
echo "ESCALATING: cass index --full --force-rebuild --json (log: $REBUILD_LOG, cap: ${REBUILD_TIMEOUT}s)" >&2
timeout "$REBUILD_TIMEOUT" cass index --full --force-rebuild --json >"$REBUILD_LOG" 2>&1
rebuild_rc=$?
case "$rebuild_rc" in
  124) echo "  ! rebuild hit ${REBUILD_TIMEOUT}s timeout (likely issue #196)" >&2 ;;
  0)   : ;;
  *)   echo "  ! rebuild exited $rebuild_rc (data may still be partially committed)" >&2 ;;
esac

# Even on exit 0 the JSON may report success:false (the last_indexed_at race
# documented in coding_agent_session_search-zz8ni). Always verify by re-reading state.
state_line=$(cass_state) || { echo "UNAVAILABLE: state after rebuild not observed" >&2; exit 2; }
IFS=$'\t' read -r FRESH DB_EXISTS DOCS MSGS REC <<< "$state_line" || true
if [ "${DB_EXISTS:-false}" = "true" ] && [ "${DOCS:-0}" != "0" ]; then
  echo "RECOVERED: index is queryable (fresh marker may still be stale; that's harmless)" >&2
  exit 0
fi

# Genuinely stuck — surface for human (compact JSON only, not the verbose log spam)
echo "BROKEN: cass cannot self-recover" >&2
echo "Diagnostic (cass diag --json):" >&2
timeout "$STATUS_TIMEOUT" cass diag --json 2>/dev/null | jq -c '{paths, database, index, version}' >&2 || true
echo "Last index attempt log: $REBUILD_LOG (tail):" >&2
tail -n 5 "$REBUILD_LOG" 2>/dev/null >&2 || true
exit 1

#!/usr/bin/env bash
# validate.sh — structural check for the cass skill.
#
# CI should prove the skill artifact is valid, not require an operator's local
# cass index. Set AGENTOPS_VALIDATE_LIVE_TOOLS=1 to run the live cass smoke.

set -euo pipefail

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
SKILL_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
SKILL_MD="$SKILL_DIR/SKILL.md"
SPEC_JSON="$SKILL_DIR/skill.spec.json"

fail=0
err() { printf 'FAIL: %s\n' "$1" >&2; fail=1; }
ok() { printf 'ok:   %s\n' "$1"; }

[ -f "$SKILL_MD" ] || { err "SKILL.md missing"; exit 1; }
head -n1 "$SKILL_MD" | grep -qx -- '---' || err "frontmatter must open with ---"
grep -q '^name: cass$' "$SKILL_MD" || err "name must be cass"
grep -q '^description:' "$SKILL_MD" || err "description missing"
grep -q '^skill_api_version:' "$SKILL_MD" || err "skill_api_version missing"
grep -q 'cass search' "$SKILL_MD" || err "cass search workflow missing"
grep -q 'cass status' "$SKILL_MD" || err "cass status workflow missing"
grep -q 'Incremental refresh can become authoritative' "$SKILL_MD" || err "authoritative fallback guidance missing"
grep -q '124 is NOT zero hits' "$SKILL_MD" || err "bounded concurrent-search guidance missing"
grep -q 'not evidence that source sessions were lost' "$SKILL_MD" || err "source-preservation boundary missing"
grep -q '^## Authoritative Fallback and Concurrent Read Latency$' \
  "$SKILL_DIR/references/OBSERVABILITY.md" || err "observability fallback detail missing"

if [ -f "$SPEC_JSON" ]; then
  python3 -m json.tool "$SPEC_JSON" >/dev/null || err "skill.spec.json is not valid JSON"
  ok "skill.spec.json valid JSON"
else
  ok "skill.spec.json sidecar absent"
fi

if [ "${AGENTOPS_VALIDATE_LIVE_TOOLS:-0}" = "1" ]; then
  command -v cass >/dev/null 2>&1 || err "cass is not installed or not in PATH"
  command -v jq >/dev/null 2>&1 || err "jq is not installed or not in PATH"
  if command -v cass >/dev/null 2>&1 && command -v jq >/dev/null 2>&1; then
    status="$(cass status --robot-format json 2>/dev/null)" || err "cass status failed"
    printf '%s' "$status" | jq -e . >/dev/null 2>&1 || err "cass status returned invalid JSON"
    cass search "*" --json --limit 1 --fields minimal >/dev/null 2>&1 || err "basic cass search failed"
    cass search "*" --json --aggregate agent --limit 1 --fields minimal >/dev/null 2>&1 || err "cass aggregation search failed"
  fi
else
  ok "live cass smoke skipped (set AGENTOPS_VALIDATE_LIVE_TOOLS=1 to enable)"
fi

if [ "$fail" -eq 0 ]; then
  printf '\nPASS: cass skill artifact is valid.\n'
  exit 0
fi

printf '\nFAILED: cass skill artifact validation failed.\n' >&2
exit 1