feat(history): COD-549 read saved Codex conversations offline

plugins/codeman/skills/codeman/SKILL.md

@@ -8,12 +8,19 @@ description: >-
   read their output, and clean up; where available, message claude workers directly
   (Claude Code cross-session messaging). Use when asked to orchestrate or parallelize
   work across Codeman sessions, get a second opinion from another CLI or model, watch
-  another session, or start and manage workers. Only usable inside a Codeman-managed
-  session (CODEMAN_MUX=1); refuse to act otherwise.
+  another session, start and manage workers, or retrieve saved local Codex history
+  by file/native ID or root and descendants with topic/date filters. Live API
+  operations require a Codeman-managed session (CODEMAN_MUX=1). Offline history
+  reads do not require a server or managed session.
 ---
 
 # Driving Codeman from inside a session
 
+For **saved Codex conversation history**, use `codeman history read` and
+[reference/history.md](reference/history.md). This is a read-only local command:
+route to it **before §0**, including outside a managed session. It needs no API
+URL, credentials or running server. All live API operations below retain §0.
+
 You are an agent running inside a Codeman-managed terminal session. Codeman is the
 server that spawned you; its HTTP API can start, prompt, watch, and delete other
 sessions.
@@ -43,8 +50,8 @@ machine has no `jq` for the preamble below.
 
 ## 0. Guard and bootstrap
 
-If `CODEMAN_MUX` is not `1`, **stop and say so**. Do not guess an API URL; a server
-you are not part of is not yours to drive.
+For live API operations, if `CODEMAN_MUX` is not `1`, **stop and say so**.
+Do not guess an API URL; a server you are not part of is not yours to drive.
 
 Two failures come from your CLI, not from Codeman: name them to the user instead of
 retrying.

plugins/codeman/skills/codeman/reference/history.md

@@ -0,0 +1,51 @@
+# Saved Codex history (offline)
+
+Use `codeman history read` for retained local Codex JSONL transcripts. This command
+works outside a managed session and never calls the HTTP API. Do not bootstrap
+API credentials or require `CODEMAN_MUX` for this read-only job.
+
+Choose exactly one selector:
+
+```bash
+codeman history read --file /path/to/rollout.jsonl
+codeman history read --session-id aaaaaaaa --sessions-root /path/to/sessions
+codeman history read --root-session-id aaaaaaaa-1111-4111-8111-111111111111 \
+  --topic 'authentication' --after 2026-10-01 --before 2026-10-24 \
+  --max-bytes 65536
+```
+
+`--session-id` accepts a native conversation UUID or unique prefix of at least
+8 characters; identity comes from metadata, not filenames. `--root-session-id`
+requires a full native UUID and includes transitive descendants found in metadata.
+The default store is `$CODEX_HOME/sessions`, or `~/.codex/sessions` when unset.
+`--file` selects one file and does not search for its ancestors or children.
+
+Topic matching is a case-insensitive literal substring. Dates are inclusive
+`YYYY-MM-DD` bounds. Each filter selects whole user/assistant turns; a turn is
+retained if it has a date match and a topic match, which may be different messages
+in that turn. Tool calls/results and injected context are omitted. Adjacent duplicate
+native representations are collapsed; repeated messages from the same
+representation are retained.
+
+JSON is the default (`--json` or `--format json`); `--format text` is available.
+Results identify source paths, native session/root IDs, timestamps, roles and phases,
+plus scan counters and `complete`. A root ID is `null` when ancestry cannot be proven.
+Report that uncertainty; never relabel the queried child as its own root.
+`complete: false` reports malformed or partial records, skipped links, unattributed
+files or missing ancestors. It does not prove the store includes every conversation
+ever created, and a filtered result is only evidence for its selected scope.
+
+Reads require regular UTF8 files and reject final-component symlinks, conflicting
+metadata, ambiguous IDs, cyclic ancestry, invalid selectors and changed selected
+files. Directory traversal skips symlinks. Parent directories of an explicitly
+supplied path must be trusted; this is not a filesystem sandbox.
+
+The default total metadata/transcript scan budget is 16 MiB; `--scan-bytes` allows
+1–67108864 bytes. Directory scans are capped at 8192 entries and depth 8. The output
+budget is 8192 bytes by default; `--max-bytes` allows 1–1048576 bytes, including the
+final newline. Exhausted budgets fail with an error: output is never silently
+truncated or split into partial JSON or turns. Narrow the store/filters or explicitly
+raise the relevant budget. Missing evidence is an error, not an empty success.
+
+This command does not inspect live panes, stage prompts, submit input or manage
+sessions. For live operations return to the managed-session guard in the skill.