agentic-orchestrator 0.1.26 → 0.1.28

package/apps/control-plane/test/checkpoint-service.spec.ts

@@ -0,0 +1,537 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { describe, expect, it, vi } from 'vitest';
+import { runGit } from '../src/core/git.js';
+import {
+  CheckpointService,
+  type CheckpointProviderPort,
+  type CheckpointRecord,
+  type InteractiveExecutionConfig,
+} from '../src/application/services/checkpoint-service.js';
+import type { WorktreeWatchdogService } from '../src/application/services/worktree-watchdog-service.js';
+
+interface MutableState {
+  frontMatter: Record<string, unknown>;
+  body: string;
+}
+
+async function initGitRepo(prefix: string): Promise<string> {
+  const repoRoot = await fs.mkdtemp(path.join(os.tmpdir(), prefix));
+  await runGit(repoRoot, ['init']);
+  await runGit(repoRoot, ['config', 'user.email', 'test@example.com']);
+  await runGit(repoRoot, ['config', 'user.name', 'AOP Test']);
+  await fs.writeFile(path.join(repoRoot, 'tracked.txt'), 'initial\n', 'utf8');
+  await runGit(repoRoot, ['add', '.']);
+  await runGit(repoRoot, ['commit', '-m', 'init']);
+  return repoRoot;
+}
+
+function makeUpdateState(state: MutableState) {
+  return async (
+    _featureId: string,
+    _expectedVersion: number | null,
+    updater: (
+      frontMatter: Record<string, unknown>,
+      body: string,
+    ) => Promise<{ frontMatter?: Record<string, unknown>; body?: string }>,
+  ): Promise<Record<string, unknown>> => {
+    const next = await updater(structuredClone(state.frontMatter), state.body);
+    state.frontMatter = {
+      ...state.frontMatter,
+      ...(next.frontMatter ?? {}),
+      version:
+        typeof state.frontMatter['version'] === 'number' ? state.frontMatter['version'] + 1 : 1,
+    };
+    state.body = next.body ?? state.body;
+    return state.frontMatter;
+  };
+}
+
+function defaultConfig(
+  overrides: Partial<InteractiveExecutionConfig> = {},
+): InteractiveExecutionConfig {
+  return {
+    checkpointIntervalMs: 30_000,
+    watchdogPollIntervalMs: 2_000,
+    maxUncommittedChanges: 50,
+    validationOnCheckpoint: true,
+    revertOnViolation: false,
+    violationSeverity: 'warning',
+    ...overrides,
+  };
+}
+
+describe('CheckpointService', () => {
+  it('creates a valid checkpoint and persists diff snapshot metadata', async () => {
+    const repoRoot = await initGitRepo('aop-checkpoint-valid-');
+    const state: MutableState = {
+      frontMatter: { version: 1, status: 'building' },
+      body: 'state body',
+    };
+
+    const watchdog = {
+      getChangedFiles: vi.fn(async () => ['tracked.txt']),
+      resetChangeCount: vi.fn(),
+    } as unknown as WorktreeWatchdogService;
+
+    const provider = {
+      selection: {
+        provider: 'custom',
+        model: 'local-default',
+        provider_config_env: null,
+        provider_config_ref: null,
+      },
+      runWorker: vi.fn(),
+      sendMessage: vi.fn(async () => undefined),
+    } as unknown as CheckpointProviderPort;
+
+    const service = new CheckpointService({
+      repoRoot,
+      featurePathResolver: (featureId: string) =>
+        path.join(repoRoot, '.aop', 'features', featureId),
+      worktreePathResolver: () => repoRoot,
+      validateDiff: vi.fn(async () => ({
+        valid: true,
+        violations: [],
+        changed_files: ['tracked.txt'],
+      })),
+      watchdog,
+      provider,
+      readState: async () => ({ frontMatter: state.frontMatter }),
+      updateState: makeUpdateState(state),
+      config: defaultConfig(),
+    });
+
+    try {
+      await fs.writeFile(path.join(repoRoot, 'tracked.txt'), 'updated\n', 'utf8');
+
+      const result = await service.createCheckpoint({
+        featureId: 'feature_valid',
+        trigger: 'final',
+      });
+
+      expect(result.valid).toBe(true);
+      expect(result.blockMerge).toBe(false);
+      expect(result.checkpoint.validation_status).toBe('valid');
+      expect(result.checkpoint.files_changed).toEqual(['tracked.txt']);
+      expect(provider.sendMessage as unknown as ReturnType<typeof vi.fn>).not.toHaveBeenCalled();
+      expect(watchdog.resetChangeCount as unknown as ReturnType<typeof vi.fn>).toHaveBeenCalledWith(
+        'feature_valid',
+      );
+
+      const snapshotPath = path.join(repoRoot, result.checkpoint.diff_snapshot);
+      await expect(fs.stat(snapshotPath)).resolves.toBeTruthy();
+
+      const checkpoints = (state.frontMatter['checkpoints'] as CheckpointRecord[]) ?? [];
+      expect(checkpoints).toHaveLength(1);
+      expect(checkpoints[0].checkpoint_id).toBe(result.checkpoint.checkpoint_id);
+      expect(state.frontMatter['execution_mode']).toBe('interactive');
+
+      const metricsPath = path.join(repoRoot, '.aop', 'analytics', 'interactive-mode.json');
+      const metricsRaw = await fs.readFile(metricsPath, 'utf8');
+      const metrics = JSON.parse(metricsRaw) as {
+        totals: {
+          checkpoint_count: number;
+          valid_count: number;
+          invalid_count: number;
+        };
+        latest: {
+          feature_id: string;
+          checkpoint_id: string;
+        };
+      };
+      expect(metrics.totals.checkpoint_count).toBe(1);
+      expect(metrics.totals.valid_count).toBe(1);
+      expect(metrics.totals.invalid_count).toBe(0);
+      expect(metrics.latest.feature_id).toBe('feature_valid');
+      expect(metrics.latest.checkpoint_id).toBe(result.checkpoint.checkpoint_id);
+    } finally {
+      await fs.rm(repoRoot, { recursive: true, force: true });
+    }
+  });
+
+  it('marks invalid checkpoints, notifies agent, and reverts files when configured', async () => {
+    const repoRoot = await initGitRepo('aop-checkpoint-invalid-');
+    const state: MutableState = {
+      frontMatter: { version: 1, status: 'building' },
+      body: 'state body',
+    };
+
+    const watchdog = {
+      getChangedFiles: vi.fn(async () => ['tracked.txt']),
+      resetChangeCount: vi.fn(),
+    } as unknown as WorktreeWatchdogService;
+
+    const provider = {
+      selection: {
+        provider: 'custom',
+        model: 'local-default',
+        provider_config_env: null,
+        provider_config_ref: null,
+      },
+      runWorker: vi.fn(),
+      sendMessage: vi.fn(async () => undefined),
+    } as unknown as CheckpointProviderPort;
+
+    const service = new CheckpointService({
+      repoRoot,
+      featurePathResolver: (featureId: string) =>
+        path.join(repoRoot, '.aop', 'features', featureId),
+      worktreePathResolver: () => repoRoot,
+      validateDiff: vi.fn(async () => {
+        throw {
+          normalizedResponse: {
+            error: {
+              details: {
+                violations: [{ path: 'tracked.txt', reason: 'outside_allowed_areas' }],
+              },
+            },
+          },
+        };
+      }),
+      watchdog,
+      provider,
+      readState: async () => ({ frontMatter: state.frontMatter }),
+      updateState: makeUpdateState(state),
+      config: defaultConfig({ revertOnViolation: true, violationSeverity: 'error' }),
+    });
+
+    try {
+      await fs.writeFile(path.join(repoRoot, 'tracked.txt'), 'violating change\n', 'utf8');
+
+      const result = await service.createCheckpoint({
+        featureId: 'feature_invalid',
+        sessionId: 'builder-session-1',
+        trigger: 'final',
+      });
+
+      expect(result.valid).toBe(false);
+      expect(result.blockMerge).toBe(true);
+      expect(result.checkpoint.validation_status).toBe('invalid');
+      expect(result.checkpoint.violations).toContain('tracked.txt: outside_allowed_areas');
+      expect(result.checkpoint.severity).toBe('error');
+      expect(provider.sendMessage as unknown as ReturnType<typeof vi.fn>).toHaveBeenCalledTimes(1);
+
+      const fileContent = await fs.readFile(path.join(repoRoot, 'tracked.txt'), 'utf8');
+      expect(fileContent).toBe('initial\n');
+    } finally {
+      await fs.rm(repoRoot, { recursive: true, force: true });
+    }
+  });
+
+  it('returns filtered checkpoints from state frontmatter', async () => {
+    const repoRoot = await initGitRepo('aop-checkpoint-read-');
+    const state: MutableState = {
+      frontMatter: {
+        version: 3,
+        checkpoints: [
+          {
+            checkpoint_id: 'checkpoint-valid',
+            timestamp: new Date().toISOString(),
+            files_changed: ['tracked.txt'],
+            validation_status: 'valid',
+            violations: [],
+            severity: 'warning',
+            diff_snapshot: '.aop/features/feature_read/checkpoints/checkpoint-valid.diff',
+          },
+          { checkpoint_id: 'checkpoint-invalid-shape' },
+          'not-an-object',
+        ],
+      },
+      body: 'state body',
+    };
+
+    const service = new CheckpointService({
+      repoRoot,
+      featurePathResolver: (featureId: string) =>
+        path.join(repoRoot, '.aop', 'features', featureId),
+      worktreePathResolver: () => repoRoot,
+      validateDiff: vi.fn(async () => ({ valid: true, violations: [], changed_files: [] })),
+      watchdog: {
+        getChangedFiles: vi.fn(async () => []),
+        resetChangeCount: vi.fn(),
+      } as unknown as WorktreeWatchdogService,
+      provider: {
+        selection: {
+          provider: 'custom',
+          model: 'local-default',
+          provider_config_env: null,
+          provider_config_ref: null,
+        },
+        runWorker: vi.fn(),
+      } as unknown as CheckpointProviderPort,
+      readState: async () => ({ frontMatter: state.frontMatter }),
+      updateState: makeUpdateState(state),
+      config: defaultConfig(),
+    });
+
+    try {
+      const checkpoints = await service.getCheckpoints('feature_read');
+      expect(checkpoints).toHaveLength(1);
+      expect(checkpoints[0]).toMatchObject({
+        checkpoint_id: 'checkpoint-valid',
+        validation_status: 'valid',
+      });
+    } finally {
+      await fs.rm(repoRoot, { recursive: true, force: true });
+    }
+  });
+
+  it('supports skipped checkpoints and message-only validation error extraction', async () => {
+    const repoRoot = await initGitRepo('aop-checkpoint-skipped-');
+    const state: MutableState = {
+      frontMatter: { version: 1, status: 'building' },
+      body: 'state body',
+    };
+    const sendMessage = vi.fn(async () => undefined);
+
+    const service = new CheckpointService({
+      repoRoot,
+      featurePathResolver: (featureId: string) =>
+        path.join(repoRoot, '.aop', 'features', featureId),
+      worktreePathResolver: (_featureId: string) => path.join(repoRoot, '.missing-worktree'),
+      validateDiff: vi.fn(async () => {
+        throw {
+          normalizedResponse: {
+            error: {
+              details: {
+                message: 'checkpoint message violation',
+              },
+            },
+          },
+        };
+      }),
+      watchdog: {
+        getChangedFiles: vi.fn(async () => ['tracked.txt']),
+        resetChangeCount: vi.fn(),
+      } as unknown as WorktreeWatchdogService,
+      provider: {
+        selection: {
+          provider: 'custom',
+          model: 'local-default',
+          provider_config_env: null,
+          provider_config_ref: null,
+        },
+        runWorker: vi.fn(),
+        sendMessage,
+      } as unknown as CheckpointProviderPort,
+      readState: async () => ({ frontMatter: state.frontMatter }),
+      updateState: makeUpdateState(state),
+      config: defaultConfig({ validationOnCheckpoint: true }),
+    });
+
+    try {
+      // Missing worktree path forces git diff failure => skipped checkpoint branch.
+      const skipped = await service.createCheckpoint({
+        featureId: 'feature_skipped',
+        sessionId: 'builder-session-skipped',
+        trigger: 'final',
+      });
+      expect(skipped.checkpoint.validation_status).toBe('skipped');
+
+      // Valid worktree + message-only violation details exercises extractViolationMessages fallback.
+      const validatingService = new CheckpointService({
+        repoRoot,
+        featurePathResolver: (featureId: string) =>
+          path.join(repoRoot, '.aop', 'features', featureId),
+        worktreePathResolver: () => repoRoot,
+        validateDiff: vi.fn(async () => {
+          throw {
+            normalizedResponse: {
+              error: {
+                details: {
+                  message: 'checkpoint message violation',
+                },
+              },
+            },
+          };
+        }),
+        watchdog: {
+          getChangedFiles: vi.fn(async () => ['tracked.txt']),
+          resetChangeCount: vi.fn(),
+        } as unknown as WorktreeWatchdogService,
+        provider: {
+          selection: {
+            provider: 'custom',
+            model: 'local-default',
+            provider_config_env: null,
+            provider_config_ref: null,
+          },
+          runWorker: vi.fn(),
+          sendMessage: vi.fn(async () => {
+            throw new Error('send failed');
+          }),
+        } as unknown as CheckpointProviderPort,
+        readState: async () => ({ frontMatter: state.frontMatter }),
+        updateState: makeUpdateState(state),
+        config: defaultConfig({ revertOnViolation: false, violationSeverity: 'warning' }),
+      });
+
+      await fs.writeFile(path.join(repoRoot, 'tracked.txt'), 'changed\\n', 'utf8');
+      const invalid = await validatingService.createCheckpoint({
+        featureId: 'feature_message',
+        sessionId: 'builder-session-message',
+        trigger: 'final',
+      });
+      expect(invalid.checkpoint.validation_status).toBe('invalid');
+      expect(invalid.checkpoint.violations).toEqual(['checkpoint message violation']);
+      expect(invalid.blockMerge).toBe(false);
+    } finally {
+      await fs.rm(repoRoot, { recursive: true, force: true });
+    }
+  });
+
+  it('merges existing interactive metrics snapshot and updates rolling histories', async () => {
+    const repoRoot = await initGitRepo('aop-checkpoint-metrics-');
+    const state: MutableState = {
+      frontMatter: { version: 1, status: 'building' },
+      body: 'state body',
+    };
+    const metricsPath = path.join(repoRoot, '.aop', 'analytics', 'interactive-mode.json');
+    await fs.mkdir(path.dirname(metricsPath), { recursive: true });
+    await fs.writeFile(
+      metricsPath,
+      JSON.stringify(
+        {
+          schema_version: 1,
+          updated_at: '2026-03-06T00:00:00.000Z',
+          totals: {
+            checkpoint_count: 2,
+            valid_count: 1,
+            invalid_count: 1,
+            skipped_count: 0,
+            files_changed_total: 3,
+          },
+          histories: {
+            checkpoint_latency_ms: [120, 240],
+            validation_latency_ms: [90, 180],
+            diff_capture_latency_ms: [30, 60],
+          },
+          latest: null,
+        },
+        null,
+        2,
+      ),
+      'utf8',
+    );
+
+    const service = new CheckpointService({
+      repoRoot,
+      featurePathResolver: (featureId: string) =>
+        path.join(repoRoot, '.aop', 'features', featureId),
+      worktreePathResolver: () => repoRoot,
+      validateDiff: vi.fn(async () => ({
+        valid: true,
+        violations: [],
+        changed_files: ['tracked.txt'],
+      })),
+      watchdog: {
+        getChangedFiles: vi.fn(async () => ['tracked.txt']),
+        resetChangeCount: vi.fn(),
+      } as unknown as WorktreeWatchdogService,
+      provider: {
+        selection: {
+          provider: 'custom',
+          model: 'local-default',
+          provider_config_env: null,
+          provider_config_ref: null,
+        },
+        runWorker: vi.fn(),
+      } as unknown as CheckpointProviderPort,
+      readState: async () => ({ frontMatter: state.frontMatter }),
+      updateState: makeUpdateState(state),
+      config: defaultConfig(),
+    });
+
+    try {
+      await fs.writeFile(path.join(repoRoot, 'tracked.txt'), 'metrics-update\\n', 'utf8');
+      const result = await service.createCheckpoint({
+        featureId: 'feature_metrics',
+        trigger: 'interval',
+      });
+
+      const metricsRaw = await fs.readFile(metricsPath, 'utf8');
+      const metrics = JSON.parse(metricsRaw) as {
+        totals: {
+          checkpoint_count: number;
+          valid_count: number;
+          invalid_count: number;
+          files_changed_total: number;
+        };
+        histories: {
+          checkpoint_latency_ms: number[];
+          validation_latency_ms: number[];
+          diff_capture_latency_ms: number[];
+        };
+        latest: {
+          feature_id: string;
+          checkpoint_id: string;
+          trigger: string;
+        };
+      };
+
+      expect(metrics.totals.checkpoint_count).toBe(3);
+      expect(metrics.totals.valid_count).toBe(2);
+      expect(metrics.totals.invalid_count).toBe(1);
+      expect(metrics.totals.files_changed_total).toBeGreaterThanOrEqual(4);
+      expect(metrics.histories.checkpoint_latency_ms.length).toBe(3);
+      expect(metrics.histories.validation_latency_ms.length).toBe(3);
+      expect(metrics.histories.diff_capture_latency_ms.length).toBe(3);
+      expect(metrics.latest.feature_id).toBe('feature_metrics');
+      expect(metrics.latest.checkpoint_id).toBe(result.checkpoint.checkpoint_id);
+      expect(metrics.latest.trigger).toBe('interval');
+    } finally {
+      await fs.rm(repoRoot, { recursive: true, force: true });
+    }
+  });
+
+  it('serializes concurrent checkpoints for the same feature', async () => {
+    const repoRoot = await initGitRepo('aop-checkpoint-lock-');
+    const state: MutableState = {
+      frontMatter: { version: 1, status: 'building' },
+      body: 'state body',
+    };
+    const validateDiff = vi.fn(async () => {
+      await new Promise((resolve) => setTimeout(resolve, 40));
+      return { valid: true, violations: [], changed_files: ['tracked.txt'] };
+    });
+
+    const service = new CheckpointService({
+      repoRoot,
+      featurePathResolver: (featureId: string) =>
+        path.join(repoRoot, '.aop', 'features', featureId),
+      worktreePathResolver: () => repoRoot,
+      validateDiff,
+      watchdog: {
+        getChangedFiles: vi.fn(async () => ['tracked.txt']),
+        resetChangeCount: vi.fn(),
+      } as unknown as WorktreeWatchdogService,
+      provider: {
+        selection: {
+          provider: 'custom',
+          model: 'local-default',
+          provider_config_env: null,
+          provider_config_ref: null,
+        },
+        runWorker: vi.fn(),
+      } as unknown as CheckpointProviderPort,
+      readState: async () => ({ frontMatter: state.frontMatter }),
+      updateState: makeUpdateState(state),
+      config: defaultConfig(),
+    });
+
+    try {
+      await fs.writeFile(path.join(repoRoot, 'tracked.txt'), 'concurrent\\n', 'utf8');
+      const [first, second] = await Promise.all([
+        service.createCheckpoint({ featureId: 'feature_lock', trigger: 'final' }),
+        service.createCheckpoint({ featureId: 'feature_lock', trigger: 'final' }),
+      ]);
+
+      expect(first.checkpoint.checkpoint_id).not.toBe(second.checkpoint.checkpoint_id);
+      expect(validateDiff).toHaveBeenCalledTimes(2);
+    } finally {
+      await fs.rm(repoRoot, { recursive: true, force: true });
+    }
+  });
+});

