orbital-command 0.1.4 → 0.3.0

package/server/utils/cc-hooks-parser.test.ts

@@ -0,0 +1,96 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import { parseCcHooks } from './cc-hooks-parser.js';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+
+describe('parseCcHooks', () => {
+  let tmpFile: string;
+
+  function writeSettings(data: Record<string, unknown>): string {
+    tmpFile = path.join(os.tmpdir(), `test-settings-${Date.now()}.json`);
+    fs.writeFileSync(tmpFile, JSON.stringify(data));
+    return tmpFile;
+  }
+
+  afterEach(() => {
+    if (tmpFile && fs.existsSync(tmpFile)) fs.unlinkSync(tmpFile);
+  });
+
+  it('parses all 4 event types', () => {
+    const file = writeSettings({
+      hooks: {
+        SessionStart: [{ hooks: [{ type: 'command', command: '$CLAUDE_PROJECT_DIR/.claude/hooks/init.sh', statusMessage: 'Initializing' }] }],
+        SessionEnd: [{ hooks: [{ type: 'command', command: '$CLAUDE_PROJECT_DIR/.claude/hooks/end.sh' }] }],
+        PreToolUse: [{ matcher: 'Edit', hooks: [{ type: 'command', command: '$CLAUDE_PROJECT_DIR/.claude/hooks/guard.sh', statusMessage: 'Checking' }] }],
+        PostToolUse: [{ hooks: [{ type: 'command', command: '$CLAUDE_PROJECT_DIR/.claude/hooks/log.sh' }] }],
+      },
+    });
+    const hooks = parseCcHooks(file);
+    expect(hooks).toHaveLength(4);
+    expect(hooks.map(h => h.event)).toEqual(['SessionStart', 'SessionEnd', 'PreToolUse', 'PostToolUse']);
+  });
+
+  it('extracts script path stripping $CLAUDE_PROJECT_DIR', () => {
+    const file = writeSettings({
+      hooks: {
+        SessionStart: [{ hooks: [{ type: 'command', command: '$CLAUDE_PROJECT_DIR/.claude/hooks/init-session.sh' }] }],
+      },
+    });
+    const hooks = parseCcHooks(file);
+    expect(hooks[0].scriptPath).toBe('.claude/hooks/init-session.sh');
+    expect(hooks[0].scriptName).toBe('init-session.sh');
+  });
+
+  it('derives ID from script filename', () => {
+    const file = writeSettings({
+      hooks: {
+        SessionStart: [{ hooks: [{ type: 'command', command: '$CLAUDE_PROJECT_DIR/.claude/hooks/init-session.sh' }] }],
+      },
+    });
+    const hooks = parseCcHooks(file);
+    expect(hooks[0].id).toBe('init-session');
+  });
+
+  it('extracts matcher from group', () => {
+    const file = writeSettings({
+      hooks: {
+        PreToolUse: [{ matcher: 'Edit', hooks: [{ type: 'command', command: 'test.sh' }] }],
+      },
+    });
+    const hooks = parseCcHooks(file);
+    expect(hooks[0].matcher).toBe('Edit');
+  });
+
+  it('sets matcher to null when absent', () => {
+    const file = writeSettings({
+      hooks: {
+        SessionStart: [{ hooks: [{ type: 'command', command: 'test.sh' }] }],
+      },
+    });
+    const hooks = parseCcHooks(file);
+    expect(hooks[0].matcher).toBeNull();
+  });
+
+  it('skips non-command entries', () => {
+    const file = writeSettings({
+      hooks: {
+        SessionStart: [{ hooks: [
+          { type: 'command', command: 'test.sh' },
+          { type: 'url', command: 'https://example.com' },
+        ] }],
+      },
+    });
+    const hooks = parseCcHooks(file);
+    expect(hooks).toHaveLength(1);
+  });
+
+  it('returns empty array for file not found', () => {
+    expect(parseCcHooks('/tmp/nonexistent-settings.json')).toEqual([]);
+  });
+
+  it('returns empty array when no hooks key in settings', () => {
+    const file = writeSettings({ other: 'config' });
+    expect(parseCcHooks(file)).toEqual([]);
+  });
+});

package/server/utils/cc-hooks-parser.ts

@@ -1,6 +1,9 @@
 import { readFileSync } from 'node:fs';
+import { createLogger } from './logger.js';
 import type { CcHookEvent, CcHookParsed } from '../../shared/workflow-config.js';
 
+const log = createLogger('config');
+
 const CC_HOOK_EVENTS: CcHookEvent[] = ['SessionStart', 'SessionEnd', 'PreToolUse', 'PostToolUse'];
 
 interface SettingsHookEntry {
@@ -36,6 +39,7 @@ export function parseCcHooks(settingsPath: string): CcHookParsed[] {
   try {
     raw = readFileSync(settingsPath, 'utf-8');
   } catch {
+    log.debug('Settings file not found', { path: settingsPath });
     return [];
   }
 

package/server/utils/dispatch-utils.test.ts

@@ -0,0 +1,245 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import {
+  resolveDispatchEvent,
+  resolveActiveDispatchesForScope,
+  resolveAbandonedDispatchesForScope,
+  linkPidToDispatch,
+  resolveDispatchesByPid,
+  resolveDispatchesByDispatchId,
+  getActiveScopeIds,
+  getAbandonedScopeIds,
+} from './dispatch-utils.js';
+import { createTestDb } from '../__tests__/helpers/db.js';
+import { createMockEmitter } from '../__tests__/helpers/mock-emitter.js';
+import { WorkflowEngine } from '../../shared/workflow-engine.js';
+import { CONFIG_WITH_HOOKS } from '../../shared/__fixtures__/workflow-configs.js';
+import type Database from 'better-sqlite3';
+import type { Emitter } from '../project-emitter.js';
+
+// Mock isSessionPidAlive since it checks real OS processes
+vi.mock('./terminal-launcher.js', () => ({
+  isSessionPidAlive: vi.fn().mockReturnValue(false),
+  launchInTerminal: vi.fn(),
+  buildSessionName: vi.fn(),
+  snapshotSessionPids: vi.fn().mockReturnValue([]),
+  discoverNewSession: vi.fn(),
+  renameSession: vi.fn(),
+  launchInCategorizedTerminal: vi.fn(),
+}));
+
+function insertDispatchEvent(db: Database.Database, overrides: Record<string, unknown> = {}) {
+  const id = overrides.id ?? `dispatch-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`;
+  const data = JSON.stringify({
+    command: '/scope-implement 1',
+    transition: { from: 'backlog', to: 'active' },
+    ...(overrides.data as Record<string, unknown> ?? {}),
+  });
+  db.prepare(
+    `INSERT INTO events (id, type, scope_id, session_id, agent, data, timestamp)
+     VALUES (?, 'DISPATCH', ?, ?, NULL, ?, ?)`
+  ).run(
+    id,
+    overrides.scope_id ?? 1,
+    overrides.session_id ?? 'sess-1',
+    data,
+    overrides.timestamp ?? new Date().toISOString(),
+  );
+  return id as string;
+}
+
+describe('dispatch-utils', () => {
+  let db: Database.Database;
+  let cleanup: () => void;
+  let emitter: Emitter & { emit: ReturnType<typeof vi.fn> };
+  let engine: WorkflowEngine;
+
+  beforeEach(() => {
+    ({ db, cleanup } = createTestDb());
+    emitter = createMockEmitter();
+    engine = new WorkflowEngine(CONFIG_WITH_HOOKS);
+  });
+
+  afterEach(() => {
+    cleanup?.();
+  });
+
+  // ─── resolveDispatchEvent() ───────────────────────────────
+
+  describe('resolveDispatchEvent()', () => {
+    it('marks dispatch as resolved with outcome', () => {
+      const id = insertDispatchEvent(db);
+      resolveDispatchEvent(db, emitter, id, 'completed');
+
+      const row = db.prepare('SELECT data FROM events WHERE id = ?').get(id) as { data: string };
+      const data = JSON.parse(row.data);
+      expect(data.resolved).toBeDefined();
+      expect(data.resolved.outcome).toBe('completed');
+      expect(data.resolved.at).toBeDefined();
+    });
+
+    it('emits dispatch:resolved event', () => {
+      const id = insertDispatchEvent(db);
+      resolveDispatchEvent(db, emitter, id, 'completed');
+      expect(emitter.emit).toHaveBeenCalledWith('dispatch:resolved', expect.objectContaining({ event_id: id }));
+    });
+
+    it('stores error message for failed dispatches', () => {
+      const id = insertDispatchEvent(db);
+      resolveDispatchEvent(db, emitter, id, 'failed', 'Timeout');
+
+      const row = db.prepare('SELECT data FROM events WHERE id = ?').get(id) as { data: string };
+      const data = JSON.parse(row.data);
+      expect(data.resolved.outcome).toBe('failed');
+      expect(data.resolved.error).toBe('Timeout');
+    });
+  });
+
+  // ─── resolveActiveDispatchesForScope() ────────────────────
+
+  describe('resolveActiveDispatchesForScope()', () => {
+    it('resolves all unresolved dispatches for a scope', () => {
+      insertDispatchEvent(db, { id: 'd1', scope_id: 42 });
+      insertDispatchEvent(db, { id: 'd2', scope_id: 42 });
+      insertDispatchEvent(db, { id: 'd3', scope_id: 99 }); // different scope
+
+      resolveActiveDispatchesForScope(db, emitter, 42, 'completed');
+
+      const rows = db.prepare("SELECT data FROM events WHERE scope_id = 42").all() as Array<{ data: string }>;
+      for (const row of rows) {
+        const data = JSON.parse(row.data);
+        expect(data.resolved).toBeDefined();
+        expect(data.resolved.outcome).toBe('completed');
+      }
+
+      // Scope 99 should NOT be resolved
+      const other = db.prepare("SELECT data FROM events WHERE scope_id = 99").get() as { data: string };
+      expect(JSON.parse(other.data).resolved).toBeUndefined();
+    });
+
+    it('handles no active dispatches gracefully', () => {
+      expect(() => resolveActiveDispatchesForScope(db, emitter, 999, 'completed')).not.toThrow();
+    });
+  });
+
+  // ─── resolveAbandonedDispatchesForScope() ─────────────────
+
+  describe('resolveAbandonedDispatchesForScope()', () => {
+    it('resolves abandoned dispatches as completed', () => {
+      insertDispatchEvent(db, { scope_id: 42, data: { resolved: true, outcome: 'abandoned' } });
+      const count = resolveAbandonedDispatchesForScope(db, emitter, 42);
+      expect(count).toBeGreaterThanOrEqual(0);
+    });
+  });
+
+  // ─── linkPidToDispatch() ──────────────────────────────────
+
+  describe('linkPidToDispatch()', () => {
+    it('stores PID in event data', () => {
+      const id = insertDispatchEvent(db);
+      linkPidToDispatch(db, id, 12345);
+
+      const row = db.prepare('SELECT data FROM events WHERE id = ?').get(id) as { data: string };
+      const data = JSON.parse(row.data);
+      expect(data.pid).toBe(12345);
+    });
+
+    it('handles non-existent event gracefully', () => {
+      expect(() => linkPidToDispatch(db, 'nonexistent', 12345)).not.toThrow();
+    });
+  });
+
+  // ─── resolveDispatchesByPid() ─────────────────────────────
+
+  describe('resolveDispatchesByPid()', () => {
+    it('resolves dispatches matching PID', () => {
+      const id = insertDispatchEvent(db, { scope_id: 1 });
+      linkPidToDispatch(db, id, 54321);
+
+      const ids = resolveDispatchesByPid(db, emitter, 54321);
+      expect(ids).toHaveLength(1);
+      expect(ids[0]).toBe(id);
+
+      const row = db.prepare('SELECT data FROM events WHERE id = ?').get(id) as { data: string };
+      expect(JSON.parse(row.data).resolved).toBeDefined();
+    });
+
+    it('returns empty array when no dispatches match PID', () => {
+      expect(resolveDispatchesByPid(db, emitter, 99999)).toHaveLength(0);
+    });
+  });
+
+  // ─── resolveDispatchesByDispatchId() ──────────────────────
+
+  describe('resolveDispatchesByDispatchId()', () => {
+    it('resolves single dispatch by event ID', () => {
+      const id = insertDispatchEvent(db);
+      const ids = resolveDispatchesByDispatchId(db, emitter, id);
+      expect(ids).toHaveLength(1);
+      expect(ids[0]).toBe(id);
+    });
+
+    it('returns empty array for non-existent dispatch', () => {
+      expect(resolveDispatchesByDispatchId(db, emitter, 'nonexistent')).toHaveLength(0);
+    });
+  });
+
+  // ─── getActiveScopeIds() ──────────────────────────────────
+
+  describe('getActiveScopeIds()', () => {
+    it('returns scope IDs with unresolved dispatches', () => {
+      insertDispatchEvent(db, { scope_id: 10 });
+      insertDispatchEvent(db, { scope_id: 20 });
+
+      const mockScopeService = {
+        getById: (id: number) => ({ id, status: 'active' }),
+      } as any;
+
+      const ids = getActiveScopeIds(db, mockScopeService, engine);
+      // May return empty if dispatches are stale (PID check fails), but shouldn't throw
+      expect(Array.isArray(ids)).toBe(true);
+    });
+
+    it('excludes scopes in terminal status', () => {
+      insertDispatchEvent(db, { scope_id: 30 });
+      const mockScopeService = {
+        getById: (id: number) => ({ id, status: 'shipped' }), // terminal
+      } as any;
+
+      const ids = getActiveScopeIds(db, mockScopeService, engine);
+      expect(ids).not.toContain(30);
+    });
+  });
+
+  // ─── getAbandonedScopeIds() ───────────────────────────────
+
+  describe('getAbandonedScopeIds()', () => {
+    it('returns recently abandoned scopes', () => {
+      insertDispatchEvent(db, {
+        scope_id: 50,
+        data: { resolved: true, outcome: 'abandoned', resolved_at: new Date().toISOString(), transition: { from: 'backlog', to: 'active' } },
+      });
+
+      const mockScopeService = {
+        getById: (id: number) => ({ id, status: 'active' }),
+      } as any;
+
+      const abandoned = getAbandonedScopeIds(db, mockScopeService, engine);
+      expect(Array.isArray(abandoned)).toBe(true);
+    });
+
+    it('excludes terminal scopes', () => {
+      insertDispatchEvent(db, {
+        scope_id: 60,
+        data: { resolved: true, outcome: 'abandoned', resolved_at: new Date().toISOString(), transition: { from: 'review', to: 'shipped' } },
+      });
+
+      const mockScopeService = {
+        getById: (id: number) => ({ id, status: 'shipped' }), // terminal
+      } as any;
+
+      const abandoned = getAbandonedScopeIds(db, mockScopeService, engine);
+      const ids = abandoned.map(a => a.scope_id);
+      expect(ids).not.toContain(60);
+    });
+  });
+});

package/server/utils/dispatch-utils.ts

@@ -1,11 +1,11 @@
 import type Database from 'better-sqlite3';
-import type { Server } from 'socket.io';
+import type { Emitter } from '../project-emitter.js';
 import type { ScopeService } from '../services/scope-service.js';
 import type { WorkflowEngine } from '../../shared/workflow-engine.js';
 import { isSessionPidAlive } from './terminal-launcher.js';
 import { createLogger } from './logger.js';
 
-const log = createLogger('dispatch');
+const log = createLogger('dispatch-utils');
 
 interface DispatchRow {
   data: string;
@@ -15,7 +15,7 @@ interface DispatchRow {
 /** Mark a DISPATCH event as resolved and emit socket notification. */
 export function resolveDispatchEvent(
   db: Database.Database,
-  io: Server,
+  io: Emitter,
   eventId: string,
   outcome: 'completed' | 'failed' | 'abandoned',
   error?: string,
@@ -42,10 +42,73 @@ export function resolveDispatchEvent(
   });
 }
 
+/** Auto-revert scope status when a dispatch is abandoned, if the forward edge
+ *  has autoRevert=true and the scope is still at the dispatch target.
+ *  Safe: only reverts if the scope hasn't been moved since the dispatch.
+ *  Returns true if revert was successful. */
+function autoRevertAbandonedScope(
+  scopeService: ScopeService,
+  engine: WorkflowEngine,
+  scopeId: number,
+  data: Record<string, unknown>,
+): boolean {
+  try {
+    const transition = data.transition as { from: string; to: string } | null;
+    if (!transition?.from || !transition?.to) return false;
+
+    const scope = scopeService.getById(scopeId);
+    // Only revert if scope is still at the dispatch target (hasn't been moved)
+    if (!scope || scope.status !== transition.to) return false;
+
+    const edge = engine.findEdge(transition.from, transition.to);
+    if (!edge?.autoRevert) return false;
+
+    const result = scopeService.updateStatus(scopeId, transition.from, 'rollback');
+    if (!result.ok) return false;
+    log.info('Auto-reverted abandoned dispatch', {
+      scopeId, from: transition.to, to: transition.from,
+    });
+    return true;
+  } catch (err) {
+    log.error('Auto-revert failed', { scopeId, error: String(err) });
+    return false;
+  }
+}
+
+/** Attempt auto-revert for an abandoned dispatch and clear the abandoned state if successful.
+ *  Loads the dispatch event data, tries auto-revert, and re-resolves as 'completed' if the
+ *  scope was successfully reverted. Returns true if auto-revert + clear succeeded. */
+export function tryAutoRevertAndClear(
+  db: Database.Database,
+  io: Emitter,
+  scopeService: ScopeService,
+  engine: WorkflowEngine,
+  eventId: string,
+): boolean {
+  const row = db.prepare('SELECT data, scope_id FROM events WHERE id = ?')
+    .get(eventId) as DispatchRow | undefined;
+  if (!row || row.scope_id == null) return false;
+
+  let data: Record<string, unknown>;
+  try {
+    data = JSON.parse(row.data);
+  } catch {
+    return false;
+  }
+
+  const reverted = autoRevertAbandonedScope(scopeService, engine, row.scope_id, data);
+  if (reverted) {
+    // Clear the abandoned state so getAbandonedScopeIds won't return this scope
+    resolveDispatchEvent(db, io, eventId, 'completed');
+    log.info('Cleared abandoned dispatch after auto-revert', { eventId, scope_id: row.scope_id });
+  }
+  return reverted;
+}
+
 /** Resolve all unresolved DISPATCH events for a given scope */
 export function resolveActiveDispatchesForScope(
   db: Database.Database,
-  io: Server,
+  io: Emitter,
   scopeId: number,
   outcome: 'completed' | 'failed' | 'abandoned',
 ): void {
@@ -63,7 +126,7 @@ export function resolveActiveDispatchesForScope(
  *  Used by both recover and dismiss-abandoned routes to clear abandoned state. */
 export function resolveAbandonedDispatchesForScope(
   db: Database.Database,
-  io: Server,
+  io: Emitter,
   scopeId: number,
 ): number {
   const rows = db.prepare(
@@ -104,15 +167,13 @@ export function linkPidToDispatch(
 /** Resolve all unresolved DISPATCH events linked to a specific PID.
  *  Called when a SESSION_END event is received, indicating the Claude session
  *  process has exited and its dispatches should be cleared.
- *
- *  NOTE: Does NOT revert scope status. Skills like /scope-implement intentionally
- *  keep scopes at the transition target (e.g. "implementing") after completion.
- *  Reverting on session end was destroying completed work and deleting scope files. */
+ *  Returns the resolved event IDs so callers can attempt auto-revert. */
 export function resolveDispatchesByPid(
   db: Database.Database,
-  io: Server,
+  io: Emitter,
   pid: number,
-): number {
+  outcome: 'completed' | 'abandoned' = 'abandoned',
+): string[] {
   const rows = db.prepare(
     `SELECT id FROM events
      WHERE type = 'DISPATCH'
@@ -121,33 +182,34 @@ export function resolveDispatchesByPid(
   ).all(pid) as Array<{ id: string }>;
 
   for (const row of rows) {
-    resolveDispatchEvent(db, io, row.id, 'abandoned');
+    resolveDispatchEvent(db, io, row.id, outcome);
   }
 
-  return rows.length;
+  return rows.map(r => r.id);
 }
 
 /** Resolve all unresolved DISPATCH events linked to a specific dispatch ID.
  *  Called when a SESSION_END event includes dispatch_id from ORBITAL_DISPATCH_ID env var.
- *  Defaults to 'abandoned' — successful completions emit AGENT_COMPLETED first
- *  which resolves via inferScopeStatus as 'completed'. */
+ *  Outcome depends on how the session ended: normal_exit → completed, otherwise → abandoned.
+ *  Returns the resolved event IDs so callers can attempt auto-revert. */
 export function resolveDispatchesByDispatchId(
   db: Database.Database,
-  io: Server,
+  io: Emitter,
   dispatchId: string,
-): number {
+  outcome: 'completed' | 'abandoned' = 'abandoned',
+): string[] {
   const row = db.prepare(
     `SELECT id FROM events
      WHERE id = ? AND type = 'DISPATCH' AND JSON_EXTRACT(data, '$.resolved') IS NULL`,
   ).get(dispatchId) as { id: string } | undefined;
 
-  if (!row) return 0;
-  resolveDispatchEvent(db, io, row.id, 'abandoned');
-  return 1;
+  if (!row) return [];
+  resolveDispatchEvent(db, io, row.id, outcome);
+  return [row.id];
 }
 
-/** Fallback age threshold for dispatches without a linked PID (30 minutes). */
-const STALE_AGE_MS = 30 * 60 * 1000;
+/** Fallback age threshold for dispatches without a linked PID (10 minutes). */
+const STALE_AGE_MS = 10 * 60 * 1000;
 
 /** Get all scope IDs that have actively running DISPATCH events.
  *  Uses PID liveness (process.kill(pid, 0)) when available, falls back to
@@ -209,6 +271,7 @@ export function getActiveScopeIds(db: Database.Database, scopeService: ScopeServ
     try {
       batchData = JSON.parse(batchRow.data);
     } catch {
+      log.warn('Skipping unparseable batch dispatch event data', { data: batchRow.data });
       continue;
     }
 
@@ -242,11 +305,12 @@ export function getActiveScopeIds(db: Database.Database, scopeService: ScopeServ
  *  3. No linked PID and dispatch older than STALE_AGE_MS (fallback)
  *  Called once at startup and periodically to clean up unresolved dispatches.
  *
- *  NOTE: Does NOT revert scope status. Skills like /scope-implement intentionally
- *  keep scopes at the transition target after completion. Auto-reverting was
- *  destroying completed work and deleting scope files. Users can manually
- *  move scopes back from the dashboard if needed. */
-export function resolveStaleDispatches(db: Database.Database, io: Server, scopeService: ScopeService, engine: WorkflowEngine): number {
+ *  When a dispatch is abandoned, auto-reverts scope status if the forward edge
+ *  has autoRevert=true AND the scope is still at the dispatch target. This allows
+ *  safe recovery for edges like backlog→implementing where the session crashed
+ *  before doing meaningful work. Edges without autoRevert leave the scope in place
+ *  for manual recovery from the dashboard. */
+export function resolveStaleDispatches(db: Database.Database, io: Emitter, scopeService: ScopeService, engine: WorkflowEngine): number {
   const cutoff = new Date(Date.now() - STALE_AGE_MS).toISOString();
 
   // Single query on events only — split by cache status
@@ -288,6 +352,8 @@ export function resolveStaleDispatches(db: Database.Database, io: Server, scopeS
 
     if (isStale) {
       resolveDispatchEvent(db, io, row.id, 'abandoned');
+      // Try auto-revert; if successful, clear the abandoned state
+      tryAutoRevertAndClear(db, io, scopeService, engine, row.id);
       resolved++;
     }
   }
@@ -306,6 +372,7 @@ export function resolveStaleDispatches(db: Database.Database, io: Server, scopeS
     try {
       batchData = JSON.parse(batchRow.data);
     } catch {
+      log.warn('Skipping unparseable batch dispatch event data', { eventId: batchRow.id });
       continue;
     }
 
@@ -388,6 +455,9 @@ export function getAbandonedScopeIds(
     const fromStatus = transition?.from as string ?? null;
     const abandonedAt = resolved?.at as string ?? row.timestamp;
 
+    // Defense-in-depth: skip scopes already at their pre-dispatch status (already reverted)
+    if (fromStatus && scope.status === fromStatus) continue;
+
     result.push({ scope_id: row.scope_id, from_status: fromStatus, abandoned_at: abandonedAt });
   }
 

package/server/utils/logger.ts

@@ -33,8 +33,14 @@ const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
 const c = {
   reset: useColor ? '\x1b[0m' : '',
   dim: useColor ? '\x1b[2m' : '',
-  gray: useColor ? '\x1b[90m' : '',
+  green: useColor ? '\x1b[32m' : '',
+  blue: useColor ? '\x1b[34m' : '',
+  magenta: useColor ? '\x1b[35m' : '',
   cyan: useColor ? '\x1b[36m' : '',
+  white: useColor ? '\x1b[37m' : '',
+  gray: useColor ? '\x1b[90m' : '',
+  brightMagenta: useColor ? '\x1b[95m' : '',
+  brightCyan: useColor ? '\x1b[96m' : '',
   yellow: useColor ? '\x1b[33m' : '',
   red: useColor ? '\x1b[31m' : '',
 };
@@ -53,6 +59,34 @@ const LEVEL_LABEL: Record<LogLevel, string> = {
   error: 'ERROR',
 };
 
+// ─── Component Colors ───────────────────────────────────────
+
+const COMPONENT_COLOR: Record<string, string> = {
+  // Scope (green)
+  'scope': c.green, 'scope-watcher': c.green,
+  // Dispatch (magenta)
+  'dispatch': c.magenta, 'dispatch-utils': c.magenta, 'batch': c.magenta,
+  // Git (blue)
+  'git': c.blue, 'worktree': c.blue,
+  // Workflow (cyan)
+  'workflow': c.cyan, 'sprint': c.cyan,
+  // Sync / Config (yellow)
+  'sync': c.yellow, 'config': c.yellow, 'manifest': c.yellow, 'global-config': c.yellow,
+  // Events (white)
+  'event': c.white, 'event-watcher': c.white, 'global-watcher': c.white,
+  // Infrastructure (white)
+  'server': c.white, 'central': c.white, 'database': c.white,
+  'project-context': c.white, 'project-manager': c.white, 'launch': c.white,
+  // Terminal (bright magenta)
+  'terminal': c.brightMagenta,
+  // Services (bright cyan)
+  'gate': c.brightCyan, 'deploy': c.brightCyan, 'telemetry': c.brightCyan, 'version': c.brightCyan,
+};
+
+function componentColor(name: string): string {
+  return COMPONENT_COLOR[name] ?? c.dim;
+}
+
 // ─── Formatting ─────────────────────────────────────────────
 
 function timestamp(): string {
@@ -87,10 +121,13 @@ export interface Logger {
 function write(level: LogLevel, component: string, msg: string, data?: Record<string, unknown>): void {
   if (LEVEL_VALUE[level] < LEVEL_VALUE[currentLevel]) return;
 
-  const color = LEVEL_COLOR[level];
+  const lvl = LEVEL_COLOR[level];
   const label = LEVEL_LABEL[level];
   const kv = formatData(data);
-  const line = `${c.dim}${timestamp()}${c.reset} ${color}${label}${c.reset} ${c.dim}[${component}]${c.reset} ${msg}${kv}\n`;
+  const cc = componentColor(component);
+  // Message uses level color for warn/error (urgency), component color otherwise
+  const mc = (level === 'warn' || level === 'error') ? lvl : cc;
+  const line = `${c.dim}${timestamp()}${c.reset} ${lvl}${label}${c.reset} ${cc}[${component}]${c.reset} ${mc}${msg}${c.reset}${c.dim}${kv}${c.reset}\n`;
 
   if (level === 'warn' || level === 'error') {
     process.stderr.write(line);

package/server/utils/package-info.ts

@@ -0,0 +1,32 @@
+import path from 'path';
+import fs from 'fs';
+import { fileURLToPath } from 'url';
+
+const __selfDir = path.dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Resolve the root directory of the orbital-command package itself.
+ * Walks up from the current file until it finds package.json.
+ */
+export function getOrbitalRoot(): string {
+  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/utils/ → 2 levels up)
+  return path.resolve(__selfDir, '../..');
+}
+
+/** Read package version from package.json in the given root, or the orbital root. */
+export function getPackageVersion(rootDir?: string): string {
+  try {
+    const dir = rootDir ?? getOrbitalRoot();
+    const pkg = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf-8'));
+    return pkg.version || '0.0.0';
+  } catch {
+    return '0.0.0';
+  }
+}