fix(subagent): reconcile refreshed catalogs with the policy and harden the policy write path

- refreshProviderModels clamps a [secondary_model] binding or pool entry whose
  model vanished from the refreshed catalog, so the discovery service no longer
  rejects the whole provider patch as CONFIG_INVALID
- policy validation names [secondary_model].default_model when that field is
  the one that fails to resolve
- SubagentModelPolicyService serializes commits so the If-Match version check
  and the write run as one transition
- POST /config accepts the legacy secondary_model metadata echoed by GET and
  drops it on write instead of rejecting the round trip
- policy PUT/DELETE report only the mutating call as a validation failure
- discovery test stub validates the legacy section through the schema

Author: elkaix

packages/agent-core-v2/src/session/subagent/policy.ts

@@ -183,21 +183,25 @@ function assertModelResolves(
   field: string,
   context: SubagentPolicyValidationContext,
 ): SubagentPolicyModelInfo {
+  const label =
+    field === 'models'
+      ? `[secondary_model.models] entry "${alias}"`
+      : `[secondary_model].default_model "${alias}"`;
   let info: SubagentPolicyModelInfo | undefined;
   try {
     info = context.resolveModel(alias);
   } catch (error) {
     throw new Error2(
       ErrorCodes.CONFIG_INVALID,
-      `[secondary_model.models] entry "${alias}" could not be resolved: ${error instanceof Error ? error.message : String(error)}`,
+      `${label} could not be resolved: ${error instanceof Error ? error.message : String(error)}`,
       { cause: error, details: { section: SECONDARY_MODEL_SECTION, field, model: alias } },
     );
   }
   if (info === undefined) {
-    throw invalid(
-      `[secondary_model.models] entry "${alias}" could not be resolved: Model "${alias}" is not configured in config.toml.`,
-      { field, model: alias },
-    );
+    throw invalid(`${label} could not be resolved: Model "${alias}" is not configured in config.toml.`, {
+      field,
+      model: alias,
+    });
   }
   return info;
 }

packages/agent-core-v2/src/session/subagent/subagentModelPolicyService.ts

