@lumenflow/core 3.1.3 → 3.2.1

package/dist/retry-strategy.js

@@ -0,0 +1,286 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * WU-1747: Retry Strategy Module
+ *
+ * Provides exponential backoff retry mechanism with configurable parameters
+ * for wu:done concurrent load resilience.
+ *
+ * Features:
+ * - Configurable max attempts, base delay, multiplier
+ * - Exponential backoff with optional jitter
+ * - Presets for common scenarios (wu_done, recovery)
+ * - Callback hooks for retry events
+ * - Conditional retry based on error type
+ *
+ * @module retry-strategy
+ */
+import { LOG_PREFIX, EMOJI } from './wu-constants.js';
+/**
+ * Error message patterns that are considered retryable for wu:done operations
+ * Exported for test consistency
+ */
+export const RETRYABLE_ERROR_PATTERNS = Object.freeze({
+    FAST_FORWARD: 'fast-forward',
+    NOT_POSSIBLE: 'not possible',
+    CANNOT_LOCK_REF: 'Cannot lock ref',
+    FETCH: 'fetch',
+    PUSH: 'push',
+    ETIMEDOUT: 'ETIMEDOUT',
+    ECONNRESET: 'ECONNRESET',
+});
+/**
+ * @typedef {Object} RetryConfig
+ * @property {number} maxAttempts - Maximum number of attempts (default: 5)
+ * @property {number} baseDelayMs - Base delay in milliseconds (default: 1000)
+ * @property {number} maxDelayMs - Maximum delay cap in milliseconds (default: 30000)
+ * @property {number} multiplier - Exponential multiplier (default: 2)
+ * @property {number} jitter - Jitter factor 0-1 (default: 0.1 for 10%)
+ * @property {function} [shouldRetry] - Optional function(error) => boolean to determine if error is retryable
+ * @property {function} [onRetry] - Optional callback(attempt, error, delay) before each retry
+ */
+/**
+ * Default retry configuration
+ * Balanced for typical wu:done operations
+ */
+export const DEFAULT_RETRY_CONFIG = Object.freeze({
+    maxAttempts: 5,
+    baseDelayMs: 1000,
+    maxDelayMs: 30000,
+    multiplier: 2,
+    jitter: 0.1,
+    shouldRetry: (_error) => true,
+    onRetry: null,
+});
+/**
+ * Pre-configured retry presets for common scenarios
+ */
+export const RETRY_PRESETS = Object.freeze({
+    /**
+     * Preset for wu:done merge operations
+     * Higher attempts and longer delays for handling concurrent load
+     */
+    wu_done: Object.freeze({
+        maxAttempts: 6,
+        baseDelayMs: 2000,
+        maxDelayMs: 60000,
+        multiplier: 2,
+        jitter: 0.15, // 15% jitter to spread concurrent retries
+        shouldRetry: (error) => {
+            // Retry fast-forward failures and network errors using defined patterns
+            const message = error.message || '';
+            return Object.values(RETRYABLE_ERROR_PATTERNS).some((pattern) => message.includes(pattern));
+        },
+        onRetry: null,
+    }),
+    /**
+     * Preset for zombie state recovery
+     * More attempts with shorter delays
+     */
+    recovery: Object.freeze({
+        maxAttempts: 4,
+        baseDelayMs: 500,
+        maxDelayMs: 10000,
+        multiplier: 2,
+        jitter: 0.1,
+        shouldRetry: () => true,
+        onRetry: null,
+    }),
+    /**
+     * Preset for quick operations (file I/O, local git)
+     * Fast retries for transient errors
+     */
+    quick: Object.freeze({
+        maxAttempts: 3,
+        baseDelayMs: 100,
+        maxDelayMs: 2000,
+        multiplier: 2,
+        jitter: 0.05,
+        shouldRetry: () => true,
+        onRetry: null,
+    }),
+});
+/**
+ * Create a retry configuration by merging defaults with custom options
+ *
+ * @param {string|Object} [presetOrOptions] - Preset name or custom options
+ * @param {Object} [options] - Additional options to merge (when first arg is preset name)
+ * @returns {RetryConfig} Complete retry configuration
+ *
+ * @example
+ * // Use defaults
+ * const config = createRetryConfig();
+ *
+ * @example
+ * // Customize defaults
+ * const config = createRetryConfig({ maxAttempts: 10 });
+ *
+ * @example
+ * // Use preset
+ * const config = createRetryConfig('wu_done');
+ *
+ * @example
+ * // Customize preset
+ * const config = createRetryConfig('wu_done', { maxAttempts: 10 });
+ */
+export function createRetryConfig(presetOrOptions, options) {
+    // Determine base config
+    let baseConfig;
+    let customOptions;
+    if (typeof presetOrOptions === 'string') {
+        // First arg is preset name
+        if (!(presetOrOptions in RETRY_PRESETS)) {
+            throw new Error(`Unknown retry preset: ${presetOrOptions}`);
+        }
+        baseConfig = RETRY_PRESETS[presetOrOptions];
+        customOptions = options || {};
+    }
+    else {
+        // First arg is options (or undefined)
+        baseConfig = DEFAULT_RETRY_CONFIG;
+        customOptions = presetOrOptions || {};
+    }
+    // Merge and return
+    // Avoid overriding preset/default values with `undefined` (WU-1756):
+    // callers often pass option keys conditionally, and spreading `undefined`
+    // clobbers required defaults (e.g., maxAttempts) leading to zero-attempt retries.
+    const definedOptions = Object.fromEntries(Object.entries(customOptions).filter(([, value]) => value !== undefined));
+    return {
+        ...baseConfig,
+        ...definedOptions,
+    };
+}
+/**
+ * Calculate the backoff delay for a given attempt number
+ *
+ * Uses exponential backoff formula: baseDelay * (multiplier ^ attempt)
+ * with optional jitter to spread concurrent retry attempts
+ *
+ * @param {number} attempt - Zero-based attempt number (0 = first attempt)
+ * @param {RetryConfig} config - Retry configuration
+ * @returns {number} Delay in milliseconds
+ */
+export function calculateBackoffDelay(attempt, config) {
+    const { baseDelayMs, multiplier, maxDelayMs, jitter } = config;
+    // Exponential backoff: base * multiplier^attempt
+    let delay = baseDelayMs * Math.pow(multiplier, attempt);
+    // Cap at max delay
+    delay = Math.min(delay, maxDelayMs);
+    // Add jitter if enabled (spreads concurrent retries)
+    if (jitter > 0) {
+        // Jitter adds/subtracts random percentage
+        const jitterRange = delay * jitter;
+        const jitterOffset = (Math.random() * 2 - 1) * jitterRange;
+        delay = delay + jitterOffset;
+    }
+    return Math.round(delay);
+}
+/**
+ * Sleep for specified milliseconds
+ *
+ * @param {number} ms - Milliseconds to sleep
+ * @returns {Promise<void>}
+ */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Execute a function with retry logic and exponential backoff
+ *
+ * @template T
+ * @param {function(): Promise<T>} fn - Async function to execute
+ * @param {RetryConfig} [config] - Retry configuration (uses defaults if not provided)
+ * @returns {Promise<T>} Result of successful execution
+ * @throws {Error} Last error if all attempts fail
+ *
+ * @example
+ * const result = await withRetry(
+ *   async () => await mergeBranch(),
+ *   createRetryConfig('wu_done')
+ * );
+ */
+export async function withRetry(fn, config = DEFAULT_RETRY_CONFIG) {
+    const { maxAttempts, shouldRetry, onRetry } = config;
+    let lastError;
+    let attempt = 0;
+    while (attempt < maxAttempts) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            lastError = error;
+            attempt++;
+            // Check if we should retry
+            if (attempt >= maxAttempts) {
+                break; // Max attempts reached
+            }
+            if (!shouldRetry(error)) {
+                break; // Error not retryable
+            }
+            // Calculate delay for next retry
+            const delay = calculateBackoffDelay(attempt - 1, config);
+            // Call onRetry callback if provided
+            if (typeof onRetry === 'function') {
+                onRetry(attempt, error, delay);
+            }
+            // Log retry info
+            console.log(`${LOG_PREFIX.DONE} ${EMOJI.WARNING} Attempt ${attempt}/${maxAttempts} failed: ${error.message}`);
+            console.log(`${LOG_PREFIX.DONE} ${EMOJI.INFO} Retrying in ${delay}ms...`);
+            // Wait before retry
+            await sleep(delay);
+        }
+    }
+    // All attempts failed
+    // Defensive: if a caller passes an invalid config, ensure we throw a useful error.
+    if (!lastError) {
+        throw new Error(`Operation failed: invalid retry configuration (maxAttempts=${maxAttempts})`);
+    }
+    throw new Error(`Operation failed after ${attempt} attempt(s): ${lastError.message}\n` +
+        `Original error: ${lastError.stack || lastError.message}`);
+}
+/**
+ * Higher-order function to wrap a function with retry logic
+ *
+ * @template T
+ * @param {function(...args): Promise<T>} fn - Function to wrap
+ * @param {RetryConfig} [config] - Retry configuration
+ * @returns {function(...args): Promise<T>} Wrapped function with retry logic
+ *
+ * @example
+ * const retryableMerge = withRetryWrapper(mergeBranch, createRetryConfig('wu_done'));
+ * await retryableMerge(branch);
+ */
+export function withRetryWrapper(fn, config = DEFAULT_RETRY_CONFIG) {
+    return async (...args) => {
+        return withRetry(() => fn(...args), config);
+    };
+}
+/**
+ * Determine if an error is a git conflict error (non-retryable)
+ *
+ * @param {Error} error - Error to check
+ * @returns {boolean} True if conflict error
+ */
+export function isConflictError(error) {
+    const message = error.message || '';
+    return (message.includes('conflict') ||
+        message.includes('CONFLICT') ||
+        message.includes('<<<<<<<') ||
+        message.includes('not possible to fast-forward'));
+}
+/**
+ * Determine if an error is a network/transient error (retryable)
+ *
+ * @param {Error} error - Error to check
+ * @returns {boolean} True if likely transient
+ */
+export function isTransientError(error) {
+    const message = error.message || '';
+    return (message.includes('ETIMEDOUT') ||
+        message.includes('ECONNRESET') ||
+        message.includes('ECONNREFUSED') ||
+        message.includes('fetch failed') ||
+        message.includes('network') ||
+        message.includes('timeout'));
+}
+//# sourceMappingURL=retry-strategy.js.map

