Spec: CodexHub 0.1.8 staged compatibility and release roadmap

[NOirBRight]

Current verification policy (2026-08-04)

GitHub Actions CI is disabled for this project. Beta/RC/stable work is verified locally on the exact candidate: focused tests, affected full suites, CLI/manual checks, and the documented local release checklist. Historical Hosted runs remain evidence of past candidates only and are not a current merge or release gate.

Status

0.1.8-beta.3.3 is the current published prerelease.

• Release: https://github.com/NOirBRight/CodexHub/releases/tag/v0.1.8-beta.3.3
• Exact main/tag SHA: d1308ce5bd0546993a68579b23102bafde24513a
• Beta3 cumulative gate: 0.1.8 Beta3 gate: Publish the generic advanced-tool workflow candidate #281
• Stable v0.1.7 remains GitHub latest stable.

Beta3.1–3.3 retained the Beta3 advanced-tool release while adding the verified reasoning/history, Kimi Chat translation, message-phase, and context-derived output-limit corrections. Existing task files are not rewritten and no Provider/model fallback was added.

The active frontier is now Beta4. The remaining train separates:

1. exact runtime-derived generic Collaboration V2 over Responses;
2. three-route maintained Ollama Responses regression;
3. usable Ollama Chat plus complete Collaboration V2 on those same three routes;
4. stability freeze, fixed RC batches, and human stable promotion.

Product contract

Model selection and route identity

• The user selects the Provider and model.
• CodexHub resolves that choice to one immutable endpoint/auth/protocol/model binding.
• Tool compatibility never selects a model.
• Alias, catalog mismatch, missing capability, adaptation, retry, or error handling must never fallback to Terra, Luna, Official, or another Provider/model.

Tool compatibility

Each request derives compatibility from the installed Codex runtime declaration type and the already-selected upstream protocol:

• native — preserve the compatible declaration and wire lifecycle unchanged.
• adapt — use an Adapter only for an incompatible but reversible structural shape.
• omit — do not expose an optional unavailable/non-representable tool.
• required-but-unavailable — fail visibly before sampling when the request requires that tool.

Already compatible tools are not routed through an Adapter. Namespace/custom aliases are request-scoped and reversible. The Gateway adapts protocol shapes but does not execute tools, create agents, schedule Collaboration work, or fabricate results.

Hosted tools are exposed only when the selected Provider natively supports them. Explicit and implicit cross-Provider tool proxying are prohibited.

Unknown custom endpoints use the same conservative type/protocol rules. GLM-5.2, K2.7 Code, and DeepSeek V4 Flash 0731 are maintained-Provider regression samples, not an exhaustive allowlist or runtime eligibility gate.

Release train

0.1.8-beta.1 — usability hotfix (released)

Gate #258.

Shipped urgent Official-continuation and provider-scoped context-window fixes, exact RoutePlan/K2.7 foundations, local verification migration, release artifacts, and regressions required to make the application usable again.

0.1.8-beta.2 — generic tool compatibility core

Gate #318.

• Architecture decision: 0.1.8 Beta2: Record the runtime-derived tool compatibility architecture (ADR-0002) #350.
• Exact CLI 0.146 structural inventory: 0.1.8 Beta2: Inventory Codex CLI 0.146 tool types and representative Responses lifecycles #62 and 0.1.8 Beta2: Define the Codex CLI 0.146 Collaboration V1/V2 schema boundary #64.
• Tool-type/protocol compatibility rules and maintainer decision: 0.1.8 Beta2: Define tool-type compatibility rules for custom Responses endpoints #65 and 0.1.8 Beta2: Approve the custom-endpoint tool compatibility contract #249.
• V1/V2 corruption prevention: 0.1.8 Beta2: Isolate V1 repair from V2 namespace adaptation #198.
• Runtime-derived implementation: 0.1.8 Beta2: Implement runtime-derived tool compatibility for custom Responses endpoints #58.
• Retained closed safety foundations: Serialize DiagnosticControlBridge batches to prevent duplicate control execution #267, Pass current-session identity through the Rust port-restart lifecycle test fixture #269, 0.1.8 Beta2 prerequisite: Honor Codex visibility and keep internal reviewer models out of managed catalogs #273, 0.1.8 Beta2 prerequisite: Fail closed on model identity mismatches instead of alias or catalog fallback #274, and 0.1.8 Beta2: Preserve explicit model-catalog overrides across sync and restart #327.

