@proletariat/cli 0.3.96 → 0.3.97

package/dist/lib/providers/transition-map.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Transition Map Store
+ *
+ * Manages the pmo_transition_map table, which stores intent-to-provider-state
+ * mappings. Each work primitive (start, ready, ship, stop, drop) has a
+ * canonical intent, and this store resolves that intent to whatever state
+ * name exists on the connected board.
+ *
+ * Resolution order (in state-resolution.ts):
+ * 1. pmo_transition_map (this store) — explicit user-confirmed mappings
+ * 2. state-map.{intent} config override
+ * 3. Built-in semantic intent aliases
+ * 4. LLM fallback
+ * 5. Skip (no match)
+ */
+import type Database from 'better-sqlite3';
+import type { TransitionIntent } from './state-intents.js';
+export interface TransitionMapping {
+    provider: string;
+    intent: TransitionIntent;
+    providerStateName: string;
+    providerStateId?: string | null;
+}
+/**
+ * CRUD operations for the pmo_transition_map table.
+ */
+export declare class TransitionMapStore {
+    private db;
+    constructor(db: Database.Database);
+    /**
+     * Get the provider state name mapped to a transition intent.
+     * Returns null if no mapping exists.
+     */
+    getMapping(provider: string, intent: string): TransitionMapping | null;
+    /**
+     * Add or update a transition mapping.
+     */
+    upsertMapping(mapping: TransitionMapping): void;
+    /**
+     * List all transition mappings for a provider.
+     */
+    listMappings(provider: string): TransitionMapping[];
+    /**
+     * Remove a specific transition mapping.
+     */
+    removeMapping(provider: string, intent: string): void;
+    /**
+     * Remove all transition mappings for a provider.
+     */
+    clearMappings(provider: string): void;
+    /**
+     * Resolve a transition intent to a provider state name.
+     * Returns the mapped state name, or null if no mapping exists.
+     *
+     * This is the primary resolution method called by work commands.
+     * If this returns null, the caller should fall through to alias/LLM resolution.
+     */
+    resolveIntent(provider: string, intent: string): string | null;
+}

package/dist/lib/providers/transition-map.js

@@ -0,0 +1,113 @@
+/**
+ * Transition Map Store
+ *
+ * Manages the pmo_transition_map table, which stores intent-to-provider-state
+ * mappings. Each work primitive (start, ready, ship, stop, drop) has a
+ * canonical intent, and this store resolves that intent to whatever state
+ * name exists on the connected board.
+ *
+ * Resolution order (in state-resolution.ts):
+ * 1. pmo_transition_map (this store) — explicit user-confirmed mappings
+ * 2. state-map.{intent} config override
+ * 3. Built-in semantic intent aliases
+ * 4. LLM fallback
+ * 5. Skip (no match)
+ */
+/**
+ * CRUD operations for the pmo_transition_map table.
+ */
+export class TransitionMapStore {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    /**
+     * Get the provider state name mapped to a transition intent.
+     * Returns null if no mapping exists.
+     */
+    getMapping(provider, intent) {
+        try {
+            const row = this.db.prepare(`
+        SELECT provider, intent, provider_state_name, provider_state_id
+        FROM pmo_transition_map
+        WHERE provider = ? AND intent = ?
+      `).get(provider, intent);
+            if (!row)
+                return null;
+            return {
+                provider: row.provider,
+                intent: row.intent,
+                providerStateName: row.provider_state_name,
+                providerStateId: row.provider_state_id,
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Add or update a transition mapping.
+     */
+    upsertMapping(mapping) {
+        this.db.prepare(`
+      INSERT INTO pmo_transition_map (provider, intent, provider_state_name, provider_state_id, updated_at)
+      VALUES (?, ?, ?, ?, CURRENT_TIMESTAMP)
+      ON CONFLICT(provider, intent) DO UPDATE SET
+        provider_state_name = excluded.provider_state_name,
+        provider_state_id = excluded.provider_state_id,
+        updated_at = CURRENT_TIMESTAMP
+    `).run(mapping.provider, mapping.intent, mapping.providerStateName, mapping.providerStateId ?? null);
+    }
+    /**
+     * List all transition mappings for a provider.
+     */
+    listMappings(provider) {
+        try {
+            const rows = this.db.prepare(`
+        SELECT provider, intent, provider_state_name, provider_state_id
+        FROM pmo_transition_map
+        WHERE provider = ?
+        ORDER BY intent
+      `).all(provider);
+            return rows.map(row => ({
+                provider: row.provider,
+                intent: row.intent,
+                providerStateName: row.provider_state_name,
+                providerStateId: row.provider_state_id,
+            }));
+        }
+        catch {
+            return [];
+        }
+    }
+    /**
+     * Remove a specific transition mapping.
+     */
+    removeMapping(provider, intent) {
+        this.db.prepare(`
+      DELETE FROM pmo_transition_map
+      WHERE provider = ? AND intent = ?
+    `).run(provider, intent);
+    }
+    /**
+     * Remove all transition mappings for a provider.
+     */
+    clearMappings(provider) {
+        this.db.prepare(`
+      DELETE FROM pmo_transition_map
+      WHERE provider = ?
+    `).run(provider);
+    }
+    /**
+     * Resolve a transition intent to a provider state name.
+     * Returns the mapped state name, or null if no mapping exists.
+     *
+     * This is the primary resolution method called by work commands.
+     * If this returns null, the caller should fall through to alias/LLM resolution.
+     */
+    resolveIntent(provider, intent) {
+        const mapping = this.getMapping(provider, intent);
+        return mapping?.providerStateName ?? null;
+    }
+}
+//# sourceMappingURL=transition-map.js.map

package/dist/lib/providers/transition-map.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transition-map.js","sourceRoot":"","sources":["../../../src/lib/providers/transition-map.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAYH;;GAEG;AACH,MAAM,OAAO,kBAAkB;IACT;IAApB,YAAoB,EAAqB;QAArB,OAAE,GAAF,EAAE,CAAmB;IAAG,CAAC;IAE7C;;;OAGG;IACH,UAAU,CAAC,QAAgB,EAAE,MAAc;QACzC,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC;;;;OAI3B,CAAC,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAKV,CAAA;YAEb,IAAI,CAAC,GAAG;gBAAE,OAAO,IAAI,CAAA;YAErB,OAAO;gBACL,QAAQ,EAAE,GAAG,CAAC,QAAQ;gBACtB,MAAM,EAAE,GAAG,CAAC,MAA0B;gBACtC,iBAAiB,EAAE,GAAG,CAAC,mBAAmB;gBAC1C,eAAe,EAAE,GAAG,CAAC,iBAAiB;aACvC,CAAA;QACH,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAA;QACb,CAAC;IACH,CAAC;IAED;;OAEG;IACH,aAAa,CAAC,OAA0B;QACtC,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC;;;;;;;KAOf,CAAC,CAAC,GAAG,CACJ,OAAO,CAAC,QAAQ,EAChB,OAAO,CAAC,MAAM,EACd,OAAO,CAAC,iBAAiB,EACzB,OAAO,CAAC,eAAe,IAAI,IAAI,CAChC,CAAA;IACH,CAAC;IAED;;OAEG;IACH,YAAY,CAAC,QAAgB;QAC3B,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC;;;;;OAK5B,CAAC,CAAC,GAAG,CAAC,QAAQ,CAKb,CAAA;YAEF,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;gBACtB,QAAQ,EAAE,GAAG,CAAC,QAAQ;gBACtB,MAAM,EAAE,GAAG,CAAC,MAA0B;gBACtC,iBAAiB,EAAE,GAAG,CAAC,mBAAmB;gBAC1C,eAAe,EAAE,GAAG,CAAC,iBAAiB;aACvC,CAAC,CAAC,CAAA;QACL,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,CAAA;QACX,CAAC;IACH,CAAC;IAED;;OAEG;IACH,aAAa,CAAC,QAAgB,EAAE,MAAc;QAC5C,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC;;;KAGf,CAAC,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAA;IAC1B,CAAC;IAED;;OAEG;IACH,aAAa,CAAC,QAAgB;QAC5B,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC;;;KAGf,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAA;IAClB,CAAC;IAED;;;;;;OAMG;IACH,aAAa,CAAC,QAAgB,EAAE,MAAc;QAC5C,MAAM,OAAO,GAAG,IAAI,CAAC,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAA;QACjD,OAAO,OAAO,EAAE,iBAAiB,IAAI,IAAI,CAAA;IAC3C,CAAC;CACF"}

package/dist/lib/session/index.d.ts

@@ -1,7 +1,9 @@
 /**
  * Session Module
  *
- * Agent session monitoring, heartbeat tracking, and stale detection.
+ * Agent session monitoring, heartbeat tracking, stale detection,
+ * and tmux server crash recovery.
  */
 export * from './heartbeat.js';
 export * from './watcher.js';
+export * from './tmux-watchdog.js';

package/dist/lib/session/index.js

@@ -1,8 +1,10 @@
 /**
  * Session Module
  *
- * Agent session monitoring, heartbeat tracking, and stale detection.
+ * Agent session monitoring, heartbeat tracking, stale detection,
+ * and tmux server crash recovery.
  */
 export * from './heartbeat.js';
 export * from './watcher.js';
+export * from './tmux-watchdog.js';
 //# sourceMappingURL=index.js.map

package/dist/lib/session/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/lib/session/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,gBAAgB,CAAA;AAC9B,cAAc,cAAc,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/lib/session/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,gBAAgB,CAAA;AAC9B,cAAc,cAAc,CAAA;AAC5B,cAAc,oBAAoB,CAAA"}

package/dist/lib/session/tmux-watchdog.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Tmux Watchdog
+ *
+ * Detects tmux server crashes and attempts automatic recovery of agent sessions.
+ *
+ * Problem: When the tmux server crashes (macOS sleep, resource pressure, OOM),
+ * ALL agent sessions are silently lost. The existing heartbeat system treats
+ * each agent as individually stale, missing the root cause. There is no
+ * recovery or user notification.
+ *
+ * Solution: This watchdog monitors the tmux server process itself. When a
+ * crash is detected (server transitions from alive→dead while agents were
+ * active), it:
+ *
+ * 1. Marks all affected executions with a crash-specific error
+ * 2. Attempts to re-create tmux sessions and restart agents
+ * 3. Logs crash events for user notification
+ *
+ * Architecture:
+ * - Runs as Phase 0 in SessionWatcher.runCycle(), before heartbeat checks
+ * - Maintains last-known server state per environment (host + each container)
+ * - Uses session-utils.ts for server status checks
+ * - Uses session restart logic to re-launch agents in recovered sessions
+ */
+import { ExecutionStorage } from '../execution/storage.js';
+import type { AgentWork } from '../execution/types.js';
+/**
+ * Record of a tmux server crash event.
+ */
+export interface TmuxCrashEvent {
+    /** When the crash was detected */
+    timestamp: Date;
+    /** Where the crash occurred */
+    environment: 'host' | 'container';
+    /** Container ID (only for container crashes) */
+    containerId?: string;
+    /** Executions that were active when the crash occurred */
+    affectedExecutions: AgentWork[];
+    /** Whether recovery was attempted */
+    recoveryAttempted: boolean;
+    /** Sessions that were successfully recovered */
+    recoveredSessions: string[];
+    /** Sessions that failed to recover */
+    failedRecoveries: string[];
+}
+/**
+ * Result of a watchdog check cycle.
+ */
+export interface WatchdogCycleResult {
+    /** Whether the host tmux server is alive */
+    hostServerAlive: boolean;
+    /** Map of container ID → server alive status */
+    containerServersAlive: Map<string, boolean>;
+    /** Crash events detected in this cycle */
+    crashEvents: TmuxCrashEvent[];
+    /** Total executions affected by crashes */
+    totalAffected: number;
+    /** Total sessions recovered */
+    totalRecovered: number;
+}
+export interface TmuxWatchdogOptions {
+    /** Execution storage for DB operations */
+    storage: ExecutionStorage;
+    /** Whether to attempt auto-recovery (default: true) */
+    autoRecover?: boolean;
+    /** Logger function */
+    log?: (msg: string) => void;
+    /** Callback when a crash is detected */
+    onCrashDetected?: (event: TmuxCrashEvent) => void | Promise<void>;
+}
+export declare class TmuxWatchdog {
+    private storage;
+    private autoRecover;
+    private log;
+    private onCrashDetected?;
+    /**
+     * Tracks last known tmux server state.
+     * Key: 'host' for host server, containerId for container servers.
+     * Value: true = server was alive, false = server was down.
+     */
+    private lastServerState;
+    /**
+     * Tracks which executions were active when we last saw the server alive.
+     * Key: 'host' or containerId.
+     * Value: array of execution IDs that were active in that environment.
+     */
+    private activeExecutionsSnapshot;
+    /**
+     * Tracks crash events we've already handled to avoid duplicate recovery.
+     * Key: 'host' or containerId.
+     * Value: timestamp of when we detected the crash.
+     */
+    private handledCrashes;
+    constructor(options: TmuxWatchdogOptions);
+    /**
+     * Run a single watchdog check cycle.
+     *
+     * Checks tmux server health for host and all containers with active executions.
+     * Detects crashes (server alive→dead transition) and attempts recovery.
+     */
+    checkAndRecover(): Promise<WatchdogCycleResult>;
+    /**
+     * Handle a detected tmux server crash.
+     * Marks affected executions and attempts recovery.
+     */
+    private handleCrash;
+    /**
+     * Attempt to recover agent sessions after a tmux server crash.
+     *
+     * Recovery steps:
+     * 1. Wait briefly for tmux server to come back (macOS wake, Docker resume)
+     * 2. Create new tmux sessions with the original session names
+     * 3. Navigate to the working directory
+     * 4. Re-launch Claude Code with --resume flag
+     */
+    private attemptRecovery;
+    /**
+     * Wait for the tmux server to come back online.
+     * Returns true if the server recovered within the timeout.
+     */
+    private waitForServerRecovery;
+    /**
+     * Restart an agent session by creating a new tmux session and re-launching Claude Code.
+     */
+    private restartSession;
+    /**
+     * Restart a host tmux session.
+     */
+    private restartHostSession;
+    /**
+     * Restart a tmux session inside a Docker container.
+     */
+    private restartContainerSession;
+    /**
+     * Get the current known state of servers.
+     * Useful for diagnostics and testing.
+     */
+    getServerStates(): Map<string, boolean>;
+    /**
+     * Reset internal state. Useful for testing.
+     */
+    reset(): void;
+    /**
+     * Seed the initial server state without triggering crash detection.
+     * Call this once during watcher startup to establish baseline.
+     */
+    seedServerState(activeExecs: AgentWork[]): void;
+}
+/**
+ * Format a crash event into a human-readable notification string.
+ */
+export declare function formatCrashNotification(event: TmuxCrashEvent): string;
+/**
+ * Send a desktop notification about a tmux crash (best effort).
+ * Uses osascript on macOS, notify-send on Linux.
+ */
+export declare function sendDesktopNotification(title: string, message: string): void;