orbital-command 0.2.0 → 1.0.0

package/server/routes/config-routes.ts

@@ -1,13 +1,14 @@
 import { Router } from 'express';
-import type { Server } from 'socket.io';
+import type { Emitter } from '../project-emitter.js';
 import { ConfigService, isValidPrimitiveType } from '../services/config-service.js';
 import type { ConfigPrimitiveType } from '../services/config-service.js';
 import type { WorkflowService } from '../services/workflow-service.js';
+import { catchRoute, inferErrorStatus } from '../utils/route-helpers.js';
 
 interface ConfigRouteDeps {
   projectRoot: string;
   workflowService: WorkflowService;
-  io: Server;
+  io: Emitter;
 }
 
 export function createConfigRoutes({ projectRoot, workflowService: _workflowService, io }: ConfigRouteDeps): Router {
@@ -24,21 +25,17 @@ export function createConfigRoutes({ projectRoot, workflowService: _workflowServ
   }
 
   // GET /config/:type/tree — directory tree with frontmatter
-  router.get('/config/:type/tree', (req, res) => {
+  router.get('/config/:type/tree', catchRoute((req, res) => {
     const type = parseType(req.params.type, res);
     if (!type) return;
 
-    try {
-      const basePath = configService.getBasePath(type);
-      const tree = configService.scanDirectory(basePath);
-      res.json({ success: true, data: tree });
-    } catch (err) {
-      res.status(500).json({ success: false, error: errMsg(err) });
-    }
-  });
+    const basePath = configService.getBasePath(type);
+    const tree = configService.scanDirectory(basePath);
+    res.json({ success: true, data: tree });
+  }));
 
   // GET /config/:type/file?path=<relative> — file content
-  router.get('/config/:type/file', (req, res) => {
+  router.get('/config/:type/file', catchRoute((req, res) => {
     const type = parseType(req.params.type, res);
     if (!type) return;
 
@@ -48,19 +45,13 @@ export function createConfigRoutes({ projectRoot, workflowService: _workflowServ
       return;
     }
 
-    try {
-      const basePath = configService.getBasePath(type);
-      const content = configService.readFile(basePath, filePath);
-      res.json({ success: true, data: { path: filePath, content } });
-    } catch (err) {
-      const msg = errMsg(err);
-      const status = msg.includes('traversal') ? 403 : msg.includes('ENOENT') || msg.includes('not found') ? 404 : 500;
-      res.status(status).json({ success: false, error: msg });
-    }
-  });
+    const basePath = configService.getBasePath(type);
+    const content = configService.readFile(basePath, filePath);
+    res.json({ success: true, data: { path: filePath, content } });
+  }, inferErrorStatus));
 
   // PUT /config/:type/file — save file { path, content }
-  router.put('/config/:type/file', (req, res) => {
+  router.put('/config/:type/file', catchRoute((req, res) => {
     const type = parseType(req.params.type, res);
     if (!type) return;
 
@@ -70,20 +61,14 @@ export function createConfigRoutes({ projectRoot, workflowService: _workflowServ
       return;
     }
 
-    try {
-      const basePath = configService.getBasePath(type);
-      configService.writeFile(basePath, filePath, content);
-      io.emit(`config:${type}:changed`, { action: 'updated', path: filePath });
-      res.json({ success: true });
-    } catch (err) {
-      const msg = errMsg(err);
-      const status = msg.includes('traversal') ? 403 : msg.includes('not found') ? 404 : 500;
-      res.status(status).json({ success: false, error: msg });
-    }
-  });
+    const basePath = configService.getBasePath(type);
+    configService.writeFile(basePath, filePath, content);
+    io.emit(`config:${type}:changed`, { action: 'updated', path: filePath });
+    res.json({ success: true });
+  }, inferErrorStatus));
 
   // POST /config/:type/file — create file { path, content }
-  router.post('/config/:type/file', (req, res) => {
+  router.post('/config/:type/file', catchRoute((req, res) => {
     const type = parseType(req.params.type, res);
     if (!type) return;
 
@@ -93,20 +78,14 @@ export function createConfigRoutes({ projectRoot, workflowService: _workflowServ
       return;
     }
 
-    try {
-      const basePath = configService.getBasePath(type);
-      configService.createFile(basePath, filePath, content);
-      io.emit(`config:${type}:changed`, { action: 'created', path: filePath });
-      res.status(201).json({ success: true });
-    } catch (err) {
-      const msg = errMsg(err);
-      const status = msg.includes('traversal') ? 403 : msg.includes('already exists') ? 409 : 500;
-      res.status(status).json({ success: false, error: msg });
-    }
-  });
+    const basePath = configService.getBasePath(type);
+    configService.createFile(basePath, filePath, content);
+    io.emit(`config:${type}:changed`, { action: 'created', path: filePath });
+    res.status(201).json({ success: true });
+  }, inferErrorStatus));
 
   // DELETE /config/:type/file?path=<relative> — delete file
-  router.delete('/config/:type/file', (req, res) => {
+  router.delete('/config/:type/file', catchRoute((req, res) => {
     const type = parseType(req.params.type, res);
     if (!type) return;
 
@@ -116,20 +95,14 @@ export function createConfigRoutes({ projectRoot, workflowService: _workflowServ
       return;
     }
 
-    try {
-      const basePath = configService.getBasePath(type);
-      configService.deleteFile(basePath, filePath);
-      io.emit(`config:${type}:changed`, { action: 'deleted', path: filePath });
-      res.json({ success: true });
-    } catch (err) {
-      const msg = errMsg(err);
-      const status = msg.includes('traversal') ? 403 : msg.includes('not found') ? 404 : msg.includes('directory') ? 400 : 500;
-      res.status(status).json({ success: false, error: msg });
-    }
-  });
+    const basePath = configService.getBasePath(type);
+    configService.deleteFile(basePath, filePath);
+    io.emit(`config:${type}:changed`, { action: 'deleted', path: filePath });
+    res.json({ success: true });
+  }, inferErrorStatus));
 
   // POST /config/:type/rename — rename { oldPath, newPath }
-  router.post('/config/:type/rename', (req, res) => {
+  router.post('/config/:type/rename', catchRoute((req, res) => {
     const type = parseType(req.params.type, res);
     if (!type) return;
 
@@ -139,20 +112,14 @@ export function createConfigRoutes({ projectRoot, workflowService: _workflowServ
       return;
     }
 
-    try {
-      const basePath = configService.getBasePath(type);
-      configService.renameFile(basePath, oldPath, newPath);
-      io.emit(`config:${type}:changed`, { action: 'renamed', oldPath, newPath });
-      res.json({ success: true });
-    } catch (err) {
-      const msg = errMsg(err);
-      const status = msg.includes('traversal') ? 403 : msg.includes('not found') ? 404 : msg.includes('already exists') ? 409 : 500;
-      res.status(status).json({ success: false, error: msg });
-    }
-  });
+    const basePath = configService.getBasePath(type);
+    configService.renameFile(basePath, oldPath, newPath);
+    io.emit(`config:${type}:changed`, { action: 'renamed', oldPath, newPath });
+    res.json({ success: true });
+  }, inferErrorStatus));
 
   // POST /config/:type/folder — create folder { path }
-  router.post('/config/:type/folder', (req, res) => {
+  router.post('/config/:type/folder', catchRoute((req, res) => {
     const type = parseType(req.params.type, res);
     if (!type) return;
 
@@ -162,21 +129,12 @@ export function createConfigRoutes({ projectRoot, workflowService: _workflowServ
       return;
     }
 
-    try {
-      const basePath = configService.getBasePath(type);
-      configService.createFolder(basePath, folderPath);
-      io.emit(`config:${type}:changed`, { action: 'folder-created', path: folderPath });
-      res.status(201).json({ success: true });
-    } catch (err) {
-      const msg = errMsg(err);
-      const status = msg.includes('traversal') ? 403 : msg.includes('already exists') ? 409 : 500;
-      res.status(status).json({ success: false, error: msg });
-    }
-  });
+    const basePath = configService.getBasePath(type);
+    configService.createFolder(basePath, folderPath);
+    io.emit(`config:${type}:changed`, { action: 'folder-created', path: folderPath });
+    res.status(201).json({ success: true });
+  }, inferErrorStatus));
 
   return router;
 }
 
-function errMsg(err: unknown): string {
-  return err instanceof Error ? err.message : String(err);
-}

package/server/routes/data-routes.ts

@@ -3,134 +3,51 @@ import { execFile } from 'child_process';
 import path from 'path';
 import { promisify } from 'util';
 import type Database from 'better-sqlite3';
-import type { Server } from 'socket.io';
+import type { Emitter } from '../project-emitter.js';
+import type { EventService } from '../services/event-service.js';
 import type { GateService } from '../services/gate-service.js';
 import type { DeployService } from '../services/deploy-service.js';
+import type { GitService } from '../services/git-service.js';
 import type { WorkflowEngine } from '../../shared/workflow-engine.js';
 import { getHookEnforcement } from '../../shared/workflow-config.js';
 import { getClaudeSessions, getSessionStats, type SessionStats } from '../services/claude-session-service.js';
 import { launchInTerminal } from '../utils/terminal-launcher.js';
+import type { OrbitalConfig } from '../config.js';
+import { buildClaudeFlags } from '../utils/flag-builder.js';
+import { createLogger } from '../utils/logger.js';
+import { parseJsonFields, type Row } from '../utils/json-fields.js';
 
-const execFileAsync = promisify(execFile);
-
-// ─── Types & Helpers ────────────────────────────────────────
-
-interface DriftCommit { sha: string; message: string; author: string; date: string }
-interface BranchHead { sha: string; date: string; message: string }
-interface PipelineDriftData {
-  devToStaging: { count: number; commits: DriftCommit[]; oldestDate: string | null };
-  stagingToMain: { count: number; commits: DriftCommit[]; oldestDate: string | null };
-  heads: { dev: BranchHead; staging: BranchHead; main: BranchHead };
-}
-
-const JSON_FIELDS = ['tags', 'blocked_by', 'blocks', 'data', 'discoveries', 'next_steps', 'details'];
-
-type Row = Record<string, unknown>;
-
-function parseJsonFields(row: Row): Row {
-  const parsed = { ...row };
-  for (const field of JSON_FIELDS) {
-    if (typeof parsed[field] === 'string') {
-      try { parsed[field] = JSON.parse(parsed[field] as string); } catch { /* keep string */ }
-    }
-  }
-  return parsed;
-}
-
-function parseDriftCommits(raw: string): DriftCommit[] {
-  if (!raw) return [];
-  return raw.split('\n').map((line) => {
-    const [sha, date, message, author] = line.split('|');
-    return { sha, date, message: message ?? '', author: author ?? '' };
-  });
-}
+const log = createLogger('server');
 
-function parseHead(raw: string): BranchHead {
-  const [sha, date, message] = raw.split('|');
-  return { sha: sha ?? '', date: date ?? '', message: message ?? '' };
-}
+const execFileAsync = promisify(execFile);
 
 // ─── Route Factory ──────────────────────────────────────────
 
 interface DataRouteDeps {
   db: Database.Database;
-  io: Server;
+  io: Emitter;
+  eventService: EventService;
   gateService: GateService;
   deployService: DeployService;
+  gitService: GitService;
   engine: WorkflowEngine;
   projectRoot: string;
   inferScopeStatus: (type: string, scopeId: unknown, data: Record<string, unknown>) => void;
+  config: OrbitalConfig;
 }
 
 export function createDataRoutes({
-  db, io, gateService, deployService, engine, projectRoot, inferScopeStatus,
+  db, io, eventService, gateService, deployService, gitService, engine, projectRoot, inferScopeStatus, config,
 }: DataRouteDeps): Router {
   const router = Router();
 
-  // ─── Pipeline Drift (cached) ─────────────────────────────
-
-  let driftCache: { data: PipelineDriftData; ts: number } | null = null;
-  const DRIFT_CACHE_MS = 60_000;
-
-  async function gitLog(args: string[]): Promise<string> {
-    const { stdout } = await execFileAsync('git', args, { cwd: projectRoot });
-    return stdout.trim();
-  }
-
-  async function computeDrift(): Promise<PipelineDriftData> {
-    if (driftCache && Date.now() - driftCache.ts < DRIFT_CACHE_MS) return driftCache.data;
-
-    const [devToStagingRaw, stagingToMainRaw, devHead, stagingHead, mainHead] =
-      await Promise.all([
-        gitLog(['log', 'origin/dev', '--not', 'origin/staging', '--reverse', '--format=%H|%aI|%s|%an']),
-        gitLog(['log', 'origin/staging', '--not', 'origin/main', '--reverse', '--format=%H|%aI|%s|%an']),
-        gitLog(['log', 'origin/dev', '-1', '--format=%H|%aI|%s']),
-        gitLog(['log', 'origin/staging', '-1', '--format=%H|%aI|%s']),
-        gitLog(['log', 'origin/main', '-1', '--format=%H|%aI|%s']),
-      ]);
-
-    const devToStaging = parseDriftCommits(devToStagingRaw);
-    const stagingToMain = parseDriftCommits(stagingToMainRaw);
-
-    const data: PipelineDriftData = {
-      devToStaging: {
-        count: devToStaging.length,
-        commits: devToStaging,
-        oldestDate: devToStaging[0]?.date ?? null,
-      },
-      stagingToMain: {
-        count: stagingToMain.length,
-        commits: stagingToMain,
-        oldestDate: stagingToMain[0]?.date ?? null,
-      },
-      heads: {
-        dev: parseHead(devHead),
-        staging: parseHead(stagingHead),
-        main: parseHead(mainHead),
-      },
-    };
-
-    driftCache = { data, ts: Date.now() };
-    return data;
-  }
-
   // ─── Event Routes ──────────────────────────────────────────
 
   router.get('/events', (req, res) => {
     const limit = Number(req.query.limit) || 50;
     const type = req.query.type as string | undefined;
-    const scopeId = req.query.scope_id as string | undefined;
-
-    let query = 'SELECT * FROM events WHERE 1=1';
-    const params: unknown[] = [];
-
-    if (type) { query += ' AND type = ?'; params.push(type); }
-    if (scopeId) { query += ' AND scope_id = ?'; params.push(Number(scopeId)); }
-
-    query += ' ORDER BY timestamp DESC LIMIT ?';
-    params.push(limit);
-
-    const events = db.prepare(query).all(...params) as Row[];
+    const scopeId = req.query.scope_id ? Number(req.query.scope_id) : undefined;
+    const events = eventService.getFiltered({ limit, type, scopeId }) as unknown as Row[];
     res.json(events.map(parseJsonFields));
   });
 
@@ -167,23 +84,9 @@ export function createDataRoutes({
 
   router.get('/events/violations/summary', (_req, res) => {
     try {
-      const byRule = db.prepare(
-        `SELECT JSON_EXTRACT(data, '$.rule') as rule, COUNT(*) as count, MAX(timestamp) as last_seen
-         FROM events WHERE type = 'VIOLATION' GROUP BY rule ORDER BY count DESC`
-      ).all();
-      const byFile = db.prepare(
-        `SELECT JSON_EXTRACT(data, '$.file') as file, COUNT(*) as count FROM events
-         WHERE type = 'VIOLATION' AND JSON_EXTRACT(data, '$.file') IS NOT NULL AND JSON_EXTRACT(data, '$.file') != ''
-         GROUP BY file ORDER BY count DESC LIMIT 20`
-      ).all();
-      const overrides = db.prepare(
-        `SELECT JSON_EXTRACT(data, '$.rule') as rule, JSON_EXTRACT(data, '$.reason') as reason, timestamp as date
-         FROM events WHERE type = 'OVERRIDE' ORDER BY timestamp DESC LIMIT 50`
-      ).all();
-      const totalViolations = db.prepare(`SELECT COUNT(*) as count FROM events WHERE type = 'VIOLATION'`).get() as { count: number };
-      const totalOverrides = db.prepare(`SELECT COUNT(*) as count FROM events WHERE type = 'OVERRIDE'`).get() as { count: number };
-      res.json({ byRule, byFile, overrides, totalViolations: totalViolations.count, totalOverrides: totalOverrides.count });
-    } catch {
+      res.json(eventService.getViolationSummary());
+    } catch (err) {
+      log.error('Violations summary failed', { error: String(err) });
       res.status(500).json({ error: 'Failed to query violations summary' });
     }
   });
@@ -204,19 +107,7 @@ export function createDataRoutes({
         }
       }
 
-      // Query violation and override stats per rule
-      const violationStats = db.prepare(
-        `SELECT JSON_EXTRACT(data, '$.rule') as rule, COUNT(*) as count, MAX(timestamp) as last_seen
-         FROM events WHERE type = 'VIOLATION' GROUP BY rule`
-      ).all() as Array<{ rule: string; count: number; last_seen: string }>;
-
-      const overrideStats = db.prepare(
-        `SELECT JSON_EXTRACT(data, '$.rule') as rule, COUNT(*) as count
-         FROM events WHERE type = 'OVERRIDE' GROUP BY rule`
-      ).all() as Array<{ rule: string; count: number }>;
-
-      const violationMap = new Map(violationStats.map((v) => [v.rule, v]));
-      const overrideMap = new Map(overrideStats.map((o) => [o.rule, o]));
+      const { violations: violationMap, overrides: overrideMap } = eventService.getViolationStatsByRule();
 
       // Build summary counts
       const summary = { guards: 0, gates: 0, lifecycle: 0, observers: 0 };
@@ -239,7 +130,8 @@ export function createDataRoutes({
       }));
 
       res.json({ summary, rules, totalEdges: allEdges.length });
-    } catch {
+    } catch (err) {
+      log.error('Enforcement rules failed', { error: String(err) });
       res.status(500).json({ error: 'Failed to query enforcement rules' });
     }
   });
@@ -248,14 +140,10 @@ export function createDataRoutes({
 
   router.get('/events/violations/trend', (req, res) => {
     try {
-      const days = Number(req.query.days) || 30;
-      const trend = db.prepare(
-        `SELECT date(timestamp) as day, JSON_EXTRACT(data, '$.rule') as rule, COUNT(*) as count
-         FROM events WHERE type = 'VIOLATION' AND timestamp >= datetime('now', ? || ' days')
-         GROUP BY day, rule ORDER BY day ASC`
-      ).all(`-${days}`) as Array<{ day: string; rule: string; count: number }>;
-      res.json(trend);
-    } catch {
+      const days = Math.max(1, Math.min(365, Number(req.query.days) || 30));
+      res.json(eventService.getViolationTrend(days));
+    } catch (err) {
+      log.error('Violation trends failed', { error: String(err) });
       res.status(500).json({ error: 'Failed to query violation trends' });
     }
   });
@@ -330,8 +218,7 @@ export function createDataRoutes({
 
   router.get('/pipeline/drift', async (_req, res) => {
     try {
-      const drift = await computeDrift();
-      res.json(drift);
+      res.json(await gitService.getPipelineDrift());
     } catch (err) {
       res.status(500).json({ error: 'Failed to compute drift', details: String(err) });
     }
@@ -339,19 +226,9 @@ export function createDataRoutes({
 
   router.get('/deployments/frequency', (_req, res) => {
     try {
-      const rows = db.prepare(
-        `SELECT environment, strftime('%Y-W%W', started_at) as week, COUNT(*) as count
-         FROM deployments WHERE started_at > datetime('now', '-56 days') GROUP BY environment, week ORDER BY week ASC`
-      ).all() as Array<{ environment: string; week: string; count: number }>;
-      const weekMap = new Map<string, { week: string; staging: number; production: number }>();
-      for (const row of rows) {
-        if (!weekMap.has(row.week)) weekMap.set(row.week, { week: row.week, staging: 0, production: 0 });
-        const entry = weekMap.get(row.week)!;
-        if (row.environment === 'staging') entry.staging = row.count;
-        if (row.environment === 'production') entry.production = row.count;
-      }
-      res.json([...weekMap.values()]);
-    } catch {
+      res.json(eventService.getDeployFrequency());
+    } catch (err) {
+      log.error('Deploy frequency query failed', { error: String(err) });
       res.status(500).json({ error: 'Failed to query deployment frequency' });
     }
   });
@@ -417,7 +294,7 @@ export function createDataRoutes({
     let stats: SessionStats | null = null;
 
     if (parsed.claude_session_id && typeof parsed.claude_session_id === 'string') {
-      const claudeSessions = await getClaudeSessions();
+      const claudeSessions = await getClaudeSessions(undefined, projectRoot);
       const match = claudeSessions.find(s => s.id === parsed.claude_session_id);
       if (match) {
         meta = {
@@ -429,7 +306,7 @@ export function createDataRoutes({
           lastActiveAt: match.lastActiveAt,
         };
       }
-      stats = getSessionStats(parsed.claude_session_id as string);
+      stats = getSessionStats(parsed.claude_session_id as string, projectRoot);
     }
 
     if (!content) {
@@ -466,7 +343,8 @@ export function createDataRoutes({
       return;
     }
 
-    const resumeCmd = `cd '${projectRoot}' && claude --dangerously-skip-permissions --resume '${claude_session_id}'`;
+    const flagsStr = buildClaudeFlags(config.claude.dispatchFlags);
+    const resumeCmd = `cd '${projectRoot}' && claude ${flagsStr} --resume '${claude_session_id}'`;
 
     try {
       await launchInTerminal(resumeCmd);

package/server/routes/dispatch-routes.ts

@@ -1,15 +1,17 @@
 import { Router } from 'express';
 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 { launchInCategorizedTerminal, escapeForAnsiC, buildSessionName, snapshotSessionPids, discoverNewSession, renameSession } from '../utils/terminal-launcher.js';
+import { launchInCategorizedTerminal, escapeForAnsiC, shellQuote, buildSessionName, snapshotSessionPids, discoverNewSession, renameSession } from '../utils/terminal-launcher.js';
 import { resolveDispatchEvent, resolveAbandonedDispatchesForScope, getActiveScopeIds, getAbandonedScopeIds, linkPidToDispatch } from '../utils/dispatch-utils.js';
 import type { WorkflowEngine } from '../../shared/workflow-engine.js';
+import type { OrbitalConfig } from '../config.js';
+import { buildClaudeFlags, buildEnvVarPrefix } from '../utils/flag-builder.js';
 import { createLogger } from '../utils/logger.js';
 
 const log = createLogger('dispatch');
 
-const MAX_BATCH_SIZE = 20;
+const DEFAULT_MAX_BATCH_SIZE = 20;
 
 interface DispatchBody {
   scope_id?: number;
@@ -20,13 +22,14 @@ interface DispatchBody {
 
 interface DispatchRouteDeps {
   db: Database.Database;
-  io: Server;
+  io: Emitter;
   scopeService: ScopeService;
   projectRoot: string;
   engine: WorkflowEngine;
+  config: OrbitalConfig;
 }
 
-export function createDispatchRoutes({ db, io, scopeService, projectRoot, engine }: DispatchRouteDeps): Router {
+export function createDispatchRoutes({ db, io, scopeService, projectRoot, engine, config }: DispatchRouteDeps): Router {
   const router = Router();
 
   router.get('/dispatch/active-scopes', (_req, res) => {
@@ -79,6 +82,19 @@ export function createDispatchRoutes({ db, io, scopeService, projectRoot, engine
       }
     }
 
+    // Max concurrent dispatches guard
+    const maxConcurrent = config.dispatch.maxConcurrent;
+    if (maxConcurrent > 0) {
+      const activeCount = (db.prepare(
+        `SELECT COUNT(*) as count FROM events
+         WHERE type = 'DISPATCH' AND JSON_EXTRACT(data, '$.resolved') IS NULL`
+      ).get() as { count: number }).count;
+      if (activeCount >= maxConcurrent) {
+        res.status(429).json({ error: `Max concurrent dispatches reached (${maxConcurrent})` });
+        return;
+      }
+    }
+
     // Update scope status if transition provided
     if (scope_id != null && transition?.to) {
       const result = scopeService.updateStatus(scope_id, transition.to, 'dispatch');
@@ -107,22 +123,28 @@ export function createDispatchRoutes({ db, io, scopeService, projectRoot, engine
     const sessionName = buildSessionName({ scopeId: scope_id ?? undefined, title: scope?.title, command });
     const beforePids = snapshotSessionPids(projectRoot);
 
-    // Launch in iTerm — interactive TUI mode (no -p) for full visibility
+    // Launch in iTerm — interactive TUI mode (no -p unless printMode) for full visibility
     const promptText = prompt ?? command;
     const escaped = escapeForAnsiC(promptText);
-    const fullCmd = `cd '${projectRoot}' && ORBITAL_DISPATCH_ID='${eventId}' claude --dangerously-skip-permissions $'${escaped}'`;
+    const flagsStr = buildClaudeFlags(config.claude.dispatchFlags);
+    const envPrefix = buildEnvVarPrefix(config.dispatch.envVars);
+    const fullCmd = `cd '${shellQuote(projectRoot)}' && ${envPrefix}ORBITAL_DISPATCH_ID='${shellQuote(eventId)}' claude ${flagsStr} $'${escaped}'`;
     try {
       await launchInCategorizedTerminal(command, fullCmd, sessionName);
       res.json({ ok: true, dispatch_id: eventId, scope_id: scope_id ?? null });
 
-      // Fire-and-forget: discover session PID, link to dispatch, and rename
+      // Fire-and-forget: discover session PID, link to dispatch, and rename.
+      // If discovery fails, SESSION_START event handler will link via ORBITAL_DISPATCH_ID.
       discoverNewSession(projectRoot, beforePids)
         .then((session) => {
-          if (!session) return;
+          if (!session) {
+            log.warn('PID discovery returned null — dispatch will rely on ORBITAL_DISPATCH_ID for linkage', { dispatch_id: eventId, scope_id });
+            return;
+          }
           linkPidToDispatch(db, eventId, session.pid);
           if (sessionName) renameSession(projectRoot, session.sessionId, sessionName);
         })
-        .catch(err => log.error('PID discovery failed', { error: err.message }));
+        .catch(err => log.warn('PID discovery failed — dispatch will rely on ORBITAL_DISPATCH_ID for linkage', { dispatch_id: eventId, error: err.message }));
     } catch (err) {
       if (scope_id != null && transition?.from) {
         scopeService.updateStatus(scope_id, transition.from, 'rollback');
@@ -211,8 +233,9 @@ export function createDispatchRoutes({ db, io, scopeService, projectRoot, engine
     }
 
     // W-12: Validate batch size and scope ID types
-    if (scope_ids.length > MAX_BATCH_SIZE) {
-      res.status(400).json({ error: `Maximum batch size is ${MAX_BATCH_SIZE}` });
+    const maxBatch = config.dispatch.maxBatchSize || DEFAULT_MAX_BATCH_SIZE;
+    if (scope_ids.length > maxBatch) {
+      res.status(400).json({ error: `Maximum batch size is ${maxBatch}` });
       return;
     }
     if (!scope_ids.every(id => Number.isInteger(id) && id > 0)) {
@@ -245,21 +268,27 @@ export function createDispatchRoutes({ db, io, scopeService, projectRoot, engine
       timestamp: new Date().toISOString(),
     });
 
-    // Launch single CLI session
+    // Launch single CLI session with batch env vars
     const batchEscaped = escapeForAnsiC(command);
     const beforePids = snapshotSessionPids(projectRoot);
-    const fullCmd = `cd '${projectRoot}' && ORBITAL_DISPATCH_ID='${eventId}' claude --dangerously-skip-permissions -p $'${batchEscaped}'`;
+    const batchFlags = buildClaudeFlags(config.claude.dispatchFlags);
+    const envPrefix = buildEnvVarPrefix(config.dispatch.envVars);
+    const fullCmd = `cd '${shellQuote(projectRoot)}' && ${envPrefix}ORBITAL_DISPATCH_ID='${shellQuote(eventId)}' claude ${batchFlags} $'${batchEscaped}'`;
     try {
       await launchInCategorizedTerminal(command, fullCmd);
       res.json({ ok: true, dispatch_id: eventId, scope_ids });
 
-      // Fire-and-forget: discover session PID and link to dispatch
+      // Fire-and-forget: discover session PID and link to dispatch.
+      // If discovery fails, SESSION_START event handler will link via ORBITAL_DISPATCH_ID.
       discoverNewSession(projectRoot, beforePids)
         .then((session) => {
-          if (!session) return;
+          if (!session) {
+            log.warn('Batch PID discovery returned null — dispatch will rely on ORBITAL_DISPATCH_ID for linkage', { dispatch_id: eventId });
+            return;
+          }
           linkPidToDispatch(db, eventId, session.pid);
         })
-        .catch(err => log.error('Batch PID discovery failed', { error: err.message }));
+        .catch(err => log.warn('Batch PID discovery failed — dispatch will rely on ORBITAL_DISPATCH_ID for linkage', { dispatch_id: eventId, error: err.message }));
     } catch (err) {
       if (transition?.from) {
         for (const id of scope_ids) {