From 878462cc97bb16184c01a29dd89e3ca8339b9642 Mon Sep 17 00:00:00 2001 From: namastex888 Date: Thu, 23 Jul 2026 00:28:48 -0300 Subject: [PATCH] fix(doctor): teach plugin checks the post-A manifest contract MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Live-QA finding from the v5.260723.3 dogfood: two doctor checks still demanded the pre-Group-A manifest shape (mcpServers pointing to ./.mcp.json), so every post-A plugin generation warned 'MCP launcher unusable' and 'manifest does not declare ./.mcp.json' on perfectly healthy machines — the exact declaration Group A removed by design. - 'Codex Genie plugin' health is now installed+enabled+current; the plugin ships no MCP surface, so launcher usability is diagnostics, and the probe's stale manifest complaint (the healthy post-A shape) is filtered from it - 'Codex Genie MCP capability' inverts: declaring NO mcpServers is the pass state; a declared route is the warned regression (second Genie route risks cache-root routing); missing/corrupt/unproven arms unchanged The probe's own usability semantics are deliberately untouched: flipping 'usable' to true on post-A manifests would resurrect the plugin-route arms in route reconciliation/inspection (conflict + fallback removal). Retiring those arms wholesale is the tracked deeper follow-up. --- src/genie-commands/doctor.test.ts | 48 ++++++++++++++++++++++ src/genie-commands/doctor.ts | 66 ++++++++++++++++++++----------- 2 files changed, 91 insertions(+), 23 deletions(-) diff --git a/src/genie-commands/doctor.test.ts b/src/genie-commands/doctor.test.ts index beedfc230..16c27c304 100644 --- a/src/genie-commands/doctor.test.ts +++ b/src/genie-commands/doctor.test.ts @@ -20,6 +20,7 @@ import { dirname, join } from 'node:path'; import { computeDirDigest, computeFileDigest } from '../lib/agent-sync.js'; import { reconcileCodexProjectMcp, resolveGitProjectRoots } from '../lib/codex-project-mcp.js'; import { CANONICAL_GENIE_SKILL_NAMES } from '../lib/runtime-integrations.js'; +import { VERSION } from '../lib/version.js'; import { MINIMUM_BUN_VERSION, checkAgentSync, @@ -219,6 +220,53 @@ describe('Codex doctor lifecycle results', () => { } }); + test('post-A manifest truth: declaring NO mcpServers is the healthy shape; declaring one warns (live-QA regression)', async () => { + const root = mkdtempSync(join(tmpdir(), 'doctor-manifest-truth-')); + const priorCodexHome = process.env.CODEX_HOME; + process.env.CODEX_HOME = join(root, 'codex-home'); + try { + trustProjectInCodexConfig(root); + const activePluginRoot = join(root, 'active-plugin'); + mkdirSync(join(activePluginRoot, '.codex-plugin'), { recursive: true }); + const manifestPath = join(activePluginRoot, '.codex-plugin', 'plugin.json'); + const probe = { + cliAvailable: true, + status: 'ok' as const, + installed: true, + enabled: true, + // The probe still reports the stale pre-A manifest expectation; doctor + // must not surface it as a defect on a post-A generation. + usable: false, + usabilityDetail: 'plugin manifest does not point mcpServers to ./.mcp.json', + version: VERSION, + activePluginRoot, + detail: 'installed', + }; + + // Post-A shape: no mcpServers key → capability pass, plugin check pass. + writeFileSync(manifestPath, JSON.stringify({ name: 'genie', version: VERSION, skills: './skills/' })); + const healthy = await checkCodexIntegration(root, probe); + const capability = healthy.find((check) => check.name === 'Codex Genie MCP capability'); + const plugin = healthy.find((check) => check.name === 'Codex Genie plugin'); + expect(capability).toMatchObject({ status: 'pass' }); + expect(capability?.detail).toContain('declares no MCP route'); + expect(plugin).toMatchObject({ status: 'pass' }); + expect(plugin?.detail).not.toContain('does not point mcpServers'); + expect(plugin?.detail).not.toContain('unusable'); + + // Regression shape: a declared route is the defect (second Genie route). + writeFileSync(manifestPath, JSON.stringify({ name: 'genie', version: VERSION, mcpServers: './.mcp.json' })); + const regressed = await checkCodexIntegration(root, probe); + const declared = regressed.find((check) => check.name === 'Codex Genie MCP capability'); + expect(declared).toMatchObject({ status: 'warn' }); + expect(declared?.detail).toContain('still declares mcpServers'); + } finally { + if (priorCodexHome === undefined) Reflect.deleteProperty(process.env, 'CODEX_HOME'); + else process.env.CODEX_HOME = priorCodexHome; + rmSync(root, { recursive: true, force: true }); + } + }); + test('healthy source bundle cannot make an unproven active plugin capability pass', async () => { const root = mkdtempSync(join(tmpdir(), 'doctor-active-plugin-')); const priorCodexHome = process.env.CODEX_HOME; diff --git a/src/genie-commands/doctor.ts b/src/genie-commands/doctor.ts index bd17bd403..0d26acfbb 100644 --- a/src/genie-commands/doctor.ts +++ b/src/genie-commands/doctor.ts @@ -412,14 +412,21 @@ function codexPluginCheck(state: CodexPluginProbe): CheckResult { }; } const current = state.version === VERSION; - const healthy = current && state.enabled === true && state.usable === true; + // Post-Group-A the plugin ships NO MCP declaration — the marker-owned project + // route is the only Codex route — so plugin health is installed+enabled+current. + // The probe still reports the OLD manifest expectation ("does not point + // mcpServers to ./.mcp.json"): on a post-A generation that IS the healthy + // shape, so it is filtered from diagnostics; every other usability detail + // (missing node/launcher/binary) stays visible as diagnostics. + const healthy = current && state.enabled === true; + const staleManifestComplaint = state.usabilityDetail?.includes('does not point mcpServers') === true; + const diagnostics = + state.usable === true || staleManifestComplaint ? '' : `; diagnostics: ${state.usabilityDetail ?? 'unknown'}`; return { name: 'Codex Genie plugin', status: healthy ? 'pass' : 'warn', - detail: `v${state.version ?? 'unknown'}; ${state.enabled === true ? 'enabled' : 'disabled or unknown'}; ${state.usable === true ? 'MCP launcher usable' : `MCP launcher unusable (${state.usabilityDetail ?? 'unknown reason'})`} (CLI v${VERSION})`, - suggestion: healthy - ? undefined - : 'Run `genie setup --codex` to refresh it; keep the absolute project fallback until launcher health passes.', + detail: `v${state.version ?? 'unknown'}; ${state.enabled === true ? 'enabled' : 'disabled or unknown'}; MCP route: marker-owned project route (plugin declares none)${diagnostics} (CLI v${VERSION})`, + suggestion: healthy ? undefined : 'Run `genie setup --codex` to activate the delivered generation.', }; } @@ -581,17 +588,22 @@ function codexPluginPayloadCheck(probe: CodexPluginProbe): CheckResult | null { function codexPluginSurfaceChecks(probe: CodexPluginProbe): CheckResult[] { if (!probe.installed) return []; const manifest = probe.activePluginRoot ? join(probe.activePluginRoot, '.codex-plugin', 'plugin.json') : null; - let declared = false; - if (manifest !== null && existsSync(manifest)) { - try { - const parsed = JSON.parse(readFileSync(manifest, 'utf8')) as unknown; - declared = - typeof parsed === 'object' && - parsed !== null && - !Array.isArray(parsed) && - (parsed as Record).mcpServers === './.mcp.json'; - } catch { - declared = false; + // Post-Group-A contract (Decisions 1/7): the codex plugin manifest MUST NOT + // declare mcpServers — a declaration would re-create the second (cache-root) + // Genie route the wish removed. Absence is the healthy shape. + let manifestState: 'unproven' | 'unreadable' | 'declares-none' | 'declares-route' = 'unproven'; + if (manifest !== null) { + manifestState = 'unreadable'; + if (existsSync(manifest)) { + try { + const parsed = JSON.parse(readFileSync(manifest, 'utf8')) as unknown; + if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)) { + manifestState = + (parsed as Record).mcpServers === undefined ? 'declares-none' : 'declares-route'; + } + } catch { + manifestState = 'unreadable'; + } } } const payload = codexPluginPayloadCheck(probe); @@ -599,13 +611,21 @@ function codexPluginSurfaceChecks(probe: CodexPluginProbe): CheckResult[] { ...(payload ? [payload] : []), { name: 'Codex Genie MCP capability', - status: declared ? 'pass' : 'warn', - detail: declared - ? `stdio server declared by active plugin at ${probe.activePluginRoot}` - : manifest === null - ? 'active installed plugin root is unproven; source-bundle declarations do not establish runtime health' - : `active plugin manifest is missing, corrupt, or does not declare ./.mcp.json: ${manifest}`, - suggestion: declared ? undefined : 'Run `genie setup --codex` to refresh the active plugin cache.', + status: manifestState === 'declares-none' ? 'pass' : 'warn', + detail: + manifestState === 'declares-none' + ? `plugin declares no MCP route (marker-owned project route is authoritative) at ${probe.activePluginRoot}` + : manifestState === 'declares-route' + ? `active plugin manifest still declares mcpServers — a second Genie route risks cache-root routing: ${manifest}` + : manifestState === 'unreadable' + ? `active plugin manifest is missing or corrupt: ${manifest}` + : 'active installed plugin root is unproven; source-bundle declarations do not establish runtime health', + suggestion: + manifestState === 'declares-none' + ? undefined + : manifestState === 'declares-route' + ? 'Run `genie update` then `genie setup --codex` to activate a generation without a plugin MCP route.' + : 'Run `genie setup --codex` to refresh the active plugin cache.', }, { name: 'Codex hook review',