agentic-orchestrator 0.1.2 → 0.1.4

package/apps/control-plane/test/activity-monitor.spec.ts

@@ -0,0 +1,294 @@
+import { describe, expect, it, vi } from 'vitest';
+import { ActivityMonitorService } from '../src/application/services/activity-monitor-service.js';
+import type { ActivitySnapshot } from '../src/application/services/activity-monitor-service.js';
+import { TOOLS } from '../src/core/constants.js';
+
+const DEFAULT_THRESHOLD = 300_000;
+const RECENT_TIMESTAMP = new Date(Date.now() - 60_000).toISOString(); // 1 minute ago
+const STALE_TIMESTAMP = new Date(Date.now() - 600_000).toISOString(); // 10 minutes ago
+
+function makeToolCaller(frontMatter: Record<string, unknown>) {
+  return {
+    callTool: vi.fn(async (_role: string, toolName: string) => {
+      if (toolName === TOOLS.FEATURE_STATE_GET) {
+        return { ok: true, data: { front_matter: { version: 1, ...frontMatter } } };
+      }
+      return { ok: true, data: {} };
+    })
+  };
+}
+
+function makeNotifier() {
+  return { notify: vi.fn(async () => undefined) };
+}
+
+describe('ActivityMonitorService', () => {
+  it('GIVEN feature with recent heartbeat WHEN getActivityState called THEN returns active', async () => {
+    const toolCaller = makeToolCaller({ status: 'building', last_heartbeat_at: RECENT_TIMESTAMP });
+    const service = new ActivityMonitorService({
+      toolCaller: toolCaller as never,
+      idleThresholdMs: DEFAULT_THRESHOLD
+    });
+
+    const snapshot = await service.getActivityState('feature_a');
+
+    expect(snapshot.state).toBe('active');
+    expect(snapshot.featureId).toBe('feature_a');
+    expect(snapshot.lastEventAt).toBe(RECENT_TIMESTAMP);
+    expect(snapshot.detectedVia).toBe('jsonl');
+  });
+
+  it('GIVEN feature with stale heartbeat WHEN getActivityState called THEN returns idle', async () => {
+    const toolCaller = makeToolCaller({ status: 'building', last_heartbeat_at: STALE_TIMESTAMP });
+    const service = new ActivityMonitorService({
+      toolCaller: toolCaller as never,
+      idleThresholdMs: DEFAULT_THRESHOLD
+    });
+
+    const snapshot = await service.getActivityState('feature_b');
+
+    expect(snapshot.state).toBe('idle');
+    expect(snapshot.lastEventAt).toBe(STALE_TIMESTAMP);
+  });
+
+  it('GIVEN feature with status=failed WHEN getActivityState called THEN returns exited', async () => {
+    const toolCaller = makeToolCaller({ status: 'failed' });
+    const service = new ActivityMonitorService({ toolCaller: toolCaller as never });
+
+    const snapshot = await service.getActivityState('feature_c');
+
+    expect(snapshot.state).toBe('exited');
+    expect(snapshot.lastEventAt).toBeNull();
+  });
+
+  it('GIVEN feature with status=blocked WHEN getActivityState called THEN returns blocked', async () => {
+    const toolCaller = makeToolCaller({ status: 'blocked' });
+    const service = new ActivityMonitorService({ toolCaller: toolCaller as never });
+
+    const snapshot = await service.getActivityState('feature_d');
+
+    expect(snapshot.state).toBe('blocked');
+    expect(snapshot.lastEventAt).toBeNull();
+  });
+
+  it('GIVEN feature with no timestamp WHEN getActivityState called THEN returns unknown', async () => {
+    const toolCaller = makeToolCaller({ status: 'planning' });
+    const service = new ActivityMonitorService({ toolCaller: toolCaller as never });
+
+    const snapshot = await service.getActivityState('feature_e');
+
+    expect(snapshot.state).toBe('unknown');
+    expect(snapshot.lastEventAt).toBeNull();
+  });
+
+  it('GIVEN agent_stuck reaction enabled WHEN stuck detected THEN notifier called', async () => {
+    const toolCaller = makeToolCaller({ status: 'building', last_heartbeat_at: STALE_TIMESTAMP });
+    const notifier = makeNotifier();
+    const service = new ActivityMonitorService({
+      toolCaller: toolCaller as never,
+      notifier: notifier as never,
+      idleThresholdMs: DEFAULT_THRESHOLD,
+      reactionsPolicy: {
+        agent_stuck: { enabled: true, action: 'notify_only', idle_threshold_ms: DEFAULT_THRESHOLD, escalate_after: 2 }
+      }
+    });
+
+    const stuck = await service.checkAndNotifyStuck('feature_f');
+
+    expect(stuck).toBe(true);
+    expect(notifier.notify).toHaveBeenCalledWith(
+      'agent_stuck',
+      expect.objectContaining({ feature_id: 'feature_f' })
+    );
+  });
+
+  it('GIVEN agent_stuck reaction disabled WHEN stuck detected THEN notifier not called', async () => {
+    const toolCaller = makeToolCaller({ status: 'building', last_heartbeat_at: STALE_TIMESTAMP });
+    const notifier = makeNotifier();
+    const service = new ActivityMonitorService({
+      toolCaller: toolCaller as never,
+      notifier: notifier as never,
+      idleThresholdMs: DEFAULT_THRESHOLD,
+      reactionsPolicy: {
+        agent_stuck: { enabled: false, action: 'notify_only', idle_threshold_ms: DEFAULT_THRESHOLD, escalate_after: 2 }
+      }
+    });
+
+    const stuck = await service.checkAndNotifyStuck('feature_g');
+
+    expect(stuck).toBe(true);
+    expect(notifier.notify).not.toHaveBeenCalled();
+  });
+
+  it('GIVEN formatForStatus called WHEN state is idle THEN string includes idle', () => {
+    const service = new ActivityMonitorService({
+      toolCaller: { callTool: vi.fn() } as never
+    });
+    const snapshot: ActivitySnapshot = {
+      featureId: 'feature_h',
+      state: 'idle',
+      lastEventAt: new Date(Date.now() - 10 * 60_000).toISOString(),
+      detectedVia: 'jsonl'
+    };
+
+    const str = service.formatForStatus(snapshot);
+
+    expect(str).toContain('idle');
+  });
+
+  it('GIVEN formatForStatus called WHEN state has no timestamp THEN returns state name', () => {
+    const service = new ActivityMonitorService({
+      toolCaller: { callTool: vi.fn() } as never
+    });
+    const snapshot: ActivitySnapshot = {
+      featureId: 'feature_i',
+      state: 'unknown',
+      lastEventAt: null,
+      detectedVia: 'unknown'
+    };
+
+    const str = service.formatForStatus(snapshot);
+
+    expect(str).toBe('unknown');
+  });
+
+  it('GIVEN checkAndNotifyStuck called WHEN feature is not idle THEN returns false', async () => {
+    const toolCaller = makeToolCaller({ status: 'building', last_heartbeat_at: RECENT_TIMESTAMP });
+    const notifier = makeNotifier();
+    const service = new ActivityMonitorService({
+      toolCaller: toolCaller as never,
+      notifier: notifier as never,
+      idleThresholdMs: DEFAULT_THRESHOLD,
+      reactionsPolicy: {
+        agent_stuck: { enabled: true, action: 'notify_only', idle_threshold_ms: DEFAULT_THRESHOLD, escalate_after: 2 }
+      }
+    });
+
+    const stuck = await service.checkAndNotifyStuck('feature_j');
+
+    expect(stuck).toBe(false);
+    expect(notifier.notify).not.toHaveBeenCalled();
+  });
+
+  it('GIVEN_codex_rpc_detector_WHEN_last_run_is_recent_THEN_detected_via_process_and_state_active', async () => {
+    const toolCaller = makeToolCaller({ status: 'building', last_run_at: RECENT_TIMESTAMP });
+    const service = new ActivityMonitorService({
+      toolCaller: toolCaller as never,
+      detectorName: 'codex-rpc'
+    });
+
+    const snapshot = await service.getActivityState('feature_codex');
+
+    expect(snapshot.state).toBe('active');
+    expect(snapshot.detectedVia).toBe('process');
+    expect(snapshot.lastEventAt).toBe(RECENT_TIMESTAMP);
+  });
+
+  it('GIVEN_waiting_input_status_reason_WHEN_getActivityState_called_THEN_returns_waiting_input', async () => {
+    const toolCaller = makeToolCaller({
+      status: 'building',
+      status_reason: 'waiting_input:user_confirmation',
+      last_heartbeat_at: RECENT_TIMESTAMP
+    });
+    const service = new ActivityMonitorService({
+      toolCaller: toolCaller as never
+    });
+
+    const snapshot = await service.getActivityState('feature_wait');
+
+    expect(snapshot.state).toBe('waiting_input');
+  });
+
+  it('GIVEN_checkAndNotifyStuck_WHEN_snapshot_changes_THEN_activity_snapshot_persisted_to_state', async () => {
+    const toolCaller = makeToolCaller({ status: 'building', last_heartbeat_at: STALE_TIMESTAMP });
+    const service = new ActivityMonitorService({
+      toolCaller: toolCaller as never
+    });
+
+    await service.checkAndNotifyStuck('feature_patch');
+
+    expect(toolCaller.callTool).toHaveBeenCalledWith(
+      'orchestrator',
+      TOOLS.FEATURE_STATE_PATCH,
+      expect.objectContaining({
+        feature_id: 'feature_patch',
+        patch: expect.objectContaining({
+          front_matter: expect.objectContaining({
+            activity_state: 'idle',
+            activity_detected_via: 'jsonl'
+          })
+        })
+      })
+    );
+  });
+});
+
+describe('ActivityMonitorService detectedVia and resolveLastEvent branches', () => {
+  it('GIVEN_codex_rpc_detector_with_ledger_entry_WHEN_getActivityState_called_THEN_detectedVia_is_ledger', async () => {
+    const toolCaller = makeToolCaller({ status: 'building', last_heartbeat_at: RECENT_TIMESTAMP });
+    const operationLedger = { getLastOperationAt: vi.fn(() => RECENT_TIMESTAMP) };
+    const service = new ActivityMonitorService({
+      toolCaller: toolCaller as never,
+      detectorName: 'codex-rpc',
+      operationLedger
+    });
+    const snapshot = await service.getActivityState('feature_ledger');
+    expect(snapshot.detectedVia).toBe('ledger');
+  });
+
+  it('GIVEN_process_heuristic_detector_WHEN_getActivityState_called_THEN_detectedVia_is_process', async () => {
+    const toolCaller = makeToolCaller({ status: 'building', last_heartbeat_at: RECENT_TIMESTAMP });
+    const service = new ActivityMonitorService({
+      toolCaller: toolCaller as never,
+      detectorName: 'process-heuristic'
+    });
+    const snapshot = await service.getActivityState('feature_proc');
+    expect(snapshot.detectedVia).toBe('process');
+  });
+
+  it('GIVEN_codex_rpc_without_ledger_WHEN_getActivityState_called_THEN_detectedVia_is_process', async () => {
+    const toolCaller = makeToolCaller({ status: 'building', last_heartbeat_at: RECENT_TIMESTAMP });
+    const operationLedger = { getLastOperationAt: vi.fn(() => null) };
+    const service = new ActivityMonitorService({
+      toolCaller: toolCaller as never,
+      detectorName: 'codex-rpc',
+      operationLedger
+    });
+    const snapshot = await service.getActivityState('feature_norpc');
+    expect(snapshot.detectedVia).toBe('process');
+  });
+
+  it('GIVEN_process_heuristic_with_last_run_at_WHEN_getActivityState_THEN_uses_last_run_at', async () => {
+    const toolCaller = makeToolCaller({ status: 'building', last_run_at: RECENT_TIMESTAMP, last_heartbeat_at: undefined });
+    const service = new ActivityMonitorService({
+      toolCaller: toolCaller as never,
+      detectorName: 'process-heuristic'
+    });
+    const snapshot = await service.getActivityState('feature_run_at');
+    expect(snapshot.lastEventAt).toBe(RECENT_TIMESTAMP);
+  });
+
+  it('GIVEN_unknown_detector_name_WHEN_getActivityState_called_THEN_detectedVia_is_unknown', async () => {
+    const toolCaller = makeToolCaller({ status: 'building', last_heartbeat_at: RECENT_TIMESTAMP });
+    const service = new ActivityMonitorService({
+      toolCaller: toolCaller as never,
+      detectorName: 'some-unknown-detector'
+    });
+    const snapshot = await service.getActivityState('feature_unknown_detector');
+    expect(snapshot.detectedVia).toBe('unknown');
+  });
+
+  it('GIVEN_state_patch_throws_WHEN_checkAndNotifyStuck_called_THEN_silently_continues', async () => {
+    const toolCaller = {
+      callTool: vi.fn(async (_role: string, toolName: string) => {
+        if (toolName === TOOLS.FEATURE_STATE_GET) {
+          return { ok: true, data: { front_matter: { version: 1, status: 'building', last_heartbeat_at: STALE_TIMESTAMP } } };
+        }
+        throw new Error('patch failed');
+      })
+    };
+    const service = new ActivityMonitorService({ toolCaller: toolCaller as never });
+    // Should not throw even when persistSnapshot fails - still returns stuck status
+    await expect(service.checkAndNotifyStuck('feature_patch_fail')).resolves.not.toThrow();
+  });
+});

