[Bl0ck154]

Scope and safety

This is the new upstream-first staging lane, not a production PR or deployment.

• Clean baseline: official cheaper-inference/OmniRoute release/v3.8.53 at 5b3be70ba82ce70b59d02e2893afa3d81b6ee88b.
• Keep production and historical full-merge draft DRAFT: full upstream v3.8.53 integration — fork collision review required #43 unchanged.
• Never merge this staging branch into production until all required fork-only patches are reviewed, the full off-host verification gates pass, and a canary + rollback plan is approved. No production VPS build.

Ported in phase 1

• URL-only multipart audio transcription with SSRF-safe downloading and regression tests, from upstream contribution fix(api): support URL-only speech transcription with SSRF-safe media download cheaper-inference/OmniRoute#18040. Preserves existing uploaded-file and fallback semantics.
• Antigravity pre-response/header-timeout marker retention and no same-account replay on 504; retain 503 and Codex retry behavior, from fix(antigravity): preserve header-timeout cause and avoid same-account 504 replay cheaper-inference/OmniRoute#18052.
• Paid-only Codex Sol/Astra eligibility filter excluding Free OAuth accounts, from fix(codex): skip Free OAuth accounts for paid-only Sol and Astra models cheaper-inference/OmniRoute#17961.

The contributions are kept as Git ancestry and integrated by non-overlapping file changes. Against the pinned clean baseline the GitHub diff must show exactly these 13 code/test paths. Individual feature-branch tests are not equivalent to green combined CI. In particular the speech contribution's selective CI run is not proof of full release readiness.

Remaining migration audit (not yet ported)

The current production fork diverges substantially; an initial git rev-list --right-only --cherry-pick --no-merges against the pinned official tip reports 89 patch-id-distinct non-merge commits. This is a candidate review queue, not 89 guaranteed necessary patches: many are historical backports already semantically present upstream or superseded.

1. Review per-API-key connection ordering/preference and the corresponding settings UI, custom model/connection fallback, and 12-second preferred Gemini 3.8 header budget. The old upstream contribution feat(auth): add per-API-key ordered connection preference cheaper-inference/OmniRoute#13102 changes 91 paths and is not safe for blind file copying.
2. Compare all Codex/Astra/Luna/Claude/Antigravity model naming, account-plan gating and adaptive quarantine, with particular attention to retry budget, cancel propagation and tenant isolation.
3. Review dedicated image generation/edit routes, 16-image references, paid image quota accounting and artifact persistence. Some image PRs have already merged upstream; preserve only unresolved behavior.
4. Verify database migrations (new upstream migration order and safe WAL), startup/cache behavior, usage accounting and security controls before transferring custom schema migrations.
5. Separate fork-only packaging, operation scripts, release workflows and production credentials from upstream code; never include secrets.
6. Use DRAFT: full upstream v3.8.53 integration — fork collision review required #43 and its tracked collision inventory docs/maintenance/UPSTREAM_MERGE_3853_REVIEW.md only as an audit reference. It had 144 conflict paths and provisional fork-favored resolutions and must not be used as proof of compatibility.

Required acceptance

• Verify no missing/extra files from the three phase-1 contributions.
• Off-host focused tests for speech URL SSRF/cancellation, Antigravity 503/504 timeout/fallback, and Free-vs-paid Codex plan routing.
• Off-host core typecheck, wider Node/Vitest CI, release build and packaged smoke.
• Full own-patch semantic audit, inventory upstream-accepted PRs and removed/obsolete custom logic.
• Validate schema migration order/idempotency, rollback, and database backup in isolation.
• Run isolated synthetic-account canary (no personal data), then staged rollout with metrics and reversible rollback.
• Explicitly confirm production routing works for Oscar and other dependent clients.

No production changes, no deploy and no release authorization by opening this draft.

[Bl0ck154]

Migration audit checkpoint — 2026-10-24 (read-only semantic review)

Scope: This is not a merge/deploy approval. Keep the current production branch and running VPS artifact unchanged. No local builds/tests on the production server.

Already in upstream v3.8.53 — do not replay old fork commits

Verified via official release ancestry and/or source:

