From 0a8f6a326ef220e499c2fd5aaf14bba61ed05a68 Mon Sep 17 00:00:00 2001
From: JUN <jun@lidgeai.com>
Date: Wed, 11 Nov 2026 08:14:14 +0900
Subject: [PATCH 1/5] feat(aliases): opt-in per-provider alias templates

#7705, as approved: a provider may set aliasTemplate (for example
"{providerAlias}-{modelBasename}") to name every model that has no manual or
built-in alias. Aliases are derived at resolution time and never written to
config, so a newly discovered model gets its alias immediately and removing the
template removes them.

Only the literal {providerAlias} and {modelBasename} placeholders exist and the
basename is required. Manual > Builtin > Template. A candidate is skipped, never
renamed, when it is invalid, uses a reserved prefix, or matches anything already
claimed (native ids, provider aliases, built-in alias names, provider names,
other providers' manual aliases, combo ids and aliases); colliding candidates
are both skipped so the result is roster-order invariant.

effectiveModelAliases/resolveModelAlias take an optional providerName that all
seven callers pass. PUT /api/providers/{provider}/alias-template validates,
saves and previews; GET /api/aliases lists templates and template-sourced rows;
ocx alias template set|rm|show; an invalid hand-edited template is dropped with
a warning at load.

Closes #7705
---
 .../src/content/docs/guides/model-routing.md  |   6 +
 docs-site/src/content/docs/reference/cli.md   |   2 +-
 .../docs/reference/configuration/providers.md |   2 +-
 scripts/test-layout/layout-providers.json     |   1 +
 .../ocx/references/01_management_surface.md   |  18 ++-
 .../references/01_surface_providers-models.md |  52 ++++++-
 src/cli/alias.ts                              |  39 ++++-
 src/cli/capabilities-provider-models.ts       |  16 ++
 src/clients/config-export/alias-selectors.ts  |   2 +-
 src/codex/catalog/routed-gather.ts            |   2 +-
 src/config/load-degrade.ts                    |   9 +-
 src/config/schema/leaf-validators.ts          |   2 +
 src/providers/alias-template.ts               |  48 ++++++
 src/providers/default-aliases.ts              | 116 +++++++++++---
 src/providers/model-rename-fields.ts          |   1 +
 src/router.ts                                 |   4 +-
 src/server/auth-cors.ts                       |   1 +
 src/server/index/serve-options.ts             |   1 +
 src/server/management/model-routes.ts         |  43 +++++-
 .../management/provider-completion-test.ts    |   8 +-
 src/server/management/route-registry.ts       |   1 +
 src/types/provider.ts                         |   6 +
 tests/cli/cli-alias-json.test.ts              |  33 ++++
 .../codex-convergence-contract.test.ts        |   9 +-
 tests/fixtures/test-layout-expected.json      |   2 +-
 .../providers/provider-alias-template.test.ts | 143 ++++++++++++++++++
 tests/server/alias-management-api.test.ts     |  23 +++
 27 files changed, 544 insertions(+), 46 deletions(-)
 create mode 100644 src/providers/alias-template.ts
 create mode 100644 tests/providers/provider-alias-template.test.ts

diff --git a/docs-site/src/content/docs/guides/model-routing.md b/docs-site/src/content/docs/guides/model-routing.md
index 772a078eb74..ce2456eca37 100644
--- a/docs-site/src/content/docs/guides/model-routing.md
+++ b/docs-site/src/content/docs/guides/model-routing.md
@@ -67,6 +67,12 @@ through to one another.
 8. **Default provider** — if nothing matched, the id is sent to `config.defaultProvider` unchanged.
    (If no default provider is configured, or it is disabled, routing throws.)
 
+## Model alias templates
+
+`aliasTemplate` (opt-in, per provider) names every model of that provider that has no manual or built-in alias, for example `"aliasTemplate": "{providerAlias}-{modelBasename}"` on a provider whose alias is `CC` turns `reflection/beam:free` into `CC-beam-free`. Only two literal placeholders exist: `{providerAlias}` (the provider's alias; a template that uses it does nothing for a provider without one) and `{modelBasename}` (the last `/` segment of the model id with `:` written as `-`), and `{modelBasename}` is required. The aliases are derived whenever models are resolved and are never written to the config, so a new model gets its alias as soon as it is discovered and removing the template removes them at once.
+
+Manual aliases win, then built-in ones, then the template. A generated name is skipped, never renamed, when it is not a valid alias, starts with a reserved prefix (`gpt-`, `o1-`, `o3-`, `o4-`, `codex-`), or matches anything already claimed: a native model id or alias of the provider, a built-in alias name, a provider name or alias, another provider's manual alias, or a combo id or alias. When two models produce the same name, both are skipped, so the result does not depend on the order models are listed. A bare template alias that another provider's template also produced is ambiguous like any other alias; the `<provider-alias>/<alias>` form still works. Set it with `ocx alias template set <provider> <template>` (or `PUT /api/providers/<name>/alias-template` with `{ "template": … }`, `null` to remove), which reports how many aliases it generates and lists skipped ones with their reason; `ocx alias list` shows generated rows with source `template`. An invalid template in a hand-edited `config.json` is ignored with a warning.
+
 ## API keys and environment variables
 
 Whatever route is chosen, the provider's `apiKey` is resolved through `resolveEnvValue()`: a value of
diff --git a/docs-site/src/content/docs/reference/cli.md b/docs-site/src/content/docs/reference/cli.md
index ae34dcac19d..77647449c48 100644
--- a/docs-site/src/content/docs/reference/cli.md
+++ b/docs-site/src/content/docs/reference/cli.md
@@ -100,7 +100,7 @@ to standard error, leaves standard output empty, and exits 1.
 
 ### `ocx alias`
 
-`ocx alias list [--json]` shows effective user and built-in aliases. Use `ocx alias set <provider>[/<native-model-id>] <alias>` and `ocx alias rm <provider>[/<native-model-id>]` to edit them. Native model ids may contain additional slashes because the selector splits only at the first slash. Enable shipped defaults with `ocx alias defaults on|off [--provider <name>]`.
+`ocx alias list [--json]` shows effective user and built-in aliases. Use `ocx alias set <provider>[/<native-model-id>] <alias>` and `ocx alias rm <provider>[/<native-model-id>]` to edit them. Native model ids may contain additional slashes because the selector splits only at the first slash. Enable shipped defaults with `ocx alias defaults on|off [--provider <name>]`. `ocx alias template set <provider> <template>`, `ocx alias template rm <provider>` and `ocx alias template show [<provider>]` manage a provider's opt-in alias template; see [Model alias templates](/guides/model-routing/#model-alias-templates).
 
 ### `ocx remote-workspace`
 
diff --git a/docs-site/src/content/docs/reference/configuration/providers.md b/docs-site/src/content/docs/reference/configuration/providers.md
index 1fbccbfcec6..101c53f8634 100644
--- a/docs-site/src/content/docs/reference/configuration/providers.md
+++ b/docs-site/src/content/docs/reference/configuration/providers.md
@@ -320,7 +320,7 @@ predictions. Explicit provider/model price overrides still take precedence.
 
 ## Provider namespace aliases
 
-Providers can expose a built-in shorthand, such as `agy` for `google-antigravity`. A configured provider name or explicit alias claims that shorthand case-insensitively; a different provider's built-in shorthand is then suppressed in both catalog names and alias routing. For example, configuring a provider named `agy` keeps Google's models under `google-antigravity/<model>`, while `agy/<model>` selects the configured provider. Canonical provider names still require an exact case match, and unrecognized prefixes retain the existing model-routing fallback.
+Providers can expose a built-in shorthand, such as `agy` for `google-antigravity`. A configured provider name or explicit alias claims that shorthand case-insensitively; a different provider's built-in shorthand is then suppressed in both catalog names and alias routing. For example, configuring a provider named `agy` keeps Google's models under `google-antigravity/<model>`, while `agy/<model>` selects the configured provider. Canonical provider names still require an exact case match, and unrecognized prefixes retain the existing model-routing fallback. An opt-in per-provider `aliasTemplate` can name models that have no alias; see [Model alias templates](/guides/model-routing/#model-alias-templates).
 
 ## Provider entries (`OcxProviderConfig`)
 
diff --git a/scripts/test-layout/layout-providers.json b/scripts/test-layout/layout-providers.json
index 430956acc9d..a9639640055 100644
--- a/scripts/test-layout/layout-providers.json
+++ b/scripts/test-layout/layout-providers.json
@@ -1,4 +1,5 @@
 {
+  "provider-alias-template.test.ts": "providers",
   "claude-chat-gateway-tool-schema.test.ts": "providers",
   "provider-anthropic-usage-windows.test.ts": "providers",
   "provider-anthropic-pool-capacity.test.ts": "providers",
diff --git a/skills/ocx/references/01_management_surface.md b/skills/ocx/references/01_management_surface.md
index f0613d23df0..efa51144bfc 100644
--- a/skills/ocx/references/01_management_surface.md
+++ b/skills/ocx/references/01_management_surface.md
@@ -26,7 +26,7 @@ These answer in the CLI head and never reach the proxy, so they work with nothin
 | Chapter | Declared capabilities |
 |---|---|
 | [lifecycle](01_surface_lifecycle.md) | 14 |
-| [providers-models](01_surface_providers-models.md) | 50 |
+| [providers-models](01_surface_providers-models.md) | 53 |
 | [accounts](01_surface_accounts.md) | 43 |
 | [agents-routing](01_surface_agents-routing.md) | 68 |
 | [integrations](01_surface_integrations.md) | 41 |
@@ -527,6 +527,18 @@ Original invocation order. These headings preserve links to the previous single-
 
 [State-changing task](01_surface_providers-models.md#ocx-alias-defaults)
 
+### `ocx alias template set`
+
+[State-changing task](01_surface_providers-models.md#ocx-alias-template-set)
+
+### `ocx alias template rm`
+
+[State-changing task](01_surface_providers-models.md#ocx-alias-template-rm)
+
+### `ocx alias template show`
+
+[Read-oriented task](01_surface_providers-models.md#ocx-alias-template-show)
+
 ### `ocx provider pacing`
 
 [State-changing task](01_surface_providers-models.md#ocx-provider-pacing)
@@ -1553,6 +1565,6 @@ Original invocation order. These headings preserve links to the previous single-
 
 ## Counts
 
-- declared capabilities: 376
-- of those, state-changing: 232
+- declared capabilities: 379
+- of those, state-changing: 234
 - head-resolved invocations: 2
diff --git a/skills/ocx/references/01_surface_providers-models.md b/skills/ocx/references/01_surface_providers-models.md
index 75571fe5f74..4ff5a6e31fa 100644
--- a/skills/ocx/references/01_surface_providers-models.md
+++ b/skills/ocx/references/01_surface_providers-models.md
@@ -8,7 +8,7 @@
 Use these declarations to choose a task, then check its flags and authority before execution.
 Non-mutating probes may still contact providers, consume quota or refresh caches.
 
-Declared capabilities: 50.
+Declared capabilities: 53.
 
 ### `ocx models price`
 
@@ -861,6 +861,56 @@ State-changing: yes. JSON mode: `payload`.
 | `--provider` | string | Limit the toggle to one provider. |
 | `--json` | boolean | Emit the alias settings receipt. |
 
+### `ocx alias template set`
+
+Usage: `ocx alias template set <provider> <template> [--json]`
+
+Set a provider's opt-in alias template for models without an alias.
+
+State-changing: yes. JSON mode: `payload`.
+
+| Method | Route |
+|---|---|
+| PUT | `/api/providers/{provider}/alias-template` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the receipt with the generated and skipped preview. |
+
+- Only the literal {providerAlias} and {modelBasename} placeholders are allowed, and {modelBasename} is required. Aliases are derived when models resolve and never written to config. Manual and built-in aliases win; a generated name that collides with anything already claimed is skipped, never renamed.
+
+### `ocx alias template rm`
+
+Usage: `ocx alias template rm <provider> [--json]`
+
+Remove a provider's alias template; its generated aliases disappear at once.
+
+State-changing: yes. JSON mode: `payload`.
+
+| Method | Route |
+|---|---|
+| PUT | `/api/providers/{provider}/alias-template` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the receipt. |
+
+### `ocx alias template show`
+
+Usage: `ocx alias template show [<provider>] [--json]`
+
+Read configured alias templates.
+
+State-changing: no. JSON mode: `payload`.
+
+| Method | Route |
+|---|---|
+| GET | `/api/aliases` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the template map, or one provider's template. |
+
 ### `ocx provider pacing`
 
 Usage: `ocx provider pacing <name> [--json]; ocx provider pacing <name> [--enabled <on|off>] [--rpm <number>] [--min-interval-ms <integer>] [--max-concurrent <integer>] [--json]; ocx provider pacing <name> --file <FILE|-> [--json]`
diff --git a/src/cli/alias.ts b/src/cli/alias.ts
index 6eedd6f1506..be1974e3393 100644
--- a/src/cli/alias.ts
+++ b/src/cli/alias.ts
@@ -5,7 +5,10 @@ const USAGE = `Usage:
   ocx alias set <provider> <alias>
   ocx alias set <provider>/<native-model-id> <alias>
   ocx alias rm <provider>[/<native-model-id>]
-  ocx alias defaults <on|off> [--provider <name>]`;
+  ocx alias defaults <on|off> [--provider <name>]
+  ocx alias template set <provider> <template>
+  ocx alias template rm <provider>
+  ocx alias template show [<provider>]`;
 
 function selector(value: string): { provider: string; model?: string } {
   const slash = value.indexOf("/");
@@ -32,6 +35,7 @@ async function runAliasAction(argv: string[], deps: RuntimeApiDeps): Promise<num
     printData(result, wantsJson, lines.length ? lines : ["No aliases configured."]);
     return 0;
   }
+  if (action === "template") return runTemplateAction(args, wantsJson, deps);
   if (action === "defaults") {
     const state = args.shift()?.toLowerCase();
     const provider = takeOption(args, "--provider");
@@ -70,3 +74,36 @@ async function runAliasAction(argv: string[], deps: RuntimeApiDeps): Promise<num
   }
   return 0;
 }
+
+/**
+ * #7705: opt-in per-provider alias templates. The template is stored as text and the aliases are
+ * derived when models resolve; `set` prints how many aliases it produces and how many it skipped.
+ */
+async function runTemplateAction(args: string[], wantsJson: boolean, deps: RuntimeApiDeps): Promise<number> {
+  const sub = args.shift()?.toLowerCase();
+  if (sub === "show") {
+    const provider = args.shift()?.trim();
+    rejectArgs(args, USAGE);
+    const result = await runtimeRequest<{ templates?: Record<string, string> }>("/api/aliases", {}, deps);
+    const templates = Object.entries(result.templates ?? {}).filter(([name]) => !provider || name === provider);
+    printData(provider ? { provider, template: Object.fromEntries(templates)[provider] ?? null } : (result.templates ?? {}), wantsJson,
+      templates.length ? templates.map(([name, template]) => `${name}: ${template}`) : ["No alias templates configured."]);
+    return 0;
+  }
+  if (sub !== "set" && sub !== "rm") throw new CliUsageError("alias template requires set, rm or show", USAGE);
+  const provider = args.shift()?.trim();
+  if (!provider) throw new CliUsageError("alias template requires a provider", USAGE);
+  const template = sub === "set" ? args.shift() : null;
+  if (sub === "set" && !template?.trim()) throw new CliUsageError("alias template set requires a template", USAGE);
+  rejectArgs(args, USAGE);
+  const result = await runtimeRequest<{ preview?: { generated: number; skippedTotal?: number; skipped?: unknown[] } }>(
+    `/api/providers/${encodeURIComponent(provider)}/alias-template`,
+    { method: "PUT", body: JSON.stringify({ template }) },
+    deps,
+  );
+  const skipped = result.preview?.skippedTotal ?? result.preview?.skipped?.length ?? 0;
+  printData(result, wantsJson, sub === "set"
+    ? [`${provider}: ${template} (${result.preview?.generated ?? 0} aliases, ${skipped} skipped)`]
+    : [`Removed the alias template for ${provider}.`]);
+  return 0;
+}
diff --git a/src/cli/capabilities-provider-models.ts b/src/cli/capabilities-provider-models.ts
index 56bd2fb2bd3..265028f0cd6 100644
--- a/src/cli/capabilities-provider-models.ts
+++ b/src/cli/capabilities-provider-models.ts
@@ -248,6 +248,22 @@ export const PROVIDER_MODEL_CAPABILITIES: readonly Capability[] = [
     usage: "ocx alias defaults <on|off> [--provider <name>] [--json]", routes: [{ method: "PUT", path: "/api/default-aliases" }], mutates: true, json: "payload",
     flags: [{ name: "--provider", value: "string", summary: "Limit the toggle to one provider." }, { name: "--json", value: "boolean", summary: "Emit the alias settings receipt." }],
   },
+  {
+    command: ["alias", "template", "set"], summary: "Set a provider's opt-in alias template for models without an alias.",
+    usage: "ocx alias template set <provider> <template> [--json]", routes: [{ method: "PUT", path: "/api/providers/{provider}/alias-template" }], mutates: true, json: "payload",
+    flags: [{ name: "--json", value: "boolean", summary: "Emit the receipt with the generated and skipped preview." }],
+    details: ["Only the literal {providerAlias} and {modelBasename} placeholders are allowed, and {modelBasename} is required. Aliases are derived when models resolve and never written to config. Manual and built-in aliases win; a generated name that collides with anything already claimed is skipped, never renamed."],
+  },
+  {
+    command: ["alias", "template", "rm"], summary: "Remove a provider's alias template; its generated aliases disappear at once.",
+    usage: "ocx alias template rm <provider> [--json]", routes: [{ method: "PUT", path: "/api/providers/{provider}/alias-template" }], mutates: true, json: "payload",
+    flags: [{ name: "--json", value: "boolean", summary: "Emit the receipt." }],
+  },
+  {
+    command: ["alias", "template", "show"], summary: "Read configured alias templates.",
+    usage: "ocx alias template show [<provider>] [--json]", routes: [{ method: "GET", path: "/api/aliases" }], mutates: false, json: "payload",
+    flags: [{ name: "--json", value: "boolean", summary: "Emit the template map, or one provider's template." }],
+  },
   {
     command: ["provider","pacing"],
     usage: "ocx provider pacing <name> [--json]; ocx provider pacing <name> [--enabled <on|off>] [--rpm <number>] [--min-interval-ms <integer>] [--max-concurrent <integer>] [--json]; ocx provider pacing <name> --file <FILE|-> [--json]",
diff --git a/src/clients/config-export/alias-selectors.ts b/src/clients/config-export/alias-selectors.ts
index 8b2e2ba2993..9d72f3a8060 100644
--- a/src/clients/config-export/alias-selectors.ts
+++ b/src/clients/config-export/alias-selectors.ts
@@ -22,7 +22,7 @@ export function attachExportAliasSelectors(config: OcxConfig, input: readonly Ex
   // A minimal or partially repaired config can omit providers; it then has no aliases.
   const aliases = new Map(Object.entries(config.providers ?? {}).map(([name, provider]) => [name, {
     namespace: effectiveProviderAlias(name, provider, config) ?? name,
-    models: effectiveModelAliases(config, provider, knownModelIdsForProvider(name, provider, config)),
+    models: effectiveModelAliases(config, provider, knownModelIdsForProvider(name, provider, config), name),
   }]));
   const candidates = models.map(model => {
     if (model.native || model.provider === "combo") return undefined;
diff --git a/src/codex/catalog/routed-gather.ts b/src/codex/catalog/routed-gather.ts
index 76e7fe75f75..9db8ddd8fe9 100644
--- a/src/codex/catalog/routed-gather.ts
+++ b/src/codex/catalog/routed-gather.ts
@@ -791,7 +791,7 @@ async function gatherRoutedModelsUncached(
   // ponytail: catalog-scale scan; index ids by provider if catalog growth makes this measurable.
   const aliasDisplayNames = new Map(activeProviders.flatMap(({ name, provider }) => {
     const providerModels = models.filter(model => model.provider === name);
-    const aliases = [...effectiveModelAliases(config, provider, providerModels.map(model => model.id))];
+    const aliases = [...effectiveModelAliases(config, provider, providerModels.map(model => model.id), name)];
     return aliases.flatMap(([id, { alias }]) => {
       const exact = providerModels.filter(model => model.id === id);
       const matches = exact.length > 0
diff --git a/src/config/load-degrade.ts b/src/config/load-degrade.ts
index ce3bae9c269..4a2296b66aa 100644
--- a/src/config/load-degrade.ts
+++ b/src/config/load-degrade.ts
@@ -27,6 +27,7 @@ import { isPassiveRead } from "../lib/passive-read";
 import { redactSecretString } from "../lib/redact";
 import { isValidProviderName } from "./provider-name";
 import { MODEL_ALIAS_PATTERN } from "../providers/default-aliases";
+import { aliasTemplateError } from "../providers/alias-template";
 import { MODEL_DISCOVERY_MAX_MODELS } from "../providers/model-discovery-limits";
 import { getProviderRegistryEntry, providerMatchesRegistryTransport, registryModelServiceTierCapabilityApplies } from "../providers/registry";
 import { providerFastSwitchOff } from "../providers/fast-opt-in";
@@ -1032,7 +1033,13 @@ export function sanitizeAliasesForLoad(raw: unknown, warn: (message: string) =>
   const comboAliases = new Set(Object.values((root.combos as Record<string, { alias?: unknown }> | undefined) ?? {})
     .map(combo => typeof combo?.alias === "string" ? combo.alias.toLowerCase() : "").filter(Boolean));
   const accountNamespaces = new Set(Object.keys((root.codexAccountNamespaces as Record<string, unknown> | undefined) ?? {}).map(name => name.toLowerCase()));
-  for (const provider of Object.values(providers)) {
+  for (const [providerName, provider] of Object.entries(providers)) {
+    // #7705: a hand-edited template that would not validate loses only itself, not the config.
+    if (provider.aliasTemplate !== undefined
+      && (typeof provider.aliasTemplate !== "string" || aliasTemplateError(provider.aliasTemplate) !== null)) {
+      warn(`Ignoring invalid alias template for provider ${providerName} in config.json`);
+      delete provider.aliasTemplate;
+    }
     const alias = provider.alias;
     if (typeof alias !== "string" || !isValidProviderName(alias)
       || providerNames.has(alias.toLowerCase()) || claimedProviders.has(alias.toLowerCase())
diff --git a/src/config/schema/leaf-validators.ts b/src/config/schema/leaf-validators.ts
index 78be982477d..1a00e59bd0e 100644
--- a/src/config/schema/leaf-validators.ts
+++ b/src/config/schema/leaf-validators.ts
@@ -350,6 +350,8 @@ export const providerConfigSchema = z.object({
   tlsProfile: z.literal("antigravity-browser").optional(),
   alias: z.string().optional(),
   modelAliases: z.record(z.string(), z.string()).optional(),
+  // Grammar is checked by sanitizeAliasesForLoad and the alias-template route (#7705).
+  aliasTemplate: z.string().optional(),
   modelDisplayNames: modelDisplayNamesSchema.optional(),
   defaultAliases: z.boolean().optional(),
   initialModelSelection: z.object({
diff --git a/src/providers/alias-template.ts b/src/providers/alias-template.ts
new file mode 100644
index 00000000000..6290c7db9ad
--- /dev/null
+++ b/src/providers/alias-template.ts
@@ -0,0 +1,48 @@
+/**
+ * Opt-in per-provider alias templates (#7705). Pure: no config reads or writes, no expression
+ * evaluation. A template is literal text plus the two placeholders `{providerAlias}` and
+ * `{modelBasename}`; anything else in braces makes the template invalid. The basename is required,
+ * because a template without it would give every model of the provider the same name.
+ */
+/** Defined here so default-aliases can import this module without a cycle; it re-exports it. */
+export const MODEL_ALIAS_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+const PLACEHOLDER = /\{([^{}]*)\}/g;
+const KNOWN = new Set(["providerAlias", "modelBasename"]);
+/** The same reserved prefixes the config loader refuses for manual model aliases. */
+export const RESERVED_ALIAS_PREFIX = /^(?:gpt-|o1-|o3-|o4-|codex-)/i;
+export const MAX_ALIAS_TEMPLATE_LENGTH = 128;
+
+export type AliasTemplateSkip = "no_provider_alias" | "invalid_alias" | "reserved_prefix";
+
+/** Null for a usable template, otherwise a short reason fit for an API error. */
+export function aliasTemplateError(template: string): string | null {
+  if (typeof template !== "string" || !template.trim()) return "template must be a non-empty string";
+  if (template.length > MAX_ALIAS_TEMPLATE_LENGTH) return `template must be at most ${MAX_ALIAS_TEMPLATE_LENGTH} characters`;
+  const stripped = template.replace(PLACEHOLDER, "");
+  if (/[{}]/.test(stripped)) return "template has an unbalanced or nested brace";
+  for (const match of template.matchAll(PLACEHOLDER)) {
+    if (!KNOWN.has(match[1]!)) return `unknown placeholder {${match[1]}}; use {providerAlias} and {modelBasename}`;
+  }
+  if (!template.includes("{modelBasename}")) return "template must include {modelBasename}";
+  return null;
+}
+
+/** Final `/` segment of a model id, with `:` written as `-` (`a/b/beam:free` -> `beam-free`). */
+export function modelBasename(id: string): string {
+  return id.slice(id.lastIndexOf("/") + 1).replaceAll(":", "-");
+}
+
+/** One model's candidate, or why it has none. Assumes a template `aliasTemplateError` accepted. */
+export function expandAliasTemplate(
+  template: string,
+  providerAlias: string | undefined,
+  id: string,
+): { alias: string } | { skip: AliasTemplateSkip } {
+  if (template.includes("{providerAlias}") && !providerAlias) return { skip: "no_provider_alias" };
+  const alias = template.replace(PLACEHOLDER, (_whole, name: string) =>
+    name === "providerAlias" ? providerAlias ?? "" : modelBasename(id));
+  if (!MODEL_ALIAS_PATTERN.test(alias)) return { skip: "invalid_alias" };
+  if (RESERVED_ALIAS_PREFIX.test(alias)) return { skip: "reserved_prefix" };
+  return { alias };
+}
diff --git a/src/providers/default-aliases.ts b/src/providers/default-aliases.ts
index 30128db749d..e014c1a29c2 100644
--- a/src/providers/default-aliases.ts
+++ b/src/providers/default-aliases.ts
@@ -42,7 +42,9 @@ export function effectiveProviderAliasDecision(
 
 import type { OcxConfig, OcxProviderConfig } from "../types";
 
-export const MODEL_ALIAS_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+import { expandAliasTemplate, MODEL_ALIAS_PATTERN, type AliasTemplateSkip } from "./alias-template";
+
+export { MODEL_ALIAS_PATTERN };
 
 /** Ordered, most-specific-first built-in aliases. Updated with the provider registry. */
 export const DEFAULT_MODEL_ALIASES: ReadonlyArray<{ match: RegExp; alias: string }> = [
@@ -59,7 +61,7 @@ export const DEFAULT_MODEL_ALIASES: ReadonlyArray<{ match: RegExp; alias: string
   { match: /^grok-4/, alias: "grok" },
 ];
 
-export interface EffectiveModelAlias { alias: string; source: "user" | "builtin" }
+export interface EffectiveModelAlias { alias: string; source: "user" | "builtin" | "template" }
 
 function builtinRule(id: string): { match: RegExp; alias: string } | undefined {
   const tail = id.slice(id.lastIndexOf("/") + 1);
@@ -70,42 +72,116 @@ export function defaultAliasesEnabled(config: Pick<OcxConfig, "defaultModelAlias
   return provider.defaultAliases ?? config.defaultModelAliases ?? false;
 }
 
+/** The parts of the config an alias view reads; `providers` and `combos` only matter to templates. */
+export type AliasViewConfig = Pick<OcxConfig, "defaultModelAliases"> & Partial<Pick<OcxConfig, "providers" | "combos">>;
+
+/**
+ * Manual aliases, then built-in ones (when enabled), then the provider's opt-in template (#7705).
+ * The template applies only when `providerName` is given, so a caller that does not pass it sees
+ * exactly the view it always did.
+ */
 export function effectiveModelAliases(
-  config: Pick<OcxConfig, "defaultModelAliases">,
+  config: AliasViewConfig,
   provider: OcxProviderConfig,
   knownIds: Iterable<string>,
+  providerName?: string,
 ): Map<string, EffectiveModelAlias> {
+  const known = [...knownIds];
   const result = new Map<string, EffectiveModelAlias>();
   for (const [id, alias] of Object.entries(provider.modelAliases ?? {})) {
     if (typeof alias === "string" && MODEL_ALIAS_PATTERN.test(alias)) result.set(id, { alias, source: "user" });
   }
-  if (!defaultAliasesEnabled(config, provider)) return result;
-  const claims = new Map<string, string[]>();
-  for (const id of knownIds) {
-    if (result.has(id)) continue;
-    const rule = builtinRule(id);
-    if (!rule) continue;
-    const key = rule.alias.toLowerCase();
-    claims.set(key, [...(claims.get(key) ?? []), id]);
+  if (defaultAliasesEnabled(config, provider)) {
+    const claims = new Map<string, string[]>();
+    for (const id of known) {
+      if (result.has(id)) continue;
+      const rule = builtinRule(id);
+      if (!rule) continue;
+      const key = rule.alias.toLowerCase();
+      claims.set(key, [...(claims.get(key) ?? []), id]);
+    }
+    for (const [alias, ids] of claims) {
+      if (ids.length !== 1) continue;
+      const id = ids[0]!;
+      // Catalog drift must skip, never shadow, a native id or explicit user alias.
+      if (known.some(candidate => candidate.toLowerCase() === alias)) continue;
+      if ([...result.values()].some(value => value.alias.toLowerCase() === alias)) continue;
+      result.set(id, { alias: builtinRule(id)!.alias, source: "builtin" });
+    }
   }
-  for (const [alias, ids] of claims) {
-    if (ids.length !== 1) continue;
-    const id = ids[0]!;
-    // Catalog drift must skip, never shadow, a native id or explicit user alias.
-    if ([...knownIds].some(candidate => candidate.toLowerCase() === alias)) continue;
-    if ([...result.values()].some(value => value.alias.toLowerCase() === alias)) continue;
-    result.set(id, { alias: builtinRule(id)!.alias, source: "builtin" });
+  if (providerName !== undefined && provider.aliasTemplate) {
+    for (const [id, alias] of templateAliasPlan(config, provider, providerName, known, result).accepted) {
+      result.set(id, { alias, source: "template" });
+    }
   }
   return result;
 }
 
+export interface TemplateAliasPlan {
+  accepted: Map<string, string>;
+  skipped: Array<{ id: string; candidate?: string; reason: AliasTemplateSkip | "collision" | "reserved" }>;
+}
+
+/**
+ * Template candidates for ids that have no manual or built-in alias. Every name already claimed is
+ * reserved first: this provider's native ids and aliases, every built-in alias name, every
+ * provider name and provider alias, other providers' manual aliases, and combo ids and aliases.
+ * Two candidates that collide are both skipped, so the result does not depend on roster order;
+ * nothing is ever renamed to make it fit.
+ */
+export function templateAliasPlan(
+  config: AliasViewConfig,
+  provider: OcxProviderConfig,
+  providerName: string,
+  knownIds: readonly string[],
+  existing: ReadonlyMap<string, EffectiveModelAlias>,
+): TemplateAliasPlan {
+  const plan: TemplateAliasPlan = { accepted: new Map(), skipped: [] };
+  const template = provider.aliasTemplate;
+  if (!template) return plan;
+  const providerAlias = config.providers
+    ? effectiveProviderAlias(providerName, provider, config as Pick<OcxConfig, "providers">)
+    : (provider.alias?.trim() || undefined);
+  const reserved = new Set<string>();
+  const reserve = (value: unknown) => { if (typeof value === "string" && value.trim()) reserved.add(value.trim().toLowerCase()); };
+  for (const id of knownIds) reserve(id);
+  for (const value of existing.values()) reserve(value.alias);
+  for (const rule of DEFAULT_MODEL_ALIASES) reserve(rule.alias);
+  for (const [name, other] of Object.entries(config.providers ?? {})) {
+    reserve(name);
+    reserve(other.alias);
+    if (name !== providerName) for (const alias of Object.values(other.modelAliases ?? {})) reserve(alias);
+  }
+  for (const [id, combo] of Object.entries(config.combos ?? {})) { reserve(id); reserve((combo as { alias?: unknown }).alias); }
+  const candidates = new Map<string, Array<{ id: string; alias: string }>>();
+  for (const id of [...new Set(knownIds)].sort()) {
+    if (existing.has(id)) continue;
+    const expanded = expandAliasTemplate(template, providerAlias, id);
+    if ("skip" in expanded) { plan.skipped.push({ id, reason: expanded.skip }); continue; }
+    const key = expanded.alias.toLowerCase();
+    candidates.set(key, [...(candidates.get(key) ?? []), { id, alias: expanded.alias }]);
+  }
+  for (const [key, rows] of candidates) {
+    if (rows.length > 1) {
+      for (const row of rows) plan.skipped.push({ id: row.id, candidate: row.alias, reason: "collision" });
+    } else if (reserved.has(key)) {
+      plan.skipped.push({ id: rows[0]!.id, candidate: rows[0]!.alias, reason: "reserved" });
+    } else {
+      plan.accepted.set(rows[0]!.id, rows[0]!.alias);
+    }
+  }
+  plan.skipped.sort((a, b) => a.id.localeCompare(b.id));
+  return plan;
+}
+
 export function resolveModelAlias(
-  config: Pick<OcxConfig, "defaultModelAliases">,
+  config: AliasViewConfig,
   provider: OcxProviderConfig,
   knownIds: Iterable<string>,
   requested: string,
+  providerName?: string,
 ): string | undefined {
   const needle = requested.toLowerCase();
-  return [...effectiveModelAliases(config, provider, knownIds)]
+  return [...effectiveModelAliases(config, provider, knownIds, providerName)]
     .find(([, value]) => value.alias.toLowerCase() === needle)?.[0];
 }
diff --git a/src/providers/model-rename-fields.ts b/src/providers/model-rename-fields.ts
index 07543600058..3e8d130fab5 100644
--- a/src/providers/model-rename-fields.ts
+++ b/src/providers/model-rename-fields.ts
@@ -6,6 +6,7 @@ type ModelRenameRole = "none" | "record" | "list" | "scalar" | "nested-models";
 export const PROVIDER_MODEL_RENAME_ROLES = {
   alias: "none",
   modelAliases: "record",
+  aliasTemplate: "none",
   modelDisplayNames: "record",
   defaultAliases: "none",
   adapter: "none",
diff --git a/src/router.ts b/src/router.ts
index 1d517d7ad51..b0282e3e337 100644
--- a/src/router.ts
+++ b/src/router.ts
@@ -600,7 +600,7 @@ function routeModelInternal(
       const decoded = decodeRoutedModelIdOrThrow(requestedModel, known);
       const nativeModel = known.includes(decoded)
         ? decoded
-        : resolveModelAlias(config, prov, known, requestedModel)
+        : resolveModelAlias(config, prov, known, requestedModel, provName)
           // Last resort for direct requests while the live roster is cold: display-name keys are
           // operator-declared native ids, consulted only here so they never claim aliases or shadow
           // known or retained ids. Concrete policy/combo/redirect targets (bypassCombos) keep the
@@ -672,7 +672,7 @@ function routeModelInternal(
   const aliasMatches: Array<{ provider: string; model: string; qualified: string }> = [];
   for (const [provName, prov] of activeProviderEntries(config)) {
     const known = knownModelIdsForProvider(provName, prov, config);
-    const native = resolveModelAlias(config, prov, known, modelId);
+    const native = resolveModelAlias(config, prov, known, modelId, provName);
     if (native) aliasMatches.push({
       provider: provName,
       model: native,
diff --git a/src/server/auth-cors.ts b/src/server/auth-cors.ts
index c9056aec260..6fe47ac80bb 100644
--- a/src/server/auth-cors.ts
+++ b/src/server/auth-cors.ts
@@ -1078,6 +1078,7 @@ type ProviderConfigFieldPolicy = "editor" | "redacted" | "runtime";
 const PROVIDER_CONFIG_FIELD_POLICY = {
   alias: "editor",
   modelAliases: "editor",
+  aliasTemplate: "editor",
   modelDisplayNames: "editor",
   defaultAliases: "editor",
   adapter: "editor",
diff --git a/src/server/index/serve-options.ts b/src/server/index/serve-options.ts
index 8174de67ba5..6a153ca608b 100644
--- a/src/server/index/serve-options.ts
+++ b/src/server/index/serve-options.ts
@@ -1270,6 +1270,7 @@ export function createServeOptions(ctx: ServeOptionsContext) {
                 config,
                 provider,
                 knownModelIdsForProvider(m.provider, provider, config),
+                m.provider,
               ).get(m.id)
             : undefined;
           const effectiveId = !isCombo && !fastModelId && effective
diff --git a/src/server/management/model-routes.ts b/src/server/management/model-routes.ts
index 07b7da80b6e..f1248a05134 100644
--- a/src/server/management/model-routes.ts
+++ b/src/server/management/model-routes.ts
@@ -116,7 +116,8 @@ import { deriveProviderPresets } from "../../providers/derive";
 import { providerCodexAccountMode } from "../../providers/registry";
 import { encodedModelIdCollides, routedSlug, slugEquals } from "../../providers/slug-codec";
 import { knownModelIdsForProvider } from "../../router";
-import { effectiveModelAliases, MODEL_ALIAS_PATTERN } from "../../providers/default-aliases";
+import { effectiveModelAliases, MODEL_ALIAS_PATTERN, templateAliasPlan } from "../../providers/default-aliases";
+import { aliasTemplateError } from "../../providers/alias-template";
 import { isValidModelDiscoveryModelId } from "../../providers/model-discovery-limits";
 import { commitProviderPatch } from "./provider-patch-transaction";
 import { ConfigWritePublishedError } from "../../config/persist-unlocked";
@@ -277,18 +278,20 @@ export async function handleModelRoutes(ctx: ManagementContext): Promise<Respons
 
   if (url.pathname === "/api/aliases" && req.method === "GET") {
     const providers: Record<string, string> = {};
-    const models: Record<string, Record<string, { alias: string; source: "user" | "builtin"; stale?: boolean }>> = {};
+    const models: Record<string, Record<string, { alias: string; source: "user" | "builtin" | "template"; stale?: boolean }>> = {};
     for (const [name, provider] of Object.entries(config.providers)) {
       if (provider.alias) providers[name] = provider.alias;
       const known = knownModelIdsForProvider(name, provider, config);
       const knownSet = new Set(known);
-      const rows: Record<string, { alias: string; source: "user" | "builtin"; stale?: boolean }> = {};
-      for (const [id, value] of effectiveModelAliases(config, provider, new Set([...known, ...Object.keys(provider.modelAliases ?? {})]))) {
+      const rows: Record<string, { alias: string; source: "user" | "builtin" | "template"; stale?: boolean }> = {};
+      for (const [id, value] of effectiveModelAliases(config, provider, new Set([...known, ...Object.keys(provider.modelAliases ?? {})]), name)) {
         rows[id] = { ...value, ...(!knownSet.has(id) ? { stale: true } : {}) };
       }
       if (Object.keys(rows).length) models[name] = rows;
     }
-    return jsonResponse({ providers, models, defaults: {
+    const templates = Object.fromEntries(Object.entries(config.providers)
+      .filter(([, provider]) => typeof provider.aliasTemplate === "string").map(([name, provider]) => [name, provider.aliasTemplate]));
+    return jsonResponse({ providers, models, templates, defaults: {
       global: config.defaultModelAliases ?? false,
       providers: Object.fromEntries(Object.entries(config.providers).filter(([, p]) => p.defaultAliases !== undefined).map(([n, p]) => [n, p.defaultAliases])),
     } });
@@ -321,6 +324,36 @@ export async function handleModelRoutes(ctx: ManagementContext): Promise<Respons
     return jsonResponse({ ok: true, provider: name, alias, catalogRefresh });
   }
 
+  // #7705: the opt-in template is stored as text and derived at resolution time; this route only
+  // validates, saves and previews it. The preview is the same plan routing uses, bounded.
+  const aliasTemplateMatch = url.pathname.match(/^\/api\/providers\/([^/]+)\/alias-template$/);
+  if (aliasTemplateMatch && req.method === "PUT") {
+    const name = decodeURIComponent(aliasTemplateMatch[1]!);
+    if (name === "keys") return null;
+    const provider = config.providers[name];
+    if (!provider) return jsonResponse({ error: `provider '${name}' not found` }, 404, req, config);
+    let raw: unknown;
+    try { raw = await readManagementJsonBody(req); } catch (error) { rethrowManagementBodyTooLarge(error); return jsonResponse({ error: "invalid JSON body" }, 400); }
+    if (!isPlainRecord(raw) || (raw.template !== null && typeof raw.template !== "string")) {
+      return jsonResponse({ error: "template must be a string or null" }, 400, req, config);
+    }
+    const template = typeof raw.template === "string" ? raw.template.trim() : null;
+    const problem = template === null ? null : aliasTemplateError(template);
+    if (problem) return jsonResponse({ error: problem }, 400, req, config);
+    if (template) provider.aliasTemplate = template; else delete provider.aliasTemplate;
+    persistConfig(config);
+    const catalogRefresh = await convergeCodexCatalog();
+    if (!template) return jsonResponse({ ok: true, provider: name, template: null, catalogRefresh });
+    const known = knownModelIdsForProvider(name, provider, config);
+    const existing = effectiveModelAliases(config, { ...provider, aliasTemplate: undefined }, known, name);
+    const plan = templateAliasPlan(config, provider, name, known, existing);
+    return jsonResponse({
+      ok: true, provider: name, template,
+      preview: { generated: plan.accepted.size, skipped: plan.skipped.slice(0, 50), skippedTotal: plan.skipped.length },
+      catalogRefresh,
+    });
+  }
+
   const modelAliasMatch = url.pathname.match(/^\/api\/providers\/([^/]+)\/model-aliases$/);
   if (modelAliasMatch && req.method === "PUT") {
     const name = decodeURIComponent(modelAliasMatch[1]!);
diff --git a/src/server/management/provider-completion-test.ts b/src/server/management/provider-completion-test.ts
index c2fd14fef94..fbb559e08c0 100644
--- a/src/server/management/provider-completion-test.ts
+++ b/src/server/management/provider-completion-test.ts
@@ -72,13 +72,13 @@ function transportExclusion(row: OcxProviderConfig): Extract<ProviderCompletionT
   if (typeof (row as { fetch?: unknown }).fetch === "function" && "proxy" in row) return "custom_executor_egress";
   return undefined;
 }
-function nativeModel(config: OcxConfig, row: OcxProviderConfig, model: string): string {
+function nativeModel(config: OcxConfig, name: string, row: OcxProviderConfig, model: string): string {
   const known = new Set([...(row.models ?? []), ...Object.keys(row.modelAliases ?? {})]);
-  return known.has(model) ? model : resolveModelAlias(config, row, known, model) ?? model;
+  return known.has(model) ? model : resolveModelAlias(config, row, known, model, name) ?? model;
 }
 function derive(config: OcxConfig, name: string, row: OcxProviderConfig, model: string) {
   const resolved = routedProviderConfig(name, row);
-  const native = nativeModel(config, resolved, model);
+  const native = nativeModel(config, name, resolved, model);
   const routed = resolveWireProtocolOverride(name, native, resolved);
   const wire = routed.adapter;
   if (wire !== "openai-chat" && wire !== "openai-responses") throw new Error("unsupported adapter");
@@ -134,7 +134,7 @@ export async function runProviderCompletionTest(
   let snapshot: OcxProviderConfig = metadata;
   let destinationRefused = false;
   try { snapshot = routedProviderConfig(name, metadata); } catch { destinationRefused = true; }
-  const native = nativeModel(config, snapshot, model);
+  const native = nativeModel(config, name, snapshot, model);
   const wire = resolveWireProtocolOverride(name, native, snapshot).adapter;
   if (wire !== "openai-chat" && wire !== "openai-responses") return { applicable: false, reason: "unsupported_adapter", adapter: wire };
   const now = deps.now ?? (() => performance.now());
diff --git a/src/server/management/route-registry.ts b/src/server/management/route-registry.ts
index 094ed5eb681..a1b085802d1 100644
--- a/src/server/management/route-registry.ts
+++ b/src/server/management/route-registry.ts
@@ -472,6 +472,7 @@ export const MANAGEMENT_ROUTES: readonly ManagementRoute[] = [
   { method: "GET", path: "/api/request-history/{id}/route-decision", module: "server/management/request-history-routes", mutates: false, mechanism: "ends-with" },
   { method: "PUT", path: "/api/providers/{provider}/alias", module: "server/management/model-routes", mutates: true, mechanism: "regex" },
   { method: "PUT", path: "/api/providers/{provider}/model-aliases", module: "server/management/model-routes", mutates: true, mechanism: "regex" },
+  { method: "PUT", path: "/api/providers/{provider}/alias-template", module: "server/management/model-routes", mutates: true, mechanism: "regex" },
   { method: "GET", path: "/api/providers/{provider}/model-costs", module: "server/management/model-routes", mutates: false, mechanism: "regex" },
   { method: "PUT", path: "/api/providers/{provider}/model-costs", module: "server/management/model-routes", mutates: true, mechanism: "regex" },
   { method: "PUT", path: "/api/providers/{provider}/model-display-names", module: "server/management/model-routes", mutates: true, mechanism: "regex" },
diff --git a/src/types/provider.ts b/src/types/provider.ts
index 1b22c2d2d69..c52cfd00cec 100644
--- a/src/types/provider.ts
+++ b/src/types/provider.ts
@@ -313,6 +313,12 @@ export interface OcxProviderConfig {
   alias?: string;
   /** Native model id -> short, slash-free request alias. */
   modelAliases?: Record<string, string>;
+  /**
+   * Opt-in alias template for models without a manual or built-in alias (#7705), for example
+   * `{providerAlias}-{modelBasename}`. Derived at resolution time and never written back; only the
+   * literal `{providerAlias}` and `{modelBasename}` placeholders are allowed.
+   */
+  aliasTemplate?: string;
   /** Display-only labels for exact native model ids discovered under this provider. */
   modelDisplayNames?: Record<string, string>;
   /** Override the global built-in model-alias switch for this provider. */
diff --git a/tests/cli/cli-alias-json.test.ts b/tests/cli/cli-alias-json.test.ts
index 7dca4604f2a..e64305b5096 100644
--- a/tests/cli/cli-alias-json.test.ts
+++ b/tests/cli/cli-alias-json.test.ts
@@ -56,3 +56,36 @@ describe("alias failure boundaries", () => {
     },
   );
 });
+
+describe("#7705 alias template commands", () => {
+  test("set, rm and show reach the template route and the list", async () => {
+    const out = spyOn(console, "log").mockImplementation(() => {});
+    const calls: Array<{ path: string; method: string; body: unknown }> = [];
+    const deps = { baseUrl: "http://cli.test", fetchImpl: async (input: string | URL | Request, init?: RequestInit) => {
+      calls.push({ path: String(input), method: init?.method ?? "GET", body: init?.body ? JSON.parse(String(init.body)) : null });
+      return Response.json({ ok: true, templates: { cc: "{providerAlias}-{modelBasename}" }, preview: { generated: 3, skipped: [] } });
+    } };
+    try {
+      expect(await handleAliasCommand(["template", "set", "cc", "{providerAlias}-{modelBasename}"], deps)).toBe(0);
+      expect(await handleAliasCommand(["template", "rm", "cc"], deps)).toBe(0);
+      expect(await handleAliasCommand(["template", "show", "cc"], deps)).toBe(0);
+      expect(calls).toEqual([
+        { path: "http://cli.test/api/providers/cc/alias-template", method: "PUT", body: { template: "{providerAlias}-{modelBasename}" } },
+        { path: "http://cli.test/api/providers/cc/alias-template", method: "PUT", body: { template: null } },
+        { path: "http://cli.test/api/aliases", method: "GET", body: null },
+      ]);
+      expect(out.mock.calls.map(call => call.join(" ")).join("\n")).toContain("cc: {providerAlias}-{modelBasename}");
+    } finally { out.mockRestore(); }
+  });
+
+  test("a template action without its operands is a usage error before any request", async () => {
+    const err = spyOn(console, "error").mockImplementation(() => {});
+    let requests = 0;
+    try {
+      for (const args of [["template"], ["template", "set", "cc"], ["template", "rm"], ["template", "wat", "cc"]]) {
+        expect(await handleAliasCommand(args, { baseUrl: "http://cli.test", fetchImpl: async () => { requests++; return Response.json({}); } })).toBe(2);
+      }
+      expect(requests).toBe(0);
+    } finally { err.mockRestore(); }
+  });
+});
diff --git a/tests/codex-integration/codex-convergence-contract.test.ts b/tests/codex-integration/codex-convergence-contract.test.ts
index 5d38840e690..8b8d7de1e62 100644
--- a/tests/codex-integration/codex-convergence-contract.test.ts
+++ b/tests/codex-integration/codex-convergence-contract.test.ts
@@ -581,7 +581,7 @@ test("a failure cause never carries message text, paths or identifiers (#1784)",
 test("the route inventory retains every convergence path after separating subagent routes", () => {
   const counts = Object.fromEntries([
     ["provider-routes.ts", 8],
-    ["model-routes.ts", 15],
+    ["model-routes.ts", 16],
     ["combo-routes.ts", 2],
     ["agent-settings-routes.ts", 1],
     ["subagent-model-routes.ts", 1],
@@ -601,7 +601,7 @@ test("the route inventory retains every convergence path after separating subage
   }));
   expect(counts).toEqual({
     "provider-routes.ts": 8,
-    "model-routes.ts": 15,
+    "model-routes.ts": 16,
     "combo-routes.ts": 2,
     "agent-settings-routes.ts": 1,
     "subagent-model-routes.ts": 1,
@@ -619,9 +619,10 @@ test("both model-discovery write paths converge the Codex catalog", () => {
   expect(acknowledge.match(/await convergeCodexCatalog\(\)/g)?.length).toBe(1);
 });
 
-test("all three alias write routes converge the Codex catalog", () => {
+test("all four alias write routes converge the Codex catalog", () => {
   const source = readFileSync(repoPath("src", "server", "management", "model-routes.ts"), "utf8");
-  for (const marker of ["providerAliasMatch && req.method", "modelAliasMatch && req.method", 'url.pathname === "/api/default-aliases"']) {
+  // The fourth is the #7705 alias-template route: a template changes which aliases the catalog shows.
+  for (const marker of ["providerAliasMatch && req.method", "aliasTemplateMatch && req.method", "modelAliasMatch && req.method", 'url.pathname === "/api/default-aliases"']) {
     const start = source.indexOf(marker);
     expect(start).toBeGreaterThan(-1);
     expect(source.slice(start, source.indexOf("\n  if (", start + 1))).toContain("await convergeCodexCatalog()");
diff --git a/tests/fixtures/test-layout-expected.json b/tests/fixtures/test-layout-expected.json
index 08602048200..a443cf7b7bc 100644
--- a/tests/fixtures/test-layout-expected.json
+++ b/tests/fixtures/test-layout-expected.json
@@ -1205,7 +1205,7 @@
   "provider-egress-fetch.test.ts": "responses", "provider-egress-management-validation.test.ts": "server",
   "provider-egress-outbound.test.ts": "providers", "provider-egress.test.ts": "lib",
   "provider-id-rewrite.test.ts": "providers", "provider-key-store.test.ts": "providers",
-  "provider-live-models.test.ts": "providers", "provider-model-aliases.test.ts": "providers",
+  "provider-live-models.test.ts": "providers", "provider-model-aliases.test.ts": "providers", "provider-alias-template.test.ts": "providers",
   "provider-model-discovery-contract.test.ts": "providers", "provider-outbound-private-network.test.ts": "providers",
   "provider-outbound.test.ts": "providers", "provider-runtime-fetch.test.ts": "providers",
   "provider-tls-profile.test.ts": "providers", "provider-payload.test.ts": "gui",
diff --git a/tests/providers/provider-alias-template.test.ts b/tests/providers/provider-alias-template.test.ts
new file mode 100644
index 00000000000..8a1808b56c1
--- /dev/null
+++ b/tests/providers/provider-alias-template.test.ts
@@ -0,0 +1,143 @@
+/**
+ * #7705: an opt-in, per-provider alias template derived at resolution time. Manual aliases win,
+ * then built-in ones, then the template; a generated name that would collide with anything already
+ * claimed is skipped on both sides rather than renamed, so the result does not depend on roster
+ * order. Nothing here writes configuration.
+ */
+import { describe, expect, test } from "bun:test";
+import { aliasTemplateError, expandAliasTemplate, modelBasename } from "../../src/providers/alias-template";
+import { effectiveModelAliases, templateAliasPlan } from "../../src/providers/default-aliases";
+import { routeModel } from "../../src/router";
+import { sanitizeAliasesForLoad } from "../../src/config/load-degrade";
+import type { OcxConfig, OcxProviderConfig } from "../../src/types";
+
+const TEMPLATE = "{providerAlias}-{modelBasename}";
+
+function config(models: string[], extra: Partial<OcxProviderConfig> = {}): OcxConfig {
+  return {
+    port: 10100,
+    defaultProvider: "other",
+    providers: {
+      cc: { adapter: "openai-chat", baseUrl: "https://cc.test/v1", alias: "CC", aliasTemplate: TEMPLATE, models, ...extra },
+      other: { adapter: "openai-chat", baseUrl: "https://other.test/v1", models: ["o1-mini-x"] },
+    },
+  };
+}
+
+function aliases(c: OcxConfig, ids = c.providers.cc!.models as string[]) {
+  return Object.fromEntries([...effectiveModelAliases(c, c.providers.cc!, ids, "cc")]
+    .map(([id, value]) => [id, `${value.alias}:${value.source}`]));
+}
+
+describe("alias template grammar", () => {
+  test("only the two literal placeholders are accepted, and the basename is required", () => {
+    expect(aliasTemplateError(TEMPLATE)).toBeNull();
+    expect(aliasTemplateError("{modelBasename}")).toBeNull();
+    expect(aliasTemplateError("")).not.toBeNull();
+    expect(aliasTemplateError("{providerAlias}")).not.toBeNull();
+    expect(aliasTemplateError("{vendor}-{modelBasename}")).not.toBeNull();
+    expect(aliasTemplateError("x-{modelBasename")).not.toBeNull();
+    expect(aliasTemplateError("{model${1+1}}")).not.toBeNull();
+  });
+
+  test("the basename is the last path segment with colons as hyphens", () => {
+    expect(modelBasename("command-code/reflection/beam:free")).toBe("beam-free");
+    expect(modelBasename("plain")).toBe("plain");
+    expect(expandAliasTemplate(TEMPLATE, "CC", "command-code/reflection/beam:free")).toEqual({ alias: "CC-beam-free" });
+  });
+
+  test("a missing provider alias or an output that is not a valid alias is skipped, never repaired", () => {
+    expect(expandAliasTemplate(TEMPLATE, undefined, "x/y")).toEqual({ skip: "no_provider_alias" });
+    expect(expandAliasTemplate(TEMPLATE, "CC", "vendor/has space")).toEqual({ skip: "invalid_alias" });
+    expect(expandAliasTemplate("{modelBasename}", undefined, "gpt-5.9")).toEqual({ skip: "reserved_prefix" });
+  });
+});
+
+describe("template aliases in the effective alias view", () => {
+  test("every unaliased model gets a template alias with its own source", () => {
+    expect(aliases(config(["reflection/beam:free", "reflection/ray"]))).toEqual({
+      "reflection/beam:free": "CC-beam-free:template",
+      "reflection/ray": "CC-ray:template",
+    });
+  });
+
+  test("a manual alias wins, and its name is reserved against the template", () => {
+    const c = config(["a/one", "b/two"], { modelAliases: { "a/one": "CC-two" } });
+    expect(aliases(c)).toEqual({ "a/one": "CC-two:user" });
+  });
+
+  test("a built-in alias wins over the template", () => {
+    const c = config(["anthropic/claude-opus-5-1", "x/plain"], { defaultAliases: true });
+    expect(aliases(c)).toEqual({ "anthropic/claude-opus-5-1": "opus:builtin", "x/plain": "CC-plain:template" });
+  });
+
+  test("two ids with the same candidate are both skipped, whatever the roster order", () => {
+    const ids = ["a/x:free", "b/x-free", "c/solo"];
+    const c = config(ids);
+    expect(aliases(c, ids)).toEqual({ "c/solo": "CC-solo:template" });
+    expect(aliases(c, [...ids].reverse())).toEqual({ "c/solo": "CC-solo:template" });
+  });
+
+  test("a candidate that equals a native id, a built-in alias name or another provider's alias is skipped", () => {
+    const c = config(["CC-native", "v/native", "v/opus", "v/sel"], { aliasTemplate: "{modelBasename}" });
+    c.providers.other!.modelAliases = { "o1-mini-x": "sel" };
+    // The basename template would name "CC-native" after itself (a native id), "v/opus" after a
+    // built-in alias name and "v/sel" after other's manual alias; all three are skipped.
+    expect(aliases(c)).toEqual({ "v/native": "native:template" });
+  });
+
+  test("a combo id is reserved too", () => {
+    const c = config(["v/fast"], { aliasTemplate: "{modelBasename}" });
+    c.combos = { fast: { targets: [] } } as never;
+    expect(aliases(c)).toEqual({});
+  });
+
+  test("without a provider name the view is exactly what it was before templates", () => {
+    const c = config(["x/plain"]);
+    expect([...effectiveModelAliases(c, c.providers.cc!, ["x/plain"])]).toEqual([]);
+  });
+
+  test("the plan reports why a candidate was skipped", () => {
+    const c = config(["a/x:free", "b/x-free", "bad id"]);
+    const plan = templateAliasPlan(c, c.providers.cc!, "cc", c.providers.cc!.models as string[], new Map());
+    expect(plan.accepted.size).toBe(0);
+    expect(plan.skipped).toEqual([
+      { id: "a/x:free", candidate: "CC-x-free", reason: "collision" },
+      { id: "b/x-free", candidate: "CC-x-free", reason: "collision" },
+      { id: "bad id", reason: "invalid_alias" },
+    ]);
+  });
+});
+
+describe("routing a template alias", () => {
+  test("a bare template alias routes to its native id, and so does the provider-qualified one", () => {
+    const c = config(["reflection/beam:free"]);
+    expect(routeModel(c, "CC-beam-free")).toMatchObject({ providerName: "cc", modelId: "reflection/beam:free", routeReason: "model-alias" });
+    expect(routeModel(c, "CC/CC-beam-free")).toMatchObject({ providerName: "cc", modelId: "reflection/beam:free" });
+  });
+
+  test("removing the template removes the alias at once", () => {
+    const c = config(["reflection/beam:free"]);
+    delete c.providers.cc!.aliasTemplate;
+    expect(routeModel(c, "CC-beam-free")).toMatchObject({ providerName: "other", routeReason: "default-provider" });
+  });
+});
+
+describe("loading a hand-edited alias template", () => {
+  test("an invalid template is dropped with a warning; a valid one is kept", () => {
+    const warnings: string[] = [];
+    const raw = { providers: {
+      cc: { adapter: "openai-chat", baseUrl: "https://cc.test", aliasTemplate: "{vendor}-{modelBasename}" },
+      ok: { adapter: "openai-chat", baseUrl: "https://ok.test", aliasTemplate: "{modelBasename}" },
+      odd: { adapter: "openai-chat", baseUrl: "https://odd.test", aliasTemplate: 42 },
+    } };
+    sanitizeAliasesForLoad(raw, message => warnings.push(message));
+    expect("aliasTemplate" in raw.providers.cc).toBe(false);
+    expect(raw.providers.ok.aliasTemplate).toBe("{modelBasename}");
+    expect("aliasTemplate" in raw.providers.odd).toBe(false);
+    expect(warnings).toEqual([
+      "Ignoring invalid alias template for provider cc in config.json",
+      "Ignoring invalid alias template for provider odd in config.json",
+    ]);
+  });
+});
diff --git a/tests/server/alias-management-api.test.ts b/tests/server/alias-management-api.test.ts
index 3f25e7bde6e..e07f61a1e50 100644
--- a/tests/server/alias-management-api.test.ts
+++ b/tests/server/alias-management-api.test.ts
@@ -38,3 +38,26 @@ test("alias write routes reject case-insensitive collisions", async () => {
   expect((await request(c, "/api/providers/alpha/model-aliases", { set: { m1: "same", m2: "SAME" } }))?.status).toBe(409);
   expect((await request(c, "/api/providers/alpha/model-aliases", { set: { m1: "gpt-5.6-sol" } }))?.status).toBe(409);
 });
+
+test("#7705: an alias template is set, previewed, listed with its source, and cleared", async () => {
+  const c = config();
+  c.providers.alpha!.alias = "AL";
+  const set = await request(c, "/api/providers/alpha/alias-template", { template: "{providerAlias}-{modelBasename}" });
+  expect(set?.status).toBe(200);
+  expect(await set?.json()).toMatchObject({ ok: true, provider: "alpha", template: "{providerAlias}-{modelBasename}", preview: { generated: 2, skipped: [] } });
+  expect(c.providers.alpha!.aliasTemplate).toBe("{providerAlias}-{modelBasename}");
+  const list = await (await request(c, "/api/aliases"))!.json();
+  expect(list).toMatchObject({ templates: { alpha: "{providerAlias}-{modelBasename}" }, models: { alpha: { m1: { alias: "AL-m1", source: "template" }, m2: { alias: "AL-m2", source: "template" } } } });
+  expect((await request(c, "/api/providers/alpha/alias-template", { template: null }))?.status).toBe(200);
+  expect(c.providers.alpha!.aliasTemplate).toBeUndefined();
+  expect((await (await request(c, "/api/aliases"))!.json()).models.alpha).toBeUndefined();
+});
+
+test("#7705: an invalid template or unknown provider is refused without a write", async () => {
+  const c = config();
+  for (const template of ["{vendor}-{modelBasename}", "{providerAlias}", "", 7]) {
+    expect((await request(c, "/api/providers/alpha/alias-template", { template }))?.status).toBe(400);
+  }
+  expect(c.providers.alpha!.aliasTemplate).toBeUndefined();
+  expect((await request(c, "/api/providers/nobody/alias-template", { template: "{modelBasename}" }))?.status).toBe(404);
+});

From eec8da83817c747b64eef3cb937bf6b71620aaff Mon Sep 17 00:00:00 2001
From: JUN <jun@lidgeai.com>
Date: Wed, 11 Nov 2026 09:24:38 +0900
Subject: [PATCH 2/5] test(aliases): pin cross-provider template name
 collisions as ambiguous

Two providers whose templates produce the same name leave the bare name
ambiguous and keep each provider-qualified name routable.
---
 tests/providers/provider-alias-template.test.ts | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/tests/providers/provider-alias-template.test.ts b/tests/providers/provider-alias-template.test.ts
index 8a1808b56c1..de7e194de2e 100644
--- a/tests/providers/provider-alias-template.test.ts
+++ b/tests/providers/provider-alias-template.test.ts
@@ -121,6 +121,14 @@ describe("routing a template alias", () => {
     delete c.providers.cc!.aliasTemplate;
     expect(routeModel(c, "CC-beam-free")).toMatchObject({ providerName: "other", routeReason: "default-provider" });
   });
+
+  test("two providers whose templates produce the same name: neither wins the bare name, each keeps its qualified one", () => {
+    const c = config(["reflection/beam"], { aliasTemplate: "{modelBasename}-t" });
+    c.providers.dd = { adapter: "openai-chat", baseUrl: "https://dd.test/v1", aliasTemplate: "{modelBasename}-t", models: ["vendor/beam"] };
+    expect(() => routeModel(c, "beam-t")).toThrow("model alias 'beam-t' is ambiguous: CC/beam-t, dd/beam-t");
+    expect(routeModel(c, "CC/beam-t")).toMatchObject({ providerName: "cc", modelId: "reflection/beam" });
+    expect(routeModel(c, "dd/beam-t")).toMatchObject({ providerName: "dd", modelId: "vendor/beam" });
+  });
 });
 
 describe("loading a hand-edited alias template", () => {

From f9d0c99ed9a8a52bfcb646b08930de50835aec33 Mon Sep 17 00:00:00 2001
From: JUN <jun@lidgeai.com>
Date: Wed, 11 Nov 2026 10:45:43 +0900
Subject: [PATCH 3/5] fix(aliases): look up providers by own key in the alias
 routes

PUT /api/providers/<name>/alias, /model-aliases and /alias-template read
config.providers[name], so an inherited key such as __proto__ resolved to
Object.prototype and the write landed on every object. All three now
require an own provider and answer 404 otherwise.
---
 src/server/management/model-routes.ts     | 15 +++++++++------
 tests/server/alias-management-api.test.ts | 22 ++++++++++++++++++++++
 2 files changed, 31 insertions(+), 6 deletions(-)

diff --git a/src/server/management/model-routes.ts b/src/server/management/model-routes.ts
index f1248a05134..9115f06e8c7 100644
--- a/src/server/management/model-routes.ts
+++ b/src/server/management/model-routes.ts
@@ -305,8 +305,9 @@ export async function handleModelRoutes(ctx: ManagementContext): Promise<Respons
     // this guard the alias route matched `name = "keys"`, found no such provider, and returned
     // 404 for every key-pool rename.
     if (name === "keys") return null;
-    const provider = config.providers[name];
-    if (!provider) return jsonResponse({ error: `provider '${name}' not found` }, 404, req, config);
+    // Own keys only: `__proto__` or `constructor` would otherwise resolve to Object.prototype.
+    if (!hasOwnProvider(config.providers, name)) return jsonResponse({ error: `provider '${name}' not found` }, 404, req, config);
+    const provider = config.providers[name]!;
     let raw: unknown;
     try { raw = await readManagementJsonBody(req); } catch (error) { rethrowManagementBodyTooLarge(error); return jsonResponse({ error: "invalid JSON body" }, 400); }
     if (!isPlainRecord(raw) || (raw.alias !== null && typeof raw.alias !== "string")) return jsonResponse({ error: "alias must be a string or null" }, 400, req, config);
@@ -330,8 +331,9 @@ export async function handleModelRoutes(ctx: ManagementContext): Promise<Respons
   if (aliasTemplateMatch && req.method === "PUT") {
     const name = decodeURIComponent(aliasTemplateMatch[1]!);
     if (name === "keys") return null;
-    const provider = config.providers[name];
-    if (!provider) return jsonResponse({ error: `provider '${name}' not found` }, 404, req, config);
+    // Own keys only: `__proto__` or `constructor` would otherwise resolve to Object.prototype.
+    if (!hasOwnProvider(config.providers, name)) return jsonResponse({ error: `provider '${name}' not found` }, 404, req, config);
+    const provider = config.providers[name]!;
     let raw: unknown;
     try { raw = await readManagementJsonBody(req); } catch (error) { rethrowManagementBodyTooLarge(error); return jsonResponse({ error: "invalid JSON body" }, 400); }
     if (!isPlainRecord(raw) || (raw.template !== null && typeof raw.template !== "string")) {
@@ -358,8 +360,9 @@ export async function handleModelRoutes(ctx: ManagementContext): Promise<Respons
   if (modelAliasMatch && req.method === "PUT") {
     const name = decodeURIComponent(modelAliasMatch[1]!);
     if (name === "keys") return null;
-    const provider = config.providers[name];
-    if (!provider) return jsonResponse({ error: `provider '${name}' not found` }, 404, req, config);
+    // Own keys only: `__proto__` or `constructor` would otherwise resolve to Object.prototype.
+    if (!hasOwnProvider(config.providers, name)) return jsonResponse({ error: `provider '${name}' not found` }, 404, req, config);
+    const provider = config.providers[name]!;
     let raw: unknown;
     try { raw = await readManagementJsonBody(req); } catch (error) { rethrowManagementBodyTooLarge(error); return jsonResponse({ error: "invalid JSON body" }, 400); }
     if (!isPlainRecord(raw) || (raw.set !== undefined && !isPlainRecord(raw.set)) || (raw.remove !== undefined && !Array.isArray(raw.remove))) return jsonResponse({ error: "invalid model alias update" }, 400, req, config);
diff --git a/tests/server/alias-management-api.test.ts b/tests/server/alias-management-api.test.ts
index e07f61a1e50..bef4526e24c 100644
--- a/tests/server/alias-management-api.test.ts
+++ b/tests/server/alias-management-api.test.ts
@@ -61,3 +61,25 @@ test("#7705: an invalid template or unknown provider is refused without a write"
   expect(c.providers.alpha!.aliasTemplate).toBeUndefined();
   expect((await request(c, "/api/providers/nobody/alias-template", { template: "{modelBasename}" }))?.status).toBe(404);
 });
+
+test("provider alias routes treat inherited object keys as unknown providers", async () => {
+  const c = config();
+  const routes: Array<[string, unknown]> = [
+    ["alias-template", { template: "{modelBasename}-x" }],
+    ["alias", { alias: "proto" }],
+    ["model-aliases", { set: { m1: "proto-one" } }],
+  ];
+  try {
+    for (const name of ["__proto__", "constructor", "toString"]) {
+      for (const [route, body] of routes) {
+        expect((await request(c, `/api/providers/${name}/${route}`, body))?.status).toBe(404);
+      }
+    }
+    const probe = {} as Record<string, unknown>;
+    expect(probe.aliasTemplate).toBeUndefined();
+    expect(probe.alias).toBeUndefined();
+    expect(probe.modelAliases).toBeUndefined();
+  } finally {
+    for (const key of ["aliasTemplate", "alias", "modelAliases"]) delete (Object.prototype as Record<string, unknown>)[key];
+  }
+});

From b82caf63c70e966406e8eb4320ebf44c1a5cb109 Mon Sep 17 00:00:00 2001
From: JUN <jun@lidgeai.com>
Date: Wed, 11 Nov 2026 11:58:21 +0900
Subject: [PATCH 4/5] fix(aliases): keep alias templates behind their own write
 boundary

aliasTemplate is an alias overlay like alias and modelAliases: a full
provider POST may only round-trip the stored value and PATCH refuses it.
Any live write that still carries one (the provider editor batch, ocx
config set) is checked against the same grammar the alias-template route
uses; load keeps dropping a malformed hand edit on its own.

/api/default-aliases now also requires an own provider key, so
__proto__ is a 404 instead of a write to Object.prototype.
---
 src/config/diagnostics.ts                 | 18 +++++++++++++
 src/server/management/model-routes.ts     |  6 ++---
 src/server/management/provider-routes.ts  |  2 +-
 tests/server/alias-management-api.test.ts | 33 +++++++++++++++++++++++
 4 files changed, 55 insertions(+), 4 deletions(-)

diff --git a/src/config/diagnostics.ts b/src/config/diagnostics.ts
index 617db940f68..9a11bec3c88 100644
--- a/src/config/diagnostics.ts
+++ b/src/config/diagnostics.ts
@@ -1,3 +1,4 @@
+import { aliasTemplateError } from "../providers/alias-template";
 import { readExistingSpendSalt, spendPoolAliasesError, validatePoolAliasOwners } from "../lib/spend-pool-alias-validation";
 import { isSubagentModelEntry, rawSubagentModelForce } from "./subagent-models";
 import { validRemainingQuotaAccountIds } from "../codex/account-use-remaining";
@@ -633,6 +634,22 @@ export function loopbackCompanionBindError(
  * this opt-in listener cannot discard providers or credentials. A live config mutation must not
  * get that leniency: it receives an exact field error before the degrading schema is applied.
  */
+/**
+ * #7705: load drops a hand-edited template that does not validate; a live write that carries one
+ * (a provider-wide save, `ocx config set`) gets the same reason the alias-template route gives.
+ */
+function providerAliasTemplateConfigError(value: unknown): string | null {
+  const providers = rawConfigRecord(rawConfigRecord(value)?.providers);
+  if (!providers) return null;
+  for (const [name, provider] of Object.entries(providers)) {
+    const template = rawConfigRecord(provider)?.aliasTemplate;
+    if (template === undefined) continue;
+    const problem = typeof template === "string" ? aliasTemplateError(template) : "template must be a string";
+    if (problem) return `schema_invalid: providers.${name}.aliasTemplate: ${problem}`;
+  }
+  return null;
+}
+
 function managementIngressConfigError(value: unknown): string | null {
   const raw = rawConfigRecord(value);
   if (!raw) return null;
@@ -785,6 +802,7 @@ export function validateConfigCandidate(value: unknown): { ok: true; config: Ocx
     ?? clientRolePairError(value)
     ?? loopbackListenerPortError(value)
     ?? managementIngressConfigError(value)
+    ?? providerAliasTemplateConfigError(value)
     ?? metricsExportConfigError(value)
     ?? serviceHealthRecoveryConfigError(value)
     ?? telemetryConfigError(value)
diff --git a/src/server/management/model-routes.ts b/src/server/management/model-routes.ts
index 9115f06e8c7..d1b90dbd1dc 100644
--- a/src/server/management/model-routes.ts
+++ b/src/server/management/model-routes.ts
@@ -391,9 +391,9 @@ export async function handleModelRoutes(ctx: ManagementContext): Promise<Respons
     try { raw = await readManagementJsonBody(req); } catch (error) { rethrowManagementBodyTooLarge(error); return jsonResponse({ error: "invalid JSON body" }, 400); }
     if (!isPlainRecord(raw) || typeof raw.enabled !== "boolean" || (raw.provider !== undefined && typeof raw.provider !== "string")) return jsonResponse({ error: "enabled must be boolean" }, 400, req, config);
     if (typeof raw.provider === "string") {
-      const provider = config.providers[raw.provider];
-      if (!provider) return jsonResponse({ error: `provider '${raw.provider}' not found` }, 404, req, config);
-      provider.defaultAliases = raw.enabled;
+      // Own keys only, as in the alias routes above.
+      if (!hasOwnProvider(config.providers, raw.provider)) return jsonResponse({ error: `provider '${raw.provider}' not found` }, 404, req, config);
+      config.providers[raw.provider]!.defaultAliases = raw.enabled;
     } else config.defaultModelAliases = raw.enabled;
     persistConfig(config);
     const catalogRefresh = await convergeCodexCatalog();
diff --git a/src/server/management/provider-routes.ts b/src/server/management/provider-routes.ts
index 12debc10978..f5c56fbc0ea 100644
--- a/src/server/management/provider-routes.ts
+++ b/src/server/management/provider-routes.ts
@@ -154,7 +154,7 @@ type ProviderPatchApplication =
       headersTouched: boolean;
     };
 
-const PROVIDER_ALIAS_OVERLAY_FIELDS = ["alias", "modelAliases", "defaultAliases"] as const;
+const PROVIDER_ALIAS_OVERLAY_FIELDS = ["alias", "modelAliases", "defaultAliases", "aliasTemplate"] as const;
 type ProviderAliasOverlayField = typeof PROVIDER_ALIAS_OVERLAY_FIELDS[number];
 
 /**
diff --git a/tests/server/alias-management-api.test.ts b/tests/server/alias-management-api.test.ts
index bef4526e24c..e75903ea110 100644
--- a/tests/server/alias-management-api.test.ts
+++ b/tests/server/alias-management-api.test.ts
@@ -83,3 +83,36 @@ test("provider alias routes treat inherited object keys as unknown providers", a
     for (const key of ["aliasTemplate", "alias", "modelAliases"]) delete (Object.prototype as Record<string, unknown>)[key];
   }
 });
+
+test("#7705: provider-wide writes cannot store a template the alias-template route would refuse", async () => {
+  const { validateConfigCandidate } = await import("../../src/config");
+  const bad = config();
+  bad.providers.alpha!.aliasTemplate = "{vendor}-{modelBasename}";
+  const refused = validateConfigCandidate(bad);
+  expect(refused.ok).toBe(false);
+  if (!refused.ok) expect(refused.error).toContain("aliasTemplate");
+  const good = config();
+  good.providers.alpha!.aliasTemplate = "{modelBasename}-x";
+  expect(validateConfigCandidate(good).ok).toBe(true);
+
+  const c = config();
+  const post = (provider: Record<string, unknown>) => {
+    const req = new Request("http://localhost/api/providers", { method: "POST",
+      headers: { "content-type": "application/json", host: "localhost" }, body: JSON.stringify({ name: "alpha", provider }) });
+    return handleManagementAPI(req, new URL(req.url), c, { saveConfigPreservingClaudeCode: () => {}, createManagementConvergeCodex: catalogConvergenceFactory() });
+  };
+  const created = await post({ ...c.providers.alpha, aliasTemplate: "{modelBasename}-x" });
+  expect(created?.status).toBe(400);
+  expect((await created!.json()).error).toContain("aliasTemplate is managed by the dedicated alias API");
+  expect(c.providers.alpha!.aliasTemplate).toBeUndefined();
+});
+
+test("default-aliases treats inherited object keys as unknown providers", async () => {
+  const c = config();
+  try {
+    expect((await request(c, "/api/default-aliases", { enabled: true, provider: "__proto__" }))?.status).toBe(404);
+    expect(({} as Record<string, unknown>).defaultAliases).toBeUndefined();
+  } finally {
+    delete (Object.prototype as Record<string, unknown>).defaultAliases;
+  }
+});

From cea34ddff80879374fa6263aa0ca86ccc301ede2 Mon Sep 17 00:00:00 2001
From: JUN <jun@lidgeai.com>
Date: Wed, 11 Nov 2026 12:41:31 +0900
Subject: [PATCH 5/5] fix(aliases): reserve registry provider aliases against
 templates

A provider that sets no alias still answers to its registry alias (agy for
google-antigravity); a template name equal to it is now skipped as
reserved, as the approved design requires for any provider alias. Also
moves the template write check above the ingress doc comment it was
inserted under.
---
 src/config/diagnostics.ts                       | 14 +++++++-------
 src/providers/default-aliases.ts                |  2 ++
 tests/providers/provider-alias-template.test.ts | 10 ++++++++++
 3 files changed, 19 insertions(+), 7 deletions(-)

diff --git a/src/config/diagnostics.ts b/src/config/diagnostics.ts
index 9a11bec3c88..0bd1c8316ad 100644
--- a/src/config/diagnostics.ts
+++ b/src/config/diagnostics.ts
@@ -627,13 +627,6 @@ export function loopbackCompanionBindError(
     + "loopback bind already admits local callers without a credential.";
 }
 
-/**
- * Validate the hub management ingress at the live-write boundary.
- *
- * The persisted schema intentionally degrades a malformed hand edit to disabled so a typo in
- * this opt-in listener cannot discard providers or credentials. A live config mutation must not
- * get that leniency: it receives an exact field error before the degrading schema is applied.
- */
 /**
  * #7705: load drops a hand-edited template that does not validate; a live write that carries one
  * (a provider-wide save, `ocx config set`) gets the same reason the alias-template route gives.
@@ -650,6 +643,13 @@ function providerAliasTemplateConfigError(value: unknown): string | null {
   return null;
 }
 
+/**
+ * Validate the hub management ingress at the live-write boundary.
+ *
+ * The persisted schema intentionally degrades a malformed hand edit to disabled so a typo in
+ * this opt-in listener cannot discard providers or credentials. A live config mutation must not
+ * get that leniency: it receives an exact field error before the degrading schema is applied.
+ */
 function managementIngressConfigError(value: unknown): string | null {
   const raw = rawConfigRecord(value);
   if (!raw) return null;
diff --git a/src/providers/default-aliases.ts b/src/providers/default-aliases.ts
index e014c1a29c2..ce982633a0b 100644
--- a/src/providers/default-aliases.ts
+++ b/src/providers/default-aliases.ts
@@ -150,6 +150,8 @@ export function templateAliasPlan(
   for (const [name, other] of Object.entries(config.providers ?? {})) {
     reserve(name);
     reserve(other.alias);
+    // A registry alias (`agy` for google-antigravity) names the provider even when it sets none.
+    if (config.providers) reserve(effectiveProviderAlias(name, other, config as Pick<OcxConfig, "providers">));
     if (name !== providerName) for (const alias of Object.values(other.modelAliases ?? {})) reserve(alias);
   }
   for (const [id, combo] of Object.entries(config.combos ?? {})) { reserve(id); reserve((combo as { alias?: unknown }).alias); }
diff --git a/tests/providers/provider-alias-template.test.ts b/tests/providers/provider-alias-template.test.ts
index de7e194de2e..4b34d4ab1f0 100644
--- a/tests/providers/provider-alias-template.test.ts
+++ b/tests/providers/provider-alias-template.test.ts
@@ -149,3 +149,13 @@ describe("loading a hand-edited alias template", () => {
     ]);
   });
 });
+
+describe("registry provider aliases", () => {
+  test("a provider's registry alias is reserved even when it sets none of its own", () => {
+    const c = config(["vendor/agy", "vendor/beam"], { aliasTemplate: "{modelBasename}" });
+    c.providers["google-antigravity"] = { adapter: "google-antigravity", baseUrl: "https://agy.test/v1" } as OcxProviderConfig;
+    const plan = templateAliasPlan(c, c.providers.cc!, "cc", ["vendor/agy", "vendor/beam"], new Map());
+    expect([...plan.accepted]).toEqual([["vendor/beam", "beam"]]);
+    expect(plan.skipped).toEqual([{ id: "vendor/agy", candidate: "agy", reason: "reserved" }]);
+  });
+});