Codex Skill Loader Broken Symlink Recovery

---
name: codex-skill-loader-broken-symlink-recovery
description: Diagnose Codex startup failures in workspace-hub caused by a broken `.Codex/skills/skills` symlink and recover without misattributing the failure to issue scope.
version: 1.0.0
author: Hermes Agent
license: MIT
tags: [codex, workspace-hub, symlink, troubleshooting, skills-loader]
---

# Codex skill-loader broken symlink recovery

Use when a Codex run in `workspace-hub` fails early with an error like:

- `failed to stat skills entry ... /workspace-hub/.Codex/skills/skills (symlink): No such file or directory`

## Why this matters

This failure happens before issue execution meaningfully begins. It is easy to mistake it for a prompt, auth, or issue-scope problem. In practice, the cause can be a broken repo-local symlink under `.Codex/skills/`.

## Detection

1. Inspect the failing process log for `codex_core_skills::loader` errors.
2. Check whether the offending path is a symlink:
   - `test -L .Codex/skills/skills && readlink .Codex/skills/skills`
3. Check whether the symlink target actually exists from the repo root:
   - `test -e .Codex/skills/skills && echo exists || echo missing`

Known bad state observed in `workspace-hub`:
- `.Codex/skills/skills -> ../.Codex/skills`
- from repo root this resolved to a missing path, so Codex failed before execution.

## Recovery pattern

1. Treat the run as infrastructure-blocked, not issue-blocked.
2. Salvage any other active runs first; do not assume all provider runs are invalid.
3. Verify issue completion independently using:
   - `process list/poll/log`
   - `git status`
   - `git log --oneline -n 5`
   - `gh issue view <n>`
4. If another run already completed the issue, clean leftover drift and close via evidence rather than rerunning blindly.
5. Before launching new Codex work from the root repo, verify the symlink path again.

## Practical notes

- A watch-pattern `error` notification from Codex can be a repo bootstrap defect rather than task failure.
- Keep external git verification authoritative; Codex/Codex may still leave unrelated residue like temp prompt files or runtime drift files.
- In workspace-hub, also check for stray edits to `scripts/testing/coverage-results.json` after agent runs and revert them unless explicitly in scope.

## Minimal verification bundle

Use this bundle before deciding to rerun:

```bash
git -C /path/to/worktree status --short
git -C /path/to/worktree log --oneline -n 5
gh issue view <issue> --json number,title,state,comments,url
```

If the issue is already landed/closed, prefer cleanup + closeout over another Codex launch.