@principles/pd-cli 1.75.0 → 1.77.0

package/tests/commands/config-doctor.test.ts

@@ -1,624 +1,325 @@
 /**
- * pd config doctor tests (PRI-299).
+ * config-doctor tests — PRI-305
  *
  * Covers:
- *   - workspace + openclaw path discovery
- *   - feature-flag presence + warnings
- *   - provider classification: healthy / auth_missing / rate_limit / config_missing / parse_failure
- *   - JSON output is a single parseable object
- *   - secrets are never leaked
- *   - CLI command wiring (pd config doctor --help, --workspace, --json)
+ *   - Internal agent runtime binding readiness
+ *   - JSON purity
+ *   - Missing config → defaults
+ *   - Malformed config → fail loud
+ *   - No secret output
+ *   - Legacy file detection
+ *   - CLI handler: --json stdout purity and exit code
  */
 
-import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
 import * as yaml from 'js-yaml';
-import { execFileSync } from 'node:child_process';
-import { buildDoctorOutput, resolveProviderConfigFromWorkflows, getOpenClawHome, getOpenClawConfigPath } from '../../src/services/config-doctor.js';
+import { buildDoctorOutput, type DoctorOutput } from '../../src/services/config-doctor.js';
+import { handleConfigDoctor } from '../../src/commands/config-doctor.js';
 
-// ─── Helpers ─────────────────────────────────────────────────────────────────
+// ── Helpers ─────────────────────────────────────────────────────────────────
 
 function mkTmpDir(): string {
-  return fs.mkdtempSync(path.join(os.tmpdir(), 'pd-doctor-test-'));
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'pd-config-doctor-test-'));
 }
 
 function rmTmpDir(dir: string): void {
   try { fs.rmSync(dir, { recursive: true, force: true }); } catch { /* ignore */ }
 }
 
