# Inspector workflow and limits ## Workflow - Run `node scripts/inspect.mjs list`; it resolves storage and returns bounded metadata. - Narrow with a literal name/ID/cwd query, `--cwd `, or `--since YYYY-MM-DD` / `--until YYYY-MM-DD` (inclusive UTC session start dates). - Page with `--offset N --limit N`; maximum limit is 100. - Run `node scripts/inspect.mjs show `; duplicate names or prefixes are errors, so choose an exact ID or discovered file. - Use `--view branch` for history or `--view context` for model context; `--leaf ` selects another branch. - Timeline rows include source line and entry ID. `--text` returns bounded user, assistant, and summary excerpts; `--content` returns each entry's complete non-structural fields under `payload`, including tool arguments/results, errors, thinking, images, Bash output, and custom state. - Default leaf is the last persisted entry, not an unrecorded live `/tree` cursor. Branch counts cover persisted messages; context counts include retained-tail messages separately. ## Examples ```sh node scripts/inspect.mjs list "tune" node scripts/inspect.mjs list --since 2026-09-01 --limit 10 node scripts/inspect.mjs show "tune bugs" --view context --text node scripts/inspect.mjs show 01a07693 --view branch --content --offset 50 --limit 50 ``` ## Storage resolution - Precedence: CLI `--session-dir` → `PI_CODING_AGENT_SESSION_DIR` → project `.pi/settings.json` `sessionDir` → global `${PI_CODING_AGENT_DIR:-~/.pi/agent}/settings.json` `sessionDir`. - Project-relative paths resolve against cwd. Otherwise try `~/.local/state/pi/sessions`, then agent-dir `sessions`, then cwd `.pi/sessions`. - Stop at the first store containing JSONL files. An explicitly configured empty or missing directory never falls through. - Never search outside these roots; directory and file symlinks are not followed. ## Validation and interpretation - Unfiltered lists validate every discovered session. Date/cwd filters may skip a body only after a valid header proves it is out of scope; invalid headers and in-scope files remain errors, and query/pagination never permit skipping. - `complete` means every candidate was fully parsed or safely excluded; `scanned`, `parsed`, and `skipped` distinguish outcomes. List exits nonzero when any unresolved file fails validation. - An unfinished live JSONL line is an error; retry after its writer finishes. - Report malformed/unsupported sessions by file and line, never by contents. - Do not count abandoned branches or retained-tail copies as additional user turns.