fix(rerank): classify missing auth before fallback (#2059)

Missing ZEROENTROPY_API_KEY threw AIConfigError from auth resolution, which
rerank.ts recorded as reason 'unknown' — and doctor's reranker_health had no
unknown bucket, so it reported ok while every rerank silently failed open.

- gateway.rerank wraps AIConfigError from applyResolveAuth as
  RerankError(reason: 'auth') before any HTTP call.
- checkRerankerHealth warns on >=3 'unknown' failures in the 7-day window
  (covers historical pre-fix audit rows), with a ZEROENTROPY_API_KEY setup
  hint when the error summary points at a missing key.
- Tests: RerankError(auth) classification, applyReranker fail-open + audit
  reason, doctor warn on repeated unknowns.

Takeover of #2070.

Co-authored-by: maxpetrusenkoagent <maxpetrusenkoagent@users.noreply.github.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

src/commands/autopilot.ts

@@ -151,100 +151,6 @@ export function shouldSpawnAutopilotWorker(args: string[]): boolean {
   return !args.includes('--no-worker');
 }
 
-/**
- * #1525 — positional subcommand translation.
- *
- * Pre-fix, `gbrain autopilot status` silently fell through to "start daemon"
- * because `runAutopilot()` only branched on flag forms (`--status`, etc.).
- * `status` was treated as a stray positional and ignored.
- *
- * This translator maps known positional subcommands to their flag form so
- * `autopilot status` is equivalent to `autopilot --status`, then rejects
- * any unrecognized positional with a fail-loud error before any side
- * effect (lockfile, daemon spawn, sync dispatch) runs.
- *
- * Scope decisions:
- *   - Known aliases: `status` → `--status`, `install` → `--install`,
- *     `uninstall` → `--uninstall`, `start` → (drop; default daemon launch).
- *   - `stop` is intentionally NOT aliased here. Stopping a running daemon
- *     is a new behavior (read PID from lock, SIGTERM, drain) that deserves
- *     its own design and PR. Users typing `gbrain autopilot stop` today get
- *     the unknown-positional error with the canonical alternatives.
- *   - At most one positional allowed; multiple positionals fail loud.
- */
-// Every flag that consumes the NEXT argv token. Missing one here makes the
-// translator misread the flag's value as a positional subcommand and exit 2
-// (e.g. `--install --target linux-cron`). Keep in sync with parseArg call sites.
-const AUTOPILOT_VALUE_FLAGS = new Set(['--repo', '--interval', '--target']);
-const AUTOPILOT_POSITIONAL_ALIASES: Record<string, string | null> = {
-  status: '--status',
-  install: '--install',
-  uninstall: '--uninstall',
-  start: null, // drop the positional; default behavior is daemon launch
-};
-
-export type PositionalTranslation =
-  | { ok: true; args: string[] }
-  | {
-      ok: false;
-      reason: 'unknown_subcommand' | 'multiple_subcommands';
-      message: string;
-    };
-
-export function translatePositionalSubcommands(args: string[]): PositionalTranslation {
-  const out: string[] = [];
-  let positionalSeen = false;
-  let i = 0;
-  while (i < args.length) {
-    const a = args[i];
-    if (AUTOPILOT_VALUE_FLAGS.has(a)) {
-      // Pass through the flag and its value untouched. If the value is
-      // missing at end-of-argv, fall through so the existing parseArg
-      // path can report the broken usage.
-      out.push(a);
-      if (i + 1 < args.length) {
-        out.push(args[i + 1]);
-        i += 2;
-      } else {
-        i += 1;
-      }
-      continue;
-    }
-    if (a.startsWith('-')) {
-      out.push(a);
-      i += 1;
-      continue;
-    }
-    // Positional subcommand.
-    if (positionalSeen) {
-      const known = Object.keys(AUTOPILOT_POSITIONAL_ALIASES).join(', ');
-      return {
-        ok: false,
-        reason: 'multiple_subcommands',
-        message: `Multiple subcommands given. Use only one of: ${known}.`,
-      };
-    }
-    positionalSeen = true;
-    if (a in AUTOPILOT_POSITIONAL_ALIASES) {
-      const alias = AUTOPILOT_POSITIONAL_ALIASES[a];
-      if (alias) out.push(alias);
-      i += 1;
-      continue;
-    }
-    const known = Object.keys(AUTOPILOT_POSITIONAL_ALIASES).join(', ');
-    return {
-      ok: false,
-      reason: 'unknown_subcommand',
-      message:
-        `Unknown subcommand: \`${a}\`.\n` +
-        `Allowed subcommands: ${known}.\n` +
-        `Or use the flag form: --status, --install, --uninstall.\n` +
-        `Run \`gbrain autopilot --help\` for full usage.`,
-    };
-  }
-  return { ok: true, args: out };
-}
-
 export function isPidAlive(pid: number): boolean {
   if (!Number.isFinite(pid) || pid <= 0) return false;
   try {
@@ -457,11 +363,6 @@ export async function runAutopilot(engine: BrainEngine, args: string[]) {
       '       gbrain autopilot --install [--repo <path>]\n' +
       '       gbrain autopilot --uninstall\n' +
       '       gbrain autopilot --status [--json]\n\n' +
-      'Subcommand aliases:\n' +
-      '       gbrain autopilot status     → --status\n' +
-      '       gbrain autopilot install    → --install\n' +
-      '       gbrain autopilot uninstall  → --uninstall\n' +
-      '       gbrain autopilot start      → (default daemon launch)\n\n' +
       'Self-maintaining brain daemon. Runs the full maintenance cycle\n' +
       '(lint + backlinks + sync + extract + embed + orphans) on an interval.\n\n' +
       'For a one-shot cron-triggered cycle, see `gbrain dream`.',
@@ -469,16 +370,6 @@ export async function runAutopilot(engine: BrainEngine, args: string[]) {
     return;
   }
 
-  // #1525: translate positional subcommands to their flag form BEFORE any
-  // side effect (lockfile, daemon spawn, sync dispatch). Unknown positionals
-  // fail loud here rather than silently starting the daemon.
-  const translated = translatePositionalSubcommands(args);
-  if (!translated.ok) {
-    console.error(translated.message);
-    process.exit(2);
-  }
-  args = translated.args;
-
   if (args.includes('--install')) {
     await installDaemon(engine, args);
     return;

src/commands/doctor.ts

@@ -1551,6 +1551,24 @@ export async function checkRerankerHealth(engine: BrainEngine): Promise<Check> {
       };
     }
 
+    // Historical #2059 rows were logged as `unknown` before missing reranker
+    // auth was classified at the gateway. Surface repeated unknowns instead of
+    // reporting "ok" while every rerank fails open.
+    const unknownFails = failures.filter((f) => f.reason === 'unknown');
+    if (unknownFails.length >= 3) {
+      const setupHint = unknownFails.some((f) => {
+        const summary = String(f.error_summary ?? '');
+        return summary.includes('ZEROENTROPY_API_KEY') || summary.toLowerCase().includes('api key');
+      })
+        ? ' Fix: verify ZEROENTROPY_API_KEY and run `gbrain models doctor`.'
+        : '';
+      return {
+        name: 'reranker_health',
+        status: 'warn',
+        message: `${unknownFails.length} unknown reranker failure(s) in last 7 days.${setupHint}`,
+      };
+    }
+
     return {
       name: 'reranker_health',
       status: 'ok',

src/core/ai/gateway.ts

@@ -3656,7 +3656,15 @@ export async function rerank(input: RerankInput): Promise<RerankResult[]> {
   // whose request/response shape differs from ZE/llama.cpp (e.g. Voyage with
   // `top_k` / `data[]`) needs separate adapter hooks in a follow-up plan.
   const url = `${compat.baseURL.replace(/\/$/, '')}${tp.path ?? '/models/rerank'}`;
-  const auth = applyResolveAuth(recipe, cfg, 'reranker');
+  let auth: { apiKey?: string; headers?: Record<string, string> };
+  try {
+    auth = applyResolveAuth(recipe, cfg, 'reranker');
+  } catch (err) {
+    if (err instanceof AIConfigError) {
+      throw new RerankError(err.message, 'auth');
+    }
+    throw err;
+  }
   // applyResolveAuth returns { apiKey } for Bearer-style auth (SDK's native
   // path) or { headers } for custom-header providers (Azure). v0.37.6.0:
   // recipes can ALSO declare default_headers (attribution etc.) which flow

test/ai/rerank.test.ts

@@ -154,6 +154,28 @@ describe('gateway.rerank() — happy path', () => {
 describe('gateway.rerank() — error classification', () => {
   beforeEach(() => configureZE());
 
+  test('missing required reranker API key → RerankError(auth) before HTTP call', async () => {
+    configureGateway({
+      reranker_model: 'zeroentropyai:zerank-2',
+      env: {},
+    });
+    let called = false;
+    __setRerankTransportForTests(async () => {
+      called = true;
+      return mockResp({ results: [{ index: 0, relevance_score: 0.5 }] });
+    });
+
+    try {
+      await rerank({ query: 'q', documents: ['d'] });
+      throw new Error('should have thrown');
+    } catch (err) {
+      expect(err).toBeInstanceOf(RerankError);
+      expect((err as RerankError).reason).toBe('auth');
+      expect((err as Error).message).toContain('ZEROENTROPY_API_KEY');
+      expect(called).toBe(false);
+    }
+  });
+
   test('401 → auth', async () => {
     __setRerankTransportForTests(async () => new Response('Unauthorized', { status: 401 }));
     try {

test/autopilot-positional-subcommands.test.ts

@@ -1,197 +0,0 @@
-/**
- * Tests for translatePositionalSubcommands() — the v0.41.x #1525 fix that
- * prevents `gbrain autopilot status` from silently starting the daemon.
- *
- * IRON RULE regression guard: the exact ticket repro (`gbrain autopilot
- * status`) MUST translate to `--status`, not fall through to the default
- * daemon launch. Verified by the "ticket-exact repro" case below.
- */
-
-import { describe, test, expect } from 'bun:test';
-import { translatePositionalSubcommands } from '../src/commands/autopilot.ts';
-
-describe('translatePositionalSubcommands — known aliases', () => {
-  test('IRON RULE — `autopilot status` translates to `--status` (ticket #1525 repro)', () => {
-    const r = translatePositionalSubcommands(['status']);
-    expect(r.ok).toBe(true);
-    if (r.ok) expect(r.args).toEqual(['--status']);
-  });
-
-  test('`install` translates to `--install`', () => {
-    const r = translatePositionalSubcommands(['install']);
-    expect(r.ok).toBe(true);
-    if (r.ok) expect(r.args).toEqual(['--install']);
-  });
-
-  test('`uninstall` translates to `--uninstall`', () => {
-    const r = translatePositionalSubcommands(['uninstall']);
-    expect(r.ok).toBe(true);
-    if (r.ok) expect(r.args).toEqual(['--uninstall']);
-  });
-
-  test('`start` drops the positional (default daemon launch)', () => {
-    const r = translatePositionalSubcommands(['start']);
-    expect(r.ok).toBe(true);
-    if (r.ok) expect(r.args).toEqual([]);
-  });
-
-  test('`start --json` drops only the positional, keeps the flag', () => {
-    const r = translatePositionalSubcommands(['start', '--json']);
-    expect(r.ok).toBe(true);
-    if (r.ok) expect(r.args).toEqual(['--json']);
-  });
-});
-
-describe('translatePositionalSubcommands — flag/positional interleaving', () => {
-  test('`status --json` preserves the trailing flag', () => {
-    const r = translatePositionalSubcommands(['status', '--json']);
-    expect(r.ok).toBe(true);
-    if (r.ok) expect(r.args).toEqual(['--status', '--json']);
-  });
-
-  test('`--json status` preserves the leading flag', () => {
-    const r = translatePositionalSubcommands(['--json', 'status']);
-    expect(r.ok).toBe(true);
-    if (r.ok) expect(r.args).toEqual(['--json', '--status']);
-  });
-
-  test('`--repo /foo status` does not mis-classify the path as positional', () => {
-    const r = translatePositionalSubcommands(['--repo', '/foo', 'status']);
-    expect(r.ok).toBe(true);
-    if (r.ok) expect(r.args).toEqual(['--repo', '/foo', '--status']);
-  });
-
-  test('`--interval 300 install` does not mis-classify the number as positional', () => {
-    const r = translatePositionalSubcommands(['--interval', '300', 'install']);
-    expect(r.ok).toBe(true);
-    if (r.ok) expect(r.args).toEqual(['--interval', '300', '--install']);
-  });
-
-  test('`--install --target linux-cron` does not mis-classify the target as positional', () => {
-    // --target is installDaemon's value flag; its value must never be read
-    // as a positional subcommand (regression guard for the review fix).
-    const r = translatePositionalSubcommands(['--install', '--target', 'linux-cron']);
-    expect(r.ok).toBe(true);
-    if (r.ok) expect(r.args).toEqual(['--install', '--target', 'linux-cron']);
-  });
-
-  test('`install --target macos` keeps the alias translation and the target value', () => {
-    const r = translatePositionalSubcommands(['install', '--target', 'macos']);
-    expect(r.ok).toBe(true);
-    if (r.ok) expect(r.args).toEqual(['--install', '--target', 'macos']);
-  });
-
-  test('value-flag at end of argv with missing value passes through (so parseArg can report it)', () => {
-    const r = translatePositionalSubcommands(['--repo']);
-    expect(r.ok).toBe(true);
-    if (r.ok) expect(r.args).toEqual(['--repo']);
-  });
-
-  test('value-flag whose value looks like an alias is NOT translated', () => {
-    // `--repo status` means "use repo path 'status'", not "show status".
-    // Translator must not destructure the value of --repo.
-    const r = translatePositionalSubcommands(['--repo', 'status']);
-    expect(r.ok).toBe(true);
-    if (r.ok) expect(r.args).toEqual(['--repo', 'status']);
-  });
-});
-
-describe('translatePositionalSubcommands — pass-through cases', () => {
-  test('empty args returns empty args', () => {
-    const r = translatePositionalSubcommands([]);
-    expect(r.ok).toBe(true);
-    if (r.ok) expect(r.args).toEqual([]);
-  });
-
-  test('flag-only invocation passes through unchanged', () => {
-    const r = translatePositionalSubcommands(['--status', '--json']);
-    expect(r.ok).toBe(true);
-    if (r.ok) expect(r.args).toEqual(['--status', '--json']);
-  });
-
-  test('short flag `-h` passes through unchanged', () => {
-    const r = translatePositionalSubcommands(['-h']);
-    expect(r.ok).toBe(true);
-    if (r.ok) expect(r.args).toEqual(['-h']);
-  });
-
-  test('all known bare flags pass through unchanged', () => {
-    const flags = ['--help', '--install', '--uninstall', '--status', '--json', '--inline', '--no-worker'];
-    const r = translatePositionalSubcommands(flags);
-    expect(r.ok).toBe(true);
-    if (r.ok) expect(r.args).toEqual(flags);
-  });
-});
-
-describe('translatePositionalSubcommands — rejection of unknown positionals', () => {
-  test('unknown positional `foo` fails with reason=unknown_subcommand + structured message', () => {
-    const r = translatePositionalSubcommands(['foo']);
-    expect(r.ok).toBe(false);
-    if (!r.ok) {
-      expect(r.reason).toBe('unknown_subcommand');
-      expect(r.message).toContain('Unknown subcommand: `foo`');
-      expect(r.message).toContain('status');
-      expect(r.message).toContain('install');
-      expect(r.message).toContain('uninstall');
-      expect(r.message).toContain('--help');
-    }
-  });
-
-  test('unknown positional `stop` fails with reason=unknown_subcommand (NOT silently aliased)', () => {
-    // Stop is mentioned in the ticket but deliberately NOT aliased in this
-    // PR — stopping a running daemon is a new behavior, not just an alias.
-    // Until that feature lands separately, `stop` must fail loud rather
-    // than starting the daemon (the bug we're fixing).
-    const r = translatePositionalSubcommands(['stop']);
-    expect(r.ok).toBe(false);
-    if (!r.ok) {
-      expect(r.reason).toBe('unknown_subcommand');
-      expect(r.message).toContain('Unknown subcommand: `stop`');
-    }
-  });
-
-  test('unknown positional `status-detail` (close-but-not-matching) fails', () => {
-    const r = translatePositionalSubcommands(['status-detail']);
-    expect(r.ok).toBe(false);
-    if (!r.ok) {
-      expect(r.reason).toBe('unknown_subcommand');
-      expect(r.message).toContain('Unknown subcommand: `status-detail`');
-    }
-  });
-
-  test('multiple positionals fail with reason=multiple_subcommands (`start install`)', () => {
-    const r = translatePositionalSubcommands(['start', 'install']);
-    expect(r.ok).toBe(false);
-    if (!r.ok) {
-      expect(r.reason).toBe('multiple_subcommands');
-      expect(r.message).toContain('Multiple subcommands');
-    }
-  });
-
-  test('multiple positionals fail even when both are known aliases (`status install`)', () => {
-    const r = translatePositionalSubcommands(['status', 'install']);
-    expect(r.ok).toBe(false);
-    if (!r.ok) {
-      expect(r.reason).toBe('multiple_subcommands');
-      expect(r.message).toContain('Multiple subcommands');
-    }
-  });
-
-  test('known-then-unknown rejects with multiple_subcommands (first-positional-wins)', () => {
-    // First positional is known, second is not. Rejection comes from the
-    // multiple-positional rule, which fires before the unknown check; the
-    // intent is "only one subcommand allowed."
-    const r = translatePositionalSubcommands(['status', 'garbage']);
-    expect(r.ok).toBe(false);
-    if (!r.ok) expect(r.reason).toBe('multiple_subcommands');
-  });
-
-  test('unknown-then-known rejects on the unknown (unknown fires before second-positional check)', () => {
-    const r = translatePositionalSubcommands(['garbage', 'status']);
-    expect(r.ok).toBe(false);
-    if (!r.ok) {
-      expect(r.reason).toBe('unknown_subcommand');
-      expect(r.message).toContain('garbage');
-    }
-  });
-});

test/doctor.test.ts

@@ -2,6 +2,11 @@ import { describe, test, expect, beforeAll, afterAll, beforeEach } from 'bun:tes
 import { mkdirSync, rmSync, writeFileSync } from 'fs';
 import { join } from 'path';
 import { tmpdir } from 'os';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { withEnv } from './helpers/with-env.ts';
+import { logRerankFailure } from '../src/core/rerank-audit.ts';
 
 describe('doctor command', () => {
   test('doctor module exports runDoctor', async () => {
@@ -47,6 +52,34 @@ describe('doctor command', () => {
     expect(check.issues![0].action).toContain('trigger');
   });
 
+  test('reranker_health warns on repeated unknown rerank failures', async () => {
+    const { checkRerankerHealth } = await import('../src/commands/doctor.ts');
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gbrain-rerank-doctor-'));
+    try {
+      await withEnv({ GBRAIN_AUDIT_DIR: tmpDir }, async () => {
+        for (let i = 0; i < 3; i++) {
+          logRerankFailure({
+            model: 'zeroentropyai:zerank-2',
+            reason: 'unknown',
+            query_hash: `unknown${i}`,
+            doc_count: 30,
+            error_summary: 'ZeroEntropy reranker requires ZEROENTROPY_API_KEY.',
+          });
+        }
+        const check = await checkRerankerHealth({
+          async getConfig(key: string): Promise<string | null> {
+            return key === 'search.reranker.enabled' ? 'true' : null;
+          },
+        } as any);
+        expect(check.status).toBe('warn');
+        expect(check.message).toContain('unknown');
+        expect(check.message).toContain('ZEROENTROPY_API_KEY');
+      });
+    } finally {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+
   test('runDoctor accepts null engine for filesystem-only mode', async () => {
     const { runDoctor } = await import('../src/commands/doctor.ts');
     // runDoctor should accept null engine — it runs filesystem checks only.

test/search/rerank.test.ts

@@ -12,9 +12,14 @@
  */
 
 import { describe, test, expect, beforeAll, afterAll } from 'bun:test';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
 import { applyReranker, type RerankerOpts } from '../../src/core/search/rerank.ts';
 import { RerankError, type RerankResult } from '../../src/core/ai/gateway.ts';
+import { readRecentRerankFailures } from '../../src/core/rerank-audit.ts';
 import type { SearchResult } from '../../src/core/types.ts';
+import { withEnv } from '../helpers/with-env.ts';
 
 function makeResult(slug: string, score: number, chunk: string): SearchResult {
   return {
@@ -160,6 +165,36 @@ describe('applyReranker — fail-open on every RerankError reason', () => {
     expect(out).toEqual(results);
   });
 
+  test('missing gateway reranker API key fail-opens and audits auth', async () => {
+    const { configureGateway } = await import('../../src/core/ai/gateway.ts');
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gbrain-rerank-search-'));
+    try {
+      await withEnv({ GBRAIN_AUDIT_DIR: tmpDir }, async () => {
+        configureGateway({
+          reranker_model: 'zeroentropyai:zerank-2',
+          env: {},
+        });
+
+        const results = [makeResult('a', 1.0, 'doc a')];
+        const out = await applyReranker('q', results, {
+          enabled: true,
+          topNIn: 1,
+          topNOut: null,
+          model: 'zeroentropyai:zerank-2',
+        });
+
+        expect(out).toEqual(results);
+        const failures = readRecentRerankFailures(1);
+        expect(failures).toHaveLength(1);
+        expect(failures[0]!.reason).toBe('auth');
+        expect(failures[0]!.error_summary).toContain('ZEROENTROPY_API_KEY');
+      });
+    } finally {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+      configureGateway({ env: { ZEROENTROPY_API_KEY: 'test-key' } });
+    }
+  });
+
   test('fail-open on non-RerankError throw too', async () => {
     const results = [makeResult('a', 1.0, 'a')];
     const opts: RerankerOpts = {