orbital-command 0.2.0 → 1.0.0

package/server/routes/sync-routes.ts

@@ -0,0 +1,175 @@
+import { Router } from 'express';
+import type { SyncService } from '../services/sync-service.js';
+import type { ProjectManager } from '../project-manager.js';
+import { isValidRelativePath } from '../utils/route-helpers.js';
+
+interface SyncRouteDeps {
+  syncService: SyncService;
+  projectManager: ProjectManager;
+}
+
+export function createSyncRoutes({ syncService, projectManager }: SyncRouteDeps): Router {
+  const router = Router();
+
+  // ─── Sync State ─────────────────────────────────────────
+
+  /** GET /sync/state/:projectId — sync state for a specific project */
+  router.get('/sync/state/:projectId', (req, res) => {
+    const ctx = projectManager.getContext(req.params.projectId);
+    if (!ctx) return res.status(404).json({ error: 'Project not found' });
+
+    const report = syncService.computeSyncState(ctx.id, ctx.config.projectRoot);
+    res.json(report);
+  });
+
+  /** GET /sync/global-state — matrix view across all projects */
+  router.get('/sync/global-state', (_req, res) => {
+    const report = syncService.computeGlobalSyncState();
+    res.json(report);
+  });
+
+  // ─── Override Operations ────────────────────────────────
+
+  /** POST /sync/override — create an override for a file in a project */
+  router.post('/sync/override', (req, res) => {
+    const { projectId, relativePath, reason } = req.body as {
+      projectId: string; relativePath: string; reason?: string;
+    };
+    if (!projectId || !relativePath) {
+      return res.status(400).json({ error: 'projectId and relativePath required' });
+    }
+    if (!isValidRelativePath(relativePath)) {
+      return res.status(400).json({ error: 'Invalid relativePath' });
+    }
+
+    const ctx = projectManager.getContext(projectId);
+    if (!ctx) return res.status(404).json({ error: 'Project not found' });
+
+    syncService.createOverride(ctx.config.projectRoot, relativePath, reason);
+    res.json({ success: true });
+  });
+
+  /** POST /sync/revert — revert an override back to global */
+  router.post('/sync/revert', (req, res) => {
+    const { projectId, relativePath } = req.body as {
+      projectId: string; relativePath: string;
+    };
+    if (!projectId || !relativePath) {
+      return res.status(400).json({ error: 'projectId and relativePath required' });
+    }
+    if (!isValidRelativePath(relativePath)) {
+      return res.status(400).json({ error: 'Invalid relativePath' });
+    }
+
+    const ctx = projectManager.getContext(projectId);
+    if (!ctx) return res.status(404).json({ error: 'Project not found' });
+
+    syncService.revertOverride(ctx.config.projectRoot, relativePath);
+    res.json({ success: true });
+  });
+
+  /** POST /sync/promote — promote a project override to global */
+  router.post('/sync/promote', (req, res) => {
+    const { projectId, relativePath } = req.body as {
+      projectId: string; relativePath: string;
+    };
+    if (!projectId || !relativePath) {
+      return res.status(400).json({ error: 'projectId and relativePath required' });
+    }
+    if (!isValidRelativePath(relativePath)) {
+      return res.status(400).json({ error: 'Invalid relativePath' });
+    }
+
+    const ctx = projectManager.getContext(projectId);
+    if (!ctx) return res.status(404).json({ error: 'Project not found' });
+
+    const result = syncService.promoteOverride(ctx.config.projectRoot, relativePath);
+    res.json({ success: true, ...result });
+  });
+
+  /** POST /sync/resolve-drift — resolve a drifted file */
+  router.post('/sync/resolve-drift', (req, res) => {
+    const { projectId, relativePath, resolution } = req.body as {
+      projectId: string; relativePath: string; resolution: 'pin-override' | 'reset-global';
+    };
+    if (!projectId || !relativePath || !resolution) {
+      return res.status(400).json({ error: 'projectId, relativePath, and resolution required' });
+    }
+    if (!isValidRelativePath(relativePath)) {
+      return res.status(400).json({ error: 'Invalid relativePath' });
+    }
+
+    const ctx = projectManager.getContext(projectId);
+    if (!ctx) return res.status(404).json({ error: 'Project not found' });
+
+    syncService.resolveDrift(ctx.config.projectRoot, relativePath, resolution);
+    res.json({ success: true });
+  });
+
+  // ─── Impact Preview ─────────────────────────────────────
+
+  /** GET /sync/impact?path=<relativePath> — preview impact of a global change */
+  router.get('/sync/impact', (req, res) => {
+    const relativePath = req.query.path as string;
+    if (!relativePath) {
+      return res.status(400).json({ error: 'path query parameter required' });
+    }
+    if (!isValidRelativePath(relativePath)) {
+      return res.status(400).json({ error: 'Invalid path' });
+    }
+
+    const preview = syncService.getImpactPreview(relativePath);
+    res.json(preview);
+  });
+
+  // ─── Project Management ─────────────────────────────────
+
+  /** GET /projects — list all registered projects */
+  router.get('/projects', (req, res) => {
+    const include = req.query.include as string | undefined;
+    res.json(projectManager.getProjectList({
+      includeWorkflow: include?.includes('workflow'),
+    }));
+  });
+
+  /** POST /projects — register a new project */
+  router.post('/projects', async (req, res) => {
+    const { path: projectPath, name, color } = req.body as {
+      path: string; name?: string; color?: string;
+    };
+    if (!projectPath) {
+      return res.status(400).json({ error: 'path required' });
+    }
+
+    try {
+      const summary = await projectManager.addProject(projectPath, { name, color });
+      res.status(201).json(summary);
+    } catch (err) {
+      res.status(500).json({ error: String(err) });
+    }
+  });
+
+  /** DELETE /projects/:id — unregister a project */
+  router.delete('/projects/:id', async (req, res) => {
+    const removed = await projectManager.removeProject(req.params.id);
+    if (!removed) return res.status(404).json({ error: 'Project not found' });
+    res.json({ success: true });
+  });
+
+  /** PATCH /projects/:id — update project metadata */
+  router.patch('/projects/:id', async (req, res) => {
+    const { name, color, enabled } = req.body as {
+      name?: string; color?: string; enabled?: boolean;
+    };
+
+    if (name !== undefined && !name.trim()) {
+      return res.status(400).json({ error: 'Name cannot be empty' });
+    }
+
+    const updated = await projectManager.updateProject(req.params.id, { name, color, enabled });
+    if (!updated) return res.status(404).json({ error: 'Project not found' });
+    res.json(updated);
+  });
+
+  return router;
+}