-function writeWorkflowsYaml(stateDir: string, content: unknown): void {
-  fs.mkdirSync(stateDir, { recursive: true });
-  const yamlText = typeof content === 'string' ? content : yaml.dump(content);
-  fs.writeFileSync(path.join(stateDir, 'workflows.yaml'), yamlText, 'utf8');
+function writeConfig(workspaceDir: string, content: string): void {
+  const configDir = path.join(workspaceDir, '.pd');
+  fs.mkdirSync(configDir, { recursive: true });
+  fs.writeFileSync(path.join(configDir, 'config.yaml'), content, 'utf8');
 }
 
-function buildWorkflowsYaml(opts: { provider?: string; model?: string; apiKeyEnv?: string; baseUrl?: string }): unknown {
-  return {
-    version: '1',
-    funnels: [
-      {
-        workflowId: 'pd-runtime-v2-diagnosis',
-        stages: [],
-        policy: {
-          runtimeKind: 'pi-ai',
-          ...(opts.provider ? { provider: opts.provider } : {}),
-          ...(opts.model ? { model: opts.model } : {}),
-          ...(opts.apiKeyEnv ? { apiKeyEnv: opts.apiKeyEnv } : {}),
-          ...(opts.baseUrl ? { baseUrl: opts.baseUrl } : {}),
-        },
+function makeValidConfigYaml(): string {
+  return yaml.dump({
+    version: 1,
+    features: {
+      prompt: { category: 'core', enabled: true },
+      code_tool_hook: { category: 'core', enabled: true },
+      defer_archive: { category: 'core', enabled: true },
+      correction_observer: { category: 'quiet', enabled: false },
+      empathy_observer: { category: 'quiet', enabled: false },
+    },
+    runtimeProfiles: {
+      'openclaw.default': { type: 'openclaw', source: 'default' },
+      'openclaw.model.lmstudio.qwen3': { type: 'openclaw', provider: 'lmstudio', model: 'qwen3.6-27b-mtp' },
+      'pd.anthropic-sonnet': { type: 'pi-ai', provider: 'anthropic', model: 'claude-3-5-sonnet', apiKeyEnv: 'ANTHROPIC_API_KEY', timeoutMs: 300000 },
+    },
+    internalAgents: {
+      defaultRuntime: 'openclaw.default',
+      agents: {
+        diagnostician: { enabled: true, runtimeProfile: 'openclaw.model.lmstudio.qwen3' },
+        dreamer: { enabled: true },
+        scribe: { enabled: true },
+        artificer: { enabled: true },
+        philosopher: { enabled: false },
+        evaluator: { enabled: false },
+        rolloutReviewer: { enabled: false },
+        trainer: { enabled: false },
+        correctionObserver: { enabled: false },
+        empathyObserver: { enabled: false },
       },
-    ],
-  };
-}
-
-// ─── resolveProviderConfigFromWorkflows ──────────────────────────────────────
-
-describe('resolveProviderConfigFromWorkflows', () => {
-  it('returns source=missing when workflows.yaml is absent and no CLI overrides', async () => {
-    const tmp = mkTmpDir();
-    try {
-      const result = await resolveProviderConfigFromWorkflows(path.join(tmp, '.state'));
-      expect(result.source).toBe('missing');
-      expect(result.workflowsFound).toBe(false);
-      expect(result.provider).toBeNull();
-      expect(result.model).toBeNull();
-      expect(result.apiKeyEnv).toBeNull();
-    } finally { rmTmpDir(tmp); }
+    },
+    ui: { diagnostics: { mode: 'simple' } },
   });
+}
 
-  it('returns source=cli_flag when workflows.yaml is absent but CLI flags supplied', async () => {
-    const tmp = mkTmpDir();
-    try {
-      const result = await resolveProviderConfigFromWorkflows(path.join(tmp, '.state'), {
-        cliProvider: 'openrouter',
-        cliModel: 'anthropic/claude-sonnet-4',
-        cliApiKeyEnv: 'OPENROUTER_API_KEY',
-      });
-      expect(result.source).toBe('cli_flag');
-      expect(result.workflowsFound).toBe(false);
-      expect(result.provider).toBe('openrouter');
-      expect(result.model).toBe('anthropic/claude-sonnet-4');
-      expect(result.apiKeyEnv).toBe('OPENROUTER_API_KEY');
-    } finally { rmTmpDir(tmp); }
-  });
+// ── Internal agent runtime binding readiness ─────────────────────────────────
 
-  it('parses a well-formed workflows.yaml with the diagnostic funnel', async () => {
+describe('Internal agent runtime binding readiness', () => {
+  it('disabled agents show readiness=disabled', async () => {
     const tmp = mkTmpDir();
+    writeConfig(tmp, makeValidConfigYaml());
     try {
-      writeWorkflowsYaml(path.join(tmp, '.state'), buildWorkflowsYaml({
-        provider: 'openrouter',
-        model: 'anthropic/claude-sonnet-4',
-        apiKeyEnv: 'OPENROUTER_API_KEY',
-      }));
-      const result = await resolveProviderConfigFromWorkflows(path.join(tmp, '.state'));
-      expect(result.source).toBe('workflows.yaml');
-      expect(result.workflowsFound).toBe(true);
-      expect(result.parseWarning).toBeUndefined();
-      expect(result.provider).toBe('openrouter');
-      expect(result.model).toBe('anthropic/claude-sonnet-4');
-      expect(result.apiKeyEnv).toBe('OPENROUTER_API_KEY');
+      const output = await buildDoctorOutput({ workspaceDir: tmp });
+      const philosopher = output.internalAgents.find(a => a.name === 'philosopher');
+      expect(philosopher).toBeDefined();
+      expect(philosopher!.readiness).toBe('disabled');
+      expect(philosopher!.enabled).toBe(false);
     } finally { rmTmpDir(tmp); }
   });
 
-  it('returns parseWarning on YAML parse error', async () => {
+  it('enabled agent with openclaw profile shows readiness=ready', async () => {
     const tmp = mkTmpDir();
+    writeConfig(tmp, makeValidConfigYaml());
     try {
-      writeWorkflowsYaml(path.join(tmp, '.state'), 'gfi: [unterminated');
-      const result = await resolveProviderConfigFromWorkflows(path.join(tmp, '.state'));
-      expect(result.workflowsFound).toBe(true);
-      expect(result.parseWarning).toBeDefined();
-      expect(result.parseWarning).toMatch(/parse error/i);
-      expect(result.provider).toBeNull();
+      const output = await buildDoctorOutput({ workspaceDir: tmp });
+      const diagnostician = output.internalAgents.find(a => a.name === 'diagnostician');
+      expect(diagnostician).toBeDefined();
+      expect(diagnostician!.enabled).toBe(true);
+      expect(diagnostician!.readiness).toBe('ready');
     } finally { rmTmpDir(tmp); }
   });
 
-  it('returns parseWarning when diagnostic funnel is missing', async () => {
+  it('enabled agent with pi-ai profile and missing env shows readiness=needs_setup', async () => {
     const tmp = mkTmpDir();
+    writeConfig(tmp, makeValidConfigYaml());
+    // Ensure ANTHROPIC_API_KEY is not set
+    const originalKey = process.env.ANTHROPIC_API_KEY;
+    delete process.env.ANTHROPIC_API_KEY;
     try {
-      writeWorkflowsYaml(path.join(tmp, '.state'), {
-        version: '1',
-        funnels: [{ workflowId: 'some-other-funnel', stages: [], policy: {} }],
+      // Create config with an enabled agent using pi-ai profile
+      const config = yaml.dump({
+        version: 1,
+        features: {
+          prompt: { category: 'core', enabled: true },
+          code_tool_hook: { category: 'core', enabled: true },
+          defer_archive: { category: 'core', enabled: true },
+          correction_observer: { category: 'quiet', enabled: false },
+          empathy_observer: { category: 'quiet', enabled: false },
+        },
+        runtimeProfiles: {
+          'openclaw.default': { type: 'openclaw', source: 'default' },
+          'pd.anthropic-sonnet': { type: 'pi-ai', provider: 'anthropic', model: 'claude-3-5-sonnet', apiKeyEnv: 'ANTHROPIC_API_KEY' },
+        },
+        internalAgents: {
+          defaultRuntime: 'openclaw.default',
+          agents: {
+            diagnostician: { enabled: true, runtimeProfile: 'pd.anthropic-sonnet' },
+            dreamer: { enabled: true },
+            scribe: { enabled: true },
+            artificer: { enabled: true },
+            philosopher: { enabled: false },
+            evaluator: { enabled: false },
+            rolloutReviewer: { enabled: false },
+            trainer: { enabled: false },
+            correctionObserver: { enabled: false },
+            empathyObserver: { enabled: false },
+          },
+        },
       });
-      const result = await resolveProviderConfigFromWorkflows(path.join(tmp, '.state'));
-      expect(result.workflowsFound).toBe(true);
-      expect(result.parseWarning).toMatch(/funnel 'pd-runtime-v2-diagnosis' not found/);
-    } finally { rmTmpDir(tmp); }
-  });
+      writeConfig(tmp, config);
 
-  it('returns parseWarning when funnels is not an array', async () => {
-    const tmp = mkTmpDir();
-    try {
-      writeWorkflowsYaml(path.join(tmp, '.state'), 'version: 1\nfunnels: not-an-array\n');
-      const result = await resolveProviderConfigFromWorkflows(path.join(tmp, '.state'));
-      expect(result.workflowsFound).toBe(true);
-      expect(result.parseWarning).toMatch(/funnels is not an array/);
-    } finally { rmTmpDir(tmp); }
+      const output = await buildDoctorOutput({ workspaceDir: tmp });
+      const diagnostician = output.internalAgents.find(a => a.name === 'diagnostician');
+      expect(diagnostician).toBeDefined();
+      expect(diagnostician!.readiness).toBe('needs_setup');
+      expect(diagnostician!.apiKeyEnv).toBe('ANTHROPIC_API_KEY');
+      expect(diagnostician!.apiKeyPresent).toBe(false);
+      expect(diagnostician!.nextAction).toContain('ANTHROPIC_API_KEY');
+    } finally {
+      if (originalKey !== undefined) process.env.ANTHROPIC_API_KEY = originalKey;
+      rmTmpDir(tmp);
+    }
   });
 });
 
-// ─── buildDoctorOutput ───────────────────────────────────────────────────────
+// ── JSON purity ──────────────────────────────────────────────────────────────
 
-describe('buildDoctorOutput — config_missing', () => {
-  it('classifies provider as config_missing when workflows.yaml is absent and no CLI overrides', async () => {
+describe('JSON purity', () => {
+  it('output is a single parseable JSON object', async () => {
     const tmp = mkTmpDir();
     try {
       const output = await buildDoctorOutput({ workspaceDir: tmp });
-      expect(output.status).toBe('failed');
-      expect(output.reason).toBeDefined();
-      expect(output.reason).toMatch(/auth_missing|config_missing/);
-      expect(output.providerHealth).toHaveLength(1);
-      const ph = output.providerHealth[0];
-      expect(ph.classification).toBe('config_missing');
-      expect(ph.provider).toBeNull();
-      expect(ph.model).toBeNull();
-      expect(ph.apiKeyPresent).toBe(false);
-      expect(ph.reason).toBeDefined();
-      expect(ph.nextAction).toBeDefined();
-      expect(output.nextActions.length).toBeGreaterThan(0);
+      const json = JSON.stringify(output, null, 2);
+      const parsed = JSON.parse(json);
+      expect(typeof parsed).toBe('object');
+      expect(parsed).not.toBeNull();
+      expect(Array.isArray(parsed)).toBe(false);
     } finally { rmTmpDir(tmp); }
   });
 });
 
-describe('buildDoctorOutput — auth_missing', () => {
-  it('classifies provider as auth_missing when apiKeyEnv is set in workflows but env var is unset', async () => {
+// ── Missing config → defaults ────────────────────────────────────────────────
+
+describe('Missing config → defaults', () => {
+  it('returns status=ok when config file is absent (uses defaults)', async () => {
     const tmp = mkTmpDir();
     try {
-      writeWorkflowsYaml(path.join(tmp, '.state'), buildWorkflowsYaml({
-        provider: 'openrouter',
-        model: 'anthropic/claude-sonnet-4',
-        apiKeyEnv: 'PD_DOCTOR_TEST_KEY_NEVER_SET_X9Z',
-      }));
       const output = await buildDoctorOutput({ workspaceDir: tmp });
-      expect(output.status).toBe('failed');
-      expect(output.reason).toMatch(/auth_missing|config_missing/);
-      const ph = output.providerHealth[0];
-      expect(ph.classification).toBe('auth_missing');
-      expect(ph.provider).toBe('openrouter');
-      expect(ph.model).toBe('anthropic/claude-sonnet-4');
-      expect(ph.apiKeyEnv).toBe('PD_DOCTOR_TEST_KEY_NEVER_SET_X9Z');
-      expect(ph.apiKeyPresent).toBe(false);
-      expect(ph.reason).toMatch(/not set or empty/);
+      // With defaults, MVP core features are enabled, so status should be ok or degraded
+      expect(['ok', 'degraded']).toContain(output.status);
+      expect(output.featureFlags.source).toBe('defaults');
+      expect(output.featureFlags.enabledMvpChannels).toContain('prompt');
     } finally { rmTmpDir(tmp); }
   });
+});
+
+// ── Malformed config → fail loud ────────────────────────────────────────────
 
-  it('classifies provider as auth_missing when apiKeyEnv is not in workflows.yaml at all', async () => {
+describe('Malformed config → fail loud', () => {
+  it('returns status=failed with reason and nextActions for YAML parse error', async () => {
     const tmp = mkTmpDir();
+    writeConfig(tmp, 'version: [unterminated');
     try {
-      writeWorkflowsYaml(path.join(tmp, '.state'), buildWorkflowsYaml({
-        provider: 'openrouter',
-        model: 'anthropic/claude-sonnet-4',
-      }));
       const output = await buildDoctorOutput({ workspaceDir: tmp });
       expect(output.status).toBe('failed');
-      const ph = output.providerHealth[0];
-      expect(ph.classification).toBe('auth_missing');
-      expect(ph.apiKeyEnv).toBeNull();
-      expect(ph.apiKeyPresent).toBe(false);
+      expect(output.reason).toBeTruthy();
+      expect(output.nextActions.length).toBeGreaterThan(0);
     } finally { rmTmpDir(tmp); }
   });
 });
 
-describe('buildDoctorOutput — healthy', () => {
-  it('classifies provider as healthy when config is valid and env var is set', async () => {
-    const tmp = mkTmpDir();
-    const envName = 'PD_DOCTOR_TEST_KEY_PRESENT_OK';
-    const previous = process.env[envName];
-    process.env[envName] = 'redacted-test-value-not-leaked';
-    try {
-      writeWorkflowsYaml(path.join(tmp, '.state'), buildWorkflowsYaml({
-        provider: 'openrouter',
-        model: 'anthropic/claude-sonnet-4',
-        apiKeyEnv: envName,
-      }));
-      const output = await buildDoctorOutput({ workspaceDir: tmp });
-      expect(output.status).toBe('ok');
-      const ph = output.providerHealth[0];
-      expect(ph.classification).toBe('healthy');
-      expect(ph.apiKeyEnv).toBe(envName);
-      expect(ph.apiKeyPresent).toBe(true);
-      // Ensure the env var value is NOT leaked
-      const json = JSON.stringify(output);
-      expect(json).not.toContain('redacted-test-value-not-leaked');
-    } finally {
-      if (previous === undefined) {
-        delete process.env[envName];
-      } else {
-        process.env[envName] = previous;
-      }
-      rmTmpDir(tmp);
-    }
-  });
-});
+// ── No secret output ─────────────────────────────────────────────────────────
 
-describe('buildDoctorOutput — rate_limit', () => {
-  it('classifies provider as rate_limit when state.db contains a 429 signature', async () => {
+describe('No secret output', () => {
+  it('output never contains raw API key values', async () => {
     const tmp = mkTmpDir();
-    const envName = 'PD_DOCTOR_TEST_KEY_RATELIMIT_OK';
-    const previous = process.env[envName];
-    process.env[envName] = 'redacted-test-value';
+    writeConfig(tmp, makeValidConfigYaml());
     try {
-      writeWorkflowsYaml(path.join(tmp, '.state'), buildWorkflowsYaml({
-        provider: 'openrouter',
-        model: 'anthropic/claude-sonnet-4',
-        apiKeyEnv: envName,
-      }));
-      // Plant a fake state.db that includes a 429 / rate_limit message
-      await plantStateDbWithMessage(tmp, "Error: 429 too many requests, rpm exhausted");
       const output = await buildDoctorOutput({ workspaceDir: tmp });
-      const ph = output.providerHealth[0];
-      expect(ph.classification).toBe('rate_limit');
-      expect(ph.reason).toMatch(/rate_limit|signature/i);
-      expect(output.status).toBe('degraded');
-    } finally {
-      if (previous === undefined) {
-        delete process.env[envName];
-      } else {
-        process.env[envName] = previous;
-      }
-      rmTmpDir(tmp);
-    }
+      const json = JSON.stringify(output);
+      expect(json).not.toContain('sk-ant-');
+      expect(json).not.toMatch(/"apiKey"\s*:/);
+      expect(json).not.toContain('"gatewayToken"');
+    } finally { rmTmpDir(tmp); }
   });
 
-  it('classifies provider as rate_limit when state.db has candidate_failed + rpm exhausted', async () => {
+  it('internal agents show apiKeyEnv name, not value', async () => {
     const tmp = mkTmpDir();
-    const envName = 'PD_DOCTOR_TEST_KEY_RATELIMIT_2';
-    const previous = process.env[envName];
-    process.env[envName] = 'redacted-test-value';
+    writeConfig(tmp, makeValidConfigYaml());
     try {
-      writeWorkflowsYaml(path.join(tmp, '.state'), buildWorkflowsYaml({
-        provider: 'openrouter',
-        model: 'anthropic/claude-sonnet-4',
-        apiKeyEnv: envName,
-      }));
-      await plantStateDbWithMessage(tmp, "candidate_failed: rpm exhausted for current model");
       const output = await buildDoctorOutput({ workspaceDir: tmp });
-      const ph = output.providerHealth[0];
-      expect(ph.classification).toBe('rate_limit');
-    } finally {
-      if (previous === undefined) {
-        delete process.env[envName];
-      } else {
-        process.env[envName] = previous;
+      for (const agent of output.internalAgents) {
+        if (agent.apiKeyEnv) {
+          // apiKeyEnv should be the env var name, not the key value
+          expect(agent.apiKeyEnv).toMatch(/^[A-Z_]+$/);
+        }
       }
-      rmTmpDir(tmp);
-    }
+    } finally { rmTmpDir(tmp); }
   });
 });
 
-describe('buildDoctorOutput — secrets redaction', () => {
-  it('never includes the env var value in the output', async () => {
-    const tmp = mkTmpDir();
-    const envName = 'PD_DOCTOR_TEST_KEY_REDACTION';
-    const secret = 'sk-1234567890abcdef-secret-do-not-leak';
-    const previous = process.env[envName];
-    process.env[envName] = secret;
-    try {
-      writeWorkflowsYaml(path.join(tmp, '.state'), buildWorkflowsYaml({
-        provider: 'openrouter',
-        model: 'anthropic/claude-sonnet-4',
-        apiKeyEnv: envName,
-      }));
-      const output = await buildDoctorOutput({ workspaceDir: tmp });
-      const json = JSON.stringify(output);
-      expect(json).not.toContain(secret);
-      // env var name is allowed to appear; raw value is not
-      expect(json).toContain(envName);
-    } finally {
-      if (previous === undefined) {
-        delete process.env[envName];
-      } else {
-        process.env[envName] = previous;
-      }
-      rmTmpDir(tmp);
-    }
-  });
-});
+// ── Legacy file detection ────────────────────────────────────────────────────
 
-describe('buildDoctorOutput — parse_failure (workflows.yaml)', () => {
-  it('reports parse_failure warning when workflows.yaml is malformed', async () => {
+describe('Legacy file detection', () => {
+  it('detects .pd/feature-flags.yaml and reports as legacy', async () => {
     const tmp = mkTmpDir();
+    const pdDir = path.join(tmp, '.pd');
+    fs.mkdirSync(pdDir, { recursive: true });
+    fs.writeFileSync(path.join(pdDir, 'feature-flags.yaml'), 'prompt:\n  enabled: true\n', 'utf8');
     try {
-      writeWorkflowsYaml(path.join(tmp, '.state'), 'gfi: [unterminated');
       const output = await buildDoctorOutput({ workspaceDir: tmp });
-      expect(output.warnings.length).toBeGreaterThan(0);
-      expect(output.warnings.some((w) => /parse error/i.test(w))).toBe(true);
-      expect(output.nextActions.some((a) => /workflows.yaml/i.test(a))).toBe(true);
+      expect(output.legacyFilesDetected.length).toBeGreaterThan(0);
+      expect(output.legacyFilesDetected[0]).toContain('feature-flags.yaml');
     } finally { rmTmpDir(tmp); }
   });
 });
 
-describe('buildDoctorOutput — feature flags', () => {
-  it('reports enabled MVP channels from feature-flags.yaml', async () => {
+// ── Feature flags from config.yaml ───────────────────────────────────────────
+
+describe('Feature flags from config.yaml', () => {
+  it('shows enabled MVP channels from config', async () => {
     const tmp = mkTmpDir();
+    writeConfig(tmp, makeValidConfigYaml());
     try {
-      const pdDir = path.join(tmp, '.pd');
-      fs.mkdirSync(pdDir, { recursive: true });
-      fs.writeFileSync(
-        path.join(pdDir, 'feature-flags.yaml'),
-        'prompt:\n  enabled: true\ncode_tool_hook:\n  enabled: true\ndefer_archive:\n  enabled: true\ngfi:\n  enabled: false\n',
-        'utf8',
-      );
       const output = await buildDoctorOutput({ workspaceDir: tmp });
-      expect(output.featureFlags.source).toBe('workspace_file');
-      expect(output.featureFlags.enabledMvpChannels).toEqual(
-        expect.arrayContaining(['prompt', 'code_tool_hook', 'defer_archive']),
-      );
-      expect(output.featureFlags.disabledFlags).toContain('gfi');
+      expect(output.featureFlags.enabledMvpChannels).toContain('prompt');
+      expect(output.featureFlags.enabledMvpChannels).toContain('code_tool_hook');
+      expect(output.featureFlags.enabledMvpChannels).toContain('defer_archive');
     } finally { rmTmpDir(tmp); }
   });
 });
 
-describe('buildDoctorOutput — paths', () => {
-  it('reports existence of PD and OpenClaw config paths', async () => {
-    const tmp = mkTmpDir();
-    try {
-      fs.mkdirSync(path.join(tmp, '.pd'), { recursive: true });
-      const output = await buildDoctorOutput({ workspaceDir: tmp });
-      expect(output.pdConfigPaths.workspaceDir.exists).toBe(true);
-      expect(output.pdConfigPaths.pdDir.exists).toBe(true);
-      expect(output.pdConfigPaths.featureFlags.exists).toBe(false);
-      expect(output.openclawConfigPaths.openclawHome.path).toBe(getOpenClawHome());
-      expect(output.openclawConfigPaths.openclawConfig.path).toBe(getOpenClawConfigPath());
-    } finally { rmTmpDir(tmp); }
+// ── CLI handler: --json stdout purity and exit code ──────────────────────────
+
+describe('CLI handler: --json stdout purity and exit code', () => {
+  let stdoutSpy: ReturnType<typeof vi.spyOn>;
+  let stderrSpy: ReturnType<typeof vi.spyOn>;
+  let originalExitCode: number | undefined;
+
+  beforeEach(() => {
+    stdoutSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    stderrSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    originalExitCode = process.exitCode;
+    process.exitCode = undefined;
   });
-});
 
-// ─── JSON shape contract ─────────────────────────────────────────────────────
+  afterEach(() => {
+    stdoutSpy.mockRestore();
+    stderrSpy.mockRestore();
+    process.exitCode = originalExitCode;
+  });
 
-describe('buildDoctorOutput — JSON output contract', () => {
-  it('JSON.stringify produces a single parseable object containing all required fields', async () => {
+  it('--json outputs exactly one parseable JSON object to stdout', async () => {
     const tmp = mkTmpDir();
     try {
-      const output = await buildDoctorOutput({ workspaceDir: tmp });
-      const json = JSON.stringify(output, null, 2);
-      const parsed: unknown = JSON.parse(json);
+      await handleConfigDoctor({ workspace: tmp, json: true });
+      expect(stdoutSpy).toHaveBeenCalledTimes(1);
+      const output = stdoutSpy.mock.calls[0][0] as string;
+      const parsed = JSON.parse(output);
       expect(typeof parsed).toBe('object');
       expect(parsed).not.toBeNull();
-      expect(parsed).not.toBeInstanceOf(Array);
-      // Required top-level fields
+      expect(Array.isArray(parsed)).toBe(false);
       expect(parsed).toHaveProperty('status');
-      expect(parsed).toHaveProperty('workspaceDir');
-      expect(parsed).toHaveProperty('pdConfigPaths');
-      expect(parsed).toHaveProperty('openclawConfigPaths');
       expect(parsed).toHaveProperty('featureFlags');
-      expect(parsed).toHaveProperty('providerHealth');
-      expect(parsed).toHaveProperty('warnings');
-      expect(parsed).toHaveProperty('nextActions');
-      // status is one of ok|degraded|failed
-      expect(['ok', 'degraded', 'failed']).toContain(parsed.status);
+      expect(parsed).toHaveProperty('internalAgents');
     } finally { rmTmpDir(tmp); }
   });
 
-  it('no env var value is present in the JSON output even when key is set', async () => {
-    const tmp = mkTmpDir();
-    const envName = 'PD_DOCTOR_TEST_JSON_REDACTION';
-    const secret = 'super-secret-value-do-not-leak-12345';
-    const previous = process.env[envName];
-    process.env[envName] = secret;
-    try {
-      writeWorkflowsYaml(path.join(tmp, '.state'), buildWorkflowsYaml({
-        provider: 'openrouter',
-        model: 'anthropic/claude-sonnet-4',
-        apiKeyEnv: envName,
-      }));
-      const output = await buildDoctorOutput({ workspaceDir: tmp });
-      const json = JSON.stringify(output, null, 2);
-      expect(json).not.toContain(secret);
-    } finally {
-      if (previous === undefined) {
-        delete process.env[envName];
-      } else {
-        process.env[envName] = previous;
-      }
-      rmTmpDir(tmp);
-    }
-  });
-});
-
-describe('buildDoctorOutput — feature flags failure resilience', () => {
-  it('does not throw when feature-flags.yaml is a directory, outputs degraded status and flag warnings', async () => {
+  it('--json sets process.exitCode=1 on failed status', async () => {
     const tmp = mkTmpDir();
+    writeConfig(tmp, 'version: [unterminated');
     try {
-      const pdDir = path.join(tmp, '.pd');
-      fs.mkdirSync(pdDir, { recursive: true });
-      fs.mkdirSync(path.join(pdDir, 'feature-flags.yaml'), { recursive: true });
-
-      const output = await buildDoctorOutput({ workspaceDir: tmp });
-      expect(['degraded', 'failed']).toContain(output.status);
-      expect(output.featureFlags.source).toBe('unavailable');
-      expect(output.featureFlags.warnings.some(w => w.includes('feature flags unavailable'))).toBe(true);
-      expect(output.warnings.some(w => w.includes('feature flags unavailable'))).toBe(true);
-      expect(output.nextActions.some(a => a.includes('readable file, not a directory'))).toBe(true);
+      await handleConfigDoctor({ workspace: tmp, json: true });
+      expect(process.exitCode).toBe(1);
+      const output = stdoutSpy.mock.calls[0][0] as string;
+      const parsed = JSON.parse(output);
+      expect(parsed.status).toBe('failed');
+      expect(parsed.reason).toBeTruthy();
     } finally { rmTmpDir(tmp); }
   });
-});
-
-describe('buildDoctorOutput — CorrectionObserver diagnostics', () => {
-  it('reports auth_missing when ANTHROPIC_API_KEY is not set (default env fallback)', async () => {
-    const tmp = mkTmpDir();
-    const apiKeyEnv = 'ANTHROPIC_API_KEY';
-    const previous = process.env[apiKeyEnv];
-    delete process.env[apiKeyEnv];
-    try {
-      const output = await buildDoctorOutput({ workspaceDir: tmp });
-      const co = output.internalAgents.correctionObserver;
-      expect(co.enabled).toBe(true);
-      expect(co.status).toBe('auth_missing');
-      expect(co.configSource).toBe('env');
-      expect(co.apiKeyEnv).toBe('ANTHROPIC_API_KEY');
-      expect(co.apiKeyPresent).toBe(false);
-      expect(co.nextAction).toMatch(/set the environment variable 'ANTHROPIC_API_KEY'/i);
-    } finally {
-      if (previous !== undefined) {
-        process.env[apiKeyEnv] = previous;
-      }
-      rmTmpDir(tmp);
-    }
-  });
 
-  it('reports disabled when correction_observer is disabled in feature-flags.yaml', async () => {
+  it('--json does not set exitCode=1 on ok status', async () => {
     const tmp = mkTmpDir();
     try {
-      const pdDir = path.join(tmp, '.pd');
-      fs.mkdirSync(pdDir, { recursive: true });
-      fs.writeFileSync(
-        path.join(pdDir, 'feature-flags.yaml'),
-        'correction_observer:\n  enabled: false\n',
-        'utf8',
-      );
-      const output = await buildDoctorOutput({ workspaceDir: tmp });
-      const co = output.internalAgents.correctionObserver;
-      expect(co.enabled).toBe(false);
-      expect(co.status).toBe('disabled');
-      expect(co.reason).toContain('CorrectionObserver is disabled');
-      expect(co.nextAction).toContain('correction_observer.enabled=true');
+      await handleConfigDoctor({ workspace: tmp, json: true });
+      expect(process.exitCode).toBeUndefined();
     } finally { rmTmpDir(tmp); }
   });
 
-  it('reports configured when pd-correction-observer policy is present in workflows.yaml and key exists', async () => {
-    const tmp = mkTmpDir();
-    const customKeyEnv = 'PD_DOCTOR_TEST_CO_KEY';
-    const previous = process.env[customKeyEnv];
-    process.env[customKeyEnv] = 'dummy-key-value-not-leaked';
-    try {
-      writeWorkflowsYaml(path.join(tmp, '.state'), {
-        version: '1',
-        funnels: [
-          {
-            workflowId: 'pd-correction-observer',
-            policy: {
-              runtimeKind: 'pi-ai',
-              provider: 'anthropic',
-              model: 'anthropic/claude-3-5-sonnet',
-              apiKeyEnv: customKeyEnv,
-            },
-          },
-        ],
-      });
-      const output = await buildDoctorOutput({ workspaceDir: tmp });
-      const co = output.internalAgents.correctionObserver;
-      expect(co.enabled).toBe(true);
-      expect(co.status).toBe('configured');
-      expect(co.configSource).toBe('workflows.yaml');
-      expect(co.provider).toBe('anthropic');
-      expect(co.model).toBe('anthropic/claude-3-5-sonnet');
-      expect(co.apiKeyEnv).toBe(customKeyEnv);
-      expect(co.apiKeyPresent).toBe(true);
-      const json = JSON.stringify(output);
-      expect(json).not.toContain('dummy-key-value-not-leaked');
-    } finally {
-      if (previous === undefined) {
-        delete process.env[customKeyEnv];
-      } else {
-        process.env[customKeyEnv] = previous;
-      }
-      rmTmpDir(tmp);
-    }
-  });
-});
-
-// ─── CLI command wiring ──────────────────────────────────────────────────────
-
-describe('CLI command wiring (pd config doctor)', () => {
-  let cliPath: string;
-  let workspaceRoot: string;
-
-  beforeEach(() => {
-    workspaceRoot = path.resolve(__dirname, '../../../..');
-    cliPath = path.join(workspaceRoot, 'packages', 'pd-cli', 'dist', 'index.js');
-  });
-
-  it('config doctor is registered at pd config doctor --help', () => {
-    const out = runPd(['config', 'doctor', '--help'], workspaceRoot);
-    expect(out).toContain('PD');
-    expect(out).toContain('--workspace');
-    expect(out).toContain('--json');
-  });
-
-  it('config subcommand appears in pd --help', () => {
-    const out = runPd(['--help'], workspaceRoot);
-    expect(out).toMatch(/\bconfig\b/);
-  });
-
-  it('pd config doctor --json outputs a single parseable JSON object on stdout', () => {
+  it('--json output contains no extra stdout lines (no banners, headers)', async () => {
     const tmp = mkTmpDir();
     try {
-      const out = runPd(['config', 'doctor', '--workspace', tmp, '--json'], workspaceRoot);
-      expect(out).toBeDefined();
-      const parsed = JSON.parse(out);
-      expect(typeof parsed).toBe('object');
-      expect(parsed).not.toBeNull();
-      expect(parsed).toHaveProperty('status');
-      expect(parsed).toHaveProperty('workspaceDir');
-      expect(parsed).toHaveProperty('pdConfigPaths');
-      expect(parsed).toHaveProperty('openclawConfigPaths');
-      expect(parsed).toHaveProperty('featureFlags');
-      expect(parsed).toHaveProperty('providerHealth');
-      expect(parsed).toHaveProperty('warnings');
-      expect(parsed).toHaveProperty('nextActions');
+      await handleConfigDoctor({ workspace: tmp, json: true });
+      expect(stdoutSpy).toHaveBeenCalledTimes(1);
+      const output = stdoutSpy.mock.calls[0][0] as string;
+      expect(() => JSON.parse(output)).not.toThrow();
     } finally { rmTmpDir(tmp); }
   });
-
-  it('pd config doctor --workspace <missing> still emits structured JSON (no crash)', () => {
-    const out = runPd(['config', 'doctor', '--workspace', '/nonexistent/workspace/path/x9z', '--json'], workspaceRoot);
-    const parsed = JSON.parse(out);
-    expect(parsed.status).toBe('failed');
-    expect(parsed.providerHealth).toBeInstanceOf(Array);
-    expect(parsed.nextActions).toBeInstanceOf(Array);
-  });
 });
-
-// ─── Helpers for CLI tests ───────────────────────────────────────────────────
-
-function runPd(args: string[], cwd: string): string {
-  try {
-    return execFileSync('node', ['packages/pd-cli/dist/index.js', ...args], {
-      encoding: 'utf8',
-      cwd,
-    });
-  } catch (err: unknown) {
-    if (err && typeof err === 'object' && 'stdout' in err) {
-      return String((err as { stdout: unknown }).stdout);
-    }
-    throw err;
-  }
-}
-
-// ─── Helpers for state.db planting ───────────────────────────────────────────
-
-async function plantStateDbWithMessage(workspaceDir: string, errorMessage: string): Promise<void> {
-  let Database: typeof import('better-sqlite3');
-  try {
-    Database = (await import('better-sqlite3')).default;
-  } catch {
-    // better-sqlite3 not available; tests requiring this will be skipped.
-    return;
-  }
-  const pdDir = path.join(workspaceDir, '.pd');
-  fs.mkdirSync(pdDir, { recursive: true });
-  const dbPath = path.join(pdDir, 'state.db');
-  const db = new Database(dbPath);
-  try {
-    db.exec(`
-      CREATE TABLE IF NOT EXISTS tasks (
-        task_id TEXT,
-        kind TEXT,
-        status TEXT,
-        error_message TEXT,
-        error_category TEXT,
-        updated_at INTEGER
-      );
-    `);
-    const now = Date.now();
-    const insert = db.prepare(
-      `INSERT INTO tasks (task_id, kind, status, error_message, error_category, updated_at)
-       VALUES (?, ?, ?, ?, ?, ?)`,
-    );
-    insert.run('test-task-1', 'diagnostician', 'failed', errorMessage, 'rate_limit', now);
-    insert.run('test-task-2', 'diagnostician', 'failed', 'previous unrelated error', 'other', now - 60_000);
-  } finally {
-    db.close();
-  }
-}