codex-task-inspector

Codex Task Inspector

用于统一检查 Codex 异步任务状态，避免把“仓库里的任务跟踪文件（.codex-tasks/）”与“Codex 实际数据目录里的 session/rollout 日志”混为一谈。

关键纠错（高频踩坑）

当用户提供类似 019df414-... 这种 rollout/session id 并询问“任务进展”，默认应优先检查探测出的 Codex 数据目录：

• ✅ <detected_codex_dir>/sessions/YYYY/MM/DD/rollout-...-<id>.jsonl（权威事实来源：含 task_complete、命令执行、CI watch 记录）
• ⚠️ .codex-tasks/ 只在用户明确说“看仓库里的 .codex-tasks 跟踪”或你确定该任务是由仓库派发器写入 .codex-tasks/ 时才用

如果你先去 .codex-tasks/ 导致找不到 id，这是误判路径；应立即切换到探测出的 Codex 数据目录再查。

适用场景

当用户提到以下意图时触发：

• “检查 Codex 状态”
• “看看 Codex 任务进展”
• “汇总 .codex-tasks”
• “本地任务还在跑吗”
• “CI 这边还剩什么”
• “哪个 Codex 任务失败了”

核心原则

1. 先判定本地进程，再看文件产物。 不要因为 .codex-tasks 里还有文件，就误判任务仍在运行。
2. 本地任务状态与 CI 状态分开汇报。 .pid 代表本地进程，*-last.md / *-report-*.md 代表任务产物，*.log 里的 poll 代表 CI 轮询。
3. 默认只读。 不修改 .codex-tasks/，不清理 pid/log/report，不擅自重跑任务。
4. 输出必须给出下一步建议，但只限于：继续查失败原因 / 整理状态表 / 指定某任务深挖。

标准检查顺序

第 0 步：先选对数据目录（必须）

0.0 先探测 Codex 实际数据目录

无论最终是否会落到 .codex-tasks/，先明确当前机器上的 Codex 数据目录，避免把 ~/.codex 当成硬编码事实。

优先运行：

python3 .agents/skills/codex-task-inspector/scripts/detect_codex_data_dir.py

解读规则：

• selected_source=env:CODEX_HOME → 说明当前应优先看 CODEX_HOME
• selected_source=default:$HOME/.codex → 说明当前使用默认回退目录
• markers 里若存在 config_toml/sessions_dir/session_index/history/state_db，可作为“这是活跃 Codex home”的旁证

只有当用户明确要求检查仓库 .codex-tasks/ 时，才切换到仓库路径；否则都先以探测结果为准。

输入信号 → 选路由：

• 用户给的是 019... 这种 rollout/session id，或明确说“去 Codex 默认数据目录” → 走探测出的 Codex 数据目录
• 用户明确说“看这个仓库 .codex-tasks” → 走 .codex-tasks/

0.1 在探测出的 Codex 数据目录按 rollout/session id 定位日志

优先在 <detected_codex_dir>/sessions/ 下找 rollout-*-<id>.jsonl：

export RID='019df414-235e-74e3-be4b-84f883e0ea17'
export CODEX_DIR="$(python3 .agents/skills/codex-task-inspector/scripts/detect_codex_data_dir.py | python3 -c 'import json,sys; print(json.load(sys.stdin)["selected_path"])')"
python3 - <<'PY'
import glob
import os

rid = os.environ['RID']
base = os.path.join(os.environ['CODEX_DIR'], 'sessions')
paths = glob.glob(f"{base}/**/rollout-*-{rid}.jsonl", recursive=True)
for p in sorted(paths):
    print(p)
PY