agentic-orchestrator 0.1.2 → 0.1.4

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

@@ -1,14 +1,54 @@
 import path from 'node:path';
-import { describe, expect, it, vi } from 'vitest';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
 import { ERROR_CODES } from '../src/core/error-codes.js';
+import { TOOLS } from '../src/core/constants.js';
 import { CliArgumentParser } from '../src/cli/cli-argument-parser.js';
 import { assertOkResponse, callCliTool } from '../src/cli/tooling.js';
 import { canonicalFeatureIdFromPath, isCanonicalSpecPath, isLegacyCanonicalSpecPath } from '../src/cli/spec-utils.js';
+import { RetryCommandHandler } from '../src/cli/retry-command-handler.js';
+import { StatusCommandHandler } from '../src/cli/status-command-handler.js';
+import { SendCommandHandler } from '../src/cli/send-command-handler.js';
 
 describe('cli helper modules', () => {
   it('GIVEN_empty_argv_or_extended_flags_WHEN_parsing_THEN_handles_defaults_and_all_supported_tokens', () => {
     const parser = new CliArgumentParser();
     expect(parser.parse([])).toEqual({ command: 'run' });
+    // --all, --port, --foreground, --dev, --force, --project, --summary, --auto, --batch, --takeover-stale-run
+    const miscParsed = parser.parse([
+      'status',
+      '--all',
+      '--port',
+      '9090',
+      '--foreground',
+      '--dev',
+      '--force',
+      '--project',
+      'my-project',
+      '--summary',
+      '--auto',
+      '--batch',
+      '--takeover-stale-run',
+      '--message',
+      'hello world'
+    ]);
+    expect(miscParsed).toMatchObject({
+      command: 'status',
+      all: true,
+      port: 9090,
+      foreground: true,
+      dev: true,
+      force: true,
+      project: 'my-project',
+      summary: true,
+      auto: true,
+      batch: true,
+      takeover_stale_run: true,
+      message: 'hello world'
+    });
+    // --port with non-numeric next token (no value consumed)
+    const portNoNum = parser.parse(['run', '--port', '--foreground']);
+    expect(portNoNum.port).toBeUndefined();
+    expect(portNoNum.foreground).toBe(true);
     expect(parser.parse(['-fi', '.aop/features/feature_x/spec.md'])).toMatchObject({
       command: 'run',
       file_input: '.aop/features/feature_x/spec.md'
@@ -53,6 +93,17 @@ describe('cli helper modules', () => {
       remove_worktree: false,
       remove_branch: 'force'
     });
+    const positionalSend = parser.parse(['send', 'feature_positional', 'please rerun qa with latest fixes']);
+    expect(positionalSend).toMatchObject({
+      command: 'send',
+      feature_id: 'feature_positional',
+      message: 'please rerun qa with latest fixes'
+    });
+    const positionalAttach = parser.parse(['attach', 'feature_positional']);
+    expect(positionalAttach).toMatchObject({
+      command: 'attach',
+      feature_id: 'feature_positional'
+    });
     expect(parser.resolveTransport('InProcess')).toBe('inprocess');
     expect(parser.resolveTransport(undefined)).toBe('mcp');
   });
@@ -103,3 +154,355 @@ describe('cli helper modules', () => {
     );
   });
 });
+
+describe('RetryCommandHandler', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('GIVEN_missing_feature_id_WHEN_execute_called_THEN_throws_invalid_cli_args', async () => {
+    const toolClient = { call: vi.fn() };
+    const handler = new RetryCommandHandler(toolClient as never, 'run:test');
+    await expect(handler.execute({ command: 'retry' })).rejects.toMatchObject({
+      code: ERROR_CODES.INVALID_CLI_ARGS
+    });
+  });
+
+  it('GIVEN_invalid_feature_id_slug_WHEN_execute_called_THEN_throws_invalid_cli_args', async () => {
+    const toolClient = { call: vi.fn() };
+    const handler = new RetryCommandHandler(toolClient as never, 'run:test');
+    await expect(
+      handler.execute({ command: 'retry', feature_id: 'INVALID Feature ID' })
+    ).rejects.toMatchObject({ code: ERROR_CODES.INVALID_CLI_ARGS });
+  });
+
+  it('GIVEN_valid_feature_id_no_force_WHEN_execute_called_THEN_runs_retry_gate_without_reset', async () => {
+    const callMock = vi.fn().mockImplementation(async (toolName: string) => {
+      if (toolName === TOOLS.FEATURE_STATE_GET) {
+        return { ok: true, data: { front_matter: { version: 5, status: 'qa' } } };
+      }
+      if (toolName === TOOLS.GATES_RUN) {
+        return { ok: true, data: { overall: 'pass' } };
+      }
+      return { ok: true, data: {} };
+    });
+    const handler = new RetryCommandHandler({ call: callMock } as never, 'run:test');
+    const result = await handler.execute({ command: 'retry', feature_id: 'feature_abc' });
+    expect(result).toMatchObject({
+      ok: true,
+      data: {
+        feature_id: 'feature_abc',
+        retry_count_reset: false,
+        retry_executed: true,
+        retry_mode: 'full',
+        retry_outcome: 'pass'
+      }
+    });
+    expect(callMock).toHaveBeenCalledWith(
+      TOOLS.GATES_RUN,
+      expect.objectContaining({ feature_id: 'feature_abc', mode: 'full' }),
+      expect.any(Object)
+    );
+  });
+
+  it('GIVEN_valid_feature_id_with_force_WHEN_execute_called_THEN_gets_current_state_and_patches_retry_count', async () => {
+    const callMock = vi.fn().mockImplementation(async (toolName: string) => {
+      if (toolName === TOOLS.FEATURE_STATE_GET) {
+        return { ok: true, data: { front_matter: { version: 5 } } };
+      }
+      if (toolName === TOOLS.GATES_RUN) {
+        return { ok: true, data: { overall: 'fail' } };
+      }
+      return { ok: true, data: {} };
+    });
+    const handler = new RetryCommandHandler({ call: callMock } as never, 'run:test');
+    const result = await handler.execute({ command: 'retry', feature_id: 'feature_abc', force: true });
+
+    expect(result).toMatchObject({
+      ok: true,
+      data: { feature_id: 'feature_abc', retry_count_reset: true }
+    });
+    expect(callMock).toHaveBeenCalledWith(
+      TOOLS.FEATURE_STATE_GET,
+      expect.objectContaining({ feature_id: 'feature_abc' }),
+      expect.any(Object)
+    );
+    expect(callMock).toHaveBeenCalledWith(
+      TOOLS.FEATURE_STATE_PATCH,
+      expect.objectContaining({ feature_id: 'feature_abc', expected_version: 5 }),
+      expect.any(Object)
+    );
+    expect(callMock).toHaveBeenCalledWith(
+      TOOLS.GATES_RUN,
+      expect.objectContaining({ feature_id: 'feature_abc' }),
+      expect.any(Object)
+    );
+  });
+});
+
+describe('StatusCommandHandler', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('GIVEN_options_all_with_project_statuses_WHEN_execute_THEN_returns_aggregate', async () => {
+    const toolClient = { call: vi.fn() };
+    const handler = new StatusCommandHandler(toolClient as never, 'run:test');
+    const projectStatuses = [{ name: 'proj1', path: '/path/to/proj1', status: 'ok' }];
+    const result = await handler.execute({ all: true, projectStatuses });
+    expect(result).toMatchObject({ ok: true, data: { projects: projectStatuses } });
+    expect(toolClient.call).not.toHaveBeenCalled();
+  });
+
+  it('GIVEN_summary_mode_WHEN_execute_THEN_returns_summary_with_activity_states', async () => {
+    const recentTs = new Date(Date.now() - 60_000).toISOString();
+    const oldTs = new Date(Date.now() - 600_000).toISOString();
+    const features = [
+      { feature_id: 'no_ts', status: 'planning' },
+      { feature_id: 'recent', status: 'building', last_heartbeat_at: recentTs },
+      { feature_id: 'old_one', status: 'merged', last_run_at: oldTs }
+    ];
+    const toolClient = { call: vi.fn(async () => ({ ok: true, data: { features } })) };
+    const handler = new StatusCommandHandler(toolClient as never, 'run:test');
+    const result = await handler.execute({ summary: true });
+
+    expect(result).toMatchObject({
+      ok: true,
+      data: {
+        summary: [
+          { feature_id: 'no_ts', status: 'planning', activity: 'unknown' },
+          { feature_id: 'recent', status: 'building', activity: 'active' },
+          { feature_id: 'old_one', status: 'merged', activity: 'idle' }
+        ]
+      }
+    });
+  });
+
+  it('GIVEN_features_with_pr_field_WHEN_execute_THEN_adds_pr_info', async () => {
+    const prData = {
+      number: 42,
+      url: 'https://github.com/repo/pull/42',
+      ci_status: 'success',
+      review_decision: 'approved',
+      merge_ready: true,
+      pending_review_threads: 0,
+      has_conflicts: false,
+      merge_score: 100
+    };
+    const features = [{ feature_id: 'feature_a', status: 'review', pr: prData }];
+    const toolClient = { call: vi.fn(async () => ({ ok: true, data: { features } })) };
+    const handler = new StatusCommandHandler(toolClient as never, 'run:test');
+    const result = await handler.execute();
+
+    expect(result).toMatchObject({
+      ok: true,
+      data: {
+        features: [expect.objectContaining({ feature_id: 'feature_a', pr_info: prData })]
+      }
+    });
+  });
+
+  it('GIVEN_features_without_pr_field_WHEN_execute_THEN_no_pr_info_added', async () => {
+    const features = [{ feature_id: 'feature_b', status: 'planning' }];
+    const toolClient = { call: vi.fn(async () => ({ ok: true, data: { features } })) };
+    const handler = new StatusCommandHandler(toolClient as never, 'run:test');
+    const result = await handler.execute();
+
+    const data = (result as { ok: boolean; data: { features: Record<string, unknown>[] } }).data;
+    expect(data.features[0]).not.toHaveProperty('pr_info');
+  });
+});
+
+describe('SendCommandHandler', () => {
+  it('GIVEN_invalid_feature_id_WHEN_send_executed_THEN_throws_invalid_cli_args', async () => {
+    const toolClient = { call: vi.fn() };
+    const handler = new SendCommandHandler(toolClient as never, 'run:test');
+    await expect(
+      handler.execute({ command: 'send', feature_id: 'INVALID Feature ID', message: 'hello' })
+    ).rejects.toMatchObject({ code: ERROR_CODES.INVALID_CLI_ARGS });
+  });
+});
+
+describe('RetryCommandHandler branch coverage', () => {
+  it('GIVEN_feature_in_merged_status_without_force_WHEN_execute_called_THEN_throws_invalid_cli_args', async () => {
+    const callMock = vi.fn().mockImplementation(async (toolName: string) => {
+      if (toolName === TOOLS.FEATURE_STATE_GET) {
+        return { ok: true, data: { front_matter: { version: 1, status: 'merged' } } };
+      }
+      return { ok: true, data: {} };
+    });
+    const handler = new RetryCommandHandler({ call: callMock } as never, 'run:test');
+    await expect(
+      handler.execute({ command: 'retry', feature_id: 'feature_x' })
+    ).rejects.toMatchObject({ code: ERROR_CODES.INVALID_CLI_ARGS });
+  });
+
+  it('GIVEN_feature_blocked_with_forced_retry_fast_reason_WHEN_execute_called_THEN_infers_fast_mode', async () => {
+    const callMock = vi.fn().mockImplementation(async (toolName: string) => {
+      if (toolName === TOOLS.FEATURE_STATE_GET) {
+        return { ok: true, data: { front_matter: { version: 2, status: 'blocked', status_reason: 'forced_retry:fast' } } };
+      }
+      if (toolName === TOOLS.GATES_RUN) {
+        return { ok: true, data: { overall: 'pass' } };
+      }
+      return { ok: true, data: {} };
+    });
+    const handler = new RetryCommandHandler({ call: callMock } as never, 'run:test');
+    const result = await handler.execute({ command: 'retry', feature_id: 'feature_y', force: true }) as Record<string, unknown>;
+    const data = result.data as Record<string, unknown>;
+    expect(data.retry_mode).toBe('fast');
+  });
+
+  it('GIVEN_feature_blocked_with_force_and_last_gate_mode_full_WHEN_execute_called_THEN_patches_status_to_qa', async () => {
+    const callMock = vi.fn().mockImplementation(async (toolName: string) => {
+      if (toolName === TOOLS.FEATURE_STATE_GET) {
+        return { ok: true, data: { front_matter: { version: 3, status: 'blocked', evidence: { last_gate_mode: 'full' } } } };
+      }
+      if (toolName === TOOLS.GATES_RUN) {
+        return { ok: true, data: { overall: 'pass' } };
+      }
+      return { ok: true, data: {} };
+    });
+    const handler = new RetryCommandHandler({ call: callMock } as never, 'run:test');
+    const result = await handler.execute({ command: 'retry', feature_id: 'feature_z', force: true }) as Record<string, unknown>;
+    const data = result.data as Record<string, unknown>;
+    expect(data.retry_mode).toBe('full');
+    expect(data.forced_retry_executed).toBe(true);
+    // verify patch was called with status qa
+    expect(callMock).toHaveBeenCalledWith(
+      TOOLS.FEATURE_STATE_PATCH,
+      expect.objectContaining({ patch: expect.objectContaining({ front_matter: expect.objectContaining({ status: 'qa' }) }) }),
+      expect.any(Object)
+    );
+  });
+
+  it('GIVEN_feature_blocked_with_force_and_merge_gate_mode_WHEN_execute_called_THEN_patches_status_to_ready_to_merge', async () => {
+    const callMock = vi.fn().mockImplementation(async (toolName: string) => {
+      if (toolName === TOOLS.FEATURE_STATE_GET) {
+        return { ok: true, data: { front_matter: { version: 4, status: 'blocked', evidence: { last_gate_mode: 'merge' } } } };
+      }
+      if (toolName === TOOLS.GATES_RUN) {
+        return { ok: true, data: { overall: 'pass' } };
+      }
+      return { ok: true, data: {} };
+    });
+    const handler = new RetryCommandHandler({ call: callMock } as never, 'run:test');
+    const result = await handler.execute({ command: 'retry', feature_id: 'feature_m', force: true }) as Record<string, unknown>;
+    const data = result.data as Record<string, unknown>;
+    expect(data.retry_mode).toBe('merge');
+    expect(callMock).toHaveBeenCalledWith(
+      TOOLS.FEATURE_STATE_PATCH,
+      expect.objectContaining({ patch: expect.objectContaining({ front_matter: expect.objectContaining({ status: 'ready_to_merge' }) }) }),
+      expect.any(Object)
+    );
+  });
+});
+
+describe('HelpCommandHandler', () => {
+  it('GIVEN_no_subcommand_WHEN_execute_called_THEN_returns_full_help_text', async () => {
+    const { HelpCommandHandler } = await import('../src/cli/help-command-handler.js');
+    const handler = new HelpCommandHandler();
+    const result = handler.execute();
+    expect(result.ok).toBe(true);
+    expect(result.data.help).toContain('aop — Agentic Orchestrator');
+    expect(result.data.help).toContain('Commands:');
+    expect(result.data.help).toContain('run');
+    expect(result.data.help).toContain('status');
+  });
+
+  it('GIVEN_valid_subcommand_WHEN_execute_called_THEN_returns_detailed_help_for_command', async () => {
+    const { HelpCommandHandler } = await import('../src/cli/help-command-handler.js');
+    const handler = new HelpCommandHandler();
+    const result = handler.execute('run');
+    expect(result.ok).toBe(true);
+    expect(result.data.help).toContain('Usage: aop run');
+    expect(result.data.help).toContain('Flags:');
+  });
+
+  it('GIVEN_unknown_subcommand_WHEN_execute_called_THEN_returns_full_help_text', async () => {
+    const { HelpCommandHandler } = await import('../src/cli/help-command-handler.js');
+    const handler = new HelpCommandHandler();
+    const result = handler.execute('nonexistent');
+    expect(result.ok).toBe(true);
+    expect(result.data.help).toContain('Commands:');
+  });
+
+  it('GIVEN_command_without_flags_WHEN_execute_called_THEN_renders_without_flags_section', async () => {
+    const { HelpCommandHandler } = await import('../src/cli/help-command-handler.js');
+    const handler = new HelpCommandHandler();
+    const result = handler.execute('stop');
+    expect(result.ok).toBe(true);
+    expect(result.data.help).toContain('Usage: aop stop');
+    // stop has no flags
+    expect(result.data.help).not.toContain('Flags:');
+  });
+});
+
+describe('StatusCommandHandler feature with no timestamp', () => {
+  it('GIVEN_feature_with_no_timestamp_fields_WHEN_summary_THEN_activity_is_unknown', async () => {
+    const features = [
+      { feature_id: 'feat_no_ts', status: 'planning' }
+    ];
+    const toolClient = { call: vi.fn(async () => ({ ok: true, data: { features } })) };
+    const handler = new StatusCommandHandler(toolClient as never, 'run:test');
+    const result = await handler.execute({ summary: true }) as any;
+    expect(result.ok).toBe(true);
+    const found = result.data.summary.find((f: any) => f.feature_id === 'feat_no_ts');
+    expect(found?.activity).toBe('unknown');
+  });
+});
+
+describe('StatusCommandHandler explicit activity_state branches', () => {
+  it('GIVEN_features_with_idle_and_waiting_input_states_WHEN_summary_THEN_returns_correct_activity', async () => {
+    const toolClient = {
+      call: vi.fn(async () => ({
+        ok: true,
+        data: {
+          features: [
+            { feature_id: 'feat_idle', status: 'building', activity_state: 'idle' },
+            { feature_id: 'feat_waiting', status: 'building', activity_state: 'waiting_input' },
+            { feature_id: 'feat_blocked', status: 'blocked', activity_state: 'blocked' },
+            { feature_id: 'feat_exited', status: 'failed', activity_state: 'exited' }
+          ]
+        }
+      }))
+    };
+    const handler = new StatusCommandHandler(toolClient as never, 'run:test');
+    const result = await handler.execute({ summary: true }) as any;
+    expect(result.ok).toBe(true);
+    const idle = result.data.summary.find((f: any) => f.feature_id === 'feat_idle');
+    expect(idle?.activity).toBe('idle');
+    const waiting = result.data.summary.find((f: any) => f.feature_id === 'feat_waiting');
+    expect(waiting?.activity).toBe('waiting_input');
+  });
+
+  it('GIVEN_feature_with_pr_field_WHEN_execute_without_summary_THEN_includes_pr_info', async () => {
+    const toolClient = {
+      call: vi.fn(async () => ({
+        ok: true,
+        data: {
+          features: [
+            {
+              feature_id: 'feat_pr',
+              status: 'ready_to_merge',
+              pr: {
+                number: 42,
+                url: 'https://github.com/pr/42',
+                ci_status: 'pass',
+                review_decision: 'approved',
+                merge_ready: true,
+                pending_review_threads: 0,
+                has_conflicts: false,
+                merge_score: 1
+              }
+            }
+          ]
+        }
+      }))
+    };
+    const handler = new StatusCommandHandler(toolClient as never, 'run:test');
+    const result = await handler.execute({}) as any;
+    expect(result.ok).toBe(true);
+    expect(result.data.features[0].pr_info.number).toBe(42);
+  });
+});

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

@@ -3,7 +3,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { ERROR_CODES } from '../src/core/error-codes.js';
-import { TOOLS } from '../src/core/constants.js';
+import { STATUS, TOOLS } from '../src/core/constants.js';
 
 const ensureLoadedMock = vi.hoisted(() => vi.fn(async () => undefined));
 const recoverFromStateMock = vi.hoisted(
@@ -606,4 +606,185 @@ describe('aop CLI unit', () => {
       }
     });
   });
+
+  it('GIVEN_resume_with_BUILDING_status_WHEN_main_runs_THEN_resumes_in_building_phase', async () => {
+    featureStateGetMock.mockResolvedValue({ data: { front_matter: { status: STATUS.BUILDING } } });
+    const code = await main(['resume'], { cwd, env: {} as NodeJS.ProcessEnv });
+    const writes = asJsonWrites(stdoutSpy);
+    expect(code).toBe(0);
+    expect(writes[0]).toMatchObject({
+      ok: true,
+      data: { resumed: true, resumed_features: [expect.objectContaining({ resume_phase: STATUS.BUILDING })] }
+    });
+  });
+
+  it('GIVEN_resume_with_QA_status_WHEN_main_runs_THEN_resumes_in_qa_phase', async () => {
+    featureStateGetMock.mockResolvedValue({ data: { front_matter: { status: STATUS.QA } } });
+    const code = await main(['resume'], { cwd, env: {} as NodeJS.ProcessEnv });
+    const writes = asJsonWrites(stdoutSpy);
+    expect(code).toBe(0);
+    expect(writes[0]).toMatchObject({
+      ok: true,
+      data: { resumed_features: [expect.objectContaining({ resume_phase: STATUS.QA })] }
+    });
+  });
+
+  it('GIVEN_resume_with_READY_TO_MERGE_status_WHEN_main_runs_THEN_resumes_in_ready_to_merge_phase', async () => {
+    featureStateGetMock.mockResolvedValue({ data: { front_matter: { status: STATUS.READY_TO_MERGE } } });
+    const code = await main(['resume'], { cwd, env: {} as NodeJS.ProcessEnv });
+    const writes = asJsonWrites(stdoutSpy);
+    expect(code).toBe(0);
+    expect(writes[0]).toMatchObject({
+      ok: true,
+      data: { resumed_features: [expect.objectContaining({ resume_phase: STATUS.READY_TO_MERGE })] }
+    });
+  });
+
+  it('GIVEN_feature_with_MERGED_status_WHEN_resume_runs_THEN_filters_terminal_feature_and_returns_resumed_false', async () => {
+    featureStateGetMock.mockResolvedValue({ data: { front_matter: { status: STATUS.MERGED } } });
+    const code = await main(['resume'], { cwd, env: {} as NodeJS.ProcessEnv });
+    const writes = asJsonWrites(stdoutSpy);
+    expect(code).toBe(0);
+    expect(writes[0]).toMatchObject({ ok: true, data: { resumed: false } });
+  });
+
+  it('GIVEN_feature_with_FAILED_status_WHEN_resume_runs_THEN_filters_terminal_feature', async () => {
+    featureStateGetMock.mockResolvedValue({ data: { front_matter: { status: STATUS.FAILED } } });
+    const code = await main(['resume'], { cwd, env: {} as NodeJS.ProcessEnv });
+    const writes = asJsonWrites(stdoutSpy);
+    expect(code).toBe(0);
+    expect(writes[0]).toMatchObject({ ok: true, data: { resumed: false } });
+  });
+
+  it('GIVEN_feature_state_throws_WHEN_resume_builds_plan_THEN_silently_skips_broken_feature', async () => {
+    featureStateGetMock.mockRejectedValue(new Error('parse error'));
+    const code = await main(['resume'], { cwd, env: {} as NodeJS.ProcessEnv });
+    const writes = asJsonWrites(stdoutSpy);
+    expect(code).toBe(0);
+    expect(writes[0]).toMatchObject({ ok: true, data: { resumed: false } });
+  });
+
+  it('GIVEN_runtimeSessions_has_feature_sessions_WHEN_resume_builds_plan_THEN_includes_session_features', async () => {
+    getRuntimeSessionsMock.mockResolvedValue({
+      run_id: 'run:from-sessions',
+      owner_instance_id: 'owner:from-sessions',
+      feature_sessions: { feature_resume: { planner: 'p1', builder: 'b1', qa: 'q1' } }
+    });
+    featureDiscoverSpecsMock.mockResolvedValue({ data: { specs: [] } });
+    readIndexMock.mockResolvedValue({ version: 1, active: [], blocked: [], blocked_queue: [] });
+    featureStateGetMock.mockResolvedValue({ data: { front_matter: { status: STATUS.BUILDING } } });
+
+    const code = await main(['resume'], { cwd, env: {} as NodeJS.ProcessEnv });
+    const writes = asJsonWrites(stdoutSpy);
+    expect(code).toBe(0);
+    expect(writes[0]).toMatchObject({
+      ok: true,
+      data: { resumed: true, resumed_features: [expect.objectContaining({ feature_id: 'feature_resume' })] }
+    });
+  });
+
+  it('GIVEN_index_has_blocked_queue_entry_WHEN_resume_builds_plan_THEN_includes_blocked_queue_feature', async () => {
+    readIndexMock.mockResolvedValue({
+      version: 1,
+      active: [],
+      blocked: [],
+      blocked_queue: [{ feature_id: 'feature_queued' }]
+    });
+    getRuntimeSessionsMock.mockResolvedValue({
+      run_id: 'none',
+      owner_instance_id: 'none',
+      feature_sessions: {}
+    });
+    featureDiscoverSpecsMock.mockResolvedValue({ data: { specs: [] } });
+    featureStateGetMock.mockResolvedValue({ data: { front_matter: { status: STATUS.PLANNING } } });
+
+    const code = await main(['resume'], { cwd, env: {} as NodeJS.ProcessEnv });
+    const writes = asJsonWrites(stdoutSpy);
+    expect(code).toBe(0);
+    expect(writes[0]).toMatchObject({ ok: true, data: { resumed: true } });
+  });
+
+  it('GIVEN_index_has_blocked_feature_WHEN_resume_builds_plan_THEN_includes_blocked_feature', async () => {
+    readIndexMock.mockResolvedValue({
+      version: 1,
+      active: [],
+      blocked: ['feature_blocked'],
+      blocked_queue: []
+    });
+    getRuntimeSessionsMock.mockResolvedValue({ run_id: 'none', owner_instance_id: 'none', feature_sessions: {} });
+    featureDiscoverSpecsMock.mockResolvedValue({ data: { specs: [] } });
+    featureStateGetMock.mockResolvedValue({ data: { front_matter: { status: STATUS.PLANNING } } });
+
+    const code = await main(['resume'], { cwd, env: {} as NodeJS.ProcessEnv });
+    expect(code).toBe(0);
+  });
+
+  it('GIVEN_multiple_features_in_different_phases_WHEN_resume_runs_THEN_sorted_by_phase_rank', async () => {
+    readIndexMock.mockResolvedValue({
+      version: 1,
+      active: ['feature_a', 'feature_b'],
+      blocked: [],
+      blocked_queue: []
+    });
+    getRuntimeSessionsMock.mockResolvedValue({ run_id: 'none', owner_instance_id: 'none', feature_sessions: {} });
+    featureDiscoverSpecsMock.mockResolvedValue({ data: { specs: [] } });
+    featureStateGetMock.mockImplementation(async (featureId?: string) => {
+      if (featureId === 'feature_a') {
+        return { data: { front_matter: { status: STATUS.QA } } };
+      }
+      return { data: { front_matter: { status: STATUS.PLANNING } } };
+    });
+
+    const code = await main(['resume'], { cwd, env: {} as NodeJS.ProcessEnv });
+    const writes = asJsonWrites(stdoutSpy);
+    expect(code).toBe(0);
+    const features = writes[0].data.resumed_features as Array<{ feature_id: string }>;
+    // PLANNING (rank 0) should come before QA (rank 2)
+    expect(features[0].feature_id).toBe('feature_b');
+    expect(features[1].feature_id).toBe('feature_a');
+  });
+
+  it('GIVEN_batch_flag_with_folder_input_WHEN_run_command_THEN_executes_batch_mode', async () => {
+    const incoming = path.join(cwd, 'batch_folder');
+    await fs.mkdir(incoming, { recursive: true });
+    await fs.writeFile(path.join(incoming, 'batch_feature.md'), '# Batch\n', 'utf8');
+
+    toolCallMock.mockResolvedValue({ ok: true, data: {} });
+
+    const code = await main(['run', '-fl', 'batch_folder', '--batch'], { cwd, env: {} as NodeJS.ProcessEnv });
+    const writes = asJsonWrites(stdoutSpy);
+    expect(code).toBe(0);
+    expect(writes[0]).toMatchObject({ ok: true, data: { command: 'batch-run', created: 1 } });
+  });
+
+  it('GIVEN_batch_mode_with_already_active_feature_WHEN_run_command_THEN_skips_it', async () => {
+    const incoming = path.join(cwd, 'batch_folder2');
+    await fs.mkdir(incoming, { recursive: true });
+    await fs.writeFile(path.join(incoming, 'existing_feature.md'), '# Existing\n', 'utf8');
+
+    // Write an index that marks this feature as already active
+    const indexDir = path.join(cwd, '.aop', 'features');
+    await fs.mkdir(indexDir, { recursive: true });
+    await fs.writeFile(path.join(indexDir, 'index.json'), JSON.stringify({ active: ['existing_feature'] }), 'utf8');
+
+    toolCallMock.mockResolvedValue({ ok: true, data: {} });
+
+    const code = await main(['run', '-fl', 'batch_folder2', '--batch'], { cwd, env: {} as NodeJS.ProcessEnv });
+    const writes = asJsonWrites(stdoutSpy);
+    expect(code).toBe(0);
+    expect(writes[0]).toMatchObject({ ok: true, data: { command: 'batch-run', skipped: 1, created: 0 } });
+  });
+
+  it('GIVEN_batch_mode_with_init_failure_WHEN_run_command_THEN_counts_as_failed', async () => {
+    const incoming = path.join(cwd, 'batch_folder3');
+    await fs.mkdir(incoming, { recursive: true });
+    await fs.writeFile(path.join(incoming, 'fail_feature.md'), '# Fail\n', 'utf8');
+
+    toolCallMock.mockRejectedValue(new Error('init failure'));
+
+    const code = await main(['run', '-fl', 'batch_folder3', '--batch'], { cwd, env: {} as NodeJS.ProcessEnv });
+    const writes = asJsonWrites(stdoutSpy);
+    expect(code).toBe(0);
+    expect(writes[0]).toMatchObject({ ok: true, data: { command: 'batch-run', failed: 1 } });
+  });
 });