---
name: lov-fix-codex-session
description: >
  诊断并修复无法恢复的 Codex 会话：定位悬挂 tool call/output，并在切换模型
  提供商后处理 Model provider not found 的 provider 绑定，恢复交付物与可继续路径。
license: MIT
compatibility: "Portable Agent Skills format. Python 3.8+ standard library only for the
  diagnostic CLIs; reads ~/.codex rollout JSONL and state_*.sqlite, and can sync
  thread provider metadata. No network or external CLI required."
metadata:
  author: skill-publisher
  version: "0.2.0"
  card_standard: lovstudio/skill-card/v1
  content_class: deterministic-output
  tags:
    - codex
    - session-repair
    - rollout
    - provider-sync
    - troubleshooting
    - tool-call
---

# 会话救援 · Session Rescuer

把一条无法继续的 Codex 线程诊断清楚，并给出能继续的产物。它覆盖两种常见
故障：tool call 没有配对的 tool output，以及切换 provider / 中转站后
`Model provider not found`。前者可以从磁盘交付物接手或生成可恢复 rollout
副本；后者只同步 `state_*.sqlite` 的 provider 绑定，不改写 rollout。

## Triggers

### Activate when

- “修复 codex://threads/… 里报错：No tool output found for tool call …”
- “修复 codex://threads/… 里报错：Model provider `custom` not found”
- “切换中转站 / CC Switch 后旧 Codex 线程打不开，需要把 model_provider 统一为当前 provider”
- “这条 Codex 会话继续不了了 / 会话卡死在 systemError / 会话恢复不了”
- “帮我诊断这个 Codex 线程为什么无法继续，怎么救回里面的产物”
- “Fix this stuck Codex session showing 'No tool output found for tool call …'”
- “Sync all Codex thread model_provider values to the current provider name”
- “Diagnose and recover a Codex thread that can no longer be resumed.”

### Do not activate when

- 只是要打开、导航到某个 Codex 会话 —— 交给 `lov-open-codex-session`。
- 只是要检索过去聊过什么 / 上次怎么解决的 —— 交给 `lov-search-chat`。
- 只修改 `config.toml`、不处理 thread 元数据 —— 交给 provider manager / CC Switch；
  本 Skill 处理的是 thread 与配置已经不一致后的恢复。
- 面向任意软件错误的通用定位与修复 —— 交给 `lov-fix-general`；本 Skill 只处理
  Codex 会话持久化状态与 provider 绑定的特定故障。
- 要把修复后的源发布 / 上架 / 上传 —— 交给 `lov-skill-publisher`。

## User Profile (cross-session)

`skill.yaml` 声明 `user-profile/v1`。每次运行开始先读共享的 user、brand、
workspace、preferences 与 `skills.lov-fix-codex-session` 命名空间。线程 id、
rollout 路径、转录内容、秘密或完整私有路径都不写入持久 Profile；涉及会话的
标识只在当前请求内使用。字段解析优先级：当前请求 → 项目上下文 → Skill 记录
→ 共享偏好 → 共享 user/brand Profile → 安全默认值。

When the user directly states a durable preference or brand fact, persist it
through `scripts/profile_store.py` and report the saved profile path. Put
Skill-specific values under `records.<field>`; use `brand.<field>` or
`user.<field>` for shared values. Do not persist inferred secrets or credentials.
See `references/user-profile.md` for the complete contract.

## Skill Group Composition

Read `references/skill-composition.md` before deciding whether to invoke or
extend any adjacent capability. The record distinguishes optional upstream and
downstream handoffs from embedded Kit modules. Do not silently depend on a
sibling Skill that is not shipped with this source.

## Workflow (MANDATORY)

**You MUST follow these steps in order.**

### Step 0: Resolve skill root, dependencies, and runtime context

- Use `SKILL_DIR` if the environment provides it.
- Otherwise infer the installed skill directory from the current skill context.
- Verify every required local module, reference, script, and asset before work.
- If a required resource is missing, name its expected relative path and stop
  before producing a partial result.

When running scripts manually:

```bash
export SKILL_DIR="/path/to/lov-fix-codex-session"
```

`context.profile` 按上述优先级解析。用户直接说出的、希望跨会话保留的值，用
`scripts/profile_store.py record --confirm` 原子写回并报告保存路径；推断值、
秘密、token、cookie 与 key 不入库。

### Step 1: Understand the requested outcome

- Separate internal context from user-visible output.
- Confirm the input, intended audience, expected deliverable, and evidence gaps.
- Record one real user case before calling the Skill complete. The case must show
  the input, the prompt or minimum brief, and the output; do not invent results.
