@lumenflow/core 2.18.2 → 2.19.0

package/dist/micro-worktree.js

@@ -28,438 +28,19 @@
  * @see {@link packages/@lumenflow/cli/src/initiative-create.ts} - Initiative creation (WU-1439)
  */
 import { getGitForCwd, createGitForPath } from './git-adapter.js';
-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';
+import { MAX_MERGE_RETRIES, MAX_PUSH_RETRIES, DEFAULT_PUSH_RETRY_CONFIG, resolvePushRetryConfig, LUMENFLOW_FORCE_ENV, LUMENFLOW_FORCE_REASON_ENV, LUMENFLOW_WU_TOOL_ENV, DEFAULT_LOG_PREFIX, RetryExhaustionError, isRetryExhaustionError, formatRetryExhaustionError, shouldSkipRemoteOperations, getTempBranchName, createMicroWorktreeDir, findWorktreeByBranch, cleanupOrphanedMicroWorktree, cleanupMicroWorktree, pushRefspecWithForce, pushRefspecWithRetry, } from './micro-worktree-shared.js';
 /**
  * Maximum retry attempts for ff-only merge when main moves
  *
  * This handles race conditions when multiple agents run wu:create or wu:edit
  * concurrently. Each retry fetches latest main and rebases.
  */
-export const MAX_MERGE_RETRIES = 3;
-/**
- * Maximum retry attempts for push when origin/main advances
- *
- * 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,
-};
-/**
- * Resolve effective push retry config from defaults + global config + operation override.
- *
- * Priority (lowest to highest):
- * 1. DEFAULT_PUSH_RETRY_CONFIG
- * 2. Global config from `.lumenflow.config.yaml` (`git.push_retry`)
- * 3. Operation-specific override from caller
- */
-export function resolvePushRetryConfig(globalConfig, operationOverride) {
-    return {
-        ...DEFAULT_PUSH_RETRY_CONFIG,
-        ...(globalConfig || {}),
-        ...(operationOverride || {}),
-    };
-}
-/**
- * Environment variable name for LUMENFLOW_FORCE bypass
- *
- * WU-1081: Exported for use in micro-worktree push operations.
- */
-export const LUMENFLOW_FORCE_ENV = 'LUMENFLOW_FORCE';
-/**
- * Environment variable name for LUMENFLOW_FORCE_REASON audit trail
- *
- * WU-1081: Exported for use in micro-worktree push operations.
- */
-export const LUMENFLOW_FORCE_REASON_ENV = 'LUMENFLOW_FORCE_REASON';
-/**
- * Environment variable name for LUMENFLOW_WU_TOOL
- *
- * WU-1365: Exported for use by CLI commands that use micro-worktree operations.
- * The pre-push hook checks this env var to allow micro-worktree pushes to main.
- * Valid values are: wu-create, wu-edit, wu-done, wu-delete, wu-claim, wu-block,
- * wu-unblock, initiative-create, initiative-edit, release, lumenflow-upgrade
- */
-export const LUMENFLOW_WU_TOOL_ENV = 'LUMENFLOW_WU_TOOL';
-/**
- * Default log prefix for micro-worktree operations
- *
- * 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
- *
- * @param {string} operation - Operation name (e.g., 'wu-create', 'wu-edit')
- * @param {string} id - WU ID (e.g., 'wu-123')
- * @returns {string} Temp branch name (e.g., 'tmp/wu-create/wu-123')
- */
-export function getTempBranchName(operation, id) {
-    return `${BRANCHES.TEMP_PREFIX}${operation}/${id.toLowerCase()}`;
-}
-/**
- * Create micro-worktree in /tmp directory
- *
- * @param {string} prefix - Directory prefix (e.g., 'wu-create-', 'wu-edit-')
- * @returns {string} Path to created micro-worktree directory
- */
-export function createMicroWorktreeDir(prefix) {
-    return mkdtempSync(join(tmpdir(), prefix));
-}
-/**
- * Parse git worktree list output to find worktrees by branch
- *
- * WU-2237: Helper to parse porcelain format output from `git worktree list --porcelain`
- *
- * @param {string} worktreeListOutput - Output from git worktree list --porcelain
- * @param {string} branchName - Branch name to search for (e.g., 'tmp/wu-create/wu-123')
- * @returns {string|null} Worktree path if found, null otherwise
- */
-export function findWorktreeByBranch(worktreeListOutput, branchName) {
-    const branchRef = `refs/heads/${branchName}`;
-    const lines = worktreeListOutput.split('\n');
-    let currentWorktreePath = null;
-    for (const line of lines) {
-        if (line.startsWith('worktree ')) {
-            currentWorktreePath = line.substring('worktree '.length);
-        }
-        else if (line.startsWith('branch ') && line.substring('branch '.length) === branchRef) {
-            return currentWorktreePath;
-        }
-        else if (line === '') {
-            currentWorktreePath = null;
-        }
-    }
-    return null;
-}
-/**
- * Clean up orphaned micro-worktree and temp branch from a previous interrupted operation
- *
- * WU-2237: Before creating a new micro-worktree, detect and clean any existing temp
- * branch/worktree for the same operation+WU ID. This handles scenarios where:
- * - A previous wu:create/wu:edit was interrupted (timeout/crash)
- * - The temp branch and /tmp worktree were left behind
- * - A subsequent operation would fail with 'branch already exists'
- *
- * This function is idempotent - safe to call even when no orphans exist.
- *
- * @param {string} operation - Operation name (e.g., 'wu-create', 'wu-edit')
- * @param {string} id - WU ID (e.g., 'WU-123')
- * @param {Object} gitAdapter - GitAdapter instance to use (for testability)
- * @param {string} logPrefix - Log prefix for console output
- * @returns {Promise<{cleanedWorktree: boolean, cleanedBranch: boolean}>} Cleanup status
- */
-export async function cleanupOrphanedMicroWorktree(operation, id, gitAdapter, logPrefix = DEFAULT_LOG_PREFIX) {
-    const tempBranchName = getTempBranchName(operation, id);
-    let cleanedWorktree = false;
-    let cleanedBranch = false;
-    // Step 1: Check git worktree list for any worktree on this temp branch
-    try {
-        const worktreeListOutput = await gitAdapter.worktreeList();
-        const orphanWorktreePath = findWorktreeByBranch(worktreeListOutput, tempBranchName);
-        if (orphanWorktreePath) {
-            console.log(`${logPrefix} Found orphaned worktree for ${tempBranchName}: ${orphanWorktreePath}`);
-            try {
-                await gitAdapter.worktreeRemove(orphanWorktreePath, { force: true });
-                console.log(`${logPrefix} ✅ Removed orphaned worktree: ${orphanWorktreePath}`);
-                cleanedWorktree = true;
-            }
-            catch (err) {
-                const errMsg = err instanceof Error ? err.message : String(err);
-                console.warn(`${logPrefix} ⚠️  Could not remove orphaned worktree: ${errMsg}`);
-                // Try filesystem cleanup as fallback
-                tryFilesystemCleanup(orphanWorktreePath);
-                cleanedWorktree = true;
-            }
-        }
-    }
-    catch (err) {
-        const errMsg = err instanceof Error ? err.message : String(err);
-        console.warn(`${logPrefix} ⚠️  Could not check worktree list: ${errMsg}`);
-    }
-    // Step 2: Check if the temp branch exists and delete it
-    try {
-        const branchExists = await gitAdapter.branchExists(tempBranchName);
-        if (branchExists) {
-            console.log(`${logPrefix} Found orphaned temp branch: ${tempBranchName}`);
-            await gitAdapter.deleteBranch(tempBranchName, { force: true });
-            console.log(`${logPrefix} ✅ Deleted orphaned temp branch: ${tempBranchName}`);
-            cleanedBranch = true;
-        }
-    }
-    catch (err) {
-        const errMsg = err instanceof Error ? err.message : String(err);
-        console.warn(`${logPrefix} ⚠️  Could not delete orphaned branch: ${errMsg}`);
-    }
-    return { cleanedWorktree, cleanedBranch };
-}
-/**
- * Try to remove a worktree path via filesystem as fallback
- *
- * WU-2237: Extracted helper to reduce cognitive complexity.
- *
- * @param {string} worktreePath - Path to remove
- */
-function tryFilesystemCleanup(worktreePath) {
-    try {
-        if (existsSync(worktreePath)) {
-            rmSync(worktreePath, { recursive: true, force: true });
-        }
-    }
-    catch {
-        // Ignore filesystem cleanup errors
-    }
-}
-/**
- * Remove a worktree using git, with filesystem fallback
- *
- * WU-2237: Extracted helper to reduce cognitive complexity.
- *
- * @param {Object} gitAdapter - Git adapter instance
- * @param {string} worktreePath - Path to worktree
- * @param {string} logPrefix - Log prefix
- * @param {string} [contextLabel] - Optional label for logging (e.g., 'registered')
- */
-async function removeWorktreeSafe(gitAdapter, worktreePath, logPrefix, contextLabel = '') {
-    const label = contextLabel ? ` ${contextLabel}` : '';
-    try {
-        await gitAdapter.worktreeRemove(worktreePath, { force: true });
-        if (contextLabel) {
-            console.log(`${logPrefix} ✅ Removed${label} worktree: ${worktreePath}`);
-        }
-    }
-    catch (err) {
-        const errMsg = err instanceof Error ? err.message : String(err);
-        console.warn(`${logPrefix} ⚠️  Could not remove${label} worktree: ${errMsg}`);
-        tryFilesystemCleanup(worktreePath);
-    }
-}
-/**
- * Cleanup micro-worktree and temp branch
- *
- * Runs even on failure to prevent orphaned resources.
- * Safe to call multiple times (idempotent).
- *
- * WU-2237: Enhanced to also check git worktree list for registered worktrees
- * on the temp branch, in case the worktree path differs from what was expected.
- *
- * @param {string} worktreePath - Path to micro-worktree
- * @param {string} branchName - Temp branch name
- * @param {string} logPrefix - Log prefix for console output
- */
-export async function cleanupMicroWorktree(worktreePath, branchName, logPrefix = DEFAULT_LOG_PREFIX) {
-    console.log(`${logPrefix} Cleaning up micro-worktree...`);
-    const mainGit = getGitForCwd();
-    // Remove the known worktree path first (must be done before deleting branch)
-    if (existsSync(worktreePath)) {
-        await removeWorktreeSafe(mainGit, worktreePath, logPrefix);
-    }
-    // WU-2237: Also check git worktree list for any registered worktrees on this branch
-    await cleanupRegisteredWorktreeForBranch(mainGit, branchName, worktreePath, logPrefix);
-    // Delete temp branch
-    await deleteBranchSafe(mainGit, branchName, logPrefix);
-    console.log(`${logPrefix} ✅ Cleanup complete`);
-}
-/**
- * Clean up any registered worktree for a branch that differs from the expected path
- *
- * WU-2237: Extracted helper to reduce cognitive complexity.
- *
- * @param {Object} gitAdapter - Git adapter instance
- * @param {string} branchName - Branch name to search for
- * @param {string} expectedPath - Expected worktree path (skip if matches)
- * @param {string} logPrefix - Log prefix
- */
-async function cleanupRegisteredWorktreeForBranch(gitAdapter, branchName, expectedPath, logPrefix) {
-    try {
-        const worktreeListOutput = await gitAdapter.worktreeList();
-        const registeredPath = findWorktreeByBranch(worktreeListOutput, branchName);
-        if (registeredPath && registeredPath !== expectedPath) {
-            console.log(`${logPrefix} Found additional registered worktree: ${registeredPath}`);
-            await removeWorktreeSafe(gitAdapter, registeredPath, logPrefix, 'registered');
-        }
-    }
-    catch (err) {
-        const errMsg = err instanceof Error ? err.message : String(err);
-        console.warn(`${logPrefix} ⚠️  Could not check worktree list: ${errMsg}`);
-    }
-}
-/**
- * Delete a branch safely, ignoring errors
- *
- * WU-2237: Extracted helper to reduce cognitive complexity.
- *
- * @param {Object} gitAdapter - Git adapter instance
- * @param {string} branchName - Branch to delete
- * @param {string} logPrefix - Log prefix
- */
-async function deleteBranchSafe(gitAdapter, branchName, logPrefix) {
-    try {
-        const branchExists = await gitAdapter.branchExists(branchName);
-        if (branchExists) {
-            await gitAdapter.deleteBranch(branchName, { force: true });
-        }
-    }
-    catch (err) {
-        const errMsg = err instanceof Error ? err.message : String(err);
-        console.warn(`${logPrefix} ⚠️  Could not delete branch: ${errMsg}`);
-    }
-}
-/**
- * Stage changes including deletions in micro-worktree
- *
- * WU-1813: Uses addWithDeletions to properly stage tracked file deletions.
- * This replaces the previous pattern of using gitWorktree.add(files) which
- * could miss deletions when files were removed.
- *
- * @param {Object} gitWorktree - GitAdapter instance for the worktree
- * @param {string[]|undefined} files - Files to stage (undefined/empty = stage all)
- * @returns {Promise<void>}
- */
+export { MAX_MERGE_RETRIES, MAX_PUSH_RETRIES, DEFAULT_PUSH_RETRY_CONFIG, resolvePushRetryConfig, LUMENFLOW_FORCE_ENV, LUMENFLOW_FORCE_REASON_ENV, LUMENFLOW_WU_TOOL_ENV, DEFAULT_LOG_PREFIX, RetryExhaustionError, isRetryExhaustionError, formatRetryExhaustionError, shouldSkipRemoteOperations, getTempBranchName, createMicroWorktreeDir, findWorktreeByBranch, cleanupOrphanedMicroWorktree, cleanupMicroWorktree, pushRefspecWithForce, pushRefspecWithRetry, };
 export async function stageChangesWithDeletions(gitWorktree, files) {
     // Normalise undefined/null to empty array for addWithDeletions
     const filesToStage = files || [];
@@ -777,125 +358,6 @@ export async function pushWithRetryConfig(mainGit, worktreeGit, remote, branch,
  * @returns {Promise<void>}
  * @throws {Error} If push fails (env vars still restored)
  */
-export async function pushRefspecWithForce(gitAdapter, remote, localRef, remoteRef, reason) {
-    // Save original env values
-    const originalForce = process.env[LUMENFLOW_FORCE_ENV];
-    const originalReason = process.env[LUMENFLOW_FORCE_REASON_ENV];
-    try {
-        // Set LUMENFLOW_FORCE for the push
-        process.env[LUMENFLOW_FORCE_ENV] = '1';
-        process.env[LUMENFLOW_FORCE_REASON_ENV] = reason;
-        // Perform the push
-        await gitAdapter.pushRefspec(remote, localRef, remoteRef);
-    }
-    finally {
-        // Restore original env values
-        if (originalForce === undefined) {
-            Reflect.deleteProperty(process.env, LUMENFLOW_FORCE_ENV);
-        }
-        else {
-            process.env[LUMENFLOW_FORCE_ENV] = originalForce;
-        }
-        if (originalReason === undefined) {
-            Reflect.deleteProperty(process.env, LUMENFLOW_FORCE_REASON_ENV);
-        }
-        else {
-            process.env[LUMENFLOW_FORCE_REASON_ENV] = originalReason;
-        }
-    }
-}
-/**
- * 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 remote-tracking ref.
-            // In pushOnly mode, local `main` is intentionally not updated (WU-1435),
-            // so rebasing onto `main` will not make progress after a successful push.
-            const remoteTrackingRef = `${remote}/${remoteRef}`;
-            console.log(`${logPrefix} Rebasing temp branch onto ${remoteTrackingRef}...`);
-            await gitWorktree.rebase(remoteTrackingRef);
-            // 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
- *
- * This is the main entry point for micro-worktree operations.
- * Handles the full lifecycle: create temp branch, create worktree,
- * execute operation, merge, push, and cleanup.
- *
- * 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')
- * @param {string} options.id - WU ID (e.g., 'WU-123')
- * @param {string} options.logPrefix - Log prefix for console output
- * @param {boolean} [options.pushOnly=false] - Skip local main merge, push directly to origin/main
- * @param {Object} [options.pushRetryOverride] - Optional push retry overrides for this operation
- * @param {Function} options.execute - Async function to execute in micro-worktree
- *   Receives: { worktreePath: string, gitWorktree: GitAdapter }
- *   Should return: { commitMessage: string, files: string[] }
- * @returns {Promise<Object>} Result with ref property for worktree creation
- * @throws {Error} If any step fails (cleanup still runs)
- */
 export async function withMicroWorktree(options) {
     const { operation, id, logPrefix = `[${operation}]`, execute, pushOnly = false, pushRetryOverride, } = options;
     const mainGit = getGitForCwd();
@@ -904,31 +366,37 @@ export async function withMicroWorktree(options) {
     // 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
-    // WU-1308: Skip when git.requireRemote=false (local-only mode)
-    if (!pushOnly && !skipRemote) {
+    // WU-1179/WU-1672: Fetch origin/main before starting to minimize race condition window.
+    // In pushOnly mode, fetch updates origin/main tracking ref without touching local main.
+    // WU-1308: Skip when git.requireRemote=false (local-only mode).
+    if (!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}`);
+        if (pushOnly) {
+            console.log(`${logPrefix} ✅ Push-only mode will base from ${REMOTES.ORIGIN}/${BRANCHES.MAIN}; local main unchanged (WU-1672)`);
+        }
+        else {
+            // Update local main to match origin/main for standard mode.
+            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 baseRef = pushOnly && !skipRemote ? `${REMOTES.ORIGIN}/${BRANCHES.MAIN}` : BRANCHES.MAIN;
     const microWorktreePath = createMicroWorktreeDir(`${operation}-`);
     console.log(`${logPrefix} Using micro-worktree isolation (WU-1262)`);
     console.log(`${logPrefix} Temp branch: ${tempBranchName}`);
     console.log(`${logPrefix} Micro-worktree: ${microWorktreePath}`);
     if (pushOnly) {
-        console.log(`${logPrefix} Push-only mode: local main will not be modified (WU-1435)`);
+        console.log(`${logPrefix} Push-only mode: local main will not be modified (WU-1435/WU-1672)`);
     }
     try {
         // Step 1: Create temp branch without switching
         console.log(`${logPrefix} Creating temp branch...`);
-        await mainGit.createBranchNoCheckout(tempBranchName, BRANCHES.MAIN);
+        await mainGit.createBranchNoCheckout(tempBranchName, baseRef);
         // Step 2: Create micro-worktree pointing to temp branch
         console.log(`${logPrefix} Creating micro-worktree...`);
         await mainGit.worktreeAddExisting(microWorktreePath, tempBranchName);