• fix(codex-images): allow 16 references for dedicated GPT Image edits cheaper-inference/OmniRoute#16623 dedicated GPT Image edits up to 16 references (upstream commit 8926293e78).
• feat(audio): expand Fish Audio S2.1 and voice cloning cheaper-inference/OmniRoute#13090 Fish Audio S2.1 / voice cloning (62d14a7fc7).
• fix(sse): honor Google RPC ErrorInfo quota-reset metadata as an upstream retry hint cheaper-inference/OmniRoute#16529 Google RPC retry hint (39e30eb509); fix(sse): keep generated-image deltas in OpenAI-format streams cheaper-inference/OmniRoute#16540 image deltas (4fee5568d1); fix(claude): drop the Claude Code diagnostics telemetry field Anthropic rejects cheaper-inference/OmniRoute#16543 Claude diagnostics (02fbc29ee5); fix(logging): mask URL query credentials and secret headers in request capture, write call-log artifacts 0600 cheaper-inference/OmniRoute#16484 credential log sanitization (b451f1813e); fix(sse): normalize OpenAI tool-call IDs longer than 64 characters cheaper-inference/OmniRoute#16490 long tool-call IDs (3527f04998).
• fix(codex): convert the fake-200 "servers are currently overloaded" output stream into a 503 cheaper-inference/OmniRoute#16287 Codex fake-200 overload (f490ddb27f); fix(codex): retry once without undecryptable reasoning ciphertext cheaper-inference/OmniRoute#16288 ciphertext retry (87bdbfaa8b); fix(usage): retry a usage write once when the database is locked cheaper-inference/OmniRoute#16276 usage DB lock retry (429e7f1ffd); Codex encrypted reasoning replay failures can be masked as STREAM_EARLY_EOF cheaper-inference/OmniRoute#16364/fix(sse): surface Codex replay-reasoning rejections instead of masking them as STREAM_EARLY_EOF (#16364) cheaper-inference/OmniRoute#16375 replay errors (8fc2b689a5); fix(resilience): crash guard re-throws empty_response during a combo retry, killing the server with exit code 7 cheaper-inference/OmniRoute#16347/fix(resilience): keep empty_response stream errors from killing the server via the crash guard (#16347) cheaper-inference/OmniRoute#16359 crash guard (1f9aee0551).
• feat(combos): opt-in auto-prune of stale combo steps after a model sync cheaper-inference/OmniRoute#15925 combo prune; fix(resilience): scope explicit Codex overload cooldown to exact model cheaper-inference/OmniRoute#16014 model cooldown; fix(combo): drop malformed custom models from the auto candidate pool cheaper-inference/OmniRoute#16069 malformed candidates; fix(providers): antigravity live catalogs list only gemini-3.8-flash-tiered — the -high/-medium/-low tiers are refused by the live-catalog check (same shift as 3.7 in #10341) cheaper-inference/OmniRoute#15659/fix(antigravity): accept Gemini Flash tier ids on accounts whose live catalog lists only -tiered (#15659) cheaper-inference/OmniRoute#15735 tiered model ids; fix(codex): hand off live SSE after readiness event cheaper-inference/OmniRoute#15094 SSE readiness; feat(providers): add Claude Opus 5.5 support cheaper-inference/OmniRoute#14546 Claude Opus 5.5 are also in official ancestry. Production fork's commit SHAs may differ, but this functionality is already upstream.
• Current official src/shared/utils/httpClientAbortGuard.mjs handles RELAY_TIMEOUT and relay_timeout plus BodyTimeoutError; do not cherry-pick the older fork guard replacement wholesale.
• GPT-6.1 Sol identifiers already exist in the current official Codex model catalog; review behavior, not just name presence.

Important fork-only features still absent