Outcome: custom Responses endpoints receive one generic native/adapt/omit/required-but-unavailable path with exact model identity and no cross-Provider proxy. Beta2 adds no alternate-codec retry or model-output format repair.

0.1.8-beta.3 — generic advanced tools, official Collaboration controls, and Ollama stream diagnosis

Gate #281.

• Official Collaboration capability matrix: 0.1.8 Beta3: Qualify official Collaboration V1/V2 support for the catalog #369.
• Per-model V1/V2 override UI/materializer, starting with Luna V2: 0.1.8 Beta3: Persist and expose per-model Collaboration V1/V2 overrides (Luna V2) #368 (depends on 0.1.8 Beta2: Preserve explicit model-catalog overrides across sync and restart #327).
• Ollama Responses timeout/stream-failure classification and any narrow generic fix: 0.1.8 Beta3: Diagnose Ollama Responses timeouts and classify stream failures #370.
• Client-executed tool_search: 0.1.8 Beta3: Complete the generic client tool_search lifecycle #63, 0.1.8 Beta3: Implement the generic client tool_search protocol adapter #277, and 0.1.8 Beta3: Verify the complete generic client tool_search workflow #278.
• Reversible Code Mode: 0.1.8 Beta3: Complete the generic reversible Code Mode workflow #251, 0.1.8 Beta3: Implement the generic reversible custom/freeform Code Mode codec #279, and 0.1.8 Beta3: Verify the complete generic Code Mode workflow #280.

Outcome: add no global V1/V2 switch and no model fallback. Official catalog values remain the baseline; only an accepted, exact-model user override changes the effective value and survives restart/sync/catalog rebuild. V2 selectors are shown only for list-visible Official models with a complete accepted matrix verdict. Generic client tool discovery and Code Mode remain model-agnostic. Ollama transport failures are classified separately from semantic/tool incompatibility; no blanket timeout increase or blind replay is accepted.

0.1.8-beta.4 — runtime-derived generic Collaboration V2

Gate #284.

• Exact candidate-bound V1/V2 runtime and wire reconciliation: 0.1.8 Beta4: Reconcile the exact Codex Collaboration V2 runtime/wire contract #392.
• User-owned agent configuration safety: Preserve Codex agents configuration across Gateway overlay lifecycle #199.
• Generic direct-tool/lifecycle implementation and verification: 0.1.8 Beta4: Complete the generic Collaboration V2 workflow #252, 0.1.8 Beta4: Implement runtime-derived Collaboration V2 direct-tool and lifecycle adaptation #282, and 0.1.8 Beta4: Verify the complete generic Collaboration V2 lifecycle #283.
• Closed Beta2 isolation foundations 0.1.8 Beta2: Define the Codex CLI 0.146 Collaboration V1/V2 schema boundary #64 and 0.1.8 Beta2: Isolate V1 repair from V2 namespace adaptation #198 remain binding only as corrected by 0.1.8 Beta4: Reconcile the exact Codex Collaboration V2 runtime/wire contract #392.

Outcome: complete the generic spawn/message/follow-up/wait/interrupt/list lifecycle over custom Responses routes using the actual runtime V2 direct-tool surface. Native-compatible shapes remain native; only complete reversible lifecycles adapt. Essential non-representable semantics fail before sampling. Codex Client remains the agent owner/executor; Gateway performs no scheduling and does not rewrite task history.

0.1.8-beta.5 — three-route maintained Ollama Responses regression

Gate #351.

