fix(catalog): harden alias encoding and gather single-flight identity

Wibias · Wibias · commit 8ac098a2c314 · 2026-07-30T09:36:18.000+02:00
Encode / as ~s and literal ~ as ~t so legacy bare-~ aliases keep resolving.
Hash catalog-affecting config into the gather flight key and return
flight-local combo omissions so concurrent keys cannot cross-contaminate.
diff --git a/docs-site/src/content/docs/guides/claude-code.md b/docs-site/src/content/docs/guides/claude-code.md
@@ -191,9 +191,12 @@ the alias back to the routed model. On older Claude Code versions the picker sta
 slots via
 `ANTHROPIC_MODEL` or type any routed id with `/model` (Claude Code passes strings through).
 
-**Alias grammar rules:** provider must not contain `/` or `--` or equal `native`; model must not
-contain `/`. Routes the readable form cannot express fall back to the hashed alias. Model ids
-MAY contain `--` (resolution splits on the first `--` only); native slugs containing `--` fall back to the hashed form.
+**Alias grammar rules:** provider must not contain `/` or `--` or equal `native`.
+Model ids may contain `/` — encoded as `~s` in the alias (e.g. `openrouter/anthropic/claude-opus-4-8`
+→ `claude-ocx-openrouter--anthropic~sclaude-opus-4-8`). Literal `~` in a model id is encoded as `~t`.
+Bare `~` not followed by `s`/`t` is treated as a literal tilde so older persisted aliases keep resolving.
+Routes the readable form cannot express fall back to the hashed alias. Model ids MAY contain `--`
+(resolution splits on the first `--` only); native slugs containing `--` fall back to the hashed form.
 
 **Model resolution order:** `[1m]` marker stripped → readable alias decoded → Desktop hashed
 alias decoded → `modelMap` exact match → date-stripped match (`-20250514` removed) → passthrough.
diff --git a/docs-site/src/content/docs/ko/guides/claude-code.md b/docs-site/src/content/docs/ko/guides/claude-code.md
@@ -116,10 +116,13 @@ Claude Desktop의 하단 선택기로 이미 실행 중인 3P 대화의 모델
 `/model <id>`를 사용하세요. OpenCodex는 선택기 상태를 따로 볼 수 없고 각 요청에 실린 모델 ID를
 라우팅해요. 적용 결과는 **Logs → requestedModel**에서 확인할 수 있어요.
 
-**별칭 문법 규칙:** provider에는 `/`나 `--`를 넣을 수 없고 `native`와 같아도 안 돼요. model에는
-`/`를 넣을 수 없어요. 읽기 쉬운 형식으로 표현할 수 없는 라우트는 해시 별칭으로 대체해요. 모델
-ID에는 `--`를 넣을 **수 있어요**(해석할 때 첫 번째 `--`만 기준으로 나눠요). `--`가 포함된
-네이티브 슬러그는 해시 형식으로 대체해요.
+**별칭 문법 규칙:** provider에는 `/`나 `--`를 넣을 수 없고 `native`와 같아도 안 돼요. model ID에
+`/`가 있으면 별칭에서 `~s`로 인코딩해요(예: `openrouter/anthropic/claude-opus-4-8` →
+`claude-ocx-openrouter--anthropic~sclaude-opus-4-8`). model ID의 리터럴 `~`는 `~t`로 인코딩해요.
+`s`/`t`가 따르지 않는 단독 `~`는 예전 설정과의 호환을 위해 리터럴 `~`로 해석해요. 읽기 쉬운
+형식으로 표현할 수 없는 라우트는 해시 별칭으로 대체해요. 모델 ID에는 `--`를 넣을 **수 있어요**
+(해석할 때 첫 번째 `--`만 기준으로 나눠요). `--`가 포함된 네이티브 슬러그는 해시 형식으로
+대체해요.
 
 **모델 해석 순서:** `[1m]` 표식 제거 → 읽기 쉬운 별칭 디코딩 → Desktop 해시 별칭 디코딩 →
 `modelMap` 정확히 일치 → 날짜를 제거한 값과 일치(`-20250514` 제거) → 패스스루 순서예요.
diff --git a/src/claude/alias.ts b/src/claude/alias.ts
@@ -9,10 +9,13 @@
  *
  * Reversibility rules:
  *  - providers containing `--` or `/` are not aliased (split boundary safety);
