Read Codex History

Read Codex History

Read Codex evidence only. Do not continue the old task or change its project. If the user wants execution after the read is complete, pass the verified evidence to daymade-claude-code:continue-codex-work.

Codex has four different history surfaces

Do not substitute one surface for another. A prompt-ledger row proves what was submitted, not what the Agent answered. A state DB path is only a candidate until the rollout's session_meta.id matches. A rollout can exist without a prompt-ledger row, and a /fork prompt can exist without a child rollout. A runtime-log thread is not a resumable session until state_*.sqlite confirms it (see below).

Runtime error log (logs_*.sqlite)

For "Codex is slow / keeps reconnecting / which of my sessions is erroring", read this surface before blaming the network or the service. Bucket by error shape and by hour: errors clustered in time windows mean episodic transport instability; a steady rate means a standing condition; one process_uuid failing where others are clean means a per-process cause (for example a stale in-memory token), not an outage.

-- error shapes in the last 24h
SELECT CASE WHEN feedback_log_body LIKE '%timed out%' THEN 'timeout'
            WHEN feedback_log_body LIKE '%could not be refreshed%' THEN 'token-refresh'
            WHEN feedback_log_body LIKE '%error sending request%' THEN 'send-failure'
            ELSE 'other' END AS shape, COUNT(*)
FROM logs WHERE ts >= strftime('%s','now','-24 hours') AND level IN ('ERROR','WARN')
GROUP BY shape ORDER BY 2 DESC;

-- the same buckets per hour: clustered windows or a steady rate?
SELECT strftime('%m-%d %H', ts, 'unixepoch', 'localtime') AS hr,
       SUM(feedback_log_body LIKE '%timed out%') AS timeouts,
       SUM(feedback_log_body LIKE '%could not be refreshed%') AS token_refresh
FROM logs WHERE ts >= strftime('%s','now','-72 hours') AND level IN ('ERROR','WARN')
GROUP BY hr ORDER BY hr;

-- which OS processes are failing, and since when
SELECT process_uuid, COUNT(*), datetime(MIN(ts),'unixepoch','localtime') first_seen
FROM logs WHERE feedback_log_body LIKE '%could not be refreshed%'
GROUP BY process_uuid ORDER BY 2 DESC;

Two pitfalls measured 2026-10-03:

• A thread_id found here is an app-server thread handle, not proof of a resumable rollout. Verify it exists in state_*.sqlite threads.id before handing out codex resume <id>; a logs-only id fails with "No saved session found with ID".
• strftime('%s', '<local wall time>', 'localtime') double-converts and can push the boundary into the future, returning 0 rows that look like "no data". Write boundaries as UTC literals (local wall time minus your offset) instead.

Read references/storage_and_portability.md for source discovery, timestamps, writer-lock semantics, legacy Kimi compatibility, and storage failures. Read references/codex_rollout_format.md before interpreting fork snapshots, compaction, event streams, or end reasons.

Route by the requested result

The requested output wins over the motivation. “Show my recent original inputs” means a chronological raw-input table, not feedback classification, topic mining, an interactive app, or all historical sessions.

For “how many messages/feedback did I give in this conversation; list them verbatim,” read references/user_input_reconciliation.md. Use the reconciler to compose the existing ledger and strict lineage readers. It preserves occurrences, original strings, and source coordinates. Treat exit 2 or complete: false as an incomplete result: scope_input_count: null is not zero, and verified inputs are not a complete total. Review unmatched records against their actual source before supplying any hash-bound injection exclusion. State the counting unit and cutoff; do not call message counts a count of distinct criticisms. Keep ordinary recent-input requests on the ledger-only route.

Commands

Resolve scripts relative to this SKILL.md. Do not rebuild the join with ad-hoc SQLite, Node, jq, or recursive grep.

Recent inventory

<skill-dir>/scripts/list_local_history.py \
  --source codex --index-only --cwd <workspace> --limit 20 --language zh

Writer-lock output is positive-only: a held lock proves that exact advisory lock was held during the snapshot. It does not identify the process or prove liveness; an unmarked row does not prove the Session stopped.

Locate a quoted exchange

For “which Session was this?” with a project, date, or title clue, use the existing inventory first. Select the strongest candidate by title and scope; a title match is only a lead. Do not begin with a full-corpus scan or a cross-provider index when these clues already bound discovery.

<skill-dir>/scripts/list_local_history.py \
  --source codex --index-only --cwd <workspace> --include-archived \
  --from-date <YYYY-MM-DD> --to-date <YYYY-MM-DD> --limit 20
<skill-dir>/scripts/read_codex_session.py --session <CANDIDATE_ID> --full