- 先判断故障类型：报错含 `Model provider ... not found` 时，输入是当前
  `config.toml` / `state_*.sqlite`；报错含 `No tool output found` 时，输入是
  **线程 id / codex:// 链接**。输出始终是**一份诊断结论 + 可继续的恢复路径**；
  不要把实现细节作为用户制品。

### Step 1.5: Analyze nearby Skills before implementation

- Inspect related local and installed Skills by routing contract and concrete
  input/output, not by filename alone.
- Record upstream, core, downstream, overlap, and not-composed decisions in
  `references/skill-composition.md`.
- Keep sibling Skills optional and artifact-based. When stages require hard
  coupling for one outcome, create a self-contained Kit instead.
- 本 Skill 是 Codex 会话恢复这一窄领域的核心原子，与通用修复、会话导航、
  会话检索是相邻不重叠关系；见 `references/skill-composition.md`。

### Step 2: Execute the workflow

1. **故障分诊**：错误是 `Model provider ... not found` 时走 `A`；否则按
   `B` 处理悬挂 tool call。
2. **A. 同步 provider 绑定（只读预演）**：
   ```bash
   python3 "$SKILL_DIR/scripts/sync_thread_provider.py" --codex-home "$HOME/.codex" --json
   ```
   确认 `candidate_ids` 只包含真正过期的 provider（默认 `stale-only`，不会
   动 built-in 的 `openai`）。然后退出 Codex Desktop，运行：
   ```bash
   python3 "$SKILL_DIR/scripts/sync_thread_provider.py" --codex-home "$HOME/.codex" --apply
   ```
   脚本会先做 SQLite 一致备份再写 `threads.model_provider`。**不要重写
   `sessions/` 下的 JSONL**：paginated 会话的 `end_byte_offset` 会因此失效。
3. **B. 解析标识**：若错误是悬挂 tool call，从 `codex://threads/<uuid>`、
   线程 id 提取 `thread_id`；若给的是链接，只取 UUID。
4. **B. 定位 rollout**：优先读 `state_5.sqlite` 的 `threads.rollout_path`；拿不到
   就在 `~/.codex/sessions` 下按线程 id 搜索 `rollout-*.jsonl`。
5. **B. 只读诊断**：
   ```bash
   python3 "$SKILL_DIR/scripts/fix_codex_session.py" "$thread_id" --json
   ```
   核对报告中的 `dangling_calls` 与 `last_turn_error`；`poisoned=true` 即为毒点。
6. **恢复交付物**：找出该线程在项目目录里已生成的 Markdown、PDF、图片、代码。
   这些是真正值得抢救的产物，先把它们确认下来并回读。
7. **给出恢复路径**（tool-call 场景二选一，优先第一条）：
   - 在已保存交付物的基础上新开一条干净线程，把收尾工作做完（不要继续旧线程）。
   - 若必须沿用同一线程，运行：
     ```bash
     python3 "$SKILL_DIR/scripts/fix_codex_session.py" "$thread_id" --fix
     ```
     生成 `<rollout>.repaired.jsonl`（不覆盖原文件，宿主未运行线程时才用
     `--write`，且会留 `.bak` 备份）。告知用户：部分宿主需重启或重新加载后
     修复才生效。
8. **验证**：provider 场景回读 `threads.model_provider` 分布并确认无过期 provider；
   tool-call 场景确认修复副本仍是合法 JSONL、`dangling_calls` 已清空、交付物可打开。
   报告具体文件与恢复结论，不要回读被丢弃的私密内容。

### Step 3: Validate the deliverable

- Verify completeness, factual support, user-visible copy, and output paths.
- Report concrete files or results, plus any remaining evidence gaps.
- Validate `skill-card.yaml`, `cases/cases.json`, and `pricing-card.yaml` as the
  standard trust bundle for this Skill.

## Dependencies

- Python 3.8+（仅标准库；`fix_codex_session.py` 与 `sync_thread_provider.py`
  都不需要第三方包）。
- 可读的 Codex 会话目录（默认 `~/.codex/sessions`）；线程 id 用于定位。
- 可读的 `config.toml` 与 `state_*.sqlite`；provider 同步只写 SQLite 索引。
- 宿主若提供 `read_thread` / `list_threads` 等能力，可用于确认线程当前状态。
- 其他 Skill 均为可选手柄，不是运行前提：`lov-open-codex-session`（导航）、
  `lov-fix-general`（通用修复）、`lov-search-chat`（会话检索）。