@lumenflow/core 2.4.0 → 2.5.1

package/dist/micro-worktree.d.ts

@@ -28,6 +28,7 @@
  * @see {@link packages/@lumenflow/cli/src/initiative-create.ts} - Initiative creation (WU-1439)
  */
 import type { GitAdapter } from './git-adapter.js';
+import type { PushRetryConfig } from './lumenflow-config-schema.js';
 /**
  * Context passed to the execute function in withMicroWorktree
  */
@@ -81,8 +82,17 @@ export declare const MAX_MERGE_RETRIES = 3;
  * WU-1179: When push fails due to race condition (origin advanced while we
  * were working), rollback local main to origin/main and retry.
  * Each retry: fetch -> rebase temp branch -> re-merge -> push.
+ *
+ * @deprecated Use DEFAULT_PUSH_RETRY_CONFIG.retries instead (WU-1332)
  */
 export declare const MAX_PUSH_RETRIES = 3;
+/**
+ * WU-1332: Default push retry configuration
+ *
+ * Provides sensible defaults for micro-worktree push operations.
+ * Can be overridden via .lumenflow.config.yaml git.push_retry section.
+ */
+export declare const DEFAULT_PUSH_RETRY_CONFIG: PushRetryConfig;
 /**
  * Environment variable name for LUMENFLOW_FORCE bypass
  *
@@ -101,6 +111,102 @@ export declare const LUMENFLOW_FORCE_REASON_ENV = "LUMENFLOW_FORCE_REASON";
  * Extracted to constant to satisfy sonarjs/no-duplicate-string rule.
  */
 export declare const DEFAULT_LOG_PREFIX = "[micro-wt]";
+/**
+ * WU-1336: Typed error for retry exhaustion in micro-worktree operations
+ *
+ * Thrown when push retries are exhausted due to race conditions with parallel agents.
+ * CLI commands should use `isRetryExhaustionError` to detect this error type and
+ * `formatRetryExhaustionError` to generate actionable user-facing messages.
+ *
+ * This centralizes retry exhaustion handling so CLI commands do not need to
+ * duplicate detection logic or error formatting.
+ *
+ * @example
+ * ```typescript
+ * import { RetryExhaustionError, isRetryExhaustionError, formatRetryExhaustionError } from '@lumenflow/core';
+ *
+ * try {
+ *   await withMicroWorktree({ ... });
+ * } catch (error) {
+ *   if (isRetryExhaustionError(error)) {
+ *     console.error(formatRetryExhaustionError(error, { command: 'pnpm initiative:add-wu ...' }));
+ *   } else {
+ *     throw error;
+ *   }
+ * }
+ * ```
+ */
+export declare class RetryExhaustionError extends Error {
+    /** Name of the error class (for instanceof checks across module boundaries) */
+    readonly name = "RetryExhaustionError";
+    /** Operation that was being performed (e.g., 'initiative-add-wu') */
+    readonly operation: string;
+    /** Number of retry attempts that were exhausted */
+    readonly retries: number;
+    constructor(operation: string, retries: number);
+}
+/**
+ * WU-1336: Options for formatting retry exhaustion error messages
+ */
+export interface FormatRetryExhaustionOptions {
+    /** Command to suggest for retrying (e.g., 'pnpm initiative:add-wu --wu WU-123 --initiative INIT-001') */
+    command: string;
+}
+/**
+ * WU-1336: Type guard to check if an error is a retry exhaustion error
+ *
+ * Detects both the typed `RetryExhaustionError` class and legacy error messages
+ * that match the "Push failed after N attempts" pattern.
+ *
+ * @param {unknown} error - Error to check
+ * @returns {boolean} True if this is a retry exhaustion error
+ *
+ * @example
+ * ```typescript
+ * if (isRetryExhaustionError(error)) {
+ *   // Handle retry exhaustion
+ * }
+ * ```
+ */
+export declare function isRetryExhaustionError(error: unknown): error is Error;
+/**
+ * WU-1336: Format retry exhaustion error with actionable next steps
+ *
+ * When push retries are exhausted, provides clear guidance on how to proceed.
+ * CLI commands should use this instead of duplicating error formatting logic.
+ *
+ * @param {Error} error - The retry exhaustion error
+ * @param {FormatRetryExhaustionOptions} options - Formatting options
+ * @returns {string} Formatted error message with next steps
+ *
+ * @example
+ * ```typescript
+ * const message = formatRetryExhaustionError(error, {
+ *   command: 'pnpm initiative:add-wu --wu WU-123 --initiative INIT-001',
+ * });
+ * console.error(message);
+ * ```
+ */
+export declare function formatRetryExhaustionError(error: Error, options: FormatRetryExhaustionOptions): string;
+/**
+ * WU-1308: Check if remote operations should be skipped based on git.requireRemote config
+ *
+ * When git.requireRemote is false, micro-worktree operations skip:
+ * - Fetching origin/main before starting
+ * - Pushing to origin/main after completion
+ *
+ * This enables local-only development without a remote repository.
+ *
+ * @returns {boolean} True if remote operations should be skipped (requireRemote=false)
+ *
+ * @example
+ * ```yaml
+ * # .lumenflow.config.yaml
+ * git:
+ *   requireRemote: false  # Enable local-only mode
+ * ```
+ */
+export declare function shouldSkipRemoteOperations(): boolean;
 /**
  * Temp branch prefix for micro-worktree operations
  *
@@ -200,11 +306,16 @@ export declare function mergeWithRetry(tempBranchName: string, microWorktreePath
  * Push to origin/main with retry logic for race conditions
  *
  * WU-1179: When push fails because origin/main advanced (race condition with
- * parallel agents), this function rolls back local main to origin/main and
- * retries the full sequence: fetch -> rebase temp branch -> re-merge -> push.
+ * parallel agents), this function retries with fetch and rebase.
+ *
+ * WU-1348: The retry logic no longer resets the main checkout. Instead, it:
+ * 1. Fetches origin/main to get latest remote state
+ * 2. Rebases the temp branch onto origin/main (in the micro-worktree)
+ * 3. Re-merges the rebased temp branch to local main (ff-only)
+ * 4. Retries the push
  *
- * This prevents the scenario where local main is left diverged from origin
- * after a push failure.
+ * This preserves micro-worktree isolation - the main checkout files are never
+ * hard-reset, preventing file flash and preserving any uncommitted work.
  *
  * @param {Object} mainGit - GitAdapter instance for main checkout
  * @param {Object} worktreeGit - GitAdapter instance for micro-worktree
@@ -215,6 +326,32 @@ export declare function mergeWithRetry(tempBranchName: string, microWorktreePath
  * @throws {Error} If push fails after all retries
  */
 export declare function pushWithRetry(mainGit: GitAdapter, worktreeGit: GitAdapter, remote: string, branch: string, tempBranchName: string, logPrefix?: string): Promise<void>;
