Define Every Code-owned convergence contracts

[shiny-code-bot]

Objective

Define the executable product contracts and ownership exceptions that allow Codex Lab to adopt a current openai/codex tree by default without losing intentional Every Code behavior. The authoritative restored Every Code source remains evidence for product intent, while tests, fixtures, snapshots, and explicit decisions become the durable convergence gate.

Finish Line

Every surviving Codex Lab difference from upstream is either protected by an executable Every Code contract, recorded as an intentional owned exception, or removed from the convergence candidate; the contract matrix is sufficient to unblock #428.

Current Status

State: Complete. The contract authority has been fully consumed by the final upstream-first candidate.

Final candidate: code/upstream-snapshot-428 at 86cad522213c21e4d3696064878c4233cb3df724 (tree bd3e9f400737f27900615ef3b011d163b0214b55). #428 is closed complete.

Final contract result:

• IDENTITY-1 preserves isolated codex-lab, CODEX_LAB_HOME, ~/.codex-lab, auth, telemetry, installer, and release identity.
• MODEL-1 makes provider catalogs/default metadata authoritative, preserves explicit user selections, and limits bundled data to bootstrap/offline fallback.
• RELEASE-1 preserves GitHub Releases and Codex Lab-owned signed binary/app/installer/updater/rollback/package/endpoints/credentials without inheriting OpenAI release authority.
• Account/auth, history/resume, app-server/protocol, agent/tool/review, TUI, Code Bridge/browser/remote-control, privacy, and validation contracts are protected by executable tests, fixtures, snapshots, live evidence, or explicit opt-in characterization.
• Strict convergence passes with 369 guarded paths, zero violations, zero stale waivers, and 40 decided records. The deterministic harness passes 18/18 scenarios and explicitly reports three opt-in live scenarios.

No contract-definition work remains. Permanent source/runtime cutover remains separately gated by #343/#382.

Last verified: July 29, 2026.

Scope

• In: product identity and config precedence; account/auth/storage/switching UX; history/resume/persistence; app-server and protocol compatibility; agent/tool/review behavior; TUI interaction contracts; Code Bridge/browser/remote-control integration; release ownership and model defaults.
• Out: importing the upstream tree, resolving the integration branch, replaying historical commits, final cutover, or preserving undocumented local behavior by default.

Acceptance Criteria

• Publish a compact ownership matrix for upstream-owned, contract-adapted, red-risk, and intentionally Every Code-owned surfaces.
• Every critical owned surface has an executable test, fixture, snapshot, dogfood gate, or explicit reason why live validation is required.
• Preserve authoritative Every Code account/login/settings flows, CODE_HOME/CODEX_LAB_HOME precedence, product identity, release ownership, Auto Drive, external-agent, Background Review, Code Bridge, browser, and remote-control contracts where still intended.
• Define schema, migration, history/resume, auth/account, sandbox/approval, and TUI regression gates for Build upstream snapshot integration and canary branch #428.
• Route the six actionable rows found by Reconstruct pre-checkpoint semantic ledger through 1bbdb327 #407, including the completed Stop emitting free-form analytics error subreason #429 analytics privacy fix and candidate validation of plugin-cache, MCP visibility, and OTEL counter→gauge behavior.
• Require every surviving modification to an upstream-owned file to name its owning contract or explicit product decision.
• Do not require unclassified historical commits to block Build upstream snapshot integration and canary branch #428 once the candidate satisfies the contract matrix.

Relationships

• Parent: Sync Codex Lab with current openai/codex substrate #230.
• Contract authority consumed by: Build upstream snapshot integration and canary branch #428 upstream snapshot integration.
• Related implementation fast-track: Stop emitting free-form analytics error subreason #429 analytics privacy.
• Downstream product lanes: Sync canonical turn, context, history, and recovery substrate #305, Sync subscription auth and multi-account substrate #306, Sync exec, tools, sandbox, and external-agent substrate #307, and Sync TUI, Guardian, and CI substrate #308.
• Strategy parent: Upstream sync and Codex Lab feature reclassification #229.
• Historical evidence: completed children Align auto-review durable store and lifecycle with Every Code #130, Rework external-agent parity for Codex Lab #153, Audit auth/login/account switching parity #157, and Decide account storage direction for multi-auth MVP #159; Verify upstream coverage through checkpoint and classify pending delta #387/Reconstruct pre-checkpoint semantic ledger through 1bbdb327 #407 ledgers; authoritative source ../code-prealign-new-skills/code-rs.
• Initial checked-in gate: PR Define initial Every Code convergence contracts #431 / merge 8add494682f7c0674672e8dc5b38a4565cd7629b.

