@lumenflow/cli 2.18.3 → 2.20.0

package/dist/wu-done.js

@@ -33,12 +33,16 @@
  */
 // WU-2542: Import from @lumenflow/core to establish shim layer dependency
 import '@lumenflow/core';
+// WU-1663: XState pipeline actor for state-driven orchestration
+import { createActor } from 'xstate';
+import { wuDoneMachine, WU_DONE_EVENTS } from '@lumenflow/core/wu-done-machine';
 // WU-1153: wu:done guard for uncommitted code_paths is implemented in core package
 // The guard runs in executeWorktreeCompletion() before metadata transaction
 // See: packages/@lumenflow/core/src/wu-done-validation.ts
 import { execSync } from 'node:child_process';
 import prettyMs from 'pretty-ms';
 import { runGates } from './gates.js';
+import { resolveWuDonePreCommitGateDecision } from '@lumenflow/core/gates-agent-mode';
 import { buildClaimRepairCommand } from './wu-claim-repair-guidance.js';
 import { getGitForCwd, createGitForPath } from '@lumenflow/core/git-adapter';
 import { die, getErrorMessage } from '@lumenflow/core/error-handler';
@@ -59,9 +63,8 @@ executePreflightCodePathValidation, buildPreflightCodePathErrorMessage,
 // WU-2308: Pre-commit hooks with worktree context
 validateAllPreCommitHooks, 
 // WU-2310: Type vs code_paths preflight validation