+/**
+ * WU-1332: Push to origin with configurable retry using p-retry
+ *
+ * Enhanced version of pushWithRetry that uses p-retry for exponential backoff
+ * and supports configuration via PushRetryConfig. When push fails due to
+ * non-fast-forward (origin moved), automatically rebases and retries.
+ *
+ * WU-1348: The retry logic no longer resets the main checkout. Instead, it:
+ * 1. Fetches origin/main to get latest remote state
+ * 2. Rebases the temp branch onto origin/main (in the micro-worktree)
+ * 3. Re-merges the rebased temp branch to local main (ff-only)
+ * 4. Retries the push
+ *
+ * This preserves micro-worktree isolation - the main checkout files are never
+ * hard-reset, preventing file flash and preserving any uncommitted work.
+ *
+ * @param {Object} mainGit - GitAdapter instance for main checkout
+ * @param {Object} worktreeGit - GitAdapter instance for micro-worktree
+ * @param {string} remote - Remote name (e.g., 'origin')
+ * @param {string} branch - Branch name (e.g., 'main')
+ * @param {string} tempBranchName - Temp branch that was merged (for rebase)
+ * @param {string} logPrefix - Log prefix for console output
+ * @param {PushRetryConfig} config - Push retry configuration
+ * @throws {Error} If push fails after all retries or if retry is disabled
+ */
+export declare function pushWithRetryConfig(mainGit: GitAdapter, worktreeGit: GitAdapter, remote: string, branch: string, tempBranchName: string, logPrefix?: string, config?: PushRetryConfig): Promise<void>;
 /**
  * Push using refspec with LUMENFLOW_FORCE to bypass pre-push hooks
  *
@@ -234,6 +371,33 @@ export declare function pushWithRetry(mainGit: GitAdapter, worktreeGit: GitAdapt
  * @throws {Error} If push fails (env vars still restored)
  */
 export declare function pushRefspecWithForce(gitAdapter: GitAdapter, remote: string, localRef: string, remoteRef: string, reason: string): Promise<void>;
