Document pressure-aware pre-compaction checkpoints
This commit is contained in:
Meta Vens
parent
80bc702675
commit
c0ffed588a
5 changed files with 29 additions and 2 deletions
|
|
@ -100,6 +100,8 @@ Before compaction, handoff, or a deliberate phase boundary:
|
|||
3. refresh `notes/fresh-workspace-handoff.md`
|
||||
4. state the next action plainly
|
||||
|
||||
If context pressure is clearly rising, do this **before** the hard compaction hits. A harness that only remembers to save itself after the blackout is still acting like a chat transcript with a superiority complex.
|
||||
|
||||
Epiphany should eventually make this automatic. Until then, we do it on purpose.
|
||||
|
||||
## Why This Exists
|
||||
|
|
|
|||
|
|
@ -240,6 +240,17 @@ If a compaction wipes the graph spine and leaves only a prose aftertaste, Epipha
|
|||
|
||||
Before compaction, handoff, or an intentional phase boundary, Epiphany should persist a minimal checkpoint on purpose.
|
||||
|
||||
This should not wait for an actual compaction interrupt.
|
||||
|
||||
The harness should track context-pressure signals early and enter a checkpointing posture before the cliff edge:
|
||||
|
||||
- `low`: no special action
|
||||
- `medium`: make sure the current frontier, evidence, and next action are up to date soon
|
||||
- `high`: checkpoint at the next safe point and mark compaction as pending
|
||||
- `critical`: stop nonessential exploration, persist immediately, and switch to re-entry-safe behavior
|
||||
|
||||
If the system notices it is close to the context limit and just keeps coding until the lights go out, it is still doing transcript improv, not memory-aware work.
|
||||
|
||||
That checkpoint should include:
|
||||
|
||||
- current objective
|
||||
|
|
@ -991,6 +1002,8 @@ The rules should be:
|
|||
|
||||
- compaction should prefer safe points rather than arbitrary interruption
|
||||
- if pressure arrives mid-pass, mark compaction pending and defer until the role reaches a boundary
|
||||
- compaction pressure should be detected before the hard limit; once pressure is `high`, the role should shift from "keep working" to "finish the current bounded move and checkpoint"
|
||||
- once pressure is `critical`, the role should stop nonessential work and persist the re-entry packet immediately, even if that means cutting short a line of thought
|
||||
- every compaction should emit an explicit checkpoint or resume packet
|
||||
- resume should say what survived, what was discarded, and what the role should do first
|
||||
|
||||
|
|
@ -1034,6 +1047,8 @@ This suggests two useful compaction modes:
|
|||
|
||||
The important thing is honesty. The system should admit that compaction happened instead of pretending the role has perfect continuity after being hit on the head.
|
||||
|
||||
Just as important: the system should admit when compaction is *about to* happen. A role that can see the wall coming should start acting nervous on purpose.
|
||||
|
||||
#### `churn`
|
||||
|
||||
Health signals about whether the work is getting sloppy.
|
||||
|
|
@ -1042,6 +1057,7 @@ Suggested fields:
|
|||
|
||||
- `understanding_status`: `clear`, `uncertain`, `stale`
|
||||
- `diff_pressure`: low/medium/high
|
||||
- `context_pressure`: low/medium/high/critical
|
||||
- `graph_freshness`: fresh/stale/missing or split freshness for architecture vs dataflow
|
||||
- `unexplained_writes`: count
|
||||
- `last_warning`
|
||||
|
|
@ -1263,7 +1279,10 @@ Behavior:
|
|||
- persist the latest Epiphany snapshot before the turn fully settles
|
||||
- persist or refresh the graph checkpoint before any compaction finalizes
|
||||
- treat compaction as a role-aware state transition, not hidden transcript trimming
|
||||
- watch context pressure before the hard limit and trigger checkpoint behavior early rather than waiting for forced compaction
|
||||
- compact at safe points where possible; otherwise mark compaction pending and defer until the active role reaches a boundary
|
||||
- when context pressure reaches `high`, checkpoint at the next safe point and narrow the active work to a bounded landing zone
|
||||
- when context pressure reaches `critical`, stop nonessential exploration and persist a re-entry-safe checkpoint immediately
|
||||
- preserve the graph spine and frontier metadata across compaction
|
||||
- preserve retrieval freshness summaries and dirty-shard metadata across compaction
|
||||
- preserve open mechanism questions, open gaps, and shard completion state across compaction
|
||||
|
|
|
|||
|
|
@ -144,8 +144,12 @@ That means this persistence workflow is not optional ceremony. It should be part
|
|||
- append evidence
|
||||
- refresh the handoff note
|
||||
- make the next action explicit
|
||||
2. compaction should happen from a known checkpoint, not at some random point in the middle of an implementation trance
|
||||
3. resumed work should start from the persisted checkpoint and next action, not from vibes and transcript archaeology
|
||||
2. if context pressure is climbing toward compaction:
|
||||
- stop pretending there is plenty of room left
|
||||
- narrow the current move to a bounded landing zone
|
||||
- persist the checkpoint before the hard limit actually trips
|
||||
3. compaction should happen from a known checkpoint, not at some random point in the middle of an implementation trance
|
||||
4. resumed work should start from the persisted checkpoint and next action, not from vibes and transcript archaeology
|
||||
|
||||
If the harness cannot do that by default later, it is not opinionated enough yet.
|
||||
|
||||
|
|
|
|||
|
|
@ -35,3 +35,4 @@
|
|||
{"ts": "2026-04-24T00:39:29+01:00", "type": "decision", "status": "ok", "note": "Delivered Phase 3 as a conservative typed read-surface slice instead of full live event/update exposure. Added optional epiphanyState to hydrated app-server Thread payloads and kept dedicated Epiphany-specific update RPCs and live notifications deferred so the client can read canonical state without scraping prompt text."}
|
||||
{"ts": "2026-04-24T00:39:29+01:00", "type": "implementation", "status": "ok", "note": "Implemented the Phase 3 typed client exposure slice in vendored Codex. Added a shared core helper to reconstruct the latest surviving EpiphanyThreadState from rollout items, exposed live thread epiphany_state through CodexThread, added optional Thread.epiphany_state in app-server protocol v2, hydrated thread/start, thread/resume, thread/fork, thread/read, thread/unarchive, and detached review-thread startup from live state or rollout, patched exhaustive Thread test fixtures, and documented the new field in app-server/README.md."}
|
||||
{"ts": "2026-04-24T00:39:29+01:00", "type": "verification", "status": "ok", "note": "Verified the Phase 3 slice with the Windows CARGO_TARGET_DIR workaround. cargo fmt --all passed; cargo test -p codex-core -p codex-app-server-protocol -p codex-app-server -p codex-analytics -p codex-exec -p codex-tui --lib --no-run passed; and targeted tests passed for codex-core latest_epiphany_state_from_rollout_items, codex-app-server load_epiphany_state_from_rollout_path_reads_latest_snapshot, and codex-app-server-protocol serialize_client_response."}
|
||||
{"ts": "2026-04-24T00:44:53+01:00", "type": "decision", "status": "ok", "note": "Patched the Epiphany spec and handoff workflow to make compaction pressure-aware instead of purely reactive. Added the rule that the harness should detect rising context pressure before the hard limit, checkpoint at the next safe point when pressure is high, and persist immediately when pressure is critical rather than waiting for forced compaction to erase live reasoning."}
|
||||
|
|
|
|||
|
|
@ -76,6 +76,7 @@ accepted_design:
|
|||
- Phase 2 is landed: a dedicated EpiphanyStateInstructions fragment now renders bounded Epiphany thread state into the developer prompt path during build_initial_context, with omission/inclusion/resume coverage and a stable snapshot
|
||||
- Phase 3 read-surface slice is landed: app-server protocol Thread payloads now carry optional typed epiphany_state hydrated from live CodexThread state when available and otherwise reconstructed from rollout with rollback/compaction semantics; dedicated Epiphany update RPCs and live notifications remain deferred
|
||||
- Epiphany should be an opinionated software development agent: pre-compaction and pre-handoff persistence of map, evidence, and next action are part of the workflow, not optional operator folklore
|
||||
- compaction handling should be pressure-aware rather than reactive: when context pressure rises, Epiphany should narrow the active move and persist checkpoints before forced compaction actually hits
|
||||
|
||||
rejected_paths:
|
||||
- name: pinned_map_only
|
||||
|
|
|
|||
Reference in a new issue