@lumenflow/cli 1.1.0 → 1.3.2

package/dist/wu-claim.js

@@ -15,7 +15,7 @@
  * Full migration to thin shim pending @lumenflow/core CLI export implementation.
  */
 import { existsSync, readFileSync, rmSync } from 'node:fs';
-import { access, readFile, writeFile } from 'node:fs/promises';
+import { access, readFile, writeFile, mkdir } from 'node:fs/promises';
 import path from 'node:path';
 import { isOrphanWorktree } from '@lumenflow/core/dist/orphan-detector.js';
 // WU-1352: Use centralized YAML functions from wu-yaml.mjs
@@ -32,14 +32,15 @@ import { getGitForCwd, createGitForPath } from '@lumenflow/core/dist/git-adapter
 import { die } from '@lumenflow/core/dist/error-handler.js';
 import { createWUParser, WU_OPTIONS } from '@lumenflow/core/dist/arg-parser.js';
 import { WU_PATHS, getStateStoreDirFromBacklog } from '@lumenflow/core/dist/wu-paths.js';
-import { BRANCHES, REMOTES, WU_STATUS, CLAIMED_MODES, STATUS_SECTIONS, PATTERNS, toKebab, LOG_PREFIX, MICRO_WORKTREE_OPERATIONS, COMMIT_FORMATS, EMOJI, FILE_SYSTEM, STRING_LITERALS, } from '@lumenflow/core/dist/wu-constants.js';
+import { BRANCHES, REMOTES, WU_STATUS, CLAIMED_MODES, STATUS_SECTIONS, PATTERNS, toKebab, LOG_PREFIX, GIT_REFS, MICRO_WORKTREE_OPERATIONS, COMMIT_FORMATS, EMOJI, FILE_SYSTEM, STRING_LITERALS, } from '@lumenflow/core/dist/wu-constants.js';
 import { withMicroWorktree } from '@lumenflow/core/dist/micro-worktree.js';
-import { ensureOnMain } from '@lumenflow/core/dist/wu-helpers.js';
+import { ensureOnMain, ensureMainUpToDate } from '@lumenflow/core/dist/wu-helpers.js';
 import { emitWUFlowEvent } from '@lumenflow/core/dist/telemetry.js';
 import { checkLaneForOrphanDoneWU, repairWUInconsistency, } from '@lumenflow/core/dist/wu-consistency-checker.js';
 import { emitMandatoryAgentAdvisory } from '@lumenflow/core/dist/orchestration-advisory-loader.js';
 import { validateWU, generateAutoApproval } from '@lumenflow/core/dist/wu-schema.js';
 import { startSessionForWU } from '@lumenflow/agent/dist/auto-session-integration.js';
+import { getConfig } from '@lumenflow/core/dist/lumenflow-config.js';
 import { detectFixableIssues, applyFixes, autoFixWUYaml, formatIssues, } from '@lumenflow/core/dist/wu-yaml-fixer.js';
 import { validateSpecCompleteness } from '@lumenflow/core/dist/wu-done-validators.js';
 import { getAssignedEmail } from '@lumenflow/core/dist/wu-claim-helpers.js';
@@ -164,7 +165,7 @@ function validateYAMLSchema(WU_PATH, doc, args) {
 }
 // WU-1576: validateBacklogConsistency removed - repair now happens inside micro-worktree
 // See claimWorktreeMode() execute function for the new location
