@principles/pd-cli 1.99.0 → 1.101.0

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: 'Malformed run rows are visible here but not auto-repaired. Runner execution tolerates them (uses the latest valid run). To quarantine malformed rows: pd runtime internalization integrity-repair --confirm --json',
+        }, 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: Malformed run rows are visible here but not auto-repaired. Runner execution tolerates them (uses the latest valid run). To quarantine malformed rows: pd runtime internalization integrity-repair --confirm --json\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-internalization-integrity-repair.test.ts

@@ -82,6 +82,44 @@ describe('handleRuntimeInternalizationIntegrityRepair', () => {
     expect(jsonOutput.repairedCount).toBe(1);
   });
 
+  it('emits malformed_run_row quarantine actions as a single JSON object', async () => {
+    // Verifies the new malformed-run repair pass flows through the CLI contract
+    // unchanged: exactly one JSON object on stdout, with the quarantine action present.
+    mockRepair.mockReturnValue(makeResult({
+      dryRun: false,
+      repairedCount: 1,
+      actions: [
+        {
+          action: 'quarantine_malformed_run',
+          targetId: 'run-malf-1',
+          taskId: 'task-1',
+          type: 'malformed_run_row',
+          severity: 'warning',
+          previousState: 'queued',
+          nextState: 'failed',
+          previousStatus: 'queued',
+          newStatus: 'failed',
+          recommendedAction: 'quarantine_malformed_run',
+          reason: 'Run run-malf-1 (task task-1) failed schema validation — quarantined',
+        },
+      ],
+    }));
+
+    await handleRuntimeInternalizationIntegrityRepair({ workspace: WS, confirm: true, json: true });
+
+    // Exactly one console.log call (single JSON object, no banners/extra stdout).
+    expect(consoleLogSpy).toHaveBeenCalledTimes(1);
+    const jsonOutput = JSON.parse(consoleLogSpy.mock.calls[0][0]);
+    expect(jsonOutput.repairedCount).toBe(1);
+    expect(jsonOutput.actions).toHaveLength(1);
+    expect(jsonOutput.actions[0]).toMatchObject({
+      type: 'malformed_run_row',
+      recommendedAction: 'quarantine_malformed_run',
+      newStatus: 'failed',
+      targetId: 'run-malf-1',
+    });
+  });
+
   it('outputs text format when --json not specified', async () => {
     mockRepair.mockReturnValue(makeResult({ dryRun: true }));
 

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'),
+    });
+  });
+});

package/tests/commands/task.test.ts

