@principles/pd-cli 1.145.1 → 1.146.0

package/tests/commands/build-trajectory-evidence.test.ts

@@ -1,5 +1,7 @@
 /**
- * Tests for buildTrajectoryEvidenceFromDb — PRI-341
+ * Tests for acquireTrajectoryEvidenceFromDb — PRI-341 extraction behavior,
+ * PRI-642 typed classification (the legacy array wrapper was removed with
+ * its last production consumer).
  *
  * Uses real temporary SQLite DBs (trajectory.db) to validate evidence extraction.
  */
@@ -9,7 +11,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
 import { MAX_EVIDENCE_ENTRIES } from '@principles/core/runtime-v2';
-import { buildTrajectoryEvidenceFromDb } from '../../src/commands/build-trajectory-evidence.js';
+import { acquireTrajectoryEvidenceFromDb } from '../../src/commands/build-trajectory-evidence.js';
 
 // ── Helpers ─────────────────────────────────────────────────────────────────
 
@@ -127,7 +129,7 @@ function insertToolCall(
 
 // ── Tests ───────────────────────────────────────────────────────────────────
 
-describe('buildTrajectoryEvidenceFromDb — PRI-341', () => {
+describe('acquireTrajectoryEvidenceFromDb — behavior via typed API (PRI-341 extraction, PRI-642 wrapper removal)', () => {
   beforeEach(() => {
     createStateDir();
   });
@@ -140,198 +142,261 @@ describe('buildTrajectoryEvidenceFromDb — PRI-341', () => {
     }
   });
 
-  // 用例 A: trajectory.db contains 3 assistant turns for session '123'
-  // → returns evidence with length ≤ MAX_EVIDENCE_ENTRIES, each entry has sourceRef and note
-  it('A: returns evidence entries from assistant turns (≤ MAX_EVIDENCE_ENTRIES)', () => {
+  /** Available-class entries, or the unavailable reason for assertions. */
+  function acquire(sessionId: string | undefined) {
+    return acquireTrajectoryEvidenceFromDb(stateDir, sessionId, tmpDir);
+  }
+
+  function entriesOf(sessionId: string) {
+    const result = acquire(sessionId);
+    expect(result.status).toBe('available');
+    return result.status === 'available' ? result.entries : [];
+  }
+
+  function insertSession(db: Database.Database, sessionId: string): void {
+    db.prepare('INSERT INTO sessions (session_id, started_at, updated_at) VALUES (?, ?, ?)')
+      .run(sessionId, '2026-01-01T09:00:00Z', '2026-01-01T09:00:00Z');
+  }
+
+  it('returns available entries (≤ MAX_EVIDENCE_ENTRIES) from assistant turns', () => {
     const db = createTrajectoryDb();
+    insertSession(db, '123');
     insertAssistantTurn(db, '123', 'First assistant response about backups', '2026-01-01T10:00:00Z');
     insertAssistantTurn(db, '123', 'Second response about validation', '2026-01-01T10:01:00Z');
     insertAssistantTurn(db, '123', 'Third response about error handling', '2026-01-01T10:02:00Z');
     db.close();
 
-    const evidence = buildTrajectoryEvidenceFromDb(stateDir, '123', tmpDir);
+    const entries = entriesOf('123');
 
-    expect(evidence.length).toBeGreaterThan(0);
-    expect(evidence.length).toBeLessThanOrEqual(MAX_EVIDENCE_ENTRIES);
-    for (const entry of evidence) {
+    expect(entries.length).toBeGreaterThan(0);
+    expect(entries.length).toBeLessThanOrEqual(MAX_EVIDENCE_ENTRIES);
+    for (const entry of entries) {
       expect(entry.sourceRef).toBeTruthy();
       expect(entry.note).toBeTruthy();
-      expect(typeof entry.sourceRef).toBe('string');
-      expect(typeof entry.note).toBe('string');
     }
   });
 
-  // 用例 B: sessionId is undefined or trajectory.db doesn't exist
-  // → returns placeholder entry, does not throw, does not return empty array
-  it('B: returns placeholder when sessionId is undefined', () => {
-    const evidence = buildTrajectoryEvidenceFromDb(stateDir, undefined, tmpDir);
+  it('classifies an undefined session as session_not_found (no placeholder entries)', () => {
+    const db = createTrajectoryDb();
+    db.close();
+    const result = acquire(undefined);
+    expect(result.status).toBe('unavailable');
+    if (result.status !== 'unavailable') return;
+    expect(result.reasonCode).toBe('session_not_found');
+  });
 
-    expect(evidence.length).toBeGreaterThan(0);
-    expect(evidence[0].sourceRef).toBe('owner_reported:cli');
-    expect(evidence[0].note).toBeTruthy();
+  it('surfaces user correction turns with correctionDetected=true', () => {
+    const db = createTrajectoryDb();
+    insertSession(db, '123');
+    insertUserTurn(db, '123', 'Please fix the backup logic', true, '2026-01-01T09:59:00Z');
+    insertAssistantTurn(db, '123', 'I will fix the backup logic', '2026-01-01T10:00:00Z');
+    db.close();
+
+    const entries = entriesOf('123');
+
+    const ownerEntry = entries.find(e => e.sourceRef.startsWith('owner_message:'));
+    expect(ownerEntry).toBeDefined();
+    expect(ownerEntry!.note).toContain('fix the backup logic');
   });
 
-  it('B2: returns placeholder when trajectory.db does not exist', () => {
-    const evidence = buildTrajectoryEvidenceFromDb(stateDir, 'some-session', tmpDir);
+  it('extracts failed tool_calls as evidence entries (PRI-358)', () => {
+    const db = createTrajectoryDb();
+    insertSession(db, '123');
+    insertToolCall(db, '123', 'bash', 'failure', 'non_zero_exit', 1, '2026-01-01T10:00:00Z');
+    insertToolCall(db, '123', 'write_file', 'success', null, 0, '2026-01-01T10:01:00Z');
+    insertToolCall(db, '123', 'bash', 'failure', 'timeout', 124, '2026-01-01T10:02:00Z');
+    db.close();
+
+    const entries = entriesOf('123');
 
-    expect(evidence.length).toBeGreaterThan(0);
-    expect(evidence[0].sourceRef).toBe('owner_reported:cli');
+    const failureEntries = entries.filter(e => e.sourceRef.startsWith('tool_call_failure:'));
+    expect(failureEntries.length).toBe(2);
+    expect(failureEntries[0].note).toContain('bash');
+    expect(failureEntries[0].note).toContain('non_zero_exit');
+    expect(failureEntries[1].note).toContain('timeout');
   });
 
-  it('B3: returns placeholder when sessionId is "cli"', () => {
-    const evidence = buildTrajectoryEvidenceFromDb(stateDir, 'cli', tmpDir);
+  it('limits failed tool_calls to 3 entries', () => {
+    const db = createTrajectoryDb();
+    insertSession(db, '123');
+    insertToolCall(db, '123', 'bash', 'failure', 'err1', 1, '2026-01-01T10:00:00Z');
+    insertToolCall(db, '123', 'bash', 'failure', 'err2', 2, '2026-01-01T10:01:00Z');
+    insertToolCall(db, '123', 'bash', 'failure', 'err3', 3, '2026-01-01T10:02:00Z');
+    insertToolCall(db, '123', 'bash', 'failure', 'err4', 4, '2026-01-01T10:03:00Z');
+    db.close();
+
+    const entries = entriesOf('123');
 
-    expect(evidence.length).toBeGreaterThan(0);
-    expect(evidence[0].sourceRef).toBe('owner_reported:cli');
+    const failureEntries = entries.filter(e => e.sourceRef.startsWith('tool_call_failure:'));
+    expect(failureEntries.length).toBe(3);
   });
 
-  // Additional: user correction turns are surfaced
-  it('surfaces user correction turns with correctionDetected=true', () => {
+  it('handles a missing tool_calls table gracefully (classified unavailable, no throw)', () => {
+    const dbPath = path.join(stateDir, 'trajectory.db');
+    const db = new Database(dbPath);
+    db.exec("CREATE TABLE IF NOT EXISTS sessions (session_id TEXT PRIMARY KEY, started_at TEXT, updated_at TEXT)");
+    db.exec("CREATE TABLE IF NOT EXISTS assistant_turns (id INTEGER PRIMARY KEY AUTOINCREMENT, session_id TEXT NOT NULL, sanitized_text TEXT, created_at TEXT NOT NULL)");
+    db.exec("CREATE TABLE IF NOT EXISTS user_turns (id INTEGER PRIMARY KEY AUTOINCREMENT, session_id TEXT NOT NULL, turn_index INTEGER NOT NULL DEFAULT 0, raw_excerpt TEXT, correction_detected INTEGER NOT NULL DEFAULT 0, created_at TEXT NOT NULL)");
+    db.prepare('INSERT INTO sessions (session_id, started_at, updated_at) VALUES (?, ?, ?)').run('123', '2026-01-01T09:00:00Z', '2026-01-01T09:00:00Z');
+    db.close();
+
+    const result = acquire('123');
+    expect(result.status).toBe('unavailable');
+    if (result.status !== 'unavailable') return;
+    expect(['empty_trajectory', 'evidence_read_failed']).toContain(result.reasonCode);
+  });
+
+  it('includes resultPreview in tool failure evidence note', () => {
     const db = createTrajectoryDb();
-    insertUserTurn(db, '123', 'Please fix the backup logic', true, '2026-01-01T09:59:00Z');
-    insertAssistantTurn(db, '123', 'I will fix the backup logic', '2026-01-01T10:00:00Z');
+    insertSession(db, '123');
+    insertToolCall(db, '123', 'bash', 'failure', 'ENOENT', 1, '2026-01-01T10:00:00Z', 'Error: no such file or directory');
     db.close();
 
-    const evidence = buildTrajectoryEvidenceFromDb(stateDir, '123', tmpDir);
+    const entries = entriesOf('123');
 
-    expect(evidence.length).toBeGreaterThan(0);
-    const ownerEntry = evidence.find(e => e.sourceRef.startsWith('owner_message:'));
-    expect(ownerEntry).toBeDefined();
-    expect(ownerEntry!.note).toContain('fix the backup logic');
+    const failureEntry = entries.find(e => e.sourceRef.startsWith('tool_call_failure:'));
+    expect(failureEntry).toBeDefined();
+    expect(failureEntry!.note).toContain('ENOENT');
+    expect(failureEntry!.note).toContain('Error: no such file or directory');
+  });
+
+  it('includes truncation warning when stop_reason is length', () => {
+    const db = createTrajectoryDb();
+    insertSession(db, '123');
+    db.prepare("INSERT INTO assistant_turns (session_id, sanitized_text, stop_reason, created_at) VALUES (?, ?, ?, ?)")
+      .run('123', 'Partial output truncated...', 'length', '2026-01-01T10:00:00Z');
+    db.close();
+
+    const entries = entriesOf('123');
+
+    const agentEntry = entries.find(e => e.sourceRef.startsWith('agent_turn:'));
+    expect(agentEntry).toBeDefined();
+    expect(agentEntry!.note).toContain('Partial output truncated...');
+    expect(agentEntry!.note).toContain('[TRUNCATED: output cut off by length limit]');
   });
 
-  // Additional: empty trajectory DB (tables exist but no rows) → meaningful placeholder
-  it('returns trajectory:empty placeholder when DB has no turns for session', () => {
+  it('does not include truncation warning when stop_reason is end_turn', () => {
     const db = createTrajectoryDb();
+    insertSession(db, '123');
+    db.prepare("INSERT INTO assistant_turns (session_id, sanitized_text, stop_reason, created_at) VALUES (?, ?, ?, ?)")
+      .run('123', 'Complete output', 'end_turn', '2026-01-01T10:00:00Z');
     db.close();
 
-    const evidence = buildTrajectoryEvidenceFromDb(stateDir, 'nonexistent-session', tmpDir);
+    const entries = entriesOf('123');
 
-    expect(evidence.length).toBeGreaterThan(0);
-    expect(evidence[0].sourceRef).toBe('trajectory:empty');
+    const agentEntry = entries.find(e => e.sourceRef.startsWith('agent_turn:'));
+    expect(agentEntry).toBeDefined();
+    expect(agentEntry!.note).toBe('Complete output');
+    expect(agentEntry!.note).not.toContain('[TRUNCATED');
   });
+});
+
+// ── PRI-642 Scope A — typed acquisition from trajectory.db (SPEC §7.3) ───────
 
-  // ── PRI-358: Failed tool_calls evidence ────────────────────────────────────
-
-  describe('PRI-358: failed tool_calls evidence', () => {
-    it('extracts failed tool_calls as evidence entries', () => {
-      const db = createTrajectoryDb();
-      insertToolCall(db, '123', 'bash', 'failure', 'non_zero_exit', 1, '2026-01-01T10:00:00Z');
-      insertToolCall(db, '123', 'write_file', 'success', null, 0, '2026-01-01T10:01:00Z');
-      insertToolCall(db, '123', 'bash', 'failure', 'timeout', 124, '2026-01-01T10:02:00Z');
-      db.close();
-
-      const evidence = buildTrajectoryEvidenceFromDb(stateDir, '123', tmpDir);
-
-      const failureEntries = evidence.filter(e => e.sourceRef.startsWith('tool_call_failure:'));
-      expect(failureEntries.length).toBe(2);
-      expect(failureEntries[0].note).toContain('bash');
-      expect(failureEntries[0].note).toContain('non_zero_exit');
-      expect(failureEntries[1].note).toContain('timeout');
-    });
-
-    it('does not add tool_call_failure entries when no failures exist', () => {
-      const db = createTrajectoryDb();
-      insertToolCall(db, '123', 'bash', 'success', null, 0, '2026-01-01T10:00:00Z');
-      db.close();
-
-      const evidence = buildTrajectoryEvidenceFromDb(stateDir, '123', tmpDir);
-
-      const failureEntries = evidence.filter(e => e.sourceRef.startsWith('tool_call_failure:'));
-      expect(failureEntries.length).toBe(0);
-    });
-
-    it('limits failed tool_calls to 3 entries', () => {
-      const db = createTrajectoryDb();
-      insertToolCall(db, '123', 'bash', 'failure', 'err1', 1, '2026-01-01T10:00:00Z');
-      insertToolCall(db, '123', 'bash', 'failure', 'err2', 2, '2026-01-01T10:01:00Z');
-      insertToolCall(db, '123', 'bash', 'failure', 'err3', 3, '2026-01-01T10:02:00Z');
-      insertToolCall(db, '123', 'bash', 'failure', 'err4', 4, '2026-01-01T10:03:00Z');
-      db.close();
-
-      const evidence = buildTrajectoryEvidenceFromDb(stateDir, '123', tmpDir);
-
-      const failureEntries = evidence.filter(e => e.sourceRef.startsWith('tool_call_failure:'));
-      expect(failureEntries.length).toBe(3);
-    });
-
-    it('handles missing tool_calls table gracefully', () => {
-      // Create DB without tool_calls table
-      const dbPath = path.join(stateDir, 'trajectory.db');
-      const db = new Database(dbPath);
-      db.exec(`
-        CREATE TABLE IF NOT EXISTS sessions (session_id TEXT PRIMARY KEY, started_at TEXT, updated_at TEXT)
-      `);
-      db.exec(`
-        CREATE TABLE IF NOT EXISTS assistant_turns (
-          id INTEGER PRIMARY KEY AUTOINCREMENT, session_id TEXT NOT NULL,
-          sanitized_text TEXT, created_at TEXT NOT NULL
-        )
-      `);
-      db.exec(`
-        CREATE TABLE IF NOT EXISTS user_turns (
-          id INTEGER PRIMARY KEY AUTOINCREMENT, session_id TEXT NOT NULL,
-          turn_index INTEGER NOT NULL DEFAULT 0, raw_excerpt TEXT,
-          correction_detected INTEGER NOT NULL DEFAULT 0, created_at TEXT NOT NULL
-        )
-      `);
-      db.close();
-
-      const evidence = buildTrajectoryEvidenceFromDb(stateDir, '123', tmpDir);
-
-      // Should not throw, should have some evidence (trajectory:empty or unavailable)
-      expect(evidence.length).toBeGreaterThan(0);
-      // Should NOT have tool_call_failure:unavailable since we have no other evidence
-      // and the table simply doesn't exist (not an error condition worth reporting)
-    });
+describe('acquireTrajectoryEvidenceFromDb — typed CLI acquisition (PRI-642 Scope A)', () => {
+  beforeEach(() => {
+    createStateDir();
   });
 
-  // ── Trajectory v2 enhancement: resultPreview + stopReason ─────────────────
-
-  describe('trajectory v2 enhancement: resultPreview and stopReason', () => {
-    it('includes resultPreview in tool failure evidence note', () => {
-      const db = createTrajectoryDb();
-      insertToolCall(db, '123', 'bash', 'failure', 'ENOENT', 1, '2026-01-01T10:00:00Z', 'Error: no such file or directory');
-      db.close();
-
-      const evidence = buildTrajectoryEvidenceFromDb(stateDir, '123', tmpDir);
-
-      const failureEntry = evidence.find(e => e.sourceRef.startsWith('tool_call_failure:'));
-      expect(failureEntry).toBeDefined();
-      expect(failureEntry!.note).toContain('ENOENT');
-      expect(failureEntry!.note).toContain('Error: no such file or directory');
-    });
-
-    it('includes truncation warning when stop_reason is length', () => {
-      const db = createTrajectoryDb();
-      db.prepare(`
-        INSERT INTO assistant_turns (session_id, sanitized_text, stop_reason, created_at)
-        VALUES (?, ?, ?, ?)
-      `).run('123', 'Partial output truncated...', 'length', '2026-01-01T10:00:00Z');
-      db.close();
-
-      const evidence = buildTrajectoryEvidenceFromDb(stateDir, '123', tmpDir);
-
-      const agentEntry = evidence.find(e => e.sourceRef.startsWith('agent_turn:'));
-      expect(agentEntry).toBeDefined();
-      expect(agentEntry!.note).toContain('Partial output truncated...');
-      expect(agentEntry!.note).toContain('[TRUNCATED: output cut off by length limit]');
-    });
-
-    it('does not include truncation warning when stop_reason is end_turn', () => {
-      const db = createTrajectoryDb();
-      db.prepare(`
-        INSERT INTO assistant_turns (session_id, sanitized_text, stop_reason, created_at)
-        VALUES (?, ?, ?, ?)
-      `).run('123', 'Complete output', 'end_turn', '2026-01-01T10:00:00Z');
-      db.close();
-
-      const evidence = buildTrajectoryEvidenceFromDb(stateDir, '123', tmpDir);
-
-      const agentEntry = evidence.find(e => e.sourceRef.startsWith('agent_turn:'));
-      expect(agentEntry).toBeDefined();
-      expect(agentEntry!.note).toBe('Complete output');
-      expect(agentEntry!.note).not.toContain('[TRUNCATED');
-    });
+  afterEach(() => {
+    try {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    } catch {
+      // ignore cleanup errors
+    }
+  });
+
+  it('returns available with entries for a session that has turns', async () => {
+    const { acquireTrajectoryEvidenceFromDb } = await import('../../src/commands/build-trajectory-evidence.js');
+    const db = createTrajectoryDb();
+    // Turn writers upsert the sessions row — mirror the real DB shape.
+    db.prepare('INSERT INTO sessions (session_id, started_at, updated_at) VALUES (?, ?, ?)')
+      .run('real-session', '2026-01-01T09:00:00Z', '2026-01-01T09:00:00Z');
+    insertUserTurn(db, 'real-session', 'Owner correction', true, '2026-01-01T09:59:00Z');
+    insertAssistantTurn(db, 'real-session', 'assistant text', '2026-01-01T10:00:00Z');
+    db.close();
+
+    const result = acquireTrajectoryEvidenceFromDb(stateDir, 'real-session', tmpDir);
+
+    expect(result.status).toBe('available');
+    if (result.status !== 'available') return;
+    expect(result.entries.length).toBeGreaterThan(0);
+    expect(result.entries.some(e => e.sourceRef.startsWith('owner_message:'))).toBe(true);
+    expect(result.entries.some(e => e.sourceRef.startsWith('agent_turn:'))).toBe(true);
+  });
+
+  it('returns unavailable/session_not_found for a session absent from the sessions table (SPEC 12.1.4)', async () => {
+    const { acquireTrajectoryEvidenceFromDb } = await import('../../src/commands/build-trajectory-evidence.js');
+    const db = createTrajectoryDb();
+    insertAssistantTurn(db, 'other-session', 'unrelated', '2026-01-01T10:00:00Z');
+    db.close();
+
+    const result = acquireTrajectoryEvidenceFromDb(stateDir, 'no-such-session', tmpDir);
+
+    expect(result.status).toBe('unavailable');
+    if (result.status !== 'unavailable') return;
+    expect(result.reasonCode).toBe('session_not_found');
+  });
+
+  it('returns unavailable/session_not_found for the "cli" and "unknown" sentinels', async () => {
+    const { acquireTrajectoryEvidenceFromDb } = await import('../../src/commands/build-trajectory-evidence.js');
+    const db = createTrajectoryDb();
+    db.close();
+
+    const cliResult = acquireTrajectoryEvidenceFromDb(stateDir, 'cli', tmpDir);
+    const unknownResult = acquireTrajectoryEvidenceFromDb(stateDir, 'unknown', tmpDir);
+
+    expect(cliResult.status).toBe('unavailable');
+    expect(unknownResult.status).toBe('unavailable');
+    if (cliResult.status !== 'unavailable' || unknownResult.status !== 'unavailable') return;
+    expect(cliResult.reasonCode).toBe('session_not_found');
+    expect(unknownResult.reasonCode).toBe('session_not_found');
+  });
+
+  it('returns unavailable/trajectory_unavailable when trajectory.db is missing', async () => {
+    const { acquireTrajectoryEvidenceFromDb } = await import('../../src/commands/build-trajectory-evidence.js');
+
+    const result = acquireTrajectoryEvidenceFromDb(stateDir, 'some-session', tmpDir);
+
+    expect(result.status).toBe('unavailable');
+    if (result.status !== 'unavailable') return;
+    expect(result.reasonCode).toBe('trajectory_unavailable');
+  });
+
+  it('returns unavailable/empty_trajectory when the session exists but has no turns or tool calls', async () => {
+    const { acquireTrajectoryEvidenceFromDb } = await import('../../src/commands/build-trajectory-evidence.js');
+    const db = createTrajectoryDb();
+    db.prepare(`
+      INSERT INTO sessions (session_id, started_at, updated_at)
+      VALUES (?, ?, ?)
+    `).run('quiet-session', '2026-01-01T09:00:00Z', '2026-01-01T09:00:00Z');
+    db.close();
+
+    const result = acquireTrajectoryEvidenceFromDb(stateDir, 'quiet-session', tmpDir);
+
+    expect(result.status).toBe('unavailable');
+    if (result.status !== 'unavailable') return;
+    expect(result.reasonCode).toBe('empty_trajectory');
+  });
+
+  it('returns a different reasonCode for unreadable DB vs empty trajectory (exec-prompt item 5)', async () => {
+    const { acquireTrajectoryEvidenceFromDb } = await import('../../src/commands/build-trajectory-evidence.js');
+    const db = createTrajectoryDb();
+    db.close();
+    // Corrupt the DB file after close so the read-only open fails.
+    const dbPath = path.join(stateDir, 'trajectory.db');
+    fs.writeFileSync(dbPath, Buffer.from('this is not a sqlite database at all'));
+
+    const unreadable = acquireTrajectoryEvidenceFromDb(stateDir, 'some-session', tmpDir);
+
+    const stateDir2 = createStateDir();
+    const db2 = createTrajectoryDb();
+    db2.close();
+
+    expect(unreadable.status).toBe('unavailable');
+    if (unreadable.status !== 'unavailable') return;
+    // Unreadable DB must not share a reasonCode with a real-but-empty session.
+    expect(unreadable.reasonCode).not.toBe('empty_trajectory');
+    expect(unreadable.reasonCode).toBe('evidence_read_failed');
   });
 });

package/tests/commands/diagnose.test.ts

@@ -108,6 +108,8 @@ vi.mock('@principles/core/runtime-v2', () => {
     OpenClawCliRuntimeAdapter: vi.fn().mockImplementation(function () { return {}; }),
     PiAiRuntimeAdapter: vi.fn().mockImplementation(function () { return {}; }),
     SPLIT_PIPELINE_TOTAL_TIMEOUT_MS: 300000,
+    // PRI-638: capability gate — available by default; disabled cases override this.
+    resolveDiagnosticianCapability: vi.fn((): { available: boolean; reason?: string; message?: string; nextAction?: string } => ({ available: true })),
     PDRuntimeError: class PDRuntimeError extends Error {
       constructor(public category: string, message: string) {
         super(message);
@@ -1714,3 +1716,83 @@ describe('BUG-2 (PRI-442): sourcePainId resolution for dreamer seed', () => {
     exitSpy.mockRestore();
   });
 });
+
+// ── PRI-638: unified capability-disabled semantics ───────────────────────────
+//
+// The CLI owns no kill switch of its own: it reads the canonical authority
+// (internalAgents.agents.diagnostician.enabled) through the same resolver the
+// runtime factory uses. Owner-disabled must come out as a structured
+// `capability_disabled` result — never as missing_runtime / config failure —
+// with no adapter constructed and no provider contacted.
+
+describe('PRI-638: pd diagnose run when Diagnostician capability is disabled', () => {
+  beforeEach(async () => {
+    vi.clearAllMocks();
+    const runtimeV2 = await import('@principles/core/runtime-v2');
+    vi.mocked(runtimeV2.resolveDiagnosticianCapability).mockReturnValue({
+      available: false,
+      reason: 'capability_disabled',
+      message: "Agent 'diagnostician' is disabled",
+      nextAction: "Enable agent 'diagnostician' in .pd/config.yaml internalAgents.agents.diagnostician.enabled",
+    });
+  });
+
+  afterEach(async () => {
+    const runtimeV2 = await import('@principles/core/runtime-v2');
+    vi.mocked(runtimeV2.resolveDiagnosticianCapability).mockReset();
+  });
+
+  it('DIAG-638-01: --json emits a structured capability_disabled result and exits 1', async () => {
+    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    const exitSpy = vi.spyOn(process, 'exit').mockImplementation((() => undefined) as () => never);
+
+    await handleDiagnoseRun({
+      taskId: 'diag_task-1',
+      workspace: '/tmp/fake-workspace',
+      runtime: 'test-double',
+      json: true,
+    } as DiagnoseRunOptions);
+
+    const jsonLine = logSpy.mock.calls
+      .map((c) => String(c[0]))
+      .find((line) => line.trim().startsWith('{'));
+    expect(jsonLine).toBeDefined();
+    const parsed = JSON.parse(jsonLine as string);
+    expect(parsed.reason).toBe('capability_disabled');
+    expect(parsed.nextAction).toContain('internalAgents.agents.diagnostician.enabled');
+    expect(parsed.message).toContain('disabled');
+
+    // Kill switch fires before any runtime machinery: no adapter, no runner.
+    const runtimeV2 = await import('@principles/core/runtime-v2');
+    expect(runtimeV2.TestDoubleRuntimeAdapter).not.toHaveBeenCalled();
+    expect(runtimeV2.SplitDiagnosticianRunner).not.toHaveBeenCalled();
+    expect(exitSpy).toHaveBeenCalledWith(1);
+
+    logSpy.mockRestore();
+    exitSpy.mockRestore();
+  });
+
+  it('DIAG-638-02: human-readable output names the reason and the recovery action', async () => {
+    const errSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    const exitSpy = vi.spyOn(process, 'exit').mockImplementation((() => undefined) as () => never);
+
+    await handleDiagnoseRun({
+      taskId: 'diag_task-1',
+      workspace: '/tmp/fake-workspace',
+      runtime: 'test-double',
+      json: false,
+    } as DiagnoseRunOptions);
+
+    const out = errSpy.mock.calls.map((c) => String(c[0])).join('\n');
+    expect(out).toContain('diagnostician');
+    expect(out).toContain('capability_disabled');
+    expect(out).toContain('internalAgents.agents.diagnostician.enabled');
+
+    const runtimeV2b = await import('@principles/core/runtime-v2');
+    expect(runtimeV2b.TestDoubleRuntimeAdapter).not.toHaveBeenCalled();
+    expect(exitSpy).toHaveBeenCalledWith(1);
+
+    errSpy.mockRestore();
+    exitSpy.mockRestore();
+  });
+});

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

@@ -31,36 +31,42 @@ vi.mock('../../src/commands/build-trajectory-evidence.js', () => ({
   ]),
 }));
 
-vi.mock('@principles/core/runtime-v2', () => ({
-  PainToPrincipleService: vi.fn().mockImplementation(function(this: Record<string, unknown>, opts: Record<string, unknown>) {
-    lastServiceOpts = opts;
-    return {
-      recordPain: vi.fn(async () => mockRecordPainResult),
-    };
-  }),
-  PrincipleTreeLedgerAdapter: vi.fn().mockImplementation(function() { return {}; }),
-  computeEffectivePdConfig: vi.fn().mockReturnValue({
-    runtimeKind: 'pi-ai',
-    provider: 'test-provider',
-    model: 'test-model',
-    apiKeyEnv: 'TEST_KEY',
-    timeoutMs: 300000,
-    agentId: 'main',
-    language: 'zh-CN',
-    warnings: [],
-  }),
-  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),
-  resolveOutputLanguage: vi.fn().mockReturnValue({ outputLanguage: 'zh-CN' }),
-  isFeatureEnabled: vi.fn().mockImplementation(() => mockIsFeatureEnabledReturn),
-}));
+vi.mock('@principles/core/runtime-v2', async (importOriginal) => {
+  // PRI-642 review blocker 1: keep the REAL core evaluatePainIngress (the
+  // shared semantic authority) — only service/IO classes are mocked.
+  const actual = await importOriginal<typeof import('@principles/core/runtime-v2')>();
+  return {
+    ...actual,
+    PainToPrincipleService: vi.fn().mockImplementation(function(this: Record<string, unknown>, opts: Record<string, unknown>) {
+      lastServiceOpts = opts;
+      return {
+        recordPain: vi.fn(async () => mockRecordPainResult),
+      };
+    }),
+    PrincipleTreeLedgerAdapter: vi.fn().mockImplementation(function() { return {}; }),
+    computeEffectivePdConfig: vi.fn().mockReturnValue({
+      runtimeKind: 'pi-ai',
+      provider: 'test-provider',
+      model: 'test-model',
+      apiKeyEnv: 'TEST_KEY',
+      timeoutMs: 300000,
+      agentId: 'main',
+      language: 'zh-CN',
+      warnings: [],
+    }),
+    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),
+    resolveOutputLanguage: vi.fn().mockReturnValue({ outputLanguage: 'zh-CN' }),
+    isFeatureEnabled: vi.fn().mockImplementation(() => mockIsFeatureEnabledReturn),
+  };
+});
 
 vi.mock('../../src/services/pd-config-loader.js', () => ({
   loadPdConfig: vi.fn().mockReturnValue({