package/server/routes/version-routes.ts

@@ -3,9 +3,9 @@ import { execFile } from 'child_process';
 import { promisify } from 'util';
 import path from 'path';
 import fs from 'fs';
-import { fileURLToPath } from 'url';
 import type { Server } from 'socket.io';
 import { createLogger } from '../utils/logger.js';
+import { getOrbitalRoot } from '../utils/package-info.js';
 
 const log = createLogger('version');
 
@@ -15,21 +15,6 @@ interface VersionRouteDeps {
   io: Server;
 }
 
-/** Resolve the root directory of the orbital-command package itself. */
-function getOrbitalRoot(): string {
-  const __selfDir = path.dirname(fileURLToPath(import.meta.url));
-  // Walk up until we find package.json (handles both dev and compiled paths)
-  let dir = __selfDir;
-  for (let i = 0; i < 6; i++) {
-    if (fs.existsSync(path.join(dir, 'package.json'))) {
-      return dir;
-    }
-    dir = path.dirname(dir);
-  }
-  // Fallback: assume dev layout (server/routes/ → 2 levels up)
-  return path.resolve(__selfDir, '../..');
-}
-
 async function git(args: string[], cwd: string, timeoutMs = 15_000): Promise<string> {
   const { stdout } = await execFileAsync('git', args, { cwd, timeout: timeoutMs });
   return stdout.trim();

package/server/routes/workflow-routes.ts

@@ -4,6 +4,7 @@ import path from 'node:path';
 import type { WorkflowConfig } from '../../shared/workflow-config.js';
 import type { WorkflowService } from '../services/workflow-service.js';
 import { parseCcHooks } from '../utils/cc-hooks-parser.js';
+import { errMsg } from '../utils/route-helpers.js';
 
 interface WorkflowRouteDeps {
   workflowService: WorkflowService;
@@ -130,6 +131,10 @@ export function createWorkflowRoutes({ workflowService, projectRoot }: WorkflowR
         return;
       }
       const filePath = path.resolve(projectRoot, hook.target);
+      if (!filePath.startsWith(projectRoot + path.sep) && filePath !== projectRoot) {
+        res.status(400).json({ success: false, error: 'Path outside project root' });
+        return;
+      }
       const content = await readFile(filePath, 'utf-8');
       const lineCount = content.split('\n').length;
       res.json({ success: true, data: { hookId, filePath: hook.target, content, lineCount } });
@@ -164,6 +169,10 @@ export function createWorkflowRoutes({ workflowService, projectRoot }: WorkflowR
         return;
       }
       const filePath = path.resolve(projectRoot, hookPath);
+      if (!filePath.startsWith(projectRoot + path.sep) && filePath !== projectRoot) {
+        res.status(400).json({ success: false, error: 'Path outside project root' });
+        return;
+      }
       const content = await readFile(filePath, 'utf-8');
       const lineCount = content.split('\n').length;
       res.json({ success: true, data: { filePath: hookPath, content, lineCount } });
@@ -193,6 +202,3 @@ export function createWorkflowRoutes({ workflowService, projectRoot }: WorkflowR
   return router;
 }
 
-function errMsg(err: unknown): string {
-  return err instanceof Error ? err.message : String(err);
-}

package/server/schema.ts

@@ -81,10 +81,13 @@ CREATE TABLE IF NOT EXISTS sprint_scopes (
 CREATE INDEX IF NOT EXISTS idx_events_type ON events(type);
 CREATE INDEX IF NOT EXISTS idx_events_timestamp ON events(timestamp);
 CREATE INDEX IF NOT EXISTS idx_events_scope_id ON events(scope_id);
+CREATE INDEX IF NOT EXISTS idx_events_type_timestamp ON events(type, timestamp);
 CREATE INDEX IF NOT EXISTS idx_gates_scope_id ON quality_gates(scope_id);
 CREATE INDEX IF NOT EXISTS idx_gates_run_at ON quality_gates(run_at);
 CREATE INDEX IF NOT EXISTS idx_deployments_env ON deployments(environment);
 CREATE INDEX IF NOT EXISTS idx_sessions_scope ON sessions(scope_id);
+CREATE INDEX IF NOT EXISTS idx_sessions_claude_id ON sessions(claude_session_id);
 CREATE INDEX IF NOT EXISTS idx_sprints_status ON sprints(status);
 CREATE INDEX IF NOT EXISTS idx_sprint_scopes_sprint ON sprint_scopes(sprint_id);
+CREATE INDEX IF NOT EXISTS idx_events_dispatch_unresolved ON events(type, scope_id) WHERE type = 'DISPATCH' AND JSON_EXTRACT(data, '$.resolved') IS NULL;
 `;

package/server/services/batch-orchestrator.ts

@@ -1,11 +1,12 @@
 import type Database from 'better-sqlite3';
-import type { Server } from 'socket.io';
+import type { Emitter } from '../project-emitter.js';
 import type { SprintService } from './sprint-service.js';
 import type { ScopeService } from './scope-service.js';
-import { launchInCategorizedTerminal, escapeForAnsiC, snapshotSessionPids, discoverNewSession, isSessionPidAlive } from '../utils/terminal-launcher.js';
+import { launchInCategorizedTerminal, escapeForAnsiC, shellQuote, snapshotSessionPids, discoverNewSession, isSessionPidAlive } from '../utils/terminal-launcher.js';
 import { linkPidToDispatch, resolveDispatchEvent } from '../utils/dispatch-utils.js';
 import type { WorkflowEngine } from '../../shared/workflow-engine.js';
-import { getConfig } from '../config.js';
+import type { OrbitalConfig } from '../config.js';
+import { buildClaudeFlags, buildEnvVarPrefix } from '../utils/flag-builder.js';
 import { createLogger } from '../utils/logger.js';
 
 const log = createLogger('batch');
@@ -16,10 +17,12 @@ const VALID_MERGE_MODES = ['push', 'pr'] as const;
 export class BatchOrchestrator {
   constructor(
     private db: Database.Database,
-    private io: Server,
+    private io: Emitter,
     private sprintService: SprintService,
     private scopeService: ScopeService,
     private engine: WorkflowEngine,
+    private projectRoot: string,
+    private config: OrbitalConfig,
   ) {}
 
   /** Dispatch a batch — validates constraints and routes to column-specific handler */
@@ -70,8 +73,10 @@ export class BatchOrchestrator {
 
     // Launch single CLI session with BATCH_SCOPE_IDS prepended to command
     const escaped = escapeForAnsiC(command);
-    const fullCmd = `cd '${getConfig().projectRoot}' && BATCH_SCOPE_IDS='${scopeIdsStr}' MERGE_MODE='${mergeModeStr}' claude --dangerously-skip-permissions $'${escaped}'`;
-    const beforePids = snapshotSessionPids(getConfig().projectRoot);
+    const flagsStr = buildClaudeFlags(this.config.claude.dispatchFlags);
+    const envPrefix = buildEnvVarPrefix(this.config.dispatch.envVars);
+    const fullCmd = `cd '${shellQuote(this.projectRoot)}' && ${envPrefix}ORBITAL_DISPATCH_ID='${shellQuote(eventId)}' BATCH_SCOPE_IDS='${scopeIdsStr}' MERGE_MODE='${mergeModeStr}' claude ${flagsStr} $'${escaped}'`;
+    const beforePids = snapshotSessionPids(this.projectRoot);
 
     try {
       await launchInCategorizedTerminal(command, fullCmd);
@@ -82,7 +87,7 @@ export class BatchOrchestrator {
       });
 
       // Fire-and-forget: discover session PID and link to dispatch
-      discoverNewSession(getConfig().projectRoot, beforePids)
+      discoverNewSession(this.projectRoot, beforePids)
         .then((session) => {
           if (!session) return;
           linkPidToDispatch(this.db, eventId, session.pid);
@@ -106,7 +111,7 @@ export class BatchOrchestrator {
     } catch (err) {
       this.sprintService.updateStatus(batchId, 'failed');
       resolveDispatchEvent(this.db, this.io, eventId, 'failed', String(err));
-      return { ok: false, error: `Failed to launch terminal: ${err}` };
+      return { ok: false, error: `Failed to launch terminal: ${err instanceof Error ? err.message : String(err)}` };
     }
   }
 
@@ -148,6 +153,17 @@ export class BatchOrchestrator {
     if (batch.status !== 'dispatched' && batch.status !== 'in_progress') return;
 
     const scopes = this.sprintService.getSprintScopes(batchId);
+
+    // If batch never reached 'in_progress', the session never started —
+    // don't credit any scope regardless of their current workflow status
+    if (batch.status === 'dispatched') {
+      this.sprintService.updateStatus(batchId, 'failed');
+      for (const ss of scopes) {
+        this.sprintService.updateScopeStatus(batchId, ss.scope_id, 'failed', 'Session never started');
+      }
+      return;
+    }
+
     const allTransitioned = scopes.every((ss) => ss.dispatch_status === 'completed');
 
     if (allTransitioned) {
@@ -210,16 +226,24 @@ export class BatchOrchestrator {
       let pidDead = false;
 
       if (dispatchEvent) {
-        const data = JSON.parse(dispatchEvent.data) as Record<string, unknown>;
-        // If the dispatch event is already resolved, the session is definitely done
-        if (data.resolved != null) {
+        let data: Record<string, unknown>;
+        try {
+          data = JSON.parse(dispatchEvent.data) as Record<string, unknown>;
+        } catch {
           pidDead = true;
-        } else if (typeof data.pid === 'number') {
-          pidDead = !isSessionPidAlive(data.pid);
-        } else {
-          // No PID recorded — check if batch is old enough to consider stale
-          const dispatchedAt = batch.dispatched_at ? new Date(batch.dispatched_at).getTime() : 0;
-          pidDead = Date.now() - dispatchedAt > STALE_THRESHOLD_MS;
+          // Fall through to resolution below
+        }
+        if (!pidDead) {
+          // If the dispatch event is already resolved, the session is definitely done
+          if (data!.resolved != null) {
+            pidDead = true;
+          } else if (typeof data!.pid === 'number') {
+            pidDead = !isSessionPidAlive(data!.pid);
+          } else {
+            // No PID recorded — check if batch is old enough to consider stale
+            const dispatchedAt = batch.dispatched_at ? new Date(batch.dispatched_at).getTime() : 0;
+            pidDead = Date.now() - dispatchedAt > STALE_THRESHOLD_MS;
+          }
         }
       } else {
         // No dispatch event at all — check age

package/server/services/claude-session-service.ts

@@ -3,7 +3,7 @@ import path from 'path';
 import readline from 'readline';
 import type Database from 'better-sqlite3';
 import type { ScopeService } from './scope-service.js';
-import { getConfig, getClaudeSessionsDir } from '../config.js';
+import { getClaudeSessionsDir } from '../config.js';
 
 export interface ClaudeSession {
   id: string;
@@ -59,11 +59,12 @@ export interface SessionStats {
   };
 }
 
-function getSessionsDir(): string {
-  return getClaudeSessionsDir(getConfig().projectRoot);
+function getSessionsDir(projectRoot?: string): string {
+  if (!projectRoot) throw new Error('projectRoot is required for getSessionsDir');
+  return getClaudeSessionsDir(projectRoot);
 }
 
-let cache: { sessions: ClaudeSession[]; expiry: number } | null = null;
+const cacheByDir = new Map<string, { sessions: ClaudeSession[]; expiry: number }>();
 const CACHE_TTL_MS = 60_000;
 
 /**
@@ -146,12 +147,13 @@ async function parseSessionFile(filePath: string): Promise<ClaudeSession | null>
   };
 }
 
-export async function getClaudeSessions(since?: string): Promise<ClaudeSession[]> {
-  if (cache && Date.now() < cache.expiry) {
-    return filterSince(cache.sessions, since);
+export async function getClaudeSessions(since?: string, projectRoot?: string): Promise<ClaudeSession[]> {
+  const sessionsDir = getSessionsDir(projectRoot);
+  const cached = cacheByDir.get(sessionsDir);
+  if (cached && Date.now() < cached.expiry) {
+    return filterSince(cached.sessions, since);
   }
 
-  const sessionsDir = getSessionsDir();
   if (!fs.existsSync(sessionsDir)) return [];
 
   const files = fs
@@ -171,7 +173,7 @@ export async function getClaudeSessions(since?: string): Promise<ClaudeSession[]
     (a, b) => new Date(b.lastActiveAt).getTime() - new Date(a.lastActiveAt).getTime(),
   );
 
-  cache = { sessions, expiry: Date.now() + CACHE_TTL_MS };
+  cacheByDir.set(sessionsDir, { sessions, expiry: Date.now() + CACHE_TTL_MS });
   return filterSince(sessions, since);
 }
 
@@ -248,8 +250,8 @@ function extractFirstUserMessage(lines: string[], max: number): string | null {
  * Parse a full JSONL file and return detailed stats grouped by line type.
  * This is heavier than parseSessionFile — only called for the detail view.
  */
-export function getSessionStats(claudeSessionId: string): SessionStats | null {
-  const filePath = path.join(getSessionsDir(), `${claudeSessionId}.jsonl`);
+export function getSessionStats(claudeSessionId: string, projectRoot?: string): SessionStats | null {
+  const filePath = path.join(getSessionsDir(projectRoot), `${claudeSessionId}.jsonl`);
   if (!fs.existsSync(filePath)) return null;
 
   const stats: SessionStats = {
@@ -360,8 +362,8 @@ export function getSessionStats(claudeSessionId: string): SessionStats | null {
  * 2. For each scope, parse the sessions JSON: Record<phase, uuid[]>
  * 3. For each (phase, uuid), UPSERT into sessions table with JSONL metadata if available
  */
-export async function syncClaudeSessionsToDB(db: Database.Database, scopeService: ScopeService): Promise<number> {
-  cache = null; // Force fresh read from filesystem
+export async function syncClaudeSessionsToDB(db: Database.Database, scopeService: ScopeService, projectRoot?: string): Promise<number> {
+  cacheByDir.clear(); // Force fresh read from filesystem
 
   const scopeRows = scopeService.getAll()
     .filter(s => Object.keys(s.sessions).length > 0)
@@ -389,7 +391,7 @@ export async function syncClaudeSessionsToDB(db: Database.Database, scopeService
           if (typeof uuid !== 'string' || !uuid) continue;
 
           // Check if JSONL file exists for metadata enrichment
-          const jsonlPath = path.join(getSessionsDir(), `${uuid}.jsonl`);
+          const jsonlPath = path.join(getSessionsDir(projectRoot), `${uuid}.jsonl`);
           let startedAt: string | null = null;
           let endedAt: string | null = null;
           let summary: string | null = null;

package/server/services/config-service.ts

@@ -120,7 +120,16 @@ export class ConfigService {
       const fullPath = path.join(currentPath, entry.name);
       const relPath = path.relative(basePath, fullPath);
 
-      if (entry.isDirectory()) {
+      // Resolve symlinks: Dirent.isDirectory() returns false for symlinks-to-dirs.
+      // Self-hosted projects symlink .claude/agents/*, .claude/hooks/*, etc. into templates/.
+      let stat: fs.Stats;
+      try {
+        stat = fs.statSync(fullPath);
+      } catch {
+        continue; // broken symlink — skip silently
+      }
+
+      if (stat.isDirectory()) {
         const children = this.walkDir(fullPath, basePath, parseFrontmatter);
         nodes.push({ name: entry.name, path: relPath, type: 'folder', children });
       } else {

package/server/services/deploy-service.test.ts

@@ -0,0 +1,145 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { DeployService } from './deploy-service.js';
+import { createTestDb } from '../__tests__/helpers/db.js';
+import { createMockEmitter } from '../__tests__/helpers/mock-emitter.js';
+import type Database from 'better-sqlite3';
+import type { Emitter } from '../project-emitter.js';
+
+describe('DeployService', () => {
+  let db: Database.Database;
+  let cleanup: () => void;
+  let emitter: Emitter & { emit: ReturnType<typeof vi.fn> };
+  let service: DeployService;
+
+  beforeEach(() => {
+    ({ db, cleanup } = createTestDb());
+    emitter = createMockEmitter();
+    service = new DeployService(db, emitter);
+  });
+
+  afterEach(() => {
+    cleanup?.();
+  });
+
+  // ─── record() ─────────────────────────────────────────────
+
+  describe('record()', () => {
+    it('inserts deployment and returns ID', () => {
+      const id = service.record({
+        environment: 'staging',
+        status: 'deploying',
+        commit_sha: 'abc1234',
+        branch: 'main',
+        pr_number: null,
+        health_check_url: null,
+        details: null,
+      });
+
+      expect(id).toBe(1);
+      const row = db.prepare('SELECT * FROM deployments WHERE id = ?').get(id) as Record<string, unknown>;
+      expect(row.environment).toBe('staging');
+      expect(row.status).toBe('deploying');
+    });
+
+    it('emits deploy:updated with inserted row', () => {
+      service.record({
+        environment: 'production',
+        status: 'deploying',
+        commit_sha: 'def5678',
+        branch: 'main',
+        pr_number: 42,
+        health_check_url: 'https://example.com/health',
+        details: { version: '1.0.0' },
+      });
+
+      expect(emitter.emit).toHaveBeenCalledWith('deploy:updated', expect.objectContaining({
+        environment: 'production',
+        branch: 'main',
+        pr_number: 42,
+      }));
+    });
+  });
+
+  // ─── updateStatus() ──────────────────────────────────────
+
+  describe('updateStatus()', () => {
+    let deployId: number;
+
+    beforeEach(() => {
+      deployId = service.record({
+        environment: 'staging',
+        status: 'deploying',
+        commit_sha: 'abc',
+        branch: 'main',
+        pr_number: null,
+        health_check_url: null,
+        details: null,
+      });
+    });
+
+    it('updates status and emits deploy:updated', () => {
+      service.updateStatus(deployId, 'healthy');
+
+      const row = db.prepare('SELECT * FROM deployments WHERE id = ?').get(deployId) as Record<string, unknown>;
+      expect(row.status).toBe('healthy');
+      // 1 from record + 1 from updateStatus
+      expect(emitter.emit).toHaveBeenCalledTimes(2);
+    });
+
+    it('sets completed_at for terminal status: healthy', () => {
+      service.updateStatus(deployId, 'healthy');
+      const row = db.prepare('SELECT completed_at FROM deployments WHERE id = ?').get(deployId) as { completed_at: string | null };
+      expect(row.completed_at).not.toBeNull();
+      expect(row.completed_at).toMatch(/^\d{4}-\d{2}-\d{2}T/);
+    });
+
+    it('sets completed_at for terminal status: failed', () => {
+      service.updateStatus(deployId, 'failed');
+      const row = db.prepare('SELECT completed_at FROM deployments WHERE id = ?').get(deployId) as { completed_at: string | null };
+      expect(row.completed_at).not.toBeNull();
+    });
+
+    it('sets completed_at for terminal status: rolled-back', () => {
+      service.updateStatus(deployId, 'rolled-back');
+      const row = db.prepare('SELECT completed_at FROM deployments WHERE id = ?').get(deployId) as { completed_at: string | null };
+      expect(row.completed_at).not.toBeNull();
+    });
+
+    it('does not set completed_at for non-terminal status', () => {
+      service.updateStatus(deployId, 'deploying');
+      const row = db.prepare('SELECT completed_at FROM deployments WHERE id = ?').get(deployId) as { completed_at: string | null };
+      expect(row.completed_at).toBeNull();
+    });
+  });
+
+  // ─── getRecent() ──────────────────────────────────────────
+
+  describe('getRecent()', () => {
+    it('returns deployments ordered by started_at DESC with limit', () => {
+      service.record({ environment: 'staging', status: 'healthy', commit_sha: 'a', branch: 'main', pr_number: null, health_check_url: null, details: null });
+      service.record({ environment: 'production', status: 'deploying', commit_sha: 'b', branch: 'main', pr_number: null, health_check_url: null, details: null });
+
+      const recent = service.getRecent(1);
+      expect(recent).toHaveLength(1);
+    });
+  });
+
+  // ─── getLatestPerEnv() ────────────────────────────────────
+
+  describe('getLatestPerEnv()', () => {
+    it('returns one deployment per environment', () => {
+      service.record({ environment: 'staging', status: 'healthy', commit_sha: 'a', branch: 'main', pr_number: null, health_check_url: null, details: null });
+      service.record({ environment: 'staging', status: 'deploying', commit_sha: 'b', branch: 'main', pr_number: null, health_check_url: null, details: null });
+      service.record({ environment: 'production', status: 'healthy', commit_sha: 'c', branch: 'main', pr_number: null, health_check_url: null, details: null });
+
+      const latest = service.getLatestPerEnv();
+      expect(latest).toHaveLength(2);
+      const envs = latest.map(d => d.environment).sort();
+      expect(envs).toEqual(['production', 'staging']);
+    });
+
+    it('returns empty when no deployments exist', () => {
+      expect(service.getLatestPerEnv()).toEqual([]);
+    });
+  });
+});

package/server/services/deploy-service.ts

@@ -1,5 +1,5 @@
 import type Database from 'better-sqlite3';
-import type { Server } from 'socket.io';
+import type { Emitter } from '../project-emitter.js';
 import type { DeployStatus, DeployEnvironment } from '../../shared/api-types.js';
 import { createLogger } from '../utils/logger.js';
 
@@ -31,7 +31,7 @@ export interface DeployRow {
 export class DeployService {
   constructor(
     private db: Database.Database,
-    private io: Server
+    private io: Emitter
   ) {}
 
   /** Record a deployment event */