1. Per-key preferred connection order (feat(auth): add per-API-key ordered connection preference cheaper-inference/OmniRoute#13102), absent in the official apiKeys.ts and credential selection. git merge-tree of current Draft: upstream-first patch migration — phase 1 (speech, Antigravity, Codex) #51 head and feat(auth): add per-API-key ordered connection preference cheaper-inference/OmniRoute#13102's branch yields exactly three textual conflicts: src/i18n/messages/{en,pt-BR,vi}.json, each between newer removeSelection and the branch's four preferredConnections* labels. Preserve both keys. Core TypeScript text merges, but semantic checks remain.
2. 12s Gemini 3.8 preferred-connection header budget (cf149dc6ab) is NOT in official; its helper src/sse/services/preferredConnectionFailover.ts is absent. It relies on fork-only selectedByApiKeyPreference + preferredFallbackAvailable metadata. The upstream-contribution preference branch does not yet carry the fork-specific preferredFallbackAvailable materialization. Therefore feat(auth): add per-API-key ordered connection preference cheaper-inference/OmniRoute#13102 alone is insufficient for our customized routing; port them together with focused tests.
3. Order Forge paid image artifact retention src/lib/usage/orderForgeImageArtifactSink.ts (fork-only), and Codex image quota telemetry src/lib/images/codexImageQuotaTelemetry.ts (fork-only) are imported by live fork handlers but absent from official. The historical codexImageArtifactSink.ts itself is already removed from current production; do not resurrect it from old commits.
4. Gemini 3.5 Flash-Lite in the Antigravity shared live model registry is fork-only (f925f9508), despite the model ID appearing elsewhere in upstream registries. Revalidate live eligibility and thinking-level mapping before porting. Do not blindly claim all future Flash generations are free based on an older catalog patch.

P0 database migration incompatibility

• Fork production: src/lib/db/migrations/194_api_key_preferred_connections.sql adds api_keys.preferred_connections.
• Official v3.8.53: 194_proxy_logs_attempt_timing.sql instead adds proxy_logs.headers_ms and first_chunk_ms; official applies migration ids by version and only logs a mismatch warning. A ledger row 194/api_key_preferred_connections must not cause official 194_proxy_logs_attempt_timing to be skipped.
• Clean preferred-connection contribution (feat(auth): add per-API-key ordered connection preference cheaper-inference/OmniRoute#13102) moves the fork column to 213_api_key_preferred_connections.sql, but without historical ledger remapping.
• Staging PR DRAFT: full upstream v3.8.53 integration — fork collision review required #43 has the necessary compatibility ideas: in src/lib/db/migrationRunner/constants.ts, rehome both historical 170/api_key_preferred_connections and 194/api_key_preferred_connections to 213/api_key_preferred_connections. In migrationRunner.ts, slot 194 schema guard must check both proxy log timing columns; slot 213 must check api_keys.preferred_connections. Review and port these narrow changes, not the entire draft DRAFT: full upstream v3.8.53 integration — fork collision review required #43 conflict-resolved source tree.
• Must verify the migration ledger and physical columns read-only on the existing database, then test copied DB variants (legacy 170; legacy 194; new 213; new install; already-migrated) with backup, idempotence, repeat startup, and rollback. Do not run migrations directly on production.

Acceptance before integrating the next tranche

Keep PR #51 draft. Stage preferred-connection feature + historical migration bridge + 12s timeout in a separate isolated branch, resolve the three localization conflicts by key union, then run focused auth/tenant-boundary, retry/lease, DB-migration tests and core typecheck/off-host build. Image quota/artifact changes require a separate review/PR. No force push, production merge, service restart or live migrations.

Current head: 7453869c113007e374e1305b0816c89b361628d8; base: 5b3be70ba82ce70b59d02e2893afa3d81b6ee88b. Tests of the combined branch have not run yet.

[Bl0ck154]

Follow-up correction — current production advanced during the audit (2026-10-24)

Refreshed the fork's actual origin/production at db8bc29670b401b2dd25b2c1491039e6e1aed7ac; the older 89 patch-id-distinct non-merge candidate count referred to the earlier 6e913620b3 snapshot. Against the same pinned official upstream 5b3be70ba8, the refreshed fork now shows 110 candidate commits. Neither count means every item needs porting.

VPS /opt/omniroute-current now points to 3.8.52-custom.35 (observed via symlink, 2026-10-24). This investigation did not change/restart that release.

Important newly identified production work absent from current phase-1 #51:

• Fork #47: adaptive Antigravity per-(account,model) quarantine, 499 exclusion, bounded half-open recovery, structured timing telemetry and DB-persisted hot failover timeout settings + admin API/UI. The upstream fix(antigravity): preserve header-timeout cause and avoid same-account 504 replay cheaper-inference/OmniRoute#18052 and phase-1 Draft: upstream-first patch migration — phase 1 (speech, Antigravity, Codex) #51 cover only the narrower 504 metadata/same-account replay piece.
• Fork #49: release in-flight telemetry slots for discarded 403/429/non-2xx responses, 300s observation expiration without consuming/aborting the response body. This must accompany the fork-only telemetry implementation; do not port feat(api): adaptive Antigravity resilience, model quarantine and hot timeouts #47 without fix: prevent Antigravity timing metrics from leaking on ignored responses #49.
• Fork #46: pinned-fetch cleanup is already upstream and should NOT be reimplemented; keep the regression test where possible.
• New tracked authoritative documents already on production: docs/maintenance/FORK_PATCH_REGISTER.md, UPSTREAM_PARITY_GAP_AUDIT_20261024.md and UPSTREAM_UPGRADE_RUNBOOK.md. The parity-gap audit already verified the live SQLite DB read-only: migration ledger entry 194/api_key_preferred_connections exists, corresponding api_keys column exists, and the official proxy_logs.headers_ms/first_chunk_ms columns are missing. Thus the 194 collision is confirmed on the installed DB, not merely hypothetical. Avoid a redundant live data read.
• The upstream-first branch Draft: upstream-first patch migration — phase 1 (speech, Antigravity, Codex) #51 still lacks the fork's custom migration rehome, feat(auth): add per-API-key ordered connection preference cheaper-inference/OmniRoute#13102 preferences, advanced Antigravity health/telemetry/settings and Order Forge image retention. The next code tranche should target compatibility across these, not overwrite official source.

No production code, DB, services, release packaging or GitHub production branch modified in this audit.

[Bl0ck154]

Phase 2 staged independently as draft PR #52 on top of migration/port-custom-20261024: API-key ordered preferred connections / management UI / localization, historical SQLite 170 and 194 ledger remap to canonical 213, official 194 two-column check, and synthetic regression tests. #52 intentionally not merged; await complete off-host verification and additional fork-only preferred timeout/adaptive Antigravity work. API Route Typecheck passed on #52 SHA fd66e6b70f; full CI requested here.

[Bl0ck154]

2026-10-25 upstream-first migration chain now has two further isolated drafts: #52 per-API-key preferences, historical SQLite 170/194→213 bridge and modern Antigravity preferred 5s/12s header-cap with its focused hosted CI green; and #53 staged standalone adaptive model health / telemetry modules (including PR #49 fixes), NOT wired to live routing. A trial wholesale upstream-port of old #47 found 10 conflicts; no outdated fork handlers were copied wholesale. First #53 hosted run exposed three old runtime retry tests that still fail against modern upstream. Those are documented as mandatory phase-3B integration tests, not silently passed; narrow phase-3A retest at https://github.com/Bl0ck154/OmniRoute/actions/runs/40133727646. Keep all PRs draft and do not deploy. Full-release CI/migration/retry integration gates remain open.

[Bl0ck154]

2026-10-25 upstream contribution milestone: existing official #18052 advanced with general Antigravity 504/header-timeout protection through URL + Pro candidate retries and Codex-preserving tests at abf1278f61; existing #13102 refreshed against official v3.8.53 head 81e48878b9, all 3 locale merge conflicts resolved, official API reports mergeable:true (check state may still be unstable). Opened entirely new upstream #18096 to fix the general 194 proxy timing migration two-column guard (four synthetic SQLite combinations), Draft until CI. Internally, stacked #54 reintroduces and passes the three previously-failing runtime timeout retry regressions on hosted run 40159734648. No production deploy, real DB migration, server build or service restart.

[Bl0ck154]

Migration audit progress (2026-10-25): staged fork-specific PR #61 restored scoped Order Forge private image artifact sink on direct generations, its hosted regression passed run 40165254621. Stacked PR #64 extends to success-only edits/combos; hosted run 40171544636 green. Stacked PR #66 imports independent Codex image quota rollover arithmetic; hosted run 40171767874 green. Other agents have independent image branches #65 and #67 in progress; do not overwrite their worktrees. Broader Quality Gates still have multiple blockers and need review; runtime image quota header wiring, streamed Responses capture, copied-old-DB migration rehearsal, off-host full-build smoke and canary remain incomplete. Production release remains unchanged.

[Bl0ck154]

2026-10-25 image/CI staging snapshot, do not deploy: image artifact fork parity is now decomposed across stacked draft #61 (direct generations), #64 (edit direct+combo), #67 (Firefly edits), #68 (Responses nonstream/SSE), #69 (generation combo) plus parallel draft #66 (Codex quota telemetry core ONLY). Image sink tests, Firefly and Responses focused CI were GREEN on their exact SHAs; #69 CI here was in progress. Duplicate #65 closed without merge. Draft #60 fixed drift from 209→210 migrations/locale docs and manual changelog ancestor; draft #62 addresses compatibility findings independently. Broad CI run 40164339727 failed multiple suites + dependency security ratchet; no release readiness claimed. Existing production /opt/omniroute-current remains 3.8.52-custom.35; no live DB write, build, service restart or release publication.