lifrary · Oct 11, 2026 · Oct 11, 2026 · Oct 11, 2026
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
@@ -5,13 +5,13 @@
   },
   "metadata": {
     "description": "Single-plugin marketplace for agent-tree. Navigate Claude Code and Codex sessions and generate resume prompts.",
-    "version": "0.4.0"
+    "version": "0.6.0"
   },
   "plugins": [
     {
       "name": "agent-tree",
       "description": "Navigate Claude Code and Codex sessions as numbered trees and generate resume prompts. Terminal-only — no browser.",
-      "version": "0.4.0",
+      "version": "0.6.0",
       "author": {
         "name": "Seungwoo Lee"
       },

diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "agent-tree",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Navigate Claude Code and Codex sessions as numbered trees and generate resume prompts. Terminal-only — no browser.",
   "author": {
     "name": "Seungwoo Lee"

diff --git a/.claude/commands/mcp-smoke.md b/.claude/commands/mcp-smoke.md
@@ -9,7 +9,8 @@ Run this **after `npm publish`** has succeeded. It installs from the registry, n
 
 The handshake below checks tool presence, not source behavior. Before release,
 also run `npm run smoke:release`: its installed-tarball checks cover Claude and
-Codex discovery, portable imports, source schemas, and redacted JSON output.
+Codex discovery, portable imports, source schemas, redacted JSON output,
+child/archive search, recovery snapshots, and opt-in catalog usage.
 All seven tools accept optional `source: "claude" | "codex"`; picks without a
 source filter span both.
 

diff --git a/.claude/commands/pre-publish-audit.md b/.claude/commands/pre-publish-audit.md
@@ -7,6 +7,12 @@ You are running the agent-tree pre-publish audit. **Halt and report on the FIRST
 
 All paths below are relative to repo root (cwd is already the repo). Each code block starts with `set -euo pipefail` so a failed intermediate does not silently propagate to a green PASS.
 
+For 0.6.0, verify the combined 0.5/0.6 milestones: bounded recovery evidence
+and fork cutoffs, child/archive search and parent provenance, Codex descendant
+usage, and opt-in CLI/MCP catalog totals. Default catalogs must remain
+metadata-only. Run the installed-tarball `npm run smoke:release` as well as
+the regression suite. Passing these checks is not permission to publish.
+
 ## Check 1 — Version sync (6 fields)
 
 `package.json#version` is canonical. These five files / six fields must all match it:

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,50 @@ All notable changes to this project are documented here. The format follows [Kee
 
 ## [Unreleased]
 
+### 0.6.0 — recovery, search coverage and usage
+
+This release combines the 0.5 and 0.6 roadmap milestones. It is not yet
+published to npm; there is no separate 0.5.0 publication.
+
+### Added
+
+- Source-attributed, bounded historical evidence in recovery prompts, with
+  explicit continue/fork cutoffs and omission notices. Fork prompts exclude
+  outcomes after the selected question. Prompts do not restore files;
+  attached Git context describes the current checkout.
+- Search of Claude Code and Codex child transcripts and Codex
+  `archived_sessions/`, with exact-file commands and proven parent-step links.
+  Unknown parent steps remain unknown. Archived main sessions also resolve
+  by ID; default recent catalogs still exclude children and archives.
+- Codex descendant usage attributed separately from main usage, with
+  inherited-call deduplication and session-level attribution when the
+  initiating step is unavailable. Related child changes invalidate MCP usage
+  caches for both sources.
+- Opt-in `--sessions --usage` and `agent_tree_sessions({ usage: true })`.
+  Only selected rows are analyzed; main and child usage are preserved beside
+  combined prompt/output totals. Missing usage is distinct from zero and
+  unavailable transcripts do not erase other rows.
+
+### Changed
+
+- JSON mindmaps identify the updated contract as `spec_version: "v0.6"`.
+- Native Claude child transcripts use path-derived pick identities instead
+  of colliding with the parent session UUID repeated in their records.
+- Numeric UUIDs are no longer partially redacted as Luhn-valid credit-card
+  prefixes, preserving usable file selectors while still redacting cards.
+- Git context is explicitly current, with redaction before display shortening.
+- The roadmap now prioritizes finding and resuming reliably, then complete
+  usage accounting; release metadata is prepared for 0.6.0.
+
+### Limits
+
+- Recovery evidence is bounded to 32 excerpts and a 512-occurrence ancestry
+  walk, plus provable instruction anchors. Truncated traversal reports unknown
+  additional context rather than implying complete decision recovery.
+- Usage comes from available logs, not a billing ledger. Inherited calls
+  cannot always be distinguished when response/thread identity and timestamp
+  evidence are absent. Unknown step attribution stays explicit.
+
 ## [v0.4.0] — 2026-10-10
 
 ### Fixed

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -71,7 +71,9 @@ The reason: redaction and path-safety bugs are silent failures that bypass every
 
 ### Routing through canonical helpers
 
-If you add a new code path that analyzes a session, route it through `runPipeline` (MCP uses the analysis/cache helper inside `createServer`). Do **not** call `buildMindMap` directly — it bypasses the pipeline's redaction policy. v0.1.0 had this exact bug for three MCP tools. Claude catalogs are parse-free; Codex catalogs read bounded metadata headers, never analyze the conversation. Catalog strings still need redaction before output.
+If you add a new code path that analyzes a session, route it through `runPipeline` (MCP uses the analysis/cache helper inside `createServer`). Do **not** call `buildMindMap` directly — it bypasses the pipeline's redaction policy. v0.1.0 had this exact bug for three MCP tools. Claude catalogs are parse-free; Codex catalogs read bounded metadata headers. Explicit `--sessions --usage`
+or MCP `usage: true` may analyze only the already-limited rows, through
+`runPipeline` with LLM disabled. Catalog strings still need redaction before output.
 
 ### Adding a session source
 
@@ -99,8 +101,8 @@ retain output redaction, and never execute commands from a transcript.
   session. All per-session tools accept `file` or `sessionId`,
   never both. All tools accept optional `source`; picks can filter by source
   or list both. MCP remains heuristic-only.
-- Cover portable exports, `CLAUDE_CONFIG_DIR`, `CODEX_HOME`, regular-file
-  discovery (no agent/subagent or symlink entries), strict parse failures,
+- Cover portable exports, `CLAUDE_CONFIG_DIR`, `CODEX_HOME`, default main-only
+  catalogs, opt-in child/archive discovery with no symlink entries, strict parse failures,
   JSON redaction/no stdout banners, and incompatible CLI flags (exit 2).
   JSON is the complete mindmap, not a filtered text view.
 - Verify defaults < user < project < environment < explicit CLI precedence,

diff --git a/README.md b/README.md
@@ -174,17 +174,33 @@ Every step comes with two resume prompts.
 
 A resume prompt is plain markdown: where it came from, the files involved and your last instruction at that point, plus the current branch, recent commits and status of the git repository the session worked in. In a terminal it lands on your clipboard; paste it as the first message of a new session.
 
+Snapshots include bounded, attributed transcript evidence from before the chosen
+cutoff, not just the selected instruction. Continue includes work through the
+selected segment; fork stops at the first question anchoring that step, before
+its subsequent work or later questions in the same segment. Omitted
+evidence is identified with source references, not silently summarized away.
+These are context prompts, not native session or file restoration. The Git
+section describes the repository **now**, not its state at the historical step.
+Evidence is capped at 32 excerpts (4,096 UTF-8 bytes each), with a 36,000-byte
+rendered evidence budget. Each snapshot traverses at most 512 ancestral
+occurrences and preserves provable original/current instruction anchors.
+Older omitted context is explicitly unknown; omission counts are lower bounds
+when traversal stops early. Arbitrary system instructions and private reasoning
+are excluded; explicitly recorded compaction summaries are labeled as summaries.
+
 ```console
 $ agent-tree 3f9c2a71 --snapshot 7 --mode fork
-# Forking at: "Store sessions in Redis instead of memory" (discarding future)
+# Forking at: n_007 (discarding future)
 
-**Source session**: `3f9c2a71-5b8e-4d02-9a64-1c7e0b2d8f45` (events 14–19)
-**Mode**: fork (discarding subsequent turns from original session)
+**Source session**: `3f9c2a71-5b8e-4d02-9a64-1c7e0b2d8f45`
+**Node**: `n_007`
+**Mode**: fork
+**Evidence cutoff**: source event 14 (inclusive)
 …
 ## What I want you to DO
-- Ignore whatever path the original session took after this.
-- Re-approach the open question fresh.
-- You may suggest different architecture / file layout / tools.
+- Ignore the original session’s work after the evidence cutoff.
+- Re-approach the quoted question, or the work immediately after the stated boundary, fresh.
+- Verify files and assumptions before making changes.
 …
 ```
 
@@ -204,7 +220,12 @@ claude  cccc1111  /tmp/usage-proj  2026-10-10 14:48
 
 It reads every project and both agents unless you narrow it with `--cwd`, `--source` or `--since <days>`. It matches your prompts, the agent's replies and the commands and paths it used; add `--include-tool-output` to match tool results too. A lowercase query ignores the case of ASCII letters, and any capital letter makes it exact; letters outside ASCII, such as `é`, match only as typed. `--json` prints the results for scripts, and Claude gets the same search as the `agent_tree_search` tool.
 
-Search reads the main Claude Code transcripts and Codex sessions that `--sessions` lists. It does not read Claude Code subagent transcripts or Codex sessions archived under `~/.codex/session_archives/`. It skips its own `agent-tree --search` commands and `agent_tree_search` calls, but anything else that quotes the query, such as a message about it, is a real match, so a fresh search can find the session it was typed in.
+Search includes Claude Code and Codex subagent transcripts and Codex sessions
+under `<CODEX_HOME or ~/.codex>/archived_sessions/`. Child and archived results
+include an exact `--file` snapshot command. A child also links to its parent's
+originating step when the logs prove that relationship; otherwise the step is
+explicitly unavailable. Search skips its own `agent-tree --search` commands
+and `agent_tree_search` calls, but other text quoting the query remains a match.
 
 ### Token usage per step
 
@@ -217,7 +238,29 @@ $ agent-tree --list --usage
 3. └─ "Now write the tests for the parser please"  (0 actions · 1 file · 0min) T+20m  events 7–13  prompt 3.6k · out 49 · ctx 3.1k
 ```
 
-`prompt` counts every token the model read, cached or not, and `out` what it wrote. `ctx` is the largest prompt in the step, so you can see where the context filled up; Codex rows also show the model's window (`ctx 179k/258k`). A step that compacted the context shows it (Codex logs no counts, so its rows say only `compacted`), and subagent work appears beside the main numbers instead of inside them. Claude Code does not log the model's context window, so its rows show the context size without a limit, and Codex subagent sessions are not yet counted toward the step that started them. `--json` includes this usage whenever the session logged it.
+`prompt` counts every token the model read, cached or not, and `out` what it wrote.
+`ctx` is the largest prompt in the step; Codex also logs the model's window
+(`ctx 179k/258k`). Compactions and subagent usage appear beside the main numbers,
+not inside them. Claude Code does not log its model's context window. Both
+sources attribute linked subagent work to the initiating step, including nested
+children; usage with known session ancestry but no proven step remains at the
+session root. Portable exports do not pull in unrelated host Codex transcripts.
+`--json` includes usage whenever the session logged it.
+Unlinked descendants are marked `unattributed` in text and
+`subagents.unattributed_count` in JSON. Response IDs, thread IDs and timestamp
+evidence prevent inherited-call duplication when available; logs missing all
+such evidence cannot prove which history was copied. Totals describe available
+logs, not an independently verified billing ledger.
+
+For totals across recent sessions, use `agent-tree --sessions --usage` (or
+`agent_tree_sessions` with `usage: true`). This explicitly opts into transcript
+reads, only after `--limit` selects the rows; the default catalog remains cheap.
+Main and subagent usage stay separately available, alongside their combined
+prompt/output totals. Missing usage and unavailable files are not reported as
+zero, and token totals are not monetary cost estimates.
+Usage-enabled JSON catalog rows add `usage_status` (`available`, `not_logged`
+or `unavailable`), `usage`, `total_prompt_tokens` and `total_output_tokens`.
+Unavailable or unlogged totals are `null`; logged zeros remain numeric zero.
 
 ### Open a session from any step
 
@@ -250,7 +293,11 @@ A Codex resume prompt is a copy-paste context prompt, not a native `codex resume
 
 <br>
 
-Discovery reads only the metadata header of each rollout under `<CODEX_HOME or ~/.codex>/sessions/`. It skips subagent sessions and symlinks; `--file` can still open a subagent export. `--cwd` matches the working directory recorded in the header. Archived sessions are not scanned; open those with `--file`.
+The default catalog reads only metadata headers under
+`<CODEX_HOME or ~/.codex>/sessions/`, excluding child sessions and symlinks.
+Search additionally discovers children and `archived_sessions/`; explicit
+session IDs can resolve archived main sessions. `--file` opens exact transcripts,
+including child exports. `--cwd` matches the metadata working directory.
 
 Messages, tool calls and results, patch file paths and public reasoning summaries go through the same analysis as Claude logs. Duplicate message notifications are counted once, compaction summaries stay as system events, and encrypted reasoning is not decoded. A rollout is a chronological log, not a reconstructed fork tree.
 
@@ -443,6 +490,7 @@ Use the absolute path of your own install; after `npm install -g`, it is `$(npm
 | "show my starred steps" / "remove that star" | `agent_tree_picks({})` / `agent_tree_unstar({ cwd, nodeId })` |
 | "where did we fix the redactor?"             | `agent_tree_search({ cwd, query: "redactor" })`, then a snapshot |
 | "where did the context fill up?"             | `agent_tree_list({ cwd, usage: true, phasesOnly: true })`     |
+| "how many tokens did recent sessions use?"   | `agent_tree_sessions({ cwd, usage: true, limit: 10 })`       |
 
 On the command line, the same requests map to `--sessions`, `--list`, `--snapshot <n> --mode <mode>`, `--diff <a> <b>`, `--picks`, `--unstar <n>` and `--search <text>`.
 
@@ -510,7 +558,7 @@ Inputs are validated with zod. Success returns `{ "content": [{ "type": "text",
 | `--file <path>`                                                       | —                   | read a Claude Code or Codex JSONL file; auto-detect its source                 |
 | `--source <claude\|codex>`                                            | Claude discovery; automatic file detection | select the session source                               |
 | `--cwd <dir>`                                                         | current directory   | project for discovery and `.agent-tree.yaml`                                   |
-| `--sessions`                                                          | off                 | list sessions without analyzing them; all projects unless `--cwd`              |
+| `--sessions`                                                          | off                 | list recent main sessions; opt into analysis with `--usage`; all projects unless `--cwd` |
 | `--limit <n>`                                                         | `20` / `10`         | how many sessions `--sessions` lists or `--search` reports                     |
 | `--json`                                                              | off                 | complete redacted tree, or the `--sessions` catalog                            |
 | `--strict`                                                            | off                 | fail on malformed JSONL instead of recovering                                  |
@@ -528,7 +576,7 @@ Inputs are validated with zod. Success returns `{ "content": [{ "type": "text",
 | `--search <text>`                                                     | —                   | sessions and steps where the text appears; all projects and agents             |
 | `--since <days>`                                                      | —                   | with `--search`, only sessions changed in the last N days                      |
 | `--include-tool-output`                                               | off                 | with `--search`, also match tool results                                       |
-| `--usage`                                                             | off                 | token usage per step in the tree                                               |
+| `--usage`                                                             | off                 | token usage per tree step, or opt-in totals with `--sessions`                   |
 | `--open <id>`                                                         | —                   | start a new agent session from one step's resume prompt                        |
 | `--agent <claude\|codex>`                                             | the session's agent | which agent `--open` starts                                                    |
 | `--open-dir <dir>`                                                    | the step's directory | where `--open` starts the agent                                                |
@@ -592,9 +640,16 @@ Before every paid request, agent-tree counts the prepared prompt with `messages.
 - [x] **0.2** (October 2026, npm 0.2.1): session catalog, portable session files, JSON export, layered configuration, and support for the current Claude Code log format
 - [x] **0.3** (October 2026): a session-source interface, so logs from other coding agents can plug in, and Codex CLI sessions
 - [x] **0.4** (October 2026): search across sessions, token usage per step, and opening a new Claude Code or Codex session from any step
-- [ ] **Search subagent work and archived sessions**: reach Claude Code subagent transcripts and the Codex sessions moved to `~/.codex/session_archives/`
-- [ ] **Codex subagent usage**: count each Codex subagent's tokens against the step that started it
-- [ ] **Token totals in the session list**: show each session's total usage next to it in `--sessions`
+- [x] **0.5 — Find and resume reliably**: bounded, source-attributed recovery
+  context with explicit continue/fork cutoffs; search child and archived
+  transcripts and link results to their original files and proven parent steps.
+- [x] **0.6 — Complete usage accounting**: attribute Codex descendants without
+  duplicate inherited calls, distinguish unassigned usage, and offer opt-in
+  session-list totals without slowing the default catalog.
+
+The 0.5 and 0.6 milestones were implemented together for 0.6.0. Repository
+implementation and npm publication are separate; the latest published release
+remains 0.4.0 until the release checklist is completed.
 
 Have an idea or hit a bug? [Open an issue](https://github.com/lifrary/agent-tree/issues).
 

diff --git a/RELEASING.md b/RELEASING.md
@@ -3,7 +3,9 @@
 This is the v0.X.Y → v0.X.Y+1 (or v0.X+1.0) checklist. Captures the sequence
 that shipped v0.1.0 so the next release doesn't re-discover it.
 
-The latest release is **0.4.0**, published to npm on 2026-10-10. Updating the
+The latest published release is **0.4.0**, published to npm on 2026-10-10.
+The repository prepares **0.6.0**, including the 0.5 recovery/search milestone
+and 0.6 usage milestone; 0.5.0 is not a separate published release. Updating the
 repository does not publish to npm; registry and GitHub release steps below
 are a separate maintainer action after release approval.