Validation

• Execute contracts against current Codex Lab main, the authoritative restored Every Code reference where applicable, and Build upstream snapshot integration and canary branch #428's candidate.
• Keep model-visible context and generated artifacts bounded and deterministic.
• Use snapshots or browser/TUI evidence for user-facing flows and isolated homes for auth/config tests.

Decisions

• Reuse this issue as the single convergence-contract authority instead of creating another ledger.
• Treat upstream as the default implementation outside explicit owned surfaces.
• Preserve historical audit evidence without making audit completeness a prerequisite for integration.

Open Questions

• Which live account, remote-control, and release contracts need dogfood rather than offline fixtures?

[shiny-code-bot]

Audit checkpoint 1, read-only pass from lowest merged PRs:

Possible active miss:

• Installer default release repository still appears to be cbusillo/codex in scripts/codex_lab_package/installer.py.
• The default was introduced with PR Add Codex Lab release installer #10 and has not been changed by later installer PRs.
• Live release metadata suggests cbusillo/codex currently hosts upstream-style v0.6.x releases, while cbusillo/codex-lab hosts codex-lab-v... prereleases.
• This may have been correct at the time, but current main likely should default the Codex Lab installer to the Codex Lab release repository.

Looks right so far:

• The merged PR inventory starts at Add Codex Lab app packaging scaffold #5; no merged Codex fork overlay capability map #1-Codex Lab identity and channel naming #4 were found in the helper inventory.
• PR Add Codex Lab app packaging scaffold #5 is Codex Lab-original app packaging scaffold, not Every Code feature parity.
• PRs Add Codex Lab distribution manifest #6-Add Codex Lab installer status command #14 are release/installer infrastructure rather than direct Every Code UX parity.
• Early app/shim naming is consistently Codex Lab / codex-lab.
• Installer state defaults to ~/Library/Application Support/Codex Lab/install-state.json.

Paused for discussion before continuing or fixing.

[shiny-code-bot]

Audit checkpoint 1 update:

The installer repository miss from the first lowest-PR audit pass is now addressed by PR #127:
#127

Scope:

• Defaults install_codex_lab.py --latest / release-tag resolution to cbusillo/codex-lab through DEFAULT_REPOSITORY.
• Updates package release URL fixtures to Codex Lab release URLs.

Verification before PR:

• python3 -m unittest scripts.codex_lab_package.test_installer scripts.codex_lab_package.test_distribution_manifest
• Read-only review agent reported no findings.

[shiny-code-bot]

Audit checkpoint 1 resolved:

PR #127 merged and fixed the installer release repository miss.

Result:

• Codex Lab installer defaults now resolve releases from cbusillo/codex-lab.
• Package installer/distribution manifest tests use Codex Lab release URLs.
• CI passed before merge.

Audit can resume from the next unchecked early PRs after #24-#26.

[shiny-code-bot]

Read-only audit progress after resolving checkpoint 1:

Checked through PR #41.

Looks right / no miss found:

• Ignore local handoff scratch files #16 local handoff ignore hygiene.
• Add Codex Lab installer update command #17-Handle Codex Lab installer CLI errors #18 installer follow-ups are covered by the fix: default installer to codex-lab releases #127 repository-default fix.
• Document Just Every skill provenance #19-Add OpenAI metadata for repo skills #21 skills provenance/metadata and repo policy cleanup.
• Strengthen skill guidance and add exec harness #24-Add exec harness eval reports #26 exec harness pilot, CI gate, and reports. These are intentionally narrower than the authoritative Every Code tools/code-exec-harness; the narrowing is documented in the Codex Lab harness README and later cache-safety plans build on that explicit shape.
• Point agents at durable Codex Lab plan #29 durable planning guidance, later corrected by docs: clarify Every Code source references #125 for restored-source lookup.
• Fix exec harness cleanup automation #38-Add skills cache continuity scenario #40 exec harness automation/cache/skills-continuity follow-ups align with the focused harness plan.
• Document app-server Desktop compatibility gate #41 app-server/Desktop compatibility gate and macOS build workaround; no Every Code parity miss found.

Next audit cursor: PR #44.