@principles/pd-cli 1.145.1 → 1.146.0

package/src/commands/build-trajectory-evidence.ts

@@ -20,123 +20,122 @@ import {
 import type { PainEvidenceEntry } from '@principles/core/runtime-v2';
 
 /**
- * Build trajectory evidence entries by reading trajectory.db directly.
- *
- * @param stateDir   - The .state directory containing trajectory.db
- * @param sessionId  - The session ID to query turns for
- * @param workspaceDir - Workspace directory for path redaction (sanitizeString)
- * @returns Array of PainEvidenceEntry (never empty; degraded entries on failure)
+ * PRI-642 (SPEC §7.3): discriminated acquisition result. `unavailable` carries
+ * a distinct reasonCode so `pd pain record --session` can fail/degrade
+ * explicitly BEFORE any LLM/task/candidate mutation, without placeholder
+ * evidence.
  */
-export function buildTrajectoryEvidenceFromDb(
-  stateDir: string,
-  sessionId: string | undefined,
-  workspaceDir?: string,
-): PainEvidenceEntry[] {
-  const evidence: PainEvidenceEntry[] = [];
+export type TrajectoryEvidenceAcquisition =
+  | { status: 'available'; entries: PainEvidenceEntry[] }
+  | {
+      status: 'unavailable';
+      reasonCode: 'trajectory_unavailable' | 'session_not_found' | 'empty_trajectory' | 'evidence_read_failed';
+      detail: string;
+    };
 
-  // No session or empty → placeholder entry (ERR-002: never return empty array silently)
-  if (!sessionId || sessionId === 'cli' || sessionId === 'unknown') {
-    evidence.push({
-      sourceRef: 'owner_reported:cli',
-      note: 'No session context available',
-    });
-    return evidence;
-  }
+/** SourceRef markers that carry no real behavior trace (placeholder shapes). */
+const PLACEHOLDER_SOURCE_REFS = new Set([
+  'owner_reported:cli',
+  'owner_message:unavailable',
+  'agent_turn:unavailable',
+  'tool_call_failure:unavailable',
+  'trajectory:empty',
+]);
 
-  const dbPath = path.join(stateDir, 'trajectory.db');
-  if (!fs.existsSync(dbPath)) {
-    evidence.push({
-      sourceRef: 'owner_reported:cli',
-      note: 'No session context available',
-    });
-    return evidence;
-  }
+interface TrajectoryDbCollection {
+  entries: PainEvidenceEntry[];
+  realEntryCount: number;
+  readFailed: boolean;
+}
 
-  let db: Database.Database;
-  try {
-    db = new Database(dbPath, { readonly: true });
-  } catch {
-    evidence.push({
-      sourceRef: 'owner_reported:cli',
-      note: 'No session context available',
-    });
-    return evidence;
-  }
+/**
+ * Collect evidence entries from an open trajectory.db for one session.
+ * Shared by the typed acquisition API and the legacy array wrapper so the
+ * two can never drift.
+ */
+function collectEvidenceFromDb(
+  db: Database.Database,
+  sessionId: string,
+  workspaceDir?: string,
+): TrajectoryDbCollection {
+  const evidence: PainEvidenceEntry[] = [];
+  let readFailed = false;
 
+  // Try to read user turns with correction detection
   try {
-    // Try to read user turns with correction detection
-    try {
-      const userTurns = db.prepare(`
+    const userTurns = db.prepare(`
         SELECT id, raw_excerpt, correction_detected, correction_cue, created_at
         FROM user_turns
         WHERE session_id = ?
         ORDER BY id ASC
       `).all(sessionId) as Record<string, unknown>[];
 
-      const lastCorrectionTurn = [...userTurns].reverse().find(t => Boolean(t.correction_detected));
-      if (lastCorrectionTurn) {
-        const rawExcerpt = typeof lastCorrectionTurn.raw_excerpt === 'string'
-          ? lastCorrectionTurn.raw_excerpt
-          : '';
-        const sanitizedNote = sanitizeString(
-          rawExcerpt.slice(0, MAX_EVIDENCE_NOTE_CHARS),
-          workspaceDir,
-        );
-        evidence.push({
-          sourceRef: `owner_message:${String(lastCorrectionTurn.created_at ?? 'unknown')}`,
-          note: sanitizedNote,
-        });
-      }
-    } catch {
-      // user_turns table may not exist — degrade gracefully
-      if (evidence.length < MAX_EVIDENCE_ENTRIES) {
-        evidence.push({
-          sourceRef: 'owner_message:unavailable',
-          note: 'trajectory_user_turns_unavailable',
-        });
-      }
+    const lastCorrectionTurn = [...userTurns].reverse().find(t => Boolean(t.correction_detected));
+    if (lastCorrectionTurn) {
+      const rawExcerpt = typeof lastCorrectionTurn.raw_excerpt === 'string'
+        ? lastCorrectionTurn.raw_excerpt
+        : '';
+      const sanitizedNote = sanitizeString(
+        rawExcerpt.slice(0, MAX_EVIDENCE_NOTE_CHARS),
+        workspaceDir,
+      );
+      evidence.push({
+        sourceRef: `owner_message:${String(lastCorrectionTurn.created_at ?? 'unknown')}`,
+        note: sanitizedNote,
+      });
     }
+  } catch {
+    readFailed = true;
+    // user_turns table may not exist — degrade gracefully
+    if (evidence.length < MAX_EVIDENCE_ENTRIES) {
+      evidence.push({
+        sourceRef: 'owner_message:unavailable',
+        note: 'trajectory_user_turns_unavailable',
+      });
+    }
+  }
 
-    // Try to read assistant turns (last 3)
-    try {
-      const assistantTurns = db.prepare(`
+  // Try to read assistant turns (last 3)
+  try {
+    const assistantTurns = db.prepare(`
         SELECT id, sanitized_text, stop_reason, created_at
         FROM assistant_turns
         WHERE session_id = ?
         ORDER BY id ASC
       `).all(sessionId) as Record<string, unknown>[];
 
-      const recentAssistant = assistantTurns.slice(-3);
-      for (const turn of recentAssistant) {
-        if (evidence.length >= MAX_EVIDENCE_ENTRIES) break;
-        const sanitizedText = typeof turn.sanitized_text === 'string'
-          ? turn.sanitized_text
-          : '';
-        const sanitizedNote = sanitizeString(
-          sanitizedText.slice(0, MAX_EVIDENCE_NOTE_CHARS),
-          workspaceDir,
-        );
-        // Enhanced: append truncation warning when stop_reason=length
-        const stopReason = typeof turn.stop_reason === 'string' ? turn.stop_reason : null;
-        const truncationWarning = stopReason === 'length' ? ' [TRUNCATED: output cut off by length limit]' : '';
-        evidence.push({
-          sourceRef: `agent_turn:${String(turn.created_at ?? 'unknown')}`,
-          note: sanitizedNote + truncationWarning,
-        });
-      }
-    } catch {
-      // assistant_turns table may not exist — degrade gracefully
-      if (evidence.length < MAX_EVIDENCE_ENTRIES) {
-        evidence.push({
-          sourceRef: 'agent_turn:unavailable',
-          note: 'trajectory_assistant_turns_unavailable',
-        });
-      }
+    const recentAssistant = assistantTurns.slice(-3);
+    for (const turn of recentAssistant) {
+      if (evidence.length >= MAX_EVIDENCE_ENTRIES) break;
+      const sanitizedText = typeof turn.sanitized_text === 'string'
+        ? turn.sanitized_text
+        : '';
+      const sanitizedNote = sanitizeString(
+        sanitizedText.slice(0, MAX_EVIDENCE_NOTE_CHARS),
+        workspaceDir,
+      );
+      // Enhanced: append truncation warning when stop_reason=length
+      const stopReason = typeof turn.stop_reason === 'string' ? turn.stop_reason : null;
+      const truncationWarning = stopReason === 'length' ? ' [TRUNCATED: output cut off by length limit]' : '';
+      evidence.push({
+        sourceRef: `agent_turn:${String(turn.created_at ?? 'unknown')}`,
+        note: sanitizedNote + truncationWarning,
+      });
     }
+  } catch {
+    readFailed = true;
+    // assistant_turns table may not exist — degrade gracefully
+    if (evidence.length < MAX_EVIDENCE_ENTRIES) {
+      evidence.push({
+        sourceRef: 'agent_turn:unavailable',
+        note: 'trajectory_assistant_turns_unavailable',
+      });
+    }
+  }
 
-    // PRI-358: Try to read failed tool_calls (last 3 failures, chronological order)
-    try {
-      const failedToolCalls = db.prepare(`
+  // PRI-358: Try to read failed tool_calls (last 3 failures, chronological order)
+  try {
+    const failedToolCalls = db.prepare(`
         SELECT tool_name, error_type, exit_code, result_preview, created_at
         FROM (
           SELECT tool_name, error_type, exit_code, result_preview, created_at
@@ -148,39 +147,129 @@ export function buildTrajectoryEvidenceFromDb(
         ORDER BY created_at ASC
       `).all(sessionId) as Record<string, unknown>[];
 
-      for (const tc of failedToolCalls) {
-        if (evidence.length >= MAX_EVIDENCE_ENTRIES) break;
-        const toolName = typeof tc.tool_name === 'string' ? tc.tool_name : 'unknown';
-        const errorType = typeof tc.error_type === 'string' ? tc.error_type : 'unknown';
-        const exitCode = tc.exit_code != null ? String(tc.exit_code) : 'N/A';
-        // Enhanced: append resultPreview when available
-        const resultPreview = typeof tc.result_preview === 'string' ? tc.result_preview : null;
-        const previewSuffix = resultPreview ? ` | ${resultPreview.slice(0, 200)}` : '';
-        const note = `Tool ${toolName} failed: ${errorType} (exitCode: ${exitCode})${previewSuffix}`;
-        evidence.push({
-          sourceRef: `tool_call_failure:${String(tc.created_at ?? 'unknown')}`,
-          note: sanitizeString(note.slice(0, MAX_EVIDENCE_NOTE_CHARS), workspaceDir),
-        });
-      }
-    } catch {
-      // tool_calls table may not exist — degrade gracefully (only when no other evidence)
-      if (evidence.length === 0) {
-        evidence.push({
-          sourceRef: 'tool_call_failure:unavailable',
-          note: 'trajectory_tool_calls_unavailable',
-        });
-      }
+    for (const tc of failedToolCalls) {
+      if (evidence.length >= MAX_EVIDENCE_ENTRIES) break;
+      const toolName = typeof tc.tool_name === 'string' ? tc.tool_name : 'unknown';
+      const errorType = typeof tc.error_type === 'string' ? tc.error_type : 'unknown';
+      const exitCode = tc.exit_code != null ? String(tc.exit_code) : 'N/A';
+      // Enhanced: append resultPreview when available
+      const resultPreview = typeof tc.result_preview === 'string' ? tc.result_preview : null;
+      const previewSuffix = resultPreview ? ` | ${resultPreview.slice(0, 200)}` : '';
+      const note = `Tool ${toolName} failed: ${errorType} (exitCode: ${exitCode})${previewSuffix}`;
+      evidence.push({
+        sourceRef: `tool_call_failure:${String(tc.created_at ?? 'unknown')}`,
+        note: sanitizeString(note.slice(0, MAX_EVIDENCE_NOTE_CHARS), workspaceDir),
+      });
     }
-
-    // If no evidence at all from trajectory, provide a meaningful placeholder
+  } catch {
+    readFailed = true;
+    // tool_calls table may not exist — degrade gracefully (only when no other evidence)
     if (evidence.length === 0) {
       evidence.push({
-        sourceRef: 'trajectory:empty',
-        note: 'trajectory_available_but_empty: no user correction or assistant turns found',
+        sourceRef: 'tool_call_failure:unavailable',
+        note: 'trajectory_tool_calls_unavailable',
       });
     }
+  }
+
+  // If no evidence at all from trajectory, provide a meaningful placeholder
+  if (evidence.length === 0) {
+    evidence.push({
+      sourceRef: 'trajectory:empty',
+      note: 'trajectory_available_but_empty: no user correction or assistant turns found',
+    });
+  }
+
+  const bounded = evidence.slice(0, MAX_EVIDENCE_ENTRIES);
+  const realEntryCount = bounded.reduce(
+    (count, entry) => count + (PLACEHOLDER_SOURCE_REFS.has(entry.sourceRef) ? 0 : 1),
+    0,
+  );
+  return { entries: bounded, realEntryCount, readFailed };
+}
+
+/**
+ * PRI-642 Scope A typed acquisition from trajectory.db (SPEC §7.3).
+ *
+ * Validates that the requested session exists in the trajectory `sessions`
+ * table (every recorded turn/tool call upserts its session row, so an absent
+ * row means the session was never seen) and classifies the outcome:
+ *  - `available`            — session bound, ≥1 real behavior-trace entry;
+ *  - `session_not_found`    — session absent from the sessions table (or a
+ *                             `cli`/`unknown` sentinel — never a real session);
+ *  - `trajectory_unavailable` — no trajectory.db in this workspace;
+ *  - `evidence_read_failed` — the DB exists but cannot be opened/read;
+ *  - `empty_trajectory`     — real session, no usable evidence rows.
+ */
+export function acquireTrajectoryEvidenceFromDb(
+  stateDir: string,
+  sessionId: string | undefined,
+  workspaceDir?: string,
+): TrajectoryEvidenceAcquisition {
+  if (!sessionId || sessionId === 'cli' || sessionId === 'unknown') {
+    return {
+      status: 'unavailable',
+      reasonCode: 'session_not_found',
+      detail: sessionId ? `sentinel_session_id:${sessionId}` : 'missing_session_id',
+    };
+  }
+
+  const dbPath = path.join(stateDir, 'trajectory.db');
+  if (!fs.existsSync(dbPath)) {
+    return {
+      status: 'unavailable',
+      reasonCode: 'trajectory_unavailable',
+      detail: 'trajectory_db_missing',
+    };
+  }
+
+  let db: Database.Database;
+  try {
+    db = new Database(dbPath, { readonly: true });
+  } catch (err) {
+    return {
+      status: 'unavailable',
+      reasonCode: 'evidence_read_failed',
+      detail: `trajectory_db_unreadable: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+
+  try {
+    // Session existence: rows are upserted by every turn/tool-call write, so
+    // an absent row means the trajectory never saw this session.
+    let sessionExists = false;
+    try {
+      const row = db.prepare('SELECT 1 FROM sessions WHERE session_id = ?').get(sessionId);
+      sessionExists = row !== undefined;
+    } catch {
+      // sessions table missing → cannot validate existence; fall through and
+      // let the evidence rows decide (legacy DBs may lack the table).
+      sessionExists = true;
+    }
+    if (!sessionExists) {
+      return {
+        status: 'unavailable',
+        reasonCode: 'session_not_found',
+        detail: 'session_not_present_in_trajectory',
+      };
+    }
 
-    return evidence.slice(0, MAX_EVIDENCE_ENTRIES);
+    const collection = collectEvidenceFromDb(db, sessionId, workspaceDir);
+    if (collection.realEntryCount > 0) {
+      return { status: 'available', entries: collection.entries };
+    }
+    if (collection.readFailed) {
+      return {
+        status: 'unavailable',
+        reasonCode: 'evidence_read_failed',
+        detail: 'trajectory_tables_unreadable',
+      };
+    }
+    return {
+      status: 'unavailable',
+      reasonCode: 'empty_trajectory',
+      detail: 'session_present_but_no_usable_evidence',
+    };
   } finally {
     db.close();
   }

package/src/commands/diagnose.ts

@@ -20,7 +20,6 @@ import {
   DiagRouterRunner,
   DefaultDiagRootCauseValidator,
   DefaultDiagDistillerValidator,
-  DisabledDiagnosticianRunner,
   type DiagnosticianRunnerLike,
   TestDoubleRuntimeAdapter,
   PDRuntimeError,
@@ -37,8 +36,8 @@ import {
 import type { PDRuntimeAdapter, OutputLanguage } from '@principles/core/runtime-v2';
 import { resolveWorkspaceDir } from '../resolve-workspace.js';
 import { readOutputLanguageFromWorkspace } from '../config-reader.js';
-import { loadPdConfig, computeFlagsFromLoadResult } from '../services/pd-config-loader.js';
-import { isFeatureEnabled, SPLIT_PIPELINE_TOTAL_TIMEOUT_MS } from '@principles/core/runtime-v2';
+import { loadPdConfig } from '../services/pd-config-loader.js';
+import { SPLIT_PIPELINE_TOTAL_TIMEOUT_MS, resolveDiagnosticianCapability } from '@principles/core/runtime-v2';
 import { createHash } from 'node:crypto';
 /** Layer 0 content-hash (design §6.1); injected so diag writers can attach predecessorSummary hashes. */
 const contentHashFn = (input: string): string => createHash('sha256').update(input).digest('hex');
@@ -208,6 +207,35 @@ export async function handleDiagnoseRun(opts: DiagnoseRunOptions): Promise<void>
     return;
   }
 
+  // PRI-638: this is the CLI's ONLY capability disable check. It reads the
+  // canonical authority (internalAgents.agents.diagnostician.enabled) through
+  // the same resolver the runtime factory uses, so `pd diagnose` can never
+  // mislabel a deliberate Owner kill switch as a missing runtime, a provider
+  // failure or a malformed config. No runtime adapter is constructed and no
+  // provider is contacted on this path.
+  const configLoadResult = loadPdConfig(workspaceDir);
+  const capability = resolveDiagnosticianCapability(
+    configLoadResult.ok ? configLoadResult.effective : configLoadResult.defaults,
+  );
+  if (!capability.available) {
+    const disabledResult = {
+      ok: false,
+      status: 'failed',
+      reason: capability.reason,
+      message: capability.message,
+      nextAction: capability.nextAction,
+    };
+    if (opts.json) {
+      console.log(JSON.stringify(disabledResult, null, 2));
+    } else {
+      console.error(`error: ${capability.message}`);
+      console.error(`reason: ${capability.reason}`);
+      console.error(`nextAction: ${capability.nextAction}`);
+    }
+    process.exit(1);
+    return;
+  }
+
   // Resolve runtime kind. P1 fix (mirrors pain-retry.ts): pd diagnose run
   // must NOT default to test-double. Without --runtime, the split pipeline
   // would validate the test-double's stale DiagnosticianOutputV1-shaped
@@ -389,11 +417,11 @@ export async function handleDiagnoseRun(opts: DiagnoseRunOptions): Promise<void>
     const outputLangResult = readOutputLanguageFromWorkspace(workspaceDir);
     const outputLanguage: OutputLanguage | undefined = outputLangResult.outputLanguage;
 
-    // Check if split pipeline is enabled — 3 serial LLM calls need more time
-    const configLoadResult = loadPdConfig(workspaceDir);
-    const featureFlags = computeFlagsFromLoadResult(configLoadResult);
-    const isSplitPipeline = isFeatureEnabled(featureFlags, 'diagnostician_split_pipeline');
-    const pipelineTimeoutMs = isSplitPipeline ? SPLIT_PIPELINE_TOTAL_TIMEOUT_MS : 300_000;
+    // PRI-638: implementation selection is gone. The split pipeline is the only
+    // Diagnostician implementation in the tree, so it always runs with its
+    // documented 3-stage budget; `diagnostician_split_pipeline` no longer
+    // selects a runner nor disables capability.
+    const pipelineTimeoutMs = SPLIT_PIPELINE_TOTAL_TIMEOUT_MS;
     // BUG-1 (PRI-442): extract effectiveConfig so ADR-0019 LLM rate-limit
     // degradation (isDegradationEnabled in base-peer-runner) can read the
     // diagnostician_llm_degradation feature flag. Without this, the runners
@@ -410,34 +438,29 @@ export async function handleDiagnoseRun(opts: DiagnoseRunOptions): Promise<void>
     }
     const effectiveConfig = configLoadResult.ok ? configLoadResult.effective : configLoadResult.defaults;
 
-    let runner: DiagnosticianRunnerLike;
-    if (isSplitPipeline) {
-      const resolvedKind = typeof runtimeAdapter.kind === 'function' ? runtimeAdapter.kind() : runtimeKind;
-      const perStageTimeoutMs = pipelineTimeoutMs / 3;
-      const rootCauseRunner = new DiagRootCauseRunner(
-        { stateManager, runtimeAdapter, eventEmitter, artifactStore: stateManager.piArtifactStore, validator: new DefaultDiagRootCauseValidator(), contextAssembler, contentHashFn },
-        { owner: 'pd-cli-diagnose', runtimeKind: resolvedKind, outputLanguage, timeoutMs: perStageTimeoutMs, effectiveConfig },
-      );
-      const distillerRunner = new DiagDistillerRunner(
-        { stateManager, runtimeAdapter, eventEmitter, artifactStore: stateManager.piArtifactStore, validator: new DefaultDiagDistillerValidator(), contentHashFn },
-        { owner: 'pd-cli-diagnose', runtimeKind: resolvedKind, outputLanguage, timeoutMs: perStageTimeoutMs, effectiveConfig },
-      );
-      const routerRunner = new DiagRouterRunner(
-        { stateManager, runtimeAdapter, eventEmitter, artifactStore: stateManager.piArtifactStore, committer, contentHashFn },
-        { owner: 'pd-cli-diagnose', runtimeKind: resolvedKind, outputLanguage, timeoutMs: perStageTimeoutMs, effectiveConfig },
-      );
-
-      runner = new SplitDiagnosticianRunner({
-        rootCauseRunner,
-        distillerRunner,
-        routerRunner,
-        stateManager,
-        committer,
-        perStageTimeoutMs,
-      });
-    } else {
-      runner = new DisabledDiagnosticianRunner();
-    }
+    const resolvedKind = typeof runtimeAdapter.kind === 'function' ? runtimeAdapter.kind() : runtimeKind;
+    const perStageTimeoutMs = pipelineTimeoutMs / 3;
+    const rootCauseRunner = new DiagRootCauseRunner(
+      { stateManager, runtimeAdapter, eventEmitter, artifactStore: stateManager.piArtifactStore, validator: new DefaultDiagRootCauseValidator(), contextAssembler, contentHashFn },
+      { owner: 'pd-cli-diagnose', runtimeKind: resolvedKind, outputLanguage, timeoutMs: perStageTimeoutMs, effectiveConfig },
+    );
+    const distillerRunner = new DiagDistillerRunner(
+      { stateManager, runtimeAdapter, eventEmitter, artifactStore: stateManager.piArtifactStore, validator: new DefaultDiagDistillerValidator(), contentHashFn },
+      { owner: 'pd-cli-diagnose', runtimeKind: resolvedKind, outputLanguage, timeoutMs: perStageTimeoutMs, effectiveConfig },
+    );
+    const routerRunner = new DiagRouterRunner(
+      { stateManager, runtimeAdapter, eventEmitter, artifactStore: stateManager.piArtifactStore, committer, contentHashFn },
+      { owner: 'pd-cli-diagnose', runtimeKind: resolvedKind, outputLanguage, timeoutMs: perStageTimeoutMs, effectiveConfig },
+    );
+
+    const runner: DiagnosticianRunnerLike = new SplitDiagnosticianRunner({
+      rootCauseRunner,
+      distillerRunner,
+      routerRunner,
+      stateManager,
+      committer,
+      perStageTimeoutMs,
+    });
 
     if (!opts.json) {
       console.log(`\nRunning diagnostician for task: ${opts.taskId}`);