@polderlabs/bizar 6.2.2 → 6.2.4

package/cli/commands/setup-provider.test.mjs

@@ -1,11 +1,16 @@
 /**
  * cli/commands/setup-provider.test.mjs
  *
- * v6.2.2 — Unit tests for the setup-provider subcommand.
+ * v6.2.3 — Unit tests for the setup-provider subcommand.
  *
- * Exercises the pure helpers (`buildProviderBlock`, `parseFlags`)
- * and the filesystem mutations (`applyProviderBlock`, `removeProvider`)
- * with a mocked CLINE_DIR.
+ * v6.2.3 changed the storage backend from `~/.cline/cline.json` to
+ * `~/.cline/data/settings/providers.json` (the file the Cline CLI
+ * and kanban mode actually read). The default providerId changed
+ * from `9router` to `litellm` (a real entry in Cline's catalog).
+ *
+ * Exercises the pure helpers (`buildProviderBlock`, `parseFlags`,
+ * `OPENAI_COMPATIBLE_PROVIDERS`) and the filesystem mutations
+ * (`applyProviderBlock`, `removeProvider`) with a mocked CLINE_DIR.
  */
 import { test, describe, beforeEach, afterEach } from 'node:test';
 import assert from 'node:assert/strict';
@@ -19,27 +24,41 @@ const {
   removeProvider,
   listGatewayModels,
   parseFlags,
+  OPENAI_COMPATIBLE_PROVIDERS,
 } = await import('./setup-provider.mjs');
 
 const ORIG_CLINE_DIR = process.env.CLINE_DIR;
+const ORIG_DATA_DIR = process.env.CLINE_DATA_DIR;
+const ORIG_PROVIDER_PATH = process.env.CLINE_PROVIDER_SETTINGS_PATH;
 let workDir;
 
 function freshWorkDir() {
   workDir = mkdtempSync(join(tmpdir(), 'bizar-setup-provider-'));
+  // CLINE_DIR is the *base* dir (e.g. ~/.cline). The settings file
+  // lives at `${CLINE_DIR}/data/settings/providers.json`. Mocking
+  // CLINE_DIR is the easiest way to redirect the whole tree.
   process.env.CLINE_DIR = workDir;
+  // Clear overrides that could change the resolution path.
+  delete process.env.CLINE_DATA_DIR;
+  delete process.env.CLINE_PROVIDER_SETTINGS_PATH;
   return workDir;
 }
 