• Ollama Cloud GLM-5.2: 0.1.8 Beta5: Run the full maintained GLM-5.2 Provider regression #275.
• Ollama Cloud K2.7 Code: 0.1.8 Beta5: Run the full maintained K2.7 Code Provider regression #276.
• Ollama Cloud DeepSeek V4 Flash 0731: 0.1.8 Beta5: Run the full maintained DeepSeek V4 Flash 0731 Responses regression #393.

Outcome: independently regression-test every generic Responses capability shipped in Beta2 through Beta4 against all three Provider/model configurations maintained by CodexHub. Beta5 adds no planned generic capability, model-specific codec, runtime allowlist, or fallback.

0.1.8-beta.6 — usable Ollama Chat plus complete Collaboration V2

Gate #259.

• Runtime-derived conversion matrix: 0.1.8 Beta6: Generate the runtime-derived Chat and Collaboration V2 conversion matrix #66.
• Runtime-field and progressive-streaming contracts: 0.1.8 Beta6: Define the real Codex-to-Chat runtime-field and V2 item contract #253 and 0.1.8 Beta6: Define progressive Chat and Collaboration V2 streaming #254.
• Generic Chat Collaboration V2 implementation and verification: 0.1.8 Beta6: Implement generic Collaboration V2 over Chat Completions #394 and 0.1.8 Beta6: Verify the complete generic Chat Collaboration V2 lifecycle #395.
• Real Ollama Chat CLI paths: GLM-5.2 0.1.8 Beta6: Complete the GLM-5.2 Ollama Chat and V2 CLI path #285, K2.7 Code 0.1.8 Beta6: Complete the K2.7 Code Ollama Chat and V2 CLI path #286, and DeepSeek V4 Flash 0731 0.1.8 Beta6: Complete the DeepSeek V4 Flash 0731 Chat CLI path #396.

Outcome: all three maintained Ollama Chat routes complete progressive SSE, multi-turn text, standard function tools, default reasoning, classified errors, a real read/apply_patch/verify loop, and the complete client-owned Collaboration V2 lifecycle without hidden Responses/Official fallback or V2-to-V1 downgrade. Chat Code Mode/custom/freeform, client tool_search, arbitrary namespace, search, and hosted parity remain separately dispositioned and are not implied by V2 support.

0.1.8-beta.7 — stability and release-evidence freeze

Gate #319.

• Provider/UI and persisted-route safety: Clarify Provider navigation state after Save or endpoint errors #83 and Keep legacy persisted provider aliases on the selected route across connect/disconnect #203.
• Maintained-Provider regression status versus availability: 0.1.8 Beta7: Separate maintained-Provider regression status from transient availability #247.
• Bounded real-client capture and versioned CLI profile: Harden bounded real-client capture and preserve the accepted 0.1.7 profile #244 and 0.1.8 Beta7: Add the versioned CLI-only release-verification profile #255.
• Bounded request-local retry policy: 0.1.8 Beta7: Bound request-local retries without circuit breaking #256.
• Narrow/reject the excess fix(issue62): integrate bounded live-control evidence hardening #349 evidence-platform scope: 0.1.8 Beta7: Re-scope reusable evidence hardening from draft PR #349 #352.
• Closed Make real-client lifecycle teardown verify the entire tracked process tree #268 remains the process-tree teardown invariant.

This is the final planned beta and adds no capability.

0.1.8-rc.1 — six fixed exact-candidate regressions

Gate #257.

• Responses batches: GLM-5.2 0.1.8 RC1: Run the fixed GLM-5.2 Responses regression batch #287, K2.7 Code 0.1.8 RC1: Run the fixed K2.7 Responses regression batch #288, DeepSeek V4 Flash 0731 0.1.8 RC1: Run the fixed DeepSeek V4 Flash 0731 Responses regression batch #397.
• Chat batches: GLM-5.2 0.1.8 RC1: Run the fixed GLM-5.2 Chat regression batch #289, K2.7 Code 0.1.8 RC1: Run the fixed K2.7 Chat regression batch #290, DeepSeek V4 Flash 0731 0.1.8 RC1: Run the fixed DeepSeek V4 Flash 0731 Chat regression batch #398.
• Aggregate and publish RC: 0.1.8 RC1: Aggregate six fixed regression batches and publish promotion evidence #257.

