@principles/pd-cli 1.133.0 → 1.134.0

package/src/commands/diagnose.ts

@@ -29,13 +29,23 @@ import {
   run as diagnoseRun,
   status as diagnoseStatus,
   PrincipleTreeLedgerAdapter,
+  buildDreamerSeedFromCandidate,
+  CANDIDATE_KIND_TO_ROUTE,
+  ROUTE_CHANNEL_MAP,
+  MVP_ENABLED_CHANNELS,
 } from '@principles/core/runtime-v2';
 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 { 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');
 import { resolveRuntimeAdapterFromConfig, ConfigResolutionError } from '../services/runtime-adapter-resolver.js';
+import { resolveRuntimeFromPdConfig } from '../services/resolve-runtime-from-pd-config.js';
+import { checkAdmissionGate } from './admission-gate.js';
+import { resolveSourcePainIdFromDiagnostician } from './candidate.js';
 import * as path from 'path';
 
 function validateStalledThreshold(val: unknown): number | undefined {
@@ -198,7 +208,38 @@ export async function handleDiagnoseRun(opts: DiagnoseRunOptions): Promise<void>
     return;
   }
 
-  const runtimeKind = opts.runtime ?? 'test-double';
+  // 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
+  // payload against DiagRootCauseOutputV1Schema and fail with
+  // max_attempts_exceeded — silently producing failed/fake diagnostic data
+  // in a real workspace. Fall back to .pd/config.yaml first; refuse if
+  // nothing is bound. (rc-9-no-silent-fallback / ERR-002; EP-03, EP-04)
+  let runtimeKind = opts.runtime;
+  if (!runtimeKind) {
+    const resolved = resolveRuntimeFromPdConfig(workspaceDir);
+    if (!isRuntimeConfigError(resolved.result) && resolved.result.runtimeKind) {
+      ({ runtimeKind } = resolved.result);
+    }
+  }
+
+  if (!runtimeKind) {
+    const missingRuntime = {
+      ok: false,
+      reason: 'missing_runtime',
+      message:
+        'No --runtime specified and no .pd/config.yaml runtime binding found. pd diagnose run must not default to test-double to prevent fake data in real workspaces.',
+      nextAction: `Specify --runtime explicitly: pd diagnose run --task-id ${opts.taskId} --runtime pi-ai --provider <provider> --model <model> --apiKeyEnv <ENV>`,
+    };
+    if (opts.json) {
+      console.log(JSON.stringify(missingRuntime, null, 2));
+    } else {
+      console.error(`error: ${missingRuntime.message}`);
+      console.error(`Next action: ${missingRuntime.nextAction}`);
+    }
+    process.exit(1);
+    return;
+  }
 
   const stateManager = new RuntimeStateManager({ workspaceDir });
 
@@ -353,22 +394,37 @@ export async function handleDiagnoseRun(opts: DiagnoseRunOptions): Promise<void>
     const featureFlags = computeFlagsFromLoadResult(configLoadResult);
     const isSplitPipeline = isFeatureEnabled(featureFlags, 'diagnostician_split_pipeline');
     const pipelineTimeoutMs = isSplitPipeline ? SPLIT_PIPELINE_TOTAL_TIMEOUT_MS : 300_000;
+    // 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
+    // receive no effectiveConfig and degradation silently never fires.
+    // CR-1 (CodeRabbit P2, rc-9): warn when config load failed so the
+    // fallback to defaults is observable — no silent degradation.
+    if (!configLoadResult.ok) {
+      const errSummary = configLoadResult.errors
+        .map((e) => `${e.path}: ${e.reason}`)
+        .join('; ');
+      console.warn(
+        `[pd diagnose] .pd/config.yaml at ${configLoadResult.configPath} is malformed — falling back to default feature flags. Errors: ${errSummary}. Next action: ${configLoadResult.errors[0]?.nextAction ?? 'fix config errors and retry'}`,
+      );
+    }
+    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 },
-        { owner: 'pd-cli-diagnose', runtimeKind: resolvedKind, outputLanguage, timeoutMs: perStageTimeoutMs },
+        { 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() },
-        { owner: 'pd-cli-diagnose', runtimeKind: resolvedKind, outputLanguage, timeoutMs: perStageTimeoutMs },
+        { 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 },
-        { owner: 'pd-cli-diagnose', runtimeKind: resolvedKind, outputLanguage, timeoutMs: perStageTimeoutMs },
+        { stateManager, runtimeAdapter, eventEmitter, artifactStore: stateManager.piArtifactStore, committer, contentHashFn },
+        { owner: 'pd-cli-diagnose', runtimeKind: resolvedKind, outputLanguage, timeoutMs: perStageTimeoutMs, effectiveConfig },
       );
 
       runner = new SplitDiagnosticianRunner({
@@ -463,6 +519,23 @@ export async function handleDiagnoseRun(opts: DiagnoseRunOptions): Promise<void>
       const intakeService = new CandidateIntakeService({ stateManager, ledgerAdapter });
 
       for (const candidate of candidates) {
+        // PRI-503: admission gate check — refuse non-admitted candidates before
+        // intake, mirroring candidate.ts (intake/repair/backfill). Without this,
+        // `pd diagnose --intake` could bypass the gate and intake unreviewed
+        // candidates. cli-5-failure-no-mutation: refusal path does not call
+        // intake(), does not update candidate status, does not write ledger.
+        // cli-6-output-next-action: refusal result carries admissionBlock.nextAction.
+        const admissionBlock = checkAdmissionGate(candidate);
+        if (admissionBlock) {
+          intakeFailed = true;
+          intakeResults.push({
+            candidateId: candidate.candidateId,
+            status: 'intake_failed',
+            error: `Admission gate refused: ${admissionBlock.reason}`,
+            nextAction: admissionBlock.nextAction,
+          });
+          continue;
+        }
         try {
           const entry = await intakeService.intake(candidate.candidateId);
           if (candidate.status !== 'consumed') {
@@ -486,11 +559,79 @@ export async function handleDiagnoseRun(opts: DiagnoseRunOptions): Promise<void>
       }
     }
 
+    // Defect-004 fix: seed dreamer task for each consumed candidate whose
+    // recommendation_kind routes to an MVP-enabled internalization channel.
+    // Without this, the chain stops at 'consumed' and never reaches internalization
+    // (11 of 18 consumed candidates hit this in production). Mirrors the pattern
+    // in PainSignalBridge.onDiagnosisComplete (pain-signal-bridge.ts L310-338).
+    //
+    // DEFECT-005 (PRI-514): the dreamer seed loop is gated ONLY by `opts.intake`,
+    // NOT by a global `intakeFailed` flag. A single defer candidate whose intake
+    // is refused by the admission gate must NOT poison dreamer seed for sibling
+    // candidates that were successfully consumed (EP-03 / ERR-089 sibling-branch
+    // defect). Per-candidate eligibility is checked inside the loop via the
+    // intake result's status. `intakeFailed` is retained solely for the
+    // nextAction/exit-code signaling below (partial failure still exits non-zero).
+    if (opts.intake !== false) {
+      for (const candidate of candidates) {
+        const kind = candidate.recommendationKind;
+        if (kind === 'defer' || kind === 'implementation') continue;
+        const intakeResult = intakeResults.find((r) => r.candidateId === candidate.candidateId);
+        if (!intakeResult || intakeResult.status !== 'consumed') continue;
+        try {
+          const route = CANDIDATE_KIND_TO_ROUTE[kind ?? ''];
+          if (!route) continue;
+          const channel = ROUTE_CHANNEL_MAP[route];
+          const ready = !!channel && MVP_ENABLED_CHANNELS.has(channel);
+          // BUG-2 (PRI-442): resolve sourcePainId from the diagnostician task
+          // chain (rc-6 lineage consistency). The candidate itself doesn't carry
+          // sourcePainId; it must be resolved from the diagnostician task's
+          // diagnosticJson. ERR-004: never invent lineage.
+          const sourcePainId = await resolveSourcePainIdFromDiagnostician(stateManager, candidate);
+          const seed = buildDreamerSeedFromCandidate(candidate, { route, ready, sourcePainId: sourcePainId ?? undefined });
+          // eslint-disable-next-line no-restricted-syntax -- 'in' required for discriminated union narrowing (BridgeTaskSeed | BridgeDecision)
+          if ('decision' in seed) continue; // not_internalizable or invalid — skip
+          const existingTask = await stateManager.getTask(seed.taskId);
+          if (!existingTask) {
+            await stateManager.createTask({
+              taskId: seed.taskId,
+              taskKind: seed.taskKind,
+              inputRef: '',
+              status: seed.status,
+              attemptCount: seed.attemptCount,
+              maxAttempts: seed.maxAttempts,
+              diagnosticJson: seed.diagnosticJson,
+            });
+            intakeResults.push({
+              candidateId: candidate.candidateId,
+              status: 'dreamer_seeded',
+              nextAction: `pd task show ${seed.taskId} | pd dreamer run --task-id ${seed.taskId}`,
+            });
+          }
+        } catch (seedErr) {
+          intakeResults.push({
+            candidateId: candidate.candidateId,
+            status: 'dreamer_seed_failed',
+            error: seedErr instanceof Error ? seedErr.message : String(seedErr),
+            nextAction: `pd candidate internalize --candidate-id ${candidate.candidateId}`,
+          });
+        }
+      }
+    }
+
     if (opts.json) {
       const candidateIds = candidates.map((c) => c.candidateId);
-      const internalizeNextAction = candidateIds.length > 0
-        ? `Candidates generated but internalization has NOT started automatically. To begin internalization, run:\n  ${candidateIds.map((id) => `pd candidate internalize --candidate-id ${id} --workspace "${workspaceDir}"`).join('\n  ')}`
-        : 'No candidates were generated from this diagnosis.';
+      // CodeRabbit review fix: reflect dreamer seed status in nextAction so
+      // the owner knows whether internalization has already started or still
+      // needs manual candidate internalize. Previously the message always
+      // said "NOT started automatically" even when dreamer tasks were seeded.
+      const dreamerSeededCount = intakeResults.filter((r) => r.status === 'dreamer_seeded').length;
+      const dreamerSeedFailedCount = intakeResults.filter((r) => r.status === 'dreamer_seed_failed').length;
+      const internalizeNextAction = dreamerSeededCount > 0
+        ? `Dreamer tasks seeded automatically for ${dreamerSeededCount} candidate(s). To continue, run the dreamer tasks shown in intake.candidates[].${dreamerSeedFailedCount > 0 ? ` (${dreamerSeedFailedCount} candidate(s) failed seeding — see intake.candidates[] for retry guidance.)` : ''}`
+        : candidateIds.length > 0
+          ? `Candidates generated but internalization has NOT started automatically. To begin internalization, run:\n  ${candidateIds.map((id) => `pd candidate internalize --candidate-id ${id} --workspace "${workspaceDir}"`).join('\n  ')}`
+          : 'No candidates were generated from this diagnosis.';
       const jsonOutput = {
         ...result,
         intake: {
@@ -534,6 +675,13 @@ export async function handleDiagnoseRun(opts: DiagnoseRunOptions): Promise<void>
         } else if (ir.status === 'intake_failed') {
           console.log(`    ${ir.candidateId}: INTAKE FAILED — ${ir.error}`);
           console.log(`      Next action: pd candidate intake --candidate-id ${ir.candidateId} --workspace "${workspaceDir}"`);
+        } else if (ir.status === 'dreamer_seeded') {
+          // CodeRabbit review fix: surface dreamer seed success in TTY output
+          console.log(`    ${ir.candidateId}: dreamer seeded — ${ir.nextAction}`);
+        } else if (ir.status === 'dreamer_seed_failed') {
+          // CodeRabbit review fix: surface dreamer seed failure in TTY output
+          console.log(`    ${ir.candidateId}: DREAMER SEED FAILED — ${ir.error}`);
+          console.log(`      Next action: ${ir.nextAction}`);
         }
       }
     }

package/src/commands/errors-list.ts

@@ -0,0 +1,440 @@
+/**
+ * pd errors list — List PD pipeline errors (failed tasks + worker errors).
+ *
+ * Usage:
+ *   pd errors list [--json] [--kind <runnerKind>] [--since <hours>] [--limit <n>] [--workspace <path>]
+ *
+ * Aggregates two error sources into a single operator-facing read-only view:
+ *   1. SQLite state.db tasks where status IN ('failed', 'needs_human_review')
+ *      (via SqliteTaskStore.listFailedTasks — Task 8).
+ *   2. worker-status.json `errors` array written by EvolutionWorker
+ *      (Task 2 extended the entry shape to { at, kind, principleId, error } | string).
+ *
+ * CLI gate compliance:
+ *   - cli-1-strict-json: --json stdout is exactly one parseable JSON object.
+ *   - cli-2-exit-stops: every process.exit(...) is immediately followed by return.
+ *   - cli-6-output-next-action: empty result includes a `nextAction` field.
+ *   - cli-4-dry-run-confirm-mutex: N/A (read-only command).
+ *
+ * Runtime contract compliance:
+ *   - rc-1-treat-as-unknown: worker-status.json parsed content is treated as unknown.
+ *   - rc-2-no-as-bypass: no `as` casts; runtime validation via typeof / Array.isArray.
+ *   - rc-4-validate-array-elements: errors array elements are validated element-wise.
+ *   - rc-5-object-hasown-not-in: Object.hasOwn used for untrusted object key checks.
+ *   - rc-9-no-silent-fallback: missing worker-status.json → workerErrors=[] with
+ *     a `workerStatusMissing` note; parse failures surface a `workerStatusWarning`.
+ */
+import * as path from 'path';
+import * as fs from 'fs';
+import type { Command } from 'commander';
+import { SqliteConnection, SqliteTaskStore } from '@principles/core';
+import { resolveWorkspaceDir } from '../resolve-workspace.js';
+
+/**
+ * Options accepted by the `pd errors list` command.
+ *
+ * `since` is in hours (CLI surface); converted to a Unix-ms timestamp when
+ * passed to SqliteTaskStore.listFailedTasks.
+ */
+export interface ErrorsListOptions {
+  workspace?: string;
+  json?: boolean;
+  kind?: string;
+  since?: number; // hours
+  limit?: number;
+}
+
+/** Default and maximum values for --limit. */
+const DEFAULT_LIMIT = 50;
+const MAX_LIMIT = 200;
+
+/**
+ * Type guard: narrow `unknown` to a plain record (rc-2: no `as` bypass).
+ * Returns true only for non-null, non-array objects.
+ */
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+/**
+ * Normalized worker-status.json error entry. WorkerStatusErrorEntry in
+ * evolution-worker.ts is `{ at, kind, principleId, error }`; legacy entries
+ * are bare strings. We normalize both shapes to a structured form for output.
+ */
+interface WorkerErrorEntry {
+  at: string | null;
+  kind: string | null;
+  principleId: string | null;
+  error: string;
+  rawForm: 'object' | 'string';
+}
+
+/** Aggregated result returned by the command (JSON or text-rendered). */
+interface ErrorsListResult {
+  tasks: unknown[];
+  workerErrors: WorkerErrorEntry[];
+  total: number;
+  workerStatusPath: string;
+  workerStatusMissing?: boolean;
+  workerStatusWarning?: string;
+  nextAction?: string;
+}
+
+/**
+ * Validate and normalize a single worker-status.json errors entry.
+ *
+ * rc-1: input is `unknown` (parsed from JSON).
+ * rc-2: no `as` — uses typeof / Object.hasOwn guards.
+ * rc-5: Object.hasOwn for key checks (not `in`).
+ *
+ * Accepts:
+ *   - string → { error: <string>, rawForm: 'string', others null }
+ *   - { at, kind, principleId, error } → normalized object
+ * Anything else → null (skipped; caller records a warning).
+ */
+function normalizeWorkerErrorEntry(entry: unknown): WorkerErrorEntry | null {
+  if (typeof entry === 'string') {
+    return {
+      at: null,
+      kind: null,
+      principleId: null,
+      error: entry,
+      rawForm: 'string',
+    };
+  }
+  // rc-2: type guard instead of `as` cast (isRecord narrows unknown → record).
+  if (!isRecord(entry)) {
+    return null;
+  }
+  // rc-5: use Object.hasOwn, not `in`, for untrusted object key checks.
+  const at = Object.hasOwn(entry, 'at') && typeof entry.at === 'string' ? entry.at : null;
+  const kind = Object.hasOwn(entry, 'kind') && typeof entry.kind === 'string' ? entry.kind : null;
+  const principleId =
+    Object.hasOwn(entry, 'principleId') && typeof entry.principleId === 'string' ? entry.principleId : null;
+  // `error` is the only required field for the object form; if missing or
+  // non-string, fall back to JSON.stringify so we don't lose the entry.
+  let errorStr: string;
+  if (Object.hasOwn(entry, 'error') && typeof entry.error === 'string') {
+    errorStr = entry.error;
+  } else {
+    try {
+      errorStr = JSON.stringify(entry);
+    } catch {
+      errorStr = '[unserializable worker-status error entry]';
+    }
+  }
+  return {
+    at,
+    kind,
+    principleId,
+    error: errorStr,
+    rawForm: 'object',
+  };
+}
+
+/**
+ * Read and validate the worker-status.json `errors` array.
+ *
+ * Returns `{ entries, missing, warning }`:
+ *   - `missing: true` if the file does not exist (not an error — worker hasn't run).
+ *   - `warning: string` if the file exists but is unparseable / wrong shape
+ *     (rc-9: surface the reason, do not silently swallow).
+ *   - `entries: WorkerErrorEntry[]` validated element-wise (rc-4).
+ */
+function readWorkerStatusErrors(stateDir: string): {
+  entries: WorkerErrorEntry[];
+  missing: boolean;
+  warning: string | null;
+} {
+  const statusPath = path.join(stateDir, 'worker-status.json');
+  if (!fs.existsSync(statusPath)) {
+    return { entries: [], missing: true, warning: null };
+  }
+  let raw: string;
+  try {
+    raw = fs.readFileSync(statusPath, 'utf8');
+  } catch (err) {
+    return {
+      entries: [],
+      missing: false,
+      warning: `Failed to read worker-status.json: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+  // rc-1: parsed JSON is unknown.
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    return {
+      entries: [],
+      missing: false,
+      warning: `Failed to parse worker-status.json: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+  if (!isRecord(parsed)) {
+    return {
+      entries: [],
+      missing: false,
+      warning: 'worker-status.json root is not a JSON object',
+    };
+  }
+  // rc-5: Object.hasOwn for untrusted key check.
+  if (!Object.hasOwn(parsed, 'errors')) {
+    // No `errors` field — treat as empty (older worker-status.json may lack it).
+    return { entries: [], missing: false, warning: null };
+  }
+  const errorsField = parsed.errors;
+  if (!Array.isArray(errorsField)) {
+    return {
+      entries: [],
+      missing: false,
+      warning: 'worker-status.json `errors` field is not an array',
+    };
+  }
+  // rc-4: validate array element types; skip malformed entries.
+  const entries: WorkerErrorEntry[] = [];
+  let skipped = 0;
+  for (const item of errorsField) {
+    const normalized = normalizeWorkerErrorEntry(item);
+    if (normalized === null) {
+      skipped++;
+      continue;
+    }
+    entries.push(normalized);
+  }
+  const warning =
+    skipped > 0
+      ? `Skipped ${skipped} malformed worker-status.json error entr${skipped === 1 ? 'y' : 'ies'}`
+      : null;
+  return { entries, missing: false, warning };
+}
+
+function formatTextOutput(result: ErrorsListResult, workspaceDir: string): string {
+  const lines: string[] = [];
+  lines.push('PD Errors List');
+  lines.push(`  workspace:   ${workspaceDir}`);
+  lines.push(`  total:       ${result.total}  (tasks: ${result.tasks.length}, workerErrors: ${result.workerErrors.length})`);
+  lines.push('');
+  if (result.workerStatusMissing) {
+    lines.push(`  workerStatus: (missing — ${result.workerStatusPath} not found)`);
+  } else if (result.workerStatusWarning) {
+    lines.push(`  workerStatus: WARNING — ${result.workerStatusWarning}`);
+  }
+  if (result.tasks.length > 0) {
+    lines.push('');
+    lines.push('Failed tasks:');
+    for (const t of result.tasks) {
+      // rc-2: type guard instead of `as` cast — tasks come from SqliteTaskStore
+      // which returns FailedTaskSummary[], but we typed tasks as unknown[] to
+      // keep the result interface decoupled from core's type exports.
+      const task = isRecord(t) ? t : null;
+      const taskId = task && typeof task.taskId === 'string' ? task.taskId : '?';
+      const taskKind = task && typeof task.taskKind === 'string' ? task.taskKind : '?';
+      const status = task && typeof task.status === 'string' ? task.status : '?';
+      const lastError = task && typeof task.lastError === 'string' ? task.lastError : '-';
+      const attemptCount = task && typeof task.attemptCount === 'number' ? task.attemptCount : 0;
+      const painId = task && typeof task.painId === 'string' ? task.painId : '-';
+      const lastAttemptAt = task && typeof task.lastAttemptAt === 'string' ? task.lastAttemptAt : '-';
+      lines.push(`  - ${taskId} (${taskKind}) [${status}]`);
+      lines.push(`    painId:        ${painId}`);
+      lines.push(`    lastError:     ${lastError}`);
+      lines.push(`    attemptCount:  ${attemptCount}`);
+      lines.push(`    lastAttemptAt: ${lastAttemptAt}`);
+    }
+  }
+  if (result.workerErrors.length > 0) {
+    lines.push('');
+    lines.push('Worker errors:');
+    for (const e of result.workerErrors) {
+      const at = e.at ?? '-';
+      const kind = e.kind ?? '-';
+      const pid = e.principleId ?? '-';
+      lines.push(`  - [${at}] kind=${kind} principleId=${pid}`);
+      lines.push(`    error: ${e.error}`);
+    }
+  }
+  if (result.total === 0) {
+    lines.push('');
+    lines.push('No errors found. PD pipeline is healthy.');
+  }
+  return lines.join('\n');
+}
+
+export async function handleErrorsList(opts: ErrorsListOptions): Promise<void> {
+  const workspaceDir = opts.workspace ? path.resolve(opts.workspace) : resolveWorkspaceDir();
+  const stateDir = path.join(workspaceDir, '.pd');
+  const stateDbPath = path.join(stateDir, 'state.db');
+
+  // Pre-check: if state.db does not exist, fail loud (cli-2-exit-stops + rc-9).
+  if (!fs.existsSync(stateDbPath)) {
+    const msg = `Error: state.db not found at ${stateDbPath}. Workspace may not be initialized.`;
+    if (opts.json) {
+      // cli-1: even error JSON is a single object on stdout? No — cli-2 says
+      // failure paths write to stderr. JSON error envelope goes to stderr too
+      // so stdout stays clean (cli-1-strict-json guarantees stdout is parseable).
+      process.stderr.write(
+        JSON.stringify(
+          {
+            ok: false,
+            reason: msg,
+            nextAction: 'Run "pd runtime init --confirm --workspace <dir>" to initialize databases, then retry.',
+          },
+          null,
+          2,
+        ) + '\n',
+      );
+    } else {
+      process.stderr.write(msg + '\n');
+    }
+    process.exitCode = 1;
+    return; // cli-2-exit-stops
+  }
+
+  // Resolve and validate --limit.
+  let limit = DEFAULT_LIMIT;
+  if (opts.limit !== undefined) {
+    if (!Number.isFinite(opts.limit) || opts.limit <= 0) {
+      const msg = `Error: --limit must be a positive integer, got ${opts.limit}`;
+      // cli-6-output-next-action: mirror the state.db missing branch — when
+      // opts.json is true, emit a structured { ok:false, reason, nextAction }
+      // envelope to stderr instead of plain text.
+      if (opts.json) {
+        process.stderr.write(
+          JSON.stringify(
+            {
+              ok: false,
+              reason: msg,
+              nextAction: 'Pass --limit as a positive integer (e.g. --limit 50). Maximum is 500.',
+            },
+            null,
+            2,
+          ) + '\n',
+        );
+      } else {
+        process.stderr.write(msg + '\n');
+      }
+      process.exitCode = 1;
+      return; // cli-2-exit-stops
+    }
+    limit = Math.min(opts.limit, MAX_LIMIT);
+  }
+
+  // Resolve --since (hours → Unix-ms timestamp).
+  let sinceMs: number | undefined;
+  if (opts.since !== undefined) {
+    if (!Number.isFinite(opts.since) || opts.since < 0) {
+      const msg = `Error: --since must be a non-negative number of hours, got ${opts.since}`;
+      // cli-6-output-next-action: same JSON envelope pattern as --limit above.
+      if (opts.json) {
+        process.stderr.write(
+          JSON.stringify(
+            {
+              ok: false,
+              reason: msg,
+              nextAction: 'Pass --since as a non-negative number of hours (e.g. --since 24 for the last 24h).',
+            },
+            null,
+            2,
+          ) + '\n',
+        );
+      } else {
+        process.stderr.write(msg + '\n');
+      }
+      process.exitCode = 1;
+      return; // cli-2-exit-stops
+    }
+    sinceMs = Date.now() - opts.since * 3600 * 1000;
+  }
+
+  const connection = new SqliteConnection({ workspaceDir, readonly: true });
+  try {
+    const taskStore = new SqliteTaskStore(connection);
+    const tasks = await taskStore.listFailedTasks({
+      kind: opts.kind,
+      since: sinceMs,
+      limit,
+    });
+
+    const { entries: workerErrors, missing, warning } = readWorkerStatusErrors(stateDir);
+
+    const total = tasks.length + workerErrors.length;
+    const result: ErrorsListResult = {
+      tasks,
+      workerErrors,
+      total,
+      workerStatusPath: path.join(stateDir, 'worker-status.json'),
+    };
+    if (missing) {
+      result.workerStatusMissing = true;
+    }
+    if (warning) {
+      result.workerStatusWarning = warning;
+    }
+    // cli-6-output-next-action: include nextAction only when there are no errors.
+    if (total === 0) {
+      result.nextAction = 'No errors found. PD pipeline is healthy.';
+    }
+
+    if (opts.json) {
+      // cli-1-strict-json: stdout is exactly one parseable JSON object.
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(formatTextOutput(result, workspaceDir));
+    }
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (opts.json) {
+      process.stderr.write(
+        JSON.stringify(
+          {
+            ok: false,
+            reason: `Failed to list errors: ${message}`,
+            nextAction: 'Check workspace path and state.db readability, then retry.',
+          },
+          null,
+          2,
+        ) + '\n',
+      );
+    } else {
+      process.stderr.write(`Error: ${message}\n`);
+    }
+    process.exitCode = 1;
+    return; // cli-2-exit-stops
+  } finally {
+    connection.close();
+  }
+}
+
+/**
+ * Register the `errors` command group with `list` subcommand on a Commander
+ * program. Used by both production CLI (src/index.ts) and parser-level tests
+ * (cli-7-test-wiring).
+ *
+ * The `errors` command group is hidden from `pd --help` (operator diagnostic,
+ * same convention as `legacy` / `artifact` / `runtime recovery`).
+ */
+export function registerErrorsListCommand(program: Command): Command {
+  const errorsCmd = program
+    .command('errors', { hidden: true })
+    .description('PD pipeline error inspection (failed tasks + worker errors)');
+
+  errorsCmd
+    .command('list')
+    .description('List PD pipeline errors — failed tasks + worker-status.json errors')
+    .option('-w, --workspace <path>', 'Workspace directory')
+    .option('--json', 'Output raw JSON (cli-1-strict-json: stdout is exactly one JSON object)')
+    .option('--kind <runnerKind>', 'Filter failed tasks by task_kind (e.g. diagnostician, dreamer)')
+    .option('--since <hours>', 'Only show errors from the last N hours (non-negative number)', parseInt)
+    .option('--limit <n>', 'Max failed tasks to return (default: 50, max: 200)', parseInt)
+    .action(async (opts) => {
+      await handleErrorsList({
+        workspace: opts.workspace,
+        json: opts.json === true,
+        kind: opts.kind,
+        since: opts.since,
+        limit: opts.limit,
+      });
+    });
+
+  return errorsCmd;
+}