package/apps/control-plane/test/cli-helpers.spec.ts

@@ -34,6 +34,8 @@ describe('cli helper modules', () => {
       '--takeover-stale-run',
       '--message',
       'hello world',
+      '--checkpoint',
+      'checkpoint-001',
     ]);
     expect(miscParsed).toMatchObject({
       command: 'status',
@@ -48,6 +50,7 @@ describe('cli helper modules', () => {
       batch: true,
       takeover_stale_run: true,
       message: 'hello world',
+      checkpoint: 'checkpoint-001',
     });
     // --port with non-numeric next token (no value consumed)
     const portNoNum = parser.parse(['run', '--port', '--foreground']);
@@ -68,6 +71,8 @@ describe('cli helper modules', () => {
       'AOP_PROVIDER_CFG',
       '--transport',
       'mcp',
+      '--execution-mode',
+      'interactive',
     ]);
 
     expect(parsed).toMatchObject({
@@ -76,6 +81,7 @@ describe('cli helper modules', () => {
       agent_config: '{"command":"kiro-cli","args":["chat","--agent","dev"]}',
       provider_config_env: 'AOP_PROVIDER_CFG',
       transport: 'mcp',
+      execution_mode: 'interactive',
     });
     const deleteParsed = parser.parse([
       'delete',
@@ -467,6 +473,7 @@ describe('HelpCommandHandler', () => {
     expect(result.data.help).toContain('Commands:');
     expect(result.data.help).toContain('run');
     expect(result.data.help).toContain('status');
+    expect(result.data.help).toContain('rollback');
   });
 
   it('GIVEN_valid_subcommand_WHEN_execute_called_THEN_returns_detailed_help_for_command', async () => {
@@ -476,6 +483,16 @@ describe('HelpCommandHandler', () => {
     expect(result.ok).toBe(true);
     expect(result.data.help).toContain('Usage: aop run');
     expect(result.data.help).toContain('Flags:');
+    expect(result.data.help).toContain('--execution-mode <deterministic|interactive>');
+  });
+
+  it('GIVEN_resume_help_WHEN_execute_called_THEN_documents_execution_mode_override', async () => {
+    const { HelpCommandHandler } = await import('../src/cli/help-command-handler.js');
+    const handler = new HelpCommandHandler();
+    const result = handler.execute('resume');
+    expect(result.ok).toBe(true);
+    expect(result.data.help).toContain('Usage: aop resume [flags]');
+    expect(result.data.help).toContain('--execution-mode <deterministic|interactive>');
   });
 
   it('GIVEN_unknown_subcommand_WHEN_execute_called_THEN_returns_full_help_text', async () => {
@@ -497,6 +514,17 @@ describe('HelpCommandHandler', () => {
     expect(result.data.help).toContain('--project <name>');
   });
 
+  it('GIVEN_rollback_help_WHEN_execute_called_THEN_renders_required_flags', async () => {
+    const { HelpCommandHandler } = await import('../src/cli/help-command-handler.js');
+    const handler = new HelpCommandHandler();
+    const result = handler.execute('rollback');
+    expect(result.ok).toBe(true);
+    expect(result.data.help).toContain('Usage: aop rollback [flags]');
+    expect(result.data.help).toContain('--feature-id <id>');
+    expect(result.data.help).toContain('--checkpoint <id>');
+    expect(result.data.help).toContain('--dry-run');
+  });
+
   it('GIVEN_delete_help_WHEN_execute_called_THEN_documents_yes_for_destructive_delete', async () => {
     const { HelpCommandHandler } = await import('../src/cli/help-command-handler.js');
     const handler = new HelpCommandHandler();

package/apps/control-plane/test/cli.unit.spec.ts

@@ -161,6 +161,10 @@ vi.mock('../src/providers/worker-provider-factory.js', () => ({
   },
   resolveWorkerProviderMode: vi.fn((_cliMode, _configuredMode, fallback) => fallback ?? 'live'),
   resolveWorkerProviderPolicy: vi.fn(() => ({ require_live_provider_for_run: true })),
+  resolveWorkerProviderObservability: vi.fn(() => ({
+    raw_agent_logs_enabled: false,
+    raw_agent_logs_retention_days: 60,
+  })),
   resolveWorkerProviderRuntime: vi.fn(() => ({
     worker_response_timeout_ms: 120000,
     max_consecutive_no_progress_iterations: 2,
@@ -364,6 +368,54 @@ describe('aop CLI unit', () => {
     });
   });
 
+  it('GIVEN_rollback_command_with_dry_run_WHEN_main_runs_THEN_returns_preview_payload', async () => {
+    const featureRoot = path.join(cwd, '.aop', 'features', 'feature_resume');
+    const checkpointsDir = path.join(featureRoot, 'checkpoints');
+    await fs.mkdir(checkpointsDir, { recursive: true });
+    await fs.writeFile(
+      path.join(checkpointsDir, 'checkpoint-001.diff'),
+      'diff --git a/a b/a\n',
+      'utf8',
+    );
+    await fs.writeFile(
+      path.join(featureRoot, 'state.md'),
+      [
+        '---',
+        'feature_id: feature_resume',
+        'version: 1',
+        `worktree_path: ${cwd}`,
+        'checkpoints:',
+        '  - checkpoint_id: checkpoint-001',
+        '    timestamp: 2026-03-06T00:00:00.000Z',
+        '    files_changed: [tracked.txt]',
+        '    validation_status: valid',
+        '    violations: []',
+        '    diff_snapshot: .aop/features/feature_resume/checkpoints/checkpoint-001.diff',
+        '---',
+        '',
+      ].join('\n'),
+      'utf8',
+    );
+
+    const code = await main(
+      ['rollback', '--feature-id', 'feature_resume', '--checkpoint', 'checkpoint-001', '--dry-run'],
+      { cwd, env: {} as NodeJS.ProcessEnv },
+    );
+    const writes = asJsonWrites(stdoutSpy);
+
+    expect(code).toBe(0);
+    expect(writes[0]).toMatchObject({
+      ok: true,
+      data: {
+        command: 'rollback',
+        feature_id: 'feature_resume',
+        checkpoint_id: 'checkpoint-001',
+        dry_run: true,
+        applied: false,
+      },
+    });
+  });
+
   it('GIVEN_delete_without_feature_id_WHEN_main_runs_THEN_returns_invalid_cli_args', async () => {
     const code = await main(['delete'], { cwd, env: {} as NodeJS.ProcessEnv });
     const writes = asJsonWrites(stdoutSpy);