- *  - model ids MAY contain `/` — encoded as `~` so the alias stays slash-free
+ *  - model ids MAY contain `/` — encoded as `~s` so the alias stays slash-free
  *    for Claude Code's picker (e.g. openrouter `anthropic/claude-opus-4-8` →
- *    `claude-ocx-openrouter--anthropic~claude-opus-4-8`);
- *  - model ids that already contain `~` are not aliased (encode collision);
+ *    `claude-ocx-openrouter--anthropic~sclaude-opus-4-8`);
+ *  - model ids MAY contain `~` — encoded as `~t` (so slash encoding cannot
+ *    collide with a literal tilde that older releases already persisted);
+ *  - bare `~` not followed by `s`/`t` is left as a literal tilde on decode
+ *    (legacy aliases from before slash encoding);
  *  - model ids MAY contain `--` (resolve splits on the FIRST `--` only);
  *  - native OpenAI slugs use the pseudo-provider `native` and resolve back to
  *    the bare slug; a real provider named "native" is therefore never aliased.
@@ -21,33 +24,53 @@
 import { desktop3pAlias } from "./desktop-3p";
 
 export const CLAUDE_ALIAS_PREFIX = "claude-ocx-";
-/** Stand-in for "/" inside the model portion of a Claude Code alias. */
-const CLAUDE_ALIAS_SLASH_ENC = "~";
+/** Encoded `/` inside the model portion of a Claude Code alias. */
+const CLAUDE_ALIAS_SLASH_ENC = "~s";
+/** Encoded literal `~` inside the model portion of a Claude Code alias. */
+const CLAUDE_ALIAS_TILDE_ENC = "~t";
 const NATIVE_PSEUDO_PROVIDER = "native";
 
