360 Secure SkillHub
360 安全技能中心

Codex History Visibility Repair

用捆绑的 Python 脚本修复 Codex Desktop 迁移后的本地历史索引：规范化 state_5.sqlite 的 provider、source 与时间戳，同步 rollout JSONL 元数据，重建 session_index.jsonl 与 history.jsonl，并重写 .codex-global-state.json 的项目根。支持 dry-run、备份目录及 app-…

lttcnly
lttcnly
热度 48.05
最近更新 2026-05-31 23:10:11
分类：自动化依赖：代码执行 / 读写文件应用场景：自动化脚本 / 数据处理 / 工作流

安装技能

复制下面的话术发给你的 Agent，它会通过 secure-skills 检索并安装该技能。

执行命令安装此 skill： npx secure-skills-cli add codex-history-visibility-repair
Metadata
name
codex-history-visibility-repair
description
Use when Codex Desktop history, migrated sessions, restored rollout JSONL files, or old projects exist on disk but do not appear in the sidebar, especially after editing .codex sessions, session_index.jsonl, history.jsonl, state_5.sqlite, archived_sessions, or .codex-global-state.json.

Codex History Visibility Repair

Overview

Use the bundled Python script to repair Codex Desktop's local history indexes after migrations. The common root cause is not missing JSONL files: thread/list filters by exact model_provider, source metadata, state database rows, and project assignments.

Quick Start

Run a dry run first:

py "$env:USERPROFILE\.codex\skills\codex-history-visibility-repair\scripts\repair_codex_history_visibility.py" --dry-run --verify-app-server

Apply the repair and verify via app-server thread/list:

py "$env:USERPROFILE\.codex\skills\codex-history-visibility-repair\scripts\repair_codex_history_visibility.py" --verify-app-server

When Codex Desktop is still running, the script schedules the repaired global state to be written after Codex exits. This prevents the running app from restoring stale empty projects from memory.

If restored sessions are still archived, include them explicitly:

py "$env:USERPROFILE\.codex\skills\codex-history-visibility-repair\scripts\repair_codex_history_visibility.py" --target all --unarchive --verify-app-server

On Windows, use py if python points to the Microsoft Store/WindowsApps placeholder. Only pass --scan-project-parent D:\object when you intentionally want every child directory under that parent to become a saved Codex project.

Workflow

  1. Confirm the symptom with local counts: session files exist but thread/list or the sidebar returns too few rows.
  2. Run --dry-run; check selectedThreads, visibleThreads, resolvedProvider, resolvedSource, projectRoots, projectRootsPruned, providerDistribution, and projectMappings.
  3. Run without --dry-run; the script creates ~/.codex/history_sync_backups/visibility-repair.*.
  4. Prefer --verify-app-server; success means both threadListStateDbOnly.returned and threadListScanMode.returned match visible thread count.
  5. If globalStateWrittenNow is false and afterExitGlobalStateScheduled is true, fully exit Codex Desktop so the scheduled writer can persist the pruned project list.
  6. Fully exit Codex Desktop, wait 5-10 seconds, reopen it.

If scan-mode verification has to read very large rollout files, increase --verify-timeout-seconds.

What The Script Repairs

File or store Repair
state_5.sqlite normalizes \\?\ prefixes, sets source, thread_source, exact model_provider, and millisecond timestamps
rollout JSONL syncs first session_meta.payload so scans do not restore stale metadata
session_index.jsonl rebuilds visible thread index
history.jsonl rebuilds prompt history entries used by desktop history surfaces
.codex-global-state.json rewrites project roots, root hints, and complete project assignments; stale saved roots with no visible conversations are pruned by default and re-applied after Codex exits when needed

Provider and source default to auto, derived from the latest visible local thread, because Codex Desktop builds can filter by exact model_provider and source. Override with --provider or --source only after verifying the active build expects another string. Use --keep-existing-project-roots only when you want to retain saved roots that are not referenced by visible threads.

Common Mistakes

  • Do not only copy files into sessions/; the sidebar also depends on SQLite and global state.
  • Do not hardcode OpenAI, openai, cli, or vscode unless thread/list proves the current app expects it.
  • Do not patch only state_5.sqlite; app-server scans rollout JSONL and can reintroduce stale provider/source metadata.
  • Do not leave old after-exit scripts running; they can overwrite the repaired global state.
  • Do not use --scan-project-parent as a default; it can re-add projects the user removed from the sidebar.
  • Do not use --protect-state-minutes for persistence; the safer default is --after-exit-global-state auto, which rewrites once after Codex exits without leaving the state file read-only.
  • Do not assume an immediate .codex-global-state.json edit will persist while Codex Desktop is running; check afterExitGlobalStateScheduled.
  • Do not publish personal backups, databases, logs, or auth files with this skill.

Publishing Hygiene

Before sharing or publishing the skill, include only:

  • SKILL.md
  • agents/openai.yaml
  • scripts/repair_codex_history_visibility.py

Never include .codex backups, SQLite databases, history.jsonl, session_index.jsonl, logs, auth files, or user-specific rollout contents.