@principles/pd-cli 1.133.0 → 1.134.0

package/src/commands/pain-record.ts

@@ -32,6 +32,27 @@ export async function handlePainRecord(opts: RecordOptions): Promise<void> {
     console.error('Error: --reason <text> is required');
     console.error('Usage: pd pain record --reason <text> [--score N] [--source manual] [--workspace <path>] [--session <id>] [--json]');
     process.exit(1);
+    return;
+  }
+
+  // Bug-P fix: enforce reason length limit to prevent oversized data entering the pipeline.
+  // Consistent with pain-flood-simulation.ts (MAX_REASON_LENGTH = 500) and synthetic-baseline.ts.
+  // CodeRabbit review fix: emit JSON on --json and stop execution after exit (cli-1, cli-2, cli-5).
+  const MAX_REASON_LENGTH = 500;
+  if (opts.reason.length > MAX_REASON_LENGTH) {
+    if (opts.json) {
+      console.log(JSON.stringify({
+        status: 'failed',
+        reason: 'reason_too_long',
+        message: `--reason must be at most ${MAX_REASON_LENGTH} characters (got ${opts.reason.length})`,
+        nextAction: 'Shorten the reason text or split it into multiple pain records.',
+      }, null, 2));
+    } else {
+      console.error(`Error: --reason must be at most ${MAX_REASON_LENGTH} characters (got ${opts.reason.length})`);
+      console.error('Next action: shorten the reason text or split into multiple pain records.');
+    }
+    process.exit(1);
+    return;
   }
 
   if (opts.score !== undefined && (isNaN(opts.score) || opts.score < 0 || opts.score > 100)) {

package/src/commands/pain-retry.ts

@@ -36,13 +36,23 @@ import {
   isFeatureEnabled,
   SPLIT_PIPELINE_TOTAL_TIMEOUT_MS,
   PrincipleTreeLedgerAdapter,
+  SqliteDeadLetterStore,
+  PainSignalBridge,
+  type PainDetectedData,
+  type PainSignalBridgeResult,
+  type DeadLetterRow,
 } from '@principles/core/runtime-v2';
 import type { PDRuntimeAdapter, RuntimeConfig, OutputLanguage } from '@principles/core/runtime-v2';
+import type { Command } from 'commander';
 import { loadPdConfig, computeFlagsFromLoadResult } from '../services/pd-config-loader.js';
 import { resolveRuntimeFromPdConfig } from '../services/resolve-runtime-from-pd-config.js';
+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 type { PDTaskStatus } from '@principles/core/runtime-v2';
 import { readOutputLanguageFromWorkspace } from '../config-reader.js';
 import { resolveWorkspaceDir } from '../resolve-workspace.js';
+import { checkAdmissionGate } from './admission-gate.js';
 import * as path from 'path';
 
 // ── Types ──────────────────────────────────────────────────────────────────────
@@ -61,6 +71,7 @@ interface PainRetryOptions {
   apiKeyEnv?: string;
   baseUrl?: string;
   maxRetries?: number;
+  maxTokens?: number;
   timeoutMs?: number;
 }
 
@@ -92,8 +103,116 @@ function readNonBlankString(value: unknown): string | null {
   return typeof value === 'string' && value.trim().length > 0 ? value : null;
 }
 
+/**
+ * Validate that an unknown value (read from dead_letter_pains.pain_data) has
+ * the shape of PainDetectedData.
+ *
+ * rc-1: Treat parsed JSON as unknown.
+ * rc-2: No `as` bypass — use typeof checks and literal narrowing.
+ * rc-3: Required fields (painId, painType, source, reason) fail loud.
+ * rc-5: Use Object.hasOwn for field presence checks on untrusted objects.
+ */
+function parsePainDetectedData(value: unknown):
+  | { valid: true; data: PainDetectedData }
+  | { valid: false; error: string } {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    return {
+      valid: false,
+      error: `painData is not an object (got ${value === null ? 'null' : Array.isArray(value) ? 'array' : typeof value})`,
+    };
+  }
+  const obj = value as Record<string, unknown>;
+
+  // Detect dead-letter error envelopes from SqliteDeadLetterStore parse/serialize failures.
+  if (Object.hasOwn(obj, '__deadLetterParseError') || Object.hasOwn(obj, '__deadLetterSerializeError')) {
+    return {
+      valid: false,
+      error: `painData contains dead-letter error envelope: ${JSON.stringify(obj)}`,
+    };
+  }
+
+  // Required string fields
+  if (typeof obj.painId !== 'string' || obj.painId.trim().length === 0) {
+    return { valid: false, error: `painData.painId is not a non-blank string (got ${JSON.stringify(obj.painId)})` };
+  }
+  if (typeof obj.source !== 'string') {
+    return { valid: false, error: `painData.source is not a string (got ${JSON.stringify(obj.source)})` };
+  }
+  if (typeof obj.reason !== 'string') {
+    return { valid: false, error: `painData.reason is not a string (got ${JSON.stringify(obj.reason)})` };
+  }
+
+  // painType: narrow to literal union without `as`.
+  const painTypeRaw = obj.painType;
+  if (painTypeRaw !== 'tool_failure' && painTypeRaw !== 'dispatch_error'
+      && painTypeRaw !== 'subagent_error' && painTypeRaw !== 'user_frustration') {
+    return { valid: false, error: `painData.painType is not a valid pain type (got ${JSON.stringify(painTypeRaw)})` };
+  }
+  // After the narrowing check above, TypeScript infers painTypeRaw as the literal union.
+  const painType: PainDetectedData['painType'] = painTypeRaw === 'dispatch_error' ? 'tool_failure' : painTypeRaw;
+
+  // Build the typed object field-by-field. Optional fields are added only when present and valid.
+  const data: PainDetectedData = {
+    painId: obj.painId,
+    painType,
+    source: obj.source,
+    reason: obj.reason,
+  };
+
+  if (Object.hasOwn(obj, 'score')) {
+    if (typeof obj.score !== 'number' || !Number.isFinite(obj.score)) {
+      return { valid: false, error: `painData.score is not a finite number (got ${JSON.stringify(obj.score)})` };
+    }
+    data.score = obj.score;
+  }
+  if (Object.hasOwn(obj, 'sessionId')) {
+    if (typeof obj.sessionId !== 'string') return { valid: false, error: 'painData.sessionId is not a string' };
+    data.sessionId = obj.sessionId;
+  }
+  if (Object.hasOwn(obj, 'agentId')) {
+    if (typeof obj.agentId !== 'string') return { valid: false, error: 'painData.agentId is not a string' };
+    data.agentId = obj.agentId;
+  }
+  if (Object.hasOwn(obj, 'taskId')) {
+    if (typeof obj.taskId !== 'string') return { valid: false, error: 'painData.taskId is not a string' };
+    data.taskId = obj.taskId;
+  }
+  if (Object.hasOwn(obj, 'traceId')) {
+    if (typeof obj.traceId !== 'string') return { valid: false, error: 'painData.traceId is not a string' };
+    data.traceId = obj.traceId;
+  }
+  if (Object.hasOwn(obj, 'provenance')) {
+    const prov = obj.provenance;
+    if (prov !== 'openclaw_context_bound' && prov !== 'owner_reported_no_host_trace' && prov !== 'automatic_hook') {
+      return { valid: false, error: `painData.provenance is not a known literal (got ${JSON.stringify(prov)})` };
+    }
+    data.provenance = prov;
+  }
+  if (Object.hasOwn(obj, 'evidence')) {
+    if (!Array.isArray(obj.evidence)) {
+      return { valid: false, error: 'painData.evidence is not an array' };
+    }
+    // Validate each entry has the PainEvidenceEntry shape { sourceRef: string, note: string }.
+    const evidence: { sourceRef: string; note: string }[] = [];
+    for (let i = 0; i < obj.evidence.length; i++) {
+      const entry = obj.evidence[i];
+      if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) {
+        return { valid: false, error: `painData.evidence[${i}] is not an object` };
+      }
+      const e = entry as Record<string, unknown>;
+      if (typeof e.sourceRef !== 'string' || typeof e.note !== 'string') {
+        return { valid: false, error: `painData.evidence[${i}] missing string fields sourceRef/note` };
+      }
+      evidence.push({ sourceRef: e.sourceRef, note: e.note });
+    }
+    data.evidence = evidence;
+  }
+
+  return { valid: true, data };
+}
+
 /** Output a refused/not_found result, respecting --json mode. Exits with code 1. */
