agentic-orchestrator 0.1.2 → 0.1.4

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

@@ -44,11 +44,11 @@ describe('AopKernel', () => {
     const kernel = new AopKernel(repoRoot);
     await kernel.ensureLoaded();
 
-    const index = await (kernel as any).readIndex();
+    const runLease = await kernel.readRunLease();
     expect(await fs.readFile(path.join(repoRoot, '.aop', 'features', 'legacy_feature', 'spec.md'), 'utf8')).toContain('Legacy Spec');
-    expect(index.runtime_sessions).toBeTruthy();
-    expect(index.runtime_sessions.orchestrator_session_id).toBe('unknown');
-    expect(typeof index.runtime_sessions.lease_expires_at).toBe('string');
+    expect(runLease).toBeTruthy();
+    expect(runLease.orchestrator_session_id).toBe('unknown');
+    expect(typeof runLease.lease_expires_at).toBe('string');
   });
 
   it('prefers existing .aop runtime artifacts over legacy agentic artifacts when both exist', async () => {
@@ -208,17 +208,19 @@ describe('AopKernel', () => {
         required_resources: ['openapi']
       }
     ];
-    const runtimeSessions = index.runtime_sessions as { feature_sessions?: Record<string, unknown> };
-    runtimeSessions.feature_sessions = {
-      ...(runtimeSessions.feature_sessions ?? {}),
+    await fs.writeFile(indexPath, `${JSON.stringify(index, null, 2)}\n`, 'utf8');
+
+    // Set up feature session in run-lease.json (separate from index.json)
+    const currentLease = await kernel.readRunLease();
+    currentLease.feature_sessions = {
+      ...(currentLease.feature_sessions ?? {}),
       feature_delete: {
         planner_session_id: 'planner:1',
         builder_session_id: 'builder:1',
         qa_session_id: 'qa:1'
       }
     };
-    index.runtime_sessions = runtimeSessions;
-    await fs.writeFile(indexPath, `${JSON.stringify(index, null, 2)}\n`, 'utf8');
+    await kernel.writeRunLease(currentLease);
 
     const preview = await kernel.invoke(
       'feature.delete',
@@ -265,12 +267,12 @@ describe('AopKernel', () => {
       active: string[];
       blocked_queue: Array<{ feature_id?: string }>;
       locks: Record<string, string | null>;
-      runtime_sessions: { feature_sessions?: Record<string, unknown> };
     };
     expect(postIndex.active).not.toContain('feature_delete');
     expect(postIndex.blocked_queue.map((entry) => entry.feature_id)).not.toContain('feature_delete');
     expect(postIndex.locks.openapi).toBeNull();
-    expect(postIndex.runtime_sessions.feature_sessions?.feature_delete).toBeUndefined();
+    const postLease = await kernel.readRunLease();
+    expect(postLease.feature_sessions?.feature_delete).toBeUndefined();
 
     const rerun = await kernel.invoke(
       'feature.delete',

package/apps/control-plane/test/lock-service.spec.ts

@@ -0,0 +1,508 @@
+import { describe, it, expect, vi } from 'vitest';
+import { LockService } from '../src/application/services/lock-service.js';
+import type { LockServicePort } from '../src/application/services/lock-service.js';
+import { ERROR_CODES } from '../src/core/error-codes.js';
+import { pathExists } from '../src/core/fs.js';
+
+vi.mock('../src/core/fs.js', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('../src/core/fs.js')>();
+  return {
+    ...actual,
+    pathExists: vi.fn(async () => false),
+    nowIso: actual.nowIso
+  };
+});
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AnyRecord = Record<string, any>;
+
+function makeIndex(overrides: Partial<AnyRecord> = {}): AnyRecord {
+  return {
+    version: 1,
+    active: ['feature-a'],
+    blocked: [],
+    merged: [],
+    locks: {},
+    lock_leases: {},
+    updated_at: '2026-01-01T00:00:00.000Z',
+    ...overrides
+  };
+}
+
+function makePolicy(overrides: Partial<AnyRecord> = {}): AnyRecord {
+  return {
+    locks: {
+      resources: ['ci', 'deploy'],
+      acquire_behavior: 'wait',
+      default_wait_timeout_seconds: 1,
+      lease_ttl_seconds: 60,
+      acquire_backoff: {
+        initial_ms: 10,
+        max_ms: 100,
+        multiplier: 2,
+        jitter_ms: 0
+      },
+      ...overrides
+    }
+  };
+}
+
+function makePort(indexData: AnyRecord, policyData: AnyRecord): LockServicePort {
+  let stored = { ...indexData };
+  return {
+    withIndexLock: vi.fn(async (fn: () => Promise<unknown>) => fn()),
+    readIndex: vi.fn(async () => ({ ...stored })),
+    writeIndex: vi.fn(async (idx: AnyRecord) => {
+      stored = { ...idx };
+    }),
+    updateState: vi.fn(async () => ({})),
+    statePath: vi.fn((featureId: string) => `/tmp/.aop/features/${featureId}/state.md`),
+    getPolicySnapshot: vi.fn(() => policyData)
+  };
+}
+
+describe('LockService', () => {
+  describe('locksAcquire', () => {
+    it('GIVEN_valid_resource_and_featureId_WHEN_lock_is_free_THEN_acquires_lock', async () => {
+      const port = makePort(makeIndex(), makePolicy());
+      const svc = new LockService(port);
+
+      const result = await svc.locksAcquire('ci', 'feature-a', null);
+
+      expect(result.data.resource).toBe('ci');
+      expect(result.data.feature_id).toBe('feature-a');
+      expect(result.data.lease_id).toBeDefined();
+      expect(result.data.expires_at).toBeDefined();
+      expect(result.data.stale_reclaimed).toBe(false);
+      expect(port.writeIndex).toHaveBeenCalled();
+      expect(port.updateState).toHaveBeenCalled();
+    });
+
+    it('GIVEN_featureId_already_holds_lock_WHEN_locksAcquire_called_THEN_re_acquires_same_lock', async () => {
+      const index = makeIndex({
+        locks: { ci: 'feature-a' },
+        lock_leases: {
+          ci: {
+            holder: 'feature-a',
+            lease_id: 'existing-lease',
+            expires_at: new Date(Date.now() + 60000).toISOString()
+          }
+        }
+      });
+      const port = makePort(index, makePolicy());
+      const svc = new LockService(port);
+
+      const result = await svc.locksAcquire('ci', 'feature-a', null);
+
+      expect(result.data.feature_id).toBe('feature-a');
+      expect(result.data.stale_reclaimed).toBe(false);
+    });
+
+    it('GIVEN_expired_lease_WHEN_locksAcquire_called_THEN_reclaims_stale_lock', async () => {
+      const index = makeIndex({
+        locks: { ci: 'feature-old' },
+        lock_leases: {
+          ci: {
+            holder: 'feature-old',
+            lease_id: 'old-lease',
+            expires_at: new Date(Date.now() - 5000).toISOString()
+          }
+        }
+      });
+      const port = makePort(index, makePolicy());
+      const svc = new LockService(port);
+
+      const result = await svc.locksAcquire('ci', 'feature-a', null);
+
+      expect(result.data.stale_reclaimed).toBe(true);
+      expect(result.evidence).toBeDefined();
+      expect(result.evidence?.code).toBe(ERROR_CODES.STALE_LOCK_RECLAIMED);
+    });
+
+    it('GIVEN_unknown_resource_WHEN_locksAcquire_called_THEN_throws_invalid_argument', async () => {
+      const port = makePort(makeIndex(), makePolicy());
+      const svc = new LockService(port);
+
+      await expect(svc.locksAcquire('unknown-resource', 'feature-a', null)).rejects.toMatchObject({
+        normalizedResponse: expect.objectContaining({
+          error: expect.objectContaining({ code: ERROR_CODES.INVALID_ARGUMENT })
+        })
+      });
+    });
+
+    it('GIVEN_null_resource_WHEN_locksAcquire_called_THEN_throws_invalid_argument', async () => {
+      const port = makePort(makeIndex(), makePolicy());
+      const svc = new LockService(port);
+
+      await expect(svc.locksAcquire(null, 'feature-a', null)).rejects.toMatchObject({
+        normalizedResponse: expect.objectContaining({
+          error: expect.objectContaining({ code: ERROR_CODES.INVALID_ARGUMENT })
+        })
+      });
+    });
+
+    it('GIVEN_null_featureId_WHEN_locksAcquire_called_THEN_throws_invalid_argument', async () => {
+      const port = makePort(makeIndex(), makePolicy());
+      const svc = new LockService(port);
+
+      await expect(svc.locksAcquire('ci', null, null)).rejects.toMatchObject({
+        normalizedResponse: expect.objectContaining({
+          error: expect.objectContaining({ code: ERROR_CODES.INVALID_ARGUMENT })
+        })
+      });
+    });
+
+    it('GIVEN_lock_held_by_other_AND_behavior_is_fail_WHEN_locksAcquire_called_THEN_throws_lock_conflict', async () => {
+      const index = makeIndex({
+        locks: { ci: 'feature-b' },
+        lock_leases: {
+          ci: {
+            holder: 'feature-b',
+            lease_id: 'b-lease',
+            expires_at: new Date(Date.now() + 60000).toISOString()
+          }
+        }
+      });
+      const policy = makePolicy({ acquire_behavior: 'fail' });
+      const port = makePort(index, policy);
+      const svc = new LockService(port);
+
+      await expect(svc.locksAcquire('ci', 'feature-a', null)).rejects.toMatchObject({
+        normalizedResponse: expect.objectContaining({
+          error: expect.objectContaining({ code: ERROR_CODES.LOCK_CONFLICT })
+        })
+      });
+    });
+
+    it('GIVEN_lock_held_AND_behavior_is_wait_AND_timeout_exceeded_THEN_throws_lock_conflict', async () => {
+      const index = makeIndex({
+        locks: { ci: 'feature-b' },
+        lock_leases: {
+          ci: {
+            holder: 'feature-b',
+            lease_id: 'b-lease',
+            expires_at: new Date(Date.now() + 60000).toISOString()
+          }
+        }
+      });
+      // Very short timeout so the test completes quickly
+      const policy = makePolicy({
+        acquire_behavior: 'wait',
+        default_wait_timeout_seconds: 0,
+        acquire_backoff: { initial_ms: 5, max_ms: 5, multiplier: 1, jitter_ms: 0 }
+      });
+      const port = makePort(index, policy);
+      const svc = new LockService(port);
+
+      await expect(svc.locksAcquire('ci', 'feature-a', 0)).rejects.toMatchObject({
+        normalizedResponse: expect.objectContaining({
+          error: expect.objectContaining({ code: ERROR_CODES.LOCK_CONFLICT })
+        })
+      });
+    });
+
+    it('GIVEN_explicit_wait_timeout_WHEN_locksAcquire_called_THEN_uses_provided_timeout', async () => {
+      const index = makeIndex({
+        locks: { ci: 'feature-b' },
+        lock_leases: {
+          ci: {
+            holder: 'feature-b',
+            lease_id: 'b-lease',
+            expires_at: new Date(Date.now() + 60000).toISOString()
+          }
+        }
+      });
+      const policy = makePolicy({
+        acquire_behavior: 'wait',
+        acquire_backoff: { initial_ms: 5, max_ms: 5, multiplier: 1, jitter_ms: 0 }
+      });
+      const port = makePort(index, policy);
+      const svc = new LockService(port);
+
+      // Pass 0 seconds explicitly (overrides policy default)
+      await expect(svc.locksAcquire('ci', 'feature-a', 0)).rejects.toMatchObject({
+        normalizedResponse: expect.objectContaining({
+          error: expect.objectContaining({ code: ERROR_CODES.LOCK_CONFLICT })
+        })
+      });
+    });
+  });
+
+  describe('locksRelease', () => {
+    it('GIVEN_feature_holds_lock_WHEN_locksRelease_called_THEN_releases_lock', async () => {
+      const index = makeIndex({
+        locks: { ci: 'feature-a' },
+        lock_leases: {
+          ci: { holder: 'feature-a', lease_id: 'lease-1', expires_at: new Date(Date.now() + 60000).toISOString() }
+        }
+      });
+      const port = makePort(index, makePolicy());
+      const svc = new LockService(port);
+
+      const result = await svc.locksRelease('ci', 'feature-a');
+
+      expect(result.data.released).toBe(true);
+      expect(result.data.resource).toBe('ci');
+      expect(port.writeIndex).toHaveBeenCalled();
+      expect(port.updateState).toHaveBeenCalled();
+    });
+
+    it('GIVEN_null_args_WHEN_locksRelease_called_THEN_throws_invalid_argument', async () => {
+      const port = makePort(makeIndex(), makePolicy());
+      const svc = new LockService(port);
+
+      await expect(svc.locksRelease(null, null)).rejects.toMatchObject({
+        normalizedResponse: expect.objectContaining({
+          error: expect.objectContaining({ code: ERROR_CODES.INVALID_ARGUMENT })
+        })
+      });
+    });
+
+    it('GIVEN_null_resource_WHEN_locksRelease_called_THEN_throws_invalid_argument', async () => {
+      const port = makePort(makeIndex(), makePolicy());
+      const svc = new LockService(port);
+
+      await expect(svc.locksRelease(null, 'feature-a')).rejects.toMatchObject({
+        normalizedResponse: expect.objectContaining({
+          error: expect.objectContaining({ code: ERROR_CODES.INVALID_ARGUMENT })
+        })
+      });
+    });
+
+    it('GIVEN_lock_held_by_other_feature_WHEN_locksRelease_called_THEN_throws_lock_conflict', async () => {
+      const index = makeIndex({
+        locks: { ci: 'feature-b' },
+        lock_leases: {
+          ci: { holder: 'feature-b', lease_id: 'lease-b', expires_at: new Date(Date.now() + 60000).toISOString() }
+        }
+      });
+      const port = makePort(index, makePolicy());
+      const svc = new LockService(port);
+
+      await expect(svc.locksRelease('ci', 'feature-a')).rejects.toMatchObject({
+        normalizedResponse: expect.objectContaining({
+          error: expect.objectContaining({ code: ERROR_CODES.LOCK_CONFLICT })
+        })
+      });
+    });
+
+    it('GIVEN_lock_not_held_WHEN_locksRelease_called_THEN_releases_successfully', async () => {
+      const index = makeIndex({ locks: { ci: null }, lock_leases: { ci: null } });
+      const port = makePort(index, makePolicy());
+      const svc = new LockService(port);
+
+      const result = await svc.locksRelease('ci', 'feature-a');
+
+      expect(result.data.released).toBe(true);
+    });
+
+    it('GIVEN_collisionQueueService_present_WHEN_locksRelease_called_THEN_reDrives_queue', async () => {
+      const index = makeIndex({ locks: { ci: 'feature-a' }, lock_leases: { ci: null } });
+      const port = makePort(index, makePolicy());
+      const reDriveFn = vi.fn(async () => ({ data: { processed: 1, retried: 1, still_blocked: 0 } }));
+      port.collisionQueueService = { reDriveBlockedQueue: reDriveFn };
+      const svc = new LockService(port);
+
+      await svc.locksRelease('ci', 'feature-a');
+
+      expect(reDriveFn).toHaveBeenCalled();
+    });
+
+    it('GIVEN_collisionQueueService_throws_WHEN_locksRelease_called_THEN_still_succeeds', async () => {
+      const index = makeIndex({ locks: { ci: 'feature-a' }, lock_leases: { ci: null } });
+      const port = makePort(index, makePolicy());
+      port.collisionQueueService = {
+        reDriveBlockedQueue: vi.fn(async () => {
+          throw new Error('queue error');
+        })
+      };
+      const svc = new LockService(port);
+
+      // Should not throw despite reDrive failure
+      const result = await svc.locksRelease('ci', 'feature-a');
+      expect(result.data.released).toBe(true);
+    });
+
+    it('GIVEN_no_collisionQueueService_WHEN_locksRelease_called_THEN_succeeds_without_redriving', async () => {
+      const index = makeIndex({ locks: { ci: 'feature-a' }, lock_leases: { ci: null } });
+      const port = makePort(index, makePolicy());
+      // No collisionQueueService attached
+      const svc = new LockService(port);
+
+      const result = await svc.locksRelease('ci', 'feature-a');
+      expect(result.data.released).toBe(true);
+    });
+  });
+
+  describe('renewLeases', () => {
+    it('GIVEN_matching_lease_holders_WHEN_renewLeases_called_THEN_extends_expiry', async () => {
+      const oldExpiry = new Date(Date.now() + 10000).toISOString();
+      const index = makeIndex({
+        locks: { ci: 'feature-a' },
+        lock_leases: {
+          ci: { holder: 'feature-a', lease_id: 'lease-1', expires_at: oldExpiry }
+        }
+      });
+      const port = makePort(index, makePolicy());
+      const svc = new LockService(port);
+
+      await svc.renewLeases(['feature-a']);
+
+      expect(port.writeIndex).toHaveBeenCalled();
+      const written = vi.mocked(port.writeIndex).mock.calls[0][0];
+      const newExpiry = written.lock_leases.ci.expires_at;
+      expect(new Date(newExpiry).getTime()).toBeGreaterThan(new Date(oldExpiry).getTime());
+    });
+
+    it('GIVEN_no_matching_holders_WHEN_renewLeases_called_THEN_does_not_write_index', async () => {
+      const index = makeIndex({
+        lock_leases: {
+          ci: { holder: 'feature-b', lease_id: 'lease-b', expires_at: new Date(Date.now() + 60000).toISOString() }
+        }
+      });
+      const port = makePort(index, makePolicy());
+      const svc = new LockService(port);
+
+      await svc.renewLeases(['feature-a']);
+
+      expect(port.writeIndex).not.toHaveBeenCalled();
+    });
+
+    it('GIVEN_null_lease_entry_WHEN_renewLeases_called_THEN_skips_entry', async () => {
+      const index = makeIndex({
+        lock_leases: { ci: null }
+      });
+      const port = makePort(index, makePolicy());
+      const svc = new LockService(port);
+
+      await svc.renewLeases(['feature-a']);
+
+      expect(port.writeIndex).not.toHaveBeenCalled();
+    });
+
+    it('GIVEN_empty_featureIds_WHEN_renewLeases_called_THEN_does_not_write_index', async () => {
+      const index = makeIndex({
+        lock_leases: {
+          ci: { holder: 'feature-a', lease_id: 'lease-1', expires_at: new Date(Date.now() + 60000).toISOString() }
+        }
+      });
+      const port = makePort(index, makePolicy());
+      const svc = new LockService(port);
+
+      await svc.renewLeases([]);
+
+      expect(port.writeIndex).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('recoverFromState', () => {
+    it('GIVEN_no_stale_leases_WHEN_recoverFromState_called_THEN_returns_empty_stale_list', async () => {
+      const index = makeIndex({
+        lock_leases: {
+          ci: { holder: 'feature-a', lease_id: 'lease-1', expires_at: new Date(Date.now() + 60000).toISOString() }
+        }
+      });
+      const port = makePort(index, makePolicy());
+      const svc = new LockService(port);
+
+      const result = await svc.recoverFromState();
+
+      expect(result.data.recovered).toBe(true);
+      expect(result.data.stale_features).toEqual([]);
+      expect(port.writeIndex).not.toHaveBeenCalled();
+    });
+
+    it('GIVEN_stale_leases_with_valid_state_paths_WHEN_recoverFromState_called_THEN_clears_and_updates_state', async () => {
+      vi.mocked(pathExists).mockResolvedValueOnce(true);
+      const index = makeIndex({
+        lock_leases: {
+          ci: {
+            holder: 'feature-stale',
+            lease_id: 'old-lease',
+            expires_at: new Date(Date.now() - 10000).toISOString()
+          }
+        },
+        locks: { ci: 'feature-stale' }
+      });
+      const port = makePort(index, makePolicy());
+      const svc = new LockService(port);
+
+      const result = await svc.recoverFromState();
+
+      expect(result.data.recovered).toBe(true);
+      expect(result.data.stale_features).toContain('feature-stale');
+      expect(port.writeIndex).toHaveBeenCalled();
+      expect(port.updateState).toHaveBeenCalled();
+    });
+
+    it('GIVEN_null_lease_entry_WHEN_recoverFromState_called_THEN_skips_entry', async () => {
+      const index = makeIndex({
+        lock_leases: { ci: null }
+      });
+      const port = makePort(index, makePolicy());
+      const svc = new LockService(port);
+
+      const result = await svc.recoverFromState();
+
+      expect(result.data.stale_features).toEqual([]);
+    });
+
+    it('GIVEN_stale_lease_with_missing_state_file_WHEN_recoverFromState_called_THEN_skips_updateState', async () => {
+      // pathExists defaults to false (mock at top of file), so updateState should be skipped
+      const index = makeIndex({
+        lock_leases: {
+          deploy: {
+            holder: 'ghost-feature',
+            lease_id: 'ghost-lease',
+            expires_at: new Date(Date.now() - 5000).toISOString()
+          }
+        },
+        locks: { deploy: 'ghost-feature' }
+      });
+      const port = makePort(index, makePolicy());
+      const svc = new LockService(port);
+
+      const result = await svc.recoverFromState();
+
+      expect(result.data.stale_features).toContain('ghost-feature');
+      // updateState should NOT be called since the file doesn't exist
+      expect(port.updateState).not.toHaveBeenCalled();
+    });
+
+    it('GIVEN_multiple_stale_leases_for_same_feature_WHEN_recoverFromState_THEN_deduplicates', async () => {
+      // pathExists defaults to false; updateState will be skipped but stale_features should still be deduplicated
+      const index = makeIndex({
+        lock_leases: {
+          ci: {
+            holder: 'feature-x',
+            lease_id: 'lease-1',
+            expires_at: new Date(Date.now() - 5000).toISOString()
+          },
+          deploy: {
+            holder: 'feature-x',
+            lease_id: 'lease-2',
+            expires_at: new Date(Date.now() - 5000).toISOString()
+          }
+        },
+        locks: { ci: 'feature-x', deploy: 'feature-x' }
+      });
+      const port = makePort(index, makePolicy());
+      const svc = new LockService(port);
+
+      const result = await svc.recoverFromState();
+
+      // Deduplicated: feature-x appears once
+      expect(result.data.stale_features).toEqual(['feature-x']);
+    });
+
+    it('GIVEN_active_features_in_index_WHEN_recoverFromState_THEN_returns_active_in_data', async () => {
+      const index = makeIndex({ active: ['feature-z'], lock_leases: {} });
+      const port = makePort(index, makePolicy());
+      const svc = new LockService(port);
+
+      const result = await svc.recoverFromState();
+
+      expect(result.data.active).toEqual(['feature-z']);
+    });
+  });
+});