@hyperdrive.bot/bmad-workflow 1.0.26 → 1.0.28

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

@@ -0,0 +1,143 @@
+/**
+ * LockService
+ *
+ * Manages story file locks to prevent concurrent agent sessions from
+ * modifying the same story. Supports acquiring, checking, releasing,
+ * and stale detection of locks.
+ */
+import type pino from 'pino';
+import type { LockFileContent } from '../../models/lock.js';
+import type { FileManager } from '../file-system/file-manager.js';
+import type { GlobMatcher } from '../file-system/glob-matcher.js';
+/**
+ * Service for managing story file locks
+ *
+ * Locks are stored as `<storyPath>.lock` JSON files alongside the story files.
+ * Each lock contains the agent session ID, agent name, timestamp, and branch.
+ */
+export declare class LockService {
+    /**
+     * Default stale threshold in milliseconds (2 hours)
+     */
+    static readonly DEFAULT_STALE_THRESHOLD_MS = 7200000;
+    private readonly fileManager;
+    private readonly globMatcher;
+    private readonly logger;
+    /**
+     * Create a new LockService instance
+     *
+     * @param fileManager - FileManager instance for file operations
+     * @param globMatcher - GlobMatcher instance for file pattern matching
+     * @param logger - Pino logger instance
+     */
+    constructor(fileManager: FileManager, globMatcher: GlobMatcher, logger: pino.Logger);
+    /**
+     * Acquire a lock on a story file
+     *
+     * If a lock already exists, checks if it's stale. Stale locks are auto-released
+     * and re-acquired. Fresh locks cause a LockConflictError.
+     *
+     * @param storyPath - Path to the story file to lock
+     * @param agentName - Name of the agent acquiring the lock
+     * @param sessionId - Unique session ID of the agent
+     * @param branch - Git branch the agent is working on (defaults to 'unknown')
+     * @throws {LockConflictError} If an active (non-stale) lock exists
+     */
+    acquire(storyPath: string, agentName: string, sessionId: string, branch?: string): Promise<void>;
+    /**
+     * Get lock file content for a story
+     *
+     * @param storyPath - Path to the story file
+     * @returns Lock file content if valid, null if missing or malformed
+     */
+    getLockInfo(storyPath: string): Promise<LockFileContent | null>;
+    /**
+     * Check if a story file is currently locked
+     *
+     * @param storyPath - Path to the story file
+     * @returns True if a valid lock exists
+     */
+    isLocked(storyPath: string): Promise<boolean>;
+    /**
+     * Check if an existing lock is stale (expired or corrupt)
+     *
+     * A lock is stale when:
+     * - The lock file exists but contains malformed/unparseable JSON
+     * - The lock's started_at timestamp + thresholdMs is less than Date.now()
+     * - The lock's started_at is an invalid date
+     *
+     * A lock is NOT stale when:
+     * - No lock file exists
+     * - The lock is within the threshold window
+     *
+     * @param storyPath - Path to the story file
+     * @param thresholdMs - Stale threshold in milliseconds (default: 2 hours)
+     * @returns True if the lock is stale
+     */
+    isStale(storyPath: string, thresholdMs?: number): Promise<boolean>;
+    /**
+     * Release a lock on a story file
+     *
+     * Idempotent — calling on a non-existent lock does not throw.
+     *
+     * @param storyPath - Path to the story file
+     */
+    release(storyPath: string): Promise<void>;
+    /**
+     * Find stale lock files in a directory without releasing them
+     *
+     * Scans the given directory for `.lock` files, checks each for staleness,
+     * and returns paths of stale ones. Malformed lock files are treated as stale.
+     *
+     * @param storiesDir - Directory to scan for lock files
+     * @param thresholdMs - Optional stale threshold in milliseconds
+     * @returns Array of stale lock file paths (the .lock file paths, not story paths)
+     */
+    findStaleLocks(storiesDir: string, thresholdMs?: number): Promise<string[]>;
+    /**
+     * Batch cleanup of stale lock files in a directory
+     *
+     * Scans the given directory for `.lock` files, checks each for staleness,
+     * and removes stale ones. Malformed lock files are treated as stale.
+     *
+     * @param storiesDir - Directory to scan for lock files
+     * @param thresholdMs - Optional stale threshold in milliseconds
+     * @returns Array of removed lock file paths
+     */
+    cleanup(storiesDir: string, thresholdMs?: number): Promise<string[]>;
+    /**
+     * List all active locks in a directory with metadata
+     *
+     * Scans the given directory for `.lock` files, reads each lock,
+     * and returns metadata including stale status. Malformed locks are skipped.
+     *
+     * @param storiesDir - Directory to scan for lock files
+     * @returns Array of lock metadata objects
+     */
+    list(storiesDir: string): Promise<Array<{
+        storyPath: string;
+        lock: LockFileContent;
+        isStale: boolean;
+    }>>;
+    /**
+     * List all locks across multiple story directories with stale status
+     *
+     * Scans each directory for `.lock` files, reads and validates each lock,
+     * and returns metadata including stale status. Malformed locks are skipped
+     * with a warning. Results are sorted by started_at descending (newest first).
+     *
+     * @param storyDirs - Array of directories to scan for lock files
+     * @param thresholdMs - Optional stale threshold in milliseconds (default: DEFAULT_STALE_THRESHOLD_MS)
+     * @returns Array of lock metadata with stale boolean, sorted newest first
+     */
+    listLocks(storyDirs: string[], thresholdMs?: number): Promise<Array<LockFileContent & {
+        stale: boolean;
+    }>>;
+    /**
+     * Resolve the lock file path for a given story path
+     *
+     * @param storyPath - Path to the story file
+     * @returns Path to the corresponding lock file
+     */
+    private resolveLockPath;
+}

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

@@ -0,0 +1,290 @@
+/**
+ * LockService
+ *
+ * Manages story file locks to prevent concurrent agent sessions from
+ * modifying the same story. Supports acquiring, checking, releasing,
+ * and stale detection of locks.
+ */
+import path from 'node:path';
+import { LockConflictError, lockFileSchema } from '../../models/lock.js';
+/**
+ * Service for managing story file locks
+ *
+ * Locks are stored as `<storyPath>.lock` JSON files alongside the story files.
+ * Each lock contains the agent session ID, agent name, timestamp, and branch.
+ */
+export class LockService {
+    /**
+     * Default stale threshold in milliseconds (2 hours)
+     */
+    static DEFAULT_STALE_THRESHOLD_MS = 7_200_000;
+    fileManager;
+    globMatcher;
+    logger;
+    /**
+     * Create a new LockService instance
+     *
+     * @param fileManager - FileManager instance for file operations
+     * @param globMatcher - GlobMatcher instance for file pattern matching
+     * @param logger - Pino logger instance
+     */
+    constructor(fileManager, globMatcher, logger) {
+        this.fileManager = fileManager;
+        this.globMatcher = globMatcher;
+        this.logger = logger;
+    }
+    /**
+     * Acquire a lock on a story file
+     *
+     * If a lock already exists, checks if it's stale. Stale locks are auto-released
+     * and re-acquired. Fresh locks cause a LockConflictError.
+     *
+     * @param storyPath - Path to the story file to lock
+     * @param agentName - Name of the agent acquiring the lock
+     * @param sessionId - Unique session ID of the agent
+     * @param branch - Git branch the agent is working on (defaults to 'unknown')
+     * @throws {LockConflictError} If an active (non-stale) lock exists
+     */
+    async acquire(storyPath, agentName, sessionId, branch = 'unknown') {
+        this.logger.info({ agentName, sessionId, storyPath }, 'Attempting to acquire lock');
+        const lockPath = this.resolveLockPath(storyPath);
+        const exists = await this.fileManager.fileExists(lockPath);
+        if (exists) {
+            const existingLock = await this.getLockInfo(storyPath);
+            if (existingLock) {
+                const stale = await this.isStale(storyPath);
+                if (stale) {
+                    this.logger.info({ storyPath }, 'Stale lock auto-released, re-acquiring');
+                    await this.release(storyPath);
+                }
+                else {
+                    throw new LockConflictError(existingLock);
+                }
+            }
+            else {
+                // Lock file exists but is malformed — treat as stale and release
+                this.logger.info({ storyPath }, 'Malformed lock detected, auto-releasing and re-acquiring');
+                await this.release(storyPath);
+            }
+        }
+        const lockContent = {
+            agent_name: agentName,
+            agent_session_id: sessionId,
+            branch,
+            started_at: new Date().toISOString(),
+            story_file: storyPath,
+        };
+        await this.fileManager.writeFile(lockPath, JSON.stringify(lockContent, null, 2));
+        this.logger.info({ agentName, sessionId, storyPath }, 'Lock acquired successfully');
+    }
+    /**
+     * Get lock file content for a story
+     *
+     * @param storyPath - Path to the story file
+     * @returns Lock file content if valid, null if missing or malformed
+     */
+    async getLockInfo(storyPath) {
+        const lockPath = this.resolveLockPath(storyPath);
+        const exists = await this.fileManager.fileExists(lockPath);
+        if (!exists) {
+            return null;
+        }
+        try {
+            const content = await this.fileManager.readFile(lockPath);
+            const parsed = JSON.parse(content);
+            const result = lockFileSchema.safeParse(parsed);
+            if (!result.success) {
+                this.logger.warn({ lockPath }, 'Lock file contains invalid schema');
+                return null;
+            }
+            return result.data;
+        }
+        catch {
+            this.logger.warn({ lockPath }, 'Lock file contains malformed JSON');
+            return null;
+        }
+    }
+    /**
+     * Check if a story file is currently locked
+     *
+     * @param storyPath - Path to the story file
+     * @returns True if a valid lock exists
+     */
+    async isLocked(storyPath) {
+        const lockInfo = await this.getLockInfo(storyPath);
+        return lockInfo !== null;
+    }
+    /**
+     * Check if an existing lock is stale (expired or corrupt)
+     *
+     * A lock is stale when:
+     * - The lock file exists but contains malformed/unparseable JSON
+     * - The lock's started_at timestamp + thresholdMs is less than Date.now()
+     * - The lock's started_at is an invalid date
+     *
+     * A lock is NOT stale when:
+     * - No lock file exists
+     * - The lock is within the threshold window
+     *
+     * @param storyPath - Path to the story file
+     * @param thresholdMs - Stale threshold in milliseconds (default: 2 hours)
+     * @returns True if the lock is stale
+     */
+    async isStale(storyPath, thresholdMs = LockService.DEFAULT_STALE_THRESHOLD_MS) {
+        const lockInfo = await this.getLockInfo(storyPath);
+        const lockPath = this.resolveLockPath(storyPath);
+        if (lockInfo === null) {
+            // getLockInfo returns null for BOTH "missing file" and "malformed JSON"
+            // Distinguish: if file exists but getLockInfo is null → malformed → stale
+            const exists = await this.fileManager.fileExists(lockPath);
+            return exists; // exists + malformed = stale; !exists = not stale
+        }
+        const startedAt = new Date(lockInfo.started_at).getTime();
+        if (Number.isNaN(startedAt))
+            return true; // invalid date = stale
+        return startedAt + thresholdMs < Date.now();
+    }
+    /**
+     * Release a lock on a story file
+     *
+     * Idempotent — calling on a non-existent lock does not throw.
+     *
+     * @param storyPath - Path to the story file
+     */
+    async release(storyPath) {
+        const lockPath = this.resolveLockPath(storyPath);
+        await this.fileManager.deleteFile(lockPath);
+        this.logger.debug({ storyPath }, 'Lock released');
+    }
+    /**
+     * Find stale lock files in a directory without releasing them
+     *
+     * Scans the given directory for `.lock` files, checks each for staleness,
+     * and returns paths of stale ones. Malformed lock files are treated as stale.
+     *
+     * @param storiesDir - Directory to scan for lock files
+     * @param thresholdMs - Optional stale threshold in milliseconds
+     * @returns Array of stale lock file paths (the .lock file paths, not story paths)
+     */
+    async findStaleLocks(storiesDir, thresholdMs) {
+        const pattern = path.join(storiesDir, '**/*.lock');
+        const lockFiles = await this.globMatcher.expandPattern(pattern);
+        if (lockFiles.length === 0) {
+            return [];
+        }
+        const staleLocks = [];
+        for (const lockFile of lockFiles) {
+            const storyPath = lockFile.replace(/\.lock$/, '');
+            const stale = await this.isStale(storyPath, thresholdMs);
+            if (stale) {
+                staleLocks.push(lockFile);
+            }
+        }
+        this.logger.info({ found: staleLocks.length, scanned: lockFiles.length, storiesDir }, 'Stale lock scan complete');
+        return staleLocks;
+    }
+    /**
+     * Batch cleanup of stale lock files in a directory
+     *
+     * Scans the given directory for `.lock` files, checks each for staleness,
+     * and removes stale ones. Malformed lock files are treated as stale.
+     *
+     * @param storiesDir - Directory to scan for lock files
+     * @param thresholdMs - Optional stale threshold in milliseconds
+     * @returns Array of removed lock file paths
+     */
+    async cleanup(storiesDir, thresholdMs) {
+        const pattern = path.join(storiesDir, '**/*.lock');
+        const lockFiles = await this.globMatcher.expandPattern(pattern);
+        if (lockFiles.length === 0) {
+            return [];
+        }
+        const removed = [];
+        for (const lockFile of lockFiles) {
+            const storyPath = lockFile.replace(/\.lock$/, '');
+            const stale = await this.isStale(storyPath, thresholdMs);
+            if (stale) {
+                await this.release(storyPath);
+                removed.push(lockFile);
+            }
+        }
+        this.logger.info({ removed: removed.length, scanned: lockFiles.length, storiesDir }, 'Lock cleanup complete');
+        return removed;
+    }
+    /**
+     * List all active locks in a directory with metadata
+     *
+     * Scans the given directory for `.lock` files, reads each lock,
+     * and returns metadata including stale status. Malformed locks are skipped.
+     *
+     * @param storiesDir - Directory to scan for lock files
+     * @returns Array of lock metadata objects
+     */
+    async list(storiesDir) {
+        const pattern = path.join(storiesDir, '**/*.lock');
+        const lockFiles = await this.globMatcher.expandPattern(pattern);
+        if (lockFiles.length === 0) {
+            return [];
+        }
+        const results = [];
+        for (const lockFile of lockFiles) {
+            const storyPath = lockFile.replace(/\.lock$/, '');
+            const lockInfo = await this.getLockInfo(storyPath);
+            if (lockInfo === null) {
+                this.logger.warn({ lockFile }, 'Skipping malformed lock file');
+                continue;
+            }
+            const stale = await this.isStale(storyPath);
+            results.push({ isStale: stale, lock: lockInfo, storyPath });
+        }
+        return results;
+    }
+    /**
+     * List all locks across multiple story directories with stale status
+     *
+     * Scans each directory for `.lock` files, reads and validates each lock,
+     * and returns metadata including stale status. Malformed locks are skipped
+     * with a warning. Results are sorted by started_at descending (newest first).
+     *
+     * @param storyDirs - Array of directories to scan for lock files
+     * @param thresholdMs - Optional stale threshold in milliseconds (default: DEFAULT_STALE_THRESHOLD_MS)
+     * @returns Array of lock metadata with stale boolean, sorted newest first
+     */
+    async listLocks(storyDirs, thresholdMs = LockService.DEFAULT_STALE_THRESHOLD_MS) {
+        const allLocks = [];
+        for (const dir of storyDirs) {
+            const pattern = path.join(dir, '**/*.lock');
+            let lockFiles;
+            try {
+                lockFiles = await this.globMatcher.expandPattern(pattern);
+            }
+            catch {
+                this.logger.warn({ dir }, 'Could not scan directory for locks — skipping');
+                continue;
+            }
+            for (const lockFile of lockFiles) {
+                const storyPath = lockFile.replace(/\.lock$/, '');
+                const lockInfo = await this.getLockInfo(storyPath);
+                if (lockInfo === null) {
+                    this.logger.warn({ lockFile }, 'Skipping malformed lock file in listLocks');
+                    continue;
+                }
+                const stale = await this.isStale(storyPath, thresholdMs);
+                allLocks.push({ ...lockInfo, stale });
+            }
+        }
+        // Sort by started_at descending (newest first)
+        allLocks.sort((a, b) => new Date(b.started_at).getTime() - new Date(a.started_at).getTime());
+        this.logger.info({ count: allLocks.length, dirs: storyDirs.length }, 'listLocks scan complete');
+        return allLocks;
+    }
+    /**
+     * Resolve the lock file path for a given story path
+     *
+     * @param storyPath - Path to the story file
+     * @returns Path to the corresponding lock file
+     */
+    resolveLockPath(storyPath) {
+        return `${storyPath}.lock`;
+    }
+}

package/dist/services/orchestration/locked-story-dispatcher.d.ts

@@ -0,0 +1,40 @@
+/**
+ * LockedStoryDispatcher
+ *
+ * Lock-aware story processing wrapper that acquires a git-backed lock
+ * before processing a story and releases it after completion.
+ * When locking is disabled (lockService is null), acts as a passthrough.
+ */
+import type pino from 'pino';
+import type { DispatchResult } from '../../models/dispatch.js';
+import type { Story } from '../../models/story.js';
+import type { GitBackedLockService } from '../lock/git-backed-lock-service.js';
+/**
+ * Dispatches stories with optional lock coordination
+ *
+ * When a lockService is provided, acquires a lock before processing
+ * and releases it in a finally block. When null, calls processFn directly.
+ */
+export declare class LockedStoryDispatcher {
+    private readonly lockService;
+    private readonly logger;
+    private readonly agentName;
+    private readonly sessionId;
+    /**
+     * Create a new LockedStoryDispatcher
+     *
+     * @param lockService - GitBackedLockService instance, or null to disable locking
+     * @param logger - Pino logger instance
+     * @param agentName - Name of the agent processing stories
+     * @param sessionId - Unique session ID for this pipeline run
+     */
+    constructor(lockService: GitBackedLockService | null, logger: pino.Logger, agentName: string, sessionId: string);
+    /**
+     * Dispatch a story with optional lock coordination
+     *
+     * @param story - Story to process
+     * @param processFn - Async function that processes the story
+     * @returns DispatchResult indicating outcome
+     */
+    dispatch(story: Story, processFn: (story: Story) => Promise<void>): Promise<DispatchResult>;
+}

package/dist/services/orchestration/locked-story-dispatcher.js

@@ -0,0 +1,84 @@
+/**
+ * LockedStoryDispatcher
+ *
+ * Lock-aware story processing wrapper that acquires a git-backed lock
+ * before processing a story and releases it after completion.
+ * When locking is disabled (lockService is null), acts as a passthrough.
+ */
+import { LockConflictError, PushRejectedError } from '../../models/lock.js';
+/**
+ * Dispatches stories with optional lock coordination
+ *
+ * When a lockService is provided, acquires a lock before processing
+ * and releases it in a finally block. When null, calls processFn directly.
+ */
+export class LockedStoryDispatcher {
+    lockService;
+    logger;
+    agentName;
+    sessionId;
+    /**
+     * Create a new LockedStoryDispatcher
+     *
+     * @param lockService - GitBackedLockService instance, or null to disable locking
+     * @param logger - Pino logger instance
+     * @param agentName - Name of the agent processing stories
+     * @param sessionId - Unique session ID for this pipeline run
+     */
+    constructor(lockService, logger, agentName, sessionId) {
+        this.lockService = lockService;
+        this.logger = logger;
+        this.agentName = agentName;
+        this.sessionId = sessionId;
+    }
+    /**
+     * Dispatch a story with optional lock coordination
+     *
+     * @param story - Story to process
+     * @param processFn - Async function that processes the story
+     * @returns DispatchResult indicating outcome
+     */
+    async dispatch(story, processFn) {
+        // Passthrough mode when locking is disabled
+        if (!this.lockService) {
+            await processFn(story);
+            return { status: 'processed' };
+        }
+        const storyPath = story.filePath;
+        const cwd = process.cwd();
+        // Attempt to acquire lock
+        try {
+            await this.lockService.acquire(storyPath, this.agentName, this.sessionId, cwd);
+        }
+        catch (error) {
+            if (error instanceof LockConflictError) {
+                this.logger.info({ story: story.fullNumber, reason: error.message }, 'Story locked, skipping');
+                return { reason: error.message, status: 'skipped' };
+            }
+            if (error instanceof PushRejectedError) {
+                this.logger.warn({ error, storyId: story.fullNumber }, 'Lock acquire push failed, skipping story');
+                return { reason: `Lock acquire push failed for story "${story.fullNumber}"`, status: 'skipped' };
+            }
+            // Catch-all: any other error — skip (never crash the pipeline)
+            const err = error;
+            this.logger.error({ error: err.stack, storyId: story.fullNumber }, 'Unexpected error during lock acquire, skipping story');
+            return { reason: err.message, status: 'skipped' };
+        }
+        // Lock acquired — process and release in finally
+        try {
+            await processFn(story);
+            return { status: 'processed' };
+        }
+        catch (error) {
+            return { reason: error.message, status: 'failed' };
+        }
+        finally {
+            try {
+                await this.lockService.release(storyPath, cwd);
+            }
+            catch (releaseError) {
+                this.logger.error({ error: releaseError.message, story: story.fullNumber }, 'Failed to release lock');
+            }
+        }
+    }
+}

package/dist/services/orchestration/workflow-orchestrator.d.ts

@@ -46,7 +46,9 @@
 import type pino from 'pino';
 import type { InputDetectionResult, WorkflowCallbacks, WorkflowConfig, WorkflowResult } from '../../models/index.js';
 import type { AIProviderRunner } from '../agents/agent-runner.js';
+import type { AgentRunnerFactory } from '../agents/agent-runner-factory.js';
 import type { WorkflowLogger } from '../logging/workflow-logger.js';
+import type { GitBackedLockService } from '../lock/git-backed-lock-service.js';
 import { AssetResolver } from '../file-system/asset-resolver.js';
 import { FileManager } from '../file-system/file-manager.js';
 import { PathResolver } from '../file-system/path-resolver.js';
@@ -80,6 +82,8 @@ export interface InputDetector {
 export interface WorkflowOrchestratorConfig {
     /** Service to execute AI agents (Claude or Gemini) */
     agentRunner: AIProviderRunner;
+    /** Optional factory for discovery-based transport selection (Channel vs subprocess) */
+    agentRunnerFactory?: AgentRunnerFactory;
     /** Optional AssetResolver for three-level path resolution (CLI flag → config → bundled) */
     assetResolver?: AssetResolver;
     /** Service to handle parallel batch processing */
@@ -92,6 +96,8 @@ export interface WorkflowOrchestratorConfig {
     inputDetector: InputDetector;
     /** Logger instance for structured logging */
     logger: pino.Logger;
+    /** Optional GitBackedLockService for multi-session story locking */
+    lockService?: GitBackedLockService;
     /** Optional MCP context injector for tool discovery in agent prompts */
     mcpContextInjector?: McpContextInjector;
     /** Service to resolve file paths from config */
@@ -150,6 +156,7 @@ export interface StoryPromptOptions {
  */
 export declare class WorkflowOrchestrator {
     private readonly agentRunner;
+    private readonly agentRunnerFactory?;
     private readonly assetResolver;
     private readonly batchProcessor;
     private readonly callbacks?;
@@ -157,6 +164,7 @@ export declare class WorkflowOrchestrator {
     private readonly fileManager;
     private readonly fileScaffolder;
     private readonly inputDetector;
+    private readonly lockService?;
     private readonly logger;
     private readonly mcpContextInjector?;
     private readonly pathResolver;
@@ -171,6 +179,29 @@ export declare class WorkflowOrchestrator {
      * @param config - Configuration object containing all service dependencies
      */
     constructor(config: WorkflowOrchestratorConfig);
+    /**
+     * 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.
+     */
+    private getRunner;
+    /**
+     * Build stream callback options from workflow config.
+     * Returns onStream (spinner summary) and/or onStreamVerbose (raw passthrough)
+     * based on config.stream flag.
+     */
+    private getStreamCallbacks;
+    /**
+     * 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
+     */
+    private resolveSessionName;
     /**
      * Execute the complete workflow
      *