-function makeFakeClineJson(root, body = {}) {
+function settingsFile() {
+  return join(workDir, 'data', 'settings', 'providers.json');
+}
+
+function makeFakeSettings(root, body = {}) {
   const cfg = {
-    $schema: 'https://docs.cline.bot/config.json',
-    plugin: [],
-    default_agent: 'odin',
-    permission: 'allow',
-    snapshot: false,
+    version: 1,
+    providers: {},
+    lastUsedProvider: 'litellm',
     ...body,
   };
-  writeFileSync(join(root, 'cline.json'), JSON.stringify(cfg, null, 2));
+  const file = join(root, 'data', 'settings', 'providers.json');
+  mkdirSync(join(root, 'data', 'settings'), { recursive: true });
+  writeFileSync(file, JSON.stringify(cfg, null, 2));
+  return file;
 }
 
 beforeEach(() => {
@@ -50,137 +69,215 @@ afterEach(() => {
   if (workDir && existsSync(workDir)) rmSync(workDir, { recursive: true, force: true });
   if (ORIG_CLINE_DIR === undefined) delete process.env.CLINE_DIR;
   else process.env.CLINE_DIR = ORIG_CLINE_DIR;
+  if (ORIG_DATA_DIR === undefined) delete process.env.CLINE_DATA_DIR;
+  else process.env.CLINE_DATA_DIR = ORIG_DATA_DIR;
+  if (ORIG_PROVIDER_PATH === undefined) delete process.env.CLINE_PROVIDER_SETTINGS_PATH;
+  else process.env.CLINE_PROVIDER_SETTINGS_PATH = ORIG_PROVIDER_PATH;
+});
+
+describe('OPENAI_COMPATIBLE_PROVIDERS', () => {
+  test('includes litellm (the new v6.2.3 default)', () => {
+    assert.ok(OPENAI_COMPATIBLE_PROVIDERS.includes('litellm'),
+      'litellm must be the canonical openai-compatible providerId');
+  });
+  test('does NOT include the fake "openai-compatible" or "9router" IDs', () => {
+    assert.equal(OPENAI_COMPATIBLE_PROVIDERS.includes('openai-compatible'), false,
+      'openai-compatible is a family, not a valid providerId');
+    assert.equal(OPENAI_COMPATIBLE_PROVIDERS.includes('9router'), false,
+      '9router is not a built-in Cline providerId (would fail in kanban)');
+  });
 });
 
 describe('buildProviderBlock()', () => {
-  test('emits a baseUrl, apiKey, and bare modelIds', () => {
+  test('emits a Cline-settings-shaped block (version 1 + settings + updatedAt)', () => {
     const block = buildProviderBlock({
-      name: '9router',
+      name: 'litellm',
       gateway: 'http://localhost:20128/v1',
       apiKey: 'sk-test',
-      models: ['minimax/MiniMax-M3', 'minimax/MiniMax-M2.7'],
+      model: 'minimaxcustom/MiniMax-M3',
     });
-    assert.ok(block['9router']);
-    assert.equal(block['9router'].baseUrl, 'http://localhost:20128/v1');
-    assert.equal(block['9router'].apiKey, 'sk-test');
-    assert.deepEqual(Object.keys(block['9router'].models), ['minimax/MiniMax-M3', 'minimax/MiniMax-M2.7']);
+    assert.ok(block.settings);
+    assert.equal(block.settings.provider, 'litellm');
+    assert.equal(block.settings.model, 'minimaxcustom/MiniMax-M3');
+    assert.equal(block.settings.apiKey, 'sk-test');
+    assert.equal(block.settings.baseUrl, 'http://localhost:20128/v1');
+    assert.ok(block.settings.reasoning);
+    assert.equal(block.settings.reasoning.enabled, false);
+    assert.ok(block.updatedAt);
+    assert.match(block.updatedAt, /^\d{4}-\d{2}-\d{2}T/);
+    assert.equal(block.tokenSource, 'manual');
   });
 
   test('wraps env-var-style keys in ${env:...}', () => {
     const block = buildProviderBlock({
-      name: '9router',
+      name: 'litellm',
       gateway: 'http://localhost:20128/v1',
       apiKey: 'NINEROUTER_KEY',
-      models: ['minimax/MiniMax-M3'],
+      model: 'm1',
     });
-    assert.equal(block['9router'].apiKey, '${env:NINEROUTER_KEY}');
+    assert.equal(block.settings.apiKey, '${env:NINEROUTER_KEY}');
   });
 
-  test('keeps literal keys as-is when not env-var shaped', () => {
+  test('sets reasoning.enabled=true when reason=true', () => {
     const block = buildProviderBlock({
-      name: 'custom',
-      gateway: 'https://x.example/v1',
-      apiKey: 'sk-abc-123',
-      models: ['m1'],
+      name: 'litellm', gateway: 'http://x', apiKey: 'k', model: 'm', reason: true,
     });
-    assert.equal(block['custom'].apiKey, 'sk-abc-123');
+    assert.equal(block.settings.reasoning.enabled, true);
   });
 });
 
 describe('applyProviderBlock()', () => {
-  test('writes a new provider to ~/.cline/cline.json', () => {
-    makeFakeClineJson(workDir);
-    const block = buildProviderBlock({
-      name: '9router',
-      gateway: 'http://localhost:20128/v1',
-      apiKey: 'sk-test',
-      models: ['minimax/MiniMax-M3'],
+  test('writes to ${CLINE_DIR}/data/settings/providers.json (NOT ~/.cline/cline.json)', () => {
+    const body = buildProviderBlock({
+      name: 'litellm', gateway: 'http://localhost:20128/v1',
+      apiKey: 'sk-test', model: 'minimaxcustom/MiniMax-M3',
     });
-    const r = applyProviderBlock(block);
-    assert.equal(r.name, '9router');
-    const cfg = JSON.parse(readFileSync(join(workDir, 'cline.json'), 'utf8'));
-    assert.ok(cfg.provider['9router']);
-    assert.equal(cfg.provider['9router'].baseUrl, 'http://localhost:20128/v1');
+    const r = applyProviderBlock('litellm', body);
+    const expected = settingsFile();
+    assert.equal(r.path, expected, 'must write to the Cline settings file');
+    assert.ok(existsSync(expected));
   });
 
-  test('preserves other provider entries when adding a new one', () => {
-    makeFakeClineJson(workDir, {
-      provider: { existing: { baseUrl: 'https://a', apiKey: 'k', models: { m: {} } } },
+  test('bootstraps the settings file when it does not exist', () => {
+    // No makeFakeSettings call.
+    const body = buildProviderBlock({
+      name: 'litellm', gateway: 'http://x', apiKey: 'k', model: 'm',
     });
-    const block = buildProviderBlock({
-      name: '9router',
-      gateway: 'http://localhost:20128/v1',
-      apiKey: 'sk-test',
-      models: ['minimax/MiniMax-M3'],
-    });
-    applyProviderBlock(block);
-    const cfg = JSON.parse(readFileSync(join(workDir, 'cline.json'), 'utf8'));
-    assert.ok(cfg.provider.existing, 'existing provider preserved');
-    assert.ok(cfg.provider['9router'], 'new provider added');
+    const r = applyProviderBlock('litellm', body);
+    assert.ok(existsSync(r.path));
+    const cfg = JSON.parse(readFileSync(r.path, 'utf8'));
+    assert.equal(cfg.version, 1);
+    assert.equal(cfg.lastUsedProvider, 'litellm');
+    assert.ok(cfg.providers.litellm);
   });
 
-  test('overwrites an existing provider with the same name', () => {
-    makeFakeClineJson(workDir, {
-      provider: { '9router': { baseUrl: 'https://old', apiKey: 'old', models: {} } },
+  test('preserves other provider entries when adding a new one', () => {
+    makeFakeSettings(workDir, {
+      providers: { ollama: { settings: { provider: 'ollama', model: 'llama3' } } },
     });
-    const block = buildProviderBlock({
-      name: '9router',
-      gateway: 'http://localhost:20128/v1',
-      apiKey: 'new',
-      models: ['minimax/MiniMax-M3'],
+    const body = buildProviderBlock({
+      name: 'litellm', gateway: 'http://x', apiKey: 'k', model: 'm',
     });
-    applyProviderBlock(block);
-    const cfg = JSON.parse(readFileSync(join(workDir, 'cline.json'), 'utf8'));
-    assert.equal(cfg.provider['9router'].baseUrl, 'http://localhost:20128/v1');
-    assert.equal(cfg.provider['9router'].apiKey, 'new');
-    assert.ok(cfg.provider['9router'].models['minimax/MiniMax-M3']);
+    applyProviderBlock('litellm', body);
+    const cfg = JSON.parse(readFileSync(settingsFile(), 'utf8'));
+    assert.ok(cfg.providers.ollama, 'existing provider preserved');
+    assert.ok(cfg.providers.litellm, 'new provider added');
   });
 
-  test('throws when cline.json is missing', () => {
-    // No makeFakeClineJson call
-    const block = buildProviderBlock({
-      name: '9router',
-      gateway: 'http://localhost:20128/v1',
-      apiKey: 'sk-test',
-      models: ['minimax/MiniMax-M3'],
+  test('overwrites an existing provider with the same name', () => {
+    makeFakeSettings(workDir, {
+      providers: { litellm: { settings: { provider: 'litellm', baseUrl: 'https://old', model: 'old' } } },
     });
-    assert.throws(() => applyProviderBlock(block), /not found/);
+    const body = buildProviderBlock({
+      name: 'litellm', gateway: 'http://new', apiKey: 'new', model: 'new',
+    });
+    applyProviderBlock('litellm', body);
+    const cfg = JSON.parse(readFileSync(settingsFile(), 'utf8'));
+    assert.equal(cfg.providers.litellm.settings.baseUrl, 'http://new');
+    assert.equal(cfg.providers.litellm.settings.model, 'new');
   });
 
   test('creates a backup file', () => {
-    makeFakeClineJson(workDir, {
-      plugin: [['./plugins/bizar', {}]],
+    makeFakeSettings(workDir, {
+      providers: { x: { settings: { provider: 'x' } } },
     });
-    const block = buildProviderBlock({
-      name: '9router',
-      gateway: 'http://localhost:20128/v1',
-      apiKey: 'sk-test',
-      models: ['minimax/MiniMax-M3'],
+    const body = buildProviderBlock({
+      name: 'litellm', gateway: 'http://x', apiKey: 'k', model: 'm',
     });
-    const r = applyProviderBlock(block);
+    const r = applyProviderBlock('litellm', body);
     assert.ok(existsSync(r.backup), 'backup file created');
     const backup = JSON.parse(readFileSync(r.backup, 'utf8'));
-    assert.deepEqual(backup.plugin, [['./plugins/bizar', {}]]);
+    assert.ok(backup.providers.x, 'backup contains original entry');
+  });
+});
+
+describe('migrateLegacyOpenaiCompatible()', async () => {
+  const { migrateLegacyOpenaiCompatible } = await import('./setup-provider.mjs');
+
+  test('renames an openai-compatible entry to litellm (preserving baseUrl/apiKey/model)', () => {
+    makeFakeSettings(workDir, {
+      providers: {
+        'openai-compatible': {
+          settings: {
+            provider: 'openai-compatible',
+            baseUrl: 'http://localhost:20128/v1',
+            apiKey: 'sk-test',
+            model: 'minimaxcustom/MiniMax-M3',
+            reasoning: { enabled: false, effort: 'medium' },
+          },
+          updatedAt: '2026-07-09T21:20:00.000Z',
+          tokenSource: 'manual',
+        },
+      },
+      lastUsedProvider: 'openai-compatible',
+    });
+    const r = migrateLegacyOpenaiCompatible('litellm');
+    assert.equal(r.migrated, true);
+    assert.equal(r.from, 'openai-compatible');
+    assert.equal(r.to, 'litellm');
+    const cfg = JSON.parse(readFileSync(settingsFile(), 'utf8'));
+    assert.equal(cfg.providers['openai-compatible'], undefined, 'old key removed');
+    assert.ok(cfg.providers.litellm, 'new key added');
+    assert.equal(cfg.providers.litellm.settings.baseUrl, 'http://localhost:20128/v1', 'baseUrl preserved');
+    assert.equal(cfg.providers.litellm.settings.apiKey, 'sk-test', 'apiKey preserved');
+    assert.equal(cfg.providers.litellm.settings.model, 'minimaxcustom/MiniMax-M3', 'model preserved');
+    assert.equal(cfg.lastUsedProvider, 'litellm', 'active provider switched');
+  });
+
+  test('no-op when no legacy entry exists', () => {
+    makeFakeSettings(workDir, {
+      providers: { litellm: { settings: { provider: 'litellm' } } },
+    });
+    const r = migrateLegacyOpenaiCompatible('litellm');
+    assert.equal(r.migrated, false);
+    assert.equal(r.reason, 'no legacy entry');
+  });
+
+  test('no-op when settings file missing', () => {
+    // No makeFakeSettings call
+    const r = migrateLegacyOpenaiCompatible('litellm');
+    assert.equal(r.migrated, false);
+    assert.equal(r.reason, 'no settings file');
+  });
+
+  test('preserves lastUsedProvider when it pointed at a different entry', () => {
+    makeFakeSettings(workDir, {
+      providers: {
+        'openai-compatible': { settings: { provider: 'openai-compatible', baseUrl: 'http://a' } },
+        ollama: { settings: { provider: 'ollama' } },
+      },
+      lastUsedProvider: 'ollama',
+    });
+    migrateLegacyOpenaiCompatible('litellm');
+    const cfg = JSON.parse(readFileSync(settingsFile(), 'utf8'));
+    // Should NOT clobber the active provider if it wasn't the broken one
+    assert.equal(cfg.lastUsedProvider, 'ollama', 'active ollama preserved');
   });
 });
 
 describe('removeProvider()', () => {
   test('removes a named provider', () => {
-    makeFakeClineJson(workDir, {
-      provider: {
-        a: { baseUrl: 'https://a', apiKey: 'k', models: {} },
-        b: { baseUrl: 'https://b', apiKey: 'k', models: {} },
+    makeFakeSettings(workDir, {
+      providers: {
+        a: { settings: { provider: 'a' } },
+        b: { settings: { provider: 'b' } },
       },
     });
     const r = removeProvider('a');
     assert.equal(r.removed, true);
-    const cfg = JSON.parse(readFileSync(join(workDir, 'cline.json'), 'utf8'));
-    assert.equal(cfg.provider.a, undefined);
-    assert.ok(cfg.provider.b, 'untouched provider preserved');
+    const cfg = JSON.parse(readFileSync(settingsFile(), 'utf8'));
+    assert.equal(cfg.providers.a, undefined);
+    assert.ok(cfg.providers.b, 'untouched provider preserved');
+  });
+
+  test('returns removed=false when settings file is missing', () => {
+    const r = removeProvider('nope');
+    assert.equal(r.removed, false);
+    assert.equal(r.reason, 'no settings file');
   });
 
   test('returns removed=false for a missing provider', () => {
-    makeFakeClineJson(workDir);
+    makeFakeSettings(workDir);
     const r = removeProvider('nonexistent');
     assert.equal(r.removed, false);
     assert.equal(r.reason, 'not present');
@@ -188,23 +285,26 @@ describe('removeProvider()', () => {
 });
 
 describe('parseFlags()', () => {
-  test('parses --gateway, --key, --provider with space separator', () => {
-    const f = parseFlags(['--gateway', 'http://x', '--key', 'sk-x', '--provider', 'foo']);
+  test('parses --gateway, --key, --provider, --model with space separator', () => {
+    const f = parseFlags(['--gateway', 'http://x', '--key', 'sk-x', '--provider', 'litellm', '--model', 'm1']);
     assert.equal(f.gateway, 'http://x');
     assert.equal(f.key, 'sk-x');
-    assert.equal(f.provider, 'foo');
+    assert.equal(f.provider, 'litellm');
+    assert.equal(f.model, 'm1');
   });
 
-  test('parses --gateway=, --key=, --provider= equals form', () => {
-    const f = parseFlags(['--gateway=http://x', '--key=sk-x', '--provider=foo']);
+  test('parses equals form', () => {
+    const f = parseFlags(['--gateway=http://x', '--key=sk-x', '--provider=litellm', '--model=m1']);
     assert.equal(f.gateway, 'http://x');
     assert.equal(f.key, 'sk-x');
-    assert.equal(f.provider, 'foo');
+    assert.equal(f.provider, 'litellm');
+    assert.equal(f.model, 'm1');
   });
 
-  test('parses --list and --remove', () => {
-    const f = parseFlags(['--list']);
+  test('parses --list, --discover, --remove', () => {
+    const f = parseFlags(['--list', '--discover']);
     assert.equal(f.list, true);
+    assert.equal(f.discover, true);
     const g = parseFlags(['--remove', 'myprov']);
     assert.equal(g.remove, 'myprov');
   });

package/cli/commands/validate.mjs

@@ -65,6 +65,23 @@ const REQUIRED_HOOKS = [
 
 const REQUIRED_RUNTIME_DEPS = ['zod', '@cline/sdk', '@cline/core', '@cline/shared'];
 
+// v6.2.3 — Built-in Cline providerIds that are safe for any
+// "OpenAI-compatible endpoint" use case. The harness warns about
+// any providerId NOT in this set (since they fail in kanban mode).
+const OPENAI_COMPATIBLE_BUILTIN_IDS = new Set([
+  'litellm', 'cline', 'ollama', 'lmstudio', 'huggingface',
+  // Plus the first-class providers (also OpenAI-compatible):
+  'openrouter', 'deepseek', 'xai', 'together', 'fireworks',
+  'groq', 'cerebras', 'sambanova', 'nebius', 'baseten',
+  'requesty', 'vercel-ai-gateway', 'v0', 'aihubmix', 'hicap',
+  'nousResearch', 'huawei-cloud-maas', 'qwen', 'qwen-code',
+  'doubao', 'zai', 'zai-coding-plan', 'moonshot', 'wandb',
+  'xiaomi', 'kilo', 'oca', 'asksage', 'sapaicore',
+  // Non-OpenAI-compatible (kept so we don't false-positive):
+  'anthropic', 'google', 'bedrock', 'vertex', 'gemini',
+  'openai', 'openai-native', 'openai-codex',
+]);
+
 function check(name, fn) {
   return Promise.resolve()
     .then(fn)
@@ -284,6 +301,50 @@ const CHECKS = {
     return `user-configured providers: ${summary.join('; ')}`;
   },
 
+  'cline-settings-provider': async () => {
+    // v6.2.3 — The Cline CLI and kanban mode read from
+    // `~/.cline/data/settings/providers.json`. The harness config
+    // (`cline.json`) is a separate thing. This check inspects the
+    // actual settings file and:
+    //   1. Warns if the user has a legacy `openai-compatible` providerId
+    //      (from the v6.0.1 Cline auto-migration shim). Kanban mode
+    //      fails on this with "Unknown or disabled provider". Run
+    //      `bizar setup-provider` to auto-migrate.
+    //   2. Reports the active `lastUsedProvider` so the user can
+    //      see which provider Cline will actually use on the next
+    //      session.
+    const file = join(homedir(), '.cline', 'data', 'settings', 'providers.json');
+    if (!existsSync(file)) {
+      return 'no settings file at ~/.cline/data/settings/providers.json — run `bizar setup-provider` to add one';
+    }
+    const settings = readJsonSafe(file);
+    if (!settings || !settings.providers) {
+      return 'settings file is empty or invalid — run `bizar setup-provider`';
+    }
+    const names = Object.keys(settings.providers);
+    if (names.length === 0) {
+      throw new Error('no providers configured in Cline settings — run `bizar setup-provider`');
+    }
+    const issues = [];
+    if (names.includes('openai-compatible')) {
+      issues.push(`legacy 'openai-compatible' providerId present (broken in kanban mode) — run \`bizar setup-provider\` to auto-migrate to 'litellm'`);
+    }
+    // Check for any providerId that's not in Cline's built-in catalog.
+    for (const n of names) {
+      if (n === 'openai-compatible') continue; // handled above
+      if (!OPENAI_COMPATIBLE_BUILTIN_IDS.has(n)) {
+        issues.push(`'${n}' providerId is NOT in Cline's built-in catalog (likely broken in kanban mode)`);
+      }
+    }
+    const lastUsed = settings.lastUsedProvider || '(none)';
+    if (issues.length > 0) {
+      // Throw so the ⚠ marker shows up; the check is in LENIENT_CHECKS
+      // so this won't cause `bizar validate` to exit non-zero.
+      throw new Error(`WARN: ${issues.join('; ')}. lastUsedProvider=${lastUsed} (${names.join(', ')})`);
+    }
+    return `lastUsedProvider=${lastUsed}; providers: ${names.join(', ')}`;
+  },
+
   '9router-reachable': async () => {
     const url = process.env.NINEROUTER_URL || 'http://localhost:20128';
     const ac = new AbortController();
@@ -301,6 +362,33 @@ const CHECKS = {
     }
   },
 
+  // v6.2.4 — Warn if the user's clineruntimeMaxConsecutiveMistakes is
+  // below the plugin's recommended minimum. Cline's CLI default is 3
+  // which aborts sessions on the 3rd tool mistake. The Bizar plugin
+  // recommends 10 (or `--retries N` with N ≥ 10).
+  'mistake-limit-floor': async () => {
+    const MIN = 10;
+    const cfg = readJsonSafe(clineJsonPath());
+    if (!cfg?.plugin || !Array.isArray(cfg.plugin)) {
+      return 'no plugin entries in cline.json — skip mistake-limit check';
+    }
+    const bizarEntry = cfg.plugin.find((p) => Array.isArray(p) && p[0] && p[0].includes('plugins/bizar'));
+    if (!bizarEntry) {
+      return 'Bizar plugin not registered — skip mistake-limit check';
+    }
+    const opts = (Array.isArray(bizarEntry) && bizarEntry[1]) || {};
+    const raw = opts.clineruntimeMaxConsecutiveMistakes;
+    if (typeof raw !== 'number' || raw >= MIN) {
+      return `clineruntimeMaxConsecutiveMistakes=${raw ?? 'default 10'} (≥ ${MIN}) — OK`;
+    }
+    throw new Error(
+      `clineruntimeMaxConsecutiveMistakes=${raw} is BELOW the recommended minimum (${MIN}). ` +
+      `Cline's default of 3 aborts the session on the 3rd tool mistake. ` +
+      `Edit ~/.cline/cline.json plugin[1].clineruntimeMaxConsecutiveMistakes to ${MIN}, or run ` +
+      `\`bizar install\` to reset to defaults. (See _shared/CLINE_TOOLS.md for the top-5 mistakes.)`,
+    );
+  },
+
   'default-agent-set': async () => {
     const cfg = readJsonSafe(clineJsonPath());
     if (!cfg?.default_agent) {
@@ -371,12 +459,16 @@ const CHECK_ORDER = [
   'default-agent-set',
   'instructions-loaded',
   'provider-config',
+  'cline-settings-provider',
   '9router-reachable',
+  'mistake-limit-floor',
 ];
 
 const LENIENT_CHECKS = new Set([
   '9router-reachable',
   'provider-config', // v6.2.2+ — installer no longer touches provider config; user must configure
+  'cline-settings-provider', // v6.2.3 — warns about legacy/fake providerIds; non-blocking
+  'mistake-limit-floor', // v6.2.4 — warns about low mistake limit; non-blocking
 ]);
 
 export function showValidateHelp() {

package/cli/commands/validate.test.mjs

@@ -304,4 +304,41 @@ describe('runValidate() — JSON output', () => {
     const { exitCode } = await captureRun({ json: true, only: 'this-does-not-exist' });
     assert.equal(exitCode, 2);
   });
+
+  test('v6.2.4 — mistake-limit-floor warns when clineruntimeMaxConsecutiveMistakes is < 10', async () => {
+    const cfg = JSON.parse(readFileSync(join(workDir, 'cline.json'), 'utf8'));
+    cfg.plugin = [['./plugins/bizar', { clineruntimeMaxConsecutiveMistakes: 3 }]];
+    writeFileSync(join(workDir, 'cline.json'), JSON.stringify(cfg, null, 2));
+    const { stdout, exitCode } = await captureRun({ json: true });
+    assert.equal(exitCode, 0, 'mistake-limit-floor is lenient so exit stays 0');
+    const parsed = JSON.parse(stdout);
+    const check = parsed.results.find((r) => r.name === 'mistake-limit-floor');
+    assert.ok(check, 'mistake-limit-floor check should be present');
+    assert.equal(check.ok, false, 'low mistake limit should warn');
+    assert.match(check.message, /BELOW the recommended minimum/);
+    assert.match(check.message, /clineruntimeMaxConsecutiveMistakes=3/);
+  });
+
+  test('v6.2.4 — mistake-limit-floor OK when clineruntimeMaxConsecutiveMistakes >= 10', async () => {
+    const cfg = JSON.parse(readFileSync(join(workDir, 'cline.json'), 'utf8'));
+    cfg.plugin = [['./plugins/bizar', { clineruntimeMaxConsecutiveMistakes: 15 }]];
+    writeFileSync(join(workDir, 'cline.json'), JSON.stringify(cfg, null, 2));
+    const { stdout, exitCode } = await captureRun({ json: true });
+    assert.equal(exitCode, 0);
+    const parsed = JSON.parse(stdout);
+    const check = parsed.results.find((r) => r.name === 'mistake-limit-floor');
+    assert.equal(check.ok, true);
+    assert.match(check.message, /15/);
+  });
+
+  test('v6.2.4 — mistake-limit-floor OK when no plugin entry (legacy cline.json)', async () => {
+    const cfg = JSON.parse(readFileSync(join(workDir, 'cline.json'), 'utf8'));
+    delete cfg.plugin;
+    writeFileSync(join(workDir, 'cline.json'), JSON.stringify(cfg, null, 2));
+    const { stdout } = await captureRun({ json: true });
+    const parsed = JSON.parse(stdout);
+    const check = parsed.results.find((r) => r.name === 'mistake-limit-floor');
+    assert.match(check.message, /no plugin entries/);
+    assert.equal(check.ok, true);
+  });
 });

package/config/agents/_shared/AGENT_BASELINE.md

@@ -5,7 +5,19 @@ description: Always-on rules for every Bizar agent. Loaded automatically by clin
 
 # Agent Baseline — Always-On Rules
 
-Every Bizar agent follows these rules at all times. They are translated from the upstream Claude Fable 5 system prompt, with every Claude-specific tool / function / directory mapped to the BizarHarness equivalent (cline tools, Semble, Skills CLI, Obsidian vault, agent-browser, dashboard artifact pipeline).
+> **v6.2.4 — Read `CLINE_TOOLS.md` first.** The Cline tools (`read_file`,
+> `editor`, `apply_patch`, `ask_question`, `use_subagents`, `task`, …)
+> have strict argument shapes. Passing the wrong shape — e.g. `options:
+> null` on `ask_question` — silently fails and counts as a "mistake".
+> After 3 mistakes (10 since v6.2.4) Cline aborts the session.
+> See `_shared/CLINE_TOOLS.md` for the exact schemas.
+
+Every Bizar agent follows these rules at all times. They are the
+canonical agent baseline for the BizarHarness system — the Norse-pantheon
+multi-agent system built on top of Cline. The rules below are tuned for
+Bizar specifically: tool names reference Cline's built-in tools
+(`read_file`, `editor`, `ask_question`, …) and Bizar's plugin tools
+(`bizar_*`); storage paths reference `~/.cline/` and `~/.bizar_memory/`.
 
 ---
 
@@ -25,6 +37,33 @@ Every Bizar agent follows these rules at all times. They are translated from the
 
 ---
 
+## 1a. Tool Mistakes — Don't Kill the Session
+
+Cline's runtime counts consecutive tool failures (mistakes). When the
+count hits the limit (3 in v6.2.0–v6.2.3; **10 since v6.2.4**), it aborts
+the session with `max consecutive mistakes reached`. The most common
+cause is calling a tool with the wrong argument shape.
+
+**Top 5 mistakes that abort sessions — read this and avoid them:**
+
+1. **`ask_question` with `options: null` or `options: undefined`.** The tool silently fails and counts as a mistake. Always pass an array of 2–5 strings.
+2. **`editor` with non-matching `old_text`.** Whitespace must match exactly. Always `read_file` first and copy the bytes.
+3. **`editor` with `old_text` that matches multiple places.** Make `old_text` more specific (include more surrounding context) so it matches exactly once.
+4. **`execute_command` with shell redirects (`>`, `>>`).** Bizar blocks these by default. Use `editor` or `apply_patch` to write files.
+5. **`use_subagents` with a single prompt.** Subagents are parallel research. Spawn 3–5 at once, not one at a time.
+
+**Recovery: if you hit the mistake limit:**
+
+- Stop retrying the same broken call — each retry wastes a mistake.
+- Read `_shared/CLINE_TOOLS.md` for the exact schema.
+- Spawn a fresh session via `bizar_spawn_background` if the runtime is stuck.
+- Ask the user to abort and restart with `bizar doctor` + `bizar validate`.
+
+The full reference is at `_shared/CLINE_TOOLS.md` (linked from every agent
+file's `description` frontmatter).
+
+---
+
 ## 2. Codebase Search — Use Semble First
 
 Semble is the local code search tool — faster and more token-efficient than reading files directly.