+/**
+ * WU-1337: Push using refspec with LUMENFLOW_FORCE and retry logic
+ *
+ * Enhanced version of pushRefspecWithForce that adds retry with rebase
+ * on non-fast-forward errors. Uses p-retry for exponential backoff and
+ * respects git.push_retry configuration.
+ *
+ * On each retry:
+ * 1. Fetch origin/main to get latest state
+ * 2. Rebase the temp branch onto the updated main
+ * 3. Retry the push with LUMENFLOW_FORCE
+ *
+ * This is used by pushOnly mode in withMicroWorktree to handle race conditions
+ * when multiple agents are pushing to origin/main concurrently.
+ *
+ * @param {GitAdapter} gitWorktree - GitAdapter instance for the worktree (for rebase)
+ * @param {GitAdapter} mainGit - GitAdapter instance for main checkout (for fetch)
+ * @param {string} remote - Remote name (e.g., 'origin')
+ * @param {string} localRef - Local ref to push (e.g., 'tmp/wu-claim/wu-123')
+ * @param {string} remoteRef - Remote ref to update (e.g., 'main')
+ * @param {string} reason - Audit reason for the LUMENFLOW_FORCE bypass
+ * @param {string} logPrefix - Log prefix for console output
+ * @param {PushRetryConfig} config - Push retry configuration
+ * @returns {Promise<void>}
+ * @throws {RetryExhaustionError} If push fails after all retries
+ */
+export declare function pushRefspecWithRetry(gitWorktree: GitAdapter, mainGit: GitAdapter, remote: string, localRef: string, remoteRef: string, reason: string, logPrefix?: string, config?: PushRetryConfig): Promise<void>;
 /**
  * Execute an operation in a micro-worktree with full isolation
  *
@@ -243,6 +407,7 @@ export declare function pushRefspecWithForce(gitAdapter: GitAdapter, remote: str
  *
  * WU-1435: Added pushOnly option to keep local main pristine.
  * WU-2237: Added pre-creation cleanup of orphaned temp branches/worktrees.
+ * WU-1337: Push-only path now uses retry with rebase.
  *
  * @param {Object} options - Options for the operation
  * @param {string} options.operation - Operation name (e.g., 'wu-create', 'wu-edit')

package/dist/micro-worktree.js

@@ -32,7 +32,9 @@ import { existsSync, rmSync, mkdtempSync } from 'node:fs';
 import { execSync } from 'node:child_process';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+import pRetry from 'p-retry';
 import { BRANCHES, REMOTES, GIT_REFS, PKG_MANAGER, SCRIPTS, PRETTIER_FLAGS, STDIO_MODES, } from './wu-constants.js';
+import { getConfig } from './lumenflow-config.js';
 /**
  * Maximum retry attempts for ff-only merge when main moves
  *
@@ -46,8 +48,23 @@ export const MAX_MERGE_RETRIES = 3;
  * WU-1179: When push fails due to race condition (origin advanced while we
  * were working), rollback local main to origin/main and retry.
  * Each retry: fetch -> rebase temp branch -> re-merge -> push.
+ *
+ * @deprecated Use DEFAULT_PUSH_RETRY_CONFIG.retries instead (WU-1332)
  */
 export const MAX_PUSH_RETRIES = 3;
+/**
+ * WU-1332: Default push retry configuration
+ *
+ * Provides sensible defaults for micro-worktree push operations.
+ * Can be overridden via .lumenflow.config.yaml git.push_retry section.
+ */
+export const DEFAULT_PUSH_RETRY_CONFIG = {
+    enabled: true,
+    retries: 3,
+    min_delay_ms: 100,
+    max_delay_ms: 1000,
+    jitter: true,
+};
 /**
  * Environment variable name for LUMENFLOW_FORCE bypass
  *
@@ -66,6 +83,130 @@ export const LUMENFLOW_FORCE_REASON_ENV = 'LUMENFLOW_FORCE_REASON';
  * Extracted to constant to satisfy sonarjs/no-duplicate-string rule.
  */
 export const DEFAULT_LOG_PREFIX = '[micro-wt]';