-function encodeModelId(modelId: string): string | null {
-  if (modelId.includes(CLAUDE_ALIAS_SLASH_ENC)) return null;
-  return modelId.replaceAll("/", CLAUDE_ALIAS_SLASH_ENC);
+function encodeModelId(modelId: string): string {
+  // Escape literal tildes first so slash encoding cannot create ambiguity.
+  return modelId
+    .replaceAll("~", CLAUDE_ALIAS_TILDE_ENC)
+    .replaceAll("/", CLAUDE_ALIAS_SLASH_ENC);
 }
 
 function decodeModelId(encoded: string): string {
-  return encoded.replaceAll(CLAUDE_ALIAS_SLASH_ENC, "/");
+  let out = "";
+  for (let i = 0; i < encoded.length; i++) {
+    if (encoded[i] === "~" && i + 1 < encoded.length) {
+      const next = encoded[i + 1];
+      if (next === "s") {
+        out += "/";
+        i += 1;
+        continue;
+      }
+      if (next === "t") {
+        out += "~";
+        i += 1;
+        continue;
+      }
+    }
+    // Bare `~` (legacy pre-slash-encoding aliases) stays a literal tilde.
+    out += encoded[i];
+  }
+  return out;
 }
 
 /** Alias for a routed "<provider>/<model>" pair; null when not representable. */
 export function aliasForRoute(provider: string, modelId: string): string | null {
   if (!provider || provider.includes("--") || provider.includes("/") || provider === NATIVE_PSEUDO_PROVIDER) return null;
   if (!modelId) return null;
-  const encoded = encodeModelId(modelId);
-  if (encoded === null) return null;
-  return `${CLAUDE_ALIAS_PREFIX}${provider}--${encoded}`;
+  return `${CLAUDE_ALIAS_PREFIX}${provider}--${encodeModelId(modelId)}`;
 }
 
 /** Alias for a native OpenAI slug (bare model id, no provider namespace). */
 export function aliasForNative(slug: string): string | null {
-  // Reject "/" and "~" — "~" is the slash stand-in; allowing it would round-trip wrong via decodeModelId.
-  if (!slug || slug.includes("/") || slug.includes("--") || slug.includes(CLAUDE_ALIAS_SLASH_ENC)) return null;
-  return `${CLAUDE_ALIAS_PREFIX}${NATIVE_PSEUDO_PROVIDER}--${slug}`;
+  // Reject "/" — native ids are bare slugs. Literal `~` is fine via ~t encoding.
+  if (!slug || slug.includes("/") || slug.includes("--")) return null;
+  return `${CLAUDE_ALIAS_PREFIX}${NATIVE_PSEUDO_PROVIDER}--${encodeModelId(slug)}`;
 }
 
 /**
diff --git a/src/codex/catalog/provider-fetch.ts b/src/codex/catalog/provider-fetch.ts
@@ -58,20 +58,68 @@ import upstreamModelsSnapshot from "../data/upstream-models.json";
 import { JAWCODE_CATALOG_AUGMENT_PROVIDERS, catalogModelSlug, shouldExposeRoutedModel } from "./parsing";
 import type { CatalogModel } from "./parsing";
 import { disabledNativeSlugs, hasComboTargets, nativeInputModalities, nativeOpenAiContextWindow, nativeOpenAiSlugs, nativeParallelToolCalls, nativeReasoningEfforts } from "./metadata";
-import { deriveComboCatalogModel, getLastComboCatalogOmissions, normalizedOpenAiApiSignature, openAiApiCollisionWarnings, replaceLastComboCatalogOmissions, warnUncataloguedComboOnce } from "./aggregation";
+import { deriveComboCatalogModel, normalizedOpenAiApiSignature, openAiApiCollisionWarnings, replaceLastComboCatalogOmissions, warnUncataloguedComboOnce } from "./aggregation";
 import type { ComboCatalogOmission } from "./aggregation";
 
-/** Concurrent gatherRoutedModels callers with the same provider set share one live discovery.
- *  Keyed by gatherFlightKey so a different provider set cannot evict an in-flight gather. */
-const gatherInflight = new Map<string, Promise<CatalogModel[]>>();
+/** Concurrent gatherRoutedModels callers with the same catalog identity share one live discovery.
+ *  Keyed by gatherFlightKey so a different config cannot join or evict the wrong flight. */
+interface GatherFlightResult {
+  models: CatalogModel[];
+  comboOmissions: ComboCatalogOmission[];
+}
+
+const gatherInflight = new Map<string, Promise<GatherFlightResult>>();
+
+function stableJson(value: unknown): string {
+  return JSON.stringify(value, (_key, nested) => {
+    if (nested && typeof nested === "object" && !Array.isArray(nested)) {
+      return Object.fromEntries(Object.entries(nested as Record<string, unknown>).sort(([a], [b]) => a.localeCompare(b)));
+    }
+    return nested;
+  });
+}
+
+function providerCatalogFingerprint(name: string, prov: OcxProviderConfig): Record<string, unknown> {
+  return {
+    n: name,
+    live: prov.liveModels !== false,
+    base: prov.baseUrl ?? "",
+    adapter: prov.adapter ?? "",
+    models: [...(prov.models ?? [])].sort(),
+    defaultModel: prov.defaultModel ?? null,
+    ctx: prov.contextWindow ?? null,
+    ctxW: prov.modelContextWindows ?? null,
+    maxIn: prov.modelMaxInputTokens ?? null,
+    inMod: prov.modelInputModalities ?? null,
+    re: prov.modelReasoningEfforts ?? null,
+    defRe: prov.modelDefaultReasoningEfforts ?? null,
+    rsSum: prov.modelSupportsReasoningSummaries ?? null,
+    rsDel: prov.modelReasoningSummaryDelivery ?? null,
+    noVis: [...(prov.noVisionModels ?? [])].sort(),
+    ptc: prov.parallelToolCalls ?? null,
+    gMode: prov.googleMode ?? null,
+  };
+}
 
 function gatherFlightKey(config: OcxConfig): string {
   const providers = Object.entries(config.providers)
     .filter(([, prov]) => prov.disabled !== true)
-    .map(([name, prov]) => `${name}\0${prov.liveModels === false ? "0" : "1"}\0${prov.baseUrl ?? ""}`)
-    .sort()
-    .join("\n");
-  return `${providers}\n#${config.modelCacheTtlMs ?? DEFAULT_MODEL_CACHE_TTL_MS}`;
+    .map(([name, prov]) => providerCatalogFingerprint(name, prov))
+    .sort((a, b) => String(a.n).localeCompare(String(b.n)));
+  const assembly = stableJson({
+    providers,
+    combos: config.combos ?? {},
+    customModels: (config.customModels ?? []).map((cm) => ({
+      p: cm.provider,
+      m: cm.modelId,
+      d: cm.displayName ?? null,
+      cw: cm.contextWindow ?? null,
+      im: cm.inputModalities ?? null,
+    })),
+    caps: config.providerContextCaps ?? null,
+  });
+  const digest = createHash("sha256").update(assembly).digest("hex").slice(0, 16);
+  return `${digest}#${config.modelCacheTtlMs ?? DEFAULT_MODEL_CACHE_TTL_MS}`;
 }
 
 /** Drop in-flight gather so tests / full cache clears do not reuse a stale promise. */
@@ -594,27 +642,25 @@ export async function gatherRoutedModels(
   let promise = gatherInflight.get(key);
   if (!promise) {
     // Claim the slot synchronously before any await so same-key callers join this flight.
-    // Distinct keys keep their own entries — a second provider set must not evict the first.
-    const flight = gatherRoutedModelsUncached(config, options).finally(() => {
+    // Distinct keys keep their own entries — a second config must not evict the first.
+    const flight = gatherRoutedModelsUncached(config).finally(() => {
       if (gatherInflight.get(key) === flight) gatherInflight.delete(key);
     });
     gatherInflight.set(key, flight);
     promise = flight;
   }
-  const models = await promise;
+  const { models, comboOmissions } = await promise;
   if (options?.comboOmissions) {
-    const last = getLastComboCatalogOmissions();
     options.comboOmissions.length = 0;
-    options.comboOmissions.push(...last);
+    options.comboOmissions.push(...comboOmissions);
   }
   return models;
 }
 
 async function gatherRoutedModelsUncached(
   config: OcxConfig,
-  options?: { comboOmissions?: ComboCatalogOmission[] },
-): Promise<CatalogModel[]> {
-  // Per-invocation list: sync passes `comboOmissions` so overlapping gathers cannot race.
+): Promise<GatherFlightResult> {
+  // Flight-local list: joiners copy from the resolved promise, not a process-global last write.
   const localOmissions: ComboCatalogOmission[] = [];
   const ttlMs = config.modelCacheTtlMs ?? DEFAULT_MODEL_CACHE_TTL_MS;
   // Persisted provider entries can predate newer registry fields (noVisionModels,
@@ -696,10 +742,6 @@ async function gatherRoutedModelsUncached(
     else warnUncataloguedComboOnce(id, combo, members, localOmissions);
   }
   replaceLastComboCatalogOmissions(localOmissions);
-  if (options?.comboOmissions) {
-    options.comboOmissions.length = 0;
-    options.comboOmissions.push(...localOmissions);
-  }
   all.sort((a, b) => (a.provider === b.provider ? a.id.localeCompare(b.id) : a.provider.localeCompare(b.provider)));
   // Enriched (registry-hydrated) provider clones, keyed by name — the same view used above so
   // custom rows get the same noVisionModels / inputModalities treatment as discovered rows.
@@ -733,7 +775,7 @@ async function gatherRoutedModelsUncached(
   // Custom rows override discovered rows that encode to the same Codex-facing slug.
   const customKeys = new Set(customModels.map(c => routedSlug(c.provider, c.id)));
   const deduped = all.filter(m => !customKeys.has(routedSlug(m.provider, m.id)));
-  return [...deduped, ...customModels];
+  return { models: [...deduped, ...customModels], comboOmissions: localOmissions };
 }
 
 export function augmentRoutedModelsWithRegistryOpenAiApiRows(
diff --git a/tests/claude-alias.test.ts b/tests/claude-alias.test.ts
@@ -32,25 +32,31 @@ describe("claude discovery aliases", () => {
     expect(aliasForRoute("has--dashes", "m")).toBeNull();
     expect(aliasForRoute("has/slash", "m")).toBeNull();
     expect(aliasForRoute("native", "m")).toBeNull(); // reserved pseudo-provider
-    expect(aliasForRoute("p", "has~tilde")).toBeNull(); // encode collision with slash stand-in
     expect(aliasForRoute("", "m")).toBeNull();
     expect(aliasForRoute("p", "")).toBeNull();
     expect(aliasForNative("a--b")).toBeNull();
-    expect(aliasForNative("a~b")).toBeNull(); // same encode collision as routed models
+    expect(aliasForNative("org/model")).toBeNull(); // native ids stay bare
   });
 
-  test("model ids with '/' encode as '~' and round-trip (OpenRouter-shaped)", () => {
+  test("model ids with '/' encode as '~s' and round-trip (OpenRouter-shaped)", () => {
     const alias = aliasForRoute("openrouter", "anthropic/claude-opus-4-8");
-    expect(alias).toBe(`${CLAUDE_ALIAS_PREFIX}openrouter--anthropic~claude-opus-4-8`);
+    expect(alias).toBe(`${CLAUDE_ALIAS_PREFIX}openrouter--anthropic~sclaude-opus-4-8`);
     expect(resolveAlias(alias!)).toBe("openrouter/anthropic/claude-opus-4-8");
     expect(claudeCodeAlias("openrouter", "meta-llama/llama-3.3-70b-instruct:free")).toBe(
-      `${CLAUDE_ALIAS_PREFIX}openrouter--meta-llama~llama-3.3-70b-instruct:free`,
+      `${CLAUDE_ALIAS_PREFIX}openrouter--meta-llama~sllama-3.3-70b-instruct:free`,
     );
     expect(resolveAlias(claudeCodeAlias("openrouter", "meta-llama/llama-3.3-70b-instruct:free"))).toBe(
       "openrouter/meta-llama/llama-3.3-70b-instruct:free",
     );
   });
 
+  test("literal '~' in model ids encodes as '~t' and legacy bare '~' still resolves", () => {
+    expect(aliasForRoute("demo", "old~model")).toBe(`${CLAUDE_ALIAS_PREFIX}demo--old~tmodel`);
+    expect(resolveAlias(`${CLAUDE_ALIAS_PREFIX}demo--old~tmodel`)).toBe("demo/old~model");
+    // Pre-slash-encoding aliases kept literal tildes in the model portion.
+    expect(resolveAlias(`${CLAUDE_ALIAS_PREFIX}demo--old~model`)).toBe("demo/old~model");
+  });
+
   test("resolveAlias rejects non-aliases and malformed ids", () => {
     expect(resolveAlias("claude-sonnet-4-5")).toBeNull();
     expect(resolveAlias("gpt-5.5")).toBeNull();
@@ -96,25 +102,25 @@ describe("claudeCodeAlias — readable-or-hash shared helper (devlog 050 / audit
 
   test("slash-containing model ids stay readable (no desktop-3p hash)", () => {
     expect(claudeCodeAlias("openrouter", "anthropic/claude-opus-4-8")).toBe(
-      "claude-ocx-openrouter--anthropic~claude-opus-4-8",
+      "claude-ocx-openrouter--anthropic~sclaude-opus-4-8",
     );
-    expect(claudeCodeAlias("mock", "path/model")).toBe("claude-ocx-mock--path~model");
-    expect(resolveInboundModel("claude-ocx-openrouter--anthropic~claude-opus-4-8", undefined)).toBe(
+    expect(claudeCodeAlias("mock", "path/model")).toBe("claude-ocx-mock--path~smodel");
+    expect(resolveInboundModel("claude-ocx-openrouter--anthropic~sclaude-opus-4-8", undefined)).toBe(
       "openrouter/anthropic/claude-opus-4-8",
     );
   });
 
   test("unrepresentable shapes fall back to the desktop-3p hash — model never disappears", () => {
-    // provider literally "native", provider with separators, model id with "~",
-    // native slug with "--" (audit 051 #2 null-case coverage).
+    // provider literally "native", provider with separators, native slug with "--".
+    // Model ids with "~" are now representable via ~t encoding.
     for (const id of [
       claudeCodeAlias("native", "gpt-5.6-sol"),
       claudeCodeAlias("weird--provider", "m1"),
       claudeCodeAlias("a/b", "m2"),
-      claudeCodeAlias("mock", "has~tilde"),
       claudeCodeNativeAlias("slug--with-sep"),
     ]) {
       expect(id).toMatch(/^claude-opus-4-8-[a-z][0-9a-z]{2}$/);
     }
+    expect(claudeCodeAlias("mock", "has~tilde")).toBe("claude-ocx-mock--has~ttilde");
   });
 });
diff --git a/tests/gather-routed-models-single-flight.test.ts b/tests/gather-routed-models-single-flight.test.ts