-function refuseExit(opts: PainRetryOptions, payload: { status?: string; painId: string; taskId?: string; reason: string; message?: string; nextAction: string }): never {
+function refuseExit(opts: PainRetryOptions, payload: { status?: string; painId: string; taskId?: string; reason: string; message?: string; nextAction: string }): void {
   if (opts.json) {
     console.log(JSON.stringify({
       status: payload.status ?? 'refused',
@@ -117,8 +236,9 @@ export async function handlePainRetry(opts: PainRetryOptions): Promise<void> {
 
   // Step 1: Resolve painId → taskId
   const resolution = resolveTaskIdFromPainId(opts.painId);
+  // eslint-disable-next-line no-restricted-syntax -- 'in' required for discriminated union narrowing (taskId vs reason/nextAction)
   if ('reason' in resolution) {
-    refuseExit(opts, { painId: opts.painId, reason: resolution.reason, nextAction: resolution.nextAction });
+    return refuseExit(opts, { painId: opts.painId, reason: resolution.reason, nextAction: resolution.nextAction });
   }
 
   const { taskId } = resolution;
@@ -130,19 +250,39 @@ export async function handlePainRetry(opts: PainRetryOptions): Promise<void> {
     await stateManager.initialize();
 
     const task = await stateManager.getTask(taskId);
+
+    // Dead letter replay: when no task exists, check if the pain signal was
+    // persisted to dead_letter_pains (rc-9: no silent failure in pain.ts).
+    // If found, replay it through PainSignalBridge.onPainDetected.
+    let deadLetterReplay: { data: PainDetectedData; row: DeadLetterRow } | null = null;
     if (!task) {
-      refuseExit(opts, {
-        status: 'not_found',
-        painId: opts.painId,
-        taskId,
-        reason: 'task_not_found',
-        message: `No task found for painId '${opts.painId}' (looked for taskId '${taskId}')`,
-        nextAction: `Verify the painId is correct. Use 'pd task list --kind diagnostician' to see all diagnostician tasks.`,
-      });
+      const dlStore = new SqliteDeadLetterStore(stateManager.connection);
+      const dlRow = dlStore.getByPainId(opts.painId);
+      if (!dlRow) {
+        return refuseExit(opts, {
+          status: 'not_found',
+          painId: opts.painId,
+          taskId,
+          reason: 'task_not_found',
+          message: `No task found for painId '${opts.painId}' (looked for taskId '${taskId}') and no dead letter found`,
+          nextAction: `Verify the painId is correct. Use 'pd task list --kind diagnostician' to see all diagnostician tasks.`,
+        });
+      }
+      const parseResult = parsePainDetectedData(dlRow.painData);
+      if (!parseResult.valid) {
+        return refuseExit(opts, {
+          painId: opts.painId,
+          taskId,
+          reason: 'dead_letter_corrupt',
+          message: `Dead letter for painId '${opts.painId}' has corrupt painData: ${parseResult.error}`,
+          nextAction: `The dead letter row cannot be replayed. Inspect the dead_letter_pains table directly: SELECT * FROM dead_letter_pains WHERE pain_id = '${opts.painId}'`,
+        });
+      }
+      deadLetterReplay = { data: parseResult.data, row: dlRow };
     }
 
-    if (task.taskKind !== 'diagnostician') {
-      refuseExit(opts, {
+    if (task && task.taskKind !== 'diagnostician') {
+      return refuseExit(opts, {
         painId: opts.painId,
         taskId,
         reason: 'wrong_task_kind',
@@ -151,11 +291,13 @@ export async function handlePainRetry(opts: PainRetryOptions): Promise<void> {
       });
     }
 
-    const previousTaskStatus = task.status;
-    const previousLastError = task.lastError ?? null;
+    // For dead letter replay there is no prior task; synthesize a status so the
+    // existing logging/output paths have a non-null value to print.
+    const previousTaskStatus: PDTaskStatus | 'dead_lettered' = task ? task.status : 'dead_lettered';
+    const previousLastError = task ? (task.lastError ?? null) : null;
 
-    if (task.status === 'succeeded' && !opts.force) {
-      refuseExit(opts, {
+    if (task && task.status === 'succeeded' && !opts.force) {
+      return refuseExit(opts, {
         painId: opts.painId,
         taskId,
         reason: 'already_succeeded',
@@ -164,8 +306,8 @@ export async function handlePainRetry(opts: PainRetryOptions): Promise<void> {
       });
     }
 
-    if (!RETRYABLE_STATUSES.has(task.status) && task.status !== 'succeeded') {
-      refuseExit(opts, {
+    if (task && !RETRYABLE_STATUSES.has(task.status) && task.status !== 'succeeded') {
+      return refuseExit(opts, {
         painId: opts.painId,
         taskId,
         reason: 'status_not_retryable',
@@ -178,7 +320,7 @@ export async function handlePainRetry(opts: PainRetryOptions): Promise<void> {
     // P1 fix: --openclaw-local and --openclaw-gateway are mutually exclusive.
     // Must output JSON when --json is set (CLI operator gate).
     if (opts.openclawLocal && opts.openclawGateway) {
-      refuseExit(opts, {
+      return refuseExit(opts, {
         painId: opts.painId,
         taskId,
         reason: 'conflicting_flags',
@@ -200,7 +342,7 @@ export async function handlePainRetry(opts: PainRetryOptions): Promise<void> {
     }
 
     if (!runtimeKind) {
-      refuseExit(opts, {
+      return refuseExit(opts, {
         painId: opts.painId,
         taskId,
         reason: 'missing_runtime',
@@ -216,14 +358,14 @@ export async function handlePainRetry(opts: PainRetryOptions): Promise<void> {
       const resolved = resolveRuntimeFromPdConfig(workspaceDir);
       const configResult = resolved.result;
       if (isRuntimeConfigError(configResult)) {
-        refuseExit(opts, { painId: opts.painId, taskId, reason: configResult.reason, message: configResult.message, nextAction: configResult.nextAction });
+        return refuseExit(opts, { painId: opts.painId, taskId, reason: configResult.reason, message: configResult.message, nextAction: configResult.nextAction });
       }
       const { openclawMode } = configResult;
       // CLI flags override config (PRI-393)
       const flagMode = opts.openclawLocal ? 'local' as const : opts.openclawGateway ? 'gateway' as const : undefined;
       const effectiveMode = flagMode ?? openclawMode;
       if (!effectiveMode) {
-        refuseExit(opts, {
+        return refuseExit(opts, {
           painId: opts.painId,
           taskId,
           reason: 'missing_openclaw_mode',
@@ -279,6 +421,7 @@ export async function handlePainRetry(opts: PainRetryOptions): Promise<void> {
       const apiKeyEnv = opts.apiKeyEnv ?? policyConfig?.apiKeyEnv;
       const baseUrl = opts.baseUrl ?? policyConfig?.baseUrl;
       const maxRetries = opts.maxRetries ?? policyConfig?.maxRetries;
+      const maxTokens = opts.maxTokens ?? policyConfig?.maxTokens;
       const effectiveTimeoutMs = opts.timeoutMs ?? policyConfig?.timeoutMs;
 
       // Validate required string fields: must be non-blank strings
@@ -287,7 +430,7 @@ export async function handlePainRetry(opts: PainRetryOptions): Promise<void> {
       if (readNonBlankString(model) === null) missing.push('model');
       if (readNonBlankString(apiKeyEnv) === null) missing.push('apiKeyEnv');
       if (missing.length > 0) {
-        refuseExit(opts, {
+        return refuseExit(opts, {
           painId: opts.painId,
           taskId,
           reason: `missing_required_config: ${missing.join(', ')}`,
@@ -304,12 +447,15 @@ export async function handlePainRetry(opts: PainRetryOptions): Promise<void> {
       if (effectiveTimeoutMs !== undefined && effectiveTimeoutMs !== null && !(Number.isFinite(effectiveTimeoutMs) && effectiveTimeoutMs > 0)) {
         invalidNumeric.push(`timeoutMs (got: ${effectiveTimeoutMs})`);
       }
+      if (maxTokens !== undefined && maxTokens !== null && !(Number.isFinite(maxTokens) && maxTokens > 0)) {
+        invalidNumeric.push(`maxTokens (got: ${maxTokens})`);
+      }
       if (invalidNumeric.length > 0) {
-        refuseExit(opts, {
+        return refuseExit(opts, {
           painId: opts.painId,
           taskId,
           reason: `invalid_numeric_config: ${invalidNumeric.join(', ')}`,
-          message: `Invalid numeric pi-ai config: ${invalidNumeric.join(', ')}. maxRetries must be a non-negative integer; timeoutMs must be a positive number.`,
+          message: `Invalid numeric pi-ai config: ${invalidNumeric.join(', ')}. maxRetries must be a non-negative integer; timeoutMs and maxTokens must be positive numbers.`,
           nextAction: 'Fix the numeric values and retry.',
         });
       }
@@ -319,7 +465,7 @@ export async function handlePainRetry(opts: PainRetryOptions): Promise<void> {
       const validModel = readNonBlankString(model);
       const validApiKeyEnv = readNonBlankString(apiKeyEnv);
       if (validProvider === null || validModel === null || validApiKeyEnv === null) {
-        refuseExit(opts, {
+        return refuseExit(opts, {
           painId: opts.painId,
           taskId,
           reason: 'internal_validation_error',
@@ -329,7 +475,7 @@ export async function handlePainRetry(opts: PainRetryOptions): Promise<void> {
       }
 
       if (!process.env[validApiKeyEnv]) {
-        refuseExit(opts, {
+        return refuseExit(opts, {
           painId: opts.painId,
           taskId,
           reason: 'missing_api_key',
@@ -344,11 +490,12 @@ export async function handlePainRetry(opts: PainRetryOptions): Promise<void> {
         apiKeyEnv: validApiKeyEnv,
         baseUrl,
         maxRetries,
+        maxTokens,
         timeoutMs: effectiveTimeoutMs,
         workspace: workspaceDir,
       });
     } else {
-      refuseExit(opts, {
+      return refuseExit(opts, {
         painId: opts.painId,
         taskId,
         reason: `unknown_runtime: '${runtimeKind}'`,
@@ -378,21 +525,37 @@ export async function handlePainRetry(opts: PainRetryOptions): 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 pain retry] .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-pain-retry', runtimeKind: resolvedKind, outputLanguage },
+        { stateManager, runtimeAdapter, eventEmitter, artifactStore: stateManager.piArtifactStore, validator: new DefaultDiagRootCauseValidator(), contextAssembler, contentHashFn },
+        { owner: 'pd-cli-pain-retry', runtimeKind: resolvedKind, outputLanguage, timeoutMs: perStageTimeoutMs, effectiveConfig },
       );
       const distillerRunner = new DiagDistillerRunner(
-        { stateManager, runtimeAdapter, eventEmitter, artifactStore: stateManager.piArtifactStore, validator: new DefaultDiagDistillerValidator() },
-        { owner: 'pd-cli-pain-retry', runtimeKind: resolvedKind, outputLanguage },
+        { stateManager, runtimeAdapter, eventEmitter, artifactStore: stateManager.piArtifactStore, validator: new DefaultDiagDistillerValidator(), contentHashFn },
+        { owner: 'pd-cli-pain-retry', runtimeKind: resolvedKind, outputLanguage, timeoutMs: perStageTimeoutMs, effectiveConfig },
       );
       const routerRunner = new DiagRouterRunner(
-        { stateManager, runtimeAdapter, eventEmitter, artifactStore: stateManager.piArtifactStore, committer },
-        { owner: 'pd-cli-pain-retry', runtimeKind: resolvedKind, outputLanguage },
+        { stateManager, runtimeAdapter, eventEmitter, artifactStore: stateManager.piArtifactStore, committer, contentHashFn },
+        { owner: 'pd-cli-pain-retry', runtimeKind: resolvedKind, outputLanguage, timeoutMs: perStageTimeoutMs, effectiveConfig },
       );
 
       runner = new SplitDiagnosticianRunner({
@@ -401,12 +564,120 @@ export async function handlePainRetry(opts: PainRetryOptions): Promise<void> {
         routerRunner,
         stateManager,
         committer,
-        perStageTimeoutMs: pipelineTimeoutMs / 3,
+        perStageTimeoutMs,
       });
     } else {
       runner = new DisabledDiagnosticianRunner();
     }
 
+    // ── Dead letter replay branch ──────────────────────────────────────────
+    // When task was null but a dead letter was found, replay the pain signal
+    // through PainSignalBridge.onPainDetected instead of calling diagnoseRun.
+    // On success/failure, markRetried updates the dead_letter_pains row.
+    if (deadLetterReplay) {
+      const dlStore = new SqliteDeadLetterStore(stateManager.connection);
+      if (!opts.json) {
+        console.log(`\nReplaying dead letter pain: ${opts.painId}`);
+        console.log(`  Task ID:        ${taskId}`);
+        console.log(`  Dead Letter ID: ${deadLetterReplay.row.id}`);
+        console.log(`  Failed At:      ${deadLetterReplay.row.failedAt}`);
+        console.log(`  Retry Count:    ${deadLetterReplay.row.retryCount}`);
+        console.log(`  Runtime:        ${runtimeKind}`);
+        console.log(`  Workspace:      ${workspaceDir}\n`);
+      }
+
+      const ledgerAdapter = new PrincipleTreeLedgerAdapter({ stateDir: path.join(workspaceDir, '.state') });
+      const intakeService = new CandidateIntakeService({ stateManager, ledgerAdapter });
+      const bridge = new PainSignalBridge({
+        stateManager,
+        runner,
+        intakeService,
+        ledgerAdapter,
+        owner: 'pd-cli-pain-retry-dead-letter',
+        workspaceDir,
+      });
+
+      let bridgeResult: PainSignalBridgeResult;
+      try {
+        bridgeResult = await bridge.onPainDetected(deadLetterReplay.data);
+      } catch (err: unknown) {
+        const errorMessage = err instanceof Error ? err.message : String(err);
+        const markFail = dlStore.markRetried(opts.painId, false);
+        if (opts.json) {
+          console.log(JSON.stringify({
+            status: 'failed',
+            painId: opts.painId,
+            taskId,
+            source: 'dead_letter',
+            deadLetterId: deadLetterReplay.row.id,
+            runtimeKind,
+            errorCategory: 'execution_failed',
+            message: errorMessage,
+            markRetriedOk: markFail.ok,
+            nextAction: 'Replay threw; retry_count incremented. Adjust parameters and run pd pain retry --pain-id again.',
+          }, null, 2));
+        } else {
+          console.error(`error: ${errorMessage}`);
+          console.error(`nextAction: Replay threw; retry_count incremented. Adjust parameters and try again.`);
+        }
+        process.exit(1);
+        return;
+      }
+
+      const success = bridgeResult.status === 'succeeded';
+      const markResult = dlStore.markRetried(opts.painId, success);
+
+      if (opts.json) {
+        // cli-1-strict-json: exactly one parseable JSON object on stdout.
+        console.log(JSON.stringify({
+          status: success ? 'succeeded' : 'failed',
+          painId: opts.painId,
+          taskId,
+          source: 'dead_letter',
+          deadLetterId: deadLetterReplay.row.id,
+          runtimeKind,
+          bridgeStatus: bridgeResult.status,
+          candidateIds: bridgeResult.candidateIds,
+          ledgerEntryIds: bridgeResult.ledgerEntryIds,
+          markRetriedOk: markResult.ok,
+          message: bridgeResult.message ?? null,
+          nextAction: success
+            ? (bridgeResult.candidateIds.length > 0
+              ? `Dead letter replayed. Internalize candidates:\n  ${bridgeResult.candidateIds.map((id) => `pd candidate internalize --candidate-id ${id} --workspace "${workspaceDir}"`).join('\n  ')}`
+              : 'Dead letter replayed. No candidates generated.')
+            : `Replay did not succeed (status=${bridgeResult.status}). The dead letter remains available for future retry.`,
+        }, null, 2));
+        if (!success) {
+          process.exit(1);
+        }
+        return;
+      }
+
+      // Text output
+      console.log(`\nReplay ${success ? 'succeeded' : 'failed'}:`);
+      console.log(`  Pain ID:         ${opts.painId}`);
+      console.log(`  Task ID:         ${taskId}`);
+      console.log(`  Dead Letter ID:  ${deadLetterReplay.row.id}`);
+      console.log(`  Bridge Status:   ${bridgeResult.status}`);
+      if (bridgeResult.message) {
+        console.log(`  Message:         ${bridgeResult.message}`);
+      }
+      if (success) {
+        console.log(`  Candidates:      ${bridgeResult.candidateIds.length}`);
+        if (bridgeResult.candidateIds.length > 0) {
+          console.log(`  Ledger Entries:  ${bridgeResult.ledgerEntryIds.length}`);
+        }
+      }
+      console.log(`  Mark Retried:    ${markResult.ok ? 'ok' : `FAILED: ${markResult.error}`}`);
+      if (!success) {
+        console.log(`\n  Next Action:`);
+        console.log(`  Replay did not succeed. The dead letter remains available for future retry.`);
+        process.exit(1);
+      }
+      return;
+    }
+
+    // ── Normal retry branch ─────────────────────────────────────────────────
     if (!opts.json) {
       console.log(`\nRetrying diagnosis for pain: ${opts.painId}`);
       console.log(`  Task ID:  ${taskId}`);
@@ -463,6 +734,23 @@ export async function handlePainRetry(opts: PainRetryOptions): 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 pain retry` 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') {
@@ -548,6 +836,7 @@ export async function handlePainRetry(opts: PainRetryOptions): Promise<void> {
 
     if (intakeFailed) {
       process.exit(1);
+      return;
     }
   } catch (error: unknown) {
     const message = error instanceof Error ? error.message : String(error);
@@ -568,7 +857,36 @@ export async function handlePainRetry(opts: PainRetryOptions): Promise<void> {
       console.error(`error: ${message} (${errorCategory})`);
     }
     process.exit(1);
+    return;
   } finally {
     await stateManager.close();
   }
 }
+
+/** Register the production `pd pain retry` command and its complete option contract. */
+export function registerPainRetryCommand(
+  painCmd: Command,
+  handler: (opts: PainRetryOptions) => Promise<void> = handlePainRetry,
+): Command {
+  return painCmd
+    .command('retry')
+    .description('Retry a failed diagnosis by pain ID')
+    .requiredOption('-p, --pain-id <painId>', 'Pain ID to retry diagnosis for')
+    .option('-w, --workspace <path>', 'Workspace directory')
+    .option('-r, --runtime <kind>', "Runtime kind: 'openclaw-cli', 'test-double', 'pi-ai'")
+    .option('--openclaw-local', 'Use local OpenClaw (mutually exclusive with --openclaw-gateway)')
+    .option('--openclaw-gateway', 'Use gateway OpenClaw (mutually exclusive with --openclaw-local)')
+    .option('-a, --agent <agentId>', 'Agent ID to invoke')
+    .option('--provider <name>', 'LLM provider (e.g., openrouter) — for pi-ai, falls back to policy')
+    .option('--model <id>', 'Model ID (e.g., anthropic/claude-sonnet-4) — for pi-ai, falls back to policy')
+    .option('--apiKeyEnv <name>', 'Env var name for API key — for pi-ai, falls back to policy')
+    .option('--baseUrl <url>', 'Custom base URL — for pi-ai, falls back to policy')
+    .option('--maxRetries <n>', 'Max retry attempts for LLM failures — for pi-ai, falls back to policy', parseInt)
+    .option('--maxTokens <n>', 'Max output tokens (max_tokens) for pi-ai LLM calls — for pi-ai, falls back to policy', parseInt)
+    .option('--timeoutMs <ms>', 'Timeout in milliseconds — for pi-ai, falls back to policy', parseInt)
+    .option('--force', 'Allow retry of already-succeeded tasks')
+    .option('--json', 'Output raw JSON')
+    .action(async (opts: PainRetryOptions) => {
+      await handler(opts);
+    });
+}

package/src/commands/proven-channel-baseline.ts

@@ -101,8 +101,10 @@ export async function handleProvenChannelBaseline(opts: ProvenChannelBaselineCli
     }
 
     if (summary.status !== 'passed') {
-      console.error('');
-      console.error(`FAIL: status=${summary.status}`);
+      if (!opts.json) {
+        console.error('');
+        console.error(`FAIL: status=${summary.status}`);
+      }
       process.exitCode = 1;
     }
   } finally {