package/dist/retry-strategy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry-strategy.js","sourceRoot":"","sources":["../src/retry-strategy.ts"],"names":[],"mappings":"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"}

package/dist/rollback-utils.d.ts

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+/**
+ * Rollback Utilities for WU Tooling
+ *
+ * WU-1255: Per-file error tracking for robust rollback operations.
+ * Ensures all files are attempted even if some fail, with clear error reporting.
+ *
+ * WU-1665: Adds rollbackFromPipelineState for state-machine-driven recovery.
+ * Centralized entry point that determines rollback actions from pipeline state.
+ *
+ * @see {@link packages/@lumenflow/cli/src/wu-done.ts} - Consumer (rollbackTransaction function)
+ */
+import type { RollbackScope } from './wu-recovery.js';
+/**
+ * Error entry for failed file restoration
+ */
+interface RollbackError {
+    name: string;
+    path: string;
+    error: string;
+}
+/**
+ * Result of a rollback operation.
+ * Tracks which files were restored and which failed.
+ *
+ * WU-1665: Extended with optional scope metadata for state-machine-driven recovery.
+ *
+ * @class
+ */
+export declare class RollbackResult {
+    /** Names of successfully restored files */
+    restored: string[];
+    /** Failed file restorations */
+    errors: RollbackError[];
+    /** WU-1665: Rollback scope from pipeline state (set by rollbackFromPipelineState) */
+    scope: RollbackScope | null;
+    constructor();
+    /**
+     * Record a successful file restoration.
+     * @param {string} name - File identifier (e.g., 'backlog.md')
+     */
+    addSuccess(name: UnsafeAny): void;
+    /**
+     * Record a failed file restoration.
+     * @param {string} name - File identifier
+     * @param {string} path - Full file path
+     * @param {string} error - Error message
+     */
+    addError(name: UnsafeAny, path: UnsafeAny, error: UnsafeAny): void;
+    /**
+     * Check if all files were restored successfully.
+     * @returns {boolean} True if no errors occurred
+     */
+    get success(): boolean;
+}
+/**
+ * Restore multiple files with per-file error tracking.
+ *
+ * Each file is restored independently - if one fails, subsequent files
+ * are still attempted. This ensures maximum recovery even in partial
+ * failure scenarios.
+ *
+ * @param {Array<{name: string, path: string, content: string}>} filesToRestore - Files to restore
+ * @returns {RollbackResult} Result with restored files and UnsafeAny errors
+ *
+ * @example
+ * const result = rollbackFiles([
+ *   { name: 'backlog.md', path: '/path/to/backlog.md', content: 'original content' },
+ *   { name: 'status.md', path: '/path/to/status.md', content: 'original content' },
+ * ]);
+ *
+ * if (!result.success) {
+ *   console.error('Rollback had errors:', result.errors);
+ * }
+ */
+export declare function rollbackFiles(filesToRestore: UnsafeAny): RollbackResult;
+/**
+ * Delete multiple files with per-file error tracking.
+ *
+ * @param {Array<{name: string, path: string}>} filesToDelete - Files to delete
+ * @returns {RollbackResult} Result with deleted files and UnsafeAny errors
+ */
+export declare function deleteFiles(filesToDelete: UnsafeAny): RollbackResult;
+/**
+ * Input for the centralized pipeline-state-aware rollback.
+ */
+export interface PipelineRollbackInput {
+    /** The pipeline state where failure occurred (from machine context.failedAt) */
+    failedAt: string | null;
+    /** Snapshot map of file paths to original content (from createTransactionSnapshot) */
+    snapshot: Map<string, string | null> | null;
+    /** Files to restore via the legacy per-file rollback path */
+    filesToRestore: Array<{
+        name: string;
+        path: string;
+        content: string;
+    }>;
+}
+/**
+ * WU-1665: Centralized rollback entry point driven by pipeline state.
+ *
+ * Determines the rollback scope from the failedAt state, then executes
+ * the appropriate rollback actions. This replaces the scattered rollback
+ * logic that was previously duplicated across wu-recovery.ts, wu-transaction.ts,
+ * and the CLI orchestrator.
+ *
+ * Scope determination:
+ * - validating/preparing/gating: no-op (nothing was written)
+ * - committing: restore files from snapshot or filesToRestore
+ * - merging/pushing: restore files + flag branch rollback needed
+ * - cleaningUp: flag worktree cleanup only (push already succeeded)
+ *
+ * @param {PipelineRollbackInput} input - Rollback inputs
+ * @returns {RollbackResult} Result with scope metadata and file restoration details
+ */
+export declare function rollbackFromPipelineState(input: PipelineRollbackInput): RollbackResult;
+/**
+ * WU-1665: Compute rollback scope from pipeline failedAt state.
+ *
+ * Pure function: given the same failedAt, always returns the same scope.
+ * This is the canonical scope determination used by both
+ * StateMachineRecoveryManager.getRollbackScope() and rollbackFromPipelineState().
+ *
+ * @param {string|null} failedAt - Pipeline state where failure occurred
+ * @returns {RollbackScope} Rollback scope
+ */
+export declare function computeRollbackScope(failedAt: string | null): RollbackScope;
+export {};
+//# sourceMappingURL=rollback-utils.d.ts.map