@@ -34,6 +34,8 @@ import {
 export class SubagentModelPolicyService implements ISubagentModelPolicyService {
   declare readonly _serviceBrand: undefined;
 
+  private commitChain: Promise<unknown> = Promise.resolve();
+
   constructor(
     @IConfigService private readonly config: IConfigService,
     @IFlagService private readonly flags: IFlagService,
@@ -148,7 +150,19 @@ export class SubagentModelPolicyService implements ISubagentModelPolicyService {
     }
   }
 
-  private async commit(
+  private commit(
+    section: LegacySecondaryModelConfig | undefined,
+    expectedVersion: string | undefined,
+  ): Promise<void> {
+    const run = this.commitChain.then(
+      () => this.commitNow(section, expectedVersion),
+      () => this.commitNow(section, expectedVersion),
+    );
+    this.commitChain = run.catch(() => undefined);
+    return run;
+  }
+
+  private async commitNow(
     section: LegacySecondaryModelConfig | undefined,
     expectedVersion: string | undefined,
   ): Promise<void> {

packages/agent-core-v2/test/app/kosongConfig/discovery.test.ts

@@ -7,6 +7,7 @@ import { IAgentIdentity } from '#/app/agentIdentity/agentIdentity';
 import { IBootstrapService } from '#/app/bootstrap/bootstrap';
 import { IConfigService } from '#/app/config/config';
 import {
+  LegacySecondaryModelConfigSchema,
   normalizeLegacySecondaryModel,
   toPersistedSecondaryModel,
 } from '#/session/subagent/policy';
@@ -71,9 +72,7 @@ function stubLogService(): ILogService {
 function stubSubagentModelPolicy(): ISubagentModelPolicyService {
   const prepare = (input: unknown): PreparedSubagentPolicyMutation => {
     const policy = normalizeLegacySecondaryModel(
-      input === null || input === undefined
-        ? undefined
-        : (input as Parameters<typeof normalizeLegacySecondaryModel>[0]),
+      input === null || input === undefined ? undefined : LegacySecondaryModelConfigSchema.parse(input),
     );
     return { policy, section: toPersistedSecondaryModel(policy) };
   };

packages/agent-core-v2/test/session/subagent/subagentModelPolicyService.test.ts

@@ -125,6 +125,26 @@ describe('SubagentModelPolicyService', () => {
     expect(await codeOf(() => service.clear(before))).toBe(ErrorCodes.CONFIG_VERSION_CONFLICT);
   });
 
+  it('serializes concurrent commits so a stale expectedVersion cannot slip past the version check', async () => {
+    const service = setup({ [SECONDARY_MODEL_SECTION]: { defaultModel: 'acme/sol' } });
+    const replace = config.replace.bind(config);
+    config.replace = async (domain, value) => {
+      await new Promise((resolve) => setTimeout(resolve, 0));
+      await replace(domain, value);
+    };
+    const version = service.get().resourceVersion;
+    const [first, second] = await Promise.allSettled([
+      service.set({ mode: 'default', defaultModel: 'acme/luna' }, version),
+      service.set({ mode: 'force', defaultModel: 'acme/sol' }, version),
+    ]);
+    expect(first.status).toBe('fulfilled');
+    expect(second.status).toBe('rejected');
+    expect((second as PromiseRejectedResult).reason).toMatchObject({
+      code: ErrorCodes.CONFIG_VERSION_CONFLICT,
+    });
+    expect(config.get(SECONDARY_MODEL_SECTION)).toEqual({ defaultModel: 'acme/luna', defaultEffort: undefined });
+  });
+
   it('getEffective reports inherit while the feature is disabled and keeps the configured policy', () => {
     const service = setup(
       { [SECONDARY_MODEL_SECTION]: { defaultModel: 'acme/sol', force: true } },

packages/agent-core-v2/test/session/subagent/subagentModelsValidation.test.ts

@@ -96,7 +96,7 @@ describe('SessionSubagentModelsValidationService', () => {
     expect(isError2(error)).toBe(true);
     expect((error as Error2).code).toBe(ErrorCodes.CONFIG_INVALID);
     expect((error as Error2).message).toContain(
-      '[secondary_model.models] entry "provider/typo" could not be resolved',
+      '[secondary_model].default_model "provider/typo" could not be resolved',
     );
   });
 
@@ -128,8 +128,9 @@ describe('SessionSubagentModelsValidationService', () => {
     expect(isError2(error)).toBe(true);
     expect((error as Error2).code).toBe(ErrorCodes.CONFIG_INVALID);
     expect((error as Error2).message).toContain(
-      '[secondary_model.models] entry "provider/typo" could not be resolved',
+      '[secondary_model].default_model "provider/typo" could not be resolved',
     );
+    expect((error as Error2).message).not.toContain('[secondary_model.models]');
   });
 
   it('constructs fine for a valid pool', () => {

packages/agent-gateway/src/protocol/rest-config.ts

@@ -34,6 +34,7 @@ export const configResponseSchema = z.object({
 export type ConfigResponse = z.infer<typeof configResponseSchema>;
 
 const optionalModelAlias = z.string().min(1).optional();
+const droppedLegacyMetadata = z.unknown().optional();
 
 export const legacySecondaryModelRequestSchema = z
   .object({
@@ -44,6 +45,23 @@ export const legacySecondaryModelRequestSchema = z
     defaultEffort: z.string().optional(),
     models: z.record(z.string(), z.string()).optional(),
     force: z.boolean().optional(),
+    max_context_size: droppedLegacyMetadata,
+    maxContextSize: droppedLegacyMetadata,
+    max_input_size: droppedLegacyMetadata,
+    maxInputSize: droppedLegacyMetadata,
+    max_output_size: droppedLegacyMetadata,
+    maxOutputSize: droppedLegacyMetadata,
+    capabilities: droppedLegacyMetadata,
+    display_name: droppedLegacyMetadata,
+    displayName: droppedLegacyMetadata,
+    reasoning_key: droppedLegacyMetadata,
+    reasoningKey: droppedLegacyMetadata,
+    adaptive_thinking: droppedLegacyMetadata,
+    adaptiveThinking: droppedLegacyMetadata,
+    support_efforts: droppedLegacyMetadata,
+    supportEfforts: droppedLegacyMetadata,
+    off_effort: droppedLegacyMetadata,
+    offEffort: droppedLegacyMetadata,
   })
   .strict();
 export type LegacySecondaryModelRequest = z.infer<typeof legacySecondaryModelRequestSchema>;

packages/agent-gateway/src/routes/subagentModelPolicy.ts

@@ -172,12 +172,13 @@ export function registerSubagentModelPolicyRoutes(app: PolicyRouteHost, core: Sc
         await core.accessor.get(IConfigService).ready;
         const expectedVersion = parseIfMatch(req.headers['if-match']);
         await policyService().set(fromWirePolicy(req.body), expectedVersion);
-        publish(['secondary_model']);
-        requestLog(req)?.info({ changedFields: ['secondary_model'] }, 'subagent model policy updated');
-        respond(typedReply, req.id);
       } catch (error) {
         fail(req as PolicyRequest, typedReply, error);
+        return;
       }
+      publish(['secondary_model']);
+      requestLog(req)?.info({ changedFields: ['secondary_model'] }, 'subagent model policy updated');
+      respond(typedReply, req.id);
     },
   );
   app.put(putRoute.path, putRoute.options, putRoute.handler as unknown as Parameters<PolicyRouteHost['put']>[2]);
@@ -200,12 +201,13 @@ export function registerSubagentModelPolicyRoutes(app: PolicyRouteHost, core: Sc
         await core.accessor.get(IConfigService).ready;
         const expectedVersion = parseIfMatch(req.headers['if-match']);
         await policyService().clear(expectedVersion);
-        publish(['secondary_model']);
-        requestLog(req)?.info({ changedFields: ['secondary_model'] }, 'subagent model policy cleared');
-        respond(typedReply, req.id);
       } catch (error) {
         fail(req as PolicyRequest, typedReply, error);
+        return;
       }
+      publish(['secondary_model']);
+      requestLog(req)?.info({ changedFields: ['secondary_model'] }, 'subagent model policy cleared');
+      respond(typedReply, req.id);
     },
   );
   app.delete(deleteRoute.path, deleteRoute.options, deleteRoute.handler as unknown as Parameters<PolicyRouteHost['delete']>[2]);

packages/agent-gateway/test/config.test.ts

@@ -291,6 +291,21 @@ describe('server-v2 /api/v1/config secondary_model replacement and request atomi
     expect(await diskToml()).not.toContain('force');
   });
 
+  it('accepts legacy secondary_model metadata echoed by GET and drops it on write', async () => {
+    await boot(
+      `${MODELS_TOML}[secondary_model]\ndefault_model = "provider/fast"\nmax_context_size = 1000\ncapabilities = ["thinking"]\n`,
+    );
+    const echoed = (await getConfig()).secondary_model as Record<string, unknown>;
+    expect(echoed).toMatchObject({ defaultModel: 'provider/fast', maxContextSize: 1000 });
+
+    const res = await post({ secondary_model: { ...echoed, default_effort: 'low' } });
+    expect(res.body.code).toBe(0);
+    expect((await getConfig()).secondary_model).toEqual({
+      defaultModel: 'provider/fast',
+      defaultEffort: 'low',
+    });
+  });
+
   it('pool -> default drops the models table', async () => {
     await boot(MODELS_TOML);
     await post({

packages/oauth/src/refreshProviderModels.ts

@@ -319,6 +319,28 @@ function clampDanglingDefault(config: PythinkerConfigShape): void {
   }
 }
 
+// The same refresh can drop a model that `[secondary_model]` binds. A dangling
+// default binding clears the section (subagents inherit the caller model again);
+// a dangling pool entry is pruned so the rest of the pool keeps working. The
+// discovery service validates the section against the refreshed catalog and
+// would otherwise reject the whole provider patch.
+function clampDanglingSecondaryModel(config: PythinkerConfigShape): void {
+  const section = config.secondaryModel;
+  if (section === undefined) return;
+  const bound = section.defaultModel ?? section.model;
+  if (bound !== undefined && readModel(config, bound) === undefined) {
+    config.secondaryModel = undefined;
+    return;
+  }
+  if (section.models === undefined) return;
+  const models = Object.fromEntries(
+    Object.entries(section.models).filter(([alias]) => readModel(config, alias) !== undefined),
+  );
+  if (Object.keys(models).length !== Object.keys(section.models).length) {
+    config.secondaryModel = { ...section, models };
+  }
+}
+
 function clearDefaultThinkingWhenDefaultRemoved(
   config: PythinkerConfigShape,
   previousDefaultModel: string | undefined,
@@ -433,6 +455,7 @@ export async function refreshProviderModels(
       preserveSecondaryModelAliases(config, next);
       restoreDefaultSelection(next, config.defaultModel, config.thinking?.enabled);
       clampDanglingDefault(next);
+      clampDanglingSecondaryModel(next);
       clearDefaultThinkingWhenDefaultRemoved(next, config.defaultModel);
 
       if (providerModelsEqual(config, next, providerId, refreshedAliasKeys)) {
@@ -584,6 +607,7 @@ export async function refreshProviderModels(
       if (changedProviders.length > 0 || hasUnreportedConfigChange) {
         restoreDefaultSelection(next, config.defaultModel, config.thinking?.enabled);
         clampDanglingDefault(next);
+        clampDanglingSecondaryModel(next);
         clearDefaultThinkingWhenDefaultRemoved(next, config.defaultModel);
         for (const providerId of providersToRemoveBeforeSet) {
           await host.removeProvider(providerId);
@@ -695,6 +719,7 @@ export async function refreshProviderModels(
       if (changedProviders.length > 0) {
         restoreDefaultSelection(next, config.defaultModel, config.thinking?.enabled);
         clampDanglingDefault(next);
+        clampDanglingSecondaryModel(next);
         clearDefaultThinkingWhenDefaultRemoved(next, config.defaultModel);
         for (const providerId of providersToRemoveBeforeSet) {
           await host.removeProvider(providerId);

packages/oauth/test/models-dev-refresh.test.ts

@@ -238,7 +238,31 @@ describe('refreshProviderModels modelsDev directory providers', () => {
     expect(patch.providers?.[PROVIDER_ID]).toBeUndefined();
     expect(patch.defaultModel).toBeUndefined();
     expect(patch.thinking).toBeUndefined();
-    expect(patch.secondaryModel).toEqual(base.secondaryModel);
+    expect(patch.secondaryModel).toBeUndefined();
+  });
+
+  it('prunes vanished pool entries from secondary_model but keeps the rest of the pool', async () => {
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(async () => jsonResponse({ 'brand-new-guy': makeDocument()['brand-new-guy'] })),
+    );
+    const base = makeBaseConfig();
+    base.models = {
+      ...base.models,
+      'other/kept': { provider: 'other', model: 'kept' },
+    };
+    base.secondaryModel = {
+      defaultModel: 'other/kept',
+      models: { 'other/kept': '', [`${PROVIDER_ID}/deepseek-v4-flash`]: 'fast' },
+    };
+
+    const { host, calls } = makeHost(base);
+    await refreshProviderModels(host);
+
+    expect(lastPatch(calls).secondaryModel).toEqual({
+      defaultModel: 'other/kept',
+      models: { 'other/kept': '' },
+    });
   });
 
   it('reports a failure without writing when an entry lists no usable models', async () => {