package/apps/control-plane/test/adapter-registry.spec.ts

@@ -0,0 +1,132 @@
+import { describe, it, expect } from 'vitest';
+import {
+  DefaultAdapterRegistry,
+  AGENT_PROVIDER_SLOT,
+  globalAdapterRegistry,
+  REGISTERED_PROVIDER_NAMES
+} from '../src/application/adapters/adapter-registry.js';
+import { SUPPORTED_PROVIDERS } from '../src/providers/providers.js';
+import { ERROR_CODES } from '../src/core/error-codes.js';
+
+describe('DefaultAdapterRegistry', () => {
+  describe('GIVEN_empty_registry_WHEN_has_is_called_THEN_returns_false', () => {
+    it('returns false for any slot/name', () => {
+      const registry = new DefaultAdapterRegistry();
+      expect(registry.has('agent-provider', 'codex')).toBe(false);
+    });
+  });
+
+  describe('GIVEN_empty_registry_WHEN_list_is_called_THEN_returns_empty_array', () => {
+    it('returns empty array', () => {
+      const registry = new DefaultAdapterRegistry();
+      expect(registry.list('agent-provider')).toEqual([]);
+    });
+  });
+
+  describe('GIVEN_registered_adapter_WHEN_has_is_called_THEN_returns_true', () => {
+    it('finds the registered adapter', () => {
+      const registry = new DefaultAdapterRegistry();
+      const slot = { name: 'test-slot' };
+      registry.register(slot, { slot: 'test-slot', name: 'my-adapter' }, () => ({ value: 42 }));
+      expect(registry.has('test-slot', 'my-adapter')).toBe(true);
+    });
+  });
+
+  describe('GIVEN_registered_adapter_WHEN_list_is_called_THEN_returns_manifest', () => {
+    it('lists the manifest', () => {
+      const registry = new DefaultAdapterRegistry();
+      const slot = { name: 'test-slot' };
+      const manifest = { slot: 'test-slot', name: 'my-adapter' };
+      registry.register(slot, manifest, () => ({ value: 42 }));
+      expect(registry.list('test-slot')).toEqual([manifest]);
+    });
+  });
+
+  describe('GIVEN_registered_adapter_WHEN_resolve_is_called_THEN_factory_is_invoked', () => {
+    it('calls factory with config and returns result', () => {
+      const registry = new DefaultAdapterRegistry();
+      const slot = { name: 'compute-slot' };
+      registry.register(slot, { slot: 'compute-slot', name: 'fast' }, (config) => ({
+        speed: (config as { speed: number }).speed
+      }));
+      const result = registry.resolve(slot, 'fast', { speed: 100 });
+      expect(result).toEqual({ speed: 100 });
+    });
+  });
+
+  describe('GIVEN_unknown_adapter_WHEN_resolve_is_called_THEN_throws_structured_error', () => {
+    it('throws with UNSUPPORTED_AGENT_PROVIDER code', () => {
+      const registry = new DefaultAdapterRegistry();
+      const slot = { name: 'missing-slot' };
+      expect(() => registry.resolve(slot, 'ghost', {})).toThrowError(
+        expect.objectContaining({ code: ERROR_CODES.UNSUPPORTED_AGENT_PROVIDER })
+      );
+    });
+
+    it('includes slot and name in error details', () => {
+      const registry = new DefaultAdapterRegistry();
+      const slot = { name: 'missing-slot' };
+      let caught: unknown;
+      try {
+        registry.resolve(slot, 'ghost', {});
+      } catch (e) {
+        caught = e;
+      }
+      expect((caught as { details: Record<string, unknown> }).details).toMatchObject({
+        slot: 'missing-slot',
+        name: 'ghost'
+      });
+    });
+  });
+
+  describe('GIVEN_multiple_adapters_in_same_slot_WHEN_list_is_called_THEN_all_manifests_returned', () => {
+    it('returns all registered manifests', () => {
+      const registry = new DefaultAdapterRegistry();
+      const slot = { name: 'multi-slot' };
+      registry.register(slot, { slot: 'multi-slot', name: 'a' }, () => 'a');
+      registry.register(slot, { slot: 'multi-slot', name: 'b' }, () => 'b');
+      registry.register(slot, { slot: 'multi-slot', name: 'c' }, () => 'c');
+      expect(registry.list('multi-slot').map((m) => m.name)).toEqual(
+        expect.arrayContaining(['a', 'b', 'c'])
+      );
+    });
+  });
+});
+
+describe('AGENT_PROVIDER_SLOT', () => {
+  describe('GIVEN_global_registry_WHEN_listing_providers_THEN_all_built_ins_present', () => {
+    const expectedProviders = ['codex', 'claude', 'gemini', 'kiro-cli', 'copilot', 'custom'];
+
+    it.each(expectedProviders)('contains built-in provider: %s', (name) => {
+      expect(globalAdapterRegistry.has(AGENT_PROVIDER_SLOT.name, name)).toBe(true);
+    });
+
+    it('lists exactly the expected built-in providers', () => {
+      const names = globalAdapterRegistry.list(AGENT_PROVIDER_SLOT.name).map((m) => m.name);
+      expect(names.sort()).toEqual(expectedProviders.sort());
+    });
+  });
+
+  describe('GIVEN_global_registry_WHEN_resolving_provider_THEN_returns_contract', () => {
+    it('resolve returns object with correct name', () => {
+      const result = globalAdapterRegistry.resolve(AGENT_PROVIDER_SLOT, 'codex', {});
+      expect(result).toMatchObject({ name: 'codex' });
+    });
+  });
+});
+
+describe('REGISTERED_PROVIDER_NAMES parity with SUPPORTED_PROVIDERS', () => {
+  describe('GIVEN_adapter_registry_and_providers_WHEN_comparing_sets_THEN_they_match', () => {
+    it('SUPPORTED_PROVIDERS contains all names from adapter registry', () => {
+      for (const name of REGISTERED_PROVIDER_NAMES) {
+        expect(SUPPORTED_PROVIDERS.has(name)).toBe(true);
+      }
+    });
+
+    it('adapter registry contains all names from SUPPORTED_PROVIDERS', () => {
+      for (const name of SUPPORTED_PROVIDERS) {
+        expect(REGISTERED_PROVIDER_NAMES.has(name)).toBe(true);
+      }
+    });
+  });
+});

