@principles/pd-cli 1.73.0

package/tests/commands/health.test.ts

@@ -0,0 +1,330 @@
+/**
+ * pd health command unit tests.
+ *
+ * Tests the health command's external contract via mocked read models.
+ * Tests JSON/text output formatting, exit code behavior, and error handling.
+ * Covers both the no-database path and the state.db path (PainChainReadModel).
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+const {
+  mockPruningGetHealthSummary,
+  mockAuditCandidateLedgerConsistency,
+  mockGetLastSuccessfulChain,
+  mockPainChainClose,
+  mockExistsSync,
+  mockDbPrepare,
+  mockDbAll,
+  mockDbClose,
+} = vi.hoisted(() => {
+  return {
+    mockPruningGetHealthSummary: vi.fn(),
+    mockAuditCandidateLedgerConsistency: vi.fn(),
+    mockGetLastSuccessfulChain: vi.fn(),
+    mockPainChainClose: vi.fn().mockResolvedValue(undefined),
+    mockExistsSync: vi.fn(),
+    mockDbPrepare: vi.fn(),
+    mockDbAll: vi.fn(),
+    mockDbClose: vi.fn(),
+  };
+});
+
+vi.mock('@principles/core/runtime-v2', () => ({
+  PruningReadModel: vi.fn().mockImplementation(function () {
+    return { getHealthSummary: mockPruningGetHealthSummary };
+  }),
+  PainChainReadModel: vi.fn().mockImplementation(function () {
+    return { getLastSuccessfulChain: mockGetLastSuccessfulChain, close: mockPainChainClose };
+  }),
+  auditCandidateLedgerConsistency: mockAuditCandidateLedgerConsistency,
+  getLedgerFilePathPublic: vi.fn().mockReturnValue('/fake/workspace/.state/principle_training_state.json'),
+}));
+
+vi.mock('../../src/resolve-workspace.js', () => ({
+  resolveWorkspaceDir: vi.fn().mockReturnValue('/fake/workspace'),
+}));
+
+vi.mock('fs', () => ({
+  existsSync: mockExistsSync,
+}));
+
+vi.mock('better-sqlite3', () => {
+  return {
+    default: vi.fn().mockImplementation(() => {
+      return {
+        prepare: mockDbPrepare.mockReturnValue({ all: mockDbAll }),
+        close: mockDbClose,
+      };
+    }),
+  };
+});
+
+import { handleHealth } from '../../src/commands/health.js';
+
+const WS = '/fake/workspace';
+
+function healthyPruningSummary() {
+  return {
+    totalPrinciples: 5,
+    byStatus: { probation: 3, active: 2 },
+  };
+}
+
+function healthyLastChain() {
+  return {
+    painId: 'pain_001',
+    taskId: 'diagnosis_pain_001',
+    runId: 'run_001',
+    artifactId: 'art_001',
+    candidateIds: ['c1'],
+    ledgerEntryIds: ['l1'],
+    status: 'succeeded',
+    latencyMs: {
+      painToTask: 100,
+      taskToRun: 200,
+      runToArtifact: 50,
+    },
+    failureCategory: null,
+    checkedAt: '2026-05-03T12:00:00.000Z',
+    missingLinks: [],
+  };
+}
+
+function mockProcessExit() {
+  return vi.spyOn(process, 'exit').mockImplementation((() => undefined) as () => never);
+}
+
+describe('handleHealth', () => {
+  let consoleLogSpy: ReturnType<typeof vi.spyOn>;
+  let consoleWarnSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    process.exitCode = undefined;
+    consoleLogSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    consoleWarnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    mockExistsSync.mockReturnValue(false);
+  });
+
+  afterEach(() => {
+    consoleLogSpy.mockRestore();
+    consoleWarnSpy.mockRestore();
+  });
+
+  describe('without state.db', () => {
+    it('outputs health report with pruning summary and audit results', async () => {
+      mockPruningGetHealthSummary.mockReturnValue(healthyPruningSummary());
+      mockAuditCandidateLedgerConsistency.mockResolvedValue({ missingLedgerCount: 0 });
+
+      await handleHealth({ workspace: WS, json: true });
+
+      expect(consoleLogSpy).toHaveBeenCalled();
+      const jsonOutput = JSON.parse(consoleLogSpy.mock.calls[0][0]);
+      expect(jsonOutput.generatedAt).toBeDefined();
+      expect(jsonOutput.workspace).toBe(WS);
+      expect(jsonOutput.ledger.totalPrinciples).toBe(5);
+      expect(jsonOutput.ledger.byStatus).toEqual({ probation: 3, active: 2 });
+      expect(jsonOutput.candidateLedgerConsistency.status).toBe('ok');
+      expect(jsonOutput.candidateLedgerConsistency.missing).toBe(0);
+      expect(jsonOutput.pdStateDb.exists).toBe(false);
+    });
+
+    it('outputs readable text format', async () => {
+      mockPruningGetHealthSummary.mockReturnValue(healthyPruningSummary());
+      mockAuditCandidateLedgerConsistency.mockResolvedValue({ missingLedgerCount: 0 });
+
+      await handleHealth({ workspace: WS, json: false });
+
+      const allOutput = consoleLogSpy.mock.calls.map(c => c.join(' ')).join('\n');
+      expect(allOutput).toContain(`workspace: ${WS}`);
+      expect(allOutput).toContain('ledger.totalPrinciples: 5');
+      expect(allOutput).toContain('candidateLedgerConsistency.status: ok');
+      expect(allOutput).toContain('pdStateDb.exists: false');
+    });
+
+    it('reports zero candidate and task counts', async () => {
+      mockPruningGetHealthSummary.mockReturnValue(healthyPruningSummary());
+      mockAuditCandidateLedgerConsistency.mockResolvedValue({ missingLedgerCount: 0 });
+
+      await handleHealth({ workspace: WS, json: false });
+
+      const allOutput = consoleLogSpy.mock.calls.map(c => c.join(' ')).join('\n');
+      expect(allOutput).toContain('candidates.total: 0');
+      expect(allOutput).toContain('tasks.total: 0');
+    });
+
+    it('reports degraded consistency with exit code 1', async () => {
+      mockPruningGetHealthSummary.mockReturnValue(healthyPruningSummary());
+      mockAuditCandidateLedgerConsistency.mockResolvedValue({ missingLedgerCount: 2 });
+      const exitSpy = mockProcessExit();
+
+      await handleHealth({ workspace: WS, json: false });
+
+      expect(consoleWarnSpy).toHaveBeenCalledWith(expect.stringContaining('DEGRADED'));
+      expect(exitSpy).toHaveBeenCalledWith(1);
+
+      exitSpy.mockRestore();
+    });
+
+    it('outputs degraded consistency JSON with exit code 1', async () => {
+      mockPruningGetHealthSummary.mockReturnValue(healthyPruningSummary());
+      mockAuditCandidateLedgerConsistency.mockResolvedValue({ missingLedgerCount: 2 });
+      const exitSpy = mockProcessExit();
+
+      await handleHealth({ workspace: WS, json: true });
+
+      const jsonOutput = JSON.parse(consoleLogSpy.mock.calls[0][0]);
+      expect(jsonOutput.candidateLedgerConsistency.status).toBe('degraded');
+      expect(jsonOutput.candidateLedgerConsistency.missing).toBe(2);
+      expect(exitSpy).toHaveBeenCalledWith(1);
+
+      exitSpy.mockRestore();
+    });
+
+    it('does not include lastSuccessfulChain when no database exists', async () => {
+      mockPruningGetHealthSummary.mockReturnValue(healthyPruningSummary());
+      mockAuditCandidateLedgerConsistency.mockResolvedValue({ missingLedgerCount: 0 });
+
+      await handleHealth({ workspace: WS, json: true });
+
+      const jsonOutput = JSON.parse(consoleLogSpy.mock.calls[0][0]);
+      expect(jsonOutput.lastSuccessfulChain).toBeUndefined();
+    });
+  });
+
+  describe('with state.db', () => {
+    beforeEach(() => {
+      mockExistsSync.mockImplementation((p: string) => {
+        if (p.includes('state.db')) return true;
+        return false;
+      });
+      mockDbPrepare.mockReturnValue({ all: mockDbAll });
+      mockDbAll.mockReturnValue([]);
+    });
+
+    it('reads candidate counts from database', async () => {
+      mockPruningGetHealthSummary.mockReturnValue(healthyPruningSummary());
+      mockAuditCandidateLedgerConsistency.mockResolvedValue({ missingLedgerCount: 0 });
+      mockDbAll
+        .mockReturnValueOnce([{ total: 3, status: 'consumed' }, { total: 2, status: 'pending' }])
+        .mockReturnValueOnce([]);
+
+      await handleHealth({ workspace: WS, json: true });
+
+      const jsonOutput = JSON.parse(consoleLogSpy.mock.calls[0][0]);
+      expect(jsonOutput.pdStateDb.exists).toBe(true);
+      expect(jsonOutput.candidates.total).toBe(5);
+      expect(jsonOutput.candidates.consumed).toBe(3);
+      expect(jsonOutput.candidates.pending).toBe(2);
+    });
+
+    it('reads task counts from database', async () => {
+      mockPruningGetHealthSummary.mockReturnValue(healthyPruningSummary());
+      mockAuditCandidateLedgerConsistency.mockResolvedValue({ missingLedgerCount: 0 });
+      mockDbAll
+        .mockReturnValueOnce([])
+        .mockReturnValueOnce([{ total: 4, status: 'succeeded' }, { total: 1, status: 'failed' }]);
+
+      await handleHealth({ workspace: WS, json: true });
+
+      const jsonOutput = JSON.parse(consoleLogSpy.mock.calls[0][0]);
+      expect(jsonOutput.tasks.total).toBe(5);
+      expect(jsonOutput.tasks.byStatus).toEqual({ succeeded: 4, failed: 1 });
+    });
+
+    it('includes lastSuccessfulChain from PainChainReadModel', async () => {
+      mockPruningGetHealthSummary.mockReturnValue(healthyPruningSummary());
+      mockAuditCandidateLedgerConsistency.mockResolvedValue({ missingLedgerCount: 0 });
+      mockGetLastSuccessfulChain.mockResolvedValue(healthyLastChain());
+
+      await handleHealth({ workspace: WS, json: true });
+
+      const jsonOutput = JSON.parse(consoleLogSpy.mock.calls[0][0]);
+      expect(jsonOutput.lastSuccessfulChain).toBeDefined();
+      expect(jsonOutput.lastSuccessfulChain.taskId).toBe('diagnosis_pain_001');
+      expect(jsonOutput.lastSuccessfulChain.runId).toBe('run_001');
+      expect(jsonOutput.lastSuccessfulChain.artifactId).toBe('art_001');
+      expect(jsonOutput.lastSuccessfulChain.candidateIds).toEqual(['c1']);
+      expect(jsonOutput.lastSuccessfulChain.ledgerEntryIds).toEqual(['l1']);
+    });
+
+    it('computes totalMs latency from chain trace', async () => {
+      mockPruningGetHealthSummary.mockReturnValue(healthyPruningSummary());
+      mockAuditCandidateLedgerConsistency.mockResolvedValue({ missingLedgerCount: 0 });
+      mockGetLastSuccessfulChain.mockResolvedValue(healthyLastChain());
+
+      await handleHealth({ workspace: WS, json: true });
+
+      const jsonOutput = JSON.parse(consoleLogSpy.mock.calls[0][0]);
+      expect(jsonOutput.lastSuccessfulChain.latencyMs).toBeDefined();
+      expect(jsonOutput.lastSuccessfulChain.latencyMs.totalMs).toBe(350);
+    });
+
+    it('closes PainChainReadModel after use', async () => {
+      mockPruningGetHealthSummary.mockReturnValue(healthyPruningSummary());
+      mockAuditCandidateLedgerConsistency.mockResolvedValue({ missingLedgerCount: 0 });
+      mockGetLastSuccessfulChain.mockResolvedValue(healthyLastChain());
+
+      await handleHealth({ workspace: WS, json: true });
+
+      expect(mockPainChainClose).toHaveBeenCalled();
+    });
+
+    it('closes database after use', async () => {
+      mockPruningGetHealthSummary.mockReturnValue(healthyPruningSummary());
+      mockAuditCandidateLedgerConsistency.mockResolvedValue({ missingLedgerCount: 0 });
+      mockGetLastSuccessfulChain.mockResolvedValue(healthyLastChain());
+
+      await handleHealth({ workspace: WS, json: true });
+
+      expect(mockDbClose).toHaveBeenCalled();
+    });
+
+    it('sets partialHealth when PainChainReadModel throws', async () => {
+      mockPruningGetHealthSummary.mockReturnValue(healthyPruningSummary());
+      mockAuditCandidateLedgerConsistency.mockResolvedValue({ missingLedgerCount: 0 });
+      mockGetLastSuccessfulChain.mockRejectedValue(new Error('Chain read error'));
+
+      await handleHealth({ workspace: WS, json: true });
+
+      const jsonOutput = JSON.parse(consoleLogSpy.mock.calls[0][0]);
+      expect(jsonOutput.partialHealth).toBe(true);
+      expect(jsonOutput.lastSuccessfulChain).toBeUndefined();
+    });
+
+    it('sets partialHealth when database read throws', async () => {
+      mockPruningGetHealthSummary.mockReturnValue(healthyPruningSummary());
+      mockAuditCandidateLedgerConsistency.mockResolvedValue({ missingLedgerCount: 0 });
+      mockDbPrepare.mockImplementation(() => { throw new Error('Corrupt DB'); });
+
+      await handleHealth({ workspace: WS, json: true });
+
+      const jsonOutput = JSON.parse(consoleLogSpy.mock.calls[0][0]);
+      expect(jsonOutput.partialHealth).toBe(true);
+    });
+
+    it('handles missing lastSuccessfulChain gracefully', async () => {
+      mockPruningGetHealthSummary.mockReturnValue(healthyPruningSummary());
+      mockAuditCandidateLedgerConsistency.mockResolvedValue({ missingLedgerCount: 0 });
+      mockGetLastSuccessfulChain.mockResolvedValue(undefined);
+
+      await handleHealth({ workspace: WS, json: true });
+
+      const jsonOutput = JSON.parse(consoleLogSpy.mock.calls[0][0]);
+      expect(jsonOutput.lastSuccessfulChain).toBeUndefined();
+    });
+
+    it('includes lastSuccessfulChain in text output', async () => {
+      mockPruningGetHealthSummary.mockReturnValue(healthyPruningSummary());
+      mockAuditCandidateLedgerConsistency.mockResolvedValue({ missingLedgerCount: 0 });
+      mockGetLastSuccessfulChain.mockResolvedValue(healthyLastChain());
+
+      await handleHealth({ workspace: WS, json: false });
+
+      const allOutput = consoleLogSpy.mock.calls.map(c => c.join(' ')).join('\n');
+      expect(allOutput).toContain('lastSuccessfulChain:');
+      expect(allOutput).toContain('taskId:');
+      expect(allOutput).toContain('diagnosis_pain_001');
+    });
+  });
+});

package/tests/commands/pain-record.test.ts

@@ -0,0 +1,316 @@
+/**
+ * pd pain record command unit tests.
+ *
+ * Tests the CLI adapter layer: validation, service delegation, output formatting.
+ * PainToPrincipleService is mocked — its own contract is tested separately.
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+// ── Mock setup ──────────────────────────────────────────────────────────────
+
+let mockRecordPainResult: PainToPrincipleOutput;
+let lastRecordPainInput: PainToPrincipleInput | null = null;
+
+vi.mock('../../src/resolve-workspace.js', () => ({
+  resolveWorkspaceDir: vi.fn().mockReturnValue('/tmp/fake-workspace'),
+}));
+
+vi.mock('@principles/core/runtime-v2', () => ({
+  PainToPrincipleService: vi.fn().mockImplementation(function() {
+    return {
+      recordPain: vi.fn(async (input: PainToPrincipleInput) => {
+        lastRecordPainInput = input;
+        return mockRecordPainResult;
+      }),
+    };
+  }),
+  PrincipleTreeLedgerAdapter: vi.fn().mockImplementation(function() { return {}; }),
+  resolveRuntimeConfig: vi.fn().mockReturnValue({
+    runtimeKind: 'pi-ai',
+    provider: 'test-provider',
+    model: 'test-model',
+    apiKeyEnv: 'TEST_KEY',
+    timeoutMs: 300000,
+    agentId: 'main',
+  }),
+  isRuntimeConfigError: vi.fn().mockReturnValue(false),
+}));
+
+import { handlePainRecord } from '../../src/commands/pain-record.js';
+import type { PainToPrincipleOutput, PainToPrincipleInput, FailureCategory } from '@principles/core/runtime-v2';
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+function mockProcessExit() {
+  return vi.spyOn(process, 'exit').mockImplementation((() => undefined) as () => never);
+}
+
+const SUCCEEDED_RESULT: PainToPrincipleOutput = {
+  status: 'succeeded',
+  painId: 'manual_123_abc',
+  taskId: 'diagnosis_manual_123_abc',
+  runId: 'run-001',
+  artifactId: 'art-001',
+  candidateIds: ['c1'],
+  ledgerEntryIds: ['l1'],
+  observabilityWarnings: [],
+  latencyMs: 42,
+};
+
+function makeFailedResult(overrides?: Partial<PainToPrincipleOutput>): PainToPrincipleOutput {
+  return {
+    status: 'failed',
+    painId: 'manual_123_abc',
+    taskId: 'diagnosis_manual_123_abc',
+    candidateIds: [],
+    ledgerEntryIds: [],
+    message: 'something went wrong',
+    observabilityWarnings: [],
+    failureCategory: 'runtime_unavailable' as FailureCategory,
+    latencyMs: 10,
+    ...overrides,
+  };
+}
+
+function makeSkippedResult(overrides?: Partial<PainToPrincipleOutput>): PainToPrincipleOutput {
+  return {
+    status: 'skipped',
+    painId: 'manual_123_abc',
+    taskId: 'diagnosis_manual_123_abc',
+    candidateIds: [],
+    ledgerEntryIds: [],
+    message: 'already leased',
+    observabilityWarnings: [],
+    latencyMs: 5,
+    ...overrides,
+  };
+}
+
+// ── Tests ───────────────────────────────────────────────────────────────────
+
+describe('pd pain record', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockRecordPainResult = { ...SUCCEEDED_RESULT };
+    lastRecordPainInput = null;
+  });
+
+  // 1. --reason required
+  it('exits 1 when --reason is missing', async () => {
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    const exitSpy = mockProcessExit();
+
+    await handlePainRecord({ reason: undefined });
+
+    expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('--reason'));
+    expect(exitSpy).toHaveBeenCalledWith(1);
+
+    errorSpy.mockRestore();
+    exitSpy.mockRestore();
+  });
+
+  // 2. --score out of range
+  it('exits 1 when --score is out of range', async () => {
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    const exitSpy = mockProcessExit();
+
+    await handlePainRecord({ reason: 'test', score: 150 });
+
+    expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('--score'));
+    expect(exitSpy).toHaveBeenCalledWith(1);
+
+    errorSpy.mockRestore();
+    exitSpy.mockRestore();
+  });
+
+  // 3. Happy path --json output
+  it('outputs JSON with all fields on success (--json)', async () => {
+    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    const exitSpy = mockProcessExit();
+
+    await handlePainRecord({ reason: 'test pain', json: true });
+
+    expect(logSpy).toHaveBeenCalled();
+    const jsonOutput = JSON.parse(logSpy.mock.calls[0][0]);
+    expect(jsonOutput.status).toBe('succeeded');
+    expect(jsonOutput.painId).toBe('manual_123_abc');
+    expect(jsonOutput.taskId).toBe('diagnosis_manual_123_abc');
+    expect(jsonOutput.runId).toBe('run-001');
+    expect(jsonOutput.artifactId).toBe('art-001');
+    expect(jsonOutput.candidateIds).toEqual(['c1']);
+    expect(jsonOutput.ledgerEntryIds).toEqual(['l1']);
+    expect(jsonOutput.observabilityWarnings).toEqual([]);
+    expect(jsonOutput.latencyMs).toBe(42);
+    expect(exitSpy).not.toHaveBeenCalledWith(1);
+
+    logSpy.mockRestore();
+    exitSpy.mockRestore();
+  });
+
+  // 4. Happy path text output
+  it('outputs human-readable summary on success (text)', async () => {
+    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    const exitSpy = mockProcessExit();
+
+    await handlePainRecord({ reason: 'test pain' });
+
+    expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('[OK]'));
+    expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('manual_123_abc'));
+    expect(exitSpy).not.toHaveBeenCalledWith(1);
+
+    logSpy.mockRestore();
+    exitSpy.mockRestore();
+  });
+
+  // 5. Failed exits 1 with --json
+  it('exits 1 on failed status (--json)', async () => {
+    mockRecordPainResult = makeFailedResult();
+    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    const exitSpy = mockProcessExit();
+
+    await handlePainRecord({ reason: 'test pain', json: true });
+
+    const jsonOutput = JSON.parse(logSpy.mock.calls[0][0]);
+    expect(jsonOutput.status).toBe('failed');
+    expect(exitSpy).toHaveBeenCalledWith(1);
+
+    logSpy.mockRestore();
+    exitSpy.mockRestore();
+  });
+
+  // 6. Failed exits 1 (text)
+  it('exits 1 on failed status (text)', async () => {
+    mockRecordPainResult = makeFailedResult();
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    const exitSpy = mockProcessExit();
+
+    await handlePainRecord({ reason: 'test pain' });
+
+    const firstErrorArg = errorSpy.mock.calls[0]?.[0] ?? '';
+    expect(firstErrorArg).toContain('[FAIL]');
+    expect(exitSpy).toHaveBeenCalledWith(1);
+
+    errorSpy.mockRestore();
+    exitSpy.mockRestore();
+  });
+
+  // 7. config_missing shows diagnostic guidance
+  it('shows diagnostic guidance on config_missing failure', async () => {
+    mockRecordPainResult = makeFailedResult({
+      failureCategory: 'config_missing' as FailureCategory,
+      message: 'API key not found in env',
+    });
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    const exitSpy = mockProcessExit();
+
+    await handlePainRecord({ reason: 'test pain' });
+
+    const allErrorOutput = errorSpy.mock.calls.map(c => c.join(' ')).join('\n');
+    expect(allErrorOutput).toContain('Error: Pain signal failed');
+    expect(exitSpy).toHaveBeenCalledWith(1);
+
+    errorSpy.mockRestore();
+    exitSpy.mockRestore();
+  });
+
+  // 7a. config_missing with RuntimeConfigError exits non-zero (text)
+  it('exits 1 on config_missing with RuntimeConfigError (text)', async () => {
+    mockRecordPainResult = makeFailedResult({
+      failureCategory: 'config_missing' as FailureCategory,
+      message: 'API key not found in env',
+    });
+    const { isRuntimeConfigError, resolveRuntimeConfig } = await import('@principles/core/runtime-v2');
+    vi.mocked(isRuntimeConfigError).mockReturnValueOnce(true);
+    vi.mocked(resolveRuntimeConfig).mockReturnValueOnce({
+      ok: false,
+      reason: 'missing_openclaw_mode',
+      message: 'runtimeKind is openclaw-cli but no mode specified',
+      nextAction: 'Provide exactly one mode',
+    });
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    const exitSpy = mockProcessExit();
+
+    await handlePainRecord({ reason: 'test pain' });
+
+    expect(exitSpy).toHaveBeenCalledWith(1);
+
+    errorSpy.mockRestore();
+    exitSpy.mockRestore();
+  });
+
+  // 7b. config_missing with RuntimeConfigError outputs JSON (--json)
+  it('outputs JSON with configError on config_missing + RuntimeConfigError (--json)', async () => {
+    mockRecordPainResult = makeFailedResult({
+      failureCategory: 'config_missing' as FailureCategory,
+      message: 'API key not found in env',
+    });
+    const { isRuntimeConfigError, resolveRuntimeConfig } = await import('@principles/core/runtime-v2');
+    vi.mocked(isRuntimeConfigError).mockReturnValueOnce(true);
+    vi.mocked(resolveRuntimeConfig).mockReturnValueOnce({
+      ok: false,
+      reason: 'missing_openclaw_mode',
+      message: 'runtimeKind is openclaw-cli but no mode specified',
+      nextAction: 'Provide exactly one mode',
+    });
+    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    const exitSpy = mockProcessExit();
+
+    await handlePainRecord({ reason: 'test pain', json: true });
+
+    const jsonOutput = JSON.parse(logSpy.mock.calls[0][0]);
+    expect(jsonOutput.status).toBe('failed');
+    expect(jsonOutput.failureCategory).toBe('config_missing');
+    expect(jsonOutput.configError).toBeDefined();
+    expect(jsonOutput.configError.reason).toBe('missing_openclaw_mode');
+    expect(jsonOutput.configError.nextAction).toBe('Provide exactly one mode');
+    expect(exitSpy).toHaveBeenCalledWith(1);
+
+    logSpy.mockRestore();
+    exitSpy.mockRestore();
+  });
+
+  // 8. skipped status outputs [SKIP] and does not exit 1
+  it('outputs [SKIP] on skipped status (text)', async () => {
+    mockRecordPainResult = makeSkippedResult();
+    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    const exitSpy = mockProcessExit();
+
+    await handlePainRecord({ reason: 'test pain' });
+
+    const allOutput = logSpy.mock.calls.map(c => c.join(' ')).join(' ');
+    expect(allOutput).toContain('[SKIP]');
+    expect(exitSpy).not.toHaveBeenCalledWith(1);
+
+    logSpy.mockRestore();
+    exitSpy.mockRestore();
+  });
+
+  // 9. skipped status with --json does not exit 1
+  it('outputs skipped status in JSON without exit 1', async () => {
+    mockRecordPainResult = makeSkippedResult();
+    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    const exitSpy = mockProcessExit();
+
+    await handlePainRecord({ reason: 'test pain', json: true });
+
+    const jsonOutput = JSON.parse(logSpy.mock.calls[0][0]);
+    expect(jsonOutput.status).toBe('skipped');
+    expect(exitSpy).not.toHaveBeenCalledWith(1);
+
+    logSpy.mockRestore();
+    exitSpy.mockRestore();
+  });
+
+  // 10. recordPain called with correct arguments
+  it('passes correct arguments to recordPain', async () => {
+    await handlePainRecord({ reason: 'test pain', score: 90, source: 'ci' });
+
+    expect(lastRecordPainInput).toBeTruthy();
+    expect(lastRecordPainInput!.painType).toBe('user_frustration');
+    expect(lastRecordPainInput!.source).toBe('ci');
+    expect(lastRecordPainInput!.reason).toBe('test pain');
+    expect(lastRecordPainInput!.score).toBe(90);
+    expect(lastRecordPainInput!.sessionId).toBe('cli');
+    expect(lastRecordPainInput!.agentId).toBe('pd-cli');
+  });
+});