These are release regressions for maintained Provider configurations, not runtime restrictions on user-configured endpoints. Any product-code change after the fixed batches invalidates the RC candidate.

Stable 0.1.8 — promotion only

Gate #320.

Stable promotion requires the accepted RC lineage, bounded maintainer smoke, no open 0.1.8 P0/P1 regression, exact asset/updater readback, and a human go/no-go. Product-code changes after RC invalidate the candidate.

Current frontier

The active sequence is:

Beta3 issue-state reconciliation
        ↓
#392 exact runtime/wire contract
        ↓
#199 configuration safety + #282 implementation
        ↓
#283 real CLI/App/fixture verification
        ↓
#252 → #284 (Beta4)
        ↓
#275 + #276 + #393 → #351 (Beta5 Responses)
        ↓
#66 → #394 → #395
        ↓
#285 + #286 + #396 → #253/#254 → #259 (Beta6 Chat + V2)
        ↓
#319 → six RC batches → #257 → #320

#324 remains research input rather than a Beta4 runtime allowlist. Broad third-party route matrices, catalog-backed subagent rosters, cross-Home topology/history migration, and Chat Code Mode parity remain post-0.1.8 unless separately promoted.

Mandatory release order

Every beta and RC follows:

1. implementation complete;
2. exact candidate SHA review accepted;
3. CLI/manual verification accepted;
4. local verification gate succeeds on that lineage;
5. tag and prerelease publication.

A failed or incomplete gate stops publication. CI success alone never replaces review or CLI/manual acceptance.

Explicitly out of scope

• Any explicit or implicit cross-Provider tool proxy.
• Runtime model qualification records or named-model allowlists.
• Model selection by CodexHub.
• Provider-hosted capability emulation.
• Gateway-owned tool execution or a second agent scheduler.
• Beta2 alternate-codec retries or model-output format repair.
• Chat Code Mode/custom/freeform, client tool_search, arbitrary namespace, and hosted parity beyond the accepted Beta6 contracts.
• Anthropic Messages/Claude Code integration, provider-onboarding redesign, complete cross-Home history migration, and non-Windows packaging.

Done when

• Beta1 usability prerelease is published and read back.
• Beta2 publishes the generic tool compatibility core.
• Beta3 publishes generic client tool discovery and reversible Code Mode, official model-level V1/V2 controls, and Ollama stream/error classification; Beta3.1–3.3 hotfix regressions remain cumulative.
• Beta4 validates the exact runtime-derived generic Responses Collaboration V2 lifecycle without V1 corruption.
• Beta5 validates the complete Responses surface against GLM-5.2, K2.7 Code, and DeepSeek V4 Flash 0731.
• Beta6 validates usable Ollama Chat and the complete Collaboration V2 lifecycle against the same three routes.
• Beta7 closes stability/evidence work and freezes the RC input.
• RC1 passes all six fixed maintained-Provider batches on one exact candidate.
• Stable 0.1.8 is promoted only through 0.1.8 stable gate: Promote the accepted RC lineage #320.

[NOirBRight]

Decision update: retain only necessary CLI E2E evidence

The 0.1.8 qualification runner must not retain full real-client work roots after a completed run.

• The durable release evidence is limited to the CLI qualification summary, exact candidate/model/route manifest, bounded per-case outcome records, hashes, and sanitized diagnostics required to explain a failure.
• Successful-case isolated Codex homes, client state, copied runtimes, repeated candidate builds, VM images, GUI seeds, and complete work directories are transient and are deleted during runner finalization.
• A failed case may retain only a bounded diagnostic bundle selected by the runner; retaining the complete isolated tree is not an accepted fallback.
• 0.1.8 keeps no Desktop/ZCode/manual qualification state. The single durable product seam remains the real Codex CLI profile agreed in this specification.
• Cleanup must run on success, failure, timeout, and cancellation, and the summary must report whether transient-root cleanup completed.