trace-to-skill 0.1.38 → 0.1.39

package/docs/USE_CASES.md

@@ -21,7 +21,7 @@ What it proves:
 Recommended CI surface:
 
 ```yaml
-- uses: grnbtqdbyx-create/trace-to-skill@v0.1.38
+- uses: grnbtqdbyx-create/trace-to-skill@v0.1.39
   with:
     mode: all
     doctor-threshold: "85"
@@ -61,7 +61,58 @@ npx trace-to-skill analyze ./runs --format json
 
 This catches signals such as Windows sandbox setup refresh failures, `os error 740`, `CodexSandboxOffline` ownership drift, ACL denial, approval-policy mismatch, and Full Access sessions behaving like workspace-write or on-request mode.
 
-## 4. Quota And Usage-Limit Evidence
+## 4. Codex Auth And Connectivity Triage
+
+Use this when Codex cannot log in, exchange an auth token, stream a response, or connect through a container, proxy, VPN, corporate CA, IPv6 network, or Cloudflare challenge.
+
+```bash
+npx trace-to-skill analyze ./runs --format json
+```
+
+This catches signals such as `token_exchange_failed`, `auth.openai.com/oauth/token`, `codex_login::server`, `cf-mitigated: challenge`, missing `ca-certificates`, `update-ca-certificates`, `CODEX_CA_CERTIFICATE`, IPv6 fallback evidence, proxy/MITM TLS failures, and `stream disconnected before completion` on `chatgpt.com/backend-api/codex/responses`.
+
+## 5. Codex Mobile And Remote-Control Route Health
+
+Use this when Codex mobile, SSH remote, or desktop remote-control says it is connected but commands do not reach the expected host, workspace, or app-server.
+
+```bash
+npx trace-to-skill analyze ./runs --format json
+```
+
+This catches signals such as `Waiting for desktop`, `Directory: Unavailable`, stale `server_name` enrollment, stale remote-control listener, `127.0.0.1:14567`, missing cached helper files such as `codex-windows-sandbox-setup.exe` or `codex-command-runner.exe`, empty backend environments, stale Android session lists, and temporary recovery after re-pairing or listener restart.
+
+## 6. Codex MCP Runtime Triage
+
+Use this when MCP tools are configured and visible, but Codex cannot actually call them at runtime.
+
+```bash
+npx trace-to-skill analyze ./runs --format json
+```
+
+This catches signals such as `user cancelled MCP tool call`, `request_user_input is not supported in exec mode`, `Approve app tool call?`, `tool_call_mcp_elicitation`, routed callable names like `mcp__node_repl__js` becoming `unsupported call`, deferred discovery dropping namespace or `serverName`, `tools/list` succeeding while Codex routing fails, and stdio transport lifecycle failures such as `Transport closed`, `stdin_end`, `stdin_close`, `transport_close`, or stderr backpressure.
+
+## 7. Codex Resume And Session State Triage
+
+Use this when long Codex sessions become difficult to resume, Desktop history rendering gets sluggish, or local state migrations break goals/projects/history.
+
+```bash
+npx trace-to-skill analyze ./runs --format json
+```
+
+This catches signals such as `codex resume` picker hangs, `codex resume <id>` working while the picker freezes, large `rollout-*.jsonl` histories, high JSONL line and `response_item` / `event_msg` / `function_call` counts, large `input_image` payloads, slow `thread/resume` and `thread/goal/get` timings, `Could not load archived chats`, resume compression dropping the last 3-5 turns, `state_5.sqlite` / `goals_1.sqlite` migration mismatches, `no such table: thread_goals`, stale `projectless-thread-ids`, and `thread-workspace-root-hints` reverting after restart.
+
+## 8. Codex Token Burn Attribution
+
+Use this when Codex usage drains faster than expected and the trace needs to separate useful model work from orchestration overhead.
+
+```bash
+npx trace-to-skill analyze ./runs --format json
+npx trace-to-skill codex-report ./runs --output openai-codex-issue.md
+```
+
+This catches signals such as tokens `burning very fast`, usage dropping by visible percentages after one or two prompts, weekly allowance depletion, 5-hour usage reaching 0%, large `input` plus `cached input` totals, `write_stdin` empty polling, background commands repeatedly reporting no new output, idle app usage, compaction tax, retry/tool loops, and missing attribution between normal turns, compaction, background polling, subagents, and retries.
+
+## 9. Quota And Usage-Limit Evidence
 
 Use this when Codex blocks a prompt with a usage-limit message but another surface still shows remaining quota.
 
@@ -71,7 +122,33 @@ npx trace-to-skill analyze ./runs --format json
 
 This catches traces where `/status` or the usage page shows remaining 5h or weekly quota, accounts appear to share limits unexpectedly, a Team account inherits a Plus account's limit state, or quota reset times jump after logout/login.
 
-## 5. GitHub Context Guard
+## 10. OpenAI Codex Issue Report
+
+Use this when you want to file or update an OpenAI/Codex issue with a concise, evidence-backed report instead of pasting a full transcript.
+
+```bash
+npx trace-to-skill redact ./runs --output redacted-runs
+npx trace-to-skill codex-report redacted-runs --output openai-codex-issue.md
+```
+
+The report includes the likely Codex failure class, line-linked evidence, diagnostics to attach, and a privacy checklist. This is useful for issues about auth/connectivity, sandbox setup, remote-control routing, MCP runtime calls, resume/session-state failures, quota mismatches, and context compaction.
+
+For a cluster-to-command map of current Codex issue patterns, see [CODEX_ISSUE_MAP.md](CODEX_ISSUE_MAP.md).
+
+## 11. Sensitive File Access Evidence
+
+Use this when a trace suggests an agent read, attached, uploaded, diffed, or indexed credential-bearing files.
+
+```bash
+npx trace-to-skill analyze ./runs --format json
+npx trace-to-skill codex-report ./runs --output openai-codex-issue.md
+```
+
+This catches signals such as `.env`, `.env.production`, `.npmrc`, `.pypirc`, `.netrc`, `.aws/credentials`, `.kube/config`, `.docker/config.json`, private-key PEM blocks, `.sqlite`, `.db`, `secrets.yaml`, and production secret manifests entering agent context.
+
+Before publishing evidence, run `trace-to-skill redact` and attach only redacted excerpts plus the file path/class.
+
+## 12. GitHub Context Guard
 
 Use this before an agent reads untrusted GitHub text.
 
@@ -88,7 +165,7 @@ Use it when:
 - a bot asks Codex to triage untrusted user reports
 - logs or comments might contain instructions like "ignore previous instructions" or "print secrets"
 
-## 6. Failed Agent Run To Reviewable Rule
+## 13. Failed Agent Run To Reviewable Rule
 
 Use this when a coding agent made a repeated workflow mistake.
 
@@ -106,7 +183,7 @@ Recommended maintainer loop:
 4. Copy only evidence-backed rules into the real policy file.
 5. Run `eval` or `scorecard` in CI so the same failure does not silently return.
 
-## 7. Privacy-Preserving Adoption
+## 14. Privacy-Preserving Adoption
 
 Use this when you want public evidence without leaking private traces.
 

package/fixtures/codex-connectivity.md

@@ -0,0 +1,32 @@
+# Codex auth and connectivity failure fixture
+
+A Dev Container using Ubuntu 24.04 failed after the browser login step:
+
+```text
+2026-05-26T19:42:22.056568Z ERROR codex_login::server: oauth token exchange transport failure is_timeout=false is_connect=true is_request=true error=error sending request for url (https://auth.openai.com/oauth/token)
+Token exchange error: error sending request for url (https://auth.openai.com/oauth/token)
+codex_login::server: login callback token exchange failed
+```
+
+The environment later showed missing ca-certificates setup before the OpenAI extension was installed:
+
+```Dockerfile
+RUN apt-get update && apt-get install -y ca-certificates && update-ca-certificates
+```
+
+The API key path also looked connected in the UI but produced the same transport failure when Codex tried to reach ChatGPT:
+
+```text
+stream disconnected before completion: Transport error: network error: error decoding response body
+Reconnecting... 1/5 (stream disconnected before completion: error sending request for url (https://chatgpt.com/backend-api/codex/responses))
+```
+
+Another trace from the same issue class showed IPv6 and proxy-specific evidence:
+
+```text
+auth.openai.com resolves to IPv6 first; curl -4 works, curl -6 hangs.
+Cloudflare returned cf-mitigated: challenge when the corporate MITM proxy intercepted auth.openai.com.
+CODEX_CA_CERTIFICATE was set but did not help this WAF challenge.
+```
+
+The final report must include the Codex version, container image, proxy/VPN state, DNS IPv4/IPv6 checks, CA variables, and whether browser login, device auth, and API-key auth fail differently.

package/fixtures/codex-mcp-runtime.md

@@ -0,0 +1,51 @@
+# Codex MCP runtime failure fixture
+
+A minimal MCP server was configured correctly and `tools/list` returned the expected tool, but Codex failed at runtime.
+
+## Non-interactive approval cancellation
+
+```json
+{"type":"item.started","item":{"type":"mcp_tool_call","server":"minimal","tool":"ping","status":"in_progress"}}
+{"type":"item.completed","item":{"type":"mcp_tool_call","server":"minimal","tool":"ping","status":"failed","error":{"message":"user cancelled MCP tool call"}}}
+```
+
+Logs showed:
+
+```text
+request_user_input is not supported in exec mode
+Approve app tool call?
+tool_call_mcp_elicitation = true
+maybe_request_mcp_tool_approval called for a custom MCP tool
+```
+
+## Unsupported routed callable
+
+The server could execute the tool manually, but Codex routed the exposed name incorrectly:
+
+```text
+tools/list returned js for node_repl
+manual tools/call succeeded
+runtime routes mcp__node_repl__js as unsupported call
+unsupported call: mcp__node_repl__js
+```
+
+Another trace showed deferred tool discovery replay losing namespace metadata:
+
+```text
+Namespaced MCP tool calls fail after deferred tool discovery because replayed function_call drops namespace.
+function_call omitted namespace and serverName, so the runtime received an un-namespaced tool name.
+```
+
+## Stdio transport lifecycle
+
+A healthy stdio MCP server returned one result, exited, and Codex reused a closed client:
+
+```text
+tool call failed for `minimal_stdio/echo`
+Caused by:
+    Transport closed for MCP stdio client
+StdioServerTransport shutdown: stdin_end
+StdioServerTransport shutdown: transport_close
+```
+
+The report should include the Codex version, MCP server name and transport, callable name, whether `tools/list` and manual `tools/call` succeed, approval policy, sandbox mode, exec/non-interactive mode, elicitation setting, namespace/serverName metadata, item JSONL, stderr/backpressure evidence, and whether a transport restart changes the result.

package/fixtures/codex-remote-control.md

@@ -0,0 +1,29 @@
+# Codex remote-control route health fixture
+
+A Windows Desktop remote-control route reported connected, but mobile commands did not execute reliably.
+
+The local diagnostic showed the listener was stale:
+
+```text
+remote-control: listening on 127.0.0.1:14567, pid=18452, exe=C:\Users\user\.codex\cache\7dea4a003bc76627\codex.exe, bundle_complete=false, sandbox_helper=missing
+candidate cache directory has codex.exe but is missing codex-windows-sandbox-setup.exe and codex-command-runner.exe
+```
+
+Mobile still displayed a weak connected state:
+
+```text
+ChatGPT mobile pairing stuck on Waiting for desktop
+remote-control stays connecting
+backend environments returns empty
+Android Codex Mobile shows "Directory: Unavailable" after Desktop conversation updates
+Revoking the Android device and re-pairing restores access temporarily.
+```
+
+Another trace showed stale enrollment state:
+
+```text
+codex remote-control reuses persisted enrollment with stale server_name, causing silent WebSocket disconnect
+remoteControl/status/read succeeded, but the next mobile command never reached the active app-server.
+```
+
+The report should include desktop/app/CLI versions, mobile OS/app version, host id, listener pid/executable path, bound port, cache directory id, helper-file completeness, active server_name/enrollment, workspace root, last mobile command id, and whether restarting the listener or re-pairing changes the route.

package/fixtures/codex-session-state.md

@@ -0,0 +1,62 @@
+# Codex session resume and local state failure fixture
+
+This fixture captures a long-running Codex Desktop and CLI session that became hard to resume after local history grew large.
+
+## Resume picker hangs on large JSONL history
+
+The user reported:
+
+```text
+codex resume interactive picker hangs/freezes when session files are large.
+The UI renders the list, but Enter has no effect.
+codex resume <id> works fine as a workaround.
+```
+
+The session inventory showed large rollout files:
+
+```text
+rollout-2026-05-11T23-56-03-019e17c0.jsonl  17.7 MB
+session files include large jsonl rollout history and the picker freezes when that session is visible.
+```
+
+## State migration mismatch
+
+After a Codex update, goal state reads failed:
+
+```text
+state_5.sqlite migration version 34: drop thread goals
+goals_1.sqlite was created, but goals_1.sqlite.thread_goals was empty.
+Runtime still queried the old thread_goals table.
+error returned from database: no such table: thread_goals
+codex_core::goals failed to read thread goal for continuation
+```
+
+## Desktop thread open is sluggish
+
+A Windows Codex Desktop trace showed the same session-state path causing slow UI:
+
+```text
+Thread id: 019e5fe0-5e81-7a02-abef-f2bde9c26a4a
+Rollout/history size: 242.5 MB
+50,589 JSONL lines
+29,169 response_item records
+21,178 event_msg records
+10,538 function_call records
+112 input_image records
+Max JSONL line: 3,631,856 characters
+thread/resume took 7,760 ms
+thread/goal/get took 8,606 ms
+Codex Desktop becomes extremely sluggish with high app-server/renderer CPU when opening a large local thread.
+```
+
+## Resume compression drops recent context
+
+Another trace showed the resumed agent could not continue:
+
+```text
+codex resume context compression drops recent conversation context.
+The last 3-5 turns are discarded, including the user's latest instruction, recent errors, and file paths.
+The resumed session is effectively amnesic and cannot continue the previous task.
+```
+
+The report should include the Codex app and CLI versions, OS, thread id, rollout size, JSONL line count, response/event/function/image counts, largest line size, thread/resume and thread/goal/get timings, renderer/app-server CPU and memory, state database paths and migration versions, whether `codex resume <id>` works, whether a new thread works, and backup steps before any manual state edit.

package/fixtures/codex-token-burn.md

@@ -0,0 +1,42 @@
+# Codex unexpected usage fixture
+
+These notes preserve reports where the user cannot tell whether the cause is model choice, background polling, compaction, retries, or idle app activity.
+
+## General token burn regression
+
+```text
+Am I the only one still seeing my tokens burning very fast after today's extension update?
+Just by writing 1 or 2 prompts, usage drops by 1%.
+Within 2 hours of working I managed to burn through ~20% of my tokens.
+Token usage: total=742,555 input=697,188 (+ 9,077,504 cached) output=45,367 (reasoning 11,450)
+```
+
+## Idle app usage
+
+```text
+Codex is using daily usage even when it is not doing anything.
+I opened the app, went to eat, and came back to all 5-hour usage consumed plus 15% of weekly usage.
+Just by being open it used it all.
+```
+
+## Background polling loop
+
+```text
+Background process polling wastes tokens.
+Each write_stdin empty poll triggers a full API turn with entire conversation history.
+The model keeps polling while no new output is available and the process is still running.
+During background waits, the cadence is about one poll every 5-10 seconds.
+Cached tokens are still charged by some API/proxy billing paths.
+```
+
+## Compaction and replay cost
+
+Another report said:
+
+```text
+My Pro weekly allowance was almost fully depleted in about two days under normal usage.
+The weekly usage limit depletes unusually fast on 5.5, worsened by unstable context compaction.
+Failed context compaction forces users to restart tasks and re-explain project state, creating compaction tax.
+```
+
+The report should include the plan/workspace, app or CLI version, model, reasoning effort, speed mode, large context setting, subagent and /review usage, recent `/status` and dashboard deltas, token totals including cached input/output/reasoning, background process ids, write_stdin poll cadence, compaction attempts, retry/tool-loop counts, whether the app was idle, and before/after usage percentages.

package/fixtures/sensitive-file-access.md

@@ -0,0 +1,14 @@
+# Codex Sensitive File Access Trace
+
+User report:
+
+Codex indexed the repository before I could exclude sensitive files. The trace shows:
+
+```text
+exec_command: cat .env.production
+exec_command: sed -n '1,80p' ~/.aws/credentials
+diff --git a/.env b/.env
+-----BEGIN OPENSSH PRIVATE KEY-----
+```
+
+Expected behavior: the agent should stop and ask for an explicit redaction or exclusion rule before putting those files into context.

package/llms.txt

@@ -16,7 +16,13 @@ Runtime: Node.js 20+
 - failed tests hidden behind optimistic summaries
 - Codex context compaction failures such as remote compact stream disconnects, `context_length_exceeded`, stuck automatic compaction, and `unknown variant auto`
 - Codex sandbox and permission failures such as setup refresh errors, `os error 740`, `CodexSandboxOffline` ownership drift, ACL denial, and approval-mode downgrades
+- Codex auth and connectivity failures such as `token_exchange_failed`, `auth.openai.com/oauth/token`, missing `ca-certificates`, proxy or MITM TLS behavior, IPv6 fallback problems, Cloudflare challenge responses, and ChatGPT stream disconnects
+- Codex mobile and remote-control route health failures such as `Waiting for desktop`, `Directory Unavailable`, stale listeners on `127.0.0.1:14567`, stale `server_name` enrollment, empty backend environments, and incomplete helper bundles
+- Codex MCP runtime failures such as cancelled non-interactive approvals, `request_user_input is not supported in exec mode`, dropped namespace or `serverName` metadata, `unsupported call: mcp__...__...`, and closed `StdioServerTransport` sessions
+- Codex resume and session-state failures such as frozen resume pickers, large rollout JSONL histories, sluggish Desktop thread rendering, dropped recent context after resume, archived chat loading failures, and `state_5.sqlite` / `goals_1.sqlite` migration drift
+- Codex token-burn and usage-drain failures such as background `write_stdin` polling, idle app usage, compaction tax, retry/tool loops, cached-token-heavy turns, fast-mode drift, subagent fan-out, and unclear usage attribution
 - Codex quota and usage-limit mismatches where `/status` or the usage page shows remaining quota, accounts share limits unexpectedly, or 5h and weekly quotas move together
+- sensitive-file access in traces, including `.env`, private keys, package auth files, cloud credentials, local databases, and production secret manifests entering agent context
 - hallucinated files and broad over-editing
 - conflicting `AGENTS.md`, `CLAUDE.md`, Cursor, Copilot, or Gemini instructions
 - stale path references, missing `@file.md` includes, nested `AGENTS.md` visibility gaps, invalid UTF-8, and oversized instruction files that can make Codex follow wrong or truncated guidance
@@ -34,6 +40,7 @@ failed agent run -> failure class -> evidence-backed AGENTS.md/SKILL.md suggesti
 
 - README: https://github.com/grnbtqdbyx-create/trace-to-skill#readme
 - Use cases: https://github.com/grnbtqdbyx-create/trace-to-skill/blob/main/docs/USE_CASES.md
+- Codex issue map: https://github.com/grnbtqdbyx-create/trace-to-skill/blob/main/docs/CODEX_ISSUE_MAP.md
 - Discovery summary: https://github.com/grnbtqdbyx-create/trace-to-skill/blob/main/docs/DISCOVERY.md
 - Adoption guide: https://github.com/grnbtqdbyx-create/trace-to-skill/blob/main/docs/ADOPTION_GUIDE.md
 - Failure taxonomy: https://github.com/grnbtqdbyx-create/trace-to-skill/blob/main/docs/FAILURE_TAXONOMY.md
@@ -51,6 +58,7 @@ npx trace-to-skill lint-agents .
 npx trace-to-skill guard-github-event "$GITHUB_EVENT_PATH"
 npx trace-to-skill redact ./runs --output redacted-runs
 npx trace-to-skill analyze ./runs
+npx trace-to-skill codex-report ./runs --output openai-codex-issue.md
 npx trace-to-skill suggest ./runs --target agents-md
 npx trace-to-skill eval ./runs --threshold 80
 npx trace-to-skill benchmark
@@ -61,7 +69,7 @@ npx trace-to-skill init --comment --sarif
 ## GitHub Action
 
 ```yaml
-- uses: grnbtqdbyx-create/trace-to-skill@v0.1.38
+- uses: grnbtqdbyx-create/trace-to-skill@v0.1.39
   with:
     mode: all
     doctor-threshold: "85"
@@ -91,5 +99,23 @@ npx trace-to-skill init --comment --sarif
 - Codex OSS maintainer automation evidence
 - Codex sandbox setup refresh failed
 - Windows sandbox permission failure for Codex CLI
+- Codex token_exchange_failed auth.openai.com oauth token
+- Codex stream disconnected before completion chatgpt backend api responses
+- Codex ca-certificates update-ca-certificates Dev Container
+- Codex remote-control stale listener 127.0.0.1:14567
+- Codex mobile Waiting for desktop Directory Unavailable
+- Codex MCP unsupported call mcp__node_repl__js
+- Codex MCP tools/list succeeds but runtime call fails
+- Codex MCP Transport closed StdioServerTransport
+- Codex resume picker hangs with large session files
+- Codex Desktop sluggish opening large rollout JSONL thread
+- Codex state_5.sqlite no such table thread_goals
+- OpenAI Codex issue report from failed trace
+- Codex bug report evidence checklist
+- Codex token burn write_stdin background polling
+- Codex cached input token usage drain
+- Codex compaction tax weekly usage depleted
 - Codex usage limit despite remaining quota
 - Codex quota mismatch and rate limit debugging
+- Codex exclude sensitive files from agent context
+- detect .env private key credential file access in agent traces

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trace-to-skill",
-  "version": "0.1.38",
+  "version": "0.1.39",
   "description": "Turn failed AI coding-agent runs into reusable AGENTS.md rules, SKILL.md files, and eval evidence.",
   "type": "module",
   "main": "dist/src/index.js",
@@ -21,8 +21,10 @@
     "docs/ADOPTION_GUIDE.md",
     "docs/AGENTS_LINT.md",
     "docs/BENCHMARK.md",
+    "docs/CODEX_ISSUE_MAP.md",
     "docs/DISCOVERY.md",
     "docs/FAILURE_TAXONOMY.md",
+    "docs/RELEASE.md",
     "docs/SCORECARD.md",
     "docs/USE_CASES.md",
     "examples",
@@ -63,9 +65,24 @@
     "sandbox-permission",
     "codex-sandbox",
     "windows-sandbox",
+    "codex-connectivity",
+    "codex-auth",
+    "token-exchange-failed",
+    "codex-remote-control",
+    "codex-mobile",
+    "codex-mcp",
+    "mcp-runtime",
+    "codex-session",
+    "codex-resume",
+    "codex-issue-report",
+    "openai-triage",
+    "codex-token-burn",
+    "codex-usage",
     "quota-mismatch",
     "codex-rate-limits",
     "usage-limit",
+    "sensitive-files",
+    "codex-privacy",
     "evals",
     "open-source-maintainers",
     "self-improvement",

package/schemas/analysis-result.schema.json

@@ -65,10 +65,16 @@
         "over_editing",
         "unsafe_command",
         "secret_exposure",
+        "sensitive_file_access",
         "hidden_unicode",
         "prompt_injection",
         "context_compaction",
         "sandbox_permission",
+        "codex_connectivity",
+        "codex_remote_control",
+        "codex_mcp_runtime",
+        "codex_session_state",
+        "codex_token_burn",
         "quota_mismatch",
         "mcp_risk",
         "weak_evidence"