-async function updateWUYaml(WU_PATH, id, lane, claimedMode = 'worktree', worktreePath = null, sessionId = null) {
+async function updateWUYaml(WU_PATH, id, lane, claimedMode = 'worktree', worktreePath = null, sessionId = null, gitAdapter = null) {
     // Check file exists
     try {
         await access(WU_PATH);
@@ -223,16 +224,16 @@ async function updateWUYaml(WU_PATH, id, lane, claimedMode = 'worktree', worktre
     if (worktreePath) {
         doc.worktree_path = worktreePath;
     }
+    const git = gitAdapter || getGitForCwd();
     // WU-1423: Record owner using validated email (no silent username fallback)
     // Fallback chain: git config user.email > GIT_AUTHOR_EMAIL > error
     // WU-1427: getAssignedEmail is now async to properly await gitAdapter.getConfigValue
-    doc.assigned_to = await getAssignedEmail(getGitForCwd());
+    doc.assigned_to = await getAssignedEmail(git);
     // Record claim timestamp for duration tracking (WU-637)
     doc.claimed_at = new Date().toISOString();
     // WU-1382: Store baseline main SHA for parallel agent detection
     // wu:done will compare against this to detect if other WUs were merged during work
-    const git = getGitForCwd();
-    doc.baseline_main_sha = await git.getCommitHash('origin/main');
+    doc.baseline_main_sha = await git.getCommitHash(GIT_REFS.ORIGIN_MAIN);
     // WU-1438: Store agent session ID for tracking
     if (sessionId) {
         doc.session_id = sessionId;
@@ -357,6 +358,90 @@ export function getWorktreeCommitFiles(wuId) {
         // These generated files cause merge conflicts when main advances
     ];
 }
+function parseStagedChangeLine(line) {
+    const parts = line.trim().split(/\s+/);
+    const status = parts[0];
+    if (!status)
+        return null;
+    if (status.startsWith('R') || status.startsWith('C')) {
+        return { status, from: parts[1], filePath: parts[2] };
+    }
+    return { status, filePath: parts.slice(1).join(' ') };
+}
+async function getStagedChanges() {
+    const diff = await getGitForCwd().raw(['diff', '--cached', '--name-status']);
+    if (!diff.trim())
+        return [];
+    return diff
+        .split(STRING_LITERALS.NEWLINE)
+        .filter(Boolean)
+        .map(parseStagedChangeLine)
+        .filter(Boolean);
+}
+async function applyStagedChangesToMicroWorktree(worktreePath, stagedChanges) {
+    for (const change of stagedChanges) {
+        const filePath = change.filePath;
+        if (!filePath)
+            continue;
+        const targetPath = path.join(worktreePath, filePath);
+        if (change.status.startsWith('D')) {
+            rmSync(targetPath, { recursive: true, force: true });
+            continue;
+        }
+        const sourcePath = path.join(process.cwd(), filePath);
+        // eslint-disable-next-line security/detect-non-literal-fs-filename -- CLI tool applies staged files
+        const contents = await readFile(sourcePath, { encoding: FILE_SYSTEM.UTF8 });
+        await mkdir(path.dirname(targetPath), { recursive: true });
+        // eslint-disable-next-line security/detect-non-literal-fs-filename -- CLI tool applies staged files
+        await writeFile(targetPath, contents, { encoding: FILE_SYSTEM.UTF8 });
+    }
+}
+/**
+ * Update canonical claim state on origin/main using push-only micro-worktree.
+ * Ensures canonical state stays global while local main remains unchanged.
+ */
+async function applyCanonicalClaimUpdate(ctx, sessionId) {
+    const { args, id, laneK, worktree, WU_PATH, STATUS_PATH, BACKLOG_PATH, claimedMode, fixableIssues, stagedChanges, } = ctx;
+    const commitMsg = COMMIT_FORMATS.CLAIM(id.toLowerCase(), laneK);
+    const worktreePathForYaml = claimedMode === CLAIMED_MODES.BRANCH_ONLY ? null : path.resolve(worktree);
+    let updatedTitle = '';
+    const filesToCommit = args.noAuto && stagedChanges.length > 0
+        ? stagedChanges.map((change) => change.filePath).filter(Boolean)
+        : [WU_PATHS.WU(id), WU_PATHS.STATUS(), WU_PATHS.BACKLOG(), '.beacon/state/wu-events.jsonl'];
+    console.log(`${PREFIX} Updating canonical claim state (push-only)...`);
+    await withMicroWorktree({
+        operation: MICRO_WORKTREE_OPERATIONS.WU_CLAIM,
+        id,
+        logPrefix: PREFIX,
+        pushOnly: true,
+        execute: async ({ worktreePath }) => {
+            const microWUPath = path.join(worktreePath, WU_PATH);
+            const microStatusPath = path.join(worktreePath, STATUS_PATH);
+            const microBacklogPath = path.join(worktreePath, BACKLOG_PATH);
+            if (args.noAuto) {
+                await applyStagedChangesToMicroWorktree(worktreePath, stagedChanges);
+            }
+            else {
+                if (fixableIssues && fixableIssues.length > 0) {
+                    console.log(`${PREFIX} Applying ${fixableIssues.length} YAML fix(es)...`);
+                    autoFixWUYaml(microWUPath);
+                    console.log(`${PREFIX} YAML fixes applied successfully`);
+                }
+                const microGit = createGitForPath(worktreePath);
+                updatedTitle =
+                    (await updateWUYaml(microWUPath, id, args.lane, claimedMode, worktreePathForYaml, sessionId, microGit)) || updatedTitle;
+                await addOrReplaceInProgressStatus(microStatusPath, id, updatedTitle);
+                await removeFromReadyAndAddToInProgressBacklog(microBacklogPath, id, updatedTitle, args.lane);
+            }
+            return {
+                commitMessage: commitMsg,
+                files: filesToCommit,
+            };
+        },
+    });
+    console.log(`${PREFIX} Canonical claim state updated on origin/main`);
+    return updatedTitle;
+}
 async function readWUTitle(id) {
     const p = WU_PATHS.WU(id);
     // Check file exists
@@ -617,51 +702,44 @@ async function validateBranchOnlyMode(STATUS_PATH, id) {
  * Execute branch-only mode claim workflow
  */
 async function claimBranchOnlyMode(ctx) {
-    const { args, id, laneK, title, branch, WU_PATH, STATUS_PATH, BACKLOG_PATH, claimedMode } = ctx;
-    // WU-1438: Start agent session BEFORE metadata update to include session_id in YAML
-    let sessionId = null;
+    const { args, id, laneK, title, branch, WU_PATH, STATUS_PATH, BACKLOG_PATH, claimedMode, sessionId, updatedTitle, } = ctx;
+    // Create branch and switch to it from origin/main (avoids local main mutation)
     try {
-        const sessionResult = await startSessionForWU({
-            wuId: id,
-            tier: 2,
-        });
-        sessionId = sessionResult.sessionId;
-        if (sessionResult.alreadyActive) {
-            console.log(`${PREFIX} Agent session already active (${sessionId.slice(0, 8)}...)`);
+        await getGitForCwd().createBranch(branch, `${REMOTES.ORIGIN}/${BRANCHES.MAIN}`);
+    }
+    catch (error) {
+        die(`Canonical claim state may be updated, but branch creation failed.\n\n` +
+            `Error: ${error.message}\n\n` +
+            `Recovery:\n` +
+            `  1. Run: git fetch ${REMOTES.ORIGIN} ${BRANCHES.MAIN}\n` +
+            `  2. Retry: pnpm wu:claim --id ${id} --lane "${args.lane}"\n` +
+            `  3. If needed, delete local branch: git branch -D ${branch}`);
+    }
+    let finalTitle = updatedTitle || title;
+    const msg = COMMIT_FORMATS.CLAIM(id.toLowerCase(), laneK);
+    if (args.noPush) {
+        if (args.noAuto) {
+            await ensureCleanOrClaimOnlyWhenNoAuto();
         }
         else {
-            console.log(`${PREFIX} ${EMOJI.SUCCESS} Agent session started (${sessionId.slice(0, 8)}...)`);
+            finalTitle =
+                (await updateWUYaml(WU_PATH, id, args.lane, claimedMode, null, sessionId)) || finalTitle;
+            await addOrReplaceInProgressStatus(STATUS_PATH, id, finalTitle);
+            await removeFromReadyAndAddToInProgressBacklog(BACKLOG_PATH, id, finalTitle, args.lane);
+            await getGitForCwd().add(`${JSON.stringify(WU_PATH)} ${JSON.stringify(STATUS_PATH)} ${JSON.stringify(BACKLOG_PATH)}`);
         }
-    }
-    catch (err) {
-        // Non-blocking: session start failure should not block claim
-        console.warn(`${PREFIX} Warning: Could not start agent session: ${err.message}`);
-    }
-    // Create branch and switch to it (LEGACY - for constrained environments only)
-    await getGitForCwd().createBranch(branch, BRANCHES.MAIN);
-    // Update metadata in branch-only mode (on main checkout)
-    let updatedTitle = title;
-    if (args.noAuto) {
-        await ensureCleanOrClaimOnlyWhenNoAuto();
+        await getGitForCwd().commit(msg);
+        console.warn(`${PREFIX} Warning: --no-push enabled. Claim is local-only and NOT visible to other agents.`);
     }
     else {
-        updatedTitle =
-            (await updateWUYaml(WU_PATH, id, args.lane, claimedMode, null, sessionId)) || title;
-        await addOrReplaceInProgressStatus(STATUS_PATH, id, updatedTitle);
-        await removeFromReadyAndAddToInProgressBacklog(BACKLOG_PATH, id, updatedTitle, args.lane);
-        await getGitForCwd().add(`${JSON.stringify(WU_PATH)} ${JSON.stringify(STATUS_PATH)} ${JSON.stringify(BACKLOG_PATH)}`);
+        await getGitForCwd().push(REMOTES.ORIGIN, branch, { setUpstream: true });
     }
-    // Commit and push
-    const msg = COMMIT_FORMATS.CLAIM(id.toLowerCase(), laneK);
-    await getGitForCwd().commit(msg);
-    await getGitForCwd().push(REMOTES.ORIGIN, branch);
     // Summary
     console.log(`\n${PREFIX} Claim recorded in Branch-Only mode.`);
-    console.log(`- WU: ${id}${updatedTitle ? ` — ${updatedTitle}` : ''}`);
+    console.log(`- WU: ${id}${finalTitle ? ` — ${finalTitle}` : ''}`);
     console.log(`- Lane: ${args.lane}`);
     console.log(`- Mode: Branch-Only (no worktree)`);
-    console.log(`- Commit: ${msg}`);
-    console.log(`- Branch: ${branch}`);
+    console.log(`${args.noPush ? `- Commit: ${msg}` : `- Branch: ${branch}`}`);
     console.log('\n⚠️  LIMITATION: Branch-Only mode does not support parallel WUs (WIP=1 across ALL lanes)');
     console.log('Next: work on this branch in the main checkout.');
     // WU-1360: Print next-steps checklist to prevent common mistakes
@@ -706,97 +784,95 @@ async function claimBranchOnlyMode(ctx) {
  */
 async function claimWorktreeMode(ctx) {
     const { args, id, laneK, title, branch, worktree, WU_PATH, BACKLOG_PATH, claimedMode, fixableIssues, // Fixable issues from pre-flight validation
-     } = ctx;
+    sessionId, updatedTitle, stagedChanges, } = ctx;
     const originalCwd = process.cwd();
     const worktreePath = path.resolve(worktree);
-    let updatedTitle = title;
+    let finalTitle = updatedTitle || title;
     const commitMsg = COMMIT_FORMATS.CLAIM(id.toLowerCase(), laneK);
-    // WU-1438: Start agent session BEFORE metadata update to include session_id in YAML
-    let sessionId = null;
-    try {
-        const sessionResult = await startSessionForWU({
-            wuId: id,
-            tier: 2,
-        });
-        sessionId = sessionResult.sessionId;
-        if (sessionResult.alreadyActive) {
-            console.log(`${PREFIX} Agent session already active (${sessionId.slice(0, 8)}...)`);
-        }
-        else {
-            console.log(`${PREFIX} ${EMOJI.SUCCESS} Agent session started (${sessionId.slice(0, 8)}...)`);
-        }
-    }
-    catch (err) {
-        // Non-blocking: session start failure should not block claim
-        console.warn(`${PREFIX} Warning: Could not start agent session: ${err.message}`);
-    }
     // WU-1741: Step 1 - Create work worktree+branch from main
     // Branch creation IS the coordination lock (git prevents duplicate branch names)
     console.log(`${PREFIX} Creating worktree (branch = coordination lock)...`);
-    await getGitForCwd().worktreeAdd(worktree, branch, BRANCHES.MAIN);
+    const startPoint = args.noPush ? BRANCHES.MAIN : `${REMOTES.ORIGIN}/${BRANCHES.MAIN}`;
+    await getGitForCwd().worktreeAdd(worktree, branch, startPoint);
     console.log(`${PREFIX} ${EMOJI.SUCCESS} Worktree created at ${worktree}`);
-    // WU-1741: Step 2 - Update metadata IN the work worktree (not main)
-    if (!args.noAuto) {
-        // Build paths relative to work worktree
-        const wtWUPath = path.join(worktreePath, WU_PATH);
-        const wtBacklogPath = path.join(worktreePath, BACKLOG_PATH);
-        // Apply YAML fixes in worktree (not on main)
-        if (fixableIssues && fixableIssues.length > 0) {
-            console.log(`${PREFIX} Applying ${fixableIssues.length} YAML fix(es)...`);
-            autoFixWUYaml(wtWUPath);
-            console.log(`${PREFIX} YAML fixes applied successfully`);
+    if (!args.noPush) {
+        const wtGit = createGitForPath(worktreePath);
+        await wtGit.push(REMOTES.ORIGIN, branch, { setUpstream: true });
+    }
+    if (args.noPush) {
+        // Local-only claim (air-gapped) - update metadata inside worktree branch
+        if (args.noAuto) {
+            await applyStagedChangesToMicroWorktree(worktreePath, stagedChanges);
+        }
+        else {
+            const wtWUPath = path.join(worktreePath, WU_PATH);
+            const wtBacklogPath = path.join(worktreePath, BACKLOG_PATH);
+            if (fixableIssues && fixableIssues.length > 0) {
+                console.log(`${PREFIX} Applying ${fixableIssues.length} YAML fix(es)...`);
+                autoFixWUYaml(wtWUPath);
+                console.log(`${PREFIX} YAML fixes applied successfully`);
+            }
+            finalTitle =
+                (await updateWUYaml(wtWUPath, id, args.lane, claimedMode, worktree, sessionId)) ||
+                    finalTitle;
+            // WU-1746: Only append claim event to state store - don't regenerate backlog.md/status.md
+            const wtStateDir = getStateStoreDirFromBacklog(wtBacklogPath);
+            await appendClaimEventOnly(wtStateDir, id, finalTitle, args.lane);
         }
-        // Update metadata files in worktree (WU-1438: include session_id)
-        updatedTitle =
-            (await updateWUYaml(wtWUPath, id, args.lane, claimedMode, worktree, sessionId)) || title;
-        // WU-1746: Only append claim event to state store - don't regenerate backlog.md/status.md
-        // These generated files cause merge conflicts when committed to worktrees
-        const wtStateDir = getStateStoreDirFromBacklog(wtBacklogPath);
-        await appendClaimEventOnly(wtStateDir, id, updatedTitle, args.lane);
-        // WU-1741: Step 3 - Commit metadata in worktree (NOT on main)
-        // This commit stays on the lane branch until wu:done merges to main
         console.log(`${PREFIX} Committing claim metadata in worktree...`);
         const wtGit = createGitForPath(worktreePath);
-        // WU-1746: Use getWorktreeCommitFiles which excludes backlog.md and status.md
         const filesToCommit = getWorktreeCommitFiles(id);
         await wtGit.add(filesToCommit);
         await wtGit.commit(commitMsg);
         console.log(`${PREFIX} ${EMOJI.SUCCESS} Claim committed: ${commitMsg}`);
+        console.warn(`${PREFIX} Warning: --no-push enabled. Claim is local-only and NOT visible to other agents.`);
     }
-    // WU-1443: Auto-symlink node_modules for immediate pnpm usability
-    // WU-2238: Pass mainRepoPath to detect broken worktree-path symlinks
-    const symlinkResult = symlinkNodeModules(worktreePath, console, originalCwd);
-    if (symlinkResult.created) {
-        console.log(`${PREFIX} ${EMOJI.SUCCESS} node_modules symlinked for immediate use`);
+    // WU-1023: Auto-setup worktree dependencies
+    // By default, run pnpm install to ensure all dependencies are built (including CLI dist)
+    // Use --skip-setup to use symlink-only approach for faster claims when deps are already built
+    if (args.skipSetup) {
+        // WU-1443: Symlink-only mode for fast claims
+        // WU-2238: Pass mainRepoPath to detect broken worktree-path symlinks
+        const symlinkResult = symlinkNodeModules(worktreePath, console, originalCwd);
+        if (symlinkResult.created) {
+            console.log(`${PREFIX} ${EMOJI.SUCCESS} node_modules symlinked (--skip-setup mode)`);
+        }
+        else if (symlinkResult.refused) {
+            console.warn(`${PREFIX} Warning: symlink refused: ${symlinkResult.reason}`);
+            console.warn(`${PREFIX} Run 'pnpm install' manually in the worktree`);
+        }
+        // WU-1579: Auto-symlink nested package node_modules for turbo typecheck
+        if (!symlinkResult.refused) {
+            const nestedResult = symlinkNestedNodeModules(worktreePath, originalCwd);
+            if (nestedResult.created > 0) {
+                console.log(`${PREFIX} ${EMOJI.SUCCESS} ${nestedResult.created} nested node_modules symlinked for typecheck`);
+            }
+        }
     }
-    else if (symlinkResult.refused) {
-        // WU-2238: Symlinking was refused due to worktree-path symlinks
-        // Fall back to running pnpm install in the worktree
-        console.log(`${PREFIX} Running pnpm install in worktree (symlink refused: ${symlinkResult.reason})`);
+    else {
+        // WU-1023: Full setup mode (default) - run pnpm install with progress indicator
+        // This ensures CLI dist is built and all dependencies are properly resolved
+        console.log(`${PREFIX} Installing worktree dependencies (this may take a moment)...`);
         try {
             const { execSync } = await import('node:child_process');
             execSync('pnpm install --frozen-lockfile', {
                 cwd: worktreePath,
-                stdio: 'inherit',
-                timeout: 120000, // 2 minute timeout
+                stdio: 'inherit', // Shows progress output from pnpm
+                timeout: 300000, // 5 minute timeout for full install
             });
-            console.log(`${PREFIX} ${EMOJI.SUCCESS} pnpm install completed in worktree`);
+            console.log(`${PREFIX} ${EMOJI.SUCCESS} Worktree dependencies installed`);
         }
         catch (installError) {
+            // Non-fatal: warn but don't block claim
             console.warn(`${PREFIX} Warning: pnpm install failed: ${installError.message}`);
             console.warn(`${PREFIX} You may need to run 'pnpm install' manually in the worktree`);
-        }
-    }
-    // WU-1579: Auto-symlink nested package node_modules for turbo typecheck
-    // WU-2238: Skip nested symlinks if root symlink was refused (pnpm install handles them)
-    if (!symlinkResult.refused) {
-        const nestedResult = symlinkNestedNodeModules(worktreePath, originalCwd);
-        if (nestedResult.created > 0) {
-            console.log(`${PREFIX} ${EMOJI.SUCCESS} ${nestedResult.created} nested node_modules symlinked for typecheck`);
+            // Fall back to symlink approach so worktree is at least somewhat usable
+            console.log(`${PREFIX} Falling back to symlink approach...`);
+            applyFallbackSymlinks(worktreePath, originalCwd, console);
         }
     }
     console.log(`${PREFIX} Claim recorded in worktree`);
-    console.log(`- WU: ${id}${updatedTitle ? ` — ${updatedTitle}` : ''}`);
+    console.log(`- WU: ${id}${finalTitle ? ` — ${finalTitle}` : ''}`);
     console.log(`- Lane: ${args.lane}`);
     console.log(`- Worktree: ${worktreePath}`);
     console.log(`- Branch: ${branch}`);
@@ -827,9 +903,44 @@ async function claimWorktreeMode(ctx) {
     const wuDoc = parseYAML(wuContent);
     const codePaths = wuDoc.code_paths || [];
     emitMandatoryAgentAdvisory(codePaths, id);
+    // WU-1047: Emit agent-only project defaults from config
+    const config = getConfig();
+    printProjectDefaults(config?.agents?.methodology);
     // WU-1763: Print lifecycle nudge with tips for tool adoption
     printLifecycleNudge(id);
 }
+/**
+ * WU-1047: Format Project Defaults section (agent-only).
+ *
+ * @param {object} methodology - Methodology defaults config
+ * @returns {string} Formatted output or empty string if disabled
+ */
+export function formatProjectDefaults(methodology) {
+    if (!methodology || methodology.enabled === false)
+        return '';
+    const enforcement = methodology.enforcement || 'required';
+    const principles = Array.isArray(methodology.principles) ? methodology.principles : [];
+    const lines = [
+        `${PREFIX} 🧭 Project Defaults (agent-only)`,
+        `  Enforcement: ${enforcement}`,
+        `  Principles: ${principles.length > 0 ? principles.join(', ') : 'None'}`,
+    ];
+    if (methodology.notes) {
+        lines.push(`  Notes: ${methodology.notes}`);
+    }
+    return `\n${lines.join('\n')}`;
+}
+/**
+ * WU-1047: Print Project Defaults section (agent-only).
+ *
+ * @param {object} methodology - Methodology defaults config
+ */
+export function printProjectDefaults(methodology) {
+    const output = formatProjectDefaults(methodology);
+    if (output) {
+        console.log(output);
+    }
+}
 /**
  * WU-1763: Print a single concise tips line to improve tool adoption.
  * Non-blocking, single-line output to avoid flooding the console.
@@ -840,6 +951,27 @@ export function printLifecycleNudge(_id) {
     // Single line, concise, actionable
     console.log(`\n${PREFIX} 💡 Tip: pnpm session:recommend for context tier, mem:ready for pending work, pnpm file:*/git:* for audited wrappers`);
 }
+/**
+ * WU-1029: Apply symlink fallback (root + nested node_modules) after install failure.
+ *
+ * @param {string} worktreePath - Worktree path
+ * @param {string} mainRepoPath - Main repo path
+ * @param {Console} logger - Logger (console-compatible)
+ */
+export function applyFallbackSymlinks(worktreePath, mainRepoPath, logger = console) {
+    const symlinkResult = symlinkNodeModules(worktreePath, logger, mainRepoPath);
+    if (symlinkResult.created) {
+        logger.log(`${PREFIX} ${EMOJI.SUCCESS} node_modules symlinked as fallback`);
+    }
+    let nestedResult = null;
+    if (!symlinkResult.refused) {
+        nestedResult = symlinkNestedNodeModules(worktreePath, mainRepoPath);
+        if (nestedResult.created > 0) {
+            logger.log(`${PREFIX} ${EMOJI.SUCCESS} ${nestedResult.created} nested node_modules symlinked for typecheck`);
+        }
+    }
+    return { symlinkResult, nestedResult };
+}
 /**
  * WU-2411: Handle --resume flag for agent handoff
  *
@@ -929,6 +1061,8 @@ async function main() {
             WU_OPTIONS.reason,
             WU_OPTIONS.allowIncomplete,
             WU_OPTIONS.resume, // WU-2411: Agent handoff flag
+            WU_OPTIONS.skipSetup, // WU-1023: Skip auto-setup for fast claims
+            WU_OPTIONS.noPush, // Skip pushing claim state/branch (air-gapped)
         ],
         required: ['id', 'lane'],
         allowPositionalId: true,
@@ -954,9 +1088,19 @@ async function main() {
                 `  3. Use --no-auto if you already staged claim edits manually`);
         }
     }
-    // WU-1361: Fetch and pull FIRST - validate on fresh data, not stale pre-pull data
-    await getGitForCwd().fetch(REMOTES.ORIGIN, BRANCHES.MAIN);
-    await getGitForCwd().pull(REMOTES.ORIGIN, BRANCHES.MAIN);
+    let stagedChanges = [];
+    if (args.noAuto) {
+        await ensureCleanOrClaimOnlyWhenNoAuto();
+        stagedChanges = await getStagedChanges();
+    }
+    // WU-1361: Fetch latest remote before validation (no local main mutation)
+    if (!args.noPush) {
+        await getGitForCwd().fetch(REMOTES.ORIGIN, BRANCHES.MAIN);
+        await ensureMainUpToDate(getGitForCwd(), 'wu:claim');
+    }
+    else {
+        console.warn(`${PREFIX} Warning: --no-push enabled. Skipping origin/main sync; local state may be stale.`);
+    }
     const WU_PATH = WU_PATHS.WU(id);
     const STATUS_PATH = WU_PATHS.STATUS();
     const BACKLOG_PATH = WU_PATHS.BACKLOG();
@@ -1050,7 +1194,18 @@ async function main() {
         if (args.branchOnly) {
             await validateBranchOnlyMode(STATUS_PATH, id);
         }
-        // Check if branch already exists (prevents duplicate claims)
+        // Check if remote branch already exists (prevents duplicate global claims)
+        if (!args.noPush) {
+            const remoteExists = await getGitForCwd().remoteBranchExists(REMOTES.ORIGIN, branch);
+            if (remoteExists) {
+                die(`Remote branch ${REMOTES.ORIGIN}/${branch} already exists. WU may already be claimed.\n\n` +
+                    `Options:\n` +
+                    `  1. Coordinate with the owning agent or wait for completion\n` +
+                    `  2. Choose a different WU\n` +
+                    `  3. Use --no-push for local-only claims (offline)`);
+            }
+        }
+        // Check if branch already exists locally (prevents duplicate claims)
         const branchAlreadyExists = await getGitForCwd().branchExists(branch);
         if (branchAlreadyExists) {
             die(`Branch ${branch} already exists. WU may already be claimed.\n\n` +
@@ -1075,8 +1230,27 @@ async function main() {
                     `Manual cleanup: rm -rf ${absoluteWorktreePath}`);
             }
         }
+        // WU-1438: Start agent session BEFORE metadata update to include session_id in YAML
+        let sessionId = null;
+        try {
+            const sessionResult = await startSessionForWU({
+                wuId: id,
+                tier: 2,
+            });
+            sessionId = sessionResult.sessionId;
+            if (sessionResult.alreadyActive) {
+                console.log(`${PREFIX} Agent session already active (${sessionId.slice(0, 8)}...)`);
+            }
+            else {
+                console.log(`${PREFIX} ${EMOJI.SUCCESS} Agent session started (${sessionId.slice(0, 8)}...)`);
+            }
+        }
+        catch (err) {
+            // Non-blocking: session start failure should not block claim
+            console.warn(`${PREFIX} Warning: Could not start agent session: ${err.message}`);
+        }
         // Execute claim workflow
-        const ctx = {
+        const baseCtx = {
             args,
             id,
             laneK,
@@ -1088,6 +1262,18 @@ async function main() {
             BACKLOG_PATH,
             claimedMode,
             fixableIssues, // WU-1361: Pass fixable issues for worktree application
+            stagedChanges,
+        };
+        let updatedTitle = title;
+        if (!args.noPush) {
+            updatedTitle = (await applyCanonicalClaimUpdate(baseCtx, sessionId)) || updatedTitle;
+            // Refresh origin/main after push-only update so worktrees start from canonical state
+            await getGitForCwd().fetch(REMOTES.ORIGIN, BRANCHES.MAIN);
+        }
+        const ctx = {
+            ...baseCtx,
+            sessionId,
+            updatedTitle,
         };
         if (args.branchOnly) {
             await claimBranchOnlyMode(ctx);
@@ -1112,6 +1298,7 @@ async function main() {
 }
 // Guard main() for testability (WU-1366)
 import { fileURLToPath } from 'node:url';
+import { runCLI } from './cli-entry-point.js';
 if (process.argv[1] === fileURLToPath(import.meta.url)) {
-    main();
+    runCLI(main);
 }