- Зачем:
- `-newermt "@<epoch>"` и `-printf` в secondary session-id capture — GNU-специфичные; на macOS BSD find они не работают, а тестировать на маке негде.
- Что:
- SKILL.md: добавлена one-paragraph platform note рядом с `find` — формулирует цель шага ("найти свежие rollout-файлы, выбрать последний, извлечь UUID") и приглашает Opus/пользователя подставить BSD-эквивалент.
- docs/DESIGN.md §9.5: новое known-limitation с обоснованием template+understanding подхода вместо platform-detection.
- README.md Known limitations: user-facing note, что end-to-end на macOS не тестировался.
- Проверка:
- Ничего не ломается на Linux (команды без изменений).
- На macOS оператор читает note и адаптирует.
- Зачем:
- остатки документации ссылались на `- < file` и старый одноуровневый session-id, расходились с SKILL.md после основной правки.
- Что:
- §3.2 теперь рекомендует `cat file | cmd -` со ссылкой на §4.13.
- §7.2 smoke-test resume переведён на pipe-форму и включает secondary filesystem session-id capture.
- §7.3 (bad-UUID) тоже на pipe-форме для изоляции от §6.6.
- §2.5 разделяет success-row на reference и affected окружения, добавлен row для `- < file` exit-1-empty-stderr.
- Проверка:
- `grep -n '\- < ' docs/DESIGN.md` остаются только контекстные упоминания (§2.1 описание обеих форм, §4.13 decision, §6.6 lesson, §8 log).
- Зачем:
- форма `codex exec ... - < file` exit=1 с пустым stderr, а `--json` stdout оказывается пустым в части Claude Code песочниц; без обхода скилл не может захватить session ID и теряет resume на раундах 2-5.
- Что:
- SKILL.md Step 4/7 переведены на `cat file | codex exec ... -` как canonical; добавлен two-tier захват session ID (primary = first JSONL line, secondary = UUID из имени `~/.codex/sessions/**/rollout-*.jsonl` с mtime > CODEX_SESSIONS_BEFORE).
- README.md обновлены permissions (pipe-форма, `find rollout-*`, `date +%s`) и добавлен troubleshooting про env-specific пустой JSONL.
- docs/DESIGN.md: §2.1 описывает обе формы, §2.2 фиксирует env-specific suppression, §2.3 добавляет filesystem-recovery путь, §4.1 переделан на two-tier decision, добавлены §4.13 (canonical pipe) и §6.6 (lesson от 2026-04-17), в §8 новая строка с окружением yantar-k8s.
- Проверка:
- DESIGN.md §7.1 smoke test (обновлён на pipe-форму + проверка filesystem secondary path).
- Оба окружения (reference WSL2 + containerized sandbox) должны давать валидный session ID и успешный resume.
1082-line design note covering:
- Empirical facts about Codex CLI 0.121.0 (invocation, streams,
resume semantics, known failure modes) with copy-pasteable
verification commands.
- Claude Code harness facts (Bash truncation, cwd drift, Opus
literal-interpretation tendencies).
- 12 design decisions in a uniform format: what, where in SKILL.md,
alternatives considered, why chosen, trade-offs accepted.
- Rejected ideas (marker files, per-round naming, $(pwd), etc.) with
reasons, so future contributors don't re-propose them.
- Prior diagnostic errors from a previous agent-auditor's dump that
turned out to be wrong when verified, kept as a methodological
lesson.
- Smoke-test protocol (§7) with concrete commands and expected
outputs so any maintainer can verify the Codex contract still holds
in minutes.
- Update protocol: when and how to revise this file, with a pointer
that future Opus generations interpret instructions more literally
and SKILL.md hardening must track that.
- Mermaid flow diagram of the round-trip.
Intended audiences: future Claude sessions resuming work on the skill,
human developers, and new contributors. The file is self-contained —
does not rely on conversation history that produced the current design.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
ddadmin
