@ginkoai/cli 1.6.2 → 1.7.0

package/dist/lib/orchestrator-state.js

@@ -0,0 +1,332 @@
+/**
+ * @fileType: utility
+ * @status: current
+ * @updated: 2025-12-07
+ * @tags: [orchestrator, state, checkpoint, lifecycle, epic-004, sprint-4, task-10]
+ * @related: [../commands/orchestrate.ts, context-metrics.ts, graph/api-client.ts]
+ * @priority: high
+ * @complexity: medium
+ * @dependencies: [fs-extra, path]
+ */
+/**
+ * Orchestrator State Management (EPIC-004 Sprint 4 TASK-10)
+ *
+ * Handles:
+ * - State persistence to local filesystem and graph
+ * - State recovery on restart
+ * - Checkpoint creation for respawn scenarios
+ * - Exit condition tracking
+ *
+ * Exit Codes:
+ * - 0: Success (all tasks complete or graceful shutdown)
+ * - 1: Error (unrecoverable failure or no progress)
+ * - 75: Respawn needed (context pressure or max runtime)
+ */
+import fs from 'fs/promises';
+import path from 'path';
+// ============================================================
+// Constants
+// ============================================================
+export const EXIT_CODE_SUCCESS = 0;
+export const EXIT_CODE_ERROR = 1;
+export const EXIT_CODE_RESPAWN = 75;
+const CHECKPOINT_FILENAME = 'orchestrator-checkpoint.json';
+const STATE_NODE_LABEL = 'OrchestratorState';
+// ============================================================
+// Checkpoint Manager
+// ============================================================
+export class OrchestratorStateManager {
+    projectRoot;
+    graphId;
+    constructor(projectRoot, graphId) {
+        this.projectRoot = projectRoot;
+        this.graphId = graphId;
+    }
+    /**
+     * Get the local checkpoint file path
+     */
+    getCheckpointPath() {
+        return path.join(this.projectRoot, '.ginko', CHECKPOINT_FILENAME);
+    }
+    /**
+     * Check if a checkpoint exists
+     */
+    async hasCheckpoint() {
+        try {
+            await fs.access(this.getCheckpointPath());
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Load checkpoint from filesystem
+     */
+    async loadCheckpoint() {
+        try {
+            const checkpointPath = this.getCheckpointPath();
+            const content = await fs.readFile(checkpointPath, 'utf-8');
+            const checkpoint = JSON.parse(content);
+            // Validate version
+            if (!checkpoint.version || checkpoint.version < 1) {
+                console.warn('Warning: Old checkpoint format, may have missing fields');
+            }
+            return checkpoint;
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                return null; // No checkpoint exists
+            }
+            throw new Error(`Failed to load checkpoint: ${error.message}`);
+        }
+    }
+    /**
+     * Save checkpoint to filesystem
+     */
+    async saveCheckpoint(checkpoint, options) {
+        const checkpointPath = this.getCheckpointPath();
+        // Update with exit info if provided
+        const finalCheckpoint = {
+            ...checkpoint,
+            savedAt: new Date().toISOString(),
+            version: 1,
+            ...(options?.exitReason && { exitReason: options.exitReason }),
+            ...(options?.exitCode !== undefined && { exitCode: options.exitCode }),
+        };
+        // Ensure directory exists
+        await fs.mkdir(path.dirname(checkpointPath), { recursive: true });
+        // Write atomically (write to temp, then rename)
+        const tempPath = `${checkpointPath}.tmp`;
+        await fs.writeFile(tempPath, JSON.stringify(finalCheckpoint, null, 2), 'utf-8');
+        await fs.rename(tempPath, checkpointPath);
+    }
+    /**
+     * Delete checkpoint (after successful completion or explicit reset)
+     */
+    async deleteCheckpoint() {
+        try {
+            await fs.unlink(this.getCheckpointPath());
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT') {
+                throw error;
+            }
+            // Ignore if file doesn't exist
+        }
+    }
+    /**
+     * Create a fresh checkpoint from current state
+     * Accepts either a ContextMonitor (from runtime) or ContextMetrics (from tests)
+     */
+    createCheckpoint(state) {
+        // Get metrics from monitor or use provided metrics
+        const metrics = state.contextMonitor?.getMetrics() ?? state.contextMetrics;
+        if (!metrics) {
+            throw new Error('Either contextMonitor or contextMetrics must be provided');
+        }
+        return {
+            orchestratorId: state.orchestratorId,
+            orchestratorName: state.orchestratorName,
+            graphId: state.graphId,
+            sprintId: state.sprintId,
+            startedAt: state.startedAt.toISOString(),
+            savedAt: new Date().toISOString(),
+            lastProgressAt: state.lastProgressAt.toISOString(),
+            cyclesWithoutProgress: state.cyclesWithoutProgress,
+            completedTasks: Array.from(state.completedTasks),
+            inProgressTasks: Object.fromEntries(state.inProgressTasks),
+            blockedTasks: Array.from(state.blockedTasks),
+            assignmentHistory: state.assignmentHistory.map(a => ({
+                taskId: a.taskId,
+                agentId: a.agentId,
+                assignedAt: a.assignedAt.toISOString(),
+                status: a.status,
+            })),
+            contextMetrics: {
+                estimatedTokens: metrics.estimatedTokens,
+                contextLimit: metrics.contextLimit,
+                pressure: metrics.pressure,
+                messageCount: metrics.messageCount,
+                toolCallCount: metrics.toolCallCount,
+                eventsSinceStart: metrics.eventsSinceStart,
+                model: metrics.model,
+            },
+            version: 1,
+        };
+    }
+    /**
+     * Restore runtime state from checkpoint
+     */
+    restoreFromCheckpoint(checkpoint) {
+        return {
+            completedTasks: new Set(checkpoint.completedTasks),
+            inProgressTasks: new Map(Object.entries(checkpoint.inProgressTasks)),
+            blockedTasks: new Set(checkpoint.blockedTasks),
+            assignmentHistory: checkpoint.assignmentHistory.map(a => ({
+                taskId: a.taskId,
+                agentId: a.agentId,
+                assignedAt: new Date(a.assignedAt),
+                status: a.status,
+            })),
+            startedAt: new Date(checkpoint.startedAt),
+            lastProgressAt: new Date(checkpoint.lastProgressAt),
+            cyclesWithoutProgress: checkpoint.cyclesWithoutProgress,
+        };
+    }
+}
+// ============================================================
+// Graph Persistence (TASK-8: Orchestrator Recovery)
+// ============================================================
+/**
+ * Save orchestrator state to graph
+ * This enables cross-machine state recovery and team visibility
+ */
+export async function persistStateToGraph(checkpoint, graphApiClient) {
+    // Create or update OrchestratorState node
+    await graphApiClient.request('POST', '/api/v1/orchestrator/state', {
+        graphId: checkpoint.graphId,
+        orchestratorId: checkpoint.orchestratorId,
+        state: checkpoint,
+    });
+}
+/**
+ * Recover orchestrator state from graph
+ * Attempts to find the most recent state for the given epic/sprint
+ */
+export async function recoverStateFromGraph(graphId, epicId, graphApiClient) {
+    try {
+        // Query for most recent orchestrator state for this epic
+        const response = await graphApiClient.request('GET', `/api/v1/orchestrator/state?graphId=${graphId}&epicId=${epicId}`);
+        return response.state;
+    }
+    catch (error) {
+        // If endpoint doesn't exist yet or other error, return null
+        return null;
+    }
+}
+/**
+ * Reconcile task statuses after recovery
+ * Re-scans actual task status and compares with persisted state
+ * Handles discrepancies (e.g., task marked complete externally)
+ */
+export async function reconcileTaskStatuses(checkpoint, actualTasks, graphApiClient) {
+    const reconciledCheckpoint = { ...checkpoint };
+    const changes = [];
+    // Check completed tasks
+    for (const taskId of checkpoint.completedTasks) {
+        const actual = actualTasks.find(t => t.id === taskId);
+        if (actual && actual.status !== 'complete') {
+            // Task was marked incomplete externally - revert
+            reconciledCheckpoint.completedTasks = reconciledCheckpoint.completedTasks.filter(id => id !== taskId);
+            changes.push(`Task ${taskId} reverted from complete to ${actual.status}`);
+        }
+    }
+    // Check in-progress tasks
+    const inProgressEntries = Object.entries(checkpoint.inProgressTasks);
+    for (const [taskId, agentId] of inProgressEntries) {
+        const actual = actualTasks.find(t => t.id === taskId);
+        if (actual?.status === 'complete') {
+            // Task completed externally - move to completed
+            delete reconciledCheckpoint.inProgressTasks[taskId];
+            if (!reconciledCheckpoint.completedTasks.includes(taskId)) {
+                reconciledCheckpoint.completedTasks.push(taskId);
+            }
+            changes.push(`Task ${taskId} completed externally`);
+        }
+        else if (!actual) {
+            // Task no longer exists - remove
+            delete reconciledCheckpoint.inProgressTasks[taskId];
+            changes.push(`Task ${taskId} no longer exists`);
+        }
+    }
+    // Check for newly completed tasks not in checkpoint
+    for (const task of actualTasks) {
+        if (task.status === 'complete' && !reconciledCheckpoint.completedTasks.includes(task.id)) {
+            reconciledCheckpoint.completedTasks.push(task.id);
+            changes.push(`Task ${task.id} completed externally`);
+        }
+    }
+    // Log reconciliation if changes detected
+    if (changes.length > 0) {
+        console.log(`Reconciled ${changes.length} task status changes:`);
+        for (const change of changes) {
+            console.log(`  - ${change}`);
+        }
+    }
+    return reconciledCheckpoint;
+}
+// ============================================================
+// Exit Condition Helpers
+// ============================================================
+/**
+ * Determine exit code from reason
+ */
+export function getExitCode(reason) {
+    switch (reason) {
+        case 'all_complete':
+        case 'user_interrupt':
+        case 'manual_stop':
+            return EXIT_CODE_SUCCESS;
+        case 'context_pressure':
+        case 'max_runtime':
+            return EXIT_CODE_RESPAWN;
+        case 'no_progress':
+        case 'error':
+        default:
+            return EXIT_CODE_ERROR;
+    }
+}
+/**
+ * Check if exit code indicates respawn is needed
+ */
+export function shouldRespawn(exitCode) {
+    return exitCode === EXIT_CODE_RESPAWN;
+}
+/**
+ * Get human-readable exit message
+ */
+export function getExitMessage(reason) {
+    switch (reason) {
+        case 'all_complete':
+            return 'All tasks completed successfully';
+        case 'context_pressure':
+            return 'Context pressure exceeded threshold - respawn needed';
+        case 'max_runtime':
+            return 'Maximum runtime exceeded - respawn needed';
+        case 'no_progress':
+            return 'No progress detected for extended period - investigation needed';
+        case 'user_interrupt':
+            return 'Graceful shutdown requested';
+        case 'manual_stop':
+            return 'Orchestrator stopped manually';
+        case 'error':
+            return 'Unrecoverable error occurred';
+        default:
+            return 'Unknown exit reason';
+    }
+}
+// ============================================================
+// Singleton Instance (for global access)
+// ============================================================
+let stateManagerInstance = null;
+/**
+ * Get or create state manager instance
+ */
+export function getStateManager(projectRoot, graphId) {
+    if (!stateManagerInstance && projectRoot) {
+        stateManagerInstance = new OrchestratorStateManager(projectRoot, graphId);
+    }
+    if (!stateManagerInstance) {
+        throw new Error('State manager not initialized. Call getStateManager with projectRoot first.');
+    }
+    return stateManagerInstance;
+}
+/**
+ * Reset state manager (for testing)
+ */
+export function resetStateManager() {
+    stateManagerInstance = null;
+}
+export default OrchestratorStateManager;
+//# sourceMappingURL=orchestrator-state.js.map

package/dist/lib/orchestrator-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrator-state.js","sourceRoot":"","sources":["../../src/lib/orchestrator-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,MAAM,aAAa,CAAC;AAC7B,OAAO,IAAI,MAAM,MAAM,CAAC;AAGxB,+DAA+D;AAC/D,YAAY;AACZ,+DAA+D;AAE/D,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC;AACnC,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC;AACjC,MAAM,CAAC,MAAM,iBAAiB,GAAG,EAAE,CAAC;AAEpC,MAAM,mBAAmB,GAAG,8BAA8B,CAAC;AAC3D,MAAM,gBAAgB,GAAG,mBAAmB,CAAC;AAiG7C,+DAA+D;AAC/D,qBAAqB;AACrB,+DAA+D;AAE/D,MAAM,OAAO,wBAAwB;IAC3B,WAAW,CAAS;IACpB,OAAO,CAAU;IAEzB,YAAY,WAAmB,EAAE,OAAgB;QAC/C,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;QAC/B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;IAED;;OAEG;IACH,iBAAiB;QACf,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,QAAQ,EAAE,mBAAmB,CAAC,CAAC;IACpE,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,aAAa;QACjB,IAAI,CAAC;YACH,MAAM,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,iBAAiB,EAAE,CAAC,CAAC;YAC1C,OAAO,IAAI,CAAC;QACd,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,cAAc;QAClB,IAAI,CAAC;YACH,MAAM,cAAc,GAAG,IAAI,CAAC,iBAAiB,EAAE,CAAC;YAChD,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC,CAAC;YAC3D,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAA2B,CAAC;YAEjE,mBAAmB;YACnB,IAAI,CAAC,UAAU,CAAC,OAAO,IAAI,UAAU,CAAC,OAAO,GAAG,CAAC,EAAE,CAAC;gBAClD,OAAO,CAAC,IAAI,CAAC,yDAAyD,CAAC,CAAC;YAC1E,CAAC;YAED,OAAO,UAAU,CAAC;QACpB,CAAC;QAAC,OAAO,KAAU,EAAE,CAAC;YACpB,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;gBAC5B,OAAO,IAAI,CAAC,CAAC,uBAAuB;YACtC,CAAC;YACD,MAAM,IAAI,KAAK,CAAC,8BAA8B,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;QACjE,CAAC;IACH,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,cAAc,CAClB,UAAkC,EAClC,OAAwD;QAExD,MAAM,cAAc,GAAG,IAAI,CAAC,iBAAiB,EAAE,CAAC;QAEhD,oCAAoC;QACpC,MAAM,eAAe,GAA2B;YAC9C,GAAG,UAAU;YACb,OAAO,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACjC,OAAO,EAAE,CAAC;YACV,GAAG,CAAC,OAAO,EAAE,UAAU,IAAI,EAAE,UAAU,EAAE,OAAO,CAAC,UAAU,EAAE,CAAC;YAC9D,GAAG,CAAC,OAAO,EAAE,QAAQ,KAAK,SAAS,IAAI,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC;SACvE,CAAC;QAEF,0BAA0B;QAC1B,MAAM,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,cAAc,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAElE,gDAAgD;QAChD,MAAM,QAAQ,GAAG,GAAG,cAAc,MAAM,CAAC;QACzC,MAAM,EAAE,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,eAAe,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;QAChF,MAAM,EAAE,CAAC,MAAM,CAAC,QAAQ,EAAE,cAAc,CAAC,CAAC;IAC5C,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,gBAAgB;QACpB,IAAI,CAAC;YACH,MAAM,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,iBAAiB,EAAE,CAAC,CAAC;QAC5C,CAAC;QAAC,OAAO,KAAU,EAAE,CAAC;YACpB,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;gBAC5B,MAAM,KAAK,CAAC;YACd,CAAC;YACD,+BAA+B;QACjC,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,gBAAgB,CAAC,KAmBhB;QACC,mDAAmD;QACnD,MAAM,OAAO,GAAG,KAAK,CAAC,cAAc,EAAE,UAAU,EAAE,IAAI,KAAK,CAAC,cAAc,CAAC;QAC3E,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CAAC,0DAA0D,CAAC,CAAC;QAC9E,CAAC;QAED,OAAO;YACL,cAAc,EAAE,KAAK,CAAC,cAAc;YACpC,gBAAgB,EAAE,KAAK,CAAC,gBAAgB;YACxC,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,SAAS,EAAE,KAAK,CAAC,SAAS,CAAC,WAAW,EAAE;YACxC,OAAO,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACjC,cAAc,EAAE,KAAK,CAAC,cAAc,CAAC,WAAW,EAAE;YAClD,qBAAqB,EAAE,KAAK,CAAC,qBAAqB;YAClD,cAAc,EAAE,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC;YAChD,eAAe,EAAE,MAAM,CAAC,WAAW,CAAC,KAAK,CAAC,eAAe,CAAC;YAC1D,YAAY,EAAE,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC;YAC5C,iBAAiB,EAAE,KAAK,CAAC,iBAAiB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;gBACnD,MAAM,EAAE,CAAC,CAAC,MAAM;gBAChB,OAAO,EAAE,CAAC,CAAC,OAAO;gBAClB,UAAU,EAAE,CAAC,CAAC,UAAU,CAAC,WAAW,EAAE;gBACtC,MAAM,EAAE,CAAC,CAAC,MAAM;aACjB,CAAC,CAAC;YACH,cAAc,EAAE;gBACd,eAAe,EAAE,OAAO,CAAC,eAAe;gBACxC,YAAY,EAAE,OAAO,CAAC,YAAY;gBAClC,QAAQ,EAAE,OAAO,CAAC,QAAQ;gBAC1B,YAAY,EAAE,OAAO,CAAC,YAAY;gBAClC,aAAa,EAAE,OAAO,CAAC,aAAa;gBACpC,gBAAgB,EAAE,OAAO,CAAC,gBAAgB;gBAC1C,KAAK,EAAE,OAAO,CAAC,KAAK;aACrB;YACD,OAAO,EAAE,CAAC;SACX,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,qBAAqB,CAAC,UAAkC;QActD,OAAO;YACL,cAAc,EAAE,IAAI,GAAG,CAAC,UAAU,CAAC,cAAc,CAAC;YAClD,eAAe,EAAE,IAAI,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,eAAe,CAAC,CAAC;YACpE,YAAY,EAAE,IAAI,GAAG,CAAC,UAAU,CAAC,YAAY,CAAC;YAC9C,iBAAiB,EAAE,UAAU,CAAC,iBAAiB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;gBACxD,MAAM,EAAE,CAAC,CAAC,MAAM;gBAChB,OAAO,EAAE,CAAC,CAAC,OAAO;gBAClB,UAAU,EAAE,IAAI,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC;gBAClC,MAAM,EAAE,CAAC,CAAC,MAAM;aACjB,CAAC,CAAC;YACH,SAAS,EAAE,IAAI,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC;YACzC,cAAc,EAAE,IAAI,IAAI,CAAC,UAAU,CAAC,cAAc,CAAC;YACnD,qBAAqB,EAAE,UAAU,CAAC,qBAAqB;SACxD,CAAC;IACJ,CAAC;CACF;AAED,+DAA+D;AAC/D,oDAAoD;AACpD,+DAA+D;AAE/D;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,UAAkC,EAClC,cAAgG;IAEhG,0CAA0C;IAC1C,MAAM,cAAc,CAAC,OAAO,CAAC,MAAM,EAAE,4BAA4B,EAAE;QACjE,OAAO,EAAE,UAAU,CAAC,OAAO;QAC3B,cAAc,EAAE,UAAU,CAAC,cAAc;QACzC,KAAK,EAAE,UAAU;KAClB,CAAC,CAAC;AACL,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,OAAe,EACf,MAAc,EACd,cAAgG;IAEhG,IAAI,CAAC;QACH,yDAAyD;QACzD,MAAM,QAAQ,GAAG,MAAM,cAAc,CAAC,OAAO,CAC3C,KAAK,EACL,sCAAsC,OAAO,WAAW,MAAM,EAAE,CACjE,CAAC;QACF,OAAO,QAAQ,CAAC,KAAK,CAAC;IACxB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,4DAA4D;QAC5D,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,UAAkC,EAClC,WAAkD,EAClD,cAAgG;IAEhG,MAAM,oBAAoB,GAAG,EAAE,GAAG,UAAU,EAAE,CAAC;IAC/C,MAAM,OAAO,GAAa,EAAE,CAAC;IAE7B,wBAAwB;IACxB,KAAK,MAAM,MAAM,IAAI,UAAU,CAAC,cAAc,EAAE,CAAC;QAC/C,MAAM,MAAM,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,MAAM,CAAC,CAAC;QACtD,IAAI,MAAM,IAAI,MAAM,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;YAC3C,iDAAiD;YACjD,oBAAoB,CAAC,cAAc,GAAG,oBAAoB,CAAC,cAAc,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,KAAK,MAAM,CAAC,CAAC;YACtG,OAAO,CAAC,IAAI,CAAC,QAAQ,MAAM,8BAA8B,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;QAC5E,CAAC;IACH,CAAC;IAED,0BAA0B;IAC1B,MAAM,iBAAiB,GAAG,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,eAAe,CAAC,CAAC;IACrE,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,iBAAiB,EAAE,CAAC;QAClD,MAAM,MAAM,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,MAAM,CAAC,CAAC;QACtD,IAAI,MAAM,EAAE,MAAM,KAAK,UAAU,EAAE,CAAC;YAClC,gDAAgD;YAChD,OAAO,oBAAoB,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;YACpD,IAAI,CAAC,oBAAoB,CAAC,cAAc,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;gBAC1D,oBAAoB,CAAC,cAAc,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YACnD,CAAC;YACD,OAAO,CAAC,IAAI,CAAC,QAAQ,MAAM,uBAAuB,CAAC,CAAC;QACtD,CAAC;aAAM,IAAI,CAAC,MAAM,EAAE,CAAC;YACnB,iCAAiC;YACjC,OAAO,oBAAoB,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;YACpD,OAAO,CAAC,IAAI,CAAC,QAAQ,MAAM,mBAAmB,CAAC,CAAC;QAClD,CAAC;IACH,CAAC;IAED,oDAAoD;IACpD,KAAK,MAAM,IAAI,IAAI,WAAW,EAAE,CAAC;QAC/B,IAAI,IAAI,CAAC,MAAM,KAAK,UAAU,IAAI,CAAC,oBAAoB,CAAC,cAAc,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;YACzF,oBAAoB,CAAC,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YAClD,OAAO,CAAC,IAAI,CAAC,QAAQ,IAAI,CAAC,EAAE,uBAAuB,CAAC,CAAC;QACvD,CAAC;IACH,CAAC;IAED,yCAAyC;IACzC,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,OAAO,CAAC,GAAG,CAAC,cAAc,OAAO,CAAC,MAAM,uBAAuB,CAAC,CAAC;QACjE,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;YAC7B,OAAO,CAAC,GAAG,CAAC,OAAO,MAAM,EAAE,CAAC,CAAC;QAC/B,CAAC;IACH,CAAC;IAED,OAAO,oBAAoB,CAAC;AAC9B,CAAC;AAED,+DAA+D;AAC/D,yBAAyB;AACzB,+DAA+D;AAE/D;;GAEG;AACH,MAAM,UAAU,WAAW,CAAC,MAAkB;IAC5C,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,cAAc,CAAC;QACpB,KAAK,gBAAgB,CAAC;QACtB,KAAK,aAAa;YAChB,OAAO,iBAAiB,CAAC;QAE3B,KAAK,kBAAkB,CAAC;QACxB,KAAK,aAAa;YAChB,OAAO,iBAAiB,CAAC;QAE3B,KAAK,aAAa,CAAC;QACnB,KAAK,OAAO,CAAC;QACb;YACE,OAAO,eAAe,CAAC;IAC3B,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,QAAgB;IAC5C,OAAO,QAAQ,KAAK,iBAAiB,CAAC;AACxC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,MAAkB;IAC/C,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,cAAc;YACjB,OAAO,kCAAkC,CAAC;QAC5C,KAAK,kBAAkB;YACrB,OAAO,sDAAsD,CAAC;QAChE,KAAK,aAAa;YAChB,OAAO,2CAA2C,CAAC;QACrD,KAAK,aAAa;YAChB,OAAO,iEAAiE,CAAC;QAC3E,KAAK,gBAAgB;YACnB,OAAO,6BAA6B,CAAC;QACvC,KAAK,aAAa;YAChB,OAAO,+BAA+B,CAAC;QACzC,KAAK,OAAO;YACV,OAAO,8BAA8B,CAAC;QACxC;YACE,OAAO,qBAAqB,CAAC;IACjC,CAAC;AACH,CAAC;AAED,+DAA+D;AAC/D,yCAAyC;AACzC,+DAA+D;AAE/D,IAAI,oBAAoB,GAAoC,IAAI,CAAC;AAEjE;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,WAAoB,EAAE,OAAgB;IACpE,IAAI,CAAC,oBAAoB,IAAI,WAAW,EAAE,CAAC;QACzC,oBAAoB,GAAG,IAAI,wBAAwB,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;IAC5E,CAAC;IACD,IAAI,CAAC,oBAAoB,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CAAC,6EAA6E,CAAC,CAAC;IACjG,CAAC;IACD,OAAO,oBAAoB,CAAC;AAC9B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB;IAC/B,oBAAoB,GAAG,IAAI,CAAC;AAC9B,CAAC;AAED,eAAe,wBAAwB,CAAC"}

package/dist/lib/realtime-cursor.d.ts

@@ -0,0 +1,107 @@
+/**
+ * @fileType: utility
+ * @status: current
+ * @updated: 2025-12-05
+ * @tags: [cursor, realtime, epic-004, multi-agent, event-stream]
+ * @related: [event-logger.ts, event-queue.ts, ../commands/graph/api-client.ts]
+ * @priority: high
+ * @complexity: medium
+ * @dependencies: [auth-storage]
+ *
+ * Real-time cursor updates for EPIC-004 multi-agent coordination.
+ *
+ * Purpose: Push cursor position to cloud immediately after significant actions,
+ * enabling other agents to see work in near-real-time (< 5 seconds).
+ *
+ * When to update:
+ * - After task claim
+ * - After each logged event
+ * - After task completion
+ * - On session start/resume
+ *
+ * Configuration:
+ * - Flag: --realtime-cursor (default: true)
+ * - Env: GINKO_REALTIME_CURSOR=true|false
+ */
+/**
+ * Cursor position update payload
+ */
+export interface CursorUpdate {
+    userId: string;
+    projectId: string;
+    branch: string;
+    lastEventId?: string;
+    currentTask?: string;
+    status: 'active' | 'idle' | 'busy';
+    timestamp: string;
+    action?: 'session_start' | 'event_logged' | 'task_claimed' | 'task_completed' | 'handoff';
+}
+/**
+ * Cursor update response from API
+ */
+export interface CursorUpdateResponse {
+    success: boolean;
+    cursor: {
+        userId: string;
+        projectId: string;
+        lastEventId?: string;
+        updatedAt: string;
+    };
+}
+/**
+ * Real-time cursor configuration
+ */
+interface RealtimeCursorConfig {
+    enabled: boolean;
+    apiUrl: string;
+    debounceMs: number;
+}
+/**
+ * Set runtime override for realtime cursor
+ * Called by CLI when --no-realtime-cursor is passed
+ */
+export declare function setRealtimeCursorEnabled(enabled: boolean): void;
+/**
+ * Get configuration for realtime cursor updates
+ */
+export declare function getRealtimeCursorConfig(): RealtimeCursorConfig;
+/**
+ * Check if realtime cursor updates are enabled
+ */
+export declare function isRealtimeCursorEnabled(): boolean;
+/**
+ * Push cursor update to cloud immediately
+ *
+ * Uses debouncing to prevent rapid-fire updates (e.g., multiple events logged in quick succession).
+ * Guarantees update within config.debounceMs after last call.
+ *
+ * @param update - Cursor update payload
+ * @returns Promise resolving when update is sent (or debounced)
+ */
+export declare function pushCursorUpdate(update: CursorUpdate): Promise<void>;
+/**
+ * Update cursor on session start/resume
+ */
+export declare function onSessionStart(): Promise<void>;
+/**
+ * Update cursor after event is logged
+ */
+export declare function onEventLogged(eventId: string): Promise<void>;
+/**
+ * Update cursor when task is claimed
+ */
+export declare function onTaskClaimed(taskId: string): Promise<void>;
+/**
+ * Update cursor when task is completed
+ */
+export declare function onTaskCompleted(taskId: string): Promise<void>;
+/**
+ * Update cursor on handoff
+ */
+export declare function onHandoff(finalEventId?: string): Promise<void>;
+/**
+ * Flush any pending cursor update (for shutdown)
+ */
+export declare function flushPendingCursorUpdate(): Promise<void>;
+export {};
+//# sourceMappingURL=realtime-cursor.d.ts.map

package/dist/lib/realtime-cursor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"realtime-cursor.d.ts","sourceRoot":"","sources":["../../src/lib/realtime-cursor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAOH;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,eAAe,GAAG,cAAc,GAAG,cAAc,GAAG,gBAAgB,GAAG,SAAS,CAAC;CAC3F;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE;QACN,MAAM,EAAE,MAAM,CAAC;QACf,SAAS,EAAE,MAAM,CAAC;QAClB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;CACH;AAED;;GAEG;AACH,UAAU,oBAAoB;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB;AAOD;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAE/D;AAED;;GAEG;AACH,wBAAgB,uBAAuB,IAAI,oBAAoB,CAmB9D;AAED;;GAEG;AACH,wBAAgB,uBAAuB,IAAI,OAAO,CAEjD;AASD;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAgC1E;AA2ED;;GAEG;AACH,wBAAsB,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC,CAUpD;AAED;;GAEG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAWlE;AAED;;GAEG;AACH,wBAAsB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAWjE;AAED;;GAEG;AACH,wBAAsB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAWnE;AAED;;GAEG;AACH,wBAAsB,SAAS,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAWpE;AAED;;GAEG;AACH,wBAAsB,wBAAwB,IAAI,OAAO,CAAC,IAAI,CAAC,CAU9D"}