EpiphanyAgent

Epiphany is an opinionated fork of Codex built around one demand: the model must model the thing it is changing.

The failure mode this repo is hunting is not "the model cannot write code." It can. Annoyingly well. The failure mode is local plausibility after global coherence has already wandered into traffic wearing headphones.

Epiphany answers that by moving important state out of transcript fog and into typed, inspectable surfaces: maps, scratch, evidence, retrieval state, observations, graph/frontier state, churn pressure, and client reflections.

Current Shape

This is no longer just an external-file prompting experiment.

The landed spine now includes:

• durable EpiphanyThreadState in vendored Codex protocol/core session state
• rollout snapshots and replay reconstruction for resume, rollback, fork, and compaction
• bounded <epiphany_state> prompt injection
• typed client reads through Thread.epiphanyState
• read-only hybrid retrieval through thread/epiphany/retrieve
• explicit semantic indexing through thread/epiphany/index
• durable typed writes through thread/epiphany/update
• read-only observation distillation through thread/epiphany/distill
• read-only map/churn proposal through thread/epiphany/propose
• verifier-backed promotion through thread/epiphany/promote
• successful-write notifications through thread/epiphany/stateUpdated
• first Phase 6 reflection through read-only thread/epiphany/scene
• repo-owned heavy organs in epiphany-core/, with vendored Codex kept as the host seam where practical

Phase 1 through Phase 5 are complete enough. Phase 6 is about reflection and observable harness state, not more anxious polishing of the Phase 5 control plane.

For exact current status, trust:

• state/map.yaml
• notes/fresh-workspace-handoff.md
• notes/epiphany-fork-implementation-plan.md
• notes/epiphany-current-algorithmic-map.md

Git history and smoke artifacts carry proof. state/evidence.jsonl carries only distilled belief-changing evidence, not every little victory lap with a timestamp.

Core Artifacts

• AGENTS.md: project-specific operating discipline for future Codex sessions
• state/map.yaml: canonical current project map and accepted design
• state/scratch.md: disposable working memory for one bounded subgoal
• state/branches.json: branch hypotheses and outcomes, not volatile phase status
• state/evidence.jsonl: distilled durable evidence, decisions, rejected paths, and scars
• notes/fresh-workspace-handoff.md: compact re-entry packet
• notes/epiphany-fork-implementation-plan.md: distilled forward implementation plan
• notes/epiphany-current-algorithmic-map.md: source-grounded live control-flow map
• notes/epiphany-core-harness-surfaces.md: stable surface contract
• notes/architecture-rationale.md: why the map/scratch/evidence architecture exists
• notes/codex-repository-algorithmic-map.md: background map of the vendored Codex substrate
• protocol/controller-actions.md: legacy/manual controller discipline for local state maintenance
• tools/epiphany_state.py: compact state inspection and distilled evidence helper
• eval-plan.md: evaluation sketch for comparing Epiphany discipline against plain prompting

Next Move

When implementation resumes, choose one Phase 6 organ:

1. Live-smoke thread/epiphany/scene through app-server.
2. Design and land a minimal read-only job/progress reflection surface for indexing, remap, verification, and future specialist work.

The scene-smoke path is tighter. The job/progress path is the larger missing organ.

Working Loop

1. Rehydrate from canonical state before touching code.
2. Restate the current mechanism and intended change before substantial edits.
3. Keep one bounded hypothesis per iteration.
4. Verify the seam that matters.
5. Revert failed regression or benchmark fixes immediately.
6. Record only distilled evidence that changes future belief.
7. Commit completed work before it rots in the worktree.

Do not confuse a growing diff, growing notes, or a local green check with understanding. That is how the tower learns to smirk.

Re-entry

From the repo root:

& 'C:\Users\Meta\.cache\codex-runtimes\codex-primary-runtime\dependencies\python\python.exe' '.\tools\epiphany_state.py' status
Get-Content '.\state\map.yaml'
Get-Content '.\notes\fresh-workspace-handoff.md'
Get-Content '.\notes\epiphany-current-algorithmic-map.md'
Get-Content '.\notes\epiphany-fork-implementation-plan.md'
git status --short --branch
git log --oneline -5
Get-Content '.\state\evidence.jsonl' -Tail 8

After compaction or resume, rehydrate and reorient first. Do not continue implementation just because a note names a next move.

Verification

Use focused checks for the surface being changed.

For Phase 5 control-plane behavior changes:

& 'C:\Users\Meta\.cache\codex-runtimes\codex-primary-runtime\dependencies\python\python.exe' '.\tools\epiphany_phase5_smoke.py'

For Codex Rust work on this Windows machine:

$env:CARGO_TARGET_DIR='C:\Users\Meta\.cargo-target-codex'

Do not parallelize cargo builds or tests against the same target directory.

Licensing

The root LICENSE is the operative repository notice. In short: vendor/codex/** and other third-party material keep their upstream licenses; Project-Authored Material outside vendor/codex/** is publicly available under PolyForm Noncommercial 1.0.0 and is intended to be available under separate commercial terms by written agreement.

External contributions require CONTRIBUTOR_LICENSE_AGREEMENT.md or a separate written agreement accepted by the Project Steward.