@yalehwang/cloudpit 2.0.0 → 3.0.0

package/server/modules/providers/services/session-provider-binding.ts

@@ -0,0 +1,176 @@
+/**
+ * The upstream-provider binding a session carries (AC-462).
+ *
+ * WHY A SESSION HAS ONE. A custom model entry may name the Codex provider it
+ * dials (`codexProviderId`, AC-461). Codex records that provider inside the
+ * thread it starts and checks it again on every resume: a thread started under
+ * provider `bob` refuses a turn when the process is launched under `alice`
+ * (`modelProviderMismatch`). The binding therefore belongs to the SESSION, not
+ * only to the model currently selected — changing the model of a running
+ * session to one from another provider does not switch providers, it breaks
+ * the conversation. A session that has run under a bound provider must be
+ * forked or recreated to run under a different one.
+ *
+ * WHAT THIS FILE OWNS. The three answers every reader needs, and nothing else:
+ *   1. which provider id a selected model resolves to;
+ *   2. whether a recorded id still names a provider the project defines (a
+ *      deleted or renamed provider is MARKED, never silently replaced by the
+ *      provider default);
+ *   3. whether a switch from the recorded id to the requested one is allowed.
+ *
+ * TWO ABSENCES ARE DIFFERENT. `model_provider_id` NULL means "no binding has
+ * been recorded" — an unbound model, a session from before the column, or one
+ * that has never been sent on. NULL is NOT "the default provider", so a
+ * selection may establish a binding on such a session; once recorded, the
+ * binding only ever changes through a new session. A model that declares no
+ * provider resolves to NULL, and moving a BOUND session to it is a switch
+ * (it would run under Codex's process-global provider) and is refused.
+ *
+ * WHAT THIS FILE DOES NOT DO. It never writes rows, never reads settings, and
+ * never imports a feature module: the registry is handed in as a reading (the
+ * shared port's `CodexProviderRegistryReading`) and the catalog as the one
+ * lookup it needs. `provider-models.service.ts` composes it with both.
+ *
+ * Consumers: `provider-models.service.ts` (recording and resolving a session's
+ * selection) and, through it, `chat-websocket.service.ts` (the pre-admission
+ * refusal of a send that would switch providers).
+ */
+import type { CodexProviderRegistryReading } from '@/shared/ports/codex-provider-registry.port.js';
+import type { CustomProviderModelRecord, LLMProvider } from '@/shared/types.js';
+import { AppError } from '@/shared/utils.js';
+
+/** The catalog lookup a binding reading needs; `providerModelsDb` satisfies it. */
+export type SessionProviderBindingCatalog = {
+  findCustomProviderModelByModelId(
+    provider: LLMProvider,
+    modelId: string,
+  ): CustomProviderModelRecord | null;
+};
+
+/**
+ * A recorded binding as a reader should see it.
+ *
+ * `modelProviderProblem` is the explicit mark the AC asks for instead of a
+ * silent fallback: it is non-null only when the session carries an upstream
+ * provider id the registry no longer defines, and it names the id and the way
+ * out. `modelProviderId` is always the recorded value, unchanged — a provider
+ * that disappeared must not make the session look unbound.
+ */
+export type SessionProviderBinding = {
+  modelProviderId: string | null;
+  modelProviderProblem: string | null;
+};
+
+/**
+ * The upstream provider a selected model runs under, or null when it declares
+ * none (the entry inherits the provider's own default).
+ *
+ * The value is read from the model entry, never from the session: the session
+ * only records what the entry said at the time it first ran.
+ */
+export function resolveModelProviderId(
+  catalog: SessionProviderBindingCatalog,
+  provider: LLMProvider,
+  modelId: string,
+): string | null {
+  const record = catalog.findCustomProviderModelByModelId(provider, modelId);
+  return record?.config?.codexProviderId?.trim() || null;
+}
+
+/**
+ * Whether the registry defines this id.
+ *
+ * A project entry and a Codex built-in both count: a model may bind either
+ * (`RESERVED_CODEX_PROVIDER_IDS` is the settings source's list, carried here as
+ * data). An absent reading cannot judge, so it answers true — refusing every
+ * selection merely because the composition root has not installed the port yet
+ * would break the callers that ran before this feature existed.
+ */
+function isKnownProvider(registry: CodexProviderRegistryReading | null, providerId: string): boolean {
+  if (registry === null) {
+    return true;
+  }
+  return registry.reservedIds.includes(providerId)
+    || registry.providers.some((provider) => provider.id === providerId);
+}
+
+/**
+ * Reads a recorded provider id plus, when the registry no longer defines it,
+ * the readable mark that says so.
+ *
+ * The model itself is NEVER re-resolved here: a session whose provider was
+ * deleted keeps the model it ran with, so every reader still shows what the
+ * conversation actually used. Falling back to the catalog default is the exact
+ * silent change this mark exists to prevent.
+ */
+export function readRecordedProviderBinding(
+  registry: CodexProviderRegistryReading | null,
+  providerId: string | null,
+): SessionProviderBinding {
+  if (!providerId) {
+    return { modelProviderId: null, modelProviderProblem: null };
+  }
+  if (isKnownProvider(registry, providerId)) {
+    return { modelProviderId: providerId, modelProviderProblem: null };
+  }
+  return {
+    modelProviderId: providerId,
+    modelProviderProblem:
+      `This session is bound to provider "${providerId}", which is no longer defined. `
+      + 'Fork this session or start a new one to run it under another provider.',
+  };
+}
+
+/**
+ * Refuses moving an already-bound session to a selection that runs under a
+ * different upstream provider.
+ *
+ * Returns silently when the session has no recorded binding (any selection may
+ * establish one), or when the requested model resolves to the same id (another
+ * model on the same provider is an ordinary model switch).
+ *
+ * The refusal names both ids and the action, because "cannot switch" without
+ * "here is what to do instead" leaves the person with a dead composer.
+ */
+export function assertProviderSwitchAllowed(
+  recordedProviderId: string | null,
+  requestedProviderId: string | null,
+  requestedModel: string,
+): void {
+  if (!recordedProviderId || requestedProviderId === recordedProviderId) {
+    return;
+  }
+  const attempted = requestedProviderId === null
+    ? 'a model that inherits the provider default'
+    : `provider "${requestedProviderId}"`;
+  throw new AppError(
+    `This session is bound to provider "${recordedProviderId}"; `
+    + `model "${requestedModel}" runs under ${attempted}. A session cannot change upstream `
+    + 'provider in place — fork this session or start a new one to switch.',
+    { code: 'SESSION_PROVIDER_MISMATCH', statusCode: 409 },
+  );
+}
+
+/**
+ * Refuses recording a binding the registry does not know.
+ *
+ * A model entry can outlive the provider it names (the provider registry is a
+ * full-file replacement, so deleting or renaming an entry leaves every model
+ * entry bound to the old id pointing at nothing). Recording such an id would
+ * make a fresh session look bound to a provider that cannot be launched, so the
+ * selection is refused with the id and the two ways out.
+ */
+export function assertProviderAvailable(
+  registry: CodexProviderRegistryReading | null,
+  providerId: string | null,
+  requestedModel: string,
+): void {
+  if (!providerId || isKnownProvider(registry, providerId)) {
+    return;
+  }
+  throw new AppError(
+    `Model "${requestedModel}" is bound to provider "${providerId}", which no longer exists. `
+    + 'Pick another model, or restore the provider in the Codex provider settings.',
+    { code: 'SESSION_PROVIDER_UNKNOWN', statusCode: 409 },
+  );
+}