@@ -0,0 +1,153 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const mockGetTask = vi.hoisted(() => vi.fn());
+const mockGetRunsByTask = vi.hoisted(() => vi.fn());
+const mockInitialize = vi.hoisted(() => vi.fn());
+const mockClose = vi.hoisted(() => vi.fn());
+
+vi.mock('../../src/resolve-workspace.js', () => ({
+  resolveWorkspaceDir: vi.fn().mockReturnValue('/fake/workspace'),
+}));
+
+vi.mock('@principles/core', async (importOriginal) => {
+  const original = await importOriginal<typeof import('@principles/core')>();
+  return {
+    ...original,
+    RuntimeStateManager: vi.fn().mockImplementation(function() {
+      return {
+        initialize: mockInitialize,
+        getTask: mockGetTask,
+        getRunsByTask: mockGetRunsByTask,
+        close: mockClose,
+      };
+    }),
+  };
+});
+
+import { handleTaskShow } from '../../src/commands/task.js';
+import { MalformedRunError } from '@principles/core';
+
+describe('pd task show command handler', () => {
+  let consoleLogSpy: ReturnType<typeof vi.spyOn>;
+  let consoleErrorSpy: ReturnType<typeof vi.spyOn>;
+  let consoleWarnSpy: ReturnType<typeof vi.spyOn>;
+  let processExitSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockInitialize.mockResolvedValue(undefined);
+    mockGetTask.mockResolvedValue({
+      taskId: 'task-123',
+      taskKind: 'dreamer',
+      status: 'failed',
+      attemptCount: 1,
+      maxAttempts: 3,
+      createdAt: Date.now(),
+      updatedAt: Date.now(),
+    });
+    mockGetRunsByTask.mockResolvedValue([
+      {
+        runId: 'run-1',
+        executionStatus: 'failed',
+        attemptNumber: 1,
+        startedAt: Date.now(),
+      },
+    ]);
+    process.exitCode = 0;
+    consoleLogSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    consoleWarnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    processExitSpy = vi.spyOn(process, 'exit').mockImplementation(() => undefined as never);
+  });
+
+  it('happy path JSON mode prints task and runs, exit code 0', async () => {
+    await handleTaskShow({ id: 'task-123', json: true });
+
+    const output = JSON.parse(consoleLogSpy.mock.calls[0][0] as string);
+    expect(output).toMatchObject({
+      task: { taskId: 'task-123' },
+      runs: [{ runId: 'run-1' }],
+    });
+    expect(process.exitCode).toBe(0);
+    expect(processExitSpy).not.toHaveBeenCalled();
+  });
+
+  it('task not found JSON mode prints ok: false and exits with non-zero code', async () => {
+    mockGetTask.mockResolvedValue(null);
+
+    await handleTaskShow({ id: 'nonexistent-task', json: true });
+
+    const output = JSON.parse(consoleLogSpy.mock.calls[0][0] as string);
+    expect(output).toMatchObject({
+      ok: false,
+      reason: expect.stringContaining('Task not found'),
+      nextAction: expect.any(String),
+    });
+    expect(processExitSpy).toHaveBeenCalledWith(1);
+  });
+
+  it('degraded JSON mode prints ok: false, lists degraded runs, and sets exitCode to 1', async () => {
+    const malformedError = new MalformedRunError('Malformed schema', [
+      {
+        runId: 'run-valid',
+        executionStatus: 'succeeded',
+        attemptNumber: 1,
+        startedAt: Date.now(),
+      } as any,
+    ], [
+      {
+        runId: 'run-bad',
+        error: 'runtimeKind missing',
+        rawRow: {},
+      },
+    ]);
+
+    mockGetRunsByTask.mockRejectedValue(malformedError);
+
+    await handleTaskShow({ id: 'task-123', json: true });
+
+    const output = JSON.parse(consoleLogSpy.mock.calls[0][0] as string);
+    expect(output).toMatchObject({
+      ok: false,
+      task: { taskId: 'task-123' },
+      runs: [{ runId: 'run-valid' }],
+      degradedRuns: [{ runId: 'run-bad', error: 'runtimeKind missing' }],
+      reason: expect.stringContaining('Malformed schema'),
+      // Honest nextAction: must NOT promise an auto-repair that doesn't exist,
+      // and must point at the real quarantine command (integrity-repair --confirm).
+      nextAction: expect.stringContaining('not auto-repaired'),
+    });
+    expect(output.nextAction).toContain('integrity-repair --confirm');
+    expect(process.exitCode).toBe(1);
+    expect(processExitSpy).not.toHaveBeenCalled();
+  });
+
+  it('degraded text mode prints warning and sets exitCode to 1', async () => {
+    const malformedError = new MalformedRunError('Malformed schema', [
+      {
+        runId: 'run-valid',
+        executionStatus: 'succeeded',
+        attemptNumber: 1,
+        startedAt: Date.now(),
+      } as any,
+    ], [
+      {
+        runId: 'run-bad',
+        error: 'runtimeKind missing',
+        rawRow: {},
+      },
+    ]);
+
+    mockGetRunsByTask.mockRejectedValue(malformedError);
+
+    await handleTaskShow({ id: 'task-123', json: false });
+
+    expect(consoleErrorSpy).not.toHaveBeenCalled();
+    expect(consoleLogSpy).toHaveBeenCalledWith(expect.stringContaining('Task: task-123'));
+    // The text-mode warning must also carry the honest nextAction.
+    expect(consoleWarnSpy).toHaveBeenCalledWith(expect.stringContaining('not auto-repaired'));
+    expect(consoleWarnSpy).toHaveBeenCalledWith(expect.stringContaining('integrity-repair --confirm'));
+    expect(process.exitCode).toBe(1);
+    expect(processExitSpy).not.toHaveBeenCalled();
+  });
+});