Question 1

How to fix Ouroboros 'WinError 123' checkpoint error on Windows?

Accepted Answer

Upgrade Ouroboros to version 0.40.0 or later. This release sanitizes colons and other Windows-reserved characters (< > : " / \ | ? *) from checkpoint filenames, preventing the 'WinError 123' caused by invalid NTFS characters. No manual workaround is needed after upgrading. If upgrade is not possible, temporarily avoid seed_ids containing colons, but this is not a reliable fix.

Question 2

How to fix 'legacy profile' error when running 'ooo interview' with Codex CLI 0.134+?

Accepted Answer

This error occurs because Codex CLI ≥0.134.0 uses profile‑v2 files (e.g. ~/.codex/ouroboros‑frontier.config.toml) and rejects legacy [profiles.*] tables in ~/.codex/config.toml. A fix is underway in PR #1268. Until it merges, manually migrate: 1) Move each [profiles.ouroboros‑*] block from ~/.codex/config.toml into its own file ~/.codex/ouroboros‑*.config.toml. 2) Remove the legacy section from config.toml. Alternatively, run ouroboros setup again after the PR lands.

Question 3

How to fix UnicodeDecodeError 'gbk codec can't decode byte' when running ouroboros uninstall on Windows?

Accepted Answer

This happens on Windows with a non-UTF-8 ANSI code page (e.g., cp936/GBK on Simplified Chinese systems) when the project's `CLAUDE.md` is UTF-8 encoded. Python reads the file using the system default encoding instead of UTF-8, causing the crash before anything is removed.

**Workaround:** Enable Python UTF-8 mode by setting the environment variable before running the command:

```cmd
set PYTHONUTF8=1
python -m ouroboros uninstall --dry-run
```

Or on PowerShell:

```powershell
$env:PYTHONUTF8=1
python -m ouroboros uninstall --dry-run
```

To make it permanent, add `PYTHONUTF8=1` to your system environment variables, or run Python with the `-X utf8` flag: `python -X utf8 -m ouroboros uninstall`.

**Proper fix:** Upgrade Ouroboros once the patch lands — the fix reads/writes `CLAUDE.md` explicitly as UTF-8 and skips files that cannot be decoded, so the command completes regardless of the system code page.

Question 4

Why does ouroboros auto fail tasks that plain Codex solves, and how to stop unanswered interview questions from leaking into the worker prompt?

Accepted Answer

Root cause (v0.59.3): in `ouroboros auto` without a requester, every interview question nobody answered is injected as an `Open question:` line into `Seed.assumptions` (median ~15 per seed) and rendered into the worker's system prompt via `render_assumptions_section` (`SeedContract.from_seed` -> `render_seed_contract_for_execution` in `orchestrator/runner.py`). The worker reads each open question as part of the spec, arbitrarily picks one of the candidate answers it names, and builds the fix around it — causing auto without a requester to score 25/50 vs 32/50 with a requester in the Ambig-SWE study. Fix: separate active non-binding `LedgerEntry.question` values into a dedicated `Seed.unanswered_questions` field. Keep them fully visible in the Seed file, auto result, CLI and MCP output, and interview events, but omit them (and unconfirmed assumptions) from all worker handoffs. The split must follow ledger-entry provenance — the structured `LedgerEntry.question` field — not line text, and the same rule applies when a requester skipped a question. Rewording the prompt is not a fix: the 'assumptions may be overridden' disclaimer was present in 8/10 inspected seeds and did not prevent the failures. Workaround until the fix lands: run `ouroboros auto` with a requester so interview questions receive real answers stored in `Seed.requester_answers` instead of leaking as open questions.

Question 5

How to fix '.git/index.lock': File exists error after ouroboros auto cancels a CLI worker?

Accepted Answer

Cause: on v0.59.4, `terminate_runtime_process` sends SIGTERM only to the worker's process group, but providers like codex-cli 0.160.0 spawn each tool command (e.g. `git`) in its own session/process group. Those commands never get the signal, keep running (reparented to pid 1), and still hold `.git/index.lock` after `ouroboros auto` returns, so the caller's `git add -A` fails and the patch is lost. Workaround until the fix lands: 1) Find orphaned tool processes: `ps -eo pid,ppid,pgid,cmd | grep ` (look for ppid 1). 2) Kill them, escalating: `kill -TERM ` then `kill -KILL ` if still alive. 3) Verify no live process holds the lock: `fuser /testbed/.git/index.lock` or `lsof /testbed/.git/index.lock`. 4) Only when nothing holds it, remove it: `rm /testbed/.git/index.lock`, then re-run `git add -A`. Never delete the lock while a process owns it. The planned proper fix makes auto wait for the worker's entire process tree with a bounded SIGTERM→SIGKILL escalation and ownership-aware lock cleanup; it affects the Codex family (Codex, Copilot, Gemini, Grok, Goose, Zcode), Hermes, OMP, Pi, OpenCode, and Kiro runtimes.

ouroboros

Core Features

What It Can't Do

Use Cases

Tags

Getting Started

Similar Projects