Build upstream snapshot integration and canary branch

[shiny-code-bot]

Objective

Build a continuously refreshable upstream-first integration candidate from an exact openai/codex snapshot, then restore only contract-backed Every Code behavior. This replaces per-commit opt-in adoption with tree-level integration plus explicit product exceptions.

Finish Line

A protected integration branch descends from a recorded upstream SHA, includes the required Every Code product layer, passes the convergence contract matrix, and can absorb a newer upstream snapshot without restarting a historical per-commit audit.

Current Status

State: Complete. PR #497 merged the final proof/waiver/cleanup reconciliation into the protected candidate branch on July 29, 2026. Draft PR #465 remains the sole intentional main cutover vehicle.

Final identities:

• Current main: 82ffbe8cae7dc68a400ea5d4f29f7bcd42b18c8f (tree 214bc12e7bff546cebc3b9198bf0d9ff2185391f).
• Pre-anchor local baseline: 8add494682f7c0674672e8dc5b38a4565cd7629b.
• Initial upstream snapshot U0: 4462b9deef211723b781b426f5e5d36a5777115f from merge base b89ce9a2bcedcfddf3a48f387b7912d602d6d87c.
• Latest incrementally absorbed upstream snapshot: 61a44880a85d2fd0d8770908dea5733495e571c8.
• Final candidate: code/upstream-snapshot-428 at merge 86cad522213c21e4d3696064878c4233cb3df724, tree bd3e9f400737f27900615ef3b011d163b0214b55.

Final evidence:

• Four immutable upstream refresh snapshots reproduce exactly, demonstrating repeated incremental refresh rather than historical replay.
• Strict convergence passes with 369 guarded paths, zero violations, zero stale waivers, and 40 decided waiver records (25 converged with upstream; 15 adopted upstream deletions).
• The deterministic exec harness passes 18/18 scenarios and explicitly reports all three opt-in live scenarios instead of silently excluding them.
• Focused gates pass: 92 harness unit tests, 275 GitHub helper tests, 41 model-manager tests, 46 TUI status tests, format, ShellCheck, and candidate compile checks.
• PR Finalize upstream convergence proof set #497 blocking CI passed all required jobs in run 30427520665 (7m52s); its V8 build matrix correctly skipped because the change did not touch V8 inputs.
• Bounded dry-run-first cleanup now identifies rebuildable worktree, harness, and artifact-volume caches while rejecting unbounded explicit paths and traversal/symlink escapes.

#428 no longer blocks the product. Permanent merge of PR #465 into main remains intentionally gated by #343 and the bounded reversible #382 canary; this completion does not override that recorded user decision.

Next action: reconcile #343/#382 against the now-frozen candidate, run only their remaining operational canary/rollback evidence, and merge PR #465 when those separate gates are honestly satisfied.

Last verified: July 29, 2026.

Scope

• In: exact upstream snapshot pinning; history-preserving integration branch; risk-lane conflict handling; repeatable mirror/canary updates; compile/schema/snapshot/test gates; restoration of contract-backed Every Code product bundles.
• Out: force-updating main; replaying all local commits; requiring all 1,017 historical commits to be classified; final product cutover; unrelated feature development.

Acceptance Criteria

• Record current main, merge base, upstream U0, and candidate tree identity.
• Treat upstream as the default for non-owned surfaces and record every surviving exception.
• Consume Define Every Code-owned convergence contracts #126's contracts for identity/config, accounts/auth, history, app-server/protocol, agents/tools, TUI, release, and Every Code integrations.
• Classify conflicts into green bulk-adopt, amber contract-adapt, red manual-review, and intentionally owned lanes.
• Preserve additive Every Code crates/modules where their upstream API contracts still compile.
• Validate or explicitly route the six known missing pre-checkpoint behaviors from Reconstruct pre-checkpoint semantic ledger through 1bbdb327 #407, including the OTEL counter→gauge dependency and the P1 analytics privacy finding.
• Pass focused build, schema, migration, snapshot, integration, and repository checks appropriate to the candidate.
• Demonstrate incremental refresh from U0 through three newer upstream snapshots without resetting the branch.
• Leave main and the installed runtime unchanged until Cut over to converged Codex Lab baseline and primary harness #343's cutover gates are satisfied.

Relationships

• Parent: Sync Codex Lab with current openai/codex substrate #230.
• Enabled by: Define Every Code-owned convergence contracts #126's initial contract matrix and PR Define initial Every Code convergence contracts #431; Define Every Code-owned convergence contracts #126 remains the contract authority during candidate work.
• Blocks: Sync canonical turn, context, history, and recovery substrate #305, Sync subscription auth and multi-account substrate #306, and Cut over to converged Codex Lab baseline and primary harness #343.
• Historical evidence: Verify upstream coverage through checkpoint and classify pending delta #387, Reconstruct pre-checkpoint semantic ledger through 1bbdb327 #407, PRs Add explicit upstream audit range inventories #405-docs: classify OTEL instrument prerequisites #427, and closed Classify upstream delta after 1bbdb327 through bd9a28a8 #408.
• Authoritative Every Code behavior reference: ../code-prealign-new-skills/code-rs.

Validation

• Exact-SHA ancestry and tree checks.
• Scoped Rust build/test suites plus schema regeneration comparisons.
• Every Code contract suite from Define Every Code-owned convergence contracts #126.
• Daily canary refresh rehearsal and bounded conflict report.

Decisions

• Upstream tree snapshots, not commit-by-commit classification, are the integration unit.
• Historical ledgers remain provenance evidence but do not block the candidate.
• A final cutover must preserve both histories through reviewed GitHub PRs; no force rewrite.

Open Questions

• Select the first U0 after the initial contract gate is ready.
• Decide whether steady-state automation belongs in Cut over to converged Codex Lab baseline and primary harness #343 or a later operations child after cutover.