package/apps/control-plane/test/batch-operations.spec.ts

@@ -0,0 +1,112 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { StatusCommandHandler } from '../src/cli/status-command-handler.js';
+import { TOOLS } from '../src/core/constants.js';
+import type { RunCommandContext } from '../src/cli/run-command-handler.js';
+
+const fsReadFileMock = vi.hoisted(() => vi.fn());
+const specResolverResolveMock = vi.hoisted(() => vi.fn());
+
+vi.mock('node:fs/promises', () => ({
+  default: {
+    readFile: fsReadFileMock
+  }
+}));
+
+vi.mock('../src/cli/spec-input-resolver.js', () => ({
+  SpecInputResolver: vi.fn().mockImplementation(() => ({
+    resolve: specResolverResolveMock
+  }))
+}));
+
+import { RunCommandHandler } from '../src/cli/run-command-handler.js';
+
+function makeContext(toolCallImpl = vi.fn(async () => ({ ok: true, data: {} }))): RunCommandContext {
+  return {
+    repoRoot: '/repo',
+    env: {},
+    runId: 'run:test',
+    transport: 'inprocess' as const,
+    options: { command: 'run', batch: true, folder_input: '/specs' },
+    kernel: { getAgentsConfig: () => ({}) } as never,
+    toolClient: { call: toolCallImpl } as never
+  };
+}
+
+describe('BatchOperations', () => {
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('GIVEN_folder_with_specs_WHEN_batch_run_all_new_THEN_all_created', async () => {
+    specResolverResolveMock.mockResolvedValue([
+      '/repo/.aop/features/feature_a/spec.md',
+      '/repo/.aop/features/feature_b/spec.md'
+    ]);
+    fsReadFileMock.mockResolvedValue(JSON.stringify({ active: [], blocked: [] }));
+
+    const toolCallMock = vi.fn(async () => ({ ok: true, data: {} }));
+    const handler = new RunCommandHandler(0);
+    const result = await handler.execute(makeContext(toolCallMock));
+
+    expect(result).toMatchObject({
+      ok: true,
+      data: { command: 'batch-run', created: 2, skipped: 0, failed: 0 }
+    });
+    expect(toolCallMock).toHaveBeenCalledWith(
+      TOOLS.FEATURE_INIT,
+      expect.objectContaining({ feature_id: 'feature_a' }),
+      expect.any(Object)
+    );
+    expect(toolCallMock).toHaveBeenCalledWith(
+      TOOLS.FEATURE_INIT,
+      expect.objectContaining({ feature_id: 'feature_b' }),
+      expect.any(Object)
+    );
+  });
+
+  it('GIVEN_folder_with_specs_WHEN_batch_run_some_active_THEN_active_skipped', async () => {
+    specResolverResolveMock.mockResolvedValue([
+      '/repo/.aop/features/feature_a/spec.md',
+      '/repo/.aop/features/feature_b/spec.md'
+    ]);
+    fsReadFileMock.mockResolvedValue(JSON.stringify({ active: ['feature_a'], blocked: [] }));
+
+    const toolCallMock = vi.fn(async () => ({ ok: true, data: {} }));
+    const handler = new RunCommandHandler(0);
+    const result = await handler.execute(makeContext(toolCallMock));
+
+    expect(result).toMatchObject({
+      ok: true,
+      data: { command: 'batch-run', created: 1, skipped: 1, failed: 0 }
+    });
+    expect(toolCallMock).not.toHaveBeenCalledWith(
+      TOOLS.FEATURE_INIT,
+      expect.objectContaining({ feature_id: 'feature_a' }),
+      expect.any(Object)
+    );
+  });
+
+  it('GIVEN_status_with_summary_flag_WHEN_called_THEN_compact_output', async () => {
+    const dashboardCall = vi.fn(async () => ({
+      ok: true,
+      data: {
+        features: [
+          { feature_id: 'feature_a', status: 'planning' },
+          { feature_id: 'feature_b', status: 'building' }
+        ]
+      }
+    }));
+    const handler = new StatusCommandHandler({ call: dashboardCall } as never, 'run:test');
+    const result = await handler.execute({ summary: true });
+
+    expect(result).toMatchObject({
+      ok: true,
+      data: {
+        summary: [
+          { feature_id: 'feature_a', status: 'planning', activity: 'unknown' },
+          { feature_id: 'feature_b', status: 'building', activity: 'unknown' }
+        ]
+      }
+    });
+  });
+});

