orbital-command 0.1.0

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

@@ -0,0 +1,305 @@
+import { isSessionPidAlive } from './terminal-launcher.js';
+import { createLogger } from './logger.js';
+const log = createLogger('dispatch');
+/** Mark a DISPATCH event as resolved and emit socket notification. */
+export function resolveDispatchEvent(db, io, eventId, outcome, error) {
+    const row = db.prepare('SELECT data, scope_id FROM events WHERE id = ?')
+        .get(eventId);
+    if (!row)
+        return;
+    let data;
+    try {
+        data = JSON.parse(row.data);
+    }
+    catch (e) {
+        log.error('Failed to parse DISPATCH event data', { eventId, error: String(e) });
+        return;
+    }
+    data.resolved = { outcome, at: new Date().toISOString(), ...(error ? { error } : {}) };
+    db.prepare('UPDATE events SET data = ? WHERE id = ?').run(JSON.stringify(data), eventId);
+    io.emit('dispatch:resolved', {
+        event_id: eventId,
+        scope_id: row.scope_id,
+        scope_ids: data.scope_ids ?? null,
+        outcome,
+    });
+}
+/** Resolve all unresolved DISPATCH events for a given scope */
+export function resolveActiveDispatchesForScope(db, io, scopeId, outcome) {
+    const rows = db.prepare(`SELECT id FROM events
+     WHERE type = 'DISPATCH' AND scope_id = ? AND JSON_EXTRACT(data, '$.resolved') IS NULL`).all(scopeId);
+    for (const row of rows) {
+        resolveDispatchEvent(db, io, row.id, outcome);
+    }
+}
+/** Re-resolve abandoned DISPATCH events for a scope as completed.
+ *  Used by both recover and dismiss-abandoned routes to clear abandoned state. */
+export function resolveAbandonedDispatchesForScope(db, io, scopeId) {
+    const rows = db.prepare(`SELECT id FROM events
+     WHERE type = 'DISPATCH' AND scope_id = ?
+       AND JSON_EXTRACT(data, '$.resolved.outcome') = 'abandoned'`).all(scopeId);
+    for (const row of rows) {
+        resolveDispatchEvent(db, io, row.id, 'completed');
+    }
+    return rows.length;
+}
+/** Store the PID of the Claude session working on a dispatch.
+ *  Called after discoverNewSession finds the launched session, or when
+ *  a SESSION_START event includes ORBITAL_DISPATCH_ID from the env var. */
+export function linkPidToDispatch(db, eventId, pid) {
+    const row = db.prepare('SELECT data FROM events WHERE id = ?')
+        .get(eventId);
+    if (!row)
+        return;
+    let data;
+    try {
+        data = JSON.parse(row.data);
+    }
+    catch (e) {
+        log.error('Failed to parse DISPATCH event data', { eventId, error: String(e) });
+        return;
+    }
+    data.pid = pid;
+    db.prepare('UPDATE events SET data = ? WHERE id = ?').run(JSON.stringify(data), eventId);
+}
+/** 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. */
+export function resolveDispatchesByPid(db, io, pid) {
+    const rows = db.prepare(`SELECT id FROM events
+     WHERE type = 'DISPATCH'
+       AND JSON_EXTRACT(data, '$.resolved') IS NULL
+       AND JSON_EXTRACT(data, '$.pid') = ?`).all(pid);
+    for (const row of rows) {
+        resolveDispatchEvent(db, io, row.id, 'abandoned');
+    }
+    return rows.length;
+}
+/** 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'. */
+export function resolveDispatchesByDispatchId(db, io, dispatchId) {
+    const row = db.prepare(`SELECT id FROM events
+     WHERE id = ? AND type = 'DISPATCH' AND JSON_EXTRACT(data, '$.resolved') IS NULL`).get(dispatchId);
+    if (!row)
+        return 0;
+    resolveDispatchEvent(db, io, row.id, 'abandoned');
+    return 1;
+}
+/** Fallback age threshold for dispatches without a linked PID (30 minutes). */
+const STALE_AGE_MS = 30 * 60 * 1000;
+/** Get all scope IDs that have actively running DISPATCH events.
+ *  Uses PID liveness (process.kill(pid, 0)) when available, falls back to
+ *  age-based heuristic for legacy dispatches without a linked PID. */
+export function getActiveScopeIds(db, scopeService, engine) {
+    const rows = db.prepare(`SELECT scope_id, data FROM events
+     WHERE type = 'DISPATCH'
+       AND scope_id IS NOT NULL
+       AND JSON_EXTRACT(data, '$.resolved') IS NULL`).all();
+    const cutoff = new Date(Date.now() - STALE_AGE_MS).toISOString();
+    const active = new Set();
+    for (const row of rows) {
+        if (active.has(row.scope_id))
+            continue; // already confirmed active
+        // Skip scopes in terminal states
+        const scope = scopeService.getById(row.scope_id);
+        if (scope && engine.isTerminalStatus(scope.status))
+            continue;
+        let data;
+        try {
+            data = JSON.parse(row.data);
+        }
+        catch (e) {
+            log.error('Failed to parse DISPATCH event data', { scope_id: row.scope_id, error: String(e) });
+            continue;
+        }
+        if (typeof data.pid === 'number') {
+            // Preferred: check if the Claude session process is still running
+            if (isSessionPidAlive(data.pid)) {
+                active.add(row.scope_id);
+            }
+        }
+        else {
+            // Fallback for legacy dispatches without PID: use age-based check
+            const dispatch = db.prepare(`SELECT timestamp FROM events
+         WHERE type = 'DISPATCH' AND scope_id = ? AND JSON_EXTRACT(data, '$.resolved') IS NULL
+         ORDER BY timestamp DESC LIMIT 1`).get(row.scope_id);
+            if (dispatch && dispatch.timestamp > cutoff) {
+                active.add(row.scope_id);
+            }
+        }
+    }
+    // Also check batch dispatches (scope_id IS NULL, batch = true)
+    const batchRows = db.prepare(`SELECT data FROM events
+     WHERE type = 'DISPATCH'
+       AND scope_id IS NULL
+       AND JSON_EXTRACT(data, '$.batch') = 1
+       AND JSON_EXTRACT(data, '$.resolved') IS NULL`).all();
+    for (const batchRow of batchRows) {
+        let batchData;
+        try {
+            batchData = JSON.parse(batchRow.data);
+        }
+        catch {
+            continue;
+        }
+        const scopeIds = batchData.scope_ids;
+        if (!Array.isArray(scopeIds))
+            continue;
+        let batchAlive = false;
+        if (typeof batchData.pid === 'number') {
+            batchAlive = isSessionPidAlive(batchData.pid);
+        }
+        else {
+            // No PID — consider active (stale cleanup will catch it)
+            batchAlive = true;
+        }
+        if (batchAlive) {
+            for (const id of scopeIds) {
+                const scope = scopeService.getById(id);
+                if (scope && !engine.isTerminalStatus(scope.status)) {
+                    active.add(id);
+                }
+            }
+        }
+    }
+    return [...active];
+}
+/** Resolve stale DISPATCH events. Three staleness criteria:
+ *  1. Scope already in a terminal state (as defined by workflow config)
+ *  2. Linked PID is no longer running (session ended/crashed)
+ *  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, io, scopeService, engine) {
+    const cutoff = new Date(Date.now() - STALE_AGE_MS).toISOString();
+    // Single query on events only — split by cache status
+    const rows = db.prepare(`SELECT id, scope_id, data, timestamp FROM events
+     WHERE type = 'DISPATCH'
+       AND scope_id IS NOT NULL
+       AND JSON_EXTRACT(data, '$.resolved') IS NULL`).all();
+    let resolved = 0;
+    for (const row of rows) {
+        const scope = scopeService.getById(row.scope_id);
+        const scopeStatus = scope?.status;
+        // Criterion 1: scope in terminal state
+        if (scopeStatus && engine.isTerminalStatus(scopeStatus)) {
+            resolveDispatchEvent(db, io, row.id, 'completed');
+            resolved++;
+            continue;
+        }
+        // Criteria 2+3: dead PID or old age
+        let data;
+        try {
+            data = JSON.parse(row.data);
+        }
+        catch (e) {
+            log.error('Failed to parse DISPATCH event data', { eventId: row.id, error: String(e) });
+            continue;
+        }
+        let isStale = false;
+        if (typeof data.pid === 'number') {
+            isStale = !isSessionPidAlive(data.pid);
+        }
+        else {
+            isStale = row.timestamp <= cutoff;
+        }
+        if (isStale) {
+            resolveDispatchEvent(db, io, row.id, 'abandoned');
+            resolved++;
+        }
+    }
+    // Second pass: batch dispatches (scope_id IS NULL, batch = true)
+    const batchRows = db.prepare(`SELECT id, data, timestamp FROM events
+     WHERE type = 'DISPATCH'
+       AND scope_id IS NULL
+       AND JSON_EXTRACT(data, '$.batch') = 1
+       AND JSON_EXTRACT(data, '$.resolved') IS NULL`).all();
+    for (const batchRow of batchRows) {
+        let batchData;
+        try {
+            batchData = JSON.parse(batchRow.data);
+        }
+        catch {
+            continue;
+        }
+        const scopeIds = batchData.scope_ids;
+        // Criterion 1: all batch scopes in terminal state
+        if (Array.isArray(scopeIds) && scopeIds.length > 0) {
+            const allTerminal = scopeIds.every(id => {
+                const scope = scopeService.getById(id);
+                return scope && engine.isTerminalStatus(scope.status);
+            });
+            if (allTerminal) {
+                resolveDispatchEvent(db, io, batchRow.id, 'completed');
+                resolved++;
+                continue;
+            }
+        }
+        // Criteria 2+3: dead PID or old age
+        if (typeof batchData.pid === 'number') {
+            if (!isSessionPidAlive(batchData.pid)) {
+                resolveDispatchEvent(db, io, batchRow.id, 'abandoned');
+                resolved++;
+            }
+        }
+        else if (batchRow.timestamp <= cutoff) {
+            resolveDispatchEvent(db, io, batchRow.id, 'abandoned');
+            resolved++;
+        }
+    }
+    return resolved;
+}
+/** Get scope IDs with recent abandoned dispatch outcomes.
+ *  Returns an array of abandoned scope entries with scope_id, from_status, and abandoned_at.
+ *  Only includes scopes that are NOT currently in a terminal state and
+ *  do NOT have a newer active (unresolved) dispatch. */
+export function getAbandonedScopeIds(db, scopeService, engine, activeScopeIds) {
+    const rows = db.prepare(`SELECT scope_id, data, timestamp FROM events
+     WHERE type = 'DISPATCH'
+       AND scope_id IS NOT NULL
+       AND JSON_EXTRACT(data, '$.resolved.outcome') = 'abandoned'
+     ORDER BY timestamp DESC`).all();
+    // Get active scope IDs to exclude scopes with new dispatches
+    const activeScopes = activeScopeIds ?? getActiveScopeIds(db, scopeService, engine);
+    const activeSet = new Set(activeScopes);
+    const seen = new Set();
+    const result = [];
+    for (const row of rows) {
+        if (seen.has(row.scope_id))
+            continue;
+        seen.add(row.scope_id);
+        // Skip if scope has a new active dispatch
+        if (activeSet.has(row.scope_id))
+            continue;
+        // Skip if scope is in terminal state
+        const scope = scopeService.getById(row.scope_id);
+        if (!scope)
+            continue;
+        if (engine.isTerminalStatus(scope.status))
+            continue;
+        let data;
+        try {
+            data = JSON.parse(row.data);
+        }
+        catch (e) {
+            log.error('Failed to parse DISPATCH event data', { scope_id: row.scope_id, error: String(e) });
+            continue;
+        }
+        const transition = data.transition;
+        const resolved = data.resolved;
+        const fromStatus = transition?.from ?? null;
+        const abandonedAt = resolved?.at ?? row.timestamp;
+        result.push({ scope_id: row.scope_id, from_status: fromStatus, abandoned_at: abandonedAt });
+    }
+    return result;
+}

package/dist/server/server/utils/logger.js

@@ -0,0 +1,86 @@
+// ─── Lightweight Structured Logger ──────────────────────────
+//
+// Zero dependencies. Colored, timestamped, component-namespaced output.
+// Usage:
+//   import { createLogger } from './utils/logger.js';
+//   const log = createLogger('scope');
+//   log.info('Status updated', { id: 3, from: 'backlog', to: 'implementing' });
+//   // => 12:34:56.789 INFO  [scope] Status updated id=3 from=backlog to=implementing
+const LEVEL_VALUE = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+};
+let currentLevel = 'info';
+export function setLogLevel(level) {
+    currentLevel = level;
+}
+export function getLogLevel() {
+    return currentLevel;
+}
+// ─── Colors (ANSI) ──────────────────────────────────────────
+const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
+const c = {
+    reset: useColor ? '\x1b[0m' : '',
+    dim: useColor ? '\x1b[2m' : '',
+    gray: useColor ? '\x1b[90m' : '',
+    cyan: useColor ? '\x1b[36m' : '',
+    yellow: useColor ? '\x1b[33m' : '',
+    red: useColor ? '\x1b[31m' : '',
+};
+const LEVEL_COLOR = {
+    debug: c.gray,
+    info: c.cyan,
+    warn: c.yellow,
+    error: c.red,
+};
+const LEVEL_LABEL = {
+    debug: 'DEBUG',
+    info: 'INFO ',
+    warn: 'WARN ',
+    error: 'ERROR',
+};
+// ─── Formatting ─────────────────────────────────────────────
+function timestamp() {
+    const d = new Date();
+    const h = String(d.getHours()).padStart(2, '0');
+    const m = String(d.getMinutes()).padStart(2, '0');
+    const s = String(d.getSeconds()).padStart(2, '0');
+    const ms = String(d.getMilliseconds()).padStart(3, '0');
+    return `${h}:${m}:${s}.${ms}`;
+}
+function formatData(data) {
+    if (!data)
+        return '';
+    const pairs = [];
+    for (const [k, v] of Object.entries(data)) {
+        if (v === undefined || v === null)
+            continue;
+        const val = typeof v === 'object' ? JSON.stringify(v) : String(v);
+        pairs.push(`${k}=${val}`);
+    }
+    return pairs.length > 0 ? ' ' + pairs.join(' ') : '';
+}
+function write(level, component, msg, data) {
+    if (LEVEL_VALUE[level] < LEVEL_VALUE[currentLevel])
+        return;
+    const color = 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`;
+    if (level === 'warn' || level === 'error') {
+        process.stderr.write(line);
+    }
+    else {
+        process.stdout.write(line);
+    }
+}
+export function createLogger(component) {
+    return {
+        debug: (msg, data) => write('debug', component, msg, data),
+        info: (msg, data) => write('info', component, msg, data),
+        warn: (msg, data) => write('warn', component, msg, data),
+        error: (msg, data) => write('error', component, msg, data),
+    };
+}