agentic-orchestrator 0.1.2 → 0.1.4

package/apps/control-plane/test/services.spec.ts

@@ -1,7 +1,7 @@
 import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
-import { afterEach, describe, expect, it } from 'vitest';
+import { afterEach, describe, expect, it, vi } from 'vitest';
 import { LockService } from '../src/application/services/lock-service.js';
 import { ReportingService } from '../src/application/services/reporting-service.js';
 import { RunLeaseService } from '../src/application/services/run-lease-service.js';
@@ -80,6 +80,8 @@ function makeRunLeaseHarness(initialIndex: AnyRecord = makeIndex()) {
       lease_expires_at: at ?? new Date().toISOString()
     }) as RuntimeSessionsSnapshot;
 
+  let runLease: RuntimeSessionsSnapshot = clone(initialIndex.runtime_sessions ?? makeRuntimeSessions());
+
   const service = new RunLeaseService({
     runLeaseTtlSeconds: () => 30,
     withIndexLock: async <T>(operation: () => Promise<T>) => await operation(),
@@ -88,6 +90,10 @@ function makeRunLeaseHarness(initialIndex: AnyRecord = makeIndex()) {
       index = clone(nextIndex);
       writes.push(clone(nextIndex));
     },
+    readRunLease: async () => clone(runLease),
+    writeRunLease: async (data: RuntimeSessionsSnapshot) => {
+      runLease = clone(data);
+    },
     normalizeRuntimeSessions,
     isRunLeaseFresh: (runtimeSessions: AnyRecord) => new Date(runtimeSessions.lease_expires_at).getTime() > Date.now(),
     emptyRuntimeSessions
@@ -96,6 +102,7 @@ function makeRunLeaseHarness(initialIndex: AnyRecord = makeIndex()) {
   return {
     service,
     getIndex: () => clone(index),
+    getRunLease: () => clone(runLease),
     writes
   };
 }
@@ -218,6 +225,7 @@ async function makeReportingHarness() {
     }),
     readIndex: async () => clone(index),
     statePath: (featureId: string) => path.join(tmpDir, featureId, 'state.md'),
+    featureCostPath: (featureId: string) => path.join(tmpDir, featureId, 'cost.json'),
     readState: async (featureId: string) => ({
       frontMatter: clone(stateMap.get(featureId) ?? {})
     }),
@@ -379,7 +387,7 @@ describe('RunLeaseService', () => {
 
     const released = await harness.service.releaseRunLease('run:owner', 'owner:owner');
     expect(released.data.released).toBe(true);
-    expect(harness.getIndex().runtime_sessions.run_id).toBe('none');
+    expect(harness.getRunLease().run_id).toBe('none');
   });
 
   it('reuses existing owner metadata and rejects not-owned lease operations', async () => {
@@ -691,3 +699,88 @@ describe('ReportingService', () => {
     expect(summary.data.qa_summary.pending_required).toBe(0);
   });
 });
+
+describe('ReportingService worktree_branch coverage', () => {
+  const cleanups: Array<() => Promise<void>> = [];
+
+  afterEach(async () => {
+    while (cleanups.length > 0) {
+      const cleanup = cleanups.pop();
+      if (cleanup) {await cleanup();}
+    }
+  });
+
+  it('GIVEN_worktree_branch_string_in_frontMatter_WHEN_reportDashboard_THEN_uses_worktree_branch', async () => {
+    const harness = await makeReportingHarness();
+    cleanups.push(harness.cleanup);
+
+    await harness.ensureState('feature_a', {
+      status: STATUS.BUILDING,
+      worktree_branch: 'feature/my-branch',
+      locks: { held: [] },
+      gate_profile: 'default',
+      gates: { plan: 'pass' },
+      last_updated: '2026-01-01T00:00:00.000Z'
+    });
+
+    const dashboard = await harness.service.reportDashboard();
+    const feat = dashboard.data.features.find((f: AnyRecord) => f.feature_id === 'feature_a');
+    expect(feat?.branch).toBe('feature/my-branch');
+  });
+});
+
+describe('LockService sleep branch coverage', () => {
+  const cleanups: Array<() => Promise<void>> = [];
+
+  afterEach(async () => {
+    while (cleanups.length > 0) {
+      const cleanup = cleanups.pop();
+      if (cleanup) {await cleanup();}
+    }
+    vi.useRealTimers();
+  });
+
+  it('GIVEN_lock_held_and_wait_mode_WHEN_locksAcquire_called_THEN_sleep_is_called_and_times_out', async () => {
+    vi.useFakeTimers();
+
+    const harness = await makeLockHarness({
+      policy: {
+        locks: {
+          acquire_behavior: 'wait',
+          default_wait_timeout_seconds: 10,
+          acquire_backoff: {
+            initial_ms: 0,
+            max_ms: 0,
+            multiplier: 1,
+            jitter_ms: 0
+          }
+        }
+      },
+      states: {
+        feature_a: { version: 1, status: STATUS.PLANNING, locks: { held: [] } }
+      },
+      index: makeIndex({
+        locks: { openapi: 'feature_other', db_migrations: null },
+        lock_leases: {
+          openapi: {
+            holder: 'feature_other',
+            lease_id: 'lease-sleep-test',
+            expires_at: new Date(Date.now() + 60_000).toISOString()
+          },
+          db_migrations: null
+        }
+      })
+    });
+    cleanups.push(harness.cleanup);
+
+    // Start acquisition in background - it will call sleep() on first blocked iteration
+    const acquirePromise = harness.service.locksAcquire('openapi', 'feature_a', 10);
+
+    // Advance time past the timeout to resolve the sleep and trigger timeout
+    vi.advanceTimersByTime(15_000);
+
+    await expect(acquirePromise).rejects.toMatchObject({
+      normalizedResponse: { error: { code: ERROR_CODES.LOCK_CONFLICT } }
+    });
+  });
+});

package/apps/control-plane/test/session-management.spec.ts

@@ -0,0 +1,450 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { AopKernel } from '../src/index.js';
+import { SendCommandHandler } from '../src/cli/send-command-handler.js';
+import { AttachCommandHandler } from '../src/cli/attach-command-handler.js';
+import { ERROR_CODES } from '../src/core/error-codes.js';
+import { TOOLS } from '../src/core/constants.js';
+import { makeTempRepo, writeFeatureSpec } from './helpers.js';
+import type { WorkerProvider } from '../src/index.js';
+
+let repoRoot: string;
+
+beforeEach(async () => {
+  repoRoot = await makeTempRepo(process.cwd());
+});
+
+async function writeFeatureSession(root: string, featureId: string): Promise<void> {
+  const leasePath = path.join(root, '.aop', 'runtime', 'default', 'run-lease.json');
+  await fs.mkdir(path.dirname(leasePath), { recursive: true });
+  let lease: Record<string, unknown> = {};
+  try {
+    lease = JSON.parse(await fs.readFile(leasePath, 'utf8')) as Record<string, unknown>;
+  } catch {
+    // file may not exist yet
+  }
+  lease.orchestrator_session_id = 'orch:session-1';
+  lease.feature_sessions = {
+    ...((lease.feature_sessions as Record<string, unknown>) ?? {}),
+    [featureId]: {
+      planner_session_id: 'planner:1',
+      builder_session_id: 'builder:1',
+      qa_session_id: 'qa:1'
+    }
+  };
+  await fs.writeFile(leasePath, `${JSON.stringify(lease, null, 2)}\n`, 'utf8');
+}
+
+function makeProvider(overrides: Partial<WorkerProvider> = {}): WorkerProvider {
+  return {
+    selection: { provider: 'null', model: 'null-default', provider_config_env: null, provider_config_ref: null },
+    createSession: vi.fn(),
+    reattachSession: vi.fn(),
+    closeSession: vi.fn(),
+    runWorker: vi.fn(),
+    sendMessage: vi.fn(async () => undefined),
+    ...overrides
+  } as unknown as WorkerProvider;
+}
+
+describe('feature.send_message kernel handler', () => {
+  it('GIVEN active session exists WHEN send called THEN message delivered via provider.sendMessage', async () => {
+    const kernel = new AopKernel(repoRoot);
+    await kernel.ensureLoaded();
+    await writeFeatureSpec(repoRoot, 'feature_send_1');
+    await kernel.invoke('feature.init', { feature_id: 'feature_send_1' }, { actor_type: 'orchestrator', actor_id: 'test' });
+    await writeFeatureSession(repoRoot, 'feature_send_1');
+
+    const sendMessageMock = vi.fn(async () => undefined);
+    const provider = makeProvider({ sendMessage: sendMessageMock });
+    kernel.setProvider(provider);
+
+    const result = await kernel.invoke(
+      'feature.send_message',
+      { feature_id: 'feature_send_1', message: 'Hello agent!', operation_id: 'op:send:1' },
+      { actor_type: 'orchestrator', actor_id: 'test' }
+    );
+
+    expect(result.ok).toBe(true);
+    expect(result.data).toMatchObject({
+      feature_id: 'feature_send_1',
+      session_id: 'planner:1',
+      target_role: 'planner',
+      delivered: true
+    });
+    expect(sendMessageMock).toHaveBeenCalledWith('planner:1', 'Hello agent!');
+  });
+
+  it('GIVEN_provider_exposes_session_info_WHEN_send_called_THEN_waits_until_session_is_active_before_delivery', async () => {
+    const kernel = new AopKernel(repoRoot);
+    await kernel.ensureLoaded();
+    await writeFeatureSpec(repoRoot, 'feature_send_wait');
+    await kernel.invoke('feature.init', { feature_id: 'feature_send_wait' }, { actor_type: 'orchestrator', actor_id: 'test' });
+    await writeFeatureSession(repoRoot, 'feature_send_wait');
+
+    const getSessionInfo = vi
+      .fn()
+      .mockResolvedValueOnce({ active: false, provider: 'codex' })
+      .mockResolvedValueOnce({ active: true, provider: 'codex' });
+    const sendMessageMock = vi.fn(async () => undefined);
+    const provider = makeProvider({ sendMessage: sendMessageMock, getSessionInfo });
+    kernel.setProvider(provider);
+
+    const result = await kernel.invoke(
+      'feature.send_message',
+      { feature_id: 'feature_send_wait', message: 'Wait for ready session', operation_id: 'op:send:wait' },
+      { actor_type: 'orchestrator', actor_id: 'test' }
+    );
+
+    expect(result.ok).toBe(true);
+    expect(getSessionInfo).toHaveBeenCalledTimes(2);
+    expect(sendMessageMock).toHaveBeenCalledWith('planner:1', 'Wait for ready session');
+  });
+
+  it('GIVEN no active session WHEN send called THEN error session_not_found returned', async () => {
+    const kernel = new AopKernel(repoRoot);
+    await kernel.ensureLoaded();
+    await writeFeatureSpec(repoRoot, 'feature_send_nosession');
+    await kernel.invoke('feature.init', { feature_id: 'feature_send_nosession' }, { actor_type: 'orchestrator', actor_id: 'test' });
+
+    const provider = makeProvider();
+    kernel.setProvider(provider);
+
+    const result = await kernel.invoke(
+      'feature.send_message',
+      { feature_id: 'feature_send_nosession', message: 'Hello agent!', operation_id: 'op:send:2' },
+      { actor_type: 'orchestrator', actor_id: 'test' }
+    );
+
+    expect(result.ok).toBe(false);
+    expect(result.error).toMatchObject({
+      code: 'session_not_found',
+      message: 'No active session cluster for feature'
+    });
+  });
+
+  it('GIVEN provider does not support sendMessage WHEN send called THEN error provider_unsupported returned', async () => {
+    const kernel = new AopKernel(repoRoot);
+    await kernel.ensureLoaded();
+    await writeFeatureSpec(repoRoot, 'feature_send_noprovider');
+    await kernel.invoke('feature.init', { feature_id: 'feature_send_noprovider' }, { actor_type: 'orchestrator', actor_id: 'test' });
+    await writeFeatureSession(repoRoot, 'feature_send_noprovider');
+
+    // Provider without sendMessage
+    const provider = makeProvider({ sendMessage: undefined });
+    kernel.setProvider(provider);
+
+    const result = await kernel.invoke(
+      'feature.send_message',
+      { feature_id: 'feature_send_noprovider', message: 'Hello agent!', operation_id: 'op:send:3' },
+      { actor_type: 'orchestrator', actor_id: 'test' }
+    );
+
+    expect(result.ok).toBe(false);
+    expect(result.error).toMatchObject({
+      code: 'provider_unsupported',
+      message: 'Provider does not support sendMessage'
+    });
+  });
+
+  it('GIVEN message is empty WHEN send called THEN validation error returned', async () => {
+    const kernel = new AopKernel(repoRoot);
+    await kernel.ensureLoaded();
+    await writeFeatureSpec(repoRoot, 'feature_send_empty_msg');
+    await kernel.invoke('feature.init', { feature_id: 'feature_send_empty_msg' }, { actor_type: 'orchestrator', actor_id: 'test' });
+    await writeFeatureSession(repoRoot, 'feature_send_empty_msg');
+
+    const provider = makeProvider();
+    kernel.setProvider(provider);
+
+    const result = await kernel.invoke(
+      'feature.send_message',
+      { feature_id: 'feature_send_empty_msg', message: '', operation_id: 'op:send:4' },
+      { actor_type: 'orchestrator', actor_id: 'test' }
+    );
+
+    expect(result.ok).toBe(false);
+  });
+
+  it('GIVEN valid send WHEN operation_id reused THEN operation_id passes through in tool args', async () => {
+    const kernel = new AopKernel(repoRoot);
+    await kernel.ensureLoaded();
+    await writeFeatureSpec(repoRoot, 'feature_send_idem');
+    await kernel.invoke('feature.init', { feature_id: 'feature_send_idem' }, { actor_type: 'orchestrator', actor_id: 'test' });
+    await writeFeatureSession(repoRoot, 'feature_send_idem');
+
+    const sendMessageMock = vi.fn(async () => undefined);
+    const provider = makeProvider({ sendMessage: sendMessageMock });
+    kernel.setProvider(provider);
+
+    const operationId = 'op:idempotent:1';
+    const result1 = await kernel.invoke(
+      'feature.send_message',
+      { feature_id: 'feature_send_idem', message: 'idem message', operation_id: operationId },
+      { actor_type: 'orchestrator', actor_id: 'test' }
+    );
+    const result2 = await kernel.invoke(
+      'feature.send_message',
+      { feature_id: 'feature_send_idem', message: 'idem message', operation_id: operationId },
+      { actor_type: 'orchestrator', actor_id: 'test' }
+    );
+
+    expect(result1.ok).toBe(true);
+    expect(result2.ok).toBe(true);
+    expect(result1.data.delivered).toBe(true);
+    expect(result2.data.delivered).toBe(true);
+  });
+});
+
+describe('SendCommandHandler', () => {
+  it('GIVEN send CLI command WHEN executed THEN tool client called with correct params', async () => {
+    const call = vi.fn(async () => ({
+      ok: true,
+      data: { feature_id: 'feature_a', session_id: 'orch:1', delivered: true }
+    }));
+    const toolClient = { call };
+    const handler = new SendCommandHandler(toolClient as never, 'run:test');
+
+    const result = await handler.execute({
+      command: 'send',
+      feature_id: 'feature_a',
+      message: 'Do something'
+    });
+
+    expect(call).toHaveBeenCalledWith(
+      TOOLS.FEATURE_SEND_MESSAGE,
+      expect.objectContaining({
+        feature_id: 'feature_a',
+        message: 'Do something',
+        operation_id: expect.any(String)
+      }),
+      expect.objectContaining({
+        run_id: 'run:test',
+        actor_type: 'system'
+      })
+    );
+    expect(result).toMatchObject({
+      ok: true,
+      data: {
+        command: 'send',
+        feature_id: 'feature_a',
+        delivered: true
+      }
+    });
+  });
+
+  it('GIVEN feature_id missing WHEN send CLI called THEN validation error thrown', async () => {
+    const handler = new SendCommandHandler({ call: vi.fn() } as never, 'run:test');
+
+    await expect(
+      handler.execute({ command: 'send', message: 'Hello' })
+    ).rejects.toMatchObject({
+      code: ERROR_CODES.INVALID_CLI_ARGS,
+      details: expect.objectContaining({
+        reason: '--feature-id is required for send'
+      })
+    });
+  });
+
+  it('GIVEN message missing WHEN send CLI called THEN validation error thrown', async () => {
+    const handler = new SendCommandHandler({ call: vi.fn() } as never, 'run:test');
+
+    await expect(
+      handler.execute({ command: 'send', feature_id: 'feature_a' })
+    ).rejects.toMatchObject({
+      code: ERROR_CODES.INVALID_CLI_ARGS,
+      details: expect.objectContaining({
+        reason: '--message is required for send'
+      })
+    });
+  });
+});
+
+describe('AttachCommandHandler', () => {
+  it('GIVEN_feature_in_planning_WHEN_attach_executed_THEN_attaches_to_planner_session', async () => {
+    const kernel = new AopKernel(repoRoot);
+    await kernel.ensureLoaded();
+    await writeFeatureSpec(repoRoot, 'feature_attach_planning');
+    await kernel.invoke(
+      'feature.init',
+      { feature_id: 'feature_attach_planning' },
+      { actor_type: 'orchestrator', actor_id: 'test' }
+    );
+    await writeFeatureSession(repoRoot, 'feature_attach_planning');
+
+    const attachToSession = vi.fn(async () => undefined);
+    const provider = makeProvider({ attachToSession, reattachSession: undefined });
+    const toolClient = {
+      call: vi.fn(async () => ({ ok: true, data: { front_matter: { status: 'planning' } } }))
+    };
+
+    const handler = new AttachCommandHandler(toolClient as never, 'run:test', kernel, provider);
+    const result = await handler.execute({ command: 'attach', feature_id: 'feature_attach_planning' });
+
+    expect(attachToSession).toHaveBeenCalledWith('planner:1');
+    expect(result).toMatchObject({
+      ok: true,
+      data: {
+        command: 'attach',
+        feature_id: 'feature_attach_planning',
+        role: 'planner',
+        session_id: 'planner:1',
+        attached: true
+      }
+    });
+  });
+
+  it('GIVEN_provider_without_attachToSession_WHEN_attach_executed_THEN_returns_invalid_cli_args_for_unsupported_provider', async () => {
+    const kernel = new AopKernel(repoRoot);
+    await kernel.ensureLoaded();
+    await writeFeatureSpec(repoRoot, 'feature_attach_builder');
+    await kernel.invoke(
+      'feature.init',
+      { feature_id: 'feature_attach_builder' },
+      { actor_type: 'orchestrator', actor_id: 'test' }
+    );
+    await writeFeatureSession(repoRoot, 'feature_attach_builder');
+
+    const provider = makeProvider({
+      selection: {
+        provider: 'custom',
+        model: 'custom-default',
+        provider_config_env: null,
+        provider_config_ref: null
+      },
+      attachToSession: undefined
+    });
+    const toolClient = {
+      call: vi.fn(async () => ({ ok: true, data: { front_matter: { status: 'building' } } }))
+    };
+
+    const handler = new AttachCommandHandler(toolClient as never, 'run:test', kernel, provider);
+    await expect(handler.execute({ command: 'attach', feature_id: 'feature_attach_builder' })).rejects.toMatchObject({
+      code: ERROR_CODES.INVALID_CLI_ARGS,
+      details: expect.objectContaining({
+        reason: expect.stringContaining('does not support interactive attach'),
+        provider: 'custom'
+      })
+    });
+  });
+
+  it('GIVEN_no_feature_session_cluster_WHEN_attach_executed_THEN_returns_invalid_cli_args', async () => {
+    const kernel = new AopKernel(repoRoot);
+    await kernel.ensureLoaded();
+    await writeFeatureSpec(repoRoot, 'feature_attach_missing');
+    await kernel.invoke(
+      'feature.init',
+      { feature_id: 'feature_attach_missing' },
+      { actor_type: 'orchestrator', actor_id: 'test' }
+    );
+
+    const provider = makeProvider();
+    const toolClient = {
+      call: vi.fn(async () => ({ ok: true, data: { front_matter: { status: 'planning' } } }))
+    };
+
+    const handler = new AttachCommandHandler(toolClient as never, 'run:test', kernel, provider);
+    await expect(handler.execute({ command: 'attach', feature_id: 'feature_attach_missing' })).rejects.toMatchObject({
+      code: ERROR_CODES.INVALID_CLI_ARGS,
+      details: expect.objectContaining({
+        reason: expect.stringContaining('No active session cluster found')
+      })
+    });
+  });
+});
+
+describe('AttachCommandHandler branch coverage', () => {
+  it('GIVEN_missing_feature_id_WHEN_attach_executed_THEN_throws_invalid_cli_args', async () => {
+    const kernel = { getRuntimeSessions: vi.fn() } as never;
+    const provider = makeProvider();
+    const toolClient = { call: vi.fn() };
+    const handler = new AttachCommandHandler(toolClient as never, 'run:test', kernel, provider);
+    await expect(handler.execute({ command: 'attach' })).rejects.toMatchObject({
+      code: ERROR_CODES.INVALID_CLI_ARGS
+    });
+  });
+
+  it('GIVEN_invalid_feature_id_WHEN_attach_executed_THEN_throws_invalid_cli_args', async () => {
+    const kernel = { getRuntimeSessions: vi.fn() } as never;
+    const provider = makeProvider();
+    const toolClient = { call: vi.fn() };
+    const handler = new AttachCommandHandler(toolClient as never, 'run:test', kernel, provider);
+    await expect(handler.execute({ command: 'attach', feature_id: 'INVALID Feature ID' })).rejects.toMatchObject({
+      code: ERROR_CODES.INVALID_CLI_ARGS
+    });
+  });
+
+  it('GIVEN_feature_in_qa_status_WHEN_attach_executed_THEN_attaches_to_qa_session', async () => {
+    const kernel = new AopKernel(repoRoot);
+    await kernel.ensureLoaded();
+    await writeFeatureSpec(repoRoot, 'feature_attach_qa');
+    await kernel.invoke('feature.init', { feature_id: 'feature_attach_qa' }, { actor_type: 'orchestrator', actor_id: 'test' });
+    await writeFeatureSession(repoRoot, 'feature_attach_qa');
+
+    const attachToSession = vi.fn(async () => undefined);
+    const provider = makeProvider({ attachToSession });
+    const toolClient = {
+      call: vi.fn(async () => ({ ok: true, data: { front_matter: { status: 'qa' } } }))
+    };
+
+    const handler = new AttachCommandHandler(toolClient as never, 'run:test', kernel, provider);
+    const result = await handler.execute({ command: 'attach', feature_id: 'feature_attach_qa' });
+    const data = (result as Record<string, unknown>).data as Record<string, unknown>;
+    expect(data.role).toBe('qa');
+    expect(attachToSession).toHaveBeenCalledWith('qa:1');
+  });
+
+  it('GIVEN_feature_in_building_status_WHEN_attach_executed_THEN_attaches_to_builder_session', async () => {
+    const kernel = new AopKernel(repoRoot);
+    await kernel.ensureLoaded();
+    await writeFeatureSpec(repoRoot, 'feature_attach_building');
+    await kernel.invoke('feature.init', { feature_id: 'feature_attach_building' }, { actor_type: 'orchestrator', actor_id: 'test' });
+    await writeFeatureSession(repoRoot, 'feature_attach_building');
+
+    const attachToSession = vi.fn(async () => undefined);
+    const provider = makeProvider({ attachToSession });
+    const toolClient = {
+      call: vi.fn(async () => ({ ok: true, data: { front_matter: { status: 'building' } } }))
+    };
+
+    const handler = new AttachCommandHandler(toolClient as never, 'run:test', kernel, provider);
+    const result = await handler.execute({ command: 'attach', feature_id: 'feature_attach_building' });
+    const data = (result as Record<string, unknown>).data as Record<string, unknown>;
+    expect(data.role).toBe('builder');
+    expect(attachToSession).toHaveBeenCalledWith('builder:1');
+  });
+
+  it('GIVEN_feature_session_with_unassigned_specific_role_WHEN_attach_executed_THEN_falls_back_to_orchestrator_session', async () => {
+    const kernel = new AopKernel(repoRoot);
+    await kernel.ensureLoaded();
+    await writeFeatureSpec(repoRoot, 'feature_attach_fallback');
+    await kernel.invoke('feature.init', { feature_id: 'feature_attach_fallback' }, { actor_type: 'orchestrator', actor_id: 'test' });
+
+    // Write session with unassigned planner_session_id but valid orchestrator session
+    const leasePath = path.join(repoRoot, '.aop', 'runtime', 'default', 'run-lease.json');
+    await fs.mkdir(path.dirname(leasePath), { recursive: true });
+    await fs.writeFile(leasePath, JSON.stringify({
+      orchestrator_session_id: 'orch:fallback-1',
+      feature_sessions: {
+        feature_attach_fallback: {
+          planner_session_id: 'unassigned',
+          builder_session_id: 'unassigned',
+          qa_session_id: 'unassigned'
+        }
+      }
+    }), 'utf8');
+
+    const attachToSession = vi.fn(async () => undefined);
+    const provider = makeProvider({ attachToSession });
+    const toolClient = {
+      call: vi.fn(async () => ({ ok: true, data: { front_matter: { status: 'planning' } } }))
+    };
+
+    const handler = new AttachCommandHandler(toolClient as never, 'run:test', kernel, provider);
+    const result = await handler.execute({ command: 'attach', feature_id: 'feature_attach_fallback' });
+    const data = (result as Record<string, unknown>).data as Record<string, unknown>;
+    expect(data.session_id).toBe('orch:fallback-1');
+    expect(attachToSession).toHaveBeenCalledWith('orch:fallback-1');
+  });
+});