package/server/modules/providers/services/sessions.service.ts

@@ -481,7 +481,7 @@ export const sessionsService = {
    * chat, navigates to the returned id immediately, and the id never changes
    * for the lifetime of the conversation. The provider-native id is mapped to
    * this row later, when the provider runtime announces it mid-run. Its title
-   * comes directly from the first visible CloudCLI message and is limited to
+   * comes directly from the first visible Cloudpit message and is limited to
    * four whole words before any provider-owned storage exists.
    *
    * `selection` is the model/effort/permission-mode the caller is creating the
@@ -615,6 +615,10 @@ export const sessionsService = {
       // differently from the conversation it was branched from.
       model: source.model,
       effort: source.effort,
+      // The branch continues a thread the provider started under one upstream
+      // provider: resuming it under the process default is the mismatch this
+      // column exists to prevent, so the binding comes along.
+      modelProviderId: source.model_provider_id ?? null,
       // Same reasoning for the permission mode: a fork inherits how the
       // conversation it branches from was actually being run.
       permissionMode: source.permission_mode,

package/server/modules/providers/tests/claude-resident-addressable.test.ts

@@ -4,7 +4,7 @@
  *
  * A resident host holds one CLI across turns, and every CLI process registers a
  * name for itself when it starts: other sessions on the machine can address it
- * by that name. Claude Code picks that name; **CloudCLI does not**. It used to
+ * by that name. Claude Code picks that name; **Cloudpit does not**. It used to
  * (`--name <slug>-<id6>`, proposal §12), and that is the design this criterion
  * was rewritten for: an app-invented name outranked the session's own `ai-title`
  * and grew a new suffix on every restart. The app now launches the process with
@@ -1462,7 +1462,7 @@ test('a resident session publishes the address it answers to, and a peer reaches
       null,
       'the registry entry must carry the socket the address resolves to, or the address is not reachable',
     );
-    // The pollution shape itself, read on the published address: CloudCLI's
+    // The pollution shape itself, read on the published address: Cloudpit's
     // suffix was the app session id's first six characters appended to a slug.
     // A derived name is the CLI's and has no such tail.
     assert.strictEqual(

package/server/modules/providers/tests/claude-session-name-authority.test.ts

@@ -22,9 +22,9 @@ import { ClaudeSessionSynchronizer } from '@/modules/providers/list/claude/claud
 import { sessionsService } from '@/modules/providers/services/sessions.service.js';
 
 /**
- * Who owns a session's name: a human, Claude Code, or CloudCLI.
+ * Who owns a session's name: a human, Claude Code, or Cloudpit.
  *
- * CloudCLI does not own it. That is the settled design ((a) in the task
+ * Cloudpit does not own it. That is the settled design ((a) in the task
  * record): the app no longer hands the CLI a `--name` at all, and the name a
  * session has is the one Claude Code gives it. What remains to guard here is
  * everything an *older* build left behind — the launch address it wrote into
@@ -41,7 +41,7 @@ import { sessionsService } from '@/modules/providers/services/sessions.service.j
  * - a real `agent-name` an agent chose, and a name the user chose, both still
  *   outrank it — without those two, the simplest way to pass the case above
  *   would be to demote every name the CLI writes;
- * - the rank table itself has to keep CloudCLI's own sources below `ai`, or the
+ * - the rank table itself has to keep Cloudpit's own sources below `ai`, or the
  *   ladder above is unreachable through the other door into the same row.
  *
  * The fixtures are real transcript lines in a real temporary Claude home,
@@ -687,7 +687,7 @@ test('the discriminator is anchored on the session it is asked about', () => {
   assert.strictEqual(isSelfAssignedSessionName('The Agent That Owns This', appSessionId), false);
 });
 
-test('the rank table keeps every CloudCLI-made source below a real title', async () => {
+test('the rank table keeps every Cloudpit-made source below a real title', async () => {
   await withIsolatedDatabase(async () => {
     const projectPath = await mkdtemp(path.join(os.tmpdir(), 'claude-name-authority-rank-'));
     projectsDb.createProjectPath(projectPath);

package/server/modules/providers/tests/codex-app-server-protocol.test.ts

@@ -439,7 +439,7 @@ test('the declaration is what switches thread/queue/add on and off (AC3)', async
     jsonrpc: '2.0',
     id: 1,
     method: 'initialize',
-    params: { clientInfo: { name: 'cloudcli', version: '1' }, capabilities: {} },
+    params: { clientInfo: { name: 'cloudpit', version: '1' }, capabilities: {} },
   }));
   undeclared.write(JSON.stringify({
     jsonrpc: '2.0',

package/server/modules/providers/tests/codex-host-driver-persistent.test.ts

@@ -484,11 +484,11 @@ test('driver conforms to IProviderHostDriver with multiplexedHost=false (AC8)',
 });
 
 /**
- * The failure this criterion pins: CloudCLI's `default` effort sentinel is not
+ * The failure this criterion pins: Cloudpit's `default` effort sentinel is not
  * a codex effort, and the locked 0.153.4 app-server refuses the whole turn with
  * `Invalid value: 'default'` rather than ignoring the field.
  */
-test("turn/start omits CloudCLI's 'default' effort and forwards a codex value (AC1)", () => {
+test("turn/start omits Cloudpit's 'default' effort and forwards a codex value (AC1)", () => {
   const withDefault = turnParams('thread-effort', { command: 'hi', options: { effort: 'default' } });
   const withHigh = turnParams('thread-effort', { command: 'hi', options: { effort: 'high' } });
   const withUltracode = turnParams('thread-effort', { command: 'hi', options: { effort: 'ultracode' } });

package/server/modules/providers/tests/codex-provider-model-binding.test.ts

@@ -0,0 +1,345 @@
+import assert from 'node:assert/strict';
+import { once } from 'node:events';
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import type { AddressInfo } from 'node:net';
+import os from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+
+import Database from 'better-sqlite3';
+import express, { type NextFunction, type Request, type Response } from 'express';
+
+import { closeConnection, initializeDatabase } from '@/modules/database/index.js';
+import providerRouter from '@/modules/providers/provider.routes.js';
+import { createProviderModelsService } from '@/modules/providers/services/provider-models.service.js';
+import {
+  installCodexProviderRegistryPort,
+  type CodexProviderRegistryReading,
+} from '@/shared/ports/codex-provider-registry.port.js';
+import type {
+  CustomProviderModelInput,
+  CustomProviderModelRecord,
+  LLMProvider,
+  ProviderModelsDefinition,
+} from '@/shared/types.js';
+import { AppError } from '@/shared/utils.js';
+
+/**
+ * The model-entry → Codex provider binding (AC-461).
+ *
+ * Legs:
+ * 1. a declared `codexProviderId` is normalized, persisted, and shown as
+ *    `model · provider` in the merged catalog;
+ * 2. an id that no provider defines (never existed, or was deleted) is refused
+ *    with a readable 409 that names it, and nothing is written;
+ * 3. an entry that declares no provider keeps the pre-existing behaviour —
+ *    bare display name, no stored binding, "inherit the Codex global default";
+ * 4. a reserved Codex built-in id is bindable even though the project file may
+ *    not define it;
+ * 5. duplicating an entry copies its binding;
+ * 6. the HTTP route carries `codexProviderId` through to storage.
+ *
+ * The registry itself is a shared port (the settings module installs the real
+ * reading at boot); these legs install a fake reading so the model service is
+ * driven without touching a settings file, and the route leg installs the same
+ * fake for the process-wide singleton the router uses.
+ */
+
+const PREDEFINED: ProviderModelsDefinition = {
+  OPTIONS: [{ value: 'codex-default', label: 'Codex default' }],
+  DEFAULT: 'codex-default',
+};
+
+/** In-memory stand-in for the `provider_models` table; update persists the config like the DB. */
+const createCatalogStore = () => {
+  const rows = new Map<LLMProvider, CustomProviderModelRecord[]>();
+  let nextRecordId = 1;
+  const readRows = (provider: LLMProvider) => rows.get(provider) ?? [];
+
+  return {
+    rows,
+    listCustomProviderModels(provider: LLMProvider) {
+      return [...readRows(provider)];
+    },
+    getCustomProviderModel(provider: LLMProvider, recordId: number) {
+      return readRows(provider).find((record) => record.recordId === recordId) ?? null;
+    },
+    findCustomProviderModelByModelId(provider: LLMProvider, modelId: string) {
+      return readRows(provider).find((record) => record.modelId === modelId) ?? null;
+    },
+    createCustomProviderModel(provider: LLMProvider, input: CustomProviderModelInput) {
+      const record: CustomProviderModelRecord = {
+        recordId: nextRecordId++,
+        provider,
+        modelId: input.id,
+        model: input.model,
+        config: input.config ?? null,
+        sortOrder: readRows(provider).length,
+      };
+      rows.set(provider, [...readRows(provider), record]);
+      return record;
+    },
+    updateCustomProviderModel(
+      provider: LLMProvider,
+      recordId: number,
+      input: CustomProviderModelInput,
+    ) {
+      const existing = readRows(provider).find((record) => record.recordId === recordId);
+      if (!existing) {
+        return null;
+      }
+      const updated: CustomProviderModelRecord = {
+        ...existing,
+        modelId: input.id,
+        model: input.model,
+        config: input.config === undefined ? existing.config : input.config,
+      };
+      rows.set(provider, readRows(provider).map((record) => (
+        record.recordId === recordId ? updated : record
+      )));
+      return updated;
+    },
+    deleteCustomProviderModel(provider: LLMProvider, recordId: number, _fallbackModelId: string) {
+      const existing = readRows(provider).find((record) => record.recordId === recordId);
+      if (!existing) {
+        return null;
+      }
+      rows.set(provider, readRows(provider).filter((record) => record.recordId !== recordId));
+      return existing;
+    },
+  };
+};
+
+const createService = (read: () => CodexProviderRegistryReading | null) => {
+  const catalog = createCatalogStore();
+  const service = createProviderModelsService({
+    resolveProvider: () => ({
+      models: {
+        getSupportedModels: async () => PREDEFINED,
+        getCurrentActiveModel: async () => ({ model: PREDEFINED.DEFAULT }),
+      },
+    }),
+    catalog,
+    sessions: {
+      getSessionById: () => null,
+      setSessionModel: () => undefined,
+      // No row in this file's fixture, so no session-binding write can land;
+      // the method exists to satisfy the service's narrowed store seam.
+      setSessionModelProviderId: () => false,
+      setSessionEffort: () => undefined,
+      setSessionPermissionMode: () => false,
+    },
+    codexProviders: { read },
+  });
+  return { catalog, service };
+};
+
+/** One fake registry reading; `providers` is the mutable project half, reserved ids are fixed. */
+const createRegistry = (
+  initialIds: string[] = [],
+  reservedIds: string[] = ['openai', 'ollama', 'lmstudio'],
+) => {
+  const ids = new Set(initialIds);
+  const reading = (): CodexProviderRegistryReading => ({
+    providers: [...ids].map((id) => ({ id })),
+    reservedIds,
+  });
+  return { ids, reading };
+};
+
+const modelInput = (codexProviderId?: string): CustomProviderModelInput => ({
+  id: 'bound-model',
+  model: 'Bound Model',
+  config: codexProviderId === undefined ? { env: [] } : { env: [], codexProviderId },
+});
+
+const assertRefused = (error: unknown, providerId: string): boolean => {
+  assert.ok(error instanceof AppError, `expected AppError, got ${String(error)}`);
+  assert.equal(error.statusCode, 409);
+  assert.equal(error.code, 'CODEX_PROVIDER_UNKNOWN');
+  assert.match(error.message, new RegExp(providerId.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')));
+  assert.match(error.message, /omit codexProviderId/);
+  return true;
+};
+
+test('a declared provider is persisted and the merged catalog row shows model · provider', async () => {
+  const registry = createRegistry(['bob']);
+  const { catalog, service } = createService(registry.reading);
+
+  const created = await service.createCustomModel('codex', modelInput('bob'));
+
+  assert.equal(created.model.label, 'Bound Model · bob');
+  assert.equal(created.model.config?.codexProviderId, 'bob');
+  assert.deepEqual(created.model.config?.env, []);
+  const stored = catalog.rows.get('codex')?.[0];
+  assert.ok(stored, 'the row must be written');
+  assert.deepEqual(stored.config, { codexProviderId: 'bob', env: [] });
+
+  const merged = await service.getProviderModels('codex');
+  const option = merged.OPTIONS.find((entry) => entry.value === 'bound-model');
+  assert.equal(option?.label, 'Bound Model · bob');
+  assert.equal(option?.config?.codexProviderId, 'bob');
+});
+
+test('an unknown provider is refused with a readable 409 naming it, and nothing is written', async () => {
+  const { catalog, service } = createService(createRegistry([]).reading);
+
+  await assert.rejects(
+    service.createCustomModel('codex', modelInput('nobody')),
+    (error) => assertRefused(error, 'nobody'),
+  );
+  assert.deepEqual(catalog.rows.get('codex'), undefined, 'no row may be persisted');
+
+  const merged = await service.getProviderModels('codex');
+  assert.deepEqual(
+    merged.OPTIONS.map((entry) => entry.value),
+    ['codex-default'],
+    'a refused entry must not appear in the catalog',
+  );
+});
+
+test('a provider deleted since the entry was written is refused on update, and the row is untouched', async () => {
+  const registry = createRegistry(['bob']);
+  const { catalog, service } = createService(registry.reading);
+  const created = await service.createCustomModel('codex', modelInput('bob'));
+  const recordId = created.model.recordId;
+  assert.ok(recordId);
+
+  registry.ids.delete('bob');
+
+  await assert.rejects(
+    service.updateCustomModel('codex', recordId, {
+      id: 'bound-model',
+      model: 'Renamed',
+      config: { env: [], codexProviderId: 'bob' },
+    }),
+    (error) => assertRefused(error, 'bob'),
+  );
+  const stored = catalog.rows.get('codex')?.[0];
+  assert.equal(stored?.model, 'Bound Model', 'the refused update must not rename the row');
+  assert.equal(stored?.config?.codexProviderId, 'bob');
+
+  // A create that binds the same deleted id is refused too: no dangling reference may be added.
+  await assert.rejects(
+    service.createCustomModel('codex', { ...modelInput('bob'), id: 'second-model' }),
+    (error) => assertRefused(error, 'bob'),
+  );
+  assert.equal(catalog.rows.get('codex')?.length, 1);
+});
+
+test('an entry that declares no provider keeps the passthrough baseline', async () => {
+  const { catalog, service } = createService(createRegistry(['bob']).reading);
+
+  const withoutBinding = await service.createCustomModel('codex', modelInput());
+  assert.equal(withoutBinding.model.label, 'Bound Model');
+  assert.deepEqual(withoutBinding.model.config, { env: [] });
+
+  // No config at all: the stored config is null, exactly as before this field existed.
+  const withoutConfig = await service.createCustomModel('codex', { id: 'bare', model: 'Bare' });
+  assert.equal(withoutConfig.model.label, 'Bare');
+  assert.equal(withoutConfig.model.config, null);
+
+  assert.deepEqual(
+    catalog.rows.get('codex')?.map((record) => record.config),
+    [{ env: [] }, null],
+  );
+});
+
+test('a reserved Codex built-in id is bindable without a project registry entry', async () => {
+  const registry = createRegistry([]);
+  const { service } = createService(registry.reading);
+
+  const created = await service.createCustomModel('codex', modelInput('openai'));
+  assert.equal(created.model.label, 'Bound Model · openai');
+  assert.equal(created.model.config?.codexProviderId, 'openai');
+});
+
+test('duplicating an entry copies its provider binding', async () => {
+  const { service } = createService(createRegistry(['bob']).reading);
+  const source = await service.createCustomModel('codex', modelInput('bob'));
+  assert.ok(source.model.recordId);
+
+  const copy = await service.duplicateCustomModel('codex', source.model.recordId, {
+    id: 'copy-model',
+    model: 'Copy',
+  });
+  assert.equal(copy.model.label, 'Copy · bob');
+  assert.equal(copy.model.config?.codexProviderId, 'bob');
+});
+
+/** Mounts the production router over a temp SQLite database, like `model-config-write-path`. */
+async function withServer(run: (baseUrl: string, dbPath: string) => Promise<void>): Promise<void> {
+  const previous = process.env.DATABASE_PATH;
+  const dir = await mkdtemp(path.join(os.tmpdir(), 'codex-binding-'));
+  const dbPath = path.join(dir, 'auth.db');
+  closeConnection();
+  process.env.DATABASE_PATH = dbPath;
+  await writeFile(dbPath, '');
+  await initializeDatabase();
+
+  const app = express().use(express.json()).use('/api/providers', providerRouter);
+  app.use((error: unknown, _req: Request, res: Response, _next: NextFunction) => {
+    if (error instanceof AppError) {
+      res.status(error.statusCode).json({ success: false, error: { code: error.code, message: error.message } });
+      return;
+    }
+    res.status(500).json({ success: false });
+  });
+  const server = app.listen(0, '127.0.0.1');
+  await once(server, 'listening');
+  try {
+    await run(`http://127.0.0.1:${(server.address() as AddressInfo).port}`, dbPath);
+  } finally {
+    await new Promise<void>((resolve, reject) => server.close((e) => (e ? reject(e) : resolve())));
+    closeConnection();
+    if (previous === undefined) delete process.env.DATABASE_PATH;
+    else process.env.DATABASE_PATH = previous;
+    await rm(dir, { recursive: true, force: true });
+  }
+}
+
+const postModel = (base: string, provider: string, body: unknown) => fetch(
+  `${base}/api/providers/${provider}/models`,
+  { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) },
+);
+
+test('the HTTP route carries codexProviderId through to storage and refuses an unknown id', async () => {
+  const registry = createRegistry(['bob']);
+  installCodexProviderRegistryPort({ read: registry.reading });
+
+  await withServer(async (base, dbPath) => {
+    const accepted = await postModel(base, 'claude', {
+      id: 'route-bound',
+      model: 'Route Bound',
+      config: { env: [], codexProviderId: 'bob' },
+    });
+    assert.equal(accepted.status, 201);
+    const acceptedBody = (await accepted.json()) as {
+      data: { model: { label: string; config?: { codexProviderId?: string } } };
+    };
+    assert.equal(acceptedBody.data.model.label, 'Route Bound · bob');
+    assert.equal(acceptedBody.data.model.config?.codexProviderId, 'bob');
+
+    const refused = await postModel(base, 'claude', {
+      id: 'route-unknown',
+      model: 'Route Unknown',
+      config: { env: [], codexProviderId: 'nobody' },
+    });
+    assert.equal(refused.status, 409);
+    const refusedBody = (await refused.json()) as { error?: { code?: string; message?: string } };
+    assert.equal(refusedBody.error?.code, 'CODEX_PROVIDER_UNKNOWN');
+    assert.match(refusedBody.error?.message ?? '', /nobody/);
+
+    const db = new Database(dbPath, { readonly: true });
+    const rows = db.prepare('SELECT model_id, config_json FROM provider_models ORDER BY id').all() as Array<{
+      model_id: string;
+      config_json: string | null;
+    }>;
+    db.close();
+    assert.deepEqual(rows.map((row) => row.model_id), ['route-bound']);
+    assert.deepEqual(JSON.parse(rows[0].config_json ?? 'null'), {
+      codexProviderId: 'bob',
+      env: [],
+    });
+  });
+});