Omit unknown date bounds; replace --cwd with --all-projects when the workspace is unknown. A date describes when the quoted exchange happened, not when the Session was created. Inventory checks the created/updated interval for overlap, so an older Session resumed that day remains a candidate. Never restrict rollout directories to that day's creation folder. An asset's date is not a message date.

Exclude the current Session from candidate selection. Require the reader's verified identity and the quoted text in the original speaker's timeline entry (for a pasted assistant reply, ASSISTANT with a record coordinate). A user quoting that reply, a tool result, or a compacted summary alone does not prove where it was originally said. For a large briefing, use the private-file path below and inspect the matching entry with its role and record heading; a Session lookup does not require reading unrelated history or continuing the old task.

Stop once the quote and identity are verified; return the ID and source coordinate. If a candidate misses, try the remaining plausible candidates. A truncated listing, missing timestamps, an unavailable inventory, or no matching candidate is not absence: refine indexed recall and state its coverage. Do not fall back to raw corpus search.

Exact original inputs

# Global recent window, then group by Session
<skill-dir>/scripts/list_codex_user_inputs.py --recent 200 --language zh

# Expand exact Sessions already shown, preserving their order
<skill-dir>/scripts/list_codex_user_inputs.py \
  --session-id <ID-1> --session-id <ID-2> \
  --per-session 100 --language zh

Markdown is the human surface; JSON preserves the stored string value for forensic or machine use. Preserve duplicates, line order, timestamps, wording, and Session boundaries. Do not invent titles or split one Session into semantic categories.

Reconciled whole-conversation inputs

<skill-dir>/scripts/reconcile_codex_inputs.py --session <EXACT_ID> --format json

Use --through-record for an explicit inclusive cutoff in the selected session, and --omit-first / --omit-last only for exclusions the user actually requested. Neither option decides whether a message is an opening instruction or feedback. Use --format markdown for literal numbered quotations after resolving gaps. Read the linked reconciliation reference for result fields, reviewed exclusions, partial results, and deterministic fixture-only validation.

Exact Session evidence and lineage

<skill-dir>/scripts/read_codex_session.py --session <SESSION_ID> --full

Expected output: # Codex Session Evidence Briefing, verified selected identity, root-to-child fork lineage, exact parent byte boundaries, chronological handoff, compacted context, latest plan, tool calls, files, errors, end reason, and workspace state. If the state DB points to a rollout with the wrong identity, the reader must reject it and try the exact session_meta.id locator; never continue from the wrong file because its title or filename looked close. Codex 0.160 separates a logical thread from its immutable physical rollouts: the state index selects the current rollout, and history_base.thread_id references a physical rollout ID. Multiple segments require a valid indexed selection. Copies of the same physical rollout must be byte-identical or an append-only superset; divergent copies remain errors. Inherited prefixes must match both byte and ordinal boundaries. Paginated records must retain continuous stored ordinals. Missing, malformed, ambiguous, cyclic, oversized, identity-mismatched, or partial-line history fails visibly.

If the complete briefing is too large for one model context, materialize it once to a private temporary file and record its SHA-256 plus line count before reading. That one immutable file is still the single briefing; “one briefing” does not mean one stdout payload or one monolithic context load. Read bounded, non-overlapping ranges using its existing headings or exact record coordinates, keep coverage against the recorded line count, and report every unread range as a gap. Do not rerun the reader with different truncation and fuse the outputs into a complete-looking chronology.

Original tool and record evidence

After selecting a Session by identity or indexed recall, read stored tool results with the bundled reader rather than writing another JSONL parser:

<skill-dir>/scripts/read_codex_session.py --session <ID> --tools --contains '<literal clue>' --format json
<skill-dir>/scripts/read_codex_session.py --session <ID> --record <ORDINAL> --format json

--tools without --record expands the complete declared logical history in root-to-selected order, using exact ancestor prefixes. Its scope is logical_history; sources names every physical source and cutoff. Each result retains its source path, physical rollout ID, physical record ordinal, and logical_record position. A paired_call can point into an earlier segment. Separate subagent threads and attachment bytes are not expanded.

Repeat --record for several 1-based nonblank-record ordinals in the selected physical rollout. This selector keeps scope: selected_rollout_only; combining it with --tools intersects those selected physical records. --contains is a literal substring filter within the reported scope. Both modes preserve the original stored record, including every output string and field, with no content redaction or preview truncation. paired_call locates the preceding call for a result; inspect both coordinates before attributing an external message. Role labels do not establish human authorship.

Expected output reports identity, records_examined, matched_records, source coordinates, and truncated: false. Missing requested ordinals fail visibly. Zero matches apply only to the reported scope. --full still governs prose briefing clipping; it does not turn a briefing into complete tool evidence.