@renseiai/agentfactory-server 0.8.0

package/dist/src/issue-lock.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Issue Lock Module
+ *
+ * Prevents overlapping agents for the same issue by providing:
+ * - Per-issue mutex (Redis SET NX) that gates work dispatch
+ * - Per-issue pending queue for parking incoming work while locked
+ * - Automatic promotion: releasing a lock dispatches the next pending item
+ *
+ * Redis Keys:
+ * - issue:lock:{issueId}         -- String (JSON IssueLock), 2hr TTL
+ * - issue:pending:{issueId}      -- Sorted Set (priority-ordered session IDs)
+ * - issue:pending:items:{issueId} -- Hash (sessionId -> JSON QueuedWork)
+ */
+import { type QueuedWork } from './work-queue.js';
+import type { AgentWorkType } from './types.js';
+/**
+ * Lock payload stored in Redis
+ */
+export interface IssueLock {
+    sessionId: string;
+    workType: AgentWorkType;
+    workerId: string | null;
+    lockedAt: number;
+    issueIdentifier: string;
+}
+/**
+ * Result of a dispatchWork call
+ */
+export interface DispatchResult {
+    dispatched: boolean;
+    parked: boolean;
+    replaced: boolean;
+}
+/**
+ * Acquire an issue-level lock.
+ * Uses SET NX for atomicity -- only one caller wins.
+ *
+ * @returns true if lock was acquired
+ */
+export declare function acquireIssueLock(issueId: string, lock: IssueLock): Promise<boolean>;
+/**
+ * Read the current lock for an issue.
+ */
+export declare function getIssueLock(issueId: string): Promise<IssueLock | null>;
+/**
+ * Release an issue lock. Idempotent.
+ */
+export declare function releaseIssueLock(issueId: string): Promise<void>;
+/**
+ * Refresh the TTL on an issue lock (extend while agent is alive).
+ */
+export declare function refreshIssueLockTTL(issueId: string, ttlSeconds?: number): Promise<boolean>;
+/**
+ * Park work for a locked issue.
+ *
+ * Deduplication: at most one parked item per workType per issue.
+ * If a parked item with the same workType already exists, it's replaced
+ * (the latest webhook wins). Different workTypes can coexist.
+ */
+export declare function parkWorkForIssue(issueId: string, work: QueuedWork): Promise<{
+    parked: boolean;
+    replaced: boolean;
+}>;
+/**
+ * Promote the next pending work item for an issue.
+ * Pops the highest-priority item, acquires the issue lock for it,
+ * and queues it in the global work queue.
+ *
+ * @returns The promoted work item, or null if nothing to promote
+ */
+export declare function promoteNextPendingWork(issueId: string): Promise<QueuedWork | null>;
+/**
+ * Get the count of pending work items for an issue.
+ */
+export declare function getPendingWorkCount(issueId: string): Promise<number>;
+/**
+ * Main entry point for dispatching work.
+ *
+ * Try to acquire the issue lock:
+ * - If acquired -> queue the work in the global queue
+ * - If locked -> park the work in the per-issue pending queue
+ *
+ * @returns DispatchResult indicating what happened
+ */
+export declare function dispatchWork(work: QueuedWork): Promise<DispatchResult>;
+/**
+ * Remove a parked work item by sessionId.
+ *
+ * The issue-pending hash is keyed by workType, so we scan all entries
+ * to find the one matching the given sessionId.
+ *
+ * @returns true if a matching parked item was found and removed
+ */
+export declare function removeParkedWorkBySessionId(issueId: string, sessionId: string): Promise<boolean>;
+/**
+ * Check if a session is parked in any issue-pending queue.
+ *
+ * Scans the issue:pending:items:{issueId} hash entries for a matching sessionId.
+ *
+ * @param issueId - The issue to check
+ * @param sessionId - The session to look for
+ * @returns true if the session is parked for this issue
+ */
+export declare function isSessionParkedForIssue(issueId: string, sessionId: string): Promise<boolean>;
+/**
+ * Scan for expired issue locks that have pending work.
+ * If a lock expired naturally (TTL) but pending items remain, promote them.
+ *
+ * Called from orphan-cleanup to handle crashed workers that didn't release locks.
+ */
+export declare function cleanupExpiredLocksWithPendingWork(): Promise<number>;
+/**
+ * Release issue locks held by sessions that should no longer hold them.
+ *
+ * This handles cases where:
+ * - A session completes but the lock release failed (network error during cleanup)
+ * - Orphan cleanup resets a session to 'pending' but the lock wasn't released
+ *
+ * The lock's 2-hour TTL would eventually expire, but this proactively clears it
+ * when workers have idle capacity.
+ *
+ * Only runs when workers are online -- if no workers are available, there's no
+ * point promoting parked work since nothing can pick it up.
+ *
+ * @param hasIdleWorkers - true if at least one worker is online with spare capacity
+ * @returns Number of stale locks released and parked work promoted
+ */
+export declare function cleanupStaleLocksWithIdleWorkers(hasIdleWorkers: boolean): Promise<number>;
+//# sourceMappingURL=issue-lock.d.ts.map

package/dist/src/issue-lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"issue-lock.d.ts","sourceRoot":"","sources":["../../src/issue-lock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAmBH,OAAO,EAAa,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAE5D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAoB/C;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,aAAa,CAAA;IACvB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,QAAQ,EAAE,MAAM,CAAA;IAChB,eAAe,EAAE,MAAM,CAAA;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,OAAO,CAAA;IACnB,MAAM,EAAE,OAAO,CAAA;IACf,QAAQ,EAAE,OAAO,CAAA;CAClB;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,SAAS,GACd,OAAO,CAAC,OAAO,CAAC,CA4BlB;AAED;;GAEG;AACH,wBAAsB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAY7E;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAUrE;AAED;;GAEG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,MAAM,EACf,UAAU,GAAE,MAAyB,GACpC,OAAO,CAAC,OAAO,CAAC,CAUlB;AAED;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,UAAU,GACf,OAAO,CAAC;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,CAAC,CAoDjD;AAED;;;;;;GAMG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAqE5B;AAED;;GAEG;AACH,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAU1E;AAED;;;;;;;;GAQG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,cAAc,CAAC,CAoD5E;AAED;;;;;;;GAOG;AACH,wBAAsB,2BAA2B,CAC/C,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,OAAO,CAAC,CAsClB;AAED;;;;;;;;GAQG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,OAAO,CAAC,CAwBlB;AAED;;;;;GAKG;AACH,wBAAsB,kCAAkC,IAAI,OAAO,CAAC,MAAM,CAAC,CA6C1E;AAOD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,gCAAgC,CACpD,cAAc,EAAE,OAAO,GACtB,OAAO,CAAC,MAAM,CAAC,CAgEjB"}

package/dist/src/issue-lock.js

@@ -0,0 +1,508 @@
+/**
+ * Issue Lock Module
+ *
+ * Prevents overlapping agents for the same issue by providing:
+ * - Per-issue mutex (Redis SET NX) that gates work dispatch
+ * - Per-issue pending queue for parking incoming work while locked
+ * - Automatic promotion: releasing a lock dispatches the next pending item
+ *
+ * Redis Keys:
+ * - issue:lock:{issueId}         -- String (JSON IssueLock), 2hr TTL
+ * - issue:pending:{issueId}      -- Sorted Set (priority-ordered session IDs)
+ * - issue:pending:items:{issueId} -- Hash (sessionId -> JSON QueuedWork)
+ */
+import { redisSetNX, redisGet, redisDel, redisExpire, redisZAdd, redisZRem, redisZPopMin, redisZCard, redisHSet, redisHGet, redisHDel, redisHGetAll, isRedisConfigured, redisKeys, } from './redis.js';
+import { queueWork } from './work-queue.js';
+import { getSessionState } from './session-storage.js';
+const log = {
+    info: (msg, data) => console.log(`[issue-lock] ${msg}`, data ? JSON.stringify(data) : ''),
+    warn: (msg, data) => console.warn(`[issue-lock] ${msg}`, data ? JSON.stringify(data) : ''),
+    error: (msg, data) => console.error(`[issue-lock] ${msg}`, data ? JSON.stringify(data) : ''),
+    debug: (_msg, _data) => { },
+};
+// Redis key prefixes
+const LOCK_PREFIX = 'issue:lock:';
+const PENDING_PREFIX = 'issue:pending:';
+const PENDING_ITEMS_PREFIX = 'issue:pending:items:';
+// Default lock TTL: 2 hours
+const LOCK_TTL_SECONDS = 2 * 60 * 60;
+// Pending queue TTL: 24 hours
+const PENDING_TTL_SECONDS = 24 * 60 * 60;
+/**
+ * Acquire an issue-level lock.
+ * Uses SET NX for atomicity -- only one caller wins.
+ *
+ * @returns true if lock was acquired
+ */
+export async function acquireIssueLock(issueId, lock) {
+    if (!isRedisConfigured()) {
+        return true; // No Redis = no locking, pass through
+    }
+    try {
+        const key = `${LOCK_PREFIX}${issueId}`;
+        const acquired = await redisSetNX(key, JSON.stringify(lock), LOCK_TTL_SECONDS);
+        if (acquired) {
+            log.info('Issue lock acquired', {
+                issueId,
+                sessionId: lock.sessionId,
+                workType: lock.workType,
+                issueIdentifier: lock.issueIdentifier,
+            });
+        }
+        else {
+            log.debug('Issue lock not acquired (already held)', {
+                issueId,
+                sessionId: lock.sessionId,
+            });
+        }
+        return acquired;
+    }
+    catch (error) {
+        log.error('Failed to acquire issue lock', { error, issueId });
+        return false;
+    }
+}
+/**
+ * Read the current lock for an issue.
+ */
+export async function getIssueLock(issueId) {
+    if (!isRedisConfigured())
+        return null;
+    try {
+        const key = `${LOCK_PREFIX}${issueId}`;
+        // redisSetNX stores the raw JSON string; redisGet parses it back
+        // Since redisSetNX stores JSON.stringify(lock), redisGet returns the parsed lock directly
+        return await redisGet(key);
+    }
+    catch (error) {
+        log.error('Failed to get issue lock', { error, issueId });
+        return null;
+    }
+}
+/**
+ * Release an issue lock. Idempotent.
+ */
+export async function releaseIssueLock(issueId) {
+    if (!isRedisConfigured())
+        return;
+    try {
+        const key = `${LOCK_PREFIX}${issueId}`;
+        await redisDel(key);
+        log.info('Issue lock released', { issueId });
+    }
+    catch (error) {
+        log.error('Failed to release issue lock', { error, issueId });
+    }
+}
+/**
+ * Refresh the TTL on an issue lock (extend while agent is alive).
+ */
+export async function refreshIssueLockTTL(issueId, ttlSeconds = LOCK_TTL_SECONDS) {
+    if (!isRedisConfigured())
+        return false;
+    try {
+        const key = `${LOCK_PREFIX}${issueId}`;
+        return await redisExpire(key, ttlSeconds);
+    }
+    catch (error) {
+        log.error('Failed to refresh issue lock TTL', { error, issueId });
+        return false;
+    }
+}
+/**
+ * Park work for a locked issue.
+ *
+ * Deduplication: at most one parked item per workType per issue.
+ * If a parked item with the same workType already exists, it's replaced
+ * (the latest webhook wins). Different workTypes can coexist.
+ */
+export async function parkWorkForIssue(issueId, work) {
+    if (!isRedisConfigured()) {
+        return { parked: false, replaced: false };
+    }
+    try {
+        const pendingKey = `${PENDING_PREFIX}${issueId}`;
+        const itemsKey = `${PENDING_ITEMS_PREFIX}${issueId}`;
+        const workType = work.workType || 'development';
+        // Dedup key: use workType as the sorted set member
+        // This means at most one pending item per workType
+        const dedupMember = workType;
+        // Check if there's already a parked item with this workType
+        const existing = await redisHGet(itemsKey, dedupMember);
+        const replaced = !!existing;
+        if (replaced) {
+            // Remove old entry from sorted set before adding new one
+            await redisZRem(pendingKey, dedupMember);
+            log.info('Replacing existing parked work', {
+                issueId,
+                workType,
+                sessionId: work.sessionId,
+            });
+        }
+        // Score = priority (lower = higher priority)
+        const score = work.priority;
+        // Add to sorted set and hash
+        await redisZAdd(pendingKey, score, dedupMember);
+        await redisHSet(itemsKey, dedupMember, JSON.stringify(work));
+        // Set TTL on both keys
+        await redisExpire(pendingKey, PENDING_TTL_SECONDS);
+        await redisExpire(itemsKey, PENDING_TTL_SECONDS);
+        log.info('Work parked for issue', {
+            issueId,
+            workType,
+            sessionId: work.sessionId,
+            priority: work.priority,
+            replaced,
+        });
+        return { parked: true, replaced };
+    }
+    catch (error) {
+        log.error('Failed to park work for issue', { error, issueId });
+        return { parked: false, replaced: false };
+    }
+}
+/**
+ * Promote the next pending work item for an issue.
+ * Pops the highest-priority item, acquires the issue lock for it,
+ * and queues it in the global work queue.
+ *
+ * @returns The promoted work item, or null if nothing to promote
+ */
+export async function promoteNextPendingWork(issueId) {
+    if (!isRedisConfigured())
+        return null;
+    try {
+        const pendingKey = `${PENDING_PREFIX}${issueId}`;
+        const itemsKey = `${PENDING_ITEMS_PREFIX}${issueId}`;
+        // Pop the highest-priority (lowest score) member
+        const popped = await redisZPopMin(pendingKey);
+        if (!popped) {
+            log.debug('No pending work to promote', { issueId });
+            return null;
+        }
+        const dedupMember = popped.member;
+        // Get the work item from the hash
+        const workJson = await redisHGet(itemsKey, dedupMember);
+        if (!workJson) {
+            log.warn('Pending work item not found in hash', { issueId, dedupMember });
+            return null;
+        }
+        // Remove from hash
+        await redisHDel(itemsKey, dedupMember);
+        const work = JSON.parse(workJson);
+        // Acquire the issue lock for this promoted work
+        const lock = {
+            sessionId: work.sessionId,
+            workType: work.workType || 'development',
+            workerId: null,
+            lockedAt: Date.now(),
+            issueIdentifier: work.issueIdentifier,
+        };
+        const acquired = await acquireIssueLock(issueId, lock);
+        if (!acquired) {
+            log.warn('Failed to acquire lock for promoted work -- another lock appeared', {
+                issueId,
+                sessionId: work.sessionId,
+            });
+            // Re-park the work since we couldn't acquire the lock
+            await parkWorkForIssue(issueId, work);
+            return null;
+        }
+        // Queue in the global work queue
+        const queued = await queueWork(work);
+        if (!queued) {
+            log.error('Failed to queue promoted work', { issueId, sessionId: work.sessionId });
+            // Release the lock since we couldn't queue
+            await releaseIssueLock(issueId);
+            return null;
+        }
+        log.info('Pending work promoted', {
+            issueId,
+            sessionId: work.sessionId,
+            workType: work.workType,
+            issueIdentifier: work.issueIdentifier,
+        });
+        return work;
+    }
+    catch (error) {
+        log.error('Failed to promote pending work', { error, issueId });
+        return null;
+    }
+}
+/**
+ * Get the count of pending work items for an issue.
+ */
+export async function getPendingWorkCount(issueId) {
+    if (!isRedisConfigured())
+        return 0;
+    try {
+        const pendingKey = `${PENDING_PREFIX}${issueId}`;
+        return await redisZCard(pendingKey);
+    }
+    catch (error) {
+        log.error('Failed to get pending work count', { error, issueId });
+        return 0;
+    }
+}
+/**
+ * Main entry point for dispatching work.
+ *
+ * Try to acquire the issue lock:
+ * - If acquired -> queue the work in the global queue
+ * - If locked -> park the work in the per-issue pending queue
+ *
+ * @returns DispatchResult indicating what happened
+ */
+export async function dispatchWork(work) {
+    if (!isRedisConfigured()) {
+        // No Redis -- fall back to direct queueing (no locking)
+        const queued = await queueWork(work);
+        return { dispatched: queued, parked: false, replaced: false };
+    }
+    const issueId = work.issueId;
+    // Try to acquire the issue lock
+    const lock = {
+        sessionId: work.sessionId,
+        workType: work.workType || 'development',
+        workerId: null,
+        lockedAt: Date.now(),
+        issueIdentifier: work.issueIdentifier,
+    };
+    const acquired = await acquireIssueLock(issueId, lock);
+    if (acquired) {
+        // Lock acquired -- dispatch to global queue
+        const queued = await queueWork(work);
+        if (!queued) {
+            // Failed to queue -- release the lock
+            await releaseIssueLock(issueId);
+            return { dispatched: false, parked: false, replaced: false };
+        }
+        log.info('Work dispatched (lock acquired)', {
+            issueId,
+            sessionId: work.sessionId,
+            workType: work.workType,
+            issueIdentifier: work.issueIdentifier,
+        });
+        return { dispatched: true, parked: false, replaced: false };
+    }
+    // Lock held by another session -- park this work
+    const { parked, replaced } = await parkWorkForIssue(issueId, work);
+    if (parked) {
+        log.info('Work parked (issue locked)', {
+            issueId,
+            sessionId: work.sessionId,
+            workType: work.workType,
+            replaced,
+        });
+    }
+    return { dispatched: false, parked, replaced };
+}
+/**
+ * Remove a parked work item by sessionId.
+ *
+ * The issue-pending hash is keyed by workType, so we scan all entries
+ * to find the one matching the given sessionId.
+ *
+ * @returns true if a matching parked item was found and removed
+ */
+export async function removeParkedWorkBySessionId(issueId, sessionId) {
+    if (!isRedisConfigured())
+        return false;
+    try {
+        const pendingKey = `${PENDING_PREFIX}${issueId}`;
+        const itemsKey = `${PENDING_ITEMS_PREFIX}${issueId}`;
+        // Get all entries in the hash (keyed by workType)
+        const entries = await redisHGetAll(itemsKey);
+        if (!entries)
+            return false;
+        for (const [dedupMember, workJson] of Object.entries(entries)) {
+            try {
+                const work = JSON.parse(workJson);
+                if (work.sessionId === sessionId) {
+                    // Found the matching entry -- remove from both sorted set and hash
+                    await redisZRem(pendingKey, dedupMember);
+                    await redisHDel(itemsKey, dedupMember);
+                    log.info('Removed parked work by sessionId', {
+                        issueId,
+                        sessionId,
+                        workType: dedupMember,
+                    });
+                    return true;
+                }
+            }
+            catch {
+                // Skip malformed entries
+                continue;
+            }
+        }
+        log.debug('No parked work found for sessionId', { issueId, sessionId });
+        return false;
+    }
+    catch (error) {
+        log.error('Failed to remove parked work by sessionId', { error, issueId, sessionId });
+        return false;
+    }
+}
+/**
+ * Check if a session is parked in any issue-pending queue.
+ *
+ * Scans the issue:pending:items:{issueId} hash entries for a matching sessionId.
+ *
+ * @param issueId - The issue to check
+ * @param sessionId - The session to look for
+ * @returns true if the session is parked for this issue
+ */
+export async function isSessionParkedForIssue(issueId, sessionId) {
+    if (!isRedisConfigured())
+        return false;
+    try {
+        const itemsKey = `${PENDING_ITEMS_PREFIX}${issueId}`;
+        const entries = await redisHGetAll(itemsKey);
+        if (!entries)
+            return false;
+        for (const workJson of Object.values(entries)) {
+            try {
+                const work = JSON.parse(workJson);
+                if (work.sessionId === sessionId) {
+                    return true;
+                }
+            }
+            catch {
+                continue;
+            }
+        }
+        return false;
+    }
+    catch (error) {
+        log.error('Failed to check if session is parked', { error, issueId, sessionId });
+        return false;
+    }
+}
+/**
+ * Scan for expired issue locks that have pending work.
+ * If a lock expired naturally (TTL) but pending items remain, promote them.
+ *
+ * Called from orphan-cleanup to handle crashed workers that didn't release locks.
+ */
+export async function cleanupExpiredLocksWithPendingWork() {
+    if (!isRedisConfigured())
+        return 0;
+    let promoted = 0;
+    try {
+        // Find all pending queues
+        const pendingKeys = await redisKeys(`${PENDING_PREFIX}*`);
+        for (const pendingKey of pendingKeys) {
+            // Extract issueId from key
+            const issueId = pendingKey.replace(PENDING_PREFIX, '');
+            // Skip keys that are actually issue:pending:items:* hashes (not sorted sets)
+            if (issueId.includes(':'))
+                continue;
+            // Check if lock still exists
+            const lockKey = `${LOCK_PREFIX}${issueId}`;
+            const lock = await redisGet(lockKey);
+            if (!lock) {
+                // Lock expired but pending work exists -- promote
+                const count = await redisZCard(pendingKey);
+                if (count > 0) {
+                    log.info('Found expired lock with pending work, promoting', {
+                        issueId,
+                        pendingCount: count,
+                    });
+                    const work = await promoteNextPendingWork(issueId);
+                    if (work) {
+                        promoted++;
+                    }
+                }
+            }
+        }
+        if (promoted > 0) {
+            log.info('Promoted pending work from expired locks', { promoted });
+        }
+    }
+    catch (error) {
+        log.error('Failed to cleanup expired locks', { error });
+    }
+    return promoted;
+}
+// Statuses where a session should NOT be holding an issue lock.
+// Terminal: session finished (completed/failed/stopped) but lock release failed.
+// Pending: session was reset by orphan cleanup but lock wasn't released (see orphan-cleanup.ts).
+const STALE_LOCK_STATUSES = new Set(['completed', 'failed', 'stopped', 'pending']);
+/**
+ * Release issue locks held by sessions that should no longer hold them.
+ *
+ * This handles cases where:
+ * - A session completes but the lock release failed (network error during cleanup)
+ * - Orphan cleanup resets a session to 'pending' but the lock wasn't released
+ *
+ * The lock's 2-hour TTL would eventually expire, but this proactively clears it
+ * when workers have idle capacity.
+ *
+ * Only runs when workers are online -- if no workers are available, there's no
+ * point promoting parked work since nothing can pick it up.
+ *
+ * @param hasIdleWorkers - true if at least one worker is online with spare capacity
+ * @returns Number of stale locks released and parked work promoted
+ */
+export async function cleanupStaleLocksWithIdleWorkers(hasIdleWorkers) {
+    if (!isRedisConfigured())
+        return 0;
+    if (!hasIdleWorkers)
+        return 0;
+    let promoted = 0;
+    try {
+        // Find all issue locks
+        const lockKeys = await redisKeys(`${LOCK_PREFIX}*`);
+        for (const lockKey of lockKeys) {
+            const issueId = lockKey.replace(LOCK_PREFIX, '');
+            // Skip keys that look like pending queue keys (contain extra colons)
+            if (issueId.includes(':'))
+                continue;
+            const lock = await redisGet(lockKey);
+            if (!lock)
+                continue;
+            // Check if the lock holder's session is in a terminal state
+            const session = await getSessionState(lock.sessionId);
+            if (!session) {
+                // Session expired from Redis (24h TTL) but lock remains (2h TTL)
+                // Safe to release -- the session is long gone
+                log.info('Releasing lock for expired session', {
+                    issueId,
+                    sessionId: lock.sessionId,
+                    issueIdentifier: lock.issueIdentifier,
+                });
+                await releaseIssueLock(issueId);
+                const work = await promoteNextPendingWork(issueId);
+                if (work)
+                    promoted++;
+                continue;
+            }
+            if (STALE_LOCK_STATUSES.has(session.status)) {
+                log.info('Releasing stale lock (session no longer needs lock)', {
+                    issueId,
+                    sessionId: lock.sessionId,
+                    sessionStatus: session.status,
+                    issueIdentifier: lock.issueIdentifier,
+                    lockAge: Math.round((Date.now() - lock.lockedAt) / 1000),
+                });
+                await releaseIssueLock(issueId);
+                const work = await promoteNextPendingWork(issueId);
+                if (work) {
+                    promoted++;
+                    log.info('Promoted parked work after stale lock cleanup', {
+                        issueId,
+                        promotedSessionId: work.sessionId,
+                        promotedWorkType: work.workType,
+                    });
+                }
+            }
+        }
+        if (promoted > 0) {
+            log.info('Promoted parked work from stale locks', { promoted });
+        }
+    }
+    catch (error) {
+        log.error('Failed to cleanup stale locks', { error });
+    }
+    return promoted;
+}