package/dist/rollback-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rollback-utils.d.ts","sourceRoot":"","sources":["../src/rollback-utils.ts"],"names":[],"mappings":";AAGA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEtD;;GAEG;AACH,UAAU,aAAa;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;GAOG;AACH,qBAAa,cAAc;IACzB,2CAA2C;IAC3C,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,+BAA+B;IAC/B,MAAM,EAAE,aAAa,EAAE,CAAC;IACxB,qFAAqF;IACrF,KAAK,EAAE,aAAa,GAAG,IAAI,CAAC;;IAQ5B;;;OAGG;IACH,UAAU,CAAC,IAAI,EAAE,SAAS;IAI1B;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS;IAI3D;;;OAGG;IACH,IAAI,OAAO,YAEV;CACF;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,aAAa,CAAC,cAAc,EAAE,SAAS,kBActD;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,aAAa,EAAE,SAAS,kBAcnD;AAMD;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,gFAAgF;IAChF,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,sFAAsF;IACtF,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC;IAC5C,6DAA6D;IAC7D,cAAc,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACxE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,qBAAqB,GAAG,cAAc,CA2CtF;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,aAAa,CAkC3E"}

package/dist/rollback-utils.js

@@ -0,0 +1,217 @@
+#!/usr/bin/env node
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * Rollback Utilities for WU Tooling
+ *
+ * WU-1255: Per-file error tracking for robust rollback operations.
+ * Ensures all files are attempted even if some fail, with clear error reporting.
+ *
+ * WU-1665: Adds rollbackFromPipelineState for state-machine-driven recovery.
+ * Centralized entry point that determines rollback actions from pipeline state.
+ *
+ * @see {@link packages/@lumenflow/cli/src/wu-done.ts} - Consumer (rollbackTransaction function)
+ */
+import { writeFileSync, unlinkSync } from 'node:fs';
+/**
+ * Result of a rollback operation.
+ * Tracks which files were restored and which failed.
+ *
+ * WU-1665: Extended with optional scope metadata for state-machine-driven recovery.
+ *
+ * @class
+ */
+export class RollbackResult {
+    /** Names of successfully restored files */
+    restored;
+    /** Failed file restorations */
+    errors;
+    /** WU-1665: Rollback scope from pipeline state (set by rollbackFromPipelineState) */
+    scope;
+    constructor() {
+        this.restored = [];
+        this.errors = [];
+        this.scope = null;
+    }
+    /**
+     * Record a successful file restoration.
+     * @param {string} name - File identifier (e.g., 'backlog.md')
+     */
+    addSuccess(name) {
+        this.restored.push(name);
+    }
+    /**
+     * Record a failed file restoration.
+     * @param {string} name - File identifier
+     * @param {string} path - Full file path
+     * @param {string} error - Error message
+     */
+    addError(name, path, error) {
+        this.errors.push({ name, path, error });
+    }
+    /**
+     * Check if all files were restored successfully.
+     * @returns {boolean} True if no errors occurred
+     */
+    get success() {
+        return this.errors.length === 0;
+    }
+}
+/**
+ * Restore multiple files with per-file error tracking.
+ *
+ * Each file is restored independently - if one fails, subsequent files
+ * are still attempted. This ensures maximum recovery even in partial
+ * failure scenarios.
+ *
+ * @param {Array<{name: string, path: string, content: string}>} filesToRestore - Files to restore
+ * @returns {RollbackResult} Result with restored files and UnsafeAny errors
+ *
+ * @example
+ * const result = rollbackFiles([
+ *   { name: 'backlog.md', path: '/path/to/backlog.md', content: 'original content' },
+ *   { name: 'status.md', path: '/path/to/status.md', content: 'original content' },
+ * ]);
+ *
+ * if (!result.success) {
+ *   console.error('Rollback had errors:', result.errors);
+ * }
+ */
+export function rollbackFiles(filesToRestore) {
+    const result = new RollbackResult();
+    for (const file of filesToRestore) {
+        try {
+            writeFileSync(file.path, file.content, { encoding: 'utf-8' });
+            result.addSuccess(file.name);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            result.addError(file.name, file.path, message);
+        }
+    }
+    return result;
+}
+/**
+ * Delete multiple files with per-file error tracking.
+ *
+ * @param {Array<{name: string, path: string}>} filesToDelete - Files to delete
+ * @returns {RollbackResult} Result with deleted files and UnsafeAny errors
+ */
+export function deleteFiles(filesToDelete) {
+    const result = new RollbackResult();
+    for (const file of filesToDelete) {
+        try {
+            unlinkSync(file.path);
+            result.addSuccess(file.name);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            result.addError(file.name, file.path, message);
+        }
+    }
+    return result;
+}
+/**
+ * WU-1665: Centralized rollback entry point driven by pipeline state.
+ *
+ * Determines the rollback scope from the failedAt state, then executes
+ * the appropriate rollback actions. This replaces the scattered rollback
+ * logic that was previously duplicated across wu-recovery.ts, wu-transaction.ts,
+ * and the CLI orchestrator.
+ *
+ * Scope determination:
+ * - validating/preparing/gating: no-op (nothing was written)
+ * - committing: restore files from snapshot or filesToRestore
+ * - merging/pushing: restore files + flag branch rollback needed
+ * - cleaningUp: flag worktree cleanup only (push already succeeded)
+ *
+ * @param {PipelineRollbackInput} input - Rollback inputs
+ * @returns {RollbackResult} Result with scope metadata and file restoration details
+ */
+export function rollbackFromPipelineState(input) {
+    const { failedAt, snapshot, filesToRestore } = input;
+    const result = new RollbackResult();
+    // Determine scope from failedAt state (same logic as StateMachineRecoveryManager)
+    const scope = computeRollbackScope(failedAt);
+    result.scope = scope;
+    // If no file restoration needed, return early with scope metadata
+    if (!scope.snapshotRestore) {
+        return result;
+    }
+    // Restore files using snapshot if available, otherwise fall back to filesToRestore
+    if (snapshot && snapshot.size > 0) {
+        for (const [filePath, content] of snapshot) {
+            try {
+                if (content === null) {
+                    // File didn't exist before - delete if created
+                    try {
+                        unlinkSync(filePath);
+                        result.addSuccess(filePath);
+                    }
+                    catch {
+                        // File might not exist, which is fine
+                        result.addSuccess(filePath);
+                    }
+                }
+                else {
+                    writeFileSync(filePath, content, { encoding: 'utf-8' });
+                    result.addSuccess(filePath);
+                }
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                result.addError(filePath, filePath, message);
+            }
+        }
+    }
+    else if (filesToRestore.length > 0) {
+        // Legacy-compatible file restoration
+        const legacyResult = rollbackFiles(filesToRestore);
+        result.restored.push(...legacyResult.restored);
+        result.errors.push(...legacyResult.errors);
+    }
+    return result;
+}
+/**
+ * WU-1665: Compute rollback scope from pipeline failedAt state.
+ *
+ * Pure function: given the same failedAt, always returns the same scope.
+ * This is the canonical scope determination used by both
+ * StateMachineRecoveryManager.getRollbackScope() and rollbackFromPipelineState().
+ *
+ * @param {string|null} failedAt - Pipeline state where failure occurred
+ * @returns {RollbackScope} Rollback scope
+ */
+export function computeRollbackScope(failedAt) {
+    // Pre-write states: nothing to roll back
+    if (!failedAt || failedAt === 'validating' || failedAt === 'preparing' || failedAt === 'gating') {
+        return {
+            snapshotRestore: false,
+            branchRollback: false,
+            worktreeCleanup: false,
+        };
+    }
+    // Post-push state: push already succeeded, only cleanup remains
+    if (failedAt === 'cleaningUp') {
+        return {
+            snapshotRestore: false,
+            branchRollback: false,
+            worktreeCleanup: true,
+        };
+    }
+    // Commit-phase failures: files written, need snapshot restore
+    if (failedAt === 'committing') {
+        return {
+            snapshotRestore: true,
+            branchRollback: false,
+            worktreeCleanup: false,
+        };
+    }
+    // Merge/push phase failures: committed + potentially merged, need full rollback
+    return {
+        snapshotRestore: true,
+        branchRollback: true,
+        worktreeCleanup: false,
+    };
+}
+//# sourceMappingURL=rollback-utils.js.map

