@robhowley/pi-openrouter 0.11.1 → 0.12.0

package/README.md

@@ -1,6 +1,7 @@
 # pi-openrouter
 
 A [Pi](https://pi.dev/) extension for live OpenRouter visibility and environment sync: usage/account TUI overlays, automatic `session_id` tagging, user-scoped model catalog sync, api key management, and local model field overrides.
+A [Pi](https://pi.dev/) extension for live OpenRouter visibility and environment sync: usage/account TUI overlays, automatic session_id tagging, full or free-only model catalog sync, API key management, and local model field overrides.
 
 ## Installation
 
@@ -32,7 +33,9 @@ export OPENROUTER_MANAGEMENT_KEY=sk-or-...
 /openrouter session                  # current OpenRouter session_id
 /openrouter api-key-create           # create an API key (management key required)
 /openrouter models-sync              # sync user-scoped OpenRouter models into Pi
+/openrouter models-sync --free       # sync only openrouter/free plus explicit :free models
 /openrouter models-status            # show model sync/cache status
+/openrouter models-status --free     # show only registered/skipped free models
 /openrouter models-status --skipped  # show skipped model reasons
 /openrouter model-override-set       # set local model field overrides
 /openrouter model-override-list      # list local model field overrides
@@ -47,6 +50,29 @@ export OPENROUTER_MANAGEMENT_KEY=sk-or-...
 
 The sync uses OpenRouter’s authenticated user model catalog, so Pi can see the models available to your account instead of only the default provider list. This intentionally replaces Pi's OpenRouter provider model list with your user-scoped catalog plus OpenRouter's built-in router aliases (`openrouter/auto`, `openrouter/free`, and `openrouter/owl-alpha`). It does not merge in every built-in model unless that model is returned by your OpenRouter account catalog.
 
+### Free models only
+
+To sync only OpenRouter's free route and explicit free model variants:
+
+```shell
+/openrouter models-sync --free
+```
+
+This registers `openrouter/free` plus available `*:free` models.
+
+Use `openrouter/free` for OpenRouter's built-in free model router, or select a specific `:free` model when you want direct control.
+
+Free models are best-effort and rate-limited by OpenRouter. They are useful for experiments and low-stakes work, not guaranteed coding loops.
+
+Example free-only status output:
+
+```text
+OpenRouter models healthy
+28 registered · 3 skipped · free-only catalog · cache age: 4m
+```
+
+Run `/openrouter models-sync` again to restore the full user-scoped catalog.
+
 `/openrouter models-status`
 
 Model count and cache health live here. The Pi footer/status bar does not persistently show `OpenRouter {N} models` anymore.
@@ -55,7 +81,7 @@ Example status output:
 
 ```text
 OpenRouter models healthy
-363 registered · 2 skipped · cache age: 2m
+363 registered · 12 skipped · full catalog · cache age: 4m
 ```
 
 To see why models were skipped:

package/extensions/openrouter/__tests__/commands.test.ts

@@ -49,6 +49,7 @@ const { mocks, overlayConstructorCalls, MockUsageOverlayComponent } = vi.hoisted
       sortKeys: vi.fn(),
       syncModels: vi.fn(),
       getSyncState: vi.fn(),
+      getActiveCatalogState: vi.fn(),
       isSyncEnabled: vi.fn(),
       getSkipReasonsAsync: vi.fn(),
       groupSkipReasons: vi.fn(),
@@ -107,6 +108,7 @@ vi.mock('../account-format.js', () => ({
 vi.mock('../models/sync.js', () => ({
   syncModels: mocks.syncModels,
   getSyncState: mocks.getSyncState,
+  getActiveCatalogState: mocks.getActiveCatalogState,
   isSyncEnabled: mocks.isSyncEnabled,
   getSkipReasonsAsync: mocks.getSkipReasonsAsync,
   groupSkipReasons: mocks.groupSkipReasons,
@@ -210,6 +212,20 @@ function createKeyInventory(
   };
 }
 
+function createActiveCatalogState(overrides: Record<string, unknown> = {}) {
+  const registeredModelIds = ['openrouter/free', 'provider/model-a:free', 'provider/model-b'];
+  return {
+    mode: 'full',
+    registeredModelIds,
+    registeredCount: registeredModelIds.length,
+    skippedDetails: [],
+    skippedCount: 0,
+    source: 'api',
+    cacheAgeMs: 0,
+    ...overrides,
+  };
+}
+
 describe('registerOpenRouterCommands', () => {
   beforeEach(() => {
     vi.resetAllMocks();
@@ -237,9 +253,15 @@ describe('registerOpenRouterCommands', () => {
     mocks.sortKeys.mockImplementation((keys) => keys);
     mocks.syncModels.mockResolvedValue({ success: true, registeredCount: 3, skippedCount: 0 });
     mocks.getSyncState.mockReturnValue(null);
+    mocks.getActiveCatalogState.mockReturnValue(null);
     mocks.isSyncEnabled.mockReturnValue(true);
     mocks.getSkipReasonsAsync.mockResolvedValue([]);
-    mocks.groupSkipReasons.mockReturnValue({});
+    mocks.groupSkipReasons.mockImplementation((reasons: Array<{ reason: string }>) =>
+      reasons.reduce<Record<string, number>>((counts, reason) => {
+        counts[reason.reason] = (counts[reason.reason] || 0) + 1;
+        return counts;
+      }, {}),
+    );
     mocks.loadCache.mockResolvedValue(null);
     mocks.getCacheAgeMs.mockReturnValue(60000);
     mocks.formatDuration.mockReturnValue('1 minute');
@@ -485,7 +507,7 @@ describe('registerOpenRouterCommands', () => {
     );
   });
 
-  it('keeps models-sync success notifications unchanged', async () => {
+  it('routes full models-sync through explicit full mode and updated success copy', async () => {
     const { commands, pi } = createMockPi();
     const ctx = createMockContext();
 
@@ -498,36 +520,97 @@ describe('registerOpenRouterCommands', () => {
     registerOpenRouterCommands(pi as any);
     await commands.get('openrouter').handler('models-sync', ctx);
 
-    expect(mocks.syncModels).toHaveBeenCalledWith(ctx);
+    expect(mocks.syncModels).toHaveBeenCalledWith(ctx, 'full');
     expect(ctx.ui.notify).toHaveBeenCalledWith(
-      'OpenRouter models synced\n9 registered · 2 skipped · cache updated',
+      'OpenRouter models synced\n9 registered · 2 skipped · cache age: 0m',
       'info',
     );
   });
 
-  it('shows grouped skipped-details hints once per reason', async () => {
+  it('threads --free through models-sync and shows the free-only sync note', async () => {
     const { commands, pi } = createMockPi();
     const ctx = createMockContext();
 
-    mocks.getSyncState.mockReturnValue({ success: true, registeredCount: 7 });
-    mocks.getSkipReasonsAsync.mockResolvedValue([
-      {
-        id: 'provider/a',
-        reason: 'missing context window',
-        hint: "Add a local contextWindow override with '/openrouter model-override-set <model-id> contextWindow=<tokens>' if the model's limit is known.",
-      },
-      { id: 'provider/b', reason: 'missing context window' },
-    ]);
-    mocks.groupSkipReasons.mockReturnValue({ 'missing context window': 2 });
+    mocks.syncModels.mockResolvedValue({
+      success: true,
+      registeredCount: 28,
+      skippedCount: 3,
+    });
+
+    registerOpenRouterCommands(pi as any);
+    await commands.get('openrouter').handler('models-sync --free', ctx);
+
+    expect(mocks.syncModels).toHaveBeenCalledWith(ctx, 'free-only');
+    expect(ctx.ui.notify).toHaveBeenCalledWith(
+      "OpenRouter free models synced\n28 registered · 3 skipped · cache age: 0m\n\nSelect openrouter/free for OpenRouter's built-in free router, or choose a specific :free model.",
+      'info',
+    );
+  });
+
+  it('shows the free-empty no-op copy exactly', async () => {
+    const { commands, pi } = createMockPi();
+    const ctx = createMockContext();
+
+    mocks.syncModels.mockResolvedValue({
+      success: false,
+      outcome: 'no-change',
+      requestedMode: 'free-only',
+      catalogMode: 'full',
+      registeredCount: 0,
+      skippedCount: 0,
+      source: 'api',
+      cacheUpdated: false,
+      cacheAgeMs: 0,
+      error: null,
+    });
+
+    registerOpenRouterCommands(pi as any);
+    await commands.get('openrouter').handler('models-sync --free', ctx);
+
+    expect(mocks.syncModels).toHaveBeenCalledWith(ctx, 'free-only');
+    expect(ctx.ui.notify).toHaveBeenCalledWith(
+      'No free OpenRouter models found\nNo model catalog changed',
+      'info',
+    );
+  });
+
+  it('shows grouped skipped-details hints once per reason for models-status --free in free-only mode', async () => {
+    const { commands, pi } = createMockPi();
+    const ctx = createMockContext();
+
+    mocks.getActiveCatalogState.mockReturnValue(
+      createActiveCatalogState({
+        mode: 'free-only',
+        registeredModelIds: [
+          'openrouter/free',
+          'provider/a:free',
+          'provider/b:free',
+          'provider/c:free',
+          'provider/d:free',
+          'provider/e:free',
+          'provider/f:free',
+        ],
+        registeredCount: 7,
+        skippedDetails: [
+          {
+            id: 'provider/a:free',
+            reason: 'missing context window',
+            hint: "Add a local contextWindow override with '/openrouter model-override-set <model-id> contextWindow=<tokens>' if the model's limit is known.",
+          },
+          { id: 'provider/b:free', reason: 'missing context window' },
+        ],
+        skippedCount: 2,
+      }),
+    );
     mocks.loadCache.mockResolvedValue({ models: [], timestamp: Date.now() - 60000 });
     mocks.getCacheAgeMs.mockReturnValue(60000);
-    mocks.formatDuration.mockReturnValue('1 minute');
+    mocks.formatDuration.mockReturnValue('1m');
 
     registerOpenRouterCommands(pi as any);
-    await commands.get('openrouter').handler('models-status --skipped', ctx);
+    await commands.get('openrouter').handler('models-status --free --skipped', ctx);
 
     expect(ctx.ui.notify).toHaveBeenCalledWith(
-      "OpenRouter models healthy\n7 registered · 2 skipped · cache age: 1 minute\n\nOpenRouter skipped models: 2\n\n2 missing context window\n  suggestion: Add a local contextWindow override with '/openrouter model-override-set <model-id> contextWindow=<tokens>' if the model's limit is known.\n- provider/a\n- provider/b\n",
+      "OpenRouter models healthy\n7 registered · 2 skipped · free-only catalog · cache age: 1m\n\nOpenRouter skipped models: 2\n\n2 missing context window\n  suggestion: Add a local contextWindow override with '/openrouter model-override-set <model-id> contextWindow=<tokens>' if the model's limit is known.\n- provider/a:free\n- provider/b:free\n",
       'info',
     );
   });
@@ -656,10 +739,17 @@ describe('registerOpenRouterCommands', () => {
   });
 
   describe('models-sync failure paths', () => {
-    it('shows cache-backed failure with warning level and cache metadata', async () => {
+    it('shows mode-aware cache-backed refresh failure copy', async () => {
       const { commands, pi } = createMockPi();
       const ctx = createMockContext();
 
+      mocks.getActiveCatalogState.mockReturnValue(
+        createActiveCatalogState({
+          mode: 'free-only',
+          registeredModelIds: ['openrouter/free', 'provider/a:free'],
+          registeredCount: 2,
+        }),
+      );
       mocks.syncModels.mockResolvedValue({
         success: false,
         source: 'cache',
@@ -667,13 +757,13 @@ describe('registerOpenRouterCommands', () => {
         cacheAgeMs: 300000,
         error: 'API timeout',
       });
-      mocks.formatDuration.mockReturnValue('5 minutes');
+      mocks.formatDuration.mockReturnValue('5m');
 
       registerOpenRouterCommands(pi as any);
       await commands.get('openrouter').handler('models-sync', ctx);
 
       expect(ctx.ui.notify).toHaveBeenCalledWith(
-        'OpenRouter models sync failed\n5 registered from cache\nCache age: 5 minutes\nError: API timeout',
+        'OpenRouter models refresh failed\nUsing last successful free-only catalog · cache age: 5m',
         'warning',
       );
     });
@@ -730,34 +820,42 @@ describe('registerOpenRouterCommands', () => {
       );
     });
 
-    it('shows cache-backed failure warning with skip details when --skipped flag present', async () => {
+    it('filters active full catalogs for models-status --skipped --free regardless of flag order', async () => {
       const { commands, pi } = createMockPi();
       const ctx = createMockContext();
 
-      mocks.getSyncState.mockReturnValue({
-        success: false,
-        source: 'cache',
-        registeredCount: 8,
-        error: 'Auth expired',
-      });
-      mocks.getSkipReasonsAsync.mockResolvedValue([
-        { id: 'test/model', reason: 'missing pricing' },
-      ]);
-      mocks.groupSkipReasons.mockReturnValue({ 'missing pricing': 1 });
-      mocks.loadCache.mockResolvedValue({ models: [], timestamp: Date.now() - 180000 });
-      mocks.getCacheAgeMs.mockReturnValue(180000);
-      mocks.formatDuration.mockReturnValue('3 minutes');
+      mocks.getActiveCatalogState.mockReturnValue(
+        createActiveCatalogState({
+          mode: 'full',
+          registeredModelIds: [
+            'openrouter/free',
+            'provider/free-a:free',
+            'provider/paid-a',
+            'provider/paid-b',
+          ],
+          registeredCount: 4,
+          skippedDetails: [
+            {
+              id: 'provider/free-b:free',
+              reason: 'missing context window',
+              hint: "Add a local contextWindow override with '/openrouter model-override-set <model-id> contextWindow=<tokens>' if the model's limit is known.",
+            },
+            { id: 'provider/paid-c', reason: 'missing pricing' },
+          ],
+          skippedCount: 2,
+        }),
+      );
+      mocks.loadCache.mockResolvedValue({ models: [], timestamp: Date.now() - 240000 });
+      mocks.getCacheAgeMs.mockReturnValue(240000);
+      mocks.formatDuration.mockReturnValue('4m');
 
       registerOpenRouterCommands(pi as any);
-      await commands.get('openrouter').handler('models-status --skipped', ctx);
-
-      const notifyCall = ctx.ui.notify.mock.calls[0];
-      expect(notifyCall[1]).toBe('warning');
-      expect(notifyCall[0]).toContain('OpenRouter models cached');
-      expect(notifyCall[0]).toContain('8 registered · 1 skipped');
-      expect(notifyCall[0]).toContain('Cache age: 3 minutes');
-      expect(notifyCall[0]).toContain('Error: Auth expired');
-      expect(notifyCall[0]).toContain('missing pricing');
+      await commands.get('openrouter').handler('models-status --free --skipped', ctx);
+
+      expect(ctx.ui.notify).toHaveBeenCalledWith(
+        "OpenRouter models healthy\n2 registered · 1 skipped · full catalog · cache age: 4m\n\nOpenRouter skipped models: 1\n\n1 missing context window\n  suggestion: Add a local contextWindow override with '/openrouter model-override-set <model-id> contextWindow=<tokens>' if the model's limit is known.\n- provider/free-b:free\n",
+        'info',
+      );
     });
 
     it('shows broken error when state exists but not from cache and not success', async () => {

package/extensions/openrouter/__tests__/fixtures.ts

@@ -66,6 +66,7 @@ export function createValidModel(overrides?: Partial<OpenRouterModel>): OpenRout
  */
 export function createMockCache(overrides: Partial<ModelsCache> = {}): ModelsCache {
   return {
+    catalogMode: 'full',
     models: [createValidModel()],
     timestamp: Date.now() - 1000, // 1 second ago
     ...overrides,

package/extensions/openrouter/__tests__/hooks.test.ts

@@ -8,8 +8,10 @@ const mocks = vi.hoisted(() => ({
   getCacheAgeMs: vi.fn(),
   formatDuration: vi.fn(),
   mapOpenRouterModels: vi.fn(),
+  filterModelsForCatalogMode: vi.fn(),
   includeBuiltinRouterModels: vi.fn(),
   isSyncEnabled: vi.fn(),
+  setActiveCatalogState: vi.fn(),
   loadOpenRouterStatusBar: vi.fn(),
 }));
 
@@ -37,8 +39,10 @@ vi.mock('../models/mapper.js', () => ({
 }));
 
 vi.mock('../models/sync.js', () => ({
+  filterModelsForCatalogMode: mocks.filterModelsForCatalogMode,
   includeBuiltinRouterModels: mocks.includeBuiltinRouterModels,
   isSyncEnabled: mocks.isSyncEnabled,
+  setActiveCatalogState: mocks.setActiveCatalogState,
 }));
 
 vi.mock('../status-bar.js', () => ({
@@ -97,7 +101,12 @@ describe('openrouter hooks', () => {
     mocks.loadCache.mockResolvedValue(null);
     mocks.getCacheAgeMs.mockReturnValue(60000);
     mocks.formatDuration.mockReturnValue('1 minute');
-    mocks.mapOpenRouterModels.mockResolvedValue({ configs: [{ id: 'model-a' }] });
+    mocks.mapOpenRouterModels.mockResolvedValue({
+      configs: [{ id: 'model-a' }],
+      skipped: 0,
+      skippedDetails: [],
+    });
+    mocks.filterModelsForCatalogMode.mockImplementation((models: Array<{ id: string }>) => models);
     mocks.includeBuiltinRouterModels.mockReturnValue([{ id: 'model-a' }, { id: 'router' }]);
     mocks.isSyncEnabled.mockReturnValue(true);
     mocks.loadOpenRouterStatusBar.mockResolvedValue({ kind: 'empty' });
@@ -107,17 +116,24 @@ describe('openrouter hooks', () => {
     vi.useRealTimers();
   });
 
-  it('loads cached startup models and preserves startup cache info', async () => {
+  it('loads cached startup models, respects cached mode, and seeds active catalog state', async () => {
     const { pi } = createMockPi();
     const { loadStartupCacheState } = await loadHooksModule();
 
     mocks.loadCache.mockResolvedValue({
+      catalogMode: 'full',
       models: [{ id: 'cached/model-a' }],
+      skippedDetails: [],
       timestamp: Date.now() - 60000,
     });
 
     const startupState = await loadStartupCacheState(pi as any);
 
+    expect(mocks.filterModelsForCatalogMode).toHaveBeenCalledWith(
+      [{ id: 'cached/model-a' }],
+      'full',
+    );
+    expect(mocks.includeBuiltinRouterModels).toHaveBeenCalledWith([{ id: 'model-a' }], 'full');
     expect(pi.registerProvider).toHaveBeenCalledWith('openrouter', {
       baseUrl: 'https://openrouter.ai/api/v1',
       apiKey: 'OPENROUTER_API_KEY',
@@ -125,6 +141,62 @@ describe('openrouter hooks', () => {
       models: [{ id: 'model-a' }, { id: 'router' }],
       authHeader: true,
     });
+    expect(mocks.setActiveCatalogState).toHaveBeenCalledWith({
+      mode: 'full',
+      registeredModelIds: ['model-a', 'router'],
+      registeredCount: 2,
+      skippedCount: 0,
+      skippedDetails: [],
+      source: 'cache',
+      cacheAgeMs: 60000,
+    });
+    expect(startupState).toEqual({
+      info: {
+        count: 2,
+        age: '1 minute',
+      },
+    });
+  });
+
+  it('loads cached free-only startup models with free-only router injection only', async () => {
+    const { pi } = createMockPi();
+    const { loadStartupCacheState } = await loadHooksModule();
+
+    mocks.loadCache.mockResolvedValue({
+      catalogMode: 'free-only',
+      models: [{ id: 'cached/model-a:free' }],
+      skippedDetails: [{ id: 'bad/model:free', reason: 'missing context window' }],
+      timestamp: Date.now() - 60000,
+    });
+    mocks.mapOpenRouterModels.mockResolvedValue({
+      configs: [{ id: 'cached/model-a:free' }],
+      skipped: 1,
+      skippedDetails: [{ id: 'bad/model:free', reason: 'missing context window' }],
+    });
+    mocks.includeBuiltinRouterModels.mockReturnValue([
+      { id: 'cached/model-a:free' },
+      { id: 'openrouter/free' },
+    ]);
+
+    const startupState = await loadStartupCacheState(pi as any);
+
+    expect(mocks.filterModelsForCatalogMode).toHaveBeenCalledWith(
+      [{ id: 'cached/model-a:free' }],
+      'free-only',
+    );
+    expect(mocks.includeBuiltinRouterModels).toHaveBeenCalledWith(
+      [{ id: 'cached/model-a:free' }],
+      'free-only',
+    );
+    expect(mocks.setActiveCatalogState).toHaveBeenCalledWith({
+      mode: 'free-only',
+      registeredModelIds: ['cached/model-a:free', 'openrouter/free'],
+      registeredCount: 2,
+      skippedCount: 1,
+      skippedDetails: [{ id: 'bad/model:free', reason: 'missing context window' }],
+      source: 'cache',
+      cacheAgeMs: 60000,
+    });
     expect(startupState).toEqual({
       info: {
         count: 2,
@@ -138,14 +210,21 @@ describe('openrouter hooks', () => {
     const { loadStartupCacheState } = await loadHooksModule();
 
     mocks.loadCache.mockResolvedValue({
-      models: [{ id: 'cached/model-a' }],
+      catalogMode: 'free-only',
+      models: [{ id: 'cached/model-a:free' }],
+      skippedDetails: [],
       timestamp: Date.now() - 60000,
     });
     mocks.mapOpenRouterModels.mockRejectedValue(new Error('mapper failed'));
 
     const startupState = await loadStartupCacheState(pi as any);
 
+    expect(mocks.filterModelsForCatalogMode).toHaveBeenCalledWith(
+      [{ id: 'cached/model-a:free' }],
+      'free-only',
+    );
     expect(pi.registerProvider).not.toHaveBeenCalled();
+    expect(mocks.setActiveCatalogState).not.toHaveBeenCalled();
     expect(startupState).toEqual({
       warning: 'OpenRouter: cached models found but failed to register: mapper failed',
     });

package/extensions/openrouter/commands.ts

@@ -22,6 +22,7 @@ import type { CurrentKeyRelation, KeyInfo, RollupStatus } from './account-types.
 import {
   syncModels,
   getSyncState,
+  getActiveCatalogState,
   isSyncEnabled,
   getSkipReasonsAsync,
   groupSkipReasons,
@@ -29,7 +30,7 @@ import {
 import { loadCache, getCacheAgeMs, formatDuration } from './models/cache.js';
 import { loadModelOverrides } from './models/overrides.js';
 import { getSkipReasonHint } from './models/skip-hints.js';
-import type { ModelOverridesFile } from './models/types.js';
+import type { CatalogMode, ModelOverridesFile, SkipReason, SyncResult } from './models/types.js';
 import {
   handleModelOverrideSet,
   handleModelOverrideClear,
@@ -111,7 +112,7 @@ async function handleOpenRouterCommand(args: string, ctx: ExtensionContext): Pro
       break;
     }
     case 'models-sync': {
-      await handleModelsSyncCommand(ctx);
+      await handleModelsSyncCommand(ctx, flags);
       break;
     }
     case 'models-status': {
@@ -176,7 +177,34 @@ function notifyCurrentSession(ctx: {
   ctx.ui.notify(`OpenRouter session_id\n${getCurrentSessionId(ctx)}`, 'info');
 }
 
-async function handleModelsSyncCommand(ctx: ExtensionContext): Promise<void> {
+function getRequestedCatalogMode(flags: Record<string, boolean>): CatalogMode {
+  return flags['--free'] ? 'free-only' : 'full';
+}
+
+function getCatalogModeLabel(mode: CatalogMode): string {
+  return mode === 'free-only' ? 'free-only catalog' : 'full catalog';
+}
+
+function resolveCatalogMode(result: SyncResult, fallbackMode: CatalogMode): CatalogMode {
+  return result.catalogMode ?? fallbackMode;
+}
+
+function isNoCatalogChange(result: SyncResult): boolean {
+  return result.outcome === 'no-change';
+}
+
+function isFreeCatalogModelId(id: string): boolean {
+  return id === 'openrouter/free' || id.endsWith(':free');
+}
+
+function filterFreeSkipReasons(skipReasons: SkipReason[]): SkipReason[] {
+  return skipReasons.filter((item) => isFreeCatalogModelId(item.id));
+}
+
+async function handleModelsSyncCommand(
+  ctx: ExtensionContext,
+  flags: Record<string, boolean>,
+): Promise<void> {
   if (!isSyncEnabled()) {
     ctx.ui.notify(
       'OpenRouter model sync is disabled. Set openrouterModelSync: true in ~/.pi/agent/settings.json to enable.',
@@ -185,19 +213,39 @@ async function handleModelsSyncCommand(ctx: ExtensionContext): Promise<void> {
     return;
   }
 
-  const result = await syncModels(ctx);
+  const requestedMode = getRequestedCatalogMode(flags);
+  const result = await syncModels(ctx, requestedMode);
+
+  if (requestedMode === 'free-only' && isNoCatalogChange(result)) {
+    ctx.ui.notify('No free OpenRouter models found\nNo model catalog changed', 'info');
+    return;
+  }
+
   if (!result.success) {
-    let message = '';
     if (result.source === 'cache') {
-      message = `OpenRouter models sync failed\n${result.registeredCount} registered from cache\nCache age: ${formatDuration(result.cacheAgeMs)}\nError: ${result.error}`;
-    } else {
-      message = `OpenRouter models unavailable\n0 registered\nError: ${result.error}`;
+      const activeCatalogState = getActiveCatalogState();
+      const activeCatalogMode = resolveCatalogMode(
+        result,
+        activeCatalogState?.mode ?? requestedMode,
+      );
+      ctx.ui.notify(
+        `OpenRouter models refresh failed\nUsing last successful ${getCatalogModeLabel(activeCatalogMode)} · cache age: ${formatDuration(result.cacheAgeMs)}`,
+        'warning',
+      );
+      return;
     }
-    ctx.ui.notify(message, result.source === 'cache' ? 'warning' : 'error');
+
+    ctx.ui.notify(`OpenRouter models unavailable\n0 registered\nError: ${result.error}`, 'error');
     return;
   }
 
-  const message = `OpenRouter models synced\n${result.registeredCount} registered${result.skippedCount > 0 ? ` · ${result.skippedCount} skipped` : ''} · cache updated`;
+  let message = `${requestedMode === 'free-only' ? 'OpenRouter free models synced' : 'OpenRouter models synced'}\n${result.registeredCount} registered${result.skippedCount > 0 ? ` · ${result.skippedCount} skipped` : ''} · cache age: 0m`;
+
+  if (requestedMode === 'free-only') {
+    message +=
+      "\n\nSelect openrouter/free for OpenRouter's built-in free router, or choose a specific :free model.";
+  }
+
   ctx.ui.notify(message, 'info');
 }
 
@@ -206,12 +254,42 @@ async function handleModelsStatusCommand(
   flags: Record<string, boolean>,
 ): Promise<void> {
   const state = getSyncState();
-  const skipReasons = await getSkipReasonsAsync();
-  const groupedReasons = groupSkipReasons(skipReasons);
+  const activeCatalogState = getActiveCatalogState();
 
   const cache = await loadCache();
   const cacheAgeMs = cache ? getCacheAgeMs(cache) : null;
 
+  if (activeCatalogState) {
+    const activeSkipReasons = activeCatalogState.skippedDetails;
+    const visibleSkipReasons = flags['--free']
+      ? filterFreeSkipReasons(activeSkipReasons)
+      : activeSkipReasons;
+    const visibleSkipCount = flags['--free']
+      ? visibleSkipReasons.length
+      : activeCatalogState.skippedCount;
+    const visibleRegisteredIds = flags['--free']
+      ? (activeCatalogState.registeredModelIds ?? []).filter(isFreeCatalogModelId)
+      : (activeCatalogState.registeredModelIds ?? []);
+    const visibleRegisteredCount = flags['--free']
+      ? visibleRegisteredIds.length
+      : activeCatalogState.registeredCount;
+    const groupedReasons = flags['--skipped'] ? groupSkipReasons(visibleSkipReasons) : {};
+    const visibleCacheAgeMs = cacheAgeMs ?? activeCatalogState.cacheAgeMs;
+
+    const statusLabel = activeCatalogState.source === 'cache' ? 'cached' : 'healthy';
+    let message = `OpenRouter models ${statusLabel}\n${visibleRegisteredCount} registered${visibleSkipCount > 0 ? ` · ${visibleSkipCount} skipped` : ''} · ${getCatalogModeLabel(activeCatalogState.mode)} · cache age: ${formatDuration(visibleCacheAgeMs)}`;
+
+    if (flags['--skipped']) {
+      message += formatSkippedDetails(visibleSkipCount, groupedReasons, visibleSkipReasons);
+    }
+    ctx.ui.notify(message, 'info');
+    return;
+  }
+
+  const skipReasons = await getSkipReasonsAsync();
+  const visibleSkipReasons = flags['--free'] ? filterFreeSkipReasons(skipReasons) : skipReasons;
+  const groupedReasons = flags['--skipped'] ? groupSkipReasons(visibleSkipReasons) : {};
+
   if (!state && !cache) {
     ctx.ui.notify('OpenRouter models: not synced', 'error');
     return;
@@ -225,22 +303,22 @@ async function handleModelsStatusCommand(
   }
 
   if (state?.success) {
-    const skipCount = skipReasons.length;
+    const skipCount = visibleSkipReasons.length;
     let message = `OpenRouter models healthy\n${state.registeredCount} registered${skipCount > 0 ? ` · ${skipCount} skipped` : ''} · cache age: ${formatDuration(cacheAgeMs)}`;
 
     if (flags['--skipped']) {
-      message += formatSkippedDetails(skipCount, groupedReasons, skipReasons);
+      message += formatSkippedDetails(skipCount, groupedReasons, visibleSkipReasons);
     }
     ctx.ui.notify(message, 'info');
     return;
   }
 
   if (state?.source === 'cache') {
-    const skipCount = skipReasons.length;
+    const skipCount = visibleSkipReasons.length;
     let message = `OpenRouter models cached\n${state.registeredCount} registered${skipCount > 0 ? ` · ${skipCount} skipped` : ''}\nCache age: ${formatDuration(cacheAgeMs)}\nError: ${state.error}`;
 
     if (flags['--skipped']) {
-      message += formatSkippedDetails(skipCount, groupedReasons, skipReasons);
+      message += formatSkippedDetails(skipCount, groupedReasons, visibleSkipReasons);
     }
     ctx.ui.notify(message, 'warning');
     return;
@@ -398,7 +476,7 @@ function getErrorMessage(error: unknown): string {
 function formatSkippedDetails(
   skipCount: number,
   groupedReasons: Record<string, number>,
-  skipReasons: Array<{ id: string; reason: string; hint?: string }>,
+  skipReasons: SkipReason[],
 ): string {
   if (skipCount === 0) {
     return '\n\nNo skipped models';