orbital-command 0.2.0 → 1.0.0

package/server/utils/route-helpers.ts

@@ -0,0 +1,50 @@
+import path from 'path';
+import type { Request, Response, NextFunction, RequestHandler } from 'express';
+
+/** Extract a human-readable message from an unknown error value. */
+export function errMsg(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
+/** Validate that a relative path stays within bounds (no traversal). */
+export function isValidRelativePath(p: string): boolean {
+  const normalized = path.normalize(p);
+  return !normalized.startsWith('..') && !path.isAbsolute(normalized) && !normalized.includes('\0');
+}
+
+/** Infer an HTTP status code from an error message. */
+export function inferErrorStatus(msg: string): number {
+  if (msg.includes('traversal')) return 403;
+  if (msg.includes('ENOENT') || msg.includes('not found')) return 404;
+  if (msg.includes('already exists')) return 409;
+  if (msg.includes('directory')) return 400;
+  return 500;
+}
+
+/**
+ * Wrap an Express route handler to catch thrown errors and send a JSON error response.
+ * Works with both sync and async handlers.
+ *
+ * @param fn — route handler that may throw
+ * @param statusFn — optional function to infer status from error message (defaults to 500)
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function catchRoute<Req extends Request = any, Res extends Response = any>(
+  fn: (req: Req, res: Res, next: NextFunction) => void | Promise<void>,
+  statusFn?: (msg: string) => number,
+): RequestHandler {
+  return ((req: Req, res: Res, next: NextFunction) => {
+    try {
+      const result = fn(req, res, next);
+      if (result instanceof Promise) {
+        result.catch((err: unknown) => {
+          const msg = errMsg(err);
+          res.status(statusFn ? statusFn(msg) : 500).json({ success: false, error: msg });
+        });
+      }
+    } catch (err) {
+      const msg = errMsg(err);
+      res.status(statusFn ? statusFn(msg) : 500).json({ success: false, error: msg });
+    }
+  }) as unknown as RequestHandler;
+}

package/server/utils/terminal-launcher.ts

@@ -37,6 +37,7 @@ interface DynamicProfile {
   'Badge Text': string;
   'Tab Color'?: ItermColor;
   'Use Tab Color'?: boolean;
+  [key: string]: unknown; // allow extra color properties from parent profile
 }
 
 /** Convert a hex color (#rrggbb) to iTerm2's color dictionary format. */
@@ -74,21 +75,33 @@ function profilesFilename(prefix: string): string {
   return `${prefix.toLowerCase()}-dispatch-profiles.json`;
 }
 
-function buildProfiles(colorMap: Map<WindowCategory, string>): { Profiles: DynamicProfile[] } {
-  const prefix = getConfig().terminal.profilePrefix;
+function buildProfiles(
+  colorMap: Map<WindowCategory, string>,
+  profilePrefix?: string,
+  parentColors?: Record<string, unknown>,
+): { Profiles: DynamicProfile[] } {
+  const prefix = profilePrefix ?? getConfig().terminal.profilePrefix;
+  const useSeparateColors = parentColors?.['Use Separate Colors for Light and Dark Mode'] === true;
   return {
-    Profiles: CATEGORY_COLUMN_CANDIDATES.map(({ category }) => ({
-      Name: `${prefix}-${category}`,
-      Guid: deriveGuid(prefix, category),
-      'Dynamic Profile Parent Name': 'Default',
-      'Custom Window Title': category,
-      'Use Custom Window Title': true,
-      'Allow Title Setting': false,
-      'Title Components': 1,  // 1 = Session Name (not Job Name)
-      'Badge Text': category,
-      'Tab Color': hexToItermColor(colorMap.get(category) ?? FALLBACK_HEX),
-      'Use Tab Color': true,
-    })),
+    Profiles: CATEGORY_COLUMN_CANDIDATES.map(({ category }) => {
+      const stageColor = hexToItermColor(colorMap.get(category) ?? FALLBACK_HEX);
+      const badgeColor = { ...stageColor, 'Alpha Component': 0.5 };
+      return {
+        ...(parentColors ?? {}),  // inherited colors first — our overrides win
+        Name: `${prefix}-${category}`,
+        Guid: deriveGuid(prefix, category),
+        'Dynamic Profile Parent Name': 'Default',
+        'Custom Window Title': category,
+        'Use Custom Window Title': true,
+        'Allow Title Setting': false,
+        'Title Components': 1,  // 1 = Session Name (not Job Name)
+        'Badge Text': category,
+        'Tab Color': stageColor,
+        'Use Tab Color': true,
+        'Badge Color': badgeColor,
+        ...(useSeparateColors ? { 'Badge Color (Dark)': badgeColor, 'Badge Color (Light)': badgeColor } : {}),
+      };
+    }),
   };
 }
 
@@ -107,28 +120,64 @@ function resolveColorMap(engine: WorkflowEngine): Map<WindowCategory, string> {
   return colors;
 }
 
+const ITERM2_PLIST = path.join(os.homedir(), 'Library', 'Preferences', 'com.googlecode.iterm2.plist');
+
+/** Read all color properties from the user's iTerm2 parent profile.
+ *  Uses `plutil -extract` to pull the first bookmark as JSON, then filters
+ *  for color dicts (entries with "Red Component") and the separate-colors flag.
+ *  Returns an empty object on non-macOS or if iTerm2 prefs can't be read. */
+async function readParentProfileColors(): Promise<Record<string, unknown>> {
+  try {
+    const { stdout } = await execFileAsync(
+      'plutil', ['-extract', 'New Bookmarks.0', 'json', '-o', '-', ITERM2_PLIST],
+      { timeout: 5000 },
+    );
+    const profile = JSON.parse(stdout) as Record<string, unknown>;
+    const colors: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(profile)) {
+      if (value && typeof value === 'object' && 'Red Component' in (value as Record<string, unknown>)) {
+        colors[key] = value;
+      }
+      if (key === 'Use Separate Colors for Light and Dark Mode') {
+        colors[key] = value;
+      }
+    }
+    return colors;
+  } catch {
+    return {};
+  }
+}
+
 /** Write iTerm2 Dynamic Profiles for each workflow category.
  *  Derives tab colors from the active workflow's column definitions.
+ *  Reads the parent profile's colors to work around iTerm2's incomplete
+ *  inheritance of (Dark)/(Light) color variants.
  *  Idempotent — safe to call on every server startup. */
-export async function ensureDynamicProfiles(engine: WorkflowEngine): Promise<void> {
+const profilesWritten = new Set<string>();
+export async function ensureDynamicProfiles(engine: WorkflowEngine, profilePrefix?: string): Promise<void> {
+  const prefix = profilePrefix ?? getConfig().terminal.profilePrefix;
+  if (profilesWritten.has(prefix)) return;
+  profilesWritten.add(prefix);
   try {
     await fs.mkdir(DYNAMIC_PROFILES_DIR, { recursive: true });
-    const prefix = getConfig().terminal.profilePrefix;
     const filePath = path.join(DYNAMIC_PROFILES_DIR, profilesFilename(prefix));
     const colorMap = resolveColorMap(engine);
-    // Write tmp file outside DynamicProfiles/ — iTerm2 watches that dir and reads ALL files
-    const tmpPath = path.join(os.tmpdir(), profilesFilename(prefix) + '.tmp');
-    await fs.writeFile(tmpPath, JSON.stringify(buildProfiles(colorMap), null, 2));
+    const parentColors = await readParentProfileColors();
+    // Write tmp file outside DynamicProfiles/ — iTerm2 watches that dir and reads ALL files.
+    // Use pid + timestamp to avoid races when multiple projects call concurrently.
+    const tmpPath = path.join(os.tmpdir(), `${profilesFilename(prefix)}.${process.pid}.${Date.now()}.tmp`);
+    await fs.writeFile(tmpPath, JSON.stringify(buildProfiles(colorMap, prefix, parentColors), null, 2));
     await fs.copyFile(tmpPath, filePath);
     await fs.unlink(tmpPath).catch(() => {});
+    log.info('iTerm2 profiles ready', { categories: CATEGORY_COLUMN_CANDIDATES.length });
   } catch (err) {
-    log.warn('Failed to write iTerm2 dynamic profiles', { error: (err as Error).message });
+    log.warn('iTerm2 profiles failed', { error: (err as Error).message });
   }
 }
 
 /** Maps a WindowCategory to its iTerm2 profile name. */
-function profileNameForCategory(category: string): string {
-  return `${getConfig().terminal.profilePrefix}-${category}`;
+function profileNameForCategory(category: string, profilePrefix?: string): string {
+  return `${profilePrefix ?? getConfig().terminal.profilePrefix}-${category}`;
 }
 
 // ─── Window Categorization ──────────────────────────────────
@@ -158,6 +207,12 @@ export function commandToWindowCategory(command: string): WindowCategory | null
 /** In-memory registry: category → iTerm2 window ID (stable integer). Resets on server restart. */
 const windowRegistry = new Map<WindowCategory, number>();
 
+/** Escape a value for use inside single quotes in shell commands.
+ *  Replaces ' with '\'' (end quote, escaped quote, reopen quote). */
+export function shellQuote(s: string): string {
+  return s.replace(/'/g, "'\\''");
+}
+
 /**
  * Escape a string for use inside $'...' ANSI-C quoting.
  * Handles backslash, single-quote, and newline characters.
@@ -222,8 +277,11 @@ async function createWindowWithCommand(command: string, category: WindowCategory
       '-e', '  return id of newWindow',
       '-e', 'end tell',
     ]);
-    return parseInt(stdout.trim(), 10);
-  } catch {
+    const id = parseInt(stdout.trim(), 10);
+    if (isNaN(id)) throw new Error('Failed to parse iTerm2 window ID');
+    return id;
+  } catch (e) {
+    if (e instanceof Error && e.message === 'Failed to parse iTerm2 window ID') throw e;
     // Profile missing — fall back to default profile
     const { stdout } = await execFileAsync('osascript', [
       '-e', 'tell application "iTerm2"',
@@ -237,7 +295,9 @@ async function createWindowWithCommand(command: string, category: WindowCategory
       '-e', '  return id of newWindow',
       '-e', 'end tell',
     ]);
-    return parseInt(stdout.trim(), 10);
+    const id = parseInt(stdout.trim(), 10);
+    if (isNaN(id)) throw new Error('Failed to parse iTerm2 window ID');
+    return id;
   }
 }
 

package/server/utils/worktree-manager.ts

@@ -2,8 +2,10 @@ import { execFile as execFileCb } from 'child_process';
 import { promisify } from 'util';
 import fs from 'fs/promises';
 import path from 'path';
+import { createLogger } from './logger.js';
 
 const execFile = promisify(execFileCb);
+const log = createLogger('worktree');
 
 export interface WorktreeInfo {
   path: string;
@@ -15,6 +17,7 @@ export async function createWorktree(projectRoot: string, scopeId: number): Prom
   const wtPath = path.join(projectRoot, '.worktrees', `scope-${scopeId}`);
   const branch = `feat/scope-${scopeId}`;
 
+  log.info('Creating worktree', { scopeId, branch });
   await execFile('git', ['worktree', 'add', wtPath, '-b', branch], { cwd: projectRoot });
 
   // Ensure scopes/ and .claude/ are in .gitignore (for user projects)
@@ -50,13 +53,14 @@ export async function removeWorktree(projectRoot: string, scopeId: number): Prom
   const wtPath = path.join(projectRoot, '.worktrees', `scope-${scopeId}`);
   const branch = `feat/scope-${scopeId}`;
 
+  log.info('Removing worktree', { scopeId });
   try {
     await execFile('git', ['worktree', 'remove', wtPath, '--force'], { cwd: projectRoot });
-  } catch { /* worktree may already be gone */ }
+  } catch { log.debug('Worktree already removed', { scopeId }); }
 
   try {
     await execFile('git', ['branch', '-d', branch], { cwd: projectRoot });
-  } catch { /* branch may not exist or not be merged */ }
+  } catch { log.debug('Branch not deleted', { branch, scopeId }); }
 }
 
 export async function listWorktrees(projectRoot: string): Promise<WorktreeInfo[]> {
@@ -73,7 +77,7 @@ export async function listWorktrees(projectRoot: string): Promise<WorktreeInfo[]
     } else if (line === '' && currentPath) {
       const match = currentPath.match(/scope-(\d+)$/);
       if (match) {
-        results.push({ path: currentPath, branch: currentBranch, scopeId: parseInt(match[1]) });
+        results.push({ path: currentPath, branch: currentBranch, scopeId: parseInt(match[1], 10) });
       }
       currentPath = '';
       currentBranch = '';
@@ -82,7 +86,7 @@ export async function listWorktrees(projectRoot: string): Promise<WorktreeInfo[]
   if (currentPath) {
     const match = currentPath.match(/scope-(\d+)$/);
     if (match) {
-      results.push({ path: currentPath, branch: currentBranch, scopeId: parseInt(match[1]) });
+      results.push({ path: currentPath, branch: currentBranch, scopeId: parseInt(match[1], 10) });
     }
   }
 
@@ -96,6 +100,7 @@ export async function cleanupStaleWorktrees(projectRoot: string): Promise<number
     try {
       await fs.access(wt.path);
     } catch {
+      log.info('Cleaning stale worktree', { scopeId: wt.scopeId, path: wt.path });
       await removeWorktree(projectRoot, wt.scopeId);
       cleaned++;
     }

package/server/validator.ts

@@ -0,0 +1,270 @@
+/**
+ * Validation module for the Orbital Command primitive system.
+ *
+ * Checks cross-references between manifest, settings.local.json,
+ * workflow.json, and files on disk. Ensures internal consistency.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { loadManifest } from './manifest.js';
+import { validateHookPaths } from './settings-sync.js';
+import type { ValidationResult, ValidationSeverity } from './manifest-types.js';
+
+// ─── Public API ─────────────────────────────────────────────
+
+export interface ValidationReport {
+  results: ValidationResult[];
+  errors: number;
+  warnings: number;
+  info: number;
+}
+
+/**
+ * Run all validation checks on a project. Returns a structured report.
+ */
+export function validate(
+  projectRoot: string,
+  packageVersion: string,
+): ValidationReport {
+  const results: ValidationResult[] = [];
+  const claudeDir = path.join(projectRoot, '.claude');
+
+  // 1. Check manifest exists
+  const manifest = loadManifest(projectRoot);
+  if (!manifest) {
+    results.push({
+      severity: 'warning',
+      message: 'No orbital-manifest.json found — run `orbital update` to create one',
+    });
+    // Can't do further manifest checks without a manifest
+    return buildReport(results);
+  }
+
+  // 2. Manifest file existence — every template file should exist on disk
+  for (const [relPath, record] of Object.entries(manifest.files)) {
+    const absPath = path.join(claudeDir, relPath);
+    if (!fs.existsSync(absPath)) {
+      results.push({
+        severity: 'error',
+        message: 'Manifest references missing file',
+        file: relPath,
+        detail: `Origin: ${record.origin}, Status: ${record.status}`,
+      });
+    }
+  }
+
+  // 3. Untracked files — files on disk not in manifest
+  for (const dir of ['hooks', 'skills', 'agents']) {
+    const dirPath = path.join(claudeDir, dir);
+    if (!fs.existsSync(dirPath)) continue;
+
+    walkDir(dirPath, dir, (relPath) => {
+      if (!manifest.files[relPath]) {
+        results.push({
+          severity: 'warning',
+          message: 'Untracked file in managed directory',
+          file: relPath,
+          detail: 'Not in manifest — may be orphaned or user-created',
+        });
+      }
+    });
+  }
+
+  // 4. Settings hook file existence
+  const settingsPath = path.join(claudeDir, 'settings.local.json');
+  const brokenHooks = validateHookPaths(settingsPath, projectRoot);
+  for (const command of brokenHooks) {
+    results.push({
+      severity: 'error',
+      message: 'Settings hook references missing file',
+      detail: command,
+    });
+  }
+
+  // 5. Workflow integrity
+  const workflowPath = path.join(claudeDir, 'config', 'workflow.json');
+  if (fs.existsSync(workflowPath)) {
+    validateWorkflow(workflowPath, claudeDir, results);
+  }
+
+  // 6. Config schema check (basic — just verify it parses)
+  const configPath = path.join(claudeDir, 'orbital.config.json');
+  if (fs.existsSync(configPath)) {
+    try {
+      JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    } catch {
+      results.push({
+        severity: 'error',
+        message: 'orbital.config.json is malformed JSON',
+        file: 'orbital.config.json',
+      });
+    }
+  } else {
+    results.push({
+      severity: 'warning',
+      message: 'orbital.config.json not found',
+    });
+  }
+
+  // 7. Version consistency
+  if (manifest.packageVersion !== packageVersion) {
+    results.push({
+      severity: 'warning',
+      message: 'Manifest version mismatch — run `orbital update`',
+      detail: `Manifest: ${manifest.packageVersion}, Package: ${packageVersion}`,
+    });
+  }
+
+  // 8. Generated artifacts exist
+  for (const artifact of manifest.generatedArtifacts) {
+    const artifactPath = path.join(claudeDir, artifact);
+    if (!fs.existsSync(artifactPath)) {
+      results.push({
+        severity: 'warning',
+        message: 'Generated artifact missing',
+        file: artifact,
+        detail: 'Will be regenerated on next update',
+      });
+    }
+  }
+
+  return buildReport(results);
+}
+
+/**
+ * Format a validation report for CLI output.
+ */
+export function formatValidationReport(report: ValidationReport): string {
+  const lines: string[] = [];
+
+  lines.push('Orbital Command — validation report\n');
+
+  if (report.results.length === 0) {
+    lines.push('  All checks passed.\n');
+    return lines.join('\n');
+  }
+
+  // Group by severity
+  const grouped: Record<ValidationSeverity, ValidationResult[]> = {
+    error: [],
+    warning: [],
+    info: [],
+  };
+  for (const r of report.results) {
+    grouped[r.severity].push(r);
+  }
+
+  for (const severity of ['error', 'warning', 'info'] as const) {
+    const items = grouped[severity];
+    if (items.length === 0) continue;
+
+    const label = severity === 'error' ? 'ERRORS' : severity === 'warning' ? 'WARNINGS' : 'INFO';
+    lines.push(`  ${label}:`);
+    for (const item of items) {
+      const file = item.file ? ` [${item.file}]` : '';
+      const detail = item.detail ? ` — ${item.detail}` : '';
+      lines.push(`    ${item.message}${file}${detail}`);
+    }
+    lines.push('');
+  }
+
+  lines.push(`  Summary: ${report.errors} errors, ${report.warnings} warnings, ${report.info} info`);
+  return lines.join('\n');
+}
+
+// ─── Internal Helpers ───────────────────────────────────────
+
+/** Recursively walk a directory, calling fn with relative paths. */
+function walkDir(
+  dirPath: string,
+  prefix: string,
+  fn: (relPath: string) => void,
+): void {
+  if (!fs.existsSync(dirPath)) return;
+
+  for (const entry of fs.readdirSync(dirPath, { withFileTypes: true })) {
+    if (entry.name.startsWith('.')) continue;
+    const absPath = path.join(dirPath, entry.name);
+    const relPath = `${prefix}/${entry.name}`;
+
+    // Follow symlinks: use stat() to check if target is a directory
+    const stat = fs.statSync(absPath);
+    if (stat.isDirectory()) {
+      walkDir(absPath, relPath, fn);
+    } else {
+      fn(relPath);
+    }
+  }
+}
+
+/** Validate workflow.json hook targets and edge commands. */
+function validateWorkflow(
+  workflowPath: string,
+  claudeDir: string,
+  results: ValidationResult[],
+): void {
+  let workflow: Record<string, unknown>;
+  try {
+    workflow = JSON.parse(fs.readFileSync(workflowPath, 'utf-8'));
+  } catch {
+    results.push({
+      severity: 'error',
+      message: 'workflow.json is malformed JSON',
+      file: 'config/workflow.json',
+    });
+    return;
+  }
+
+  // Check hook targets
+  const hooks = workflow.hooks as Array<{ id?: string; target?: string }> | undefined;
+  if (Array.isArray(hooks)) {
+    for (const hook of hooks) {
+      if (!hook.target) continue;
+
+      // Resolve hook target relative to project root (targets use .claude/ prefix)
+      const targetPath = path.resolve(path.dirname(claudeDir), hook.target);
+      if (!fs.existsSync(targetPath)) {
+        results.push({
+          severity: 'error',
+          message: 'Workflow hook references missing script',
+          file: 'config/workflow.json',
+          detail: `Hook "${hook.id || 'unknown'}": ${hook.target}`,
+        });
+      }
+    }
+  }
+
+  // Check edge commands reference existing skills
+  const edges = workflow.edges as Array<{ command?: string; from?: string; to?: string }> | undefined;
+  if (Array.isArray(edges)) {
+    for (const edge of edges) {
+      if (!edge.command) continue;
+
+      // Extract skill name from command like "/skill-name {id}"
+      const match = edge.command.match(/^\/([a-z-]+)/);
+      if (!match) continue;
+
+      const skillName = match[1];
+      const skillPath = path.join(claudeDir, 'skills', skillName, 'SKILL.md');
+      if (!fs.existsSync(skillPath)) {
+        results.push({
+          severity: 'warning',
+          message: 'Workflow edge references unknown skill',
+          file: 'config/workflow.json',
+          detail: `Edge "${edge.from}" → "${edge.to}": ${edge.command}`,
+        });
+      }
+    }
+  }
+}
+
+/** Build a report with counts from a list of results. */
+function buildReport(results: ValidationResult[]): ValidationReport {
+  return {
+    results,
+    errors: results.filter(r => r.severity === 'error').length,
+    warnings: results.filter(r => r.severity === 'warning').length,
+    info: results.filter(r => r.severity === 'info').length,
+  };
+}

package/server/watchers/event-watcher.ts

@@ -8,6 +8,7 @@ import { createLogger } from '../utils/logger.js';
 const log = createLogger('event');
 
 const ARCHIVE_DIR_NAME = 'processed';
+const processingFiles = new Set<string>();
 
 /**
  * Watch .claude/orbital-events/ for new JSON event files.
@@ -81,20 +82,31 @@ function processEventFile(
   eventService: EventService,
   archiveDir: string
 ): void {
-  const event = parseEventFile(filePath);
-  if (!event) return;
+  if (processingFiles.has(filePath)) return;
+  processingFiles.add(filePath);
+  try {
+    const event = parseEventFile(filePath);
+    if (!event) return;
 
-  eventService.ingest(event);
+    eventService.ingest(event);
 
-  // Move to archive
-  const fileName = path.basename(filePath);
-  try {
-    fs.renameSync(filePath, path.join(archiveDir, fileName));
-  } catch (err) {
-    log.warn('Failed to archive event file', { file: filePath, error: (err as Error).message });
-    // If rename fails (cross-device), just delete the source
-    try { fs.unlinkSync(filePath); } catch (unlinkErr) {
-      log.warn('Failed to delete event file', { file: filePath, error: (unlinkErr as Error).message });
+    // Move to archive
+    const fileName = path.basename(filePath);
+    try {
+      fs.renameSync(filePath, path.join(archiveDir, fileName));
+    } catch (err) {
+      const code = (err as NodeJS.ErrnoException).code;
+      if (code === 'ENOENT') return; // Already archived by concurrent handler
+      log.warn('Failed to archive event file', { file: filePath, error: (err as Error).message });
+      // If rename fails (cross-device), just delete the source
+      try { fs.unlinkSync(filePath); } catch (unlinkErr) {
+        const unlinkCode = (unlinkErr as NodeJS.ErrnoException).code;
+        if (unlinkCode !== 'ENOENT') {
+          log.warn('Failed to delete event file', { file: filePath, error: (unlinkErr as Error).message });
+        }
+      }
     }
+  } finally {
+    processingFiles.delete(filePath);
   }
 }

package/server/watchers/global-watcher.ts

@@ -0,0 +1,77 @@
+import chokidar, { type FSWatcher } from 'chokidar';
+import path from 'path';
+import fs from 'fs';
+import type { Server } from 'socket.io';
+import { GLOBAL_PRIMITIVES_DIR } from '../global-config.js';
+import type { SyncService } from '../services/sync-service.js';
+import { createLogger } from '../utils/logger.js';
+
+const log = createLogger('global-watcher');
+
+/**
+ * Watch ~/.orbital/primitives/ for changes and propagate to synced projects.
+ *
+ * On file change: copies to all synced projects' .claude/ directories.
+ * On file create: copies to projects with auto-sync policy.
+ * On file delete: removes from synced projects, preserves overrides.
+ */
+export function startGlobalWatcher(
+  syncService: SyncService,
+  io: Server,
+): FSWatcher | null {
+  if (!fs.existsSync(GLOBAL_PRIMITIVES_DIR)) {
+    log.info('Global primitives directory does not exist, skipping watcher');
+    return null;
+  }
+
+  const watcher = chokidar.watch(GLOBAL_PRIMITIVES_DIR, {
+    ignored: [/(^|[/\\])\../, /\.tmp$/, /\.sync-tmp$/],
+    persistent: true,
+    ignoreInitial: true,
+    depth: 10,
+    awaitWriteFinish: { stabilityThreshold: 300, pollInterval: 100 },
+  });
+
+  function relativePath(absPath: string): string {
+    return path.relative(GLOBAL_PRIMITIVES_DIR, absPath);
+  }
+
+  watcher.on('change', (filePath) => {
+    const rel = relativePath(filePath);
+    log.info('Global primitive changed', { file: rel });
+    const result = syncService.propagateGlobalChange(rel);
+    io.to('all-projects').emit('sync:file:updated', {
+      relativePath: rel,
+      projects: result.updated,
+    });
+  });
+
+  watcher.on('add', (filePath) => {
+    const rel = relativePath(filePath);
+    log.info('Global primitive added', { file: rel });
+    const result = syncService.handleNewGlobalFile(rel);
+    io.to('all-projects').emit('sync:file:created', {
+      relativePath: rel,
+      autoSynced: result.updated,
+      pending: result.skipped,
+    });
+  });
+
+  watcher.on('unlink', (filePath) => {
+    const rel = relativePath(filePath);
+    log.info('Global primitive deleted', { file: rel });
+    const result = syncService.handleGlobalFileDeletion(rel);
+    io.to('all-projects').emit('sync:file:deleted', {
+      relativePath: rel,
+      removed: result.removed,
+      preserved: result.preserved,
+    });
+  });
+
+  watcher.on('error', (err) => {
+    log.error('Global watcher error', { error: String(err) });
+  });
+
+  log.info('Global primitives watcher started', { dir: GLOBAL_PRIMITIVES_DIR });
+  return watcher;
+}