@principles/pd-cli 1.98.0 → 1.100.0

package/src/commands/runtime-internalization-run-once.ts

@@ -575,60 +575,76 @@ export async function handleRuntimeInternalizationRunOnce(opts: RunOnceOptions):
       const artifactStore = stateManager.piArtifactStore;
       const runtimeAdapter = resolveRuntimeAdapter({ runtimeKind, taskId: wakeResult.taskId, workspaceDir, runnerKind, timeoutMs: cliTimeoutMs });
 
-      if (runnerKind === 'dreamer') {
-        const validator = new DefaultDreamerValidator();
-        const runner = new DreamerRunner(
-          { stateManager, runtimeAdapter, eventEmitter, validator, artifactStore },
-          { owner: OWNER, runtimeKind: RUNTIME_KIND, pollIntervalMs: 100, timeoutMs: effectiveTimeoutMs },
-        );
-        runnerResult = await runner.run(wakeResult.taskId);
-      } else if (runnerKind === 'philosopher') {
-        const validator = new DefaultPhilosopherValidator();
-        const runner = new PhilosopherRunner(
-          { stateManager, runtimeAdapter, eventEmitter, validator, artifactStore },
-          { owner: OWNER, runtimeKind: RUNTIME_KIND, pollIntervalMs: 100, timeoutMs: effectiveTimeoutMs },
-        );
-        runnerResult = await runner.run(wakeResult.taskId);
-      } else if (runnerKind === 'scribe') {
-        // PRI-336: Read outputLanguage from workspace config
-        const outputLangResult = readOutputLanguageFromWorkspace(workspaceDir);
-        const outputLanguage: OutputLanguage | undefined = outputLangResult.outputLanguage;
-        const validator = new DefaultScribeValidator();
-        const runner = new ScribeRunner(
-          { stateManager, runtimeAdapter, eventEmitter, validator, artifactStore },
-          { owner: OWNER, runtimeKind: RUNTIME_KIND, pollIntervalMs: 100, timeoutMs: effectiveTimeoutMs, outputLanguage },
-        );
-        runnerResult = await runner.run(wakeResult.taskId);
-      } else if (runnerKind === 'artificer') {
-        const validator = new DefaultArtificerValidator();
-        const runner = new ArtificerRunner(
-          { stateManager, runtimeAdapter, eventEmitter, validator, artifactStore },
-          { owner: OWNER, runtimeKind: RUNTIME_KIND, pollIntervalMs: 100, timeoutMs: effectiveTimeoutMs },
-        );
-        runnerResult = await runner.run(wakeResult.taskId);
-      } else if (runnerKind === 'evaluator') {
-        const validator = new DefaultEvaluatorValidator();
-        const runner = new EvaluatorRunner(
-          { stateManager, runtimeAdapter, eventEmitter, validator, artifactStore },
-          { owner: OWNER, runtimeKind: RUNTIME_KIND, pollIntervalMs: 100, timeoutMs: effectiveTimeoutMs },
-        );
-        runnerResult = await runner.run(wakeResult.taskId);
-      } else if (runnerKind === 'rollout_reviewer') {
-        const validator = new DefaultRolloutReviewerValidator();
-        const runner = new RolloutReviewerRunner(
-          { stateManager, runtimeAdapter, eventEmitter, validator, artifactStore },
-          { owner: OWNER, runtimeKind: RUNTIME_KIND, pollIntervalMs: 100, timeoutMs: effectiveTimeoutMs },
-        );
-        runnerResult = await runner.run(wakeResult.taskId);
-      } else if (runnerKind === 'trainer') {
-        const validator = new DefaultTrainerValidator();
-        const runner = new TrainerRunner(
-          { stateManager, runtimeAdapter, eventEmitter, validator, artifactStore },
-          { owner: OWNER, runtimeKind: RUNTIME_KIND, pollIntervalMs: 100, timeoutMs: effectiveTimeoutMs },
-        );
-        runnerResult = await runner.run(wakeResult.taskId);
-      } else {
-        skipReason = 'no_runner_implemented';
+      try {
+        if (runnerKind === 'dreamer') {
+          const validator = new DefaultDreamerValidator();
+          const runner = new DreamerRunner(
+            { stateManager, runtimeAdapter, eventEmitter, validator, artifactStore },
+            { owner: OWNER, runtimeKind: runtimeAdapter.kind(), pollIntervalMs: 100, timeoutMs: effectiveTimeoutMs },
+          );
+          runnerResult = await runner.run(wakeResult.taskId);
+        } else if (runnerKind === 'philosopher') {
+          const validator = new DefaultPhilosopherValidator();
+          const runner = new PhilosopherRunner(
+            { stateManager, runtimeAdapter, eventEmitter, validator, artifactStore },
+            { owner: OWNER, runtimeKind: runtimeAdapter.kind(), pollIntervalMs: 100, timeoutMs: effectiveTimeoutMs },
+          );
+          runnerResult = await runner.run(wakeResult.taskId);
+        } else if (runnerKind === 'scribe') {
+          // PRI-336: Read outputLanguage from workspace config
+          const outputLangResult = readOutputLanguageFromWorkspace(workspaceDir);
+          const outputLanguage: OutputLanguage | undefined = outputLangResult.outputLanguage;
+          const validator = new DefaultScribeValidator();
+          const runner = new ScribeRunner(
+            { stateManager, runtimeAdapter, eventEmitter, validator, artifactStore },
+            { owner: OWNER, runtimeKind: runtimeAdapter.kind(), pollIntervalMs: 100, timeoutMs: effectiveTimeoutMs, outputLanguage },
+          );
+          runnerResult = await runner.run(wakeResult.taskId);
+        } else if (runnerKind === 'artificer') {
+          const validator = new DefaultArtificerValidator();
+          const runner = new ArtificerRunner(
+            { stateManager, runtimeAdapter, eventEmitter, validator, artifactStore },
+            { owner: OWNER, runtimeKind: runtimeAdapter.kind(), pollIntervalMs: 100, timeoutMs: effectiveTimeoutMs },
+          );
+          runnerResult = await runner.run(wakeResult.taskId);
+        } else if (runnerKind === 'evaluator') {
+          const validator = new DefaultEvaluatorValidator();
+          const runner = new EvaluatorRunner(
+            { stateManager, runtimeAdapter, eventEmitter, validator, artifactStore },
+            { owner: OWNER, runtimeKind: runtimeAdapter.kind(), pollIntervalMs: 100, timeoutMs: effectiveTimeoutMs },
+          );
+          runnerResult = await runner.run(wakeResult.taskId);
+        } else if (runnerKind === 'rollout_reviewer') {
+          const validator = new DefaultRolloutReviewerValidator();
+          const runner = new RolloutReviewerRunner(
+            { stateManager, runtimeAdapter, eventEmitter, validator, artifactStore },
+            { owner: OWNER, runtimeKind: runtimeAdapter.kind(), pollIntervalMs: 100, timeoutMs: effectiveTimeoutMs },
+          );
+          runnerResult = await runner.run(wakeResult.taskId);
+        } else if (runnerKind === 'trainer') {
+          const validator = new DefaultTrainerValidator();
+          const runner = new TrainerRunner(
+            { stateManager, runtimeAdapter, eventEmitter, validator, artifactStore },
+            { owner: OWNER, runtimeKind: runtimeAdapter.kind(), pollIntervalMs: 100, timeoutMs: effectiveTimeoutMs },
+          );
+          runnerResult = await runner.run(wakeResult.taskId);
+        } else {
+          skipReason = 'no_runner_implemented';
+        }
+      } catch (runErr) {
+        console.error(`Error: runner crashed: ${runErr instanceof Error ? runErr.message : String(runErr)}`);
+        try {
+          const task = await stateManager.getTask(wakeResult.taskId);
+          const failureReason = `Unhandled runner crash: ${runErr instanceof Error ? runErr.message : String(runErr)}`;
+          if (task && stateManager.getRetryPolicy().shouldRetry(task)) {
+            await stateManager.markTaskRetryWait(wakeResult.taskId, 'execution_failed', failureReason);
+          } else {
+            await stateManager.markTaskFailed(wakeResult.taskId, 'execution_failed', failureReason);
+          }
+        } catch (dbErr) {
+          console.error(`Error: failed to update task state in DB: ${String(dbErr)}`);
+        }
+        throw runErr;
       }
     }
 

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