+/**
+ * WU-1336: Pattern to detect retry exhaustion errors from error messages
+ *
+ * Matches error messages like "Push failed after N attempts"
+ * Used for backwards compatibility with legacy error messages.
+ */
+const RETRY_EXHAUSTION_PATTERN = /Push failed after \d+ attempts/;
+/**
+ * WU-1336: Typed error for retry exhaustion in micro-worktree operations
+ *
+ * Thrown when push retries are exhausted due to race conditions with parallel agents.
+ * CLI commands should use `isRetryExhaustionError` to detect this error type and
+ * `formatRetryExhaustionError` to generate actionable user-facing messages.
+ *
+ * This centralizes retry exhaustion handling so CLI commands do not need to
+ * duplicate detection logic or error formatting.
+ *
+ * @example
+ * ```typescript
+ * import { RetryExhaustionError, isRetryExhaustionError, formatRetryExhaustionError } from '@lumenflow/core';
+ *
+ * try {
+ *   await withMicroWorktree({ ... });
+ * } catch (error) {
+ *   if (isRetryExhaustionError(error)) {
+ *     console.error(formatRetryExhaustionError(error, { command: 'pnpm initiative:add-wu ...' }));
+ *   } else {
+ *     throw error;
+ *   }
+ * }
+ * ```
+ */
+export class RetryExhaustionError extends Error {
+    /** Name of the error class (for instanceof checks across module boundaries) */
+    name = 'RetryExhaustionError';
+    /** Operation that was being performed (e.g., 'initiative-add-wu') */
+    operation;
+    /** Number of retry attempts that were exhausted */
+    retries;
+    constructor(operation, retries) {
+        super(`Push failed after ${retries} attempts. ` +
+            `Origin main may have significant traffic during ${operation}.`);
+        this.operation = operation;
+        this.retries = retries;
+        // Maintain proper prototype chain for instanceof checks
+        Object.setPrototypeOf(this, RetryExhaustionError.prototype);
+    }
+}
+/**
+ * WU-1336: Type guard to check if an error is a retry exhaustion error
+ *
+ * Detects both the typed `RetryExhaustionError` class and legacy error messages
+ * that match the "Push failed after N attempts" pattern.
+ *
+ * @param {unknown} error - Error to check
+ * @returns {boolean} True if this is a retry exhaustion error
+ *
+ * @example
+ * ```typescript
+ * if (isRetryExhaustionError(error)) {
+ *   // Handle retry exhaustion
+ * }
+ * ```
+ */
+export function isRetryExhaustionError(error) {
+    if (error instanceof RetryExhaustionError) {
+        return true;
+    }
+    // Also detect legacy error messages for backwards compatibility
+    if (error instanceof Error) {
+        return RETRY_EXHAUSTION_PATTERN.test(error.message);
+    }
+    return false;
+}
+/**
+ * WU-1336: Format retry exhaustion error with actionable next steps
+ *
+ * When push retries are exhausted, provides clear guidance on how to proceed.
+ * CLI commands should use this instead of duplicating error formatting logic.
+ *
+ * @param {Error} error - The retry exhaustion error
+ * @param {FormatRetryExhaustionOptions} options - Formatting options
+ * @returns {string} Formatted error message with next steps
+ *
+ * @example
+ * ```typescript
+ * const message = formatRetryExhaustionError(error, {
+ *   command: 'pnpm initiative:add-wu --wu WU-123 --initiative INIT-001',
+ * });
+ * console.error(message);
+ * ```
+ */
+export function formatRetryExhaustionError(error, options) {
+    const { command } = options;
+    return (`${error.message}\n\n` +
+        `Next steps:\n` +
+        `  1. Wait a few seconds and retry the operation:\n` +
+        `     ${command}\n` +
+        `  2. If the issue persists, check if another agent is rapidly pushing changes\n` +
+        `  3. Consider increasing git.push_retry.retries in .lumenflow.config.yaml`);
+}
+/**
+ * WU-1308: Check if remote operations should be skipped based on git.requireRemote config
+ *
+ * When git.requireRemote is false, micro-worktree operations skip:
+ * - Fetching origin/main before starting
+ * - Pushing to origin/main after completion
+ *
+ * This enables local-only development without a remote repository.
+ *
+ * @returns {boolean} True if remote operations should be skipped (requireRemote=false)
+ *
+ * @example
+ * ```yaml
+ * # .lumenflow.config.yaml
+ * git:
+ *   requireRemote: false  # Enable local-only mode
+ * ```
+ */
+export function shouldSkipRemoteOperations() {
+    const config = getConfig();
+    // Default is requireRemote=true, so only skip if explicitly set to false
+    return config.git.requireRemote === false;
+}
 /**
  * Temp branch prefix for micro-worktree operations
  *
@@ -377,11 +518,16 @@ export async function mergeWithRetry(tempBranchName, microWorktreePath, logPrefi
  * Push to origin/main with retry logic for race conditions
  *
  * WU-1179: When push fails because origin/main advanced (race condition with
- * parallel agents), this function rolls back local main to origin/main and
- * retries the full sequence: fetch -> rebase temp branch -> re-merge -> push.
+ * parallel agents), this function retries with fetch and rebase.
  *
- * This prevents the scenario where local main is left diverged from origin
- * after a push failure.
+ * WU-1348: The retry logic no longer resets the main checkout. Instead, it:
+ * 1. Fetches origin/main to get latest remote state
+ * 2. Rebases the temp branch onto origin/main (in the micro-worktree)
+ * 3. Re-merges the rebased temp branch to local main (ff-only)
+ * 4. Retries the push
+ *
+ * This preserves micro-worktree isolation - the main checkout files are never
+ * hard-reset, preventing file flash and preserving any uncommitted work.
  *
  * @param {Object} mainGit - GitAdapter instance for main checkout
  * @param {Object} worktreeGit - GitAdapter instance for micro-worktree
@@ -392,41 +538,119 @@ export async function mergeWithRetry(tempBranchName, microWorktreePath, logPrefi
  * @throws {Error} If push fails after all retries
  */
 export async function pushWithRetry(mainGit, worktreeGit, remote, branch, tempBranchName, logPrefix = DEFAULT_LOG_PREFIX) {
-    for (let attempt = 1; attempt <= MAX_PUSH_RETRIES; attempt++) {
+    // eslint-disable-next-line sonarjs/deprecation -- Using deprecated constant for backwards compatibility
+    const maxRetries = MAX_PUSH_RETRIES;
+    for (let attempt = 1; attempt <= maxRetries; attempt++) {
         try {
-            console.log(`${logPrefix} Pushing to ${remote}/${branch} (attempt ${attempt}/${MAX_PUSH_RETRIES})...`);
+            console.log(`${logPrefix} Pushing to ${remote}/${branch} (attempt ${attempt}/${maxRetries})...`);
             await mainGit.push(remote, branch);
             console.log(`${logPrefix} ✅ Pushed to ${remote}/${branch}`);
             return;
         }
         catch (pushErr) {
-            if (attempt < MAX_PUSH_RETRIES) {
-                console.log(`${logPrefix} ⚠️  Push failed (origin moved). Rolling back and retrying...`);
-                // Step 1: Rollback local main to origin/main
-                console.log(`${logPrefix} Rolling back local ${branch} to ${remote}/${branch}...`);
-                await mainGit.reset(`${remote}/${branch}`, { hard: true });
-                // Step 2: Fetch latest origin/main
+            if (attempt < maxRetries) {
+                console.log(`${logPrefix} ⚠️  Push failed (origin moved). Fetching and rebasing before retry...`);
+                // WU-1348: Do NOT reset main checkout - preserve micro-worktree isolation
+                // Instead, fetch latest remote state and rebase the temp branch
+                // Step 1: Fetch latest origin/main
                 console.log(`${logPrefix} Fetching ${remote}/${branch}...`);
                 await mainGit.fetch(remote, branch);
-                // Step 3: Update local main to match origin/main (ff-only)
-                console.log(`${logPrefix} Updating local ${branch}...`);
-                await mainGit.merge(`${remote}/${branch}`, { ffOnly: true });
-                // Step 4: Rebase temp branch onto updated main
-                console.log(`${logPrefix} Rebasing temp branch onto ${branch}...`);
-                await worktreeGit.rebase(branch);
-                // Step 5: Re-merge temp branch to local main
+                // Step 2: Rebase temp branch onto updated origin/main
+                console.log(`${logPrefix} Rebasing temp branch onto ${remote}/${branch}...`);
+                await worktreeGit.rebase(`${remote}/${branch}`);
+                // Step 3: Re-merge temp branch to local main (ff-only)
+                // This updates local main to include the rebased commits
                 console.log(`${logPrefix} Re-merging temp branch to ${branch}...`);
                 await mainGit.merge(tempBranchName, { ffOnly: true });
             }
             else {
                 const errMsg = pushErr instanceof Error ? pushErr.message : String(pushErr);
-                throw new Error(`Push failed after ${MAX_PUSH_RETRIES} attempts. ` +
-                    `Origin ${branch} may have significant traffic.\n` +
+                throw new Error(`Push failed after ${maxRetries} attempts. ` +
+                    `Origin ${branch} may have significant traffic.\n\n` +
+                    `Suggestions:\n` +
+                    `  - Wait a few seconds and retry the operation\n` +
+                    `  - Check if another agent is rapidly pushing changes\n` +
                     `Error: ${errMsg}`);
             }
         }
     }
 }
+/**
+ * WU-1332: Push to origin with configurable retry using p-retry
+ *
+ * Enhanced version of pushWithRetry that uses p-retry for exponential backoff
+ * and supports configuration via PushRetryConfig. When push fails due to
+ * non-fast-forward (origin moved), automatically rebases and retries.
+ *
+ * WU-1348: The retry logic no longer resets the main checkout. Instead, it:
+ * 1. Fetches origin/main to get latest remote state
+ * 2. Rebases the temp branch onto origin/main (in the micro-worktree)
+ * 3. Re-merges the rebased temp branch to local main (ff-only)
+ * 4. Retries the push
+ *
+ * This preserves micro-worktree isolation - the main checkout files are never
+ * hard-reset, preventing file flash and preserving any uncommitted work.
+ *
+ * @param {Object} mainGit - GitAdapter instance for main checkout
+ * @param {Object} worktreeGit - GitAdapter instance for micro-worktree
+ * @param {string} remote - Remote name (e.g., 'origin')
+ * @param {string} branch - Branch name (e.g., 'main')
+ * @param {string} tempBranchName - Temp branch that was merged (for rebase)
+ * @param {string} logPrefix - Log prefix for console output
+ * @param {PushRetryConfig} config - Push retry configuration
+ * @throws {Error} If push fails after all retries or if retry is disabled
+ */
+export async function pushWithRetryConfig(mainGit, worktreeGit, remote, branch, tempBranchName, logPrefix = DEFAULT_LOG_PREFIX, config = DEFAULT_PUSH_RETRY_CONFIG) {
+    // If retry is disabled, just try once and throw on failure
+    if (!config.enabled) {
+        console.log(`${logPrefix} Pushing to ${remote}/${branch} (retry disabled)...`);
+        await mainGit.push(remote, branch);
+        console.log(`${logPrefix} ✅ Pushed to ${remote}/${branch}`);
+        return;
+    }
+    let attemptNumber = 0;
+    await pRetry(async () => {
+        attemptNumber++;
+        console.log(`${logPrefix} Pushing to ${remote}/${branch} (attempt ${attemptNumber}/${config.retries})...`);
+        try {
+            await mainGit.push(remote, branch);
+            console.log(`${logPrefix} ✅ Pushed to ${remote}/${branch}`);
+        }
+        catch (pushErr) {
+            console.log(`${logPrefix} ⚠️  Push failed (origin moved). Fetching and rebasing before retry...`);
+            // WU-1348: Do NOT reset main checkout - preserve micro-worktree isolation
+            // Instead, fetch latest remote state and rebase the temp branch
+            // Fetch latest origin/main
+            console.log(`${logPrefix} Fetching ${remote}/${branch}...`);
+            await mainGit.fetch(remote, branch);
+            // Rebase temp branch onto updated origin/main
+            console.log(`${logPrefix} Rebasing temp branch onto ${remote}/${branch}...`);
+            await worktreeGit.rebase(`${remote}/${branch}`);
+            // Re-merge temp branch to local main (ff-only)
+            // This updates local main to include the rebased commits
+            console.log(`${logPrefix} Re-merging temp branch to ${branch}...`);
+            await mainGit.merge(tempBranchName, { ffOnly: true });
+            // Re-throw to trigger p-retry
+            throw pushErr;
+        }
+    }, {
+        retries: config.retries - 1, // p-retry counts retries after first attempt
+        minTimeout: config.min_delay_ms,
+        maxTimeout: config.max_delay_ms,
+        randomize: config.jitter,
+        onFailedAttempt: () => {
+            // Logging is handled in the try/catch above
+        },
+    }).catch(() => {
+        // p-retry exhausted all retries, throw descriptive error
+        throw new Error(`Push failed after ${config.retries} attempts. ` +
+            `Origin ${branch} may have significant traffic.\n\n` +
+            `Suggestions:\n` +
+            `  - Wait a few seconds and retry the operation\n` +
+            `  - Increase git.push_retry.retries in .lumenflow.config.yaml\n` +
+            `  - Check if another agent is rapidly pushing changes`);
+    });
+}
 /**
  * Push using refspec with LUMENFLOW_FORCE to bypass pre-push hooks
  *
@@ -472,6 +696,72 @@ export async function pushRefspecWithForce(gitAdapter, remote, localRef, remoteR
         }
     }
 }
+/**
+ * WU-1337: Push using refspec with LUMENFLOW_FORCE and retry logic
+ *
+ * Enhanced version of pushRefspecWithForce that adds retry with rebase
+ * on non-fast-forward errors. Uses p-retry for exponential backoff and
+ * respects git.push_retry configuration.
+ *
+ * On each retry:
+ * 1. Fetch origin/main to get latest state
+ * 2. Rebase the temp branch onto the updated main
+ * 3. Retry the push with LUMENFLOW_FORCE
+ *
+ * This is used by pushOnly mode in withMicroWorktree to handle race conditions
+ * when multiple agents are pushing to origin/main concurrently.
+ *
+ * @param {GitAdapter} gitWorktree - GitAdapter instance for the worktree (for rebase)
+ * @param {GitAdapter} mainGit - GitAdapter instance for main checkout (for fetch)
+ * @param {string} remote - Remote name (e.g., 'origin')
+ * @param {string} localRef - Local ref to push (e.g., 'tmp/wu-claim/wu-123')
+ * @param {string} remoteRef - Remote ref to update (e.g., 'main')
+ * @param {string} reason - Audit reason for the LUMENFLOW_FORCE bypass
+ * @param {string} logPrefix - Log prefix for console output
+ * @param {PushRetryConfig} config - Push retry configuration
+ * @returns {Promise<void>}
+ * @throws {RetryExhaustionError} If push fails after all retries
+ */
+export async function pushRefspecWithRetry(gitWorktree, mainGit, remote, localRef, remoteRef, reason, logPrefix = DEFAULT_LOG_PREFIX, config = DEFAULT_PUSH_RETRY_CONFIG) {
+    // If retry is disabled, just try once and throw on failure
+    if (!config.enabled) {
+        console.log(`${logPrefix} Pushing to ${remote}/${remoteRef} (push-only, retry disabled)...`);
+        await pushRefspecWithForce(gitWorktree, remote, localRef, remoteRef, reason);
+        console.log(`${logPrefix} ✅ Pushed to ${remote}/${remoteRef}`);
+        return;
+    }
+    let attemptNumber = 0;
+    await pRetry(async () => {
+        attemptNumber++;
+        console.log(`${logPrefix} Pushing to ${remote}/${remoteRef} (push-only, attempt ${attemptNumber}/${config.retries})...`);
+        try {
+            await pushRefspecWithForce(gitWorktree, remote, localRef, remoteRef, reason);
+            console.log(`${logPrefix} ✅ Pushed to ${remote}/${remoteRef}`);
+        }
+        catch (pushErr) {
+            console.log(`${logPrefix} ⚠️  Push failed (origin moved). Fetching and rebasing before retry...`);
+            // Fetch latest origin/main
+            console.log(`${logPrefix} Fetching ${remote}/${remoteRef}...`);
+            await mainGit.fetch(remote, remoteRef);
+            // Rebase temp branch onto updated main
+            console.log(`${logPrefix} Rebasing temp branch onto ${remoteRef}...`);
+            await gitWorktree.rebase(remoteRef);
+            // Re-throw to trigger p-retry
+            throw pushErr;
+        }
+    }, {
+        retries: config.retries - 1, // p-retry counts retries after first attempt
+        minTimeout: config.min_delay_ms,
+        maxTimeout: config.max_delay_ms,
+        randomize: config.jitter,
+        onFailedAttempt: () => {
+            // Logging is handled in the try/catch above
+        },
+    }).catch(() => {
+        // p-retry exhausted all retries, throw typed error
+        throw new RetryExhaustionError('push-only', config.retries);
+    });
+}
 /**
  * Execute an operation in a micro-worktree with full isolation
  *
@@ -481,6 +771,7 @@ export async function pushRefspecWithForce(gitAdapter, remote, localRef, remoteR
  *
  * WU-1435: Added pushOnly option to keep local main pristine.
  * WU-2237: Added pre-creation cleanup of orphaned temp branches/worktrees.
+ * WU-1337: Push-only path now uses retry with rebase.
  *
  * @param {Object} options - Options for the operation
  * @param {string} options.operation - Operation name (e.g., 'wu-create', 'wu-edit')
@@ -496,18 +787,24 @@ export async function pushRefspecWithForce(gitAdapter, remote, localRef, remoteR
 export async function withMicroWorktree(options) {
     const { operation, id, logPrefix = `[${operation}]`, execute, pushOnly = false } = options;
     const mainGit = getGitForCwd();
+    // WU-1308: Check if remote operations should be skipped (local-only mode)
+    const skipRemote = shouldSkipRemoteOperations();
     // WU-2237: Clean up any orphaned temp branch/worktree from previous interrupted operations
     // This makes the operation idempotent - a retry after crash/timeout will succeed
     await cleanupOrphanedMicroWorktree(operation, id, mainGit, logPrefix);
     // WU-1179: Fetch origin/main before starting to minimize race condition window
     // This ensures we start from the latest origin state, reducing push failures
-    if (!pushOnly) {
+    // WU-1308: Skip when git.requireRemote=false (local-only mode)
+    if (!pushOnly && !skipRemote) {
         console.log(`${logPrefix} Fetching ${REMOTES.ORIGIN}/${BRANCHES.MAIN} before starting...`);
         await mainGit.fetch(REMOTES.ORIGIN, BRANCHES.MAIN);
         // Update local main to match origin/main
         await mainGit.merge(`${REMOTES.ORIGIN}/${BRANCHES.MAIN}`, { ffOnly: true });
         console.log(`${logPrefix} ✅ Local main synced with ${REMOTES.ORIGIN}/${BRANCHES.MAIN}`);
     }
+    else if (skipRemote) {
+        console.log(`${logPrefix} Local-only mode (git.requireRemote=false): skipping origin sync`);
+    }
     const tempBranchName = getTempBranchName(operation, id);
     const microWorktreePath = createMicroWorktreeDir(`${operation}-`);
     console.log(`${logPrefix} Using micro-worktree isolation (WU-1262)`);
@@ -536,12 +833,22 @@ export async function withMicroWorktree(options) {
         await gitWorktree.commit(result.commitMessage);
         console.log(`${logPrefix} ✅ Committed: ${result.commitMessage}`);
         // Step 6: Push to origin (different paths for pushOnly vs standard)
-        if (pushOnly) {
+        // WU-1308: Skip push when git.requireRemote=false (local-only mode)
+        if (skipRemote) {
+            // Local-only mode: merge to local main but skip push
+            console.log(`${logPrefix} Local-only mode: merging to local main (skipping push)`);
+            await mainGit.merge(tempBranchName, { ffOnly: true });
+            console.log(`${logPrefix} ✅ Merged to local main (no remote push)`);
+            return { ...result, ref: BRANCHES.MAIN };
+        }
+        else if (pushOnly) {
             // WU-1435: Push directly to origin/main without touching local main
             // WU-1081: Use LUMENFLOW_FORCE to bypass pre-push hooks for micro-worktree pushes
-            console.log(`${logPrefix} Pushing directly to ${REMOTES.ORIGIN}/${BRANCHES.MAIN} (push-only)...`);
-            await pushRefspecWithForce(gitWorktree, REMOTES.ORIGIN, tempBranchName, BRANCHES.MAIN, `micro-worktree push for ${operation} (automated)`);
-            console.log(`${logPrefix} ✅ Pushed to ${REMOTES.ORIGIN}/${BRANCHES.MAIN}`);
+            // WU-1337: Use pushRefspecWithRetry to handle race conditions with rebase
+            // Get push_retry config from LumenFlow config
+            const config = getConfig();
+            const pushRetryConfig = config.git.push_retry || DEFAULT_PUSH_RETRY_CONFIG;
+            await pushRefspecWithRetry(gitWorktree, mainGit, REMOTES.ORIGIN, tempBranchName, BRANCHES.MAIN, `micro-worktree push for ${operation} (automated)`, logPrefix, pushRetryConfig);
             // Fetch to update remote tracking ref (FETCH_HEAD)
             console.log(`${logPrefix} Fetching ${REMOTES.ORIGIN}/${BRANCHES.MAIN}...`);
             await mainGit.fetch(REMOTES.ORIGIN, BRANCHES.MAIN);