agentic-orchestrator 0.1.27 → 0.2.0

package/apps/control-plane/test/resume-command.spec.ts

@@ -6,6 +6,8 @@ vi.mock('../src/providers/providers.js', () => ({
     model: 'none',
     provider_config_ref: null,
   })),
+  resolveProviderSelectionsByRole: vi.fn(() => ({})),
+  validateRoleProviderCompatibility: vi.fn(() => ({ valid: true, errors: [] })),
   SUPPORTED_PROVIDERS: new Set(['codex', 'claude', 'gemini', 'custom', 'kiro-cli', 'copilot']),
   NullWorkerProvider: class NullWorkerProvider {
     selection: unknown;
@@ -59,6 +61,9 @@ vi.mock('../src/providers/worker-provider-factory.js', () => ({
     worker_response_timeout_ms: 120000,
     max_consecutive_no_progress_iterations: 2,
   })),
+  resolvePromptOverlayDir: vi.fn(
+    (repoRoot: string) => `${repoRoot}/config/agentic/orchestrator/prompts/overrides`,
+  ),
 }));
 
 vi.mock('../src/supervisor/runtime.js', () => ({
@@ -76,6 +81,8 @@ vi.mock('../src/supervisor/runtime.js', () => ({
 
 import { ResumeCommandHandler } from '../src/cli/resume-command-handler.js';
 import { STATUS } from '../src/core/constants.js';
+import { ERROR_CODES } from '../src/core/error-codes.js';
+import { validateRoleProviderCompatibility } from '../src/providers/providers.js';
 import type { ToolTransport } from '../src/cli/types.js';
 
 function makeKernel(overrides: Record<string, unknown> = {}) {
@@ -89,6 +96,7 @@ function makeKernel(overrides: Record<string, unknown> = {}) {
       orchestrator_epoch: 0,
       feature_sessions: {},
     })),
+    isRunLeaseFresh: vi.fn(() => false),
     featureDiscoverSpecs: vi.fn(async () => ({ data: { specs: [] } })),
     featureStateGet: vi.fn(async () => ({
       data: { front_matter: { status: STATUS.PLANNING } },
@@ -185,6 +193,24 @@ describe('ResumeCommandHandler', () => {
     expect(result.data.resumed).toBe(false); // Terminal feature excluded, no resumables
   });
 
+  it('GIVEN_explicit_ready_to_merge_feature_WHEN_resume_is_requested_THEN_returns_invalid_status_transition', async () => {
+    const kernel = makeKernel({
+      featureStateGet: vi.fn(async () => ({
+        data: { front_matter: { status: STATUS.READY_TO_MERGE } },
+      })),
+    });
+    const handler = new ResumeCommandHandler();
+    const context = makeContext(kernel, {
+      call: vi.fn(async () => ({ ok: true, data: {} })),
+    });
+    context.options = { feature_id: 'feature_ready' } as any;
+    const result = (await handler.execute(context)) as any;
+
+    expect(result.ok).toBe(false);
+    expect(result.error.code).toBe(ERROR_CODES.INVALID_STATUS_TRANSITION);
+    expect(result.error.message).toContain('ready_to_merge');
+  });
+
   it('GIVEN_empty_feature_id_in_blocked_queue_WHEN_addSource_called_THEN_guards_and_skips', async () => {
     // Exercises addSource's `if (!featureId) return` guard
     const kernel = makeKernel({
@@ -275,10 +301,401 @@ describe('ResumeCommandHandler', () => {
 
     expect(result.ok).toBe(true);
   });
+
+  it('GIVEN_resume_feature_id_filter_WHEN_execute_THEN_targets_only_requested_feature', async () => {
+    const kernel = makeKernel({
+      readIndex: vi.fn(async () => ({
+        active: ['feature_a', 'feature_b'],
+        blocked: [],
+        blocked_queue: [],
+      })),
+      featureStateGet: vi.fn(async (featureId: string) => ({
+        data: {
+          front_matter: {
+            status: featureId === 'feature_b' ? STATUS.BUILDING : STATUS.PLANNING,
+          },
+        },
+      })),
+    });
+    const handler = new ResumeCommandHandler();
+    const context = makeContext(kernel);
+    context.options = { feature_id: 'feature_b' } as any;
+    const result = (await handler.execute(context)) as any;
+
+    expect(result.ok).toBe(true);
+    expect(result.data.resumed).toBe(true);
+    expect(result.data.resumed_features).toEqual([
+      expect.objectContaining({ feature_id: 'feature_b' }),
+    ]);
+    expect(kernel.featureStateGet).toHaveBeenCalledTimes(1);
+    expect(kernel.featureStateGet).toHaveBeenCalledWith('feature_b');
+  });
+
+  it('GIVEN_requested_feature_awaiting_input_WHEN_execute_THEN_keeps_feature_in_resume_plan', async () => {
+    const kernel = makeKernel({
+      featureStateGet: vi.fn(async () => ({
+        data: {
+          front_matter: {
+            status: STATUS.AWAITING_INPUT,
+            human_input: { open_question_count: 1 },
+          },
+        },
+      })),
+    });
+    const handler = new ResumeCommandHandler();
+    const context = makeContext(kernel);
+    context.options = { feature_id: 'feature_waiting' } as any;
+    const result = (await handler.execute(context)) as any;
+
+    expect(result.ok).toBe(true);
+    expect(result.data.resumed).toBe(true);
+    expect(result.data.resumed_features).toEqual([
+      expect.objectContaining({
+        feature_id: 'feature_waiting',
+        status: STATUS.AWAITING_INPUT,
+      }),
+    ]);
+  });
+
+  it('GIVEN_requested_feature_blocked_with_open_question_WHEN_execute_THEN_normalizes_back_to_awaiting_input', async () => {
+    const kernel = makeKernel({
+      featureStateGet: vi.fn(async () => ({
+        data: {
+          front_matter: {
+            status: STATUS.BLOCKED,
+            human_input: {
+              open_question_id: 'q_open',
+              open_question_count: 1,
+              resume_status: STATUS.INTAKE,
+            },
+          },
+        },
+      })),
+    });
+    const handler = new ResumeCommandHandler();
+    const context = makeContext(kernel);
+    context.options = { feature_id: 'feature_waiting' } as any;
+    const result = (await handler.execute(context)) as any;
+
+    expect(result.ok).toBe(true);
+    expect(result.data.resumed).toBe(true);
+    expect(result.data.resumed_features).toEqual([
+      expect.objectContaining({
+        feature_id: 'feature_waiting',
+        status: STATUS.AWAITING_INPUT,
+        resume_phase: STATUS.INTAKE,
+      }),
+    ]);
+  });
+
+  it('GIVEN_fresh_active_run_and_unassigned_feature_WHEN_execute_THEN_submits_execution_enrollment', async () => {
+    const toolClient = {
+      call: vi.fn(async () => ({
+        ok: true,
+        data: {
+          run_id: 'run:active',
+          request_id: 'exec_req_123',
+          request_status: 'pending',
+          requested_features: [
+            { feature_id: 'feature_waiting', spec_path: '.aop/features/feature_waiting/spec.md' },
+          ],
+        },
+      })),
+    };
+    const kernel = makeKernel({
+      getRuntimeSessions: vi.fn(async () => ({
+        run_id: 'run:active',
+        owner_instance_id: 'owner:active',
+        orchestrator_session_id: 'orch-sess',
+        orchestrator_epoch: 1,
+        feature_sessions: {},
+      })),
+      isRunLeaseFresh: vi.fn(() => true),
+      featureStateGet: vi.fn(async () => ({
+        data: {
+          front_matter: {
+            status: STATUS.AWAITING_INPUT,
+            human_input: { open_question_count: 1 },
+          },
+        },
+      })),
+    });
+    const handler = new ResumeCommandHandler();
+    const context = makeContext(kernel, toolClient);
+    context.options = { feature_id: 'feature_waiting' } as any;
+
+    const result = (await handler.execute(context)) as any;
+
+    expect(result.ok).toBe(true);
+    expect(result.data.resumed).toBe(true);
+    expect(result.data.resume_mode).toBe('active_run_enrollment');
+    expect(result.data.request_id).toBe('exec_req_123');
+    expect(result.data.request_status).toBe('pending');
+    expect(result.data.enrolled_features).toEqual(['feature_waiting']);
+    expect(toolClient.call).toHaveBeenCalledWith(
+      'runtime.execution_request_submit',
+      expect.objectContaining({
+        run_id: 'run:active',
+        owner_instance_id: 'owner:active',
+        request_type: 'add_features',
+        features: [
+          {
+            feature_id: 'feature_waiting',
+            spec_path: '.aop/features/feature_waiting/spec.md',
+          },
+        ],
+      }),
+      expect.any(Object),
+    );
+  });
+
+  it('GIVEN_fresh_active_run_and_unassigned_feature_with_untyped_request_metadata_WHEN_execute_THEN_normalizes_request_fields_to_null', async () => {
+    const toolClient = {
+      call: vi.fn(async () => ({
+        ok: true,
+        data: {
+          request_id: 42,
+          request_status: { state: 'pending' },
+        },
+      })),
+    };
+    const kernel = makeKernel({
+      getRuntimeSessions: vi.fn(async () => ({
+        run_id: 'run:active',
+        owner_instance_id: 'owner:active',
+        orchestrator_session_id: 'orch-sess',
+        orchestrator_epoch: 1,
+        feature_sessions: {},
+      })),
+      isRunLeaseFresh: vi.fn(() => true),
+      featureStateGet: vi.fn(async () => ({
+        data: {
+          front_matter: {
+            status: STATUS.AWAITING_INPUT,
+            human_input: { open_question_count: 1 },
+          },
+        },
+      })),
+    });
+    const handler = new ResumeCommandHandler();
+    const context = makeContext(kernel, toolClient);
+    context.options = { feature_id: 'feature_waiting' } as any;
+
+    const result = (await handler.execute(context)) as any;
+
+    expect(result.ok).toBe(true);
+    expect(result.data.resumed).toBe(true);
+    expect(result.data.resume_mode).toBe('active_run_enrollment');
+    expect(result.data.request_id).toBeNull();
+    expect(result.data.request_status).toBeNull();
+    expect(result.data.enrolled_features).toEqual(['feature_waiting']);
+  });
+
+  it('GIVEN_fresh_active_run_with_non_object_feature_sessions_WHEN_execute_THEN_treats_all_features_as_unassigned', async () => {
+    const toolClient = {
+      call: vi.fn(async () => ({
+        ok: true,
+        data: {
+          request_id: 'exec_req_non_object_sessions',
+          request_status: 'pending',
+        },
+      })),
+    };
+    const kernel = makeKernel({
+      getRuntimeSessions: vi.fn(async () => ({
+        run_id: 'run:active',
+        owner_instance_id: 'owner:active',
+        orchestrator_session_id: 'orch-sess',
+        orchestrator_epoch: 1,
+        feature_sessions: null,
+      })),
+      isRunLeaseFresh: vi.fn(() => true),
+      featureStateGet: vi.fn(async () => ({
+        data: {
+          front_matter: {
+            status: STATUS.AWAITING_INPUT,
+            human_input: { open_question_count: 1 },
+          },
+        },
+      })),
+    });
+    const handler = new ResumeCommandHandler();
+    const context = makeContext(kernel, toolClient);
+    context.options = { feature_id: 'feature_waiting' } as any;
+
+    const result = (await handler.execute(context)) as any;
+
+    expect(result.ok).toBe(true);
+    expect(result.data.resume_mode).toBe('active_run_enrollment');
+    expect(result.data.enrolled_features).toEqual(['feature_waiting']);
+    expect(result.data.already_enrolled_features).toEqual([]);
+  });
+
+  it('GIVEN_fresh_active_run_and_assigned_feature_WHEN_execute_THEN_returns_already_enrolled', async () => {
+    const toolClient = {
+      call: vi.fn(async () => ({ ok: true, data: {} })),
+    };
+    const kernel = makeKernel({
+      getRuntimeSessions: vi.fn(async () => ({
+        run_id: 'run:active',
+        owner_instance_id: 'owner:active',
+        orchestrator_session_id: 'orch-sess',
+        orchestrator_epoch: 1,
+        feature_sessions: { feature_waiting: { planner_session_id: 'planner-1' } },
+      })),
+      isRunLeaseFresh: vi.fn(() => true),
+      featureStateGet: vi.fn(async () => ({
+        data: {
+          front_matter: {
+            status: STATUS.AWAITING_INPUT,
+            human_input: { open_question_count: 1 },
+          },
+        },
+      })),
+    });
+    const handler = new ResumeCommandHandler();
+    const context = makeContext(kernel, toolClient);
+    context.options = { feature_id: 'feature_waiting' } as any;
+
+    const result = (await handler.execute(context)) as any;
+
+    expect(result.ok).toBe(true);
+    expect(result.data.resumed).toBe(true);
+    expect(result.data.resume_mode).toBe('already_enrolled');
+    expect(result.data.request_id).toBeNull();
+    expect(result.data.request_status).toBeNull();
+    expect(result.data.already_enrolled_features).toEqual(['feature_waiting']);
+    expect(toolClient.call).not.toHaveBeenCalled();
+  });
+
+  it('GIVEN_fresh_active_run_and_duplicate_enrollment_request_WHEN_execute_THEN_treats_request_as_pending', async () => {
+    const duplicateError = Object.assign(new Error('duplicate request'), {
+      code: ERROR_CODES.DUPLICATE_EXECUTION_REQUEST,
+    });
+    const toolClient = {
+      call: vi.fn(async () => {
+        throw duplicateError;
+      }),
+    };
+    const kernel = makeKernel({
+      getRuntimeSessions: vi.fn(async () => ({
+        run_id: 'run:active',
+        owner_instance_id: 'owner:active',
+        orchestrator_session_id: 'orch-sess',
+        orchestrator_epoch: 1,
+        feature_sessions: {},
+      })),
+      isRunLeaseFresh: vi.fn(() => true),
+      featureStateGet: vi.fn(async () => ({
+        data: {
+          front_matter: {
+            status: STATUS.AWAITING_INPUT,
+            human_input: { open_question_count: 1 },
+          },
+        },
+      })),
+    });
+    const handler = new ResumeCommandHandler();
+    const context = makeContext(kernel, toolClient);
+    context.options = { feature_id: 'feature_waiting' } as any;
+
+    const result = (await handler.execute(context)) as any;
+
+    expect(result.ok).toBe(true);
+    expect(result.data.resumed).toBe(true);
+    expect(result.data.resume_mode).toBe('active_run_enrollment');
+    expect(result.data.request_id).toBeNull();
+    expect(result.data.request_status).toBe('pending');
+    expect(result.data.enrolled_features).toEqual(['feature_waiting']);
+  });
+
+  it('GIVEN_fresh_active_run_and_non_duplicate_enrollment_error_WHEN_execute_THEN_rethrows', async () => {
+    const toolClient = {
+      call: vi.fn(async () => {
+        const error = new Error('backend unavailable') as Error & { code?: string };
+        error.code = ERROR_CODES.INTERNAL_ERROR;
+        throw error;
+      }),
+    };
+    const kernel = makeKernel({
+      getRuntimeSessions: vi.fn(async () => ({
+        run_id: 'run:active',
+        owner_instance_id: 'owner:active',
+        orchestrator_session_id: 'orch-sess',
+        orchestrator_epoch: 1,
+        feature_sessions: {},
+      })),
+      isRunLeaseFresh: vi.fn(() => true),
+      featureStateGet: vi.fn(async () => ({
+        data: {
+          front_matter: {
+            status: STATUS.AWAITING_INPUT,
+            human_input: { open_question_count: 1 },
+          },
+        },
+      })),
+    });
+    const handler = new ResumeCommandHandler();
+    const context = makeContext(kernel, toolClient);
+    context.options = { feature_id: 'feature_waiting' } as any;
+
+    await expect(handler.execute(context)).rejects.toMatchObject({
+      code: ERROR_CODES.INTERNAL_ERROR,
+      message: 'backend unavailable',
+    });
+  });
+
+  it('GIVEN_fresh_active_run_and_mixed_assignment_set_WHEN_execute_THEN_tracks_enrolled_and_already_enrolled_features', async () => {
+    const toolClient = {
+      call: vi.fn(async () => ({
+        ok: true,
+        data: {
+          run_id: 'run:active',
+          request_id: 'exec_req_456',
+          request_status: 'pending',
+        },
+      })),
+    };
+    const kernel = makeKernel({
+      readIndex: vi.fn(async () => ({
+        active: ['feature_waiting', 'feature_ready'],
+        blocked: [],
+        blocked_queue: [],
+      })),
+      getRuntimeSessions: vi.fn(async () => ({
+        run_id: 'run:active',
+        owner_instance_id: 'owner:active',
+        orchestrator_session_id: 'orch-sess',
+        orchestrator_epoch: 1,
+        feature_sessions: { feature_waiting: { planner_session_id: 'planner-1' } },
+      })),
+      isRunLeaseFresh: vi.fn(() => true),
+      featureStateGet: vi.fn(async (featureId: string) => ({
+        data: {
+          front_matter:
+            featureId === 'feature_waiting'
+              ? {
+                  status: STATUS.AWAITING_INPUT,
+                  human_input: { open_question_count: 1 },
+                }
+              : { status: STATUS.BUILDING },
+        },
+      })),
+    });
+    const handler = new ResumeCommandHandler();
+
+    const result = (await handler.execute(makeContext(kernel, toolClient))) as any;
+
+    expect(result.ok).toBe(true);
+    expect(result.data.resume_mode).toBe('active_run_enrollment');
+    expect(result.data.request_id).toBe('exec_req_456');
+    expect(result.data.enrolled_features).toEqual(['feature_ready']);
+    expect(result.data.already_enrolled_features).toEqual(['feature_waiting']);
+  });
 });
 
 describe('ResumeCommandHandler additional branches', () => {
-  it('GIVEN_feature_with_READY_TO_MERGE_status_WHEN_buildResumePlan_THEN_phase_is_READY_TO_MERGE', async () => {
+  it('GIVEN_feature_with_READY_TO_MERGE_status_WHEN_buildResumePlan_THEN_excludes_feature_from_generic_resume', async () => {
     const kernel = makeKernel({
       readIndex: vi.fn(async () => ({ active: ['feature_rtm'], blocked: [], blocked_queue: [] })),
       featureStateGet: vi.fn(async () => ({
@@ -288,10 +705,48 @@ describe('ResumeCommandHandler additional branches', () => {
     const handler = new ResumeCommandHandler();
     const result = (await handler.execute(makeContext(kernel))) as any;
     expect(result.ok).toBe(true);
-    // Feature is non-terminal, included → supervisor called → resumed: true
-    expect(result.data.resumed).toBe(true);
+    expect(result.data.resumed).toBe(false);
+  });
+
+  it('GIVEN_blocked_merge_failed_feature_WHEN_buildResumePlan_THEN_phase_stays_READY_TO_MERGE', async () => {
+    const kernel = makeKernel({
+      readIndex: vi.fn(async () => ({
+        active: ['feature_merge_blocked'],
+        blocked: [],
+        blocked_queue: [],
+      })),
+      featureStateGet: vi.fn(async () => ({
+        data: {
+          front_matter: {
+            status: STATUS.BLOCKED,
+            gates: { plan: 'pass', fast: 'pass', full: 'pass', merge: 'fail' },
+            evidence: { last_gate_mode: 'merge' },
+            merge_repair: {
+              attempts: 1,
+              max_attempts: 5,
+              active: true,
+              requested_at: null,
+              last_failed_at: null,
+              last_gate_evidence_path: null,
+              last_failure_summary: null,
+              reviewer_message: null,
+              exhausted_at: null,
+            },
+          },
+        },
+      })),
+    });
+    const handler = new ResumeCommandHandler();
+    const result = (await handler.execute(makeContext(kernel))) as any;
+
+    expect(result.ok).toBe(true);
     expect(
-      result.data.resumed_features?.some((f: any) => f.resume_phase === STATUS.READY_TO_MERGE),
+      result.data.resumed_features?.some(
+        (f: any) =>
+          f.feature_id === 'feature_merge_blocked' &&
+          f.status === STATUS.BLOCKED &&
+          f.resume_phase === STATUS.READY_TO_MERGE,
+      ),
     ).toBe(true);
   });
 
@@ -331,7 +786,7 @@ describe('ResumeCommandHandler additional branches', () => {
     expect(result.data.resume_plan?.owner_instance_id).toBe('owner:real');
   });
 
-  it('GIVEN_feature_with_READY_TO_MERGE_status_WHEN_buildResumePlan_THEN_phase_is_ready_to_merge', async () => {
+  it('GIVEN_feature_with_READY_TO_MERGE_status_WHEN_buildResumePlan_THEN_feature_is_not_present_in_resume_plan', async () => {
     const kernel = makeKernel({
       readIndex: vi.fn(async () => ({ active: ['feature_rtm'], blocked: [], blocked_queue: [] })),
       featureStateGet: vi.fn(async () => ({
@@ -343,7 +798,7 @@ describe('ResumeCommandHandler additional branches', () => {
     expect(result.ok).toBe(true);
     const features = result.data.resumed_features ?? result.data.resume_plan?.features ?? [];
     const feature = features.find((f: any) => f.feature_id === 'feature_rtm');
-    expect(feature?.resume_phase).toBe(STATUS.READY_TO_MERGE);
+    expect(feature).toBeUndefined();
   });
 
   it('GIVEN_feature_with_unknown_status_WHEN_buildResumePlan_THEN_phase_is_planning', async () => {
@@ -390,6 +845,34 @@ describe('ResumeCommandHandler additional branches', () => {
     expect(features.some((f: any) => typeof f.feature_id !== 'string')).toBe(false);
   });
 
+  it('GIVEN_mixed_resumable_and_awaiting_input_features_WHEN_execute_THEN_keeps_both_in_resume_plan', async () => {
+    const kernel = makeKernel({
+      readIndex: vi.fn(async () => ({
+        active: ['feature_waiting', 'feature_ready'],
+        blocked: [],
+        blocked_queue: [],
+      })),
+      featureStateGet: vi.fn(async (featureId: string) => ({
+        data: {
+          front_matter:
+            featureId === 'feature_waiting'
+              ? {
+                  status: STATUS.AWAITING_INPUT,
+                  human_input: { open_question_count: 1 },
+                }
+              : { status: STATUS.BUILDING },
+        },
+      })),
+    });
+    const handler = new ResumeCommandHandler();
+    const result = (await handler.execute(makeContext(kernel))) as any;
+    const features = result.data.resumed_features ?? result.data.resume_plan?.features ?? [];
+
+    expect(result.ok).toBe(true);
+    expect(features.some((f: any) => f.feature_id === 'feature_waiting')).toBe(true);
+    expect(features.some((f: any) => f.feature_id === 'feature_ready')).toBe(true);
+  });
+
   it('GIVEN_feature_sessions_with_empty_feature_id_WHEN_buildResumePlan_THEN_empty_id_skipped', async () => {
     const kernel = makeKernel({
       readIndex: vi.fn(async () => ({
@@ -411,7 +894,7 @@ describe('ResumeCommandHandler additional branches', () => {
 });
 
 describe('ResumeCommandHandler phaseRank and addSource branches', () => {
-  it('GIVEN_two_features_one_READY_TO_MERGE_WHEN_execute_THEN_phaseRank_called_with_ready_to_merge', async () => {
+  it('GIVEN_two_features_one_READY_TO_MERGE_WHEN_execute_THEN_excludes_ready_feature_and_keeps_remaining_resumables', async () => {
     const kernel = makeKernel({
       readIndex: vi.fn(async () => ({
         active: ['feature_rtm', 'feature_qa'],
@@ -428,8 +911,9 @@ describe('ResumeCommandHandler phaseRank and addSource branches', () => {
     const result = (await handler.execute(makeContext(kernel))) as any;
     expect(result.ok).toBe(true);
     const features = result.data.resumed_features ?? [];
-    expect(features.length).toBe(2);
-    expect(features.some((f: any) => f.resume_phase === STATUS.READY_TO_MERGE)).toBe(true);
+    expect(features.length).toBe(1);
+    expect(features[0]?.feature_id).toBe('feature_qa');
+    expect(features.some((f: any) => f.resume_phase === STATUS.READY_TO_MERGE)).toBe(false);
   });
 
   it('GIVEN_feature_sessions_with_empty_key_WHEN_execute_THEN_addSource_empty_featureId_guard', async () => {
@@ -478,4 +962,297 @@ describe('ResumeCommandHandler phaseRank and addSource branches', () => {
     const features = result.data.resumed_features ?? result.data.resume_plan?.features ?? [];
     expect(features.length).toBe(0);
   });
+
+  it('GIVEN_invalid_role_provider_compatibility_WHEN_resume_THEN_throws_with_error_code', async () => {
+    const kernel = makeKernel({
+      readIndex: vi.fn(async () => ({
+        active: ['feat_compat'],
+        blocked: [],
+        blocked_queue: [],
+      })),
+      featureStateGet: vi.fn(async () => ({
+        data: { front_matter: { status: STATUS.PLANNING } },
+      })),
+    });
+    vi.mocked(validateRoleProviderCompatibility).mockReturnValueOnce({
+      valid: false,
+      errors: [
+        {
+          code: ERROR_CODES.UNSUPPORTED_AGENT_PROVIDER,
+          message: 'Provider "bad" not supported for builder',
+          details: { retryable: false },
+          role: 'builder',
+        },
+      ],
+    });
+    const handler = new ResumeCommandHandler();
+    await expect(handler.execute(makeContext(kernel))).rejects.toThrow(
+      'Provider "bad" not supported for builder',
+    );
+  });
+
+  it('GIVEN_feature_with_intake_status_WHEN_resume_THEN_sorts_before_planning', async () => {
+    const kernel = makeKernel({
+      readIndex: vi.fn(async () => ({
+        active: ['feat_intake', 'feat_plan'],
+        blocked: [],
+        blocked_queue: [],
+      })),
+      featureStateGet: vi.fn(async (featureId: string) => {
+        if (featureId === 'feat_intake') {
+          return { data: { front_matter: { status: STATUS.INTAKE } } };
+        }
+        return { data: { front_matter: { status: STATUS.PLANNING } } };
+      }),
+    });
+    const handler = new ResumeCommandHandler();
+    const result = (await handler.execute(makeContext(kernel))) as any;
+    expect(result.ok).toBe(true);
+    const features = result.data.resumed_features ?? [];
+    expect(features.length).toBe(2);
+    // intake should come before planning (rank -1 < 0)
+    expect(features[0].feature_id).toBe('feat_intake');
+    expect(features[1].feature_id).toBe('feat_plan');
+  });
+
+  it('GIVEN_requested_feature_with_ready_to_merge_WHEN_resume_THEN_returns_blocked_error', async () => {
+    const kernel = makeKernel({
+      readIndex: vi.fn(async () => ({
+        active: [],
+        blocked: [],
+        blocked_queue: [],
+      })),
+      featureStateGet: vi.fn(async () => ({
+        data: { front_matter: { status: STATUS.READY_TO_MERGE } },
+      })),
+    });
+    const handler = new ResumeCommandHandler();
+    const ctx = makeContext(kernel);
+    ctx.options = { feature_id: 'feat_merge' } as any;
+    const result = (await handler.execute(ctx)) as any;
+    expect(result.ok).toBe(false);
+    expect(result.error.code).toBe(ERROR_CODES.INVALID_STATUS_TRANSITION);
+  });
+
+  it('GIVEN_feature_with_unknown_status_WHEN_resume_THEN_phaseRank_returns_default', async () => {
+    const kernel = makeKernel({
+      readIndex: vi.fn(async () => ({
+        active: ['feat_unknown', 'feat_plan'],
+        blocked: [],
+        blocked_queue: [],
+      })),
+      featureStateGet: vi.fn(async (featureId: string) => {
+        if (featureId === 'feat_unknown') {
+          return { data: { front_matter: { status: 'some_custom_status' } } };
+        }
+        return { data: { front_matter: { status: STATUS.PLANNING } } };
+      }),
+    });
+    const handler = new ResumeCommandHandler();
+    const result = (await handler.execute(makeContext(kernel))) as any;
+    expect(result.ok).toBe(true);
+    const features = result.data.resumed_features ?? [];
+    // planning (rank 0) should come before unknown (rank 99)
+    expect(features.length).toBe(2);
+    expect(features[0].feature_id).toBe('feat_plan');
+    expect(features[1].feature_id).toBe('feat_unknown');
+  });
+
+  it('GIVEN_deterministic_execution_mode_WHEN_resume_with_resumable_features_THEN_passes_deterministic_to_compatibility_check', async () => {
+    const kernel = makeKernel({
+      readIndex: vi.fn(async () => ({
+        active: ['feat_det'],
+        blocked: [],
+        blocked_queue: [],
+      })),
+      featureStateGet: vi.fn(async () => ({
+        data: { front_matter: { status: STATUS.PLANNING } },
+      })),
+    });
+    vi.mocked(validateRoleProviderCompatibility).mockReturnValueOnce({
+      valid: true,
+      errors: [],
+    });
+    const handler = new ResumeCommandHandler();
+    const context = makeContext(kernel);
+    context.options = { execution_mode: 'deterministic' } as any;
+    const result = (await handler.execute(context)) as any;
+
+    expect(result.ok).toBe(true);
+    expect(result.data.resumed).toBe(true);
+    expect(validateRoleProviderCompatibility).toHaveBeenCalledWith(
+      expect.anything(),
+      'deterministic',
+    );
+  });
+
+  it('GIVEN_interactive_execution_mode_WHEN_resume_with_resumable_features_THEN_passes_interactive_to_compatibility_check', async () => {
+    const kernel = makeKernel({
+      readIndex: vi.fn(async () => ({
+        active: ['feat_int'],
+        blocked: [],
+        blocked_queue: [],
+      })),
+      featureStateGet: vi.fn(async () => ({
+        data: { front_matter: { status: STATUS.BUILDING } },
+      })),
+    });
+    vi.mocked(validateRoleProviderCompatibility).mockReturnValueOnce({
+      valid: true,
+      errors: [],
+    });
+    const handler = new ResumeCommandHandler();
+    const context = makeContext(kernel);
+    context.options = { execution_mode: 'interactive' } as any;
+    const result = (await handler.execute(context)) as any;
+
+    expect(result.ok).toBe(true);
+    expect(result.data.resumed).toBe(true);
+    expect(validateRoleProviderCompatibility).toHaveBeenCalledWith(
+      expect.anything(),
+      'interactive',
+    );
+  });
+
+  it('GIVEN_non_standard_execution_mode_WHEN_resume_THEN_passes_null_to_compatibility_check', async () => {
+    const kernel = makeKernel({
+      readIndex: vi.fn(async () => ({
+        active: ['feat_null_mode'],
+        blocked: [],
+        blocked_queue: [],
+      })),
+      featureStateGet: vi.fn(async () => ({
+        data: { front_matter: { status: STATUS.PLANNING } },
+      })),
+    });
+    vi.mocked(validateRoleProviderCompatibility).mockReturnValueOnce({
+      valid: true,
+      errors: [],
+    });
+    const handler = new ResumeCommandHandler();
+    const context = makeContext(kernel);
+    context.options = { execution_mode: 'bogus' } as any;
+    const result = (await handler.execute(context)) as any;
+
+    expect(result.ok).toBe(true);
+    expect(validateRoleProviderCompatibility).toHaveBeenCalledWith(expect.anything(), null);
+  });
+
+  it('GIVEN_multiple_compatibility_errors_WHEN_resume_THEN_throws_first_error_with_all_errors_in_details', async () => {
+    const kernel = makeKernel({
+      readIndex: vi.fn(async () => ({
+        active: ['feat_multi_err'],
+        blocked: [],
+        blocked_queue: [],
+      })),
+      featureStateGet: vi.fn(async () => ({
+        data: { front_matter: { status: STATUS.PLANNING } },
+      })),
+    });
+    const errors = [
+      {
+        code: ERROR_CODES.UNSUPPORTED_AGENT_PROVIDER,
+        message: 'Provider "bad" not supported',
+        details: { provider: 'bad' },
+        role: 'planner',
+      },
+      {
+        code: ERROR_CODES.PROVIDER_AUTH_MISSING,
+        message: 'Provider "claude" requires credentials for role "builder"',
+        details: { provider: 'claude' },
+        role: 'builder',
+      },
+    ];
+    vi.mocked(validateRoleProviderCompatibility).mockReturnValueOnce({
+      valid: false,
+      errors,
+    });
+    const handler = new ResumeCommandHandler();
+    await expect(handler.execute(makeContext(kernel))).rejects.toMatchObject({
+      code: ERROR_CODES.UNSUPPORTED_AGENT_PROVIDER,
+      message: 'Provider "bad" not supported',
+      details: {
+        provider: 'bad',
+        role: 'planner',
+        all_errors: errors,
+      },
+    });
+  });
+
+  it('GIVEN_compatibility_error_with_INVALID_CLI_ARGS_code_WHEN_resume_THEN_throws_with_execution_mode_details', async () => {
+    const kernel = makeKernel({
+      readIndex: vi.fn(async () => ({
+        active: ['feat_mode_err'],
+        blocked: [],
+        blocked_queue: [],
+      })),
+      featureStateGet: vi.fn(async () => ({
+        data: { front_matter: { status: STATUS.PLANNING } },
+      })),
+    });
+    vi.mocked(validateRoleProviderCompatibility).mockReturnValueOnce({
+      valid: false,
+      errors: [
+        {
+          code: ERROR_CODES.INVALID_CLI_ARGS,
+          message:
+            "Provider 'gemini' does not support interactive execution mode for role 'builder'",
+          details: { provider: 'gemini', execution_mode: 'interactive' },
+          role: 'builder',
+        },
+      ],
+    });
+    const handler = new ResumeCommandHandler();
+    const context = makeContext(kernel);
+    context.options = { execution_mode: 'interactive' } as any;
+    await expect(handler.execute(context)).rejects.toMatchObject({
+      code: ERROR_CODES.INVALID_CLI_ARGS,
+      details: {
+        provider: 'gemini',
+        execution_mode: 'interactive',
+        role: 'builder',
+      },
+    });
+  });
+
+  it('GIVEN_policy_with_execution_and_observability_objects_WHEN_resume_THEN_passes_them_to_worker_provider', async () => {
+    const kernel = makeKernel({
+      readIndex: vi.fn(async () => ({
+        active: ['feat_policy'],
+        blocked: [],
+        blocked_queue: [],
+      })),
+      featureStateGet: vi.fn(async () => ({
+        data: { front_matter: { status: STATUS.PLANNING } },
+      })),
+      getPolicySnapshot: vi.fn(() => ({
+        execution: { require_live_provider_for_run: false },
+        observability: { raw_agent_logs_enabled: true },
+      })),
+    });
+    vi.mocked(validateRoleProviderCompatibility).mockReturnValueOnce({
+      valid: true,
+      errors: [],
+    });
+    const handler = new ResumeCommandHandler();
+    const result = (await handler.execute(makeContext(kernel))) as any;
+
+    expect(result.ok).toBe(true);
+    expect(result.data.resumed).toBe(true);
+  });
+
+  it('GIVEN_requested_feature_state_throws_WHEN_resume_with_empty_plan_THEN_falls_through_to_resumed_false', async () => {
+    const kernel = makeKernel({
+      featureStateGet: vi.fn(async () => {
+        throw new Error('state read error');
+      }),
+    });
+    const handler = new ResumeCommandHandler();
+    const context = makeContext(kernel);
+    context.options = { feature_id: 'missing_feature' } as any;
+    const result = (await handler.execute(context)) as any;
+
+    expect(result.ok).toBe(true);
+    expect(result.data.resumed).toBe(false);
+  });
 });