@@ -0,0 +1,181 @@
+import * as path from 'path';
+import { createRecoverySweepService, type RecoverySweepServiceHandle } from '@principles/core/runtime-v2';
+import { resolveWorkspaceDir } from '../resolve-workspace.js';
+
+interface RecoveryFailedTasksOptions {
+  workspace?: string;
+  dryRun?: boolean;
+  confirm?: boolean;
+  force?: boolean;
+  json?: boolean;
+}
+
+interface TaskDetail {
+  taskId: string;
+  taskKind: string;
+  status: string;
+  attemptCount: number;
+  maxAttempts: number;
+  action: string;
+  reason: string;
+  nextAction: string;
+}
+
+export async function handleRuntimeRecoveryFailedTasks(opts: RecoveryFailedTasksOptions): Promise<void> {
+  if (opts.dryRun && opts.confirm) {
+    if (opts.json) {
+      console.log(JSON.stringify({
+        ok: false,
+        reason: 'Error: --dry-run and --confirm are mutually exclusive',
+        nextAction: 'Specify only one of --dry-run or --confirm',
+      }, null, 2));
+    } else {
+      console.error('Error: --dry-run and --confirm are mutually exclusive');
+    }
+    process.exitCode = 1;
+    return;
+  }
+  const isConfirm = opts.confirm ?? false;
+  const isDryRun = !isConfirm;
+
+  let serviceHandle: RecoverySweepServiceHandle | null = null;
+
+  try {
+    const workspaceDir = opts.workspace ? path.resolve(opts.workspace) : resolveWorkspaceDir();
+    const handle = await createRecoverySweepService({ workspaceDir });
+    serviceHandle = handle;
+
+    const failedTasks = await handle.service.detectFailedTasks();
+    const taskDetails: TaskDetail[] = [];
+    let recoveredCount = 0;
+    let skippedCount = 0;
+
+    for (const t of failedTasks) {
+      if (t.isExhausted && !opts.force) {
+        taskDetails.push({
+          taskId: t.taskId,
+          taskKind: t.taskKind,
+          status: t.status,
+          attemptCount: t.attemptCount,
+          maxAttempts: t.maxAttempts,
+          action: 'skipped',
+          reason: `Task has exhausted max attempts (${t.attemptCount}/${t.maxAttempts})`,
+          nextAction: 'Run with --force to recover this task',
+        });
+        skippedCount++;
+      } else {
+        if (isConfirm) {
+          const result = await handle.service.recoverFailedTask(t.taskId, opts.force);
+          if (result) {
+            recoveredCount++;
+            taskDetails.push({
+              taskId: t.taskId,
+              taskKind: t.taskKind,
+              status: t.status,
+              attemptCount: t.attemptCount,
+              maxAttempts: t.maxAttempts,
+              action: 'recovered',
+              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.',
+            });
+          } else {
+            skippedCount++;
+            taskDetails.push({
+              taskId: t.taskId,
+              taskKind: t.taskKind,
+              status: t.status,
+              attemptCount: t.attemptCount,
+              maxAttempts: t.maxAttempts,
+              action: 'skipped',
+              reason: 'Task recovery skipped (task no longer failed or concurrently modified)',
+              nextAction: 'Verify task status using task list',
+            });
+          }
+        } else {
+          recoveredCount++;
+          taskDetails.push({
+            taskId: t.taskId,
+            taskKind: t.taskKind,
+            status: t.status,
+            attemptCount: t.attemptCount,
+            maxAttempts: t.maxAttempts,
+            action: 'would_recover',
+            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: 'Run with --confirm to recover this task',
+          });
+        }
+      }
+    }
+
+    const mode = isDryRun ? 'dry_run' : 'confirm';
+    let summaryReason = '';
+    let summaryNextAction = '';
+
+    if (isDryRun) {
+      if (taskDetails.length === 0) {
+        summaryReason = 'No failed internalization tasks found';
+        summaryNextAction = 'Nothing to recover';
+      } else {
+        summaryReason = `Found ${recoveredCount} recoverable and ${skippedCount} exhausted failed tasks`;
+        summaryNextAction = `Run with --confirm to recover tasks, and use --force to recover exhausted tasks`;
+      }
+    } 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';
+    }
+
+    if (opts.json) {
+      console.log(JSON.stringify({
+        ok: true,
+        mode,
+        recoveredCount,
+        skippedCount,
+        tasks: taskDetails,
+        reason: summaryReason,
+        nextAction: summaryNextAction,
+      }, null, 2));
+    } else {
+      console.log(`Failed Tasks Recovery (${mode.toUpperCase()})`);
+      console.log(`  reason:      ${summaryReason}`);
+      console.log(`  nextAction:  ${summaryNextAction}`);
+      console.log(`  recovered:   ${recoveredCount}`);
+      console.log(`  skipped:     ${skippedCount}`);
+      console.log('');
+      if (taskDetails.length > 0) {
+        console.log('Tasks:');
+        for (const t of taskDetails) {
+          console.log(`  - ${t.taskId} (${t.taskKind})`);
+          console.log(`    action:     ${t.action}`);
+          console.log(`    reason:     ${t.reason}`);
+          console.log(`    nextAction: ${t.nextAction}`);
+        }
+        console.log('');
+      }
+    }
+
+    if (recoveredCount > 0 && isDryRun) {
+      process.exitCode = 1;
+    }
+  } catch (err: unknown) {
+    if (opts.json) {
+      console.log(JSON.stringify({
+        ok: false,
+        reason: err instanceof Error ? err.message : String(err),
+        nextAction: 'Check workspace path and DB connectivity',
+      }, null, 2));
+    } else {
+      console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    process.exitCode = 1;
+  } finally {
+    if (serviceHandle) {
+      await serviceHandle.close();
+    }
+  }
+}