package/apps/control-plane/test/bootstrap-attach.spec.ts

@@ -0,0 +1,102 @@
+/**
+ * Focused bootstrap tests for the Attach command success path (lines 321-323 in bootstrap.ts).
+ * Uses a mocked AttachCommandHandler to avoid needing a full provider setup.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const ensureLoadedMock = vi.hoisted(() => vi.fn(async () => undefined));
+const createToolingRuntimeMock = vi.hoisted(() => vi.fn(async () => ({ runtime: 'ok' })));
+const resolveToolClientMock = vi.hoisted(() => vi.fn());
+const toolCallMock = vi.hoisted(() => vi.fn(async () => ({ ok: true, data: {} })));
+
+vi.mock('node:readline/promises', () => ({
+  default: {
+    createInterface: vi.fn(() => ({
+      question: vi.fn(async () => ''),
+      close: vi.fn()
+    }))
+  }
+}));
+
+vi.mock('../src/core/kernel.js', () => {
+  class AopKernel {
+    private readonly repoRoot: string;
+    constructor(repoRoot: string) { this.repoRoot = repoRoot; }
+    async ensureLoaded() { await ensureLoadedMock(); }
+    getRepoRoot() { return this.repoRoot; }
+    getAgentsConfig() { return {}; }
+    getRbacPolicy() { return {}; }
+    getPolicySnapshot() { return {}; }
+    setProvider() {}
+  }
+  return { AopKernel };
+});
+
+vi.mock('../src/mcp/runtime-factory.js', () => ({
+  createToolingRuntime: createToolingRuntimeMock,
+  resolveToolClient: resolveToolClientMock
+}));
+
+vi.mock('../src/cli/init-command-handler.js', () => ({
+  InitCommandHandler: vi.fn().mockImplementation(() => ({
+    execute: vi.fn(async () => ({ ok: true, data: { command: 'init', created: [], updated: [], skipped: [], validation_warnings: [], next_steps: [] } }))
+  }))
+}));
+
+vi.mock('../src/cli/dashboard-command-handler.js', () => ({
+  DashboardCommandHandler: vi.fn().mockImplementation(() => ({
+    execute: vi.fn(async () => ({ ok: true, data: { message: 'started', port: 3000 } }))
+  }))
+}));
+
+vi.mock('../src/cli/run-command-handler.js', () => ({
+  RunCommandHandler: vi.fn().mockImplementation(() => ({
+    execute: vi.fn(async () => ({ ok: true, data: { status: 'running' } }))
+  }))
+}));
+
+vi.mock('../src/cli/resume-command-handler.js', () => ({
+  ResumeCommandHandler: vi.fn().mockImplementation(() => ({
+    execute: vi.fn(async () => ({ ok: true, data: { resumed: false } }))
+  }))
+}));
+
+vi.mock('../src/cli/attach-command-handler.js', () => ({
+  AttachCommandHandler: vi.fn().mockImplementation(() => ({
+    execute: vi.fn(async () => ({
+      ok: true,
+      data: { command: 'attach', feature_id: 'feat_x', status: 'building', role: 'builder', session_id: 'sess-1', attached: true }
+    }))
+  }))
+}));
+
+describe('bootstrap runCli attach success path', () => {
+  let stdoutSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    resolveToolClientMock.mockReturnValue({ call: toolCallMock });
+    toolCallMock.mockClear();
+    ensureLoadedMock.mockClear();
+    createToolingRuntimeMock.mockClear();
+    stdoutSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+  });
+
+  afterEach(() => {
+    stdoutSpy.mockRestore();
+    vi.clearAllMocks();
+  });
+
+  it('GIVEN_attach_command_with_feature_id_WHEN_executed_THEN_returns_exit_code_0', async () => {
+    const { runCli } = await import('../src/interfaces/cli/bootstrap.js');
+    const code = await runCli(['attach', '--feature-id', 'feat_x'], {
+      cwd: '/tmp',
+      env: { ...process.env, AOP_AGENT_PROVIDER: 'custom' }
+    });
+    // Attach handler mock returns successfully → printPayload → return 0
+    expect(code).toBe(0);
+    const writes = stdoutSpy.mock.calls.flatMap((call) => {
+      try { return [JSON.parse(String(call[0]))]; } catch { return []; }
+    });
+    expect(writes[0]).toMatchObject({ ok: true, data: { command: 'attach' } });
+  });
+});