@hyperdrive.bot/bmad-workflow 1.0.25 → 1.0.27

package/dist/services/git/git-ops.d.ts

@@ -0,0 +1,58 @@
+/**
+ * GitOps — Git operations abstraction
+ *
+ * Wraps git CLI commands for pull, add, commit, push, and remove operations.
+ * All methods use execSync with { cwd, encoding: 'utf8', stdio: 'pipe' }.
+ */
+/**
+ * Result of a git push operation
+ */
+export interface PushResult {
+    isNonFastForward: boolean;
+    stderr: string;
+    success: boolean;
+}
+/**
+ * Git operations class for repository management
+ *
+ * All methods accept a `cwd` parameter to scope operations to a specific directory.
+ */
+export declare class GitOps {
+    /**
+     * Pull latest changes from remote with rebase and autostash
+     *
+     * @param cwd - Working directory for the git command
+     */
+    pull(cwd: string): void;
+    /**
+     * Stage a file for commit
+     *
+     * @param filePath - Path to the file to stage (relative to cwd)
+     * @param cwd - Working directory for the git command
+     */
+    add(filePath: string, cwd: string): void;
+    /**
+     * Create a commit with the [lock] prefix prepended to the message
+     *
+     * @param message - Commit message suffix (e.g., "acquire: story-1.001.md")
+     * @param cwd - Working directory for the git command
+     */
+    commit(message: string, cwd: string): void;
+    /**
+     * Push commits to remote
+     *
+     * Returns a typed PushResult. NEVER throws on non-fast-forward rejection.
+     * Throws PushRejectedError only on unexpected errors (e.g., no remote, network timeout).
+     *
+     * @param cwd - Working directory for the git command
+     * @returns Push result with success status and error details
+     */
+    push(cwd: string): PushResult;
+    /**
+     * Remove a file from git index (safe even if file is already deleted from disk)
+     *
+     * @param filePath - Path to the file to remove (relative to cwd)
+     * @param cwd - Working directory for the git command
+     */
+    remove(filePath: string, cwd: string): void;
+}

package/dist/services/git/git-ops.js

@@ -0,0 +1,73 @@
+/**
+ * GitOps — Git operations abstraction
+ *
+ * Wraps git CLI commands for pull, add, commit, push, and remove operations.
+ * All methods use execSync with { cwd, encoding: 'utf8', stdio: 'pipe' }.
+ */
+import { execSync } from 'node:child_process';
+import { PushRejectedError } from '../../utils/errors.js';
+/**
+ * Git operations class for repository management
+ *
+ * All methods accept a `cwd` parameter to scope operations to a specific directory.
+ */
+export class GitOps {
+    /**
+     * Pull latest changes from remote with rebase and autostash
+     *
+     * @param cwd - Working directory for the git command
+     */
+    pull(cwd) {
+        execSync('git pull --rebase --autostash', { cwd, encoding: 'utf8', stdio: 'pipe' });
+    }
+    /**
+     * Stage a file for commit
+     *
+     * @param filePath - Path to the file to stage (relative to cwd)
+     * @param cwd - Working directory for the git command
+     */
+    add(filePath, cwd) {
+        execSync(`git add ${filePath}`, { cwd, encoding: 'utf8', stdio: 'pipe' });
+    }
+    /**
+     * Create a commit with the [lock] prefix prepended to the message
+     *
+     * @param message - Commit message suffix (e.g., "acquire: story-1.001.md")
+     * @param cwd - Working directory for the git command
+     */
+    commit(message, cwd) {
+        execSync(`git commit -m "[lock] ${message}"`, { cwd, encoding: 'utf8', stdio: 'pipe' });
+    }
+    /**
+     * Push commits to remote
+     *
+     * Returns a typed PushResult. NEVER throws on non-fast-forward rejection.
+     * Throws PushRejectedError only on unexpected errors (e.g., no remote, network timeout).
+     *
+     * @param cwd - Working directory for the git command
+     * @returns Push result with success status and error details
+     */
+    push(cwd) {
+        try {
+            execSync('git push', { cwd, encoding: 'utf8', stdio: 'pipe' });
+            return { isNonFastForward: false, stderr: '', success: true };
+        }
+        catch (error) {
+            const err = error;
+            const stderr = err.stderr ? err.stderr.toString() : err.message;
+            if (/non-fast-forward|rejected/i.test(stderr)) {
+                return { isNonFastForward: true, stderr, success: false };
+            }
+            throw new PushRejectedError(`Git push failed: ${stderr}`, stderr);
+        }
+    }
+    /**
+     * Remove a file from git index (safe even if file is already deleted from disk)
+     *
+     * @param filePath - Path to the file to remove (relative to cwd)
+     * @param cwd - Working directory for the git command
+     */
+    remove(filePath, cwd) {
+        execSync(`git rm --cached --ignore-unmatch ${filePath}`, { cwd, encoding: 'utf8', stdio: 'pipe' });
+    }
+}

package/dist/services/git/index.d.ts

@@ -0,0 +1,3 @@
+export { GitOps } from './git-ops.js';
+export type { PushResult } from './git-ops.js';
+export { PushConflictHandler } from './push-conflict-handler.js';

package/dist/services/git/index.js

@@ -0,0 +1,2 @@
+export { GitOps } from './git-ops.js';
+export { PushConflictHandler } from './push-conflict-handler.js';

package/dist/services/git/push-conflict-handler.d.ts

@@ -0,0 +1,32 @@
+/**
+ * PushConflictHandler — Handles non-fast-forward push rejections
+ *
+ * When a git push is rejected due to a non-fast-forward error (race condition),
+ * this handler pulls the remote state, checks if a competing lock file exists,
+ * and either throws a LockConflictError (competing lock found) or retries the push.
+ */
+import type { GitOps } from './git-ops.js';
+/**
+ * Handles non-fast-forward push rejections during lock acquisition
+ */
+export declare class PushConflictHandler {
+    private readonly gitOps;
+    constructor(gitOps: GitOps);
+    /**
+     * Handle a non-fast-forward push rejection
+     *
+     * Pulls remote state, checks for competing lock files, and either:
+     * 1. Throws LockConflictError if a competing lock was found
+     * 2. Retries the push if the conflict was unrelated
+     * 3. Throws PushRejectedError if the retry also fails
+     *
+     * @param storyPath - Path to the story file being locked
+     * @param localLockPath - Path to the .lock file on disk
+     * @param cwd - Working directory for git operations
+     */
+    handleConflict(storyPath: string, localLockPath: string, cwd: string): void;
+    /**
+     * Clean up local lock file state
+     */
+    private cleanup;
+}

package/dist/services/git/push-conflict-handler.js

@@ -0,0 +1,84 @@
+/**
+ * PushConflictHandler — Handles non-fast-forward push rejections
+ *
+ * When a git push is rejected due to a non-fast-forward error (race condition),
+ * this handler pulls the remote state, checks if a competing lock file exists,
+ * and either throws a LockConflictError (competing lock found) or retries the push.
+ */
+import { execSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import fsExtra from 'fs-extra';
+const { removeSync } = fsExtra;
+import { LockConflictError, lockFileSchema } from '../../models/lock.js';
+import { PushRejectedError } from '../../utils/errors.js';
+/**
+ * Handles non-fast-forward push rejections during lock acquisition
+ */
+export class PushConflictHandler {
+    gitOps;
+    constructor(gitOps) {
+        this.gitOps = gitOps;
+    }
+    /**
+     * Handle a non-fast-forward push rejection
+     *
+     * Pulls remote state, checks for competing lock files, and either:
+     * 1. Throws LockConflictError if a competing lock was found
+     * 2. Retries the push if the conflict was unrelated
+     * 3. Throws PushRejectedError if the retry also fails
+     *
+     * @param storyPath - Path to the story file being locked
+     * @param localLockPath - Path to the .lock file on disk
+     * @param cwd - Working directory for git operations
+     */
+    handleConflict(storyPath, localLockPath, cwd) {
+        // Step 1: Pull remote state that caused the non-fast-forward
+        this.gitOps.pull(cwd);
+        // Step 2: Check if the pull brought in a competing .lock file
+        if (existsSync(localLockPath)) {
+            // Competing lock found — read and validate
+            const raw = readFileSync(localLockPath, 'utf8');
+            let parsed;
+            try {
+                parsed = JSON.parse(raw);
+            }
+            catch {
+                // Invalid JSON — corrupt lock
+                this.cleanup(localLockPath, cwd);
+                throw new PushRejectedError('Corrupt lock file found after pull — manual resolution required', raw);
+            }
+            const result = lockFileSchema.safeParse(parsed);
+            if (!result.success) {
+                // Schema validation failed — corrupt lock
+                this.cleanup(localLockPath, cwd);
+                throw new PushRejectedError('Corrupt lock file found after pull — manual resolution required', JSON.stringify(result.error));
+            }
+            const lockContent = result.data;
+            // Clean up losing agent's local state before throwing
+            this.cleanup(localLockPath, cwd);
+            // Throw with the winner's identity
+            throw new LockConflictError(lockContent);
+        }
+        // No competing lock — conflict was on a different file. Retry push.
+        const retryResult = this.gitOps.push(cwd);
+        if (retryResult.success) {
+            return;
+        }
+        // Retry also failed — clean up and throw
+        this.cleanup(localLockPath, cwd);
+        throw new PushRejectedError('Push rejected after retry — manual resolution required', retryResult.stderr);
+    }
+    /**
+     * Clean up local lock file state
+     */
+    cleanup(localLockPath, cwd) {
+        try {
+            removeSync(localLockPath);
+        }
+        catch { /* ignore */ }
+        try {
+            execSync('git reset HEAD -- ' + localLockPath, { cwd, stdio: 'pipe' });
+        }
+        catch { /* ignore */ }
+    }
+}

package/dist/services/lock/git-backed-lock-service.d.ts

@@ -0,0 +1,76 @@
+/**
+ * GitBackedLockService
+ *
+ * Orchestrates lock acquisition with git persistence: pull → check → create → add → commit → push.
+ * Ensures distributed agents on different machines see each other's locks by persisting
+ * lock files to the remote git branch.
+ *
+ * Delegates to:
+ * - LockService for filesystem lock operations (acquire, release, isLocked, isStale, getLockInfo)
+ * - GitOps for git operations (pull, add, commit, push)
+ * - PushConflictHandler for non-fast-forward push resolution
+ */
+import type { GitOps } from '../git/git-ops.js';
+import type { PushConflictHandler } from '../git/push-conflict-handler.js';
+import type { LockService } from './lock-service.js';
+/**
+ * Git-backed lock service that persists locks to remote via git
+ *
+ * Wraps LockService with a git pull → check → create → add → commit → push flow
+ * to ensure distributed lock visibility across machines.
+ */
+export declare class GitBackedLockService {
+    private readonly lockService;
+    private readonly gitOps;
+    private readonly conflictHandler;
+    /**
+     * Create a new GitBackedLockService
+     *
+     * @param lockService - LockService instance for filesystem lock operations
+     * @param gitOps - GitOps instance for git operations
+     * @param conflictHandler - PushConflictHandler for non-fast-forward resolution
+     */
+    constructor(lockService: LockService, gitOps: GitOps, conflictHandler: PushConflictHandler);
+    /**
+     * Acquire a lock on a story file with full git persistence
+     *
+     * Executes: pull → isLocked check → acquire → git add → git commit → git push
+     *
+     * On push non-fast-forward, delegates to PushConflictHandler.
+     * On any failure after lock file creation, cleans up the lock file from disk and git state.
+     *
+     * @param storyPath - Path to the story file to lock (relative to cwd)
+     * @param agentName - Name of the agent acquiring the lock
+     * @param sessionId - Unique session ID of the agent
+     * @param cwd - Working directory (git repository root)
+     * @throws {LockConflictError} If an active (non-stale) lock exists or another agent won the race
+     */
+    acquire(storyPath: string, agentName: string, sessionId: string, cwd: string): Promise<void>;
+    /**
+     * Release a lock on a story file with git persistence
+     *
+     * Executes: LockService.release() → GitOps.remove() → GitOps.commit() → GitOps.push()
+     *
+     * On push failure, logs a warning but does NOT throw — the lock file is already
+     * deleted locally, and the story is considered unlocked for the releasing agent.
+     *
+     * @param storyPath - Path to the story file to unlock (relative to cwd)
+     * @param cwd - Working directory (git repository root)
+     */
+    release(storyPath: string, cwd: string): Promise<void>;
+    /**
+     * Clean up a lock file from disk and git staging area
+     *
+     * Handles 3 possible states:
+     * 1. File on disk, not staged → removeSync is sufficient
+     * 2. File on disk, staged → removeSync + git reset HEAD
+     * 3. File on disk, committed but not pushed → removeSync + git reset HEAD
+     *
+     * Each cleanup step is wrapped in its own try/catch — a failure in one
+     * should not prevent the others from executing.
+     *
+     * @param lockFilePath - Path to the lock file (relative to cwd)
+     * @param cwd - Working directory (git repository root)
+     */
+    private cleanupLockFile;
+}

package/dist/services/lock/git-backed-lock-service.js

@@ -0,0 +1,173 @@
+/**
+ * GitBackedLockService
+ *
+ * Orchestrates lock acquisition with git persistence: pull → check → create → add → commit → push.
+ * Ensures distributed agents on different machines see each other's locks by persisting
+ * lock files to the remote git branch.
+ *
+ * Delegates to:
+ * - LockService for filesystem lock operations (acquire, release, isLocked, isStale, getLockInfo)
+ * - GitOps for git operations (pull, add, commit, push)
+ * - PushConflictHandler for non-fast-forward push resolution
+ */
+import { execSync } from 'node:child_process';
+import path from 'node:path';
+import fsExtra from 'fs-extra';
+const { removeSync } = fsExtra;
+import { LockConflictError, PushRejectedError } from '../../models/lock.js';
+/**
+ * Git-backed lock service that persists locks to remote via git
+ *
+ * Wraps LockService with a git pull → check → create → add → commit → push flow
+ * to ensure distributed lock visibility across machines.
+ */
+export class GitBackedLockService {
+    lockService;
+    gitOps;
+    conflictHandler;
+    /**
+     * Create a new GitBackedLockService
+     *
+     * @param lockService - LockService instance for filesystem lock operations
+     * @param gitOps - GitOps instance for git operations
+     * @param conflictHandler - PushConflictHandler for non-fast-forward resolution
+     */
+    constructor(lockService, gitOps, conflictHandler) {
+        this.lockService = lockService;
+        this.gitOps = gitOps;
+        this.conflictHandler = conflictHandler;
+    }
+    /**
+     * Acquire a lock on a story file with full git persistence
+     *
+     * Executes: pull → isLocked check → acquire → git add → git commit → git push
+     *
+     * On push non-fast-forward, delegates to PushConflictHandler.
+     * On any failure after lock file creation, cleans up the lock file from disk and git state.
+     *
+     * @param storyPath - Path to the story file to lock (relative to cwd)
+     * @param agentName - Name of the agent acquiring the lock
+     * @param sessionId - Unique session ID of the agent
+     * @param cwd - Working directory (git repository root)
+     * @throws {LockConflictError} If an active (non-stale) lock exists or another agent won the race
+     */
+    async acquire(storyPath, agentName, sessionId, cwd) {
+        const lockFilePath = storyPath + '.lock';
+        // Step 1: Sync latest remote state
+        this.gitOps.pull(cwd);
+        // Step 2: Check for existing lock
+        const locked = await this.lockService.isLocked(storyPath);
+        if (locked) {
+            // Check if the existing lock is stale
+            const stale = await this.lockService.isStale(storyPath);
+            if (!stale) {
+                // Active lock — throw conflict with owner details
+                const lockInfo = await this.lockService.getLockInfo(storyPath);
+                if (lockInfo) {
+                    throw new LockConflictError(lockInfo);
+                }
+            }
+            // Stale lock — release it before proceeding
+            await this.lockService.release(storyPath);
+        }
+        // Steps 3–8: Create lock, stage, commit, push (with cleanup on failure)
+        try {
+            // Step 3: Create .lock file on disk
+            await this.lockService.acquire(storyPath, agentName, sessionId);
+            // Step 5: Stage the lock file
+            this.gitOps.add(lockFilePath, cwd);
+            // Step 6: Commit
+            this.gitOps.commit('[lock] acquire: ' + path.basename(storyPath), cwd);
+            // Step 7: Push
+            const pushResult = this.gitOps.push(cwd);
+            // Step 8: Handle push result
+            if (!pushResult.success) {
+                if (pushResult.isNonFastForward) {
+                    // Delegate to conflict handler (Story 2.3)
+                    this.conflictHandler.handleConflict(storyPath, lockFilePath, cwd);
+                }
+                else {
+                    // Non-recoverable push error
+                    throw new PushRejectedError({ storyFile: storyPath, reason: pushResult.stderr || 'unknown error' });
+                }
+            }
+        }
+        catch (error) {
+            // Cleanup: remove lock file from disk and git state
+            this.cleanupLockFile(lockFilePath, cwd);
+            // Re-throw the original error
+            throw error;
+        }
+    }
+    /**
+     * Release a lock on a story file with git persistence
+     *
+     * Executes: LockService.release() → GitOps.remove() → GitOps.commit() → GitOps.push()
+     *
+     * On push failure, logs a warning but does NOT throw — the lock file is already
+     * deleted locally, and the story is considered unlocked for the releasing agent.
+     *
+     * @param storyPath - Path to the story file to unlock (relative to cwd)
+     * @param cwd - Working directory (git repository root)
+     */
+    async release(storyPath, cwd) {
+        const lockFilePath = storyPath + '.lock';
+        const storyFileName = path.basename(storyPath);
+        // Step 1: Delete lock file from disk
+        await this.lockService.release(storyPath);
+        // Step 2: Stage the removal in git
+        this.gitOps.remove(lockFilePath, cwd);
+        // Step 3: Commit the removal
+        this.gitOps.commit('release: ' + storyFileName, cwd);
+        // Step 4: Push — non-fatal on failure
+        try {
+            const pushResult = this.gitOps.push(cwd);
+            if (!pushResult.success) {
+                // Log warning but don't throw — lock is already deleted locally
+                console.warn(`[lock] Push after release failed for ${storyFileName}: ${pushResult.stderr || 'unknown error'}`);
+            }
+        }
+        catch (error) {
+            // Network error or other unexpected failure — still non-fatal
+            console.warn(`[lock] Push after release failed for ${storyFileName}: ${error.message}`);
+        }
+    }
+    /**
+     * Clean up a lock file from disk and git staging area
+     *
+     * Handles 3 possible states:
+     * 1. File on disk, not staged → removeSync is sufficient
+     * 2. File on disk, staged → removeSync + git reset HEAD
+     * 3. File on disk, committed but not pushed → removeSync + git reset HEAD
+     *
+     * Each cleanup step is wrapped in its own try/catch — a failure in one
+     * should not prevent the others from executing.
+     *
+     * @param lockFilePath - Path to the lock file (relative to cwd)
+     * @param cwd - Working directory (git repository root)
+     */
+    cleanupLockFile(lockFilePath, cwd) {
+        const absoluteLockPath = path.resolve(cwd, lockFilePath);
+        // Remove file from disk
+        try {
+            removeSync(absoluteLockPath);
+        }
+        catch {
+            // File may not exist — that's OK
+        }
+        // Unstage from git index (git checkout)
+        try {
+            execSync('git checkout -- ' + lockFilePath, { cwd, stdio: 'pipe' });
+        }
+        catch {
+            // May fail if file wasn't staged — that's OK
+        }
+        // Reset from staging area
+        try {
+            execSync('git reset HEAD -- ' + lockFilePath, { cwd, stdio: 'pipe' });
+        }
+        catch {
+            // May fail if nothing to reset — that's OK
+        }
+    }
+}

package/dist/services/lock/lock-cleanup.d.ts

@@ -0,0 +1,49 @@
+/**
+ * LockCleanupService
+ *
+ * Batch cleanup of stale lock files with git persistence.
+ * Pulls latest state, scans for stale locks, deletes them all,
+ * then commits and pushes in a single atomic operation.
+ */
+import type pino from 'pino';
+import type { GitOps } from '../git/git-ops.js';
+import type { LockService } from './lock-service.js';
+/**
+ * Service for batch cleanup of stale locks with git persistence
+ *
+ * Orchestrates: pull → findStaleLocks → release each → stage each → single commit → push
+ */
+export declare class LockCleanupService {
+    private readonly lockService;
+    private readonly gitOps;
+    private readonly logger;
+    private readonly storiesDir;
+    /**
+     * Create a new LockCleanupService
+     *
+     * @param lockService - LockService instance for filesystem lock operations
+     * @param gitOps - GitOps instance for git operations
+     * @param logger - Pino logger instance
+     * @param storiesDir - Directory to scan for lock files (relative to cwd)
+     */
+    constructor(lockService: LockService, gitOps: GitOps, logger: pino.Logger, storiesDir: string);
+    /**
+     * Clean up all stale locks with git persistence
+     *
+     * Flow:
+     * 1. Pull latest remote state
+     * 2. Find all stale locks via LockService.findStaleLocks()
+     * 3. If none found, return { cleaned: 0 } with no git operations
+     * 4. Delete each stale lock from disk and stage for removal
+     * 5. Commit all removals in a single commit
+     * 6. Push to remote — throws PushRejectedError on failure
+     *
+     * @param staleThresholdMs - Threshold in milliseconds for considering a lock stale
+     * @param cwd - Working directory (git repository root)
+     * @returns Object with count of cleaned locks
+     * @throws {PushRejectedError} If git push fails after cleanup
+     */
+    cleanupStaleLocks(staleThresholdMs: number, cwd: string): Promise<{
+        cleaned: number;
+    }>;
+}

package/dist/services/lock/lock-cleanup.js

@@ -0,0 +1,85 @@
+/**
+ * LockCleanupService
+ *
+ * Batch cleanup of stale lock files with git persistence.
+ * Pulls latest state, scans for stale locks, deletes them all,
+ * then commits and pushes in a single atomic operation.
+ */
+import { PushRejectedError } from '../../utils/errors.js';
+/**
+ * Service for batch cleanup of stale locks with git persistence
+ *
+ * Orchestrates: pull → findStaleLocks → release each → stage each → single commit → push
+ */
+export class LockCleanupService {
+    lockService;
+    gitOps;
+    logger;
+    storiesDir;
+    /**
+     * Create a new LockCleanupService
+     *
+     * @param lockService - LockService instance for filesystem lock operations
+     * @param gitOps - GitOps instance for git operations
+     * @param logger - Pino logger instance
+     * @param storiesDir - Directory to scan for lock files (relative to cwd)
+     */
+    constructor(lockService, gitOps, logger, storiesDir) {
+        this.lockService = lockService;
+        this.gitOps = gitOps;
+        this.logger = logger;
+        this.storiesDir = storiesDir;
+    }
+    /**
+     * Clean up all stale locks with git persistence
+     *
+     * Flow:
+     * 1. Pull latest remote state
+     * 2. Find all stale locks via LockService.findStaleLocks()
+     * 3. If none found, return { cleaned: 0 } with no git operations
+     * 4. Delete each stale lock from disk and stage for removal
+     * 5. Commit all removals in a single commit
+     * 6. Push to remote — throws PushRejectedError on failure
+     *
+     * @param staleThresholdMs - Threshold in milliseconds for considering a lock stale
+     * @param cwd - Working directory (git repository root)
+     * @returns Object with count of cleaned locks
+     * @throws {PushRejectedError} If git push fails after cleanup
+     */
+    async cleanupStaleLocks(staleThresholdMs, cwd) {
+        // Step 1: Get latest remote state
+        this.gitOps.pull(cwd);
+        // Step 2: Find all stale locks
+        const staleLocks = await this.lockService.findStaleLocks(this.storiesDir, staleThresholdMs);
+        // Step 3: No stale locks — early return, no git operations
+        if (staleLocks.length === 0) {
+            this.logger.info('No stale locks found');
+            return { cleaned: 0 };
+        }
+        this.logger.info({ count: staleLocks.length }, 'Found stale locks, cleaning up');
+        // Step 4: Delete each stale lock from disk and stage the removal
+        for (const lockFilePath of staleLocks) {
+            const storyPath = lockFilePath.replace(/\.lock$/, '');
+            await this.lockService.release(storyPath);
+            this.gitOps.remove(lockFilePath, cwd);
+        }
+        // Step 5: Single commit for all removals
+        this.gitOps.commit(`cleanup: ${staleLocks.length} stale locks`, cwd);
+        // Step 6: Push — throws on failure
+        try {
+            const pushResult = this.gitOps.push(cwd);
+            if (!pushResult.success) {
+                throw new PushRejectedError(`Push failed after stale lock cleanup: ${pushResult.stderr || 'unknown error'}`, pushResult.stderr || '');
+            }
+        }
+        catch (error) {
+            if (error instanceof PushRejectedError) {
+                throw error;
+            }
+            // Unexpected error — wrap in PushRejectedError
+            throw new PushRejectedError(`Push failed after stale lock cleanup: ${error.message}`, error.message);
+        }
+        this.logger.info({ cleaned: staleLocks.length }, 'Stale lock cleanup complete');
+        return { cleaned: staleLocks.length };
+    }
+}