# Codex Context Tracing

## Current Design

- `createRunWorkspace` and `createLiveRunWorkspace` materialize `input/`, `prompt/`, `work/`, `output/`, and `trace/`.
- `CodexTicketAgentRunner` runs two independent Codex SDK calls: the main ticket analysis and the reply-normalization pass.
- Existing trace files store raw SDK `usage` and returned `items`, but there is no compact per-call accounting for prompt/input size, returned command output size, or incremental token shape.

## Risks

- `cached_input_tokens` is per SDK call cache behavior, not proof that those tokens came only from fixed Codex system context.
- Large command outputs, full skill files, or broad reference files can enter the next turn's transcript and then become cached in later turns.
- Full raw traces are too large for routine diagnosis and can hide the actual context contributors.

## Target Contract

- Write `trace/context-trace.json` for each run.
- Record each Codex SDK call independently.
- For each call, record only metadata and sizes: input text bytes, output schema bytes, workspace `input/` and `prompt/` file sizes before the call, SDK usage, uncached token count, returned item type counts, command output bytes, agent-message bytes, web-search query bytes, serialized item bytes, and top returned item contributors.
- Top item entries may include a redacted and truncated command/search preview for diagnosis.
- Do not record secrets or full payload bodies in the summary trace.

## Implementation Steps

- Add a context-trace helper module that snapshots run inputs/prompts and summarizes Codex turn items.
- Hook the helper around both main analysis and reply-normalization calls.
- Add local contract tests for usage accounting, file-size accounting, command-output accounting, and append behavior across multiple LLM calls.

## Verification Checklist

- `npm test`
- Inspect a generated `trace/context-trace.json` from a dry-run or unit test.
- Confirm the trace has one entry per Codex call and does not include full command output.