-validateTypeVsCodePathsPreflight, buildTypeVsCodePathsErrorMessage, 
-// WU-1503: Dirty-main pre-merge guard
-validateDirtyMain, buildDirtyMainErrorMessage, } from '@lumenflow/core/wu-done-validators';
+validateTypeVsCodePathsPreflight, buildTypeVsCodePathsErrorMessage, } from '@lumenflow/core/wu-done-validators';
+import { formatPreflightWarnings } from '@lumenflow/core/wu-preflight-validators';
 // WU-1825: validateCodePathsExist moved to unified code-path-validator
 import { validateCodePathsExist } from '@lumenflow/core/code-path-validator';
 import { BRANCHES, REMOTES, PATTERNS, DEFAULTS, LOG_PREFIX, EMOJI, GIT, SESSION, WU_STATUS, WU_EXPOSURE, PKG_MANAGER, SCRIPTS, CLI_FLAGS, FILE_SYSTEM, EXIT_CODES, STRING_LITERALS, MICRO_WORKTREE_OPERATIONS, TELEMETRY_STEPS, SKIP_GATES_REASONS, CHECKPOINT_MESSAGES, LUMENFLOW_PATHS, getWUStatusDisplay, 
@@ -97,8 +100,8 @@ import { releaseLaneLock } from '@lumenflow/core/lane-lock';
 // WU-1747: Checkpoint and lock for concurrent load resilience
 import { createPreGatesCheckpoint as createWU1747Checkpoint, markGatesPassed, canSkipGates, clearCheckpoint, } from '@lumenflow/core/wu-checkpoint';
 // WU-1946: Spawn registry for tracking sub-agent spawns
-import { SpawnRegistryStore } from '@lumenflow/core/spawn-registry-store';
-import { SpawnStatus } from '@lumenflow/core/spawn-registry-schema';
+import { DelegationRegistryStore } from '@lumenflow/core/delegation-registry-store';
+import { DelegationStatus } from '@lumenflow/core/delegation-registry-schema';
 // WU-1999: Exposure validation for UI pairing
 // WU-2022: Feature accessibility validation (blocking)
 import { validateExposure, validateFeatureAccessibility } from '@lumenflow/core/wu-validation';
@@ -454,7 +457,7 @@ export async function enforceSpawnProvenanceForDone(id, doc, options = {}) {
     const initiativeId = doc.initiative.trim();
     const baseDir = options.baseDir ?? process.cwd();
     const force = options.force === true;
-    const store = new SpawnRegistryStore(path.join(baseDir, '.lumenflow', 'state'));
+    const store = new DelegationRegistryStore(path.join(baseDir, '.lumenflow', 'state'));
     await store.load();
     const spawnEntry = store.getByTarget(id);
     if (!spawnEntry) {
@@ -493,7 +496,7 @@ export async function enforceSpawnProvenanceForDone(id, doc, options = {}) {
  */
 export async function updateSpawnRegistryOnCompletion(id, baseDir = process.cwd()) {
     try {
-        const store = new SpawnRegistryStore(path.join(baseDir, '.lumenflow', 'state'));
+        const store = new DelegationRegistryStore(path.join(baseDir, '.lumenflow', 'state'));
         await store.load();
         const spawnEntry = store.getByTarget(id);
         // Graceful skip if no spawn entry found (legacy WU)
@@ -502,7 +505,7 @@ export async function updateSpawnRegistryOnCompletion(id, baseDir = process.cwd(
             return;
         }
         // Update status to completed with completedAt timestamp
-        await store.updateStatus(spawnEntry.id, SpawnStatus.COMPLETED);
+        await store.updateStatus(spawnEntry.id, DelegationStatus.COMPLETED);
         console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Spawn registry updated: ${id} marked as completed`);
     }
     catch (err) {
@@ -655,118 +658,6 @@ async function _ensureCleanWorkingTree() {
             `  - Leftover changes from previous session`);
     }
 }
-const INTERNAL_LIFECYCLE_DIRTY_FILES = new Set([
-    '.lumenflow/flow.log',
-    '.lumenflow/skip-gates-audit.log',
-    '.lumenflow/skip-cos-gates-audit.log',
-]);
-/**
- * WU-1554: Prefixes for metadata files that wu:done manages.
- * These files may be dirty after merge+rebase when wu:claim used push-only mode
- * or when concurrent agents advance origin/main. Instead of blocking wu:done,
- * these are auto-committed by the caller.
- */
-const METADATA_LIFECYCLE_PREFIXES = [
-    '.lumenflow/state/',
-    '.lumenflow/stamps/',
-    '.lumenflow/archive/',
-];
-const PROTECTED_MAIN_LIKE_BRANCHES = new Set([BRANCHES.MAIN, BRANCHES.MASTER]);
-export function isProtectedMainLikeBranch(branchName) {
-    if (!branchName) {
-        return false;
-    }
-    return PROTECTED_MAIN_LIKE_BRANCHES.has(branchName.trim());
-}
-export function shouldAutoCommitLifecycleWrites(branchName) {
-    if (!branchName || branchName.trim().length === 0) {
-        // Fail-safe: unknown branch should never trigger direct lifecycle commits.
-        return false;
-    }
-    return !isProtectedMainLikeBranch(branchName);
-}
-function parsePorcelainPath(line) {
-    if (line.length < 4)
-        return null;
-    const pathPart = line.slice(3).trim();
-    if (!pathPart)
-        return null;
-    const renameIndex = pathPart.indexOf(' -> ');
-    if (renameIndex !== -1) {
-        return pathPart.slice(renameIndex + 4);
-    }
-    return pathPart;
-}
-/**
- * WU-1554: Check if a file is a metadata lifecycle file.
- * Metadata files are managed by wu:done (wu-events.jsonl, status.md, backlog.md,
- * WU YAML, stamps, archives) and may be dirty after merge+rebase.
- */
-function isMetadataLifecycleFile(filePath, metadataDir) {
-    if (METADATA_LIFECYCLE_PREFIXES.some((prefix) => filePath.startsWith(prefix))) {
-        return true;
-    }
-    if (metadataDir && filePath.startsWith(metadataDir + '/')) {
-        return true;
-    }
-    return false;
-}
-/**
- * WU-1084: Check for uncommitted changes on main after merge completes.
- *
- * This catches cases where pnpm format (or other tooling) touched files
- * outside the WU's code_paths during worktree work. These changes survive
- * the merge and would be silently left behind when the worktree is removed.
- *
- * WU-1554: Added metadataDir parameter and metadataFiles return field.
- * Metadata files (wu-events.jsonl, status.md, backlog.md, WU YAML, stamps)
- * may be dirty after merge+rebase when wu:claim used push-only mode.
- * These are returned separately for auto-commit by the caller.
- *
- * @param gitStatus - Output from git status (porcelain format)
- * @param wuId - The WU ID for error messaging
- * @param metadataDir - Optional task directory prefix for metadata file detection
- * @returns Object with isDirty flag, file categories, and optional error message
- */
-export function checkPostMergeDirtyState(gitStatus, wuId, metadataDir) {
-    // WU-1522: Split before trimming to preserve leading spaces in porcelain format.
-    // Porcelain lines like ' M .lumenflow/flow.log' use the leading space as a status
-    // indicator (working tree vs staging area). Trimming the whole string first strips
-    // the leading space from the first line, corrupting parsePorcelainPath output.
-    const lines = gitStatus.split('\n').filter((line) => line.length >= 4);
-    if (lines.length === 0) {
-        return { isDirty: false, internalOnlyFiles: [], metadataFiles: [], unrelatedFiles: [] };
-    }
-    const dirtyFiles = lines
-        .map((line) => parsePorcelainPath(line))
-        .filter((value) => Boolean(value));
-    // WU-1554: Three-category classification
-    const internalOnlyFiles = dirtyFiles.filter((file) => INTERNAL_LIFECYCLE_DIRTY_FILES.has(file));
-    const metadataFiles = dirtyFiles.filter((file) => !INTERNAL_LIFECYCLE_DIRTY_FILES.has(file) && isMetadataLifecycleFile(file, metadataDir));
-    const unrelatedFiles = dirtyFiles.filter((file) => !INTERNAL_LIFECYCLE_DIRTY_FILES.has(file) && !isMetadataLifecycleFile(file, metadataDir));
-    if (unrelatedFiles.length === 0) {
-        return { isDirty: false, internalOnlyFiles, metadataFiles, unrelatedFiles: [] };
-    }
-    const displayStatus = gitStatus.trim();
-    const error = `Main branch has uncommitted changes after merge:\n\n${displayStatus}\n\n` +
-        `This indicates files were modified outside the WU's code_paths.\n` +
-        `Common cause: pnpm format touched files outside the WU scope.\n\n` +
-        `The worktree has NOT been removed to allow investigation.\n\n` +
-        `Options:\n` +
-        `  1. Review and commit the changes: git add . && git commit -m "format: fix formatting"\n` +
-        `  2. Discard if unwanted: git checkout -- .\n` +
-        `  3. Then re-run: pnpm wu:done --id ${wuId} --skip-worktree-completion`;
-    return { isDirty: true, internalOnlyFiles, metadataFiles, unrelatedFiles, error };
-}
-/**
- * Build the list of lifecycle files that are safe to restore after a failed wu:done attempt.
- *
- * On failure, wu:done can leave internal lifecycle logs and metadata lifecycle files dirty on main.
- * These files are managed by lifecycle tooling and should not block re-claim/retry.
- */
-export function getLifecycleRestoreTargetsOnFailure(dirtyState) {
-    return Array.from(new Set([...dirtyState.internalOnlyFiles, ...dirtyState.metadataFiles]));
-}
 /**
  * Extract completed WU IDs from git log output.
  * @param {string} logOutput - Git log output (one commit per line)
@@ -1663,6 +1554,12 @@ async function executePreFlightChecks({ id, args, isBranchOnly, isDocsOnly, docM
         const errorMessage = buildPreflightCodePathErrorMessage(id, preflightResult);
         die(errorMessage);
     }
+    if (Array.isArray(preflightResult.warnings) && preflightResult.warnings.length > 0) {
+        const warningLines = formatPreflightWarnings(preflightResult.warnings, `${LOG_PREFIX.DONE} ${EMOJI.WARNING} Reality preflight warnings:`);
+        for (const line of warningLines) {
+            console.log(line.startsWith('  - ') ? `${LOG_PREFIX.DONE} ${line}` : line);
+        }
+    }
     // WU-2310: Preflight type vs code_paths validation
     // Run BEFORE transaction to prevent documentation WUs with code paths from failing at git commit
     console.log(`${LOG_PREFIX.DONE} Validating type vs code_paths (WU-2310)...`);
@@ -1710,42 +1607,6 @@ async function executePreFlightChecks({ id, args, isBranchOnly, isDocsOnly, docM
     else {
         // Worktree mode: must be on main
         await ensureOnMain(getGitForCwd());
-        // WU-1503: Dirty-main pre-merge guard (replaces blanket ensureCleanWorkingTree)
-        // Distinguishes between WU-related dirty files (allowed) and unrelated dirty
-        // files (blocked with actionable guidance). Uses --force for audited bypass.
-        {
-            const gitAdapter = getGitForCwd();
-            const gitStatus = await gitAdapter.raw(['status', '--porcelain']);
-            if (gitStatus && gitStatus.trim()) {
-                const wuCodePaths = docForValidation.code_paths || [];
-                const dirtyResult = validateDirtyMain(gitStatus, id, wuCodePaths);
-                if (!dirtyResult.valid) {
-                    if (args.force) {
-                        console.log(`\n${LOG_PREFIX.DONE} ${EMOJI.WARNING} WU-1503: Dirty-main guard bypassed with --force`);
-                        console.log(`${LOG_PREFIX.DONE} Unrelated dirty files (${dirtyResult.unrelatedFiles.length}):`);
-                        for (const f of dirtyResult.unrelatedFiles) {
-                            console.log(`${LOG_PREFIX.DONE}   - ${f}`);
-                        }
-                    }
-                    else {
-                        die(buildDirtyMainErrorMessage(id, dirtyResult.unrelatedFiles));
-                    }
-                }
-                else if (dirtyResult.relatedFiles.length > 0) {
-                    console.log(`${LOG_PREFIX.DONE} ${EMOJI.INFO} WU-1503: ${dirtyResult.relatedFiles.length} related dirty file(s) on main (allowed)`);
-                    // WU-1554: Auto-restore related dirty files so ff-only merge can proceed.
-                    // These files will be overwritten by the merge commit anyway.
-                    // Without this, git merge --ff-only refuses to overwrite dirty tracked files.
-                    try {
-                        await gitAdapter.raw(['checkout', '--', ...dirtyResult.relatedFiles]);
-                        console.log(`${LOG_PREFIX.DONE} ${EMOJI.INFO} WU-1554: Auto-restored ${dirtyResult.relatedFiles.length} related file(s) for clean merge`);
-                    }
-                    catch (restoreErr) {
-                        console.warn(`${LOG_PREFIX.DONE} ${EMOJI.WARNING} WU-1554: Could not auto-restore related files: ${restoreErr.message}`);
-                    }
-                }
-            }
-        }
         // Prevent coordination failures by ensuring main is up-to-date
         await ensureMainUpToDate();
         // P0 EMERGENCY FIX Part 1: Restore wu-events.jsonl BEFORE parallel completion check
@@ -1939,10 +1800,17 @@ async function executePreFlightChecks({ id, args, isBranchOnly, isDocsOnly, docM
     return { title, docForValidation };
 }
 async function executeGates({ id, args, isBranchOnly, isDocsOnly, worktreePath, branchName, }) {
+    const gateResult = {
+        fullGatesRanInCurrentRun: false,
+        skippedByCheckpoint: false,
+        checkpointId: null,
+    };
     // WU-1747: Check if gates can be skipped based on valid checkpoint
     // This allows resuming wu:done without re-running gates if nothing changed
     const skipResult = canSkipGates(id, { currentHeadSha: undefined });
     if (skipResult.canSkip) {
+        gateResult.skippedByCheckpoint = true;
+        gateResult.checkpointId = skipResult.checkpoint.checkpointId;
         console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} ${CHECKPOINT_MESSAGES.SKIPPING_GATES_VALID}`);
         console.log(`${LOG_PREFIX.DONE} ${CHECKPOINT_MESSAGES.CHECKPOINT_LABEL}: ${skipResult.checkpoint.checkpointId}`);
         console.log(`${LOG_PREFIX.DONE} ${CHECKPOINT_MESSAGES.GATES_PASSED_AT}: ${skipResult.checkpoint.gatesPassedAt}`);
@@ -1954,7 +1822,7 @@ async function executeGates({ id, args, isBranchOnly, isDocsOnly, worktreePath,
             reason: SKIP_GATES_REASONS.CHECKPOINT_VALID,
             checkpoint_id: skipResult.checkpoint.checkpointId,
         });
-        return; // Skip gates entirely
+        return gateResult; // Skip gates entirely
     }
     // WU-1747: Create checkpoint before gates for resumption on failure
     if (worktreePath && branchName) {
@@ -2071,6 +1939,7 @@ async function executeGates({ id, args, isBranchOnly, isDocsOnly, worktreePath,
             });
             die(`Gates failed in Branch-Only mode. Fix issues and try again.`);
         }
+        gateResult.fullGatesRanInCurrentRun = true;
     }
     else if (worktreePath && existsSync(worktreePath)) {
         // Worktree mode: run gates in the dedicated worktree
@@ -2079,6 +1948,7 @@ async function executeGates({ id, args, isBranchOnly, isDocsOnly, worktreePath,
             isDocsOnly,
             docsOnly: Boolean(args.docsOnly),
         });
+        gateResult.fullGatesRanInCurrentRun = true;
     }
     else {
         die(`Worktree not found (${worktreePath || 'unknown'}). Gates must run in the lane worktree.\n` +
@@ -2136,6 +2006,7 @@ async function executeGates({ id, args, isBranchOnly, isDocsOnly, worktreePath,
     // WU-1747: Mark checkpoint as gates passed for resumption on failure
     // This allows subsequent wu:done attempts to skip gates if nothing changed
     markGatesPassed(id);
+    return gateResult;
 }
 /**
  * Print State HUD for visibility
@@ -2194,6 +2065,29 @@ async function main() {
     isBranchPR, derivedWorktree, docForValidation: initialDocForValidation, isDocsOnly, } = pathInfo;
     // Capture main checkout path once. process.cwd() may drift later during recovery flows.
     const mainCheckoutPath = process.cwd();
+    // WU-1663: Determine prepPassed early for pipeline actor input.
+    // canSkipGates checks if wu:prep already ran gates successfully via checkpoint.
+    // This drives the isPrepPassed guard on the GATES_SKIPPED transition.
+    const earlySkipResult = canSkipGates(id, { currentHeadSha: undefined });
+    const prepPassed = earlySkipResult.canSkip;
+    // WU-1663: Create XState pipeline actor for state-driven orchestration.
+    // The actor tracks which pipeline stage we're in (validating, gating, committing, etc.)
+    // and provides explicit state/transition contracts. Existing procedural logic continues
+    // to do the real work; the actor provides structured state tracking alongside it.
+    const pipelineActor = createActor(wuDoneMachine, {
+        input: {
+            wuId: id,
+            worktreePath: derivedWorktree,
+            prepPassed,
+        },
+    });
+    pipelineActor.start();
+    // WU-1663: Send START event to transition from idle -> validating
+    pipelineActor.send({
+        type: WU_DONE_EVENTS.START,
+        wuId: id,
+        worktreePath: derivedWorktree || '',
+    });
     // WU-1590: branch-pr has no worktree, treat like branch-only for path resolution and ensureOnMain skip
     const isNoWorktreeMode = isBranchOnly || isBranchPR;
     const resolvedWorktreePath = derivedWorktree && !isNoWorktreeMode
@@ -2220,18 +2114,32 @@ async function main() {
         await ensureCleanWorktree(effectiveWorktreePath);
     }
     // Pre-flight checks (WU-1215: extracted to executePreFlightChecks function)
-    const preFlightResult = await executePreFlightChecks({
-        id,
-        args,
-        isBranchOnly: effectiveBranchOnly,
-        isDocsOnly,
-        docMain,
-        docForValidation: initialDocForValidation,
-        derivedWorktree: effectiveDerivedWorktree,
-    });
+    // WU-1663: Wrap in try/catch to send pipeline failure event before die() propagates
+    let preFlightResult;
+    try {
+        preFlightResult = await executePreFlightChecks({
+            id,
+            args,
+            isBranchOnly: effectiveBranchOnly,
+            isDocsOnly,
+            docMain,
+            docForValidation: initialDocForValidation,
+            derivedWorktree: effectiveDerivedWorktree,
+        });
+    }
+    catch (preFlightErr) {
+        pipelineActor.send({
+            type: WU_DONE_EVENTS.VALIDATION_FAILED,
+            error: getErrorMessage(preFlightErr),
+        });
+        pipelineActor.stop();
+        throw preFlightErr;
+    }
     const title = preFlightResult.title;
     // Note: docForValidation is returned but not used after pre-flight checks
     // The metadata transaction uses docForUpdate instead
+    // WU-1663: Pre-flight checks passed - transition to preparing state
+    pipelineActor.send({ type: WU_DONE_EVENTS.VALIDATION_PASSED });
     // WU-1599: Enforce auditable spawn provenance for initiative-governed WUs.
     await enforceSpawnProvenanceForDone(id, docMain, {
         baseDir: mainCheckoutPath,
@@ -2272,7 +2180,35 @@ async function main() {
         }
         // Otherwise silently allow - fail-open
     }
-    await executeGates({ id, args, isBranchOnly: effectiveBranchOnly, isDocsOnly, worktreePath });
+    // WU-1663: Preparation complete - transition to gating state
+    pipelineActor.send({ type: WU_DONE_EVENTS.PREPARATION_COMPLETE });
+    // WU-1663: Wrap gates in try/catch to send pipeline failure event
+    let gateExecutionResult;
+    try {
+        gateExecutionResult = await executeGates({
+            id,
+            args,
+            isBranchOnly: effectiveBranchOnly,
+            isDocsOnly,
+            worktreePath,
+        });
+    }
+    catch (gateErr) {
+        pipelineActor.send({
+            type: WU_DONE_EVENTS.GATES_FAILED,
+            error: getErrorMessage(gateErr),
+        });
+        pipelineActor.stop();
+        throw gateErr;
+    }
+    // WU-1663: Gates passed - transition from gating state.
+    // Use GATES_SKIPPED if checkpoint dedup allowed skip, GATES_PASSED otherwise.
+    if (gateExecutionResult.skippedByCheckpoint) {
+        pipelineActor.send({ type: WU_DONE_EVENTS.GATES_SKIPPED });
+    }
+    else {
+        pipelineActor.send({ type: WU_DONE_EVENTS.GATES_PASSED });
+    }
     // Print State HUD for visibility (WU-1215: extracted to printStateHUD function)
     printStateHUD({
         id,
@@ -2282,12 +2218,17 @@ async function main() {
         derivedWorktree: effectiveDerivedWorktree,
         STAMPS_DIR,
     });
-    // Step 0.5: Pre-flight validation - run ALL pre-commit hooks BEFORE merge
-    // This prevents partial completion states where merge succeeds but commit fails
-    // Validates all 8 gates: secrets, file size, ESLint, Prettier, TypeScript, audit, architecture, tasks
-    // WU-2308: Pass worktreePath to run audit from worktree (checks fixed deps, not stale main deps)
-    // WU-1145: Skip pre-flight when skipGates is true (pre-flight runs gates which was already skipped)
-    if (!args.skipGates) {
+    // Step 0.5: Pre-flight hook validation policy.
+    // WU-1659: Reuse Step 0 gate attestation/checkpoint and avoid duplicate full-suite execution.
+    const preCommitGateDecision = resolveWuDonePreCommitGateDecision({
+        skipGates: Boolean(args.skipGates),
+        fullGatesRanInCurrentRun: gateExecutionResult.fullGatesRanInCurrentRun,
+        skippedByCheckpoint: gateExecutionResult.skippedByCheckpoint,
+        checkpointId: gateExecutionResult.checkpointId,
+    });
+    console.log(`${LOG_PREFIX.DONE} ${preCommitGateDecision.message}`);
+    // Fallback path remains available if gate attestation is missing for any reason.
+    if (preCommitGateDecision.runPreCommitFullSuite) {
         const hookResult = await validateAllPreCommitHooks(id, worktreePath, {
             runGates: ({ cwd }) => runGates({ cwd, docsOnly: false }),
         });
@@ -2295,9 +2236,6 @@ async function main() {
             die('Pre-flight validation failed. Fix hook issues and try again.');
         }
     }
-    else {
-        console.log(`${LOG_PREFIX.DONE} Skipping pre-flight hook validation (--skip-gates)`);
-    }
     // Step 0.6: WU-1781 - Run tasks:validate preflight BEFORE any merge/push operations
     // This prevents deadlocks where validation fails after merge, leaving local main ahead of origin
     // Specifically catches stamp-status mismatches from legacy WUs that would block pre-push hooks
@@ -2358,6 +2296,12 @@ async function main() {
                 };
                 completionResult = await executeWorktreeCompletion(worktreeContext);
             }
+            // WU-1663: Mode-specific completion succeeded - send pipeline events.
+            // The completion modules handle commit, merge, and push internally.
+            // We send the corresponding pipeline events based on the completion result.
+            pipelineActor.send({ type: WU_DONE_EVENTS.COMMIT_COMPLETE });
+            pipelineActor.send({ type: WU_DONE_EVENTS.MERGE_COMPLETE });
+            pipelineActor.send({ type: WU_DONE_EVENTS.PUSH_COMPLETE });
             // Handle recovery mode (zombie state cleanup completed)
             if ('recovered' in completionResult && completionResult.recovered) {
                 // P0 FIX: Release lane lock before early exit
@@ -2369,30 +2313,28 @@ async function main() {
                 catch {
                     // Intentionally ignore lock release errors during cleanup
                 }
+                pipelineActor.stop();
                 process.exit(EXIT_CODES.SUCCESS);
             }
         }
         catch (err) {
-            // WU-1624: Failure-path lifecycle cleanup
-            // When mode execution fails before reaching post-merge cleanup, lifecycle metadata
-            // (especially wu-events.jsonl) can remain dirty on main and block future claims.
-            // Restore lifecycle-managed files before exiting so retries/re-claims can proceed.
-            if (!isBranchPR && !effectiveBranchOnly) {
-                try {
-                    const gitMainForFailureCleanup = getGitForCwd();
-                    const failureStatus = await gitMainForFailureCleanup.getStatus();
-                    const metadataDir = path.dirname(STATUS_PATH);
-                    const failureDirty = checkPostMergeDirtyState(failureStatus, id, metadataDir);
-                    const restoreTargets = getLifecycleRestoreTargetsOnFailure(failureDirty);
-                    if (restoreTargets.length > 0) {
-                        await gitMainForFailureCleanup.raw(['restore', '--', ...restoreTargets]);
-                        console.log(`${LOG_PREFIX.DONE} ${EMOJI.INFO} Restored lifecycle files after failed completion: ${restoreTargets.join(', ')}`);
-                    }
-                }
-                catch (cleanupErr) {
-                    console.warn(`${LOG_PREFIX.DONE} ${EMOJI.WARNING} Could not restore lifecycle files after failure: ${cleanupErr.message}`);
-                }
-            }
+            // WU-1663: Mode execution failed - determine which stage failed
+            // based on completion result flags and send appropriate failure event.
+            const failureStage = completionResult.committed === false
+                ? WU_DONE_EVENTS.COMMIT_FAILED
+                : completionResult.merged === false
+                    ? WU_DONE_EVENTS.MERGE_FAILED
+                    : completionResult.pushed === false
+                        ? WU_DONE_EVENTS.PUSH_FAILED
+                        : WU_DONE_EVENTS.COMMIT_FAILED; // Default to commit as earliest possible failure
+            pipelineActor.send({
+                type: failureStage,
+                error: getErrorMessage(err),
+            });
+            // WU-1663: Log pipeline state for diagnostics
+            const failedSnapshot = pipelineActor.getSnapshot();
+            console.error(`${LOG_PREFIX.DONE} Pipeline state: ${failedSnapshot.value} (failedAt: ${failedSnapshot.context.failedAt})`);
+            pipelineActor.stop();
             // P0 FIX: Release lane lock before error exit
             try {
                 const lane = docMain.lane;
@@ -2402,6 +2344,8 @@ async function main() {
             catch {
                 // Intentionally ignore lock release errors during error handling
             }
+            console.error(`\n${LOG_PREFIX.DONE} ${EMOJI.FAILURE} Mode execution failed: ${getErrorMessage(err)}`);
+            console.error(`${LOG_PREFIX.DONE} ${EMOJI.INFO} Next step: resolve the reported error and retry: pnpm wu:done --id ${id}`);
             // WU-1811: Check if cleanup is safe before removing worktree
             // If cleanupSafe is false (or undefined), preserve worktree for recovery
             if (err.cleanupSafe === false) {
@@ -2415,58 +2359,6 @@ async function main() {
     else {
         await ensureNoAutoStagedOrNoop([WU_PATH, STATUS_PATH, BACKLOG_PATH, STAMPS_DIR]);
     }
-    // WU-1084: Check for uncommitted changes on main after merge
-    // WU-1554: Pass metadataDir so metadata files are classified separately
-    const gitMain = getGitForCwd();
-    const currentBranch = await gitMain.getCurrentBranch();
-    const allowLifecycleAutoCommit = shouldAutoCommitLifecycleWrites(currentBranch);
-    const metadataDir = path.dirname(STATUS_PATH);
-    const postMergeStatus = await gitMain.getStatus();
-    const dirtyCheck = checkPostMergeDirtyState(postMergeStatus, id, metadataDir);
-    if (dirtyCheck.internalOnlyFiles.length > 0) {
-        try {
-            await gitMain.raw(['restore', '--', ...dirtyCheck.internalOnlyFiles]);
-            console.log(`${LOG_PREFIX.DONE} ${EMOJI.INFO} Restored internal lifecycle log files: ${dirtyCheck.internalOnlyFiles.join(', ')}`);
-        }
-        catch (restoreErr) {
-            console.warn(`${LOG_PREFIX.DONE} ${EMOJI.WARNING} Could not auto-restore internal lifecycle files: ${restoreErr.message}`);
-        }
-    }
-    // WU-1554: Auto-commit metadata files left dirty after merge+rebase
-    // This handles push-only claim mode and concurrent agent advancement
-    if (dirtyCheck.metadataFiles.length > 0) {
-        if (allowLifecycleAutoCommit) {
-            try {
-                await gitMain.add(dirtyCheck.metadataFiles);
-                await gitMain.commit(`chore: post-merge metadata sync for ${id} [skip ci]`);
-                await gitMain.raw(['pull', '--rebase', '--autostash', 'origin', currentBranch]);
-                await gitMain.push('origin', currentBranch);
-                console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Auto-committed post-merge metadata: ${dirtyCheck.metadataFiles.join(', ')}`);
-            }
-            catch (commitErr) {
-                console.warn(`${LOG_PREFIX.DONE} ${EMOJI.WARNING} Could not auto-commit metadata files: ${commitErr.message}`);
-            }
-        }
-        else {
-            try {
-                await gitMain.raw(['restore', '--', ...dirtyCheck.metadataFiles]);
-                console.log(`${LOG_PREFIX.DONE} ${EMOJI.INFO} Protected branch ${currentBranch}: restored lifecycle metadata files instead of committing on branch`);
-            }
-            catch (restoreErr) {
-                console.warn(`${LOG_PREFIX.DONE} ${EMOJI.WARNING} Could not restore metadata lifecycle files on protected branch ${currentBranch}: ${restoreErr.message}`);
-            }
-        }
-    }
-    const postLifecycleStatus = await gitMain.getStatus();
-    const postLifecycleDirty = checkPostMergeDirtyState(postLifecycleStatus, id, metadataDir);
-    if (!allowLifecycleAutoCommit && postLifecycleDirty.metadataFiles.length > 0) {
-        die(`Protected branch ${currentBranch} still has lifecycle metadata changes after wu:done:\n` +
-            `${postLifecycleDirty.metadataFiles.join(STRING_LITERALS.NEWLINE)}\n\n` +
-            `wu:done will not commit directly on ${currentBranch}. Resolve and retry from the WU worktree/lane branch.`);
-    }
-    if (postLifecycleDirty.isDirty) {
-        die(postLifecycleDirty.error);
-    }
     // Step 6 & 7: Cleanup (remove worktree, delete branch) - WU-1215
     // WU-1811: Only run cleanup if all completion steps succeeded
     if (completionResult.cleanupSafe !== false) {
@@ -2539,6 +2431,12 @@ async function main() {
         // Double fail-open: even if runDecayOnDone itself throws unexpectedly, never block wu:done
         console.warn(`${LOG_PREFIX.DONE} ${EMOJI.WARNING} Decay archival error (fail-open): ${getErrorMessage(err)}`);
     }
+    // WU-1663: Cleanup complete - transition to final done state
+    pipelineActor.send({ type: WU_DONE_EVENTS.CLEANUP_COMPLETE });
+    // WU-1663: Log final pipeline state for diagnostics
+    const finalSnapshot = pipelineActor.getSnapshot();
+    console.log(`${LOG_PREFIX.DONE} Pipeline state: ${finalSnapshot.value} (WU-1663)`);
+    pipelineActor.stop();
     console.log(`\n${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Transaction COMMIT - all steps succeeded (WU-755)`);
     console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Marked done, pushed, and cleaned up.`);
     console.log(`- WU: ${id} — ${title}`);
@@ -2555,7 +2453,11 @@ async function main() {
     // WU-1983: Migration deployment nudge - only if supabase paths in code_paths
     const codePaths = docMain.code_paths || [];
     await printMigrationDeploymentNudge(codePaths, mainCheckoutPath);
-    if (allowLifecycleAutoCommit) {
+    const currentBranch = (await getGitForCwd().getCurrentBranch()).trim();
+    const shouldRunCleanupMutations = currentBranch.length > 0 &&
+        currentBranch !== BRANCHES.MAIN &&
+        currentBranch !== BRANCHES.MASTER;
+    if (shouldRunCleanupMutations) {
         // WU-1366: Auto state cleanup after successful completion
         // Non-fatal: errors are logged but do not block completion
         await runAutoCleanupAfterDone(mainCheckoutPath);