Repository navigation
Preserve V2 agent topology and paginated history during consolidation #197
Description
Outcome
Preserve Codex rust-v0.145.0 multi-agent V2 identity and paginated-history correctness when CodexHub consolidates or normalizes history across Codex homes.
Problem
Codex V2 cold resume depends on threads.agent_path and thread_spawn_edges to recover canonical descendant paths, nicknames, roles, and lazy reload identity. Paginated history also uses thread_history_1.sqlite projections with byte offsets and ordinals.
CodexHub currently:
- merges only shared columns from the threads table in src-python/history_consolidate.py;
- does not migrate thread_spawn_edges;
- recognizes state_5.sqlite but not thread_history_1.sqlite;
- merges divergent JSONL histories as source plus active extra records.
This can leave imported V2 child threads without their parent topology and can invalidate paginated-history ordinals or projection offsets.
Scope
- Detect the installed Codex state/history schema before consolidation.
- Migrate threads and thread_spawn_edges transactionally while preserving parent/child referential integrity.
- Preserve agent_path and all shared V2 identity columns without inventing missing identity.
- Treat paginated JSONL as prefix/append-only during automatic consolidation; fail closed on divergent branches.
- After any permitted JSONL rewrite, invalidate and rebuild the affected projection from the durable JSONL instead of copying stale checkpoints blindly.
- Keep backups and existing provider normalization behavior.
Acceptance criteria
- Root, child, and grandchild fixtures retain canonical paths and spawn edges after cross-home consolidation.
- Cold resume can address the original child after migration and restores its persisted role metadata.
- Missing parents, cycles, duplicate child ownership, schema mismatch, and divergent paginated histories fail before the active database is committed.
- Strict prefix and append cases preserve ordinal order.
- Rewritten histories never reuse an incompatible byte-offset or ordinal checkpoint.
- Legacy non-paginated histories retain current supported behavior.
- Backups are produced before mutation and rollback leaves the original active state readable.
Verification
python -m pytest -q tests/test_history_consolidate.py tests/test_history_overlay.py
python -m pytest -q
git diff --check
python scripts/report_quality_gates.py
Verification class is strict because this changes persisted-state migration.
Relationships
- Related to 0.1.8 Beta2: Define the Codex CLI 0.146 Collaboration V1/V2 schema boundary #64, which owns native V1/V2 lifecycle evidence.
- Source assessment: docs/research/2026-07-22-codex-rust-v0.145.0-subagent-v2-impact.md.
- Scheduled after the current connection-stability chain in Wayfinder: CodexHub 0.1.6–0.3.0 Gateway and release roadmap #147.
Activity
NOirBRight commentedon Jul 22, 2026
{ "contract": { "acceptance": [ "Root, child, and grandchild fixtures retain canonical paths, roles, nicknames, and spawn edges after cross-home consolidation, and cold resume addresses the original child identity.", "Missing parents, cycles, duplicate child ownership, incompatible schemas, and divergent paginated histories fail before the active database is committed.", "Strict-prefix and append-only histories preserve record order; any rewritten history rebuilds projection offsets and ordinals from durable JSONL and never reuses an incompatible checkpoint.", "Legacy non-paginated histories, backups, rollback readability, and existing provider normalization remain unchanged.", "Targeted history suites, full python -m pytest -q, git diff --check, report-only quality gates, exact-SHA Actions, and strict heavy review pass for the same final SHA." ], "change_claims": { "paths": [ "src-python/history_consolidate.py", "src-python/history_overlay.py", "tests/test_history_consolidate.py", "tests/test_history_overlay.py" ], "resources": [ "codex-history-v2-migration" ] }, "dependencies": { "dispatch_after": [ 20 ], "merge_after": [ 20 ] }, "design": [ "Detect the installed Codex state and paginated-history schema before consolidation; do not infer V2 columns or projection compatibility from filenames alone.", "Migrate threads and thread_spawn_edges transactionally, preserving agent_path, roles, nicknames, parent-child identity, and every shared V2 column without inventing missing identities.", "Validate referential integrity before commit and fail closed on missing parents, cycles, duplicate child ownership, or schema mismatch. Preserve backups and leave the original active state readable on failure.", "Treat paginated JSONL as prefix/append-only during automatic consolidation. Reject divergent branches; after any permitted rewrite, invalidate and rebuild thread_history_1 projections from durable JSONL instead of copying stale byte offsets or ordinals.", "Preserve legacy non-paginated and provider-normalization behavior and keep the work isolated from Gateway/E2E/config-overlay hotsets." ], "difficulty": "heavy", "done_when": [ "python -m pytest -q tests/test_history_consolidate.py tests/test_history_overlay.py", "python -m pytest -q", "git diff --check", "python scripts/report_quality_gates.py (report-only)", "Exact-SHA GitHub Actions and strict heavy review pass" ], "priority": "P2", "risk": "strict", "sha256": "1f177406ae18024dc9e2a48265eeb9f4cdc4773d3c8485f08e543d8610c6a792", "unresolved_decisions": [] }, "dispatch": null }