package/src/commands/task.ts

@@ -6,7 +6,7 @@
  *   pd task show <taskId>
  */
 import * as path from 'path';
-import { RuntimeStateManager } from '@principles/core';
+import { RuntimeStateManager, MalformedRunError, type RunRecord } from '@principles/core';
 import { resolveWorkspaceDir } from '../resolve-workspace.js';
 
 interface TaskListOptions {
@@ -77,14 +77,66 @@ export async function handleTaskShow(opts: TaskShowOptions): Promise<void> {
     const task = await stateManager.getTask(opts.id);
 
     if (!task) {
-      console.error(`Task not found: ${opts.id}`);
+      if (opts.json) {
+        console.log(JSON.stringify({
+          ok: false,
+          reason: `Task not found: ${opts.id}`,
+          nextAction: 'Specify a valid taskId',
+        }, null, 2));
+      } else {
+        console.error(`Task not found: ${opts.id}`);
+      }
       process.exit(1);
+      return;
     }
 
-    const runs = await stateManager.getRunsByTask(opts.id);
+    let runs: RunRecord[] = [];
+    let degradedRuns: { runId: string; error: string; rawRow: Record<string, unknown> }[] = [];
+    let isDegraded = false;
+    let malformedError: MalformedRunError | null = null;
+
+    try {
+      runs = await stateManager.getRunsByTask(opts.id);
+    } catch (err: unknown) {
+      if (err instanceof MalformedRunError) {
+        const { validRuns, degradedRuns: malformedRuns } = err;
+        runs = validRuns;
+        degradedRuns = malformedRuns;
+        isDegraded = true;
+        malformedError = err;
+      } else {
+        const errorMsg = err instanceof Error ? err.message : String(err);
+        if (opts.json) {
+          console.log(JSON.stringify({
+            ok: false,
+            reason: errorMsg,
+            nextAction: 'Check state.db connection and schema integrity',
+          }, null, 2));
+        } else {
+          console.error(`Error: ${errorMsg}`);
+        }
+        process.exit(1);
+        return;
+      }
+    }
 
     if (opts.json) {
-      console.log(JSON.stringify({ task, runs }, null, 2));
+      if (isDegraded) {
+        console.log(JSON.stringify({
+          ok: false,
+          task,
+          runs,
+          degradedRuns: degradedRuns.map(dr => ({
+            runId: dr.runId,
+            error: dr.error,
+          })),
+          reason: malformedError?.message ?? 'Unknown malformed run schema',
+          nextAction: 'Use integrity-repair to clean up or recover malformed runs, or fix runs in DB',
+        }, null, 2));
+        process.exitCode = 1;
+      } else {
+        console.log(JSON.stringify({ task, runs }, null, 2));
+      }
       return;
     }
 
@@ -124,6 +176,30 @@ export async function handleTaskShow(opts: TaskShowOptions): Promise<void> {
       }
       console.log('');
     }
+
+    if (isDegraded && degradedRuns.length > 0) {
+      console.warn(`WARNING: Task has ${degradedRuns.length} malformed run(s) in database!`);
+      console.warn(`Reason: ${malformedError?.message ?? 'Unknown malformed run schema'}`);
+      console.warn(`nextAction: Use integrity-repair to clean up or recover malformed runs, or fix runs in DB\n`);
+      console.log('Degraded Runs:');
+      for (const dr of degradedRuns) {
+        console.log(`  - Run: ${dr.runId}`);
+        console.log(`    Error: ${dr.error}`);
+      }
+      console.log('');
+      process.exitCode = 1;
+    }
+  } catch (err: unknown) {
+    if (opts.json) {
+      console.log(JSON.stringify({
+        ok: false,
+        reason: err instanceof Error ? err.message : String(err),
+        nextAction: 'Check workspace path and task ID',
+      }, null, 2));
+    } else {
+      console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    process.exitCode = 1;
   } finally {
     await stateManager.close();
   }

package/src/index.ts

@@ -44,6 +44,7 @@ import { handleRuntimeInternalizationIntegrityRepair } from './commands/runtime-
 import { handleRuntimeInternalizationEnqueueSuccessors } from './commands/runtime-internalization-enqueue-successors.js';
 import { handleRuntimeDiagnosticsExport } from './commands/runtime-diagnostics-export.js';
 import { handleRuntimeRecoverySweep } from './commands/runtime-recovery.js';
+import { handleRuntimeRecoveryFailedTasks } from './commands/runtime-recovery-failed-tasks.js';
 import { handleRuntimeActivationDispatch } from './commands/runtime-activation.js';
 import { handleProvenChannelBaseline } from './commands/proven-channel-baseline.js';
 import { handleDemoStoryA } from './commands/demo-story-a.js';
@@ -645,6 +646,24 @@ recoveryCmd
     await handleRuntimeRecoverySweep({ workspace: opts.workspace, dryRun: opts.dryRun, confirm: opts.confirm, json: opts.json });
   });
 
+recoveryCmd
+  .command('failed-tasks')
+  .description('Recover failed internalization tasks')
+  .option('-w, --workspace <path>', 'Workspace directory')
+  .option('--dry-run', 'Report only, no modifications (default)')
+  .option('--confirm', 'Actually recover failed tasks')
+  .option('--force', 'Force recovery of tasks that exhausted max attempts')
+  .option('--json', 'Output raw JSON')
+  .action(async (opts) => {
+    await handleRuntimeRecoveryFailedTasks({
+      workspace: opts.workspace,
+      dryRun: opts.dryRun,
+      confirm: opts.confirm,
+      force: opts.force,
+      json: opts.json,
+    });
+  });
+
 diagnosticsCmd
   .command('export')
   .description('Export diagnostic bundle for AI assistant analysis')

package/tests/commands/runtime-recovery-failed-tasks.test.ts

@@ -0,0 +1,201 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const mockDetectFailedTasks = vi.hoisted(() => vi.fn());
+const mockRecoverFailedTask = vi.hoisted(() => vi.fn());
+const mockServiceClose = vi.hoisted(() => vi.fn());
+
+vi.mock('../../src/resolve-workspace.js', () => ({
+  resolveWorkspaceDir: vi.fn().mockReturnValue('/fake/workspace'),
+}));
+
+vi.mock('@principles/core/runtime-v2', () => ({
+  createRecoverySweepService: vi.fn().mockResolvedValue({
+    service: {
+      detectFailedTasks: mockDetectFailedTasks,
+      recoverFailedTask: mockRecoverFailedTask,
+    },
+    close: mockServiceClose,
+  }),
+}));
+
+import { handleRuntimeRecoveryFailedTasks } from '../../src/commands/runtime-recovery-failed-tasks.js';
+
+describe('pd runtime recovery failed-tasks command contract', () => {
+  let consoleLogSpy: ReturnType<typeof vi.spyOn>;
+  let consoleErrorSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockDetectFailedTasks.mockResolvedValue([]);
+    mockRecoverFailedTask.mockResolvedValue({
+      taskId: 'task-1',
+      previousStatus: 'failed',
+      newStatus: 'pending',
+      attemptCount: 0,
+      maxAttempts: 3,
+      forceApplied: false,
+    });
+    mockServiceClose.mockResolvedValue(undefined);
+    process.exitCode = 0;
+    consoleLogSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+  });
+
+  it('dry-run JSON does not recover tasks and lists them as would_recover', async () => {
+    mockDetectFailedTasks.mockResolvedValue([
+      {
+        taskId: 'task-1',
+        taskKind: 'dreamer',
+        attemptCount: 1,
+        maxAttempts: 3,
+        isExhausted: false,
+        status: 'failed',
+      },
+    ]);
+
+    await handleRuntimeRecoveryFailedTasks({ workspace: '/fake/workspace', dryRun: true, json: true });
+
+    const output = JSON.parse(consoleLogSpy.mock.calls[0][0] as string);
+    expect(output).toMatchObject({
+      ok: true,
+      mode: 'dry_run',
+      recoveredCount: 1,
+      skippedCount: 0,
+    });
+    expect(output.tasks[0]).toMatchObject({
+      taskId: 'task-1',
+      action: 'would_recover',
+      reason: expect.stringContaining('attempts remain'),
+    });
+    expect(mockRecoverFailedTask).not.toHaveBeenCalled();
+    expect(mockServiceClose).toHaveBeenCalledTimes(1);
+    expect(process.exitCode).toBe(1); // exitCode 1 on dry-run when tasks are found
+  });
+
+  it('confirm JSON reports recovered tasks and mutates state', async () => {
+    mockDetectFailedTasks.mockResolvedValue([
+      {
+        taskId: 'task-1',
+        taskKind: 'dreamer',
+        attemptCount: 1,
+        maxAttempts: 3,
+        isExhausted: false,
+        status: 'failed',
+      },
+    ]);
+
+    await handleRuntimeRecoveryFailedTasks({ workspace: '/fake/workspace', confirm: true, json: true });
+
+    const output = JSON.parse(consoleLogSpy.mock.calls[0][0] as string);
+    expect(output).toMatchObject({
+      ok: true,
+      mode: 'confirm',
+      recoveredCount: 1,
+      skippedCount: 0,
+    });
+    expect(output.tasks[0]).toMatchObject({
+      taskId: 'task-1',
+      action: 'recovered',
+    });
+    expect(mockRecoverFailedTask).toHaveBeenCalledWith('task-1', undefined);
+    expect(mockServiceClose).toHaveBeenCalledTimes(1);
+    expect(process.exitCode).toBe(0);
+  });
+
+  it('dry-run JSON skips exhausted tasks without force', async () => {
+    mockDetectFailedTasks.mockResolvedValue([
+      {
+        taskId: 'task-exhausted',
+        taskKind: 'dreamer',
+        attemptCount: 3,
+        maxAttempts: 3,
+        isExhausted: true,
+        status: 'failed',
+      },
+    ]);
+
+    await handleRuntimeRecoveryFailedTasks({ workspace: '/fake/workspace', dryRun: true, json: true });
+
+    const output = JSON.parse(consoleLogSpy.mock.calls[0][0] as string);
+    expect(output).toMatchObject({
+      ok: true,
+      mode: 'dry_run',
+      recoveredCount: 0,
+      skippedCount: 1,
+    });
+    expect(output.tasks[0]).toMatchObject({
+      taskId: 'task-exhausted',
+      action: 'skipped',
+      reason: expect.stringContaining('exhausted max attempts'),
+    });
+    expect(mockRecoverFailedTask).not.toHaveBeenCalled();
+    expect(process.exitCode).toBe(0); // exitCode 0 since recoveredCount is 0
+  });
+
+  it('confirm with force recovers exhausted tasks', async () => {
+    mockDetectFailedTasks.mockResolvedValue([
+      {
+        taskId: 'task-exhausted',
+        taskKind: 'dreamer',
+        attemptCount: 3,
+        maxAttempts: 3,
+        isExhausted: true,
+        status: 'failed',
+      },
+    ]);
+
+    await handleRuntimeRecoveryFailedTasks({ workspace: '/fake/workspace', confirm: true, force: true, json: true });
+
+    const output = JSON.parse(consoleLogSpy.mock.calls[0][0] as string);
+    expect(output).toMatchObject({
+      ok: true,
+      mode: 'confirm',
+      recoveredCount: 1,
+      skippedCount: 0,
+    });
+    expect(mockRecoverFailedTask).toHaveBeenCalledWith('task-exhausted', true);
+  });
+
+  it('rejects mutual exclusion of dry-run and confirm in JSON mode', async () => {
+    await handleRuntimeRecoveryFailedTasks({ workspace: '/fake/workspace', dryRun: true, confirm: true, json: true });
+
+    expect(mockRecoverFailedTask).not.toHaveBeenCalled();
+    expect(mockServiceClose).not.toHaveBeenCalled();
+    expect(process.exitCode).toBe(1);
+
+    const output = JSON.parse(consoleLogSpy.mock.calls[0][0] as string);
+    expect(output).toMatchObject({
+      ok: false,
+      reason: expect.stringContaining('mutually exclusive'),
+    });
+  });
+
+  it('confirm JSON handles concurrent task modification gracefully (null result)', async () => {
+    mockDetectFailedTasks.mockResolvedValue([
+      {
+        taskId: 'task-concurrent',
+        taskKind: 'dreamer',
+        attemptCount: 1,
+        maxAttempts: 3,
+        isExhausted: false,
+        status: 'failed',
+      },
+    ]);
+    mockRecoverFailedTask.mockResolvedValue(null);
+
+    await handleRuntimeRecoveryFailedTasks({ workspace: '/fake/workspace', confirm: true, json: true });
+
+    const output = JSON.parse(consoleLogSpy.mock.calls[0][0] as string);
+    expect(output).toMatchObject({
+      ok: true,
+      mode: 'confirm',
+      recoveredCount: 0,
+      skippedCount: 1,
+    });
+    expect(output.tasks[0]).toMatchObject({
+      taskId: 'task-concurrent',
+      action: 'skipped',
+      reason: expect.stringContaining('no longer failed or concurrently modified'),
+    });
+  });
+});