@principles/pd-cli 1.147.10 → 1.147.12

package/src/commands/runtime-recovery-failed-tasks.ts

@@ -1,5 +1,10 @@
 import * as path from 'path';
-import { createRecoverySweepService, type RecoverySweepServiceHandle } from '@principles/core/runtime-v2';
+import {
+  createRecoverySweepService,
+  isPeerRunnerKind,
+  isDiagnosticianStageKind,
+  type RecoverySweepServiceHandle,
+} from '@principles/core/runtime-v2';
 import { resolveWorkspaceDir } from '../resolve-workspace.js';
 
 interface RecoveryFailedTasksOptions {
@@ -21,6 +26,50 @@ interface TaskDetail {
   nextAction: string;
 }
 
+/** Stage-task ID convention prefix → the remainder is the parent task ID. */
+const DIAG_STAGE_ID_PREFIXES = ['diag_rootcause-', 'diag_distiller-', 'diag_router-'] as const;
+
+/**
+ * PRI-674 review P2: per-kind execution guidance must point at commands that
+ * actually support the recovered task kind (cli-6-output-next-action).
+ *
+ * Verified against real command surfaces:
+ * - `pd runtime internalization run-once` supports ONLY the 6 peer runner
+ *   kinds (SUPPORTED_RUNNERS in runtime-internalization-run-once.ts).
+ * - `pd diagnose run --task-id <id>` is the only diagnostician execution
+ *   entry (SplitDiagnosticianRunner runs the full A→B→C pipeline from the
+ *   PARENT task; running a diag_* stage as parent would create bogus nested
+ *   stage tasks).
+ * - diag_* stage linkage: persisted inputRef = parent task ID
+ *   (SplitDiagnosticianRunner.ensureSubTask), with the
+ *   diag_<stage>-<parentTaskId> ID convention as fallback. When the parent
+ *   cannot be resolved we say so instead of printing a guessed command.
+ */
+function buildExecutionNextAction(t: { taskId: string; taskKind: string; inputRef: string | null }): string {
+  // Branch on the authoritative taskKind, never on taskId shape.
+  if (isDiagnosticianStageKind(t.taskKind)) {
+    // Parent from persisted inputRef; fallback: diag_<stage>-<parentTaskId>
+    // ID convention (plain prefix split — no regex needed for fixed literals).
+    const matchedPrefix = DIAG_STAGE_ID_PREFIXES.find((p) => t.taskId.startsWith(p));
+    const parentTaskId = t.inputRef && t.inputRef.trim() !== ''
+      ? t.inputRef
+      : matchedPrefix
+        ? t.taskId.slice(matchedPrefix.length).trim() || undefined
+        : undefined;
+    if (parentTaskId) {
+      return `Stage task of diagnostician parent "${parentTaskId}". Recover the parent, then run: pd diagnose run --task-id ${parentTaskId} (runs the full pipeline including this stage)`;
+    }
+    return `Stage task whose diagnostician parent could not be resolved (no inputRef linkage, task ID does not follow diag_<stage>-<parentTaskId>). Inspect: pd diagnose status --task-id ${t.taskId} — do not run a stage task directly as a parent`;
+  }
+  if (t.taskKind === 'diagnostician') {
+    return `Run: pd diagnose run --task-id ${t.taskId} (executes the full diag_rootcause→diag_distiller→diag_router pipeline)`;
+  }
+  if (isPeerRunnerKind(t.taskKind)) {
+    return `Run: pd runtime internalization run-once --runner ${t.taskKind} (executes the next ready ${t.taskKind} task)`;
+  }
+  return `Task kind ${t.taskKind} has no registered CLI execution entry. Inspect: pd diagnose status --task-id ${t.taskId}, or use the Console failed-tasks page`;
+}
+
 export async function handleRuntimeRecoveryFailedTasks(opts: RecoveryFailedTasksOptions): Promise<void> {
   if (opts.dryRun && opts.confirm) {
     if (opts.json) {
@@ -78,7 +127,7 @@ export async function handleRuntimeRecoveryFailedTasks(opts: RecoveryFailedTasks
               reason: t.isExhausted
                 ? `Task exhausted max attempts (${t.attemptCount}/${t.maxAttempts}) but --force specified — reset to pending`
                 : `Task failed and attempts remain (${t.attemptCount}/${t.maxAttempts}) — reset to pending`,
-              nextAction: 'Task recovered to pending. Run pd runtime internalization run-once to execute.',
+              nextAction: `Task recovered to pending. ${buildExecutionNextAction({ taskId: t.taskId, taskKind: t.taskKind, inputRef: t.inputRef })}`,
             });
           } else {
             skippedCount++;
@@ -117,7 +166,7 @@ export async function handleRuntimeRecoveryFailedTasks(opts: RecoveryFailedTasks
 
     if (isDryRun) {
       if (taskDetails.length === 0) {
-        summaryReason = 'No failed internalization tasks found';
+        summaryReason = 'No failed internalization or diagnostician tasks found';
         summaryNextAction = 'Nothing to recover';
       } else {
         summaryReason = `Found ${recoveredCount} recoverable and ${skippedCount} exhausted failed tasks`;
@@ -125,9 +174,37 @@ export async function handleRuntimeRecoveryFailedTasks(opts: RecoveryFailedTasks
       }
     } else {
       summaryReason = `Successfully recovered ${recoveredCount} failed tasks, skipped ${skippedCount} tasks`;
-      summaryNextAction = recoveredCount > 0
-        ? 'Run pd runtime internalization run-once to execute recovered tasks'
-        : 'No tasks recovered';
+      // PRI-674 review P2: mixed recoveries span different executors — split
+      // the summary by actual command surface instead of one command for all.
+      if (recoveredCount > 0) {
+        const diagParents: string[] = [];
+        const diagStages: string[] = [];
+        const peerTasks: string[] = [];
+        const otherTasks: string[] = [];
+        for (const t of taskDetails) {
+          if (t.action !== 'recovered') continue;
+          if (t.taskKind === 'diagnostician') diagParents.push(t.taskId);
+          else if (isDiagnosticianStageKind(t.taskKind)) diagStages.push(t.taskId);
+          else if (isPeerRunnerKind(t.taskKind)) peerTasks.push(t.taskId);
+          else otherTasks.push(t.taskId);
+        }
+        const lines: string[] = [];
+        if (diagParents.length > 0) {
+          lines.push(`For diagnostician parent task(s) (${diagParents.join(', ')}): pd diagnose run --task-id <taskId>`);
+        }
+        if (diagStages.length > 0) {
+          lines.push(`For diag_* stage task(s) (${diagStages.join(', ')}): recover the parent diagnostician task, then pd diagnose run --task-id <parentTaskId> (each stage's parent is in its per-task nextAction)`);
+        }
+        if (peerTasks.length > 0) {
+          lines.push(`For internalization task(s) (${peerTasks.join(', ')}): pd runtime internalization run-once --runner <kind>`);
+        }
+        if (otherTasks.length > 0) {
+          lines.push(`For other task(s) (${otherTasks.join(', ')}): no registered CLI execution entry — see per-task nextAction`);
+        }
+        summaryNextAction = `Tasks recovered to pending. Execute by kind: ${lines.join('; ')}`;
+      } else {
+        summaryNextAction = 'No tasks recovered';
+      }
     }
 
     if (opts.json) {

package/src/index.ts

@@ -870,9 +870,12 @@ const diagnosticsCmd = runtimeCmd
   .command('diagnostics', { hidden: true })
   .description('Control plane diagnostic bundle operations');
 
+// PRI-674: visible (was hidden) — the only recovery re-entry point for an
+// Owner without Console access; hidden-ness left failed diagnostician tasks
+// undiscoverable.
 const recoveryCmd = runtimeCmd
-  .command('recovery', { hidden: true })
-  .description('Runtime V2 lease recovery operations');
+  .command('recovery')
+  .description('Runtime V2 recovery operations (expired-lease sweep, failed-task recovery)');
 
 // PRI-555 phase 1: dry-run-only artifact identity drift repair planner.
 runtimeCmd
@@ -907,7 +910,7 @@ recoveryCmd
 
 recoveryCmd
   .command('failed-tasks')
-  .description('Recover failed internalization tasks')
+  .description('Recover failed internalization and diagnostician tasks')
   .option('-w, --workspace <path>', 'Workspace directory')
   .option('--dry-run', 'Report only, no modifications (default)')
   .option('--confirm', 'Actually recover failed tasks')

package/tests/commands/cli-help-snapshot.test.ts

@@ -81,12 +81,18 @@ describe('PRI-455: pd runtime --help shows only MVP owner subcommands', () => {
     expect(runtimeHelp).toMatch(/\bfeatures\b/);
   });
 
+  // PRI-674: recovery is now owner-facing — it is the only failed-task
+  // recovery re-entry point for an Owner without Console access, so hiding
+  // it made failed diagnostician tasks undiscoverable.
+  it('runtime --help shows recovery', () => {
+    expect(runtimeHelp).toMatch(/^\s+recovery\b/m);
+  });
+
   // Operator subcommands that should be hidden
   const HIDDEN_RUNTIME_SUBCOMMANDS = [
     'canary',
     'synthetic',
     'uat',
-    'recovery',
     'pruning',
     'diagnostics',
     'probe',