package/dist/rollback-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rollback-utils.js","sourceRoot":"","sources":["../src/rollback-utils.ts"],"names":[],"mappings":";AACA,iCAAiC;AACjC,yCAAyC;AACzC;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAYpD;;;;;;;GAOG;AACH,MAAM,OAAO,cAAc;IACzB,2CAA2C;IAC3C,QAAQ,CAAW;IACnB,+BAA+B;IAC/B,MAAM,CAAkB;IACxB,qFAAqF;IACrF,KAAK,CAAuB;IAE5B;QACE,IAAI,CAAC,QAAQ,GAAG,EAAE,CAAC;QACnB,IAAI,CAAC,MAAM,GAAG,EAAE,CAAC;QACjB,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;IACpB,CAAC;IAED;;;OAGG;IACH,UAAU,CAAC,IAAe;QACxB,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC3B,CAAC;IAED;;;;;OAKG;IACH,QAAQ,CAAC,IAAe,EAAE,IAAe,EAAE,KAAgB;QACzD,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAC1C,CAAC;IAED;;;OAGG;IACH,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC;IAClC,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,aAAa,CAAC,cAAyB;IACrD,MAAM,MAAM,GAAG,IAAI,cAAc,EAAE,CAAC;IAEpC,KAAK,MAAM,IAAI,IAAI,cAAc,EAAE,CAAC;QAClC,IAAI,CAAC;YACH,aAAa,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC;YAC9D,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC/B,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACjE,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QACjD,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,aAAwB;IAClD,MAAM,MAAM,GAAG,IAAI,cAAc,EAAE,CAAC;IAEpC,KAAK,MAAM,IAAI,IAAI,aAAa,EAAE,CAAC;QACjC,IAAI,CAAC;YACH,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACtB,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC/B,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACjE,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QACjD,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAkBD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,yBAAyB,CAAC,KAA4B;IACpE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,cAAc,EAAE,GAAG,KAAK,CAAC;IACrD,MAAM,MAAM,GAAG,IAAI,cAAc,EAAE,CAAC;IAEpC,kFAAkF;IAClF,MAAM,KAAK,GAAG,oBAAoB,CAAC,QAAQ,CAAC,CAAC;IAC7C,MAAM,CAAC,KAAK,GAAG,KAAK,CAAC;IAErB,kEAAkE;IAClE,IAAI,CAAC,KAAK,CAAC,eAAe,EAAE,CAAC;QAC3B,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,mFAAmF;IACnF,IAAI,QAAQ,IAAI,QAAQ,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC;QAClC,KAAK,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,IAAI,QAAQ,EAAE,CAAC;YAC3C,IAAI,CAAC;gBACH,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;oBACrB,+CAA+C;oBAC/C,IAAI,CAAC;wBACH,UAAU,CAAC,QAAQ,CAAC,CAAC;wBACrB,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;oBAC9B,CAAC;oBAAC,MAAM,CAAC;wBACP,sCAAsC;wBACtC,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;oBAC9B,CAAC;gBACH,CAAC;qBAAM,CAAC;oBACN,aAAa,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC;oBACxD,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;gBAC9B,CAAC;YACH,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;gBACjE,MAAM,CAAC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;YAC/C,CAAC;QACH,CAAC;IACH,CAAC;SAAM,IAAI,cAAc,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACrC,qCAAqC;QACrC,MAAM,YAAY,GAAG,aAAa,CAAC,cAAc,CAAC,CAAC;QACnD,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAC;QAC/C,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;IAC7C,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,oBAAoB,CAAC,QAAuB;IAC1D,yCAAyC;IACzC,IAAI,CAAC,QAAQ,IAAI,QAAQ,KAAK,YAAY,IAAI,QAAQ,KAAK,WAAW,IAAI,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAChG,OAAO;YACL,eAAe,EAAE,KAAK;YACtB,cAAc,EAAE,KAAK;YACrB,eAAe,EAAE,KAAK;SACvB,CAAC;IACJ,CAAC;IAED,gEAAgE;IAChE,IAAI,QAAQ,KAAK,YAAY,EAAE,CAAC;QAC9B,OAAO;YACL,eAAe,EAAE,KAAK;YACtB,cAAc,EAAE,KAAK;YACrB,eAAe,EAAE,IAAI;SACtB,CAAC;IACJ,CAAC;IAED,8DAA8D;IAC9D,IAAI,QAAQ,KAAK,YAAY,EAAE,CAAC;QAC9B,OAAO;YACL,eAAe,EAAE,IAAI;YACrB,cAAc,EAAE,KAAK;YACrB,eAAe,EAAE,KAAK;SACvB,CAAC;IACJ,CAAC;IAED,gFAAgF;IAChF,OAAO;QACL,eAAe,EAAE,IAAI;QACrB,cAAc,EAAE,IAAI;QACpB,eAAe,EAAE,KAAK;KACvB,CAAC;AACJ,CAAC"}

package/dist/sandbox-allowlist.d.ts

@@ -0,0 +1,16 @@
+export interface SandboxAllowlistEntry {
+    originalPath: string;
+    normalizedPath: string;
+    canonicalPath: string;
+}
+export interface SandboxAllowlist {
+    projectRoot: string;
+    writableRoots: SandboxAllowlistEntry[];
+}
+export interface BuildSandboxAllowlistInput {
+    projectRoot: string;
+    writableRoots: string[];
+}
+export declare function buildSandboxAllowlist(input: BuildSandboxAllowlistInput): SandboxAllowlist;
+export declare function isWritePathAllowed(allowlist: SandboxAllowlist, targetPath: string): boolean;
+//# sourceMappingURL=sandbox-allowlist.d.ts.map

package/dist/sandbox-allowlist.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-allowlist.d.ts","sourceRoot":"","sources":["../src/sandbox-allowlist.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,qBAAqB;IACpC,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,qBAAqB,EAAE,CAAC;CACxC;AAED,MAAM,WAAW,0BAA0B;IACzC,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB;AAkED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,0BAA0B,GAAG,gBAAgB,CAgBzF;AAED,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAa3F"}