agentic-orchestrator 0.1.28 → 0.2.1

package/apps/control-plane/test/dashboard-runtime-runner.spec.ts

@@ -0,0 +1,1550 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+const mergeExecuteMock = vi.hoisted(() => vi.fn());
+const resumeExecuteMock = vi.hoisted(() => vi.fn());
+const toolClientCallMock = vi.hoisted(() => vi.fn());
+const supervisorStartMock = vi.hoisted(() => vi.fn());
+const kernelRuntimeSessionsMock = vi.hoisted(() => vi.fn());
+const kernelIsRunLeaseFreshMock = vi.hoisted(() => vi.fn((_value?: unknown) => false));
+const kernelFeatureStateGetMock = vi.hoisted(() => vi.fn());
+const kernelRedrivePreparedConflictMock = vi.hoisted(() =>
+  vi.fn(async (_featureId: string) => false),
+);
+
+vi.mock('../src/core/kernel.js', () => ({
+  AopKernel: class AopKernel {
+    async ensureLoaded() {
+      return undefined;
+    }
+
+    getAgentsConfig() {
+      return {};
+    }
+
+    getPolicySnapshot() {
+      return {};
+    }
+
+    async getRuntimeSessions() {
+      return await kernelRuntimeSessionsMock();
+    }
+
+    async featureStateGet(featureId: string) {
+      return await kernelFeatureStateGetMock(featureId);
+    }
+
+    isRunLeaseFresh(value: unknown) {
+      return kernelIsRunLeaseFreshMock(value);
+    }
+
+    async redrivePreparedReconcilerConflict(featureId: string) {
+      return await kernelRedrivePreparedConflictMock(featureId);
+    }
+
+    setProvider() {
+      // no-op in tests
+    }
+  },
+}));
+
+vi.mock('../src/mcp/runtime-factory.js', () => ({
+  createToolingRuntime: vi.fn(async () => ({})),
+  resolveToolClient: vi.fn(() => ({ call: toolClientCallMock })),
+}));
+
+vi.mock('../src/providers/providers.js', () => ({
+  NullWorkerProvider: class NullWorkerProvider {
+    constructor(_selection: unknown) {
+      // no-op in tests
+    }
+  },
+  resolveProviderSelection: vi.fn(() => ({
+    provider: 'codex',
+    model: 'gpt-5.4',
+    provider_config_env: null,
+    provider_config_ref: null,
+  })),
+  resolveProviderSelectionsByRole: vi.fn(() => ({})),
+}));
+
+vi.mock('../src/providers/worker-provider-factory.js', () => ({
+  DefaultWorkerProviderFactory: class DefaultWorkerProviderFactory {
+    create() {
+      return {
+        selection: {
+          provider: 'codex',
+          model: 'gpt-5.4',
+          provider_config_env: null,
+          provider_config_ref: null,
+        },
+      };
+    }
+  },
+  resolveWorkerProviderMode: vi.fn(() => 'live'),
+  resolveWorkerProviderObservability: vi.fn(() => ({})),
+  resolveWorkerProviderPolicy: vi.fn(() => ({})),
+  resolveWorkerProviderRuntime: vi.fn(() => ({})),
+  resolvePromptOverlayDir: vi.fn(
+    (repoRoot: string) => `${repoRoot}/config/agentic/orchestrator/prompts/overrides`,
+  ),
+}));
+
+vi.mock('../src/supervisor/runtime.js', () => ({
+  SupervisorRuntime: class SupervisorRuntime {
+    async start(features: Array<{ feature_id: string }>) {
+      return await supervisorStartMock(features);
+    }
+  },
+}));
+
+vi.mock('../src/cli/merge-command-handler.js', () => ({
+  MergeCommandHandler: class MergeCommandHandler {
+    async execute() {
+      return await mergeExecuteMock();
+    }
+  },
+}));
+
+vi.mock('../src/cli/resume-command-handler.js', () => ({
+  ResumeCommandHandler: class ResumeCommandHandler {
+    async execute() {
+      return await resumeExecuteMock();
+    }
+  },
+}));
+
+import {
+  buildReconcilerHandoffResponse,
+  buildResumeAcceptedResponse,
+  buildRuntimeBusyResponse,
+  DashboardRuntimeRunner,
+} from '../src/cli/dashboard-runtime-runner.js';
+
+describe('dashboard runtime runner helpers', () => {
+  it('builds runtime handoff responses for resume submission', () => {
+    expect(
+      buildResumeAcceptedResponse({
+        featureId: 'feature_a',
+        started: true,
+        alreadyRunning: false,
+      }),
+    ).toEqual({
+      ok: true,
+      data: {
+        command: 'resume',
+        feature_id: 'feature_a',
+        handoff_started: true,
+        handoff_target: 'runtime',
+        started: true,
+        already_running: false,
+      },
+    });
+  });
+
+  it('builds reconciler handoff responses from merge conflicts', () => {
+    expect(
+      buildReconcilerHandoffResponse(
+        'feature_a',
+        {
+          ok: false,
+          error: {
+            code: 'reconciliation_failed',
+            message: 'Merge requires reconciler intervention before it can continue',
+          },
+        },
+        {
+          attempted: true,
+          started: true,
+          already_running: false,
+          feature_id: 'feature_a',
+        },
+      ),
+    ).toEqual({
+      ok: true,
+      data: {
+        feature_id: 'feature_a',
+        handoff_started: true,
+        handoff_target: 'reconciler',
+        merge: {
+          ok: false,
+          error: {
+            code: 'reconciliation_failed',
+            message: 'Merge requires reconciler intervention before it can continue',
+          },
+        },
+        auto_resume: {
+          attempted: true,
+          started: true,
+          already_running: false,
+          feature_id: 'feature_a',
+        },
+      },
+    });
+  });
+
+  it('builds a busy response when another background resume is active', () => {
+    expect(buildRuntimeBusyResponse('feature_busy')).toEqual({
+      ok: false,
+      error: {
+        code: 'dashboard_runtime_busy',
+        message: 'Dashboard runtime is busy resuming feature_busy',
+        details: {
+          active_command: 'feature.resume',
+          active_feature_id: 'feature_busy',
+          retryable: true,
+          requires_human: false,
+        },
+      },
+    });
+  });
+
+  it('waitForIdle returns immediately when no background task is running', async () => {
+    const runner = new DashboardRuntimeRunner({
+      repoRoot: '/repo',
+      instanceId: 'instance123456',
+      env: process.env,
+    });
+
+    await expect(runner.waitForIdle()).resolves.toBeUndefined();
+  });
+});
+
+describe('DashboardRuntimeRunner.handleCommand', () => {
+  let repoRoot: string;
+
+  beforeEach(async () => {
+    repoRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'aop-dashboard-runtime-runner-'));
+  });
+
+  beforeEach(() => {
+    mergeExecuteMock.mockReset();
+    resumeExecuteMock.mockReset();
+    toolClientCallMock.mockReset();
+    supervisorStartMock.mockReset();
+    kernelRuntimeSessionsMock.mockReset();
+    kernelIsRunLeaseFreshMock.mockReset();
+    kernelFeatureStateGetMock.mockReset();
+    kernelRedrivePreparedConflictMock.mockReset();
+    kernelIsRunLeaseFreshMock.mockReturnValue(false);
+    kernelRedrivePreparedConflictMock.mockResolvedValue(false);
+    kernelRuntimeSessionsMock.mockResolvedValue({
+      run_id: 'none',
+      owner_instance_id: 'none',
+    });
+    kernelFeatureStateGetMock.mockResolvedValue({
+      data: {
+        front_matter: {},
+      },
+    });
+  });
+
+  afterEach(async () => {
+    await fs.rm(repoRoot, { recursive: true, force: true });
+  });
+
+  it('passes successful merge results through unchanged', async () => {
+    mergeExecuteMock.mockResolvedValue({
+      ok: true,
+      data: {
+        command: 'merge',
+        reconciliation_status: 'merged',
+      },
+    });
+    const runner = new DashboardRuntimeRunner({
+      repoRoot,
+      instanceId: 'instance123456',
+      env: process.env,
+    });
+
+    await expect(
+      runner.handleCommand({
+        command: 'review.approve',
+        feature_id: 'feature_a',
+        args: {
+          approval_token: 'approved',
+          merge_strategy: 'merge_commit',
+          commit_message: 'merge feature_a',
+        },
+      }),
+    ).resolves.toEqual({
+      ok: true,
+      data: {
+        command: 'merge',
+        reconciliation_status: 'merged',
+      },
+    });
+  });
+
+  it('returns an invalid-response envelope when a merge command returns a malformed payload', async () => {
+    mergeExecuteMock.mockResolvedValue('malformed');
+    const runner = new DashboardRuntimeRunner({
+      repoRoot,
+      instanceId: 'instance123456',
+      env: process.env,
+    });
+
+    await expect(
+      runner.handleCommand({
+        command: 'review.approve',
+        feature_id: 'feature_a',
+        args: {
+          approval_token: 'approved',
+        },
+      }),
+    ).resolves.toEqual({
+      ok: false,
+      error: {
+        code: 'dashboard_runtime_invalid_response',
+        message: 'Dashboard runtime command returned an invalid response envelope',
+      },
+    });
+  });
+
+  it('returns a reconciler handoff when the merge conflict is already dispatched', async () => {
+    mergeExecuteMock.mockResolvedValue({
+      ok: false,
+      error: {
+        code: 'reconciliation_failed',
+        message: 'Merge requires reconciler intervention before it can continue',
+        details: {
+          conflict_worktree_prepared: true,
+          dispatched_to_reconciler: true,
+        },
+      },
+    });
+    const runner = new DashboardRuntimeRunner({
+      repoRoot,
+      instanceId: 'instance123456',
+      env: process.env,
+    });
+
+    const result = await runner.handleCommand({
+      command: 'review.approve',
+      feature_id: 'feature_a',
+      args: {
+        approval_token: 'approved',
+        merge_strategy: 'merge_commit',
+      },
+    });
+
+    expect(result.ok).toBe(true);
+    expect(result.data?.handoff_started).toBe(true);
+    expect(result.data?.handoff_target).toBe('reconciler');
+    expect(result.data?.auto_resume).toEqual({
+      attempted: false,
+      started: false,
+      already_running: false,
+      feature_id: 'feature_a',
+    });
+  });
+
+  it('redrives the prepared reconciler assignment immediately when an active run is already available', async () => {
+    kernelRuntimeSessionsMock.mockResolvedValue({
+      run_id: 'run:active',
+      owner_instance_id: 'owner:active',
+    });
+    kernelIsRunLeaseFreshMock.mockReturnValue(true);
+    kernelRedrivePreparedConflictMock.mockResolvedValue(true);
+    mergeExecuteMock.mockResolvedValue({
+      ok: false,
+      error: {
+        code: 'reconciliation_failed',
+        message: 'Merge requires reconciler intervention before it can continue',
+        details: {
+          conflict_worktree_prepared: true,
+          dispatched_to_reconciler: false,
+        },
+      },
+    });
+
+    const runner = new DashboardRuntimeRunner({
+      repoRoot,
+      instanceId: 'instance123456',
+      env: process.env,
+    });
+
+    const result = await runner.handleCommand({
+      command: 'review.approve',
+      feature_id: 'feature_a',
+      args: {
+        approval_token: 'approved',
+      },
+    });
+
+    expect(result.ok).toBe(true);
+    expect(result.data?.handoff_target).toBe('reconciler');
+    expect(result.data?.auto_resume).toEqual({
+      attempted: false,
+      started: false,
+      already_running: false,
+      feature_id: 'feature_a',
+    });
+    expect(result.data?.merge).toEqual({
+      ok: false,
+      error: {
+        code: 'reconciliation_failed',
+        message: 'Merge requires reconciler intervention before it can continue',
+        details: {
+          conflict_worktree_prepared: true,
+          dispatched_to_reconciler: true,
+        },
+      },
+    });
+    expect(kernelRedrivePreparedConflictMock).toHaveBeenCalledWith('feature_a');
+    expect(resumeExecuteMock).not.toHaveBeenCalled();
+  });
+
+  it('treats the dashboard-owned run as active when the lease expiry is stale but the heartbeat is recent', async () => {
+    kernelRuntimeSessionsMock.mockResolvedValue({
+      run_id: 'run:active',
+      owner_instance_id: 'instance123456',
+      last_heartbeat_at: new Date(Date.now() - 30_000).toISOString(),
+    });
+    kernelIsRunLeaseFreshMock.mockReturnValue(false);
+    kernelRedrivePreparedConflictMock.mockResolvedValue(true);
+    mergeExecuteMock.mockResolvedValue({
+      ok: false,
+      error: {
+        code: 'reconciliation_failed',
+        message: 'Merge requires reconciler intervention before it can continue',
+        details: {
+          conflict_worktree_prepared: true,
+          dispatched_to_reconciler: false,
+        },
+      },
+    });
+
+    const runner = new DashboardRuntimeRunner({
+      repoRoot,
+      instanceId: 'instance123456',
+      env: process.env,
+    });
+
+    const result = await runner.handleCommand({
+      command: 'review.approve',
+      feature_id: 'feature_a',
+      args: {
+        approval_token: 'approved',
+      },
+    });
+
+    expect(result.ok).toBe(true);
+    expect(result.data?.handoff_target).toBe('reconciler');
+    expect(result.data?.auto_resume).toEqual({
+      attempted: false,
+      started: false,
+      already_running: false,
+      feature_id: 'feature_a',
+    });
+    expect(kernelRedrivePreparedConflictMock).toHaveBeenCalledWith('feature_a');
+    expect(resumeExecuteMock).not.toHaveBeenCalled();
+  });
+
+  it('does not treat the dashboard-owned run as active when its heartbeat is stale', async () => {
+    kernelRuntimeSessionsMock.mockResolvedValue({
+      run_id: 'run:active',
+      owner_instance_id: 'instance123456',
+      last_heartbeat_at: new Date(Date.now() - 180_000).toISOString(),
+    });
+    kernelIsRunLeaseFreshMock.mockReturnValue(false);
+    mergeExecuteMock.mockResolvedValue({
+      ok: false,
+      error: {
+        code: 'reconciliation_failed',
+        message: 'Merge requires reconciler intervention before it can continue',
+        details: {
+          conflict_worktree_prepared: true,
+          dispatched_to_reconciler: false,
+        },
+      },
+    });
+    resumeExecuteMock.mockResolvedValue({
+      ok: true,
+      data: {
+        command: 'resume',
+      },
+    });
+
+    const runner = new DashboardRuntimeRunner({
+      repoRoot,
+      instanceId: 'instance123456',
+      env: process.env,
+    });
+
+    const result = await runner.handleCommand({
+      command: 'review.approve',
+      feature_id: 'feature_a',
+      args: {
+        approval_token: 'approved',
+      },
+    });
+
+    expect(result.ok).toBe(true);
+    expect(result.data?.auto_resume).toEqual({
+      attempted: true,
+      started: true,
+      already_running: false,
+      feature_id: 'feature_a',
+    });
+    // Resume now always does best-effort redrive regardless of conflict state
+    await runner.waitForIdle();
+  });
+
+  it('starts a background resume when the merge conflict needs reconciler startup', async () => {
+    mergeExecuteMock.mockResolvedValue({
+      ok: false,
+      error: {
+        code: 'reconciliation_failed',
+        message: 'Merge requires reconciler intervention before it can continue',
+        details: {
+          conflict_worktree_prepared: true,
+          dispatched_to_reconciler: false,
+        },
+      },
+    });
+    resumeExecuteMock.mockResolvedValue({
+      ok: true,
+      data: {
+        command: 'resume',
+      },
+    });
+    const runner = new DashboardRuntimeRunner({
+      repoRoot,
+      instanceId: 'instance123456',
+      env: process.env,
+    });
+
+    const result = await runner.handleCommand({
+      command: 'review.approve',
+      feature_id: 'feature_a',
+      args: {
+        approval_token: 'approved',
+      },
+    });
+
+    expect(result.ok).toBe(true);
+    expect(result.data?.handoff_started).toBe(true);
+    expect(result.data?.auto_resume).toEqual({
+      attempted: true,
+      started: true,
+      already_running: false,
+      feature_id: 'feature_a',
+    });
+    await runner.waitForIdle();
+    expect(kernelRedrivePreparedConflictMock).toHaveBeenCalledWith('feature_a');
+  });
+
+  it('returns a reconciliation failure when an active run cannot redrive a prepared conflict', async () => {
+    kernelRuntimeSessionsMock.mockResolvedValue({
+      run_id: 'run:active',
+      owner_instance_id: 'owner:active',
+    });
+    kernelIsRunLeaseFreshMock.mockReturnValue(true);
+    kernelRedrivePreparedConflictMock.mockResolvedValue(false);
+    mergeExecuteMock.mockResolvedValue({
+      ok: false,
+      error: {
+        code: 'reconciliation_failed',
+        message: 'Merge requires reconciler intervention before it can continue',
+        details: {
+          conflict_worktree_prepared: true,
+          dispatched_to_reconciler: false,
+        },
+      },
+    });
+
+    const runner = new DashboardRuntimeRunner({
+      repoRoot,
+      instanceId: 'instance123456',
+      env: process.env,
+    });
+
+    await expect(
+      runner.handleCommand({
+        command: 'review.approve',
+        feature_id: 'feature_a',
+        args: {
+          approval_token: 'approved',
+        },
+      }),
+    ).resolves.toEqual({
+      ok: false,
+      error: {
+        code: 'reconciliation_failed',
+        message: 'Prepared reconciler handoff could not be dispatched to the active run',
+        details: {
+          conflict_worktree_prepared: true,
+          dispatched_to_reconciler: false,
+          feature_id: 'feature_a',
+          retryable: true,
+          requires_human: true,
+        },
+      },
+    });
+    expect(resumeExecuteMock).not.toHaveBeenCalled();
+  });
+
+  it('returns busy when another feature is already resuming in the background', async () => {
+    let resolveResume: (() => void) | null = null;
+    resumeExecuteMock.mockImplementation(
+      () =>
+        new Promise((resolve) => {
+          resolveResume = () => resolve({ ok: true, data: { command: 'resume' } });
+        }),
+    );
+    mergeExecuteMock.mockResolvedValue({
+      ok: false,
+      error: {
+        code: 'reconciliation_failed',
+        message: 'Merge requires reconciler intervention before it can continue',
+        details: {
+          conflict_worktree_prepared: true,
+          dispatched_to_reconciler: false,
+        },
+      },
+    });
+    const runner = new DashboardRuntimeRunner({
+      repoRoot,
+      instanceId: 'instance123456',
+      env: process.env,
+    });
+
+    const resumeResult = await runner.handleCommand({
+      command: 'feature.resume',
+      feature_id: 'feature_a',
+      args: {},
+    });
+    expect(resumeResult.ok).toBe(true);
+
+    const mergeResult = await runner.handleCommand({
+      command: 'review.approve',
+      feature_id: 'feature_b',
+      args: {
+        approval_token: 'approved',
+      },
+    });
+
+    expect(mergeResult).toEqual(buildRuntimeBusyResponse('feature_a'));
+    resolveResume?.();
+    await runner.waitForIdle();
+  });
+
+  it('executes feature.resume synchronously when a fresh active run already exists', async () => {
+    kernelRuntimeSessionsMock.mockResolvedValue({
+      run_id: 'run:active',
+      owner_instance_id: 'owner:active',
+    });
+    kernelIsRunLeaseFreshMock.mockReturnValue(true);
+    resumeExecuteMock.mockResolvedValue({
+      ok: true,
+      data: {
+        command: 'resume',
+        resumed: true,
+      },
+    });
+
+    const runner = new DashboardRuntimeRunner({
+      repoRoot,
+      instanceId: 'instance123456',
+      env: process.env,
+    });
+
+    await expect(
+      runner.handleCommand({
+        command: 'feature.resume',
+        feature_id: 'feature_active',
+        args: {},
+      }),
+    ).resolves.toEqual({
+      ok: true,
+      data: {
+        command: 'resume',
+        resumed: true,
+      },
+    });
+    expect(kernelRedrivePreparedConflictMock).toHaveBeenCalledWith('feature_active');
+  });
+
+  it('resumes successfully with best-effort redrive when feature has a pending mainline conflict', async () => {
+    kernelRuntimeSessionsMock.mockResolvedValue({
+      run_id: 'run:active',
+      owner_instance_id: 'owner:active',
+    });
+    kernelIsRunLeaseFreshMock.mockReturnValue(true);
+    kernelRedrivePreparedConflictMock.mockResolvedValue(false);
+    resumeExecuteMock.mockResolvedValue({
+      ok: true,
+      data: {
+        command: 'resume',
+        resumed: true,
+      },
+    });
+
+    const runner = new DashboardRuntimeRunner({
+      repoRoot,
+      instanceId: 'instance123456',
+      env: process.env,
+    });
+
+    await expect(
+      runner.handleCommand({
+        command: 'feature.resume',
+        feature_id: 'feature_active',
+        args: {},
+      }),
+    ).resolves.toEqual({
+      ok: true,
+      data: {
+        command: 'resume',
+        resumed: true,
+      },
+    });
+    expect(kernelRedrivePreparedConflictMock).toHaveBeenCalledWith('feature_active');
+  });
+
+  it('resumes successfully and redrives when reconciler conflict can be dispatched', async () => {
+    kernelRuntimeSessionsMock.mockResolvedValue({
+      run_id: 'run:active',
+      owner_instance_id: 'owner:active',
+    });
+    kernelIsRunLeaseFreshMock.mockReturnValue(true);
+    kernelRedrivePreparedConflictMock.mockResolvedValue(true);
+    resumeExecuteMock.mockResolvedValue({
+      ok: true,
+      data: {
+        command: 'resume',
+        resumed: true,
+      },
+    });
+
+    const runner = new DashboardRuntimeRunner({
+      repoRoot,
+      instanceId: 'instance123456',
+      env: process.env,
+    });
+
+    await expect(
+      runner.handleCommand({
+        command: 'feature.resume',
+        feature_id: 'feature_active',
+        args: {},
+      }),
+    ).resolves.toEqual({
+      ok: true,
+      data: {
+        command: 'resume',
+        resumed: true,
+      },
+    });
+    expect(kernelRedrivePreparedConflictMock).toHaveBeenCalledWith('feature_active');
+  });
+
+  it('returns invalid_input when launch.submit does not include prepared features', async () => {
+    const runner = new DashboardRuntimeRunner({
+      repoRoot,
+      instanceId: 'instance123456',
+      env: process.env,
+    });
+
+    await expect(
+      runner.handleCommand({
+        command: 'launch.submit',
+        feature_id: 'feature_a',
+        args: {},
+      }),
+    ).resolves.toEqual({
+      ok: false,
+      error: {
+        code: 'invalid_input',
+        message: 'launch.submit requires at least one prepared feature.',
+      },
+    });
+  });
+
+  it('rejects malformed launch feature entries after normalizing empty values', async () => {
+    const runner = new DashboardRuntimeRunner({
+      repoRoot,
+      instanceId: 'instance123456',
+      env: process.env,
+    });
+
+    await expect(
+      runner.handleCommand({
+        command: 'launch.submit',
+        feature_id: 'feature_a',
+        args: {
+          features: [null, { feature_id: '', spec_path: '   ' }],
+        },
+      }),
+    ).resolves.toEqual({
+      ok: false,
+      error: {
+        code: 'invalid_input',
+        message: 'launch.submit requires at least one prepared feature.',
+      },
+    });
+  });
+
+  it('submits launch features into the active run when a fresh lease exists', async () => {
+    kernelRuntimeSessionsMock.mockResolvedValue({
+      run_id: 'run:active',
+      owner_instance_id: 'owner:active',
+    });
+    kernelIsRunLeaseFreshMock.mockReturnValue(true);
+    toolClientCallMock.mockResolvedValue({
+      ok: true,
+      data: {
+        run_id: 'run:active',
+        request_id: 'exec_req_123',
+        request_status: 'pending',
+      },
+    });
+
+    const runner = new DashboardRuntimeRunner({
+      repoRoot,
+      instanceId: 'instance123456',
+      env: process.env,
+    });
+
+    await expect(
+      runner.handleCommand({
+        command: 'launch.submit',
+        feature_id: 'feature_a',
+        args: {
+          features: [
+            {
+              feature_id: 'feature_b',
+              spec_path: '.aop/features/feature_b/spec.md',
+            },
+            {
+              feature_id: 'feature_a',
+              spec_path: '.aop/features/feature_a/spec.md',
+            },
+          ],
+        },
+      }),
+    ).resolves.toEqual({
+      ok: true,
+      data: {
+        command: 'launch.submit',
+        mode: 'active_run_enrollment',
+        run_id: 'run:active',
+        request_id: 'exec_req_123',
+        request_status: 'pending',
+      },
+    });
+  });
+
+  it('returns a dashboard error when active-run launch enrollment fails', async () => {
+    kernelRuntimeSessionsMock.mockResolvedValue({
+      run_id: 'run:active',
+      owner_instance_id: 'owner:active',
+    });
+    kernelIsRunLeaseFreshMock.mockReturnValue(true);
+    toolClientCallMock.mockRejectedValue(new Error('enrollment failed'));
+
+    const runner = new DashboardRuntimeRunner({
+      repoRoot,
+      instanceId: 'instance123456',
+      env: process.env,
+    });
+
+    await expect(
+      runner.handleCommand({
+        command: 'launch.submit',
+        feature_id: 'feature_a',
+        args: {
+          features: [
+            {
+              feature_id: 'feature_a',
+              spec_path: '.aop/features/feature_a/spec.md',
+            },
+          ],
+        },
+      }),
+    ).resolves.toEqual({
+      ok: false,
+      error: {
+        code: 'dashboard_runtime_failed',
+        message: 'enrollment failed',
+        details: undefined,
+      },
+    });
+  });
+
+  it('starts a background run for launch features when there is no active lease', async () => {
+    let resolveStart: (() => void) | null = null;
+    supervisorStartMock.mockImplementation(
+      () =>
+        new Promise((resolve) => {
+          resolveStart = () =>
+            resolve({
+              status: 'running',
+              queue_depth: 1,
+            });
+        }),
+    );
+
+    const runner = new DashboardRuntimeRunner({
+      repoRoot,
+      instanceId: 'instance123456',
+      env: process.env,
+    });
+
+    const result = await runner.handleCommand({
+      command: 'launch.submit',
+      feature_id: 'feature_a',
+      args: {
+        features: [
+          {
+            feature_id: 'feature_a',
+            spec_path: '.aop/features/feature_a/spec.md',
+          },
+          {
+            feature_id: 'feature_b',
+            spec_path: '.aop/features/feature_b/spec.md',
+          },
+        ],
+      },
+    });
+
+    expect(result).toEqual({
+      ok: true,
+      data: {
+        command: 'launch.submit',
+        mode: 'runtime_start',
+        run_id: expect.stringMatching(/^run:dashboard-launch:/),
+        feature_id: 'feature_a',
+        feature_ids: ['feature_a', 'feature_b'],
+        handoff_started: true,
+        handoff_target: 'runtime',
+        started: true,
+        already_running: false,
+        request_status: 'started',
+        requested_features: [
+          {
+            feature_id: 'feature_a',
+            spec_path: '.aop/features/feature_a/spec.md',
+          },
+          {
+            feature_id: 'feature_b',
+            spec_path: '.aop/features/feature_b/spec.md',
+          },
+        ],
+      },
+    });
+
+    resolveStart?.();
+    await runner.waitForIdle();
+  });
+
+  it('returns already_running for duplicate launch batches and busy for other launch work', async () => {
+    let resolveStart: (() => void) | null = null;
+    supervisorStartMock.mockImplementation(
+      () =>
+        new Promise((resolve) => {
+          resolveStart = () => resolve({ status: 'running', queue_depth: 1 });
+        }),
+    );
+
+    const runner = new DashboardRuntimeRunner({
+      repoRoot,
+      instanceId: 'instance123456',
+      env: process.env,
+    });
+
+    const first = await runner.handleCommand({
+      command: 'launch.submit',
+      feature_id: 'feature_a',
+      args: {
+        features: [{ feature_id: 'feature_a', spec_path: '.aop/features/feature_a/spec.md' }],
+      },
+    });
+    const duplicate = await runner.handleCommand({
+      command: 'launch.submit',
+      feature_id: 'feature_a',
+      args: {
+        features: [{ feature_id: 'feature_a', spec_path: '.aop/features/feature_a/spec.md' }],
+      },
+    });
+    const busy = await runner.handleCommand({
+      command: 'launch.submit',
+      feature_id: 'feature_b',
+      args: {
+        features: [{ feature_id: 'feature_b', spec_path: '.aop/features/feature_b/spec.md' }],
+      },
+    });
+
+    expect(first.ok).toBe(true);
+    expect(duplicate).toEqual({
+      ok: true,
+      data: {
+        command: 'launch.submit',
+        mode: 'runtime_start',
+        run_id: expect.stringMatching(/^run:dashboard-launch:/),
+        feature_id: 'feature_a',
+        feature_ids: ['feature_a'],
+        handoff_started: true,
+        handoff_target: 'runtime',
+        started: false,
+        already_running: true,
+        request_status: 'started',
+        requested_features: [
+          {
+            feature_id: 'feature_a',
+            spec_path: '.aop/features/feature_a/spec.md',
+          },
+        ],
+      },
+    });
+    expect(busy).toEqual({
+      ok: false,
+      error: {
+        code: 'dashboard_runtime_busy',
+        message: 'Dashboard runtime is busy starting execution for feature_a',
+        details: {
+          active_command: 'launch.submit',
+          active_feature_id: 'feature_a',
+          retryable: true,
+          requires_human: false,
+        },
+      },
+    });
+
+    resolveStart?.();
+    await runner.waitForIdle();
+  });
+
+  it('records background resume failures in the runtime state file', async () => {
+    resumeExecuteMock.mockResolvedValue({
+      ok: false,
+      error: {
+        message: 'resume failed',
+      },
+    });
+
+    const runner = new DashboardRuntimeRunner({
+      repoRoot,
+      instanceId: 'instance123456',
+      env: process.env,
+    });
+
+    const response = await runner.handleCommand({
+      command: 'feature.resume',
+      feature_id: 'feature_failed',
+      args: {},
+    });
+
+    expect(response.ok).toBe(true);
+    await runner.waitForIdle();
+
+    const statePath = path.join(
+      repoRoot,
+      '.aop',
+      'runtime',
+      'instance123456',
+      'dashboard-runtime-state.json',
+    );
+    const state = JSON.parse(await fs.readFile(statePath, 'utf8')) as {
+      last_background_error?: { message?: string; feature_id?: string; command?: string } | null;
+    };
+
+    expect(state.last_background_error).toEqual({
+      command: 'feature.resume',
+      feature_id: 'feature_failed',
+      code: 'dashboard_runtime_failed',
+      message: 'resume failed',
+      at: expect.any(String),
+    });
+  });
+
+  it('uses the fallback background failure message when resume errors do not provide one', async () => {
+    resumeExecuteMock.mockResolvedValue({
+      ok: false,
+      error: {},
+    });
+
+    const runner = new DashboardRuntimeRunner({
+      repoRoot,
+      instanceId: 'instance123456',
+      env: process.env,
+    });
+
+    await runner.handleCommand({
+      command: 'feature.resume',
+      feature_id: 'feature_failed',
+      args: {},
+    });
+    await runner.waitForIdle();
+
+    const statePath = path.join(
+      repoRoot,
+      '.aop',
+      'runtime',
+      'instance123456',
+      'dashboard-runtime-state.json',
+    );
+    const state = JSON.parse(await fs.readFile(statePath, 'utf8')) as {
+      last_background_error?: { message?: string } | null;
+    };
+
+    expect(state.last_background_error?.message).toBe('Dashboard background resume failed');
+  });
+
+  it('returns a busy error from feature.resume when launch startup is already occupying the runtime', async () => {
+    let resolveStart: (() => void) | null = null;
+    supervisorStartMock.mockImplementation(
+      () =>
+        new Promise((resolve) => {
+          resolveStart = () => resolve({ status: 'running', queue_depth: 1 });
+        }),
+    );
+
+    const runner = new DashboardRuntimeRunner({
+      repoRoot,
+      instanceId: 'instance123456',
+      env: process.env,
+    });
+
+    await runner.handleCommand({
+      command: 'launch.submit',
+      feature_id: 'feature_a',
+      args: {
+        features: [{ feature_id: 'feature_a', spec_path: '.aop/features/feature_a/spec.md' }],
+      },
+    });
+
+    await expect(
+      runner.handleCommand({
+        command: 'feature.resume',
+        feature_id: 'feature_b',
+        args: {},
+      }),
+    ).resolves.toEqual({
+      ok: false,
+      error: {
+        code: 'dashboard_runtime_busy',
+        message: 'Dashboard runtime is busy starting execution for feature_a',
+        details: {
+          active_command: 'launch.submit',
+          active_feature_id: 'feature_a',
+          retryable: true,
+          requires_human: false,
+        },
+      },
+    });
+
+    resolveStart?.();
+    await runner.waitForIdle();
+  });
+
+  it('processes queued commands and persists command completion state', async () => {
+    const runner = new DashboardRuntimeRunner({
+      repoRoot,
+      instanceId: 'instance123456',
+      env: process.env,
+    });
+    const runnerAny = runner as unknown as {
+      handleCommand: (item: unknown) => Promise<unknown>;
+      stopping: boolean;
+    };
+    vi.spyOn(runnerAny, 'handleCommand').mockImplementation(async () => {
+      runnerAny.stopping = true;
+      return {
+        ok: true,
+        data: {
+          handled: true,
+        },
+      };
+    });
+
+    const runtimeRoot = path.join(repoRoot, '.aop', 'runtime', 'instance123456');
+    await fs.mkdir(runtimeRoot, { recursive: true });
+    await fs.writeFile(
+      path.join(runtimeRoot, 'dashboard-runtime-commands.json'),
+      JSON.stringify({
+        version: 1,
+        instance_id: 'instance123456',
+        updated_at: new Date().toISOString(),
+        items: [
+          {
+            request_id: 'dash_cmd_1',
+            command: 'feature.resume',
+            feature_id: 'feature_a',
+            args: {},
+            status: 'pending',
+            requested_at: new Date().toISOString(),
+            processed_at: null,
+            result: null,
+          },
+        ],
+      }),
+      'utf8',
+    );
+
+    await runner.start();
+
+    const queue = JSON.parse(
+      await fs.readFile(path.join(runtimeRoot, 'dashboard-runtime-commands.json'), 'utf8'),
+    ) as {
+      items: Array<{ status: string; result: { ok: boolean; data: { handled: boolean } } }>;
+    };
+    const state = JSON.parse(
+      await fs.readFile(path.join(runtimeRoot, 'dashboard-runtime-state.json'), 'utf8'),
+    ) as { status: string };
+
+    expect(queue.items[0]).toMatchObject({
+      status: 'completed',
+      result: {
+        ok: true,
+        data: {
+          handled: true,
+        },
+      },
+    });
+    expect(state.status).toBe('stopped');
+  });
+
+  it('returns without work when processNextCommand sees an empty queue', async () => {
+    const runner = new DashboardRuntimeRunner({
+      repoRoot,
+      instanceId: 'instance123456',
+      env: process.env,
+    });
+
+    await expect(
+      (
+        runner as unknown as {
+          claimNextCommand: () => Promise<null>;
+          processNextCommand: () => Promise<void>;
+        }
+      ).claimNextCommand(),
+    ).resolves.toBeNull();
+    await expect(
+      (
+        runner as unknown as {
+          processNextCommand: () => Promise<void>;
+        }
+      ).processNextCommand(),
+    ).resolves.toBeUndefined();
+  });
+
+  it('creates an empty command snapshot when none exists on disk', async () => {
+    const runner = new DashboardRuntimeRunner({
+      repoRoot,
+      instanceId: 'instance123456',
+      env: process.env,
+    });
+
+    await (
+      runner as unknown as {
+        ensureCommandSnapshot: () => Promise<void>;
+      }
+    ).ensureCommandSnapshot();
+
+    const queue = JSON.parse(
+      await fs.readFile(
+        path.join(repoRoot, '.aop', 'runtime', 'instance123456', 'dashboard-runtime-commands.json'),
+        'utf8',
+      ),
+    ) as { items: unknown[]; instance_id: string };
+
+    expect(queue).toMatchObject({
+      instance_id: 'instance123456',
+      items: [],
+    });
+  });
+
+  it('marks queued commands as failed when command execution returns an error envelope', async () => {
+    const runner = new DashboardRuntimeRunner({
+      repoRoot,
+      instanceId: 'instance123456',
+      env: process.env,
+    });
+    const runnerAny = runner as unknown as {
+      handleCommand: (item: unknown) => Promise<unknown>;
+      stopping: boolean;
+    };
+    vi.spyOn(runnerAny, 'handleCommand').mockImplementation(async () => {
+      runnerAny.stopping = true;
+      return {
+        ok: false,
+        error: {
+          code: 'dashboard_runtime_failed',
+          message: 'failed to execute queued command',
+        },
+      };
+    });
+
+    const runtimeRoot = path.join(repoRoot, '.aop', 'runtime', 'instance123456');
+    await fs.mkdir(runtimeRoot, { recursive: true });
+    await fs.writeFile(
+      path.join(runtimeRoot, 'dashboard-runtime-commands.json'),
+      JSON.stringify({
+        version: 1,
+        instance_id: 'instance123456',
+        updated_at: new Date().toISOString(),
+        items: [
+          {
+            request_id: 'dash_cmd_fail',
+            command: 'launch.submit',
+            feature_id: 'feature_a',
+            args: {
+              features: [{ feature_id: 'feature_a', spec_path: '.aop/features/feature_a/spec.md' }],
+            },
+            status: 'pending',
+            requested_at: new Date().toISOString(),
+            processed_at: null,
+            result: null,
+          },
+        ],
+      }),
+      'utf8',
+    );
+
+    await runner.start();
+
+    const queue = JSON.parse(
+      await fs.readFile(path.join(runtimeRoot, 'dashboard-runtime-commands.json'), 'utf8'),
+    ) as {
+      items: Array<{ status: string; result: { ok: boolean; error: { code: string } } }>;
+    };
+
+    expect(queue.items[0]).toMatchObject({
+      status: 'failed',
+      result: {
+        ok: false,
+        error: {
+          code: 'dashboard_runtime_failed',
+        },
+      },
+    });
+  });
+
+  it('preserves unrelated queued commands when completing a single request', async () => {
+    const runner = new DashboardRuntimeRunner({
+      repoRoot,
+      instanceId: 'instance123456',
+      env: process.env,
+    });
+    const runtimeRoot = path.join(repoRoot, '.aop', 'runtime', 'instance123456');
+    await fs.mkdir(runtimeRoot, { recursive: true });
+    await fs.writeFile(
+      path.join(runtimeRoot, 'dashboard-runtime-commands.json'),
+      JSON.stringify({
+        version: 1,
+        instance_id: 'instance123456',
+        updated_at: new Date().toISOString(),
+        items: [
+          {
+            request_id: 'dash_cmd_keep',
+            command: 'feature.resume',
+            feature_id: 'feature_keep',
+            args: {},
+            status: 'pending',
+            requested_at: new Date().toISOString(),
+            processed_at: null,
+            result: null,
+          },
+          {
+            request_id: 'dash_cmd_complete',
+            command: 'feature.resume',
+            feature_id: 'feature_done',
+            args: {},
+            status: 'processing',
+            requested_at: new Date().toISOString(),
+            processed_at: null,
+            result: null,
+          },
+        ],
+      }),
+      'utf8',
+    );
+
+    await (
+      runner as unknown as {
+        completeCommand: (requestId: string, result: unknown) => Promise<void>;
+      }
+    ).completeCommand('dash_cmd_complete', {
+      ok: true,
+      data: { handled: true },
+    });
+
+    const queue = JSON.parse(
+      await fs.readFile(path.join(runtimeRoot, 'dashboard-runtime-commands.json'), 'utf8'),
+    ) as {
+      items: Array<{ request_id: string; status: string }>;
+    };
+
+    expect(queue.items).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          request_id: 'dash_cmd_keep',
+          status: 'pending',
+        }),
+        expect.objectContaining({
+          request_id: 'dash_cmd_complete',
+          status: 'completed',
+        }),
+      ]),
+    );
+  });
+
+  it('uses the provider fallback when provider selection throws during tool client initialization', async () => {
+    const { resolveProviderSelection } = await import('../src/providers/providers.js');
+    vi.mocked(resolveProviderSelection).mockImplementationOnce(() => {
+      throw new Error('selection failed');
+    });
+
+    const runner = new DashboardRuntimeRunner({
+      repoRoot,
+      instanceId: 'instance123456',
+      env: process.env,
+    });
+
+    await expect(
+      (
+        runner as unknown as {
+          initializeToolClient: () => Promise<{ call: typeof toolClientCallMock }>;
+        }
+      ).initializeToolClient(),
+    ).resolves.toEqual({
+      call: toolClientCallMock,
+    });
+  });
+
+  it('reuses the cached tool client after initialization', async () => {
+    const runner = new DashboardRuntimeRunner({
+      repoRoot,
+      instanceId: 'instance123456',
+      env: process.env,
+    });
+    const runnerAny = runner as unknown as {
+      getToolClient: () => Promise<{ call: typeof toolClientCallMock }>;
+    };
+
+    const first = await runnerAny.getToolClient();
+    const second = await runnerAny.getToolClient();
+
+    expect(first).toBe(second);
+  });
+
+  it('throws when launch background startup encounters mismatched role providers', async () => {
+    const { resolveProviderSelectionsByRole } = await import('../src/providers/providers.js');
+    vi.mocked(resolveProviderSelectionsByRole).mockImplementationOnce(
+      () =>
+        ({
+          planner: {
+            provider: 'claude',
+          },
+        }) as never,
+    );
+
+    const runner = new DashboardRuntimeRunner({
+      repoRoot,
+      instanceId: 'instance123456',
+      env: process.env,
+    });
+
+    await expect(
+      (
+        runner as unknown as {
+          runLaunchInBackground: (
+            runId: string,
+            features: Array<{ feature_id: string; spec_path: string }>,
+          ) => Promise<void>;
+        }
+      ).runLaunchInBackground('run:launch', [
+        {
+          feature_id: 'feature_a',
+          spec_path: '.aop/features/feature_a/spec.md',
+        },
+      ]),
+    ).rejects.toMatchObject({
+      code: 'invalid_cli_args',
+      details: {
+        role: 'planner',
+        base_provider: 'codex',
+        role_provider: 'claude',
+      },
+    });
+  });
+
+  it('passes object-shaped execution and observability policies into launch startup', async () => {
+    supervisorStartMock.mockResolvedValue({ status: 'running', queue_depth: 1 });
+    const runner = new DashboardRuntimeRunner({
+      repoRoot,
+      instanceId: 'instance123456',
+      env: process.env,
+    });
+    (
+      runner as unknown as {
+        kernel: { getPolicySnapshot: () => Record<string, unknown> };
+      }
+    ).kernel.getPolicySnapshot = () => ({
+      execution: { allow: true },
+      observability: { verbose: true },
+    });
+
+    await expect(
+      (
+        runner as unknown as {
+          runLaunchInBackground: (
+            runId: string,
+            features: Array<{ feature_id: string; spec_path: string }>,
+          ) => Promise<void>;
+        }
+      ).runLaunchInBackground('run:launch', [
+        {
+          feature_id: 'feature_a',
+          spec_path: '.aop/features/feature_a/spec.md',
+        },
+      ]),
+    ).resolves.toBeUndefined();
+  });
+
+  it('returns unsupported_command for unknown dashboard runtime commands', async () => {
+    const runner = new DashboardRuntimeRunner({
+      repoRoot,
+      instanceId: 'instance123456',
+      env: process.env,
+    });
+
+    await expect(
+      runner.handleCommand({
+        command: 'unknown.command' as never,
+        feature_id: 'feature_a',
+        args: {},
+      }),
+    ).resolves.toEqual({
+      ok: false,
+      error: {
+        code: 'dashboard_runtime_unsupported_command',
+        message: 'Unsupported dashboard runtime command: unknown.command',
+      },
+    });
+  });
+
+  it('uses constructor defaults when optional instanceId and env are omitted', async () => {
+    const runner = new DashboardRuntimeRunner({
+      repoRoot,
+    });
+
+    await expect(
+      runner.handleCommand({
+        command: 'unknown.command' as never,
+        feature_id: 'feature_a',
+        args: {},
+      }),
+    ).resolves.toEqual({
+      ok: false,
+      error: {
+        code: 'dashboard_runtime_unsupported_command',
+        message: 'Unsupported dashboard runtime command: unknown.command',
+      },
+    });
+  });
+});