orbital-command 0.1.0

package/dist/server/server/routes/data-routes.js

@@ -0,0 +1,461 @@
+import { Router } from 'express';
+import { execFile } from 'child_process';
+import path from 'path';
+import { promisify } from 'util';
+import { getHookEnforcement } from '../../shared/workflow-config.js';
+import { getClaudeSessions, getSessionStats } from '../services/claude-session-service.js';
+import { launchInTerminal } from '../utils/terminal-launcher.js';
+const execFileAsync = promisify(execFile);
+const JSON_FIELDS = ['tags', 'blocked_by', 'blocks', 'data', 'discoveries', 'next_steps', 'details'];
+function parseJsonFields(row) {
+    const parsed = { ...row };
+    for (const field of JSON_FIELDS) {
+        if (typeof parsed[field] === 'string') {
+            try {
+                parsed[field] = JSON.parse(parsed[field]);
+            }
+            catch { /* keep string */ }
+        }
+    }
+    return parsed;
+}
+function parseDriftCommits(raw) {
+    if (!raw)
+        return [];
+    return raw.split('\n').map((line) => {
+        const [sha, date, message, author] = line.split('|');
+        return { sha, date, message: message ?? '', author: author ?? '' };
+    });
+}
+function parseHead(raw) {
+    const [sha, date, message] = raw.split('|');
+    return { sha: sha ?? '', date: date ?? '', message: message ?? '' };
+}
+export function createDataRoutes({ db, io, gateService, deployService, engine, projectRoot, inferScopeStatus, }) {
+    const router = Router();
+    // ─── Pipeline Drift (cached) ─────────────────────────────
+    let driftCache = null;
+    const DRIFT_CACHE_MS = 60_000;
+    async function gitLog(args) {
+        const { stdout } = await execFileAsync('git', args, { cwd: projectRoot });
+        return stdout.trim();
+    }
+    async function computeDrift() {
+        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 = {
+            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;
+        const scopeId = req.query.scope_id;
+        let query = 'SELECT * FROM events WHERE 1=1';
+        const params = [];
+        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);
+        res.json(events.map(parseJsonFields));
+    });
+    router.post('/events', (req, res) => {
+        const { id, type, scope_id, session_id, agent, data, timestamp } = req.body;
+        if (!type || typeof type !== 'string') {
+            res.status(400).json({ error: 'type must be a non-empty string' });
+            return;
+        }
+        if (scope_id != null && (!Number.isInteger(scope_id) || scope_id <= 0)) {
+            res.status(400).json({ error: 'scope_id must be a positive integer or null' });
+            return;
+        }
+        const eventId = id || crypto.randomUUID();
+        const ts = timestamp || new Date().toISOString();
+        const eventData = data ?? {};
+        db.prepare(`INSERT OR IGNORE INTO events (id, type, scope_id, session_id, agent, data, timestamp)
+       VALUES (?, ?, ?, ?, ?, ?, ?)`).run(eventId, type, scope_id ?? null, session_id ?? null, agent ?? null, JSON.stringify(eventData), ts);
+        const event = { id: eventId, type, scope_id, session_id, agent, data: eventData, timestamp: ts };
+        io.emit('event:new', event);
+        inferScopeStatus(type, scope_id ?? eventData.scope_id, eventData);
+        res.status(201).json(event);
+    });
+    // ─── Violations Summary ──────────────────────────────────
+    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();
+            const totalOverrides = db.prepare(`SELECT COUNT(*) as count FROM events WHERE type = 'OVERRIDE'`).get();
+            res.json({ byRule, byFile, overrides, totalViolations: totalViolations.count, totalOverrides: totalOverrides.count });
+        }
+        catch {
+            res.status(500).json({ error: 'Failed to query violations summary' });
+        }
+    });
+    // ─── Enforcement Rules ───────────────────────────────────────
+    router.get('/enforcement/rules', (_req, res) => {
+        try {
+            const allHooks = engine.getAllHooks();
+            const allEdges = engine.getAllEdges();
+            // Build edge map: hookId → edges it's attached to
+            const hookEdgeMap = new Map();
+            for (const edge of allEdges) {
+                for (const hookId of edge.hooks ?? []) {
+                    if (!hookEdgeMap.has(hookId))
+                        hookEdgeMap.set(hookId, []);
+                    hookEdgeMap.get(hookId).push({ from: edge.from, to: edge.to, label: edge.label });
+                }
+            }
+            // 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();
+            const overrideStats = db.prepare(`SELECT JSON_EXTRACT(data, '$.rule') as rule, COUNT(*) as count
+         FROM events WHERE type = 'OVERRIDE' GROUP BY rule`).all();
+            const violationMap = new Map(violationStats.map((v) => [v.rule, v]));
+            const overrideMap = new Map(overrideStats.map((o) => [o.rule, o]));
+            // Build summary counts
+            const summary = { guards: 0, gates: 0, lifecycle: 0, observers: 0 };
+            for (const hook of allHooks) {
+                if (hook.category === 'guard')
+                    summary.guards++;
+                else if (hook.category === 'gate')
+                    summary.gates++;
+                else if (hook.category === 'lifecycle')
+                    summary.lifecycle++;
+                else if (hook.category === 'observer')
+                    summary.observers++;
+            }
+            const rules = allHooks.map((hook) => ({
+                hook,
+                enforcement: getHookEnforcement(hook),
+                edges: hookEdgeMap.get(hook.id) ?? [],
+                stats: {
+                    violations: violationMap.get(hook.id)?.count ?? 0,
+                    overrides: overrideMap.get(hook.id)?.count ?? 0,
+                    last_triggered: violationMap.get(hook.id)?.last_seen ?? null,
+                },
+            }));
+            res.json({ summary, rules, totalEdges: allEdges.length });
+        }
+        catch {
+            res.status(500).json({ error: 'Failed to query enforcement rules' });
+        }
+    });
+    // ─── Violation Trends ──────────────────────────────────────
+    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}`);
+            res.json(trend);
+        }
+        catch {
+            res.status(500).json({ error: 'Failed to query violation trends' });
+        }
+    });
+    // ─── Gate Routes ───────────────────────────────────────────
+    router.get('/gates', (req, res) => {
+        const scopeId = req.query.scope_id;
+        if (scopeId) {
+            res.json(gateService.getLatestForScope(Number(scopeId)));
+        }
+        else {
+            res.json(gateService.getLatestRun());
+        }
+    });
+    router.get('/gates/trend', (req, res) => {
+        const limit = Number(req.query.limit) || 30;
+        res.json(gateService.getTrend(limit));
+    });
+    router.get('/gates/stats', (_req, res) => {
+        res.json(gateService.getStats());
+    });
+    router.post('/gates', (req, res) => {
+        const { scope_id, gate_name, status, details, duration_ms, commit_sha } = req.body;
+        const VALID_GATE_STATUSES = ['pass', 'fail', 'running', 'skipped'];
+        if (!gate_name || typeof gate_name !== 'string') {
+            res.status(400).json({ error: 'gate_name must be a non-empty string' });
+            return;
+        }
+        if (status && !VALID_GATE_STATUSES.includes(status)) {
+            res.status(400).json({ error: `status must be one of: ${VALID_GATE_STATUSES.join(', ')}` });
+            return;
+        }
+        gateService.record({ scope_id, gate_name, status, details, duration_ms, commit_sha });
+        res.status(201).json({ ok: true });
+    });
+    // ─── Deployment Routes ─────────────────────────────────────
+    router.get('/deployments', (_req, res) => {
+        res.json(deployService.getRecent().map(parseJsonFields));
+    });
+    router.get('/deployments/latest', (_req, res) => {
+        res.json(deployService.getLatestPerEnv().map(parseJsonFields));
+    });
+    router.post('/deployments', (req, res) => {
+        const VALID_ENVIRONMENTS = ['staging', 'production'];
+        if (req.body.environment && !VALID_ENVIRONMENTS.includes(req.body.environment)) {
+            res.status(400).json({ error: `environment must be one of: ${VALID_ENVIRONMENTS.join(', ')}` });
+            return;
+        }
+        const id = deployService.record(req.body);
+        res.status(201).json({ id });
+    });
+    router.patch('/deployments/:id', (req, res) => {
+        const id = Number(req.params.id);
+        const { status, details } = req.body;
+        if (!status) {
+            res.status(400).json({ error: 'status is required' });
+            return;
+        }
+        deployService.updateStatus(id, status, details);
+        res.json({ ok: true });
+    });
+    router.get('/pipeline/drift', async (_req, res) => {
+        try {
+            const drift = await computeDrift();
+            res.json(drift);
+        }
+        catch (err) {
+            res.status(500).json({ error: 'Failed to compute drift', details: String(err) });
+        }
+    });
+    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();
+            const weekMap = new Map();
+            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.status(500).json({ error: 'Failed to query deployment frequency' });
+        }
+    });
+    // ─── Session Routes ────────────────────────────────────────
+    router.get('/sessions', (_req, res) => {
+        const rows = db.prepare('SELECT * FROM sessions ORDER BY started_at DESC').all()
+            .map(parseJsonFields);
+        const seen = new Map();
+        const scopeMap = new Map();
+        const actionMap = new Map();
+        for (const row of rows) {
+            const key = row.claude_session_id ?? row.id;
+            if (!seen.has(key)) {
+                seen.set(key, row);
+                scopeMap.set(key, []);
+                actionMap.set(key, []);
+            }
+            const sid = row.scope_id;
+            if (sid != null) {
+                const arr = scopeMap.get(key);
+                if (!arr.includes(sid))
+                    arr.push(sid);
+            }
+            const action = row.action;
+            if (action) {
+                const actions = actionMap.get(key);
+                if (!actions.includes(action))
+                    actions.push(action);
+            }
+        }
+        const results = [...seen.values()].map((row) => {
+            const key = row.claude_session_id ?? row.id;
+            return { ...row, scope_ids: scopeMap.get(key) ?? [], actions: actionMap.get(key) ?? [] };
+        });
+        res.json(results.slice(0, 50));
+    });
+    // ─── Scope Sessions ───────────────────────────────────────
+    router.get('/scopes/:id/sessions', (req, res) => {
+        const scopeId = Number(req.params.id);
+        const sessions = db.prepare('SELECT * FROM sessions WHERE scope_id = ? ORDER BY started_at DESC')
+            .all(scopeId);
+        res.json(sessions.map(parseJsonFields));
+    });
+    router.get('/sessions/:id/content', async (req, res) => {
+        const session = db.prepare('SELECT * FROM sessions WHERE id = ?')
+            .get(req.params.id);
+        if (!session) {
+            res.status(404).json({ error: 'Session not found' });
+            return;
+        }
+        const parsed = parseJsonFields(session);
+        let content = '';
+        let meta = null;
+        let stats = null;
+        if (parsed.claude_session_id && typeof parsed.claude_session_id === 'string') {
+            const claudeSessions = await getClaudeSessions();
+            const match = claudeSessions.find(s => s.id === parsed.claude_session_id);
+            if (match) {
+                meta = {
+                    slug: match.slug,
+                    branch: match.branch,
+                    fileSize: match.fileSize,
+                    summary: match.summary,
+                    startedAt: match.startedAt,
+                    lastActiveAt: match.lastActiveAt,
+                };
+            }
+            stats = getSessionStats(parsed.claude_session_id);
+        }
+        if (!content) {
+            const parts = [];
+            if (parsed.summary)
+                parts.push(`# ${parsed.summary}\n`);
+            const discoveries = Array.isArray(parsed.discoveries) ? parsed.discoveries : [];
+            if (discoveries.length > 0) {
+                parts.push('## Completed\n');
+                for (const d of discoveries)
+                    parts.push(`- ${d}`);
+                parts.push('');
+            }
+            const nextSteps = Array.isArray(parsed.next_steps) ? parsed.next_steps : [];
+            if (nextSteps.length > 0) {
+                parts.push('## Next Steps\n');
+                for (const n of nextSteps)
+                    parts.push(`- ${n}`);
+            }
+            content = parts.join('\n');
+        }
+        res.json({
+            id: parsed.id,
+            content,
+            claude_session_id: parsed.claude_session_id ?? null,
+            meta,
+            stats,
+        });
+    });
+    router.post('/sessions/:id/resume', async (req, res) => {
+        const { claude_session_id } = req.body;
+        if (!claude_session_id || !/^[0-9a-f-]{36}$/i.test(claude_session_id)) {
+            res.status(400).json({ error: 'Valid claude_session_id (UUID) required' });
+            return;
+        }
+        const resumeCmd = `cd '${projectRoot}' && claude --dangerously-skip-permissions --resume '${claude_session_id}'`;
+        try {
+            await launchInTerminal(resumeCmd);
+            res.json({ ok: true, session_id: claude_session_id });
+        }
+        catch (err) {
+            res.status(500).json({ error: 'Failed to launch terminal', details: String(err) });
+        }
+    });
+    // ─── Git Status ────────────────────────────────────────────
+    router.get('/git/status', async (_req, res) => {
+        try {
+            const [branchResult, statusResult] = await Promise.all([
+                execFileAsync('git', ['branch', '--show-current'], { cwd: projectRoot }),
+                execFileAsync('git', ['status', '--porcelain'], { cwd: projectRoot }),
+            ]);
+            const branch = branchResult.stdout.trim();
+            const dirty = statusResult.stdout.trim().length > 0;
+            let detached = false;
+            if (!branch) {
+                detached = true;
+            }
+            res.json({ branch: branch || '(detached)', dirty, detached });
+        }
+        catch (err) {
+            res.status(500).json({ error: 'Failed to get git status', details: String(err) });
+        }
+    });
+    router.get('/worktrees', async (_req, res) => {
+        try {
+            const { stdout } = await execFileAsync('git', ['worktree', 'list', '--porcelain'], { cwd: projectRoot });
+            const worktrees = [];
+            let current = { path: '', branch: '', head: '' };
+            for (const line of stdout.split('\n')) {
+                if (line.startsWith('worktree ')) {
+                    if (current.path)
+                        worktrees.push(current);
+                    current = { path: line.slice(9), branch: '', head: '' };
+                }
+                else if (line.startsWith('HEAD ')) {
+                    current.head = line.slice(5);
+                }
+                else if (line.startsWith('branch ')) {
+                    current.branch = line.slice(7);
+                }
+                else if (line === '') {
+                    if (current.path)
+                        worktrees.push(current);
+                    current = { path: '', branch: '', head: '' };
+                }
+            }
+            if (current.path)
+                worktrees.push(current);
+            res.json(worktrees);
+        }
+        catch (err) {
+            res.status(500).json({ error: 'Failed to list worktrees', details: String(err) });
+        }
+    });
+    // ─── Open File ──────────────────────────────────────────────
+    router.post('/open-file', (req, res) => {
+        const filePath = req.query.path || '';
+        if (!filePath || filePath.includes('..')) {
+            res.status(400).json({ error: 'Invalid path' });
+            return;
+        }
+        const absolute = path.resolve(projectRoot, filePath);
+        const resolvedRoot = path.resolve(projectRoot) + path.sep;
+        if (!absolute.startsWith(resolvedRoot)) {
+            res.status(400).json({ error: 'Path escapes project root' });
+            return;
+        }
+        execFile('open', [absolute], (err) => {
+            if (err) {
+                res.status(500).json({ error: 'Failed to open file' });
+                return;
+            }
+            res.json({ ok: true });
+        });
+    });
+    return router;
+}

package/dist/server/server/routes/dispatch-routes.js

@@ -0,0 +1,215 @@
+import { Router } from 'express';
+import { launchInCategorizedTerminal, escapeForAnsiC, buildSessionName, snapshotSessionPids, discoverNewSession, renameSession } from '../utils/terminal-launcher.js';
+import { resolveDispatchEvent, resolveAbandonedDispatchesForScope, getActiveScopeIds, getAbandonedScopeIds, linkPidToDispatch } from '../utils/dispatch-utils.js';
+import { createLogger } from '../utils/logger.js';
+const log = createLogger('dispatch');
+const MAX_BATCH_SIZE = 20;
+export function createDispatchRoutes({ db, io, scopeService, projectRoot, engine }) {
+    const router = Router();
+    router.get('/dispatch/active-scopes', (_req, res) => {
+        const scope_ids = getActiveScopeIds(db, scopeService, engine);
+        const abandoned_scopes = getAbandonedScopeIds(db, scopeService, engine, scope_ids);
+        res.json({ scope_ids, abandoned_scopes });
+    });
+    router.get('/dispatch/active', (req, res) => {
+        const scopeId = Number(req.query.scope_id);
+        if (isNaN(scopeId) || scopeId <= 0) {
+            res.status(400).json({ error: 'Valid scope_id query param required' });
+            return;
+        }
+        const active = db.prepare(`SELECT id, timestamp, JSON_EXTRACT(data, '$.command') as command
+       FROM events
+       WHERE type = 'DISPATCH' AND scope_id = ? AND JSON_EXTRACT(data, '$.resolved') IS NULL
+       ORDER BY timestamp DESC LIMIT 1`).get(scopeId);
+        res.json({ active: active ?? null });
+    });
+    router.post('/dispatch', async (req, res) => {
+        const { scope_id, command, prompt, transition } = req.body;
+        if (!command || !engine.isAllowedCommand(command)) {
+            res.status(400).json({ error: 'Command must start with /scope-, /git-, /test-, or /session-' });
+            return;
+        }
+        // W-11: Validate prompt field against allowed command prefixes
+        if (prompt && !engine.isAllowedCommand(prompt)) {
+            res.status(400).json({ error: 'Prompt must start with /scope-, /git-, /test-, or /session-' });
+            return;
+        }
+        // Active session guard
+        if (scope_id != null) {
+            const active = db.prepare(`SELECT id FROM events
+         WHERE type = 'DISPATCH' AND scope_id = ? AND JSON_EXTRACT(data, '$.resolved') IS NULL
+         ORDER BY timestamp DESC LIMIT 1`).get(scope_id);
+            if (active) {
+                res.status(409).json({ error: 'Active dispatch exists', dispatch_id: active.id });
+                return;
+            }
+        }
+        // Update scope status if transition provided
+        if (scope_id != null && transition?.to) {
+            const result = scopeService.updateStatus(scope_id, transition.to, 'dispatch');
+            if (!result.ok) {
+                res.status(400).json({ error: result.error });
+                return;
+            }
+        }
+        // Record DISPATCH event
+        const eventId = crypto.randomUUID();
+        const eventData = { command, transition: transition ?? null, resolved: null };
+        db.prepare(`INSERT INTO events (id, type, scope_id, session_id, agent, data, timestamp)
+       VALUES (?, 'DISPATCH', ?, NULL, 'dashboard', ?, ?)`).run(eventId, scope_id ?? null, JSON.stringify(eventData), new Date().toISOString());
+        io.emit('event:new', {
+            id: eventId, type: 'DISPATCH', scope_id: scope_id ?? null,
+            session_id: null, agent: 'dashboard', data: eventData,
+            timestamp: new Date().toISOString(),
+        });
+        // Build scope-aware session name before launch
+        const scope = scope_id != null ? scopeService.getById(scope_id) : undefined;
+        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
+        const promptText = prompt ?? command;
+        const escaped = escapeForAnsiC(promptText);
+        const fullCmd = `cd '${projectRoot}' && ORBITAL_DISPATCH_ID='${eventId}' claude --dangerously-skip-permissions $'${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
+            discoverNewSession(projectRoot, beforePids)
+                .then((session) => {
+                if (!session)
+                    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) {
+            if (scope_id != null && transition?.from) {
+                scopeService.updateStatus(scope_id, transition.from, 'rollback');
+            }
+            resolveDispatchEvent(db, io, eventId, 'failed', String(err));
+            res.status(500).json({ error: 'Failed to launch terminal', details: String(err) });
+        }
+    });
+    router.post('/dispatch/:id/resolve', (req, res) => {
+        const eventId = req.params.id;
+        const row = db.prepare('SELECT id FROM events WHERE id = ? AND type = ?')
+            .get(eventId, 'DISPATCH');
+        if (!row) {
+            res.status(404).json({ error: 'Dispatch event not found' });
+            return;
+        }
+        resolveDispatchEvent(db, io, eventId, 'completed');
+        res.json({ ok: true, dispatch_id: eventId });
+    });
+    /** Recover an abandoned scope by reverting it to its pre-dispatch status. */
+    router.post('/dispatch/recover/:scopeId', (req, res) => {
+        try {
+            const scopeId = Number(req.params.scopeId);
+            if (isNaN(scopeId) || scopeId <= 0) {
+                res.status(400).json({ error: 'Valid scopeId required' });
+                return;
+            }
+            const { from_status } = req.body;
+            if (!from_status) {
+                res.status(400).json({ error: 'from_status is required' });
+                return;
+            }
+            // Revert scope to its pre-dispatch status
+            const result = scopeService.updateStatus(scopeId, from_status, 'rollback');
+            if (!result.ok) {
+                res.status(400).json({ error: result.error });
+                return;
+            }
+            resolveAbandonedDispatchesForScope(db, io, scopeId);
+            res.json({ ok: true, scope_id: scopeId, reverted_to: from_status });
+        }
+        catch (err) {
+            log.error('Error recovering scope', { error: String(err) });
+            res.status(500).json({ error: 'Internal server error', details: String(err) });
+        }
+    });
+    /** Dismiss abandoned state without reverting scope status. */
+    router.post('/dispatch/dismiss-abandoned/:scopeId', (req, res) => {
+        try {
+            const scopeId = Number(req.params.scopeId);
+            if (isNaN(scopeId) || scopeId <= 0) {
+                res.status(400).json({ error: 'Valid scopeId required' });
+                return;
+            }
+            const dismissed = resolveAbandonedDispatchesForScope(db, io, scopeId);
+            res.json({ ok: true, scope_id: scopeId, dismissed });
+        }
+        catch (err) {
+            log.error('Error dismissing abandoned dispatches', { error: String(err) });
+            res.status(500).json({ error: 'Internal server error', details: String(err) });
+        }
+    });
+    router.post('/dispatch/batch', async (req, res) => {
+        const { scope_ids, command, transition } = req.body;
+        if (!command || !engine.isAllowedCommand(command)) {
+            res.status(400).json({ error: 'Command must start with /scope-, /git-, /test-, or /session-' });
+            return;
+        }
+        if (!Array.isArray(scope_ids) || scope_ids.length === 0) {
+            res.status(400).json({ error: 'scope_ids must be a non-empty array' });
+            return;
+        }
+        // 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}` });
+            return;
+        }
+        if (!scope_ids.every(id => Number.isInteger(id) && id > 0)) {
+            res.status(400).json({ error: 'scope_ids must contain positive integers' });
+            return;
+        }
+        // Update all scope statuses
+        if (transition?.to) {
+            for (const id of scope_ids) {
+                const result = scopeService.updateStatus(id, transition.to, 'dispatch');
+                if (!result.ok) {
+                    res.status(400).json({ error: `Scope ${id}: ${result.error}` });
+                    return;
+                }
+            }
+        }
+        // Record single DISPATCH event for the batch
+        const eventId = crypto.randomUUID();
+        const eventData = { command, transition: transition ?? null, scope_ids, batch: true, resolved: null };
+        db.prepare(`INSERT INTO events (id, type, scope_id, session_id, agent, data, timestamp)
+       VALUES (?, 'DISPATCH', NULL, NULL, 'dashboard', ?, ?)`).run(eventId, JSON.stringify(eventData), new Date().toISOString());
+        io.emit('event:new', {
+            id: eventId, type: 'DISPATCH', scope_id: null,
+            session_id: null, agent: 'dashboard', data: eventData,
+            timestamp: new Date().toISOString(),
+        });
+        // Launch single CLI session
+        const batchEscaped = escapeForAnsiC(command);
+        const beforePids = snapshotSessionPids(projectRoot);
+        const fullCmd = `cd '${projectRoot}' && ORBITAL_DISPATCH_ID='${eventId}' claude --dangerously-skip-permissions -p $'${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
+            discoverNewSession(projectRoot, beforePids)
+                .then((session) => {
+                if (!session)
+                    return;
+                linkPidToDispatch(db, eventId, session.pid);
+            })
+                .catch(err => log.error('Batch PID discovery failed', { error: err.message }));
+        }
+        catch (err) {
+            if (transition?.from) {
+                for (const id of scope_ids) {
+                    scopeService.updateStatus(id, transition.from, 'rollback');
+                }
+            }
+            resolveDispatchEvent(db, io, eventId, 'failed', String(err));
+            res.status(500).json({ error: 'Failed to launch terminal', details: String(err) });
+        }
+    });
+    return router;
+}