@hyperdrive.bot/bmad-workflow 1.0.26 → 1.0.28

package/dist/services/orchestration/workflow-orchestrator.js

@@ -43,13 +43,16 @@
  * })
  * ```
  */
+import { randomUUID } from 'node:crypto';
 import { isEpicStory } from '../../models/story.js';
 import { ParserError, ValidationError } from '../../utils/errors.js';
 import { runAgentWithRetry } from '../../utils/retry.js';
+import { derivePrefixForSessionName } from '../../utils/session-naming.js';
 import { AssetResolver } from '../file-system/asset-resolver.js';
 import { PrdFixer } from '../parsers/prd-fixer.js';
 import { FileScaffolder } from '../scaffolding/file-scaffolder.js';
 import { BatchProcessor } from './batch-processor.js';
+import { LockedStoryDispatcher } from './locked-story-dispatcher.js';
 import { StoryQueue } from './story-queue.js';
 import { ReviewQueue } from '../review/review-queue.js';
 /**
@@ -61,6 +64,7 @@ import { ReviewQueue } from '../review/review-queue.js';
  */
 export class WorkflowOrchestrator {
     agentRunner;
+    agentRunnerFactory;
     assetResolver;
     batchProcessor;
     callbacks;
@@ -68,6 +72,7 @@ export class WorkflowOrchestrator {
     fileManager;
     fileScaffolder;
     inputDetector;
+    lockService;
     logger;
     mcpContextInjector;
     pathResolver;
@@ -87,12 +92,14 @@ export class WorkflowOrchestrator {
         this.prdParser = config.prdParser;
         this.epicParser = config.epicParser;
         this.agentRunner = config.agentRunner;
+        this.agentRunnerFactory = config.agentRunnerFactory;
         this.batchProcessor = config.batchProcessor;
         this.fileManager = config.fileManager;
         this.mcpContextInjector = config.mcpContextInjector;
         this.pathResolver = config.pathResolver;
         this.reviewPhaseExecutor = config.reviewPhaseExecutor;
         this.storyTypeDetector = config.storyTypeDetector;
+        this.lockService = config.lockService;
         this.logger = config.logger;
         this.workflowLogger = config.workflowLogger;
         this.callbacks = config.callbacks;
@@ -100,6 +107,75 @@ export class WorkflowOrchestrator {
         this.prdFixer = new PrdFixer(config.agentRunner, config.fileManager, config.logger);
         this.logger.debug('WorkflowOrchestrator initialized');
     }
+    /**
+     * Select the appropriate runner for the given agent type and config.
+     *
+     * When agentRunnerFactory is set and config.useChannels is true, delegates
+     * to the factory for discovery-based transport selection. Otherwise returns
+     * the default subprocess runner.
+     */
+    getRunner(agentType, config) {
+        if (this.agentRunnerFactory && config.useChannels) {
+            const runner = this.agentRunnerFactory.create(agentType, config);
+            this.logger.debug({ agentType, transport: 'channel' }, 'Runner selected via factory');
+            return runner;
+        }
+        return this.agentRunner;
+    }
+    /**
+     * Build stream callback options from workflow config.
+     * Returns onStream (spinner summary) and/or onStreamVerbose (raw passthrough)
+     * based on config.stream flag.
+     */
+    getStreamCallbacks(config, label) {
+        if (!config.stream) {
+            return {
+                onStream: (summary) => {
+                    this.logger.info({ phase: label }, summary);
+                },
+            };
+        }
+        // Stream mode: pipe raw text to stdout with phase labels
+        process.stdout.write(`\n── [${label}] streaming ──\n`);
+        return {
+            onStreamVerbose: (text) => {
+                process.stdout.write(text + '\n');
+            },
+        };
+    }
+    /**
+     * Resolve session name template with placeholders.
+     *
+     * @param config - Workflow config containing the sessionName template
+     * @param phase - Current phase name (e.g., "dev", "epic", "story")
+     * @param storyId - Optional story/epic identifier for {story} placeholder
+     * @returns Resolved session name string, or undefined if no template
+     */
+    resolveSessionName(config, phase, storyId) {
+        let template = config.sessionName;
+        // Auto-generate if no explicit template but inputPath is available
+        if (!template && config.inputPath) {
+            const prefix = derivePrefixForSessionName(config.inputPath);
+            template = `${prefix}-{phase}-{story}`;
+        }
+        if (!template)
+            return undefined;
+        // Replace {prefix} placeholder
+        template = template.replace(/\{prefix\}/g, config.inputPath ? derivePrefixForSessionName(config.inputPath) : '');
+        // Replace {phase}
+        template = template.replace(/\{phase\}/g, phase);
+        // Stutter normalization: strip phase word from storyId when it duplicates {phase}
+        if (storyId) {
+            if (phase === 'epic' && storyId.startsWith('epic-')) {
+                storyId = storyId.slice('epic-'.length);
+            }
+            else if (phase === 'story' && storyId.startsWith('story-')) {
+                storyId = storyId.slice('story-'.length);
+            }
+            template = template.replace(/\{story\}/g, storyId);
+        }
+        return template;
+    }
     /**
      * Execute the complete workflow
      *
@@ -550,9 +626,12 @@ Write output to: ${outputPath}`;
      * @returns Promise resolving to object with success count and failure array
      * @private
      */
-    async devWorker(workerId, queue, config, reviewQueue) {
+    async devWorker(workerId, queue, config, dispatcher, reviewQueue) {
         const workerLogger = this.logger.child({ workerId });
         let successCount = 0;
+        let skippedCount = 0;
+        let processedCount = 0;
+        let failedCount = 0;
         const failures = [];
         let devPhaseStarted = false;
         workerLogger.info('Worker started');
@@ -581,7 +660,8 @@ Write output to: ${outputPath}`;
                     storyNumber: story.fullNumber,
                     storyTitle: story.title,
                 }, 'Worker processing story');
-                try {
+                // Dispatch through lock-aware wrapper (passthrough when locking disabled)
+                const dispatchResult = await dispatcher.dispatch(story, async () => {
                     // Use the actual file path from the story object
                     const storyFilePath = story.filePath || `${storyDir}/STORY-${story.fullNumber}.md`;
                     // Extract just the filename for QA folder (preserve the same filename)
@@ -595,7 +675,7 @@ Write output to: ${outputPath}`;
                             storyNumber: story.fullNumber,
                         }, 'Story already in QA folder, skipping development');
                         successCount++;
-                        continue;
+                        return;
                     }
                     const storyExists = await this.fileManager.fileExists(storyFilePath);
                     if (!storyExists) {
@@ -604,7 +684,7 @@ Write output to: ${outputPath}`;
                             error: 'Story file not found',
                             identifier: story.fullNumber,
                         });
-                        continue;
+                        return;
                     }
                     // Update story status to InProgress
                     await this.updateStoryStatus(storyFilePath, 'InProgress');
@@ -658,6 +738,9 @@ Write output to: ${outputPath}`;
                     prompt += '*yolo mode*\n';
                     // Generate unique spawn ID
                     const spawnId = `dev-${story.fullNumber}-${storyStartTime}`;
+                    // Select runner via factory (Channel) or fallback (subprocess)
+                    const runner = this.getRunner('dev', config);
+                    const transport = runner === this.agentRunner ? 'subprocess' : 'channel';
                     // Invoke onSpawnStart callback
                     this.invokeCallback('onSpawnStart', this.callbacks?.onSpawnStart, {
                         agentType: 'dev',
@@ -669,12 +752,16 @@ Write output to: ${outputPath}`;
                         spawnId,
                         startTime: storyStartTime,
                         workerId,
+                        transport,
                     });
                     // Execute dev agent with retry on timeout/killed
-                    const result = await runAgentWithRetry(this.agentRunner, prompt, {
+                    const streamCbs = this.getStreamCallbacks(config, `dev ${story.fullNumber}`);
+                    const result = await runAgentWithRetry(runner, prompt, {
                         agentType: 'dev',
                         cwd: config.cwd,
+                        ...streamCbs,
                         references: config.references,
+                        sessionName: this.resolveSessionName(config, 'dev', story.fullNumber),
                         timeout: config.timeout ?? 2_700_000,
                     }, {
                         backoffMs: config.retryBackoffMs,
@@ -697,6 +784,7 @@ Write output to: ${outputPath}`;
                             spawnId,
                             startTime: storyStartTime,
                             success: true,
+                            transport,
                             workerId,
                         });
                         // Update story status to Done
@@ -736,6 +824,7 @@ Write output to: ${outputPath}`;
                             spawnId,
                             startTime: storyStartTime,
                             success: false,
+                            transport,
                             workerId,
                         });
                         // Invoke onError callback
@@ -765,23 +854,25 @@ Write output to: ${outputPath}`;
                             identifier: story.fullNumber,
                         });
                     }
+                });
+                // Track dispatch-level counters
+                if (dispatchResult.status === 'processed')
+                    processedCount++;
+                else if (dispatchResult.status === 'skipped')
+                    skippedCount++;
+                else if (dispatchResult.status === 'failed')
+                    failedCount++;
+                // Handle dispatch result for lock-aware outcomes
+                if (dispatchResult.status === 'skipped') {
+                    workerLogger.info({ reason: dispatchResult.reason, story: story.fullNumber }, 'Story locked, skipping');
+                    continue;
                 }
-                catch (error) {
-                    // Invoke onError callback for unexpected errors
-                    this.invokeErrorCallback(error, {
-                        itemId: story.fullNumber,
-                        phaseName: 'dev',
-                        recoverable: true,
-                    });
-                    // Catch errors for individual stories to prevent worker crash
-                    workerLogger.error({
-                        error: error.message,
-                        storyNumber: story.fullNumber,
-                    }, 'Error processing story, continuing with next story');
+                if (dispatchResult.status === 'failed') {
                     failures.push({
-                        error: error.message,
+                        error: dispatchResult.reason || 'Dispatch failed',
                         identifier: story.fullNumber,
                     });
+                    continue;
                 }
                 // Wait for configured interval before next story
                 if (config.storyInterval > 0) {
@@ -790,15 +881,18 @@ Write output to: ${outputPath}`;
                 }
             }
             workerLogger.info({
-                failureCount: failures.length,
+                failed: failedCount,
+                processed: processedCount,
+                skipped: skippedCount,
                 successCount,
-            }, 'Worker completed');
-            return { failures, success: successCount };
+                workerId,
+            }, `Worker ${workerId} complete: ${processedCount} processed, ${skippedCount} skipped, ${failedCount} failed`);
+            return { failed: failedCount, failures, processed: processedCount, skipped: skippedCount, success: successCount };
         }
         catch (error) {
             workerLogger.error({ error: error.message }, 'Worker failed with unhandled error');
             // Return partial results even on worker failure
-            return { failures, success: successCount };
+            return { failed: failedCount, failures, processed: processedCount, skipped: skippedCount, success: successCount };
         }
     }
     /**
@@ -942,6 +1036,9 @@ Write output to: ${outputPath}`;
                 // Generate unique spawn ID and timestamp
                 const spawnStartTime = Date.now();
                 const spawnId = `dev-${story.fullNumber}-${spawnStartTime}`;
+                // Select runner via factory (Channel) or fallback (subprocess)
+                const runner = this.getRunner('dev', config);
+                const transport = runner === this.agentRunner ? 'subprocess' : 'channel';
                 // Invoke onSpawnStart callback
                 this.invokeCallback('onSpawnStart', this.callbacks?.onSpawnStart, {
                     agentType: 'dev',
@@ -952,11 +1049,15 @@ Write output to: ${outputPath}`;
                     prompt,
                     spawnId,
                     startTime: spawnStartTime,
+                    transport,
                 });
-                const result = await runAgentWithRetry(this.agentRunner, prompt, {
+                const streamCbs2 = this.getStreamCallbacks(config, `dev ${story.fullNumber}`);
+                const result = await runAgentWithRetry(runner, prompt, {
                     agentType: 'dev',
                     cwd: config.cwd,
+                    ...streamCbs2,
                     references: config.references,
+                    sessionName: this.resolveSessionName(config, 'dev', story.fullNumber),
                     timeout: config.timeout ?? 2_700_000,
                 }, {
                     backoffMs: config.retryBackoffMs,
@@ -979,6 +1080,7 @@ Write output to: ${outputPath}`;
                         spawnId,
                         startTime: spawnStartTime,
                         success: true,
+                        transport,
                     });
                     // Update story status to Done
                     await this.updateStoryStatus(storyFilePath, 'Done');
@@ -1001,6 +1103,7 @@ Write output to: ${outputPath}`;
                         spawnId,
                         startTime: spawnStartTime,
                         success: false,
+                        transport,
                     });
                     // Invoke onError callback for spawn failure
                     this.invokeErrorCallback(new Error(result.errors), {
@@ -1202,6 +1305,9 @@ Write output to: ${outputPath}`;
             const results = await this.batchProcessor.processBatch(epicsToCreate, async (epic) => {
                 const spawnStartTime = Date.now();
                 const spawnId = `epic-${epic.number}`;
+                // Select runner via factory (Channel) or fallback (subprocess)
+                const runner = this.getRunner('architect', config);
+                const transport = runner === this.agentRunner ? 'subprocess' : 'channel';
                 // Fire onSpawnStart so the reporter shows which epic is being generated
                 this.invokeCallback('onSpawnStart', this.callbacks?.onSpawnStart, {
                     agentType: 'architect',
@@ -1210,6 +1316,7 @@ Write output to: ${outputPath}`;
                     phaseName: 'epic',
                     spawnId,
                     startTime: spawnStartTime,
+                    transport,
                 });
                 try {
                     // Generate epic file path with prefix
@@ -1279,10 +1386,13 @@ Write output to: ${outputPath}`;
                         }, 'Claude Prompt (Epic)');
                     }
                     // Step 3: Run Claude agent to populate content sections
-                    const result = await runAgentWithRetry(this.agentRunner, prompt, {
+                    const epicStreamCbs = this.getStreamCallbacks(config, `epic ${epic.number}`);
+                    const result = await runAgentWithRetry(runner, prompt, {
                         agentType: 'architect',
                         cwd: config.cwd,
+                        ...epicStreamCbs,
                         references: config.references,
+                        sessionName: this.resolveSessionName(config, 'epic', `epic-${epic.number}`),
                         timeout: config.timeout ?? 2_700_000,
                     }, {
                         backoffMs: config.retryBackoffMs,
@@ -1319,6 +1429,7 @@ Write output to: ${outputPath}`;
                         spawnId,
                         startTime: spawnStartTime,
                         success: true,
+                        transport,
                     });
                     return epicFilePath;
                 }
@@ -1335,6 +1446,7 @@ Write output to: ${outputPath}`;
                         spawnId,
                         startTime: spawnStartTime,
                         success: false,
+                        transport,
                     });
                     throw spawnError;
                 }
@@ -1480,15 +1592,21 @@ Write output to: ${outputPath}`;
         // PIPELINE MODE: Use single worker for sequential story processing
         // Stories are processed in order, one at a time as they become available
         const workerCount = 1;
+        // Instantiate lock-aware dispatcher shared by all workers
+        const sessionId = randomUUID();
+        const agentName = config.devAgent ?? 'pirlo';
+        const dispatcher = new LockedStoryDispatcher(config.lockingEnabled ? (this.lockService ?? null) : null, this.logger, agentName, sessionId);
         this.logger.info({
             interval: config.storyInterval,
+            lockingEnabled: !!config.lockingEnabled,
             mode: 'sequential',
             reviewEnabled: !!reviewQueue,
+            sessionId,
             workerCount,
         }, 'Starting pipelined development phase (sequential processing)');
         try {
             // Create single worker for sequential processing, passing reviewQueue if review is enabled
-            const workers = Array.from({ length: workerCount }, (_, i) => this.devWorker(i, queue, config, reviewQueue));
+            const workers = Array.from({ length: workerCount }, (_, i) => this.devWorker(i, queue, config, dispatcher, reviewQueue));
             // Wait for worker to complete
             const workerResults = await Promise.all(workers);
             // Close ReviewQueue after all dev workers finish (Task 3: close/drain semantics)
@@ -1498,23 +1616,34 @@ Write output to: ${outputPath}`;
             }
             // Aggregate results from all workers
             let totalSuccess = 0;
+            let totalSkipped = 0;
+            let totalProcessed = 0;
+            let totalFailed = 0;
             const allFailures = [];
             for (const result of workerResults) {
                 totalSuccess += result.success;
+                totalSkipped += result.skipped;
+                totalProcessed += result.processed;
+                totalFailed += result.failed;
                 allFailures.push(...result.failures);
             }
             const duration = Date.now() - startTime;
             this.logger.info({
                 duration,
-                failures: allFailures.length,
-                success: totalSuccess,
+                totalFailed,
+                totalProcessed,
+                totalSkipped,
                 workerCount,
-            }, 'Pipelined development phase completed');
+            }, 'Pipeline dev phase complete');
+            // Warn when all stories were skipped (locked by other sessions)
+            if (totalProcessed === 0 && totalSkipped > 0) {
+                this.logger.warn({ totalSkipped }, 'All stories locked by other sessions — this pipeline had no work to do');
+            }
             this.invokeCallback('onPhaseComplete', this.callbacks?.onPhaseComplete, {
                 duration,
                 endTime: Date.now(),
                 failureCount: allFailures.length,
-                itemCount: totalSuccess + allFailures.length,
+                itemCount: totalSuccess + allFailures.length + totalSkipped,
                 phaseName: 'dev',
                 startTime,
                 successCount: totalSuccess,
@@ -1524,6 +1653,7 @@ Write output to: ${outputPath}`;
                 failures: allFailures,
                 phaseName: 'dev',
                 skipped: false,
+                skippedCount: totalSkipped,
                 success: totalSuccess,
             };
         }
@@ -2202,6 +2332,9 @@ Write output to: ${outputPath}`;
             const results = await storyBatchProcessor.processBatch(storiesToCreate, async (story) => {
                 const spawnStartTime = Date.now();
                 const spawnId = `story-${story.fullNumber}`;
+                // Select runner via factory (Channel) or fallback (subprocess)
+                const runner = this.getRunner('sm', config);
+                const transport = runner === this.agentRunner ? 'subprocess' : 'channel';
                 // Fire onSpawnStart so the reporter shows which story is being created
                 this.invokeCallback('onSpawnStart', this.callbacks?.onSpawnStart, {
                     agentType: 'sm',
@@ -2210,6 +2343,7 @@ Write output to: ${outputPath}`;
                     phaseName: 'story',
                     spawnId,
                     startTime: spawnStartTime,
+                    transport,
                 });
                 try {
                     // Generate story file path with prefix
@@ -2233,6 +2367,7 @@ Write output to: ${outputPath}`;
                             spawnId,
                             startTime: spawnStartTime,
                             success: true,
+                            transport,
                         });
                         return storyFilePath;
                     }
@@ -2272,10 +2407,13 @@ Write output to: ${outputPath}`;
                         }, 'Claude Prompt (Story)');
                     }
                     // Step 4: Run Claude agent to populate content sections
-                    const result = await runAgentWithRetry(this.agentRunner, prompt, {
+                    const storyStreamCbs = this.getStreamCallbacks(config, `story ${story.fullNumber}`);
+                    const result = await runAgentWithRetry(runner, prompt, {
                         agentType: 'sm',
                         cwd: config.cwd,
+                        ...storyStreamCbs,
                         references: config.references,
+                        sessionName: this.resolveSessionName(config, 'story', story.fullNumber),
                         timeout: config.timeout ?? 2_700_000,
                     }, {
                         backoffMs: config.retryBackoffMs,
@@ -2338,6 +2476,7 @@ Write output to: ${outputPath}`;
                         spawnId,
                         startTime: spawnStartTime,
                         success: true,
+                        transport,
                     });
                     return storyFilePath;
                 }
@@ -2354,6 +2493,7 @@ Write output to: ${outputPath}`;
                         spawnId,
                         startTime: spawnStartTime,
                         success: false,
+                        transport,
                     });
                     throw spawnError;
                 }
@@ -2530,6 +2670,9 @@ Write output to: ${outputPath}`;
             const results = await storyBatchProcessor.processBatch(storiesToCreate, async (story) => {
                 const spawnStartTime = Date.now();
                 const spawnId = `story-${story.fullNumber}`;
+                // Select runner via factory (Channel) or fallback (subprocess)
+                const runner = this.getRunner('sm', config);
+                const transport = runner === this.agentRunner ? 'subprocess' : 'channel';
                 // Fire onSpawnStart so the reporter shows which story is being created
                 this.invokeCallback('onSpawnStart', this.callbacks?.onSpawnStart, {
                     agentType: 'sm',
@@ -2538,6 +2681,7 @@ Write output to: ${outputPath}`;
                     phaseName: 'story',
                     spawnId,
                     startTime: spawnStartTime,
+                    transport,
                 });
                 try {
                     // Generate story file path with prefix
@@ -2561,6 +2705,7 @@ Write output to: ${outputPath}`;
                             spawnId,
                             startTime: spawnStartTime,
                             success: true,
+                            transport,
                         });
                         return storyFilePath;
                     }
@@ -2599,10 +2744,13 @@ Write output to: ${outputPath}`;
                         }, 'Claude Prompt (Story)');
                     }
                     // Step 4: Run Claude agent to populate content sections
-                    const result = await runAgentWithRetry(this.agentRunner, prompt, {
+                    const storyStreamCbs = this.getStreamCallbacks(config, `story ${story.fullNumber}`);
+                    const result = await runAgentWithRetry(runner, prompt, {
                         agentType: 'sm',
                         cwd: config.cwd,
+                        ...storyStreamCbs,
                         references: config.references,
+                        sessionName: this.resolveSessionName(config, 'story', story.fullNumber),
                         timeout: config.timeout ?? 2_700_000,
                     }, {
                         backoffMs: config.retryBackoffMs,
@@ -2665,6 +2813,7 @@ Write output to: ${outputPath}`;
                         spawnId,
                         startTime: spawnStartTime,
                         success: true,
+                        transport,
                     });
                     return storyFilePath;
                 }
@@ -2681,6 +2830,7 @@ Write output to: ${outputPath}`;
                         spawnId,
                         startTime: spawnStartTime,
                         success: false,
+                        transport,
                     });
                     throw spawnError;
                 }

package/dist/services/review/ai-review-scanner.js

@@ -55,6 +55,7 @@ export class AIReviewScanner {
                 agentType: 'qa',
                 references,
                 timeout: this.timeout,
+                sessionName: context.sessionName,
             });
             this.logger.info({ duration: result.duration, exitCode: result.exitCode, storyId: context.storyId, success: result.success }, 'AI review scan completed');
             return this.parseAgentOutput(result);

package/dist/services/review/review-phase-executor.js

@@ -9,6 +9,7 @@
  * and pipelined review execution paths. The concrete implementation
  * (DefaultReviewPhaseExecutor) composes SelfHealLoop and TechDebtTracker.
  */
+import { derivePrefixForSessionName } from '../../utils/session-naming.js';
 import { Severity } from './types.js';
 /** Default severity threshold that blocks the pipeline */
 const DEFAULT_BLOCK_ON = Severity.HIGH;
@@ -49,11 +50,13 @@ export class DefaultReviewPhaseExecutor {
         const storyFile = story.filePath ?? '';
         const blockOn = config.reviewBlockOn ?? DEFAULT_BLOCK_ON;
         this.logger.info({ storyId, blockOn }, 'Reviewing story');
+        const prefix = config.inputPath ? derivePrefixForSessionName(config.inputPath) : undefined;
         const context = {
             baseBranch: 'main',
             changedFiles: [],
             projectRoot: config.cwd ?? process.cwd(),
             referenceFiles: config.references ?? [],
+            sessionName: prefix ? `${prefix}-review-${storyId}` : undefined,
             storyFile,
             storyId,
         };

package/dist/services/review/self-heal-loop.js

@@ -120,6 +120,7 @@ export class SelfHealLoop {
             const result = await this.agentRunner.runAgent(prompt, {
                 agentType: 'dev',
                 references: [context.storyFile, ...context.changedFiles],
+                sessionName: context.sessionName?.replace('-review-', '-fix-'),
                 timeout: this.config.fixTimeout,
             });
             return result;

package/dist/services/review/types.d.ts

@@ -40,6 +40,8 @@ export interface ReviewContext {
     storyFile: string;
     /** Story identifier (e.g., "PROJ-story-1.001") */
     storyId: string;
+    /** Optional Claude session display name — forwarded to --name flag when set */
+    sessionName?: string;
 }
 /**
  * Raw output from a scanner before classification

package/dist/utils/errors.d.ts

@@ -13,10 +13,12 @@ export declare const ERR_PARSER = "ERR_PARSER";
 export declare const ERR_FILE_SYSTEM = "ERR_FILE_SYSTEM";
 export declare const ERR_AGENT = "ERR_AGENT";
 export declare const ERR_CONFIG = "ERR_CONFIG";
+export declare const ERR_LOCK = "ERR_LOCK";
+export declare const ERR_PUSH_REJECTED = "ERR_PUSH_REJECTED";
 /**
  * Type for error codes
  */
-export type ErrorCode = typeof ERR_AGENT | typeof ERR_CONFIG | typeof ERR_FILE_SYSTEM | typeof ERR_PARSER | typeof ERR_VALIDATION;
+export type ErrorCode = typeof ERR_AGENT | typeof ERR_CONFIG | typeof ERR_FILE_SYSTEM | typeof ERR_LOCK | typeof ERR_PARSER | typeof ERR_PUSH_REJECTED | typeof ERR_VALIDATION;
 /**
  * Context object for additional error information
  */
@@ -151,6 +153,20 @@ export declare class ParserError extends BaseError {
      */
     constructor(message: string, context?: ErrorContext, suggestion?: string);
 }
+/**
+ * Push rejected error for git push failures
+ *
+ * Used when a git push is rejected due to unexpected errors (not non-fast-forward).
+ */
+export declare class PushRejectedError extends BaseError {
+    /**
+     * Create a new PushRejectedError
+     *
+     * @param message - Human-readable error message
+     * @param stderr - stderr output from the git push command
+     */
+    constructor(message: string, stderr: string);
+}
 /**
  * Handle fatal errors by logging and exiting the process
  *

package/dist/utils/errors.js

@@ -12,6 +12,8 @@ export const ERR_PARSER = 'ERR_PARSER';
 export const ERR_FILE_SYSTEM = 'ERR_FILE_SYSTEM';
 export const ERR_AGENT = 'ERR_AGENT';
 export const ERR_CONFIG = 'ERR_CONFIG';
+export const ERR_LOCK = 'ERR_LOCK';
+export const ERR_PUSH_REJECTED = 'ERR_PUSH_REJECTED';
 /**
  * Base error class with error codes and context
  *
@@ -196,6 +198,22 @@ export class ParserError extends BaseError {
         super(message, ERR_PARSER, context, suggestion || defaultSuggestion);
     }
 }
+/**
+ * Push rejected error for git push failures
+ *
+ * Used when a git push is rejected due to unexpected errors (not non-fast-forward).
+ */
+export class PushRejectedError extends BaseError {
+    /**
+     * Create a new PushRejectedError
+     *
+     * @param message - Human-readable error message
+     * @param stderr - stderr output from the git push command
+     */
+    constructor(message, stderr) {
+        super(message, ERR_PUSH_REJECTED, { stderr }, 'A git push was rejected. This may indicate a concurrent operation. Pull and retry.');
+    }
+}
 /**
  * Handle fatal errors by logging and exiting the process
  *