@lumenflow/core 2.2.2 → 2.3.1

package/dist/micro-worktree.js

@@ -1,7 +1,7 @@
 /**
  * Micro-Worktree Operations
  *
- * Race-safe micro-worktree isolation pattern extracted from wu-create.mjs (WU-1262).
+ * Race-safe micro-worktree isolation pattern extracted from wu-create.ts (WU-1262).
  * Provides shared infrastructure for commands that need to modify main branch
  * atomically without switching checkout.
  *
@@ -23,9 +23,9 @@
  * - Cleanup guaranteed even on failure
  *
  * Consumers:
- * @see {@link tools/wu-create.mjs} - WU creation (WU-1262, WU-1439)
- * @see {@link tools/wu-edit.mjs} - Spec edits (WU-1274)
- * @see {@link tools/initiative-create.mjs} - Initiative creation (WU-1439)
+ * @see {@link packages/@lumenflow/cli/src/wu-create.ts} - WU creation (WU-1262, WU-1439)
+ * @see {@link packages/@lumenflow/cli/src/wu-edit.ts} - Spec edits (WU-1274)
+ * @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';
@@ -40,6 +40,14 @@ import { BRANCHES, REMOTES, GIT_REFS, PKG_MANAGER, SCRIPTS, PRETTIER_FLAGS, STDI
  * 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.
+ */
+export const MAX_PUSH_RETRIES = 3;
 /**
  * Environment variable name for LUMENFLOW_FORCE bypass
  *
@@ -136,7 +144,8 @@ export async function cleanupOrphanedMicroWorktree(operation, id, gitAdapter, lo
                 cleanedWorktree = true;
             }
             catch (err) {
-                console.warn(`${logPrefix} ⚠️  Could not remove orphaned worktree: ${err.message}`);
+                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;
@@ -144,7 +153,8 @@ export async function cleanupOrphanedMicroWorktree(operation, id, gitAdapter, lo
         }
     }
     catch (err) {
-        console.warn(`${logPrefix} ⚠️  Could not check worktree list: ${err.message}`);
+        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 {
@@ -157,7 +167,8 @@ export async function cleanupOrphanedMicroWorktree(operation, id, gitAdapter, lo
         }
     }
     catch (err) {
-        console.warn(`${logPrefix} ⚠️  Could not delete orphaned branch: ${err.message}`);
+        const errMsg = err instanceof Error ? err.message : String(err);
+        console.warn(`${logPrefix} ⚠️  Could not delete orphaned branch: ${errMsg}`);
     }
     return { cleanedWorktree, cleanedBranch };
 }
@@ -198,7 +209,8 @@ async function removeWorktreeSafe(gitAdapter, worktreePath, logPrefix, contextLa
         }
     }
     catch (err) {
-        console.warn(`${logPrefix} ⚠️  Could not remove${label} worktree: ${err.message}`);
+        const errMsg = err instanceof Error ? err.message : String(err);
+        console.warn(`${logPrefix} ⚠️  Could not remove${label} worktree: ${errMsg}`);
         tryFilesystemCleanup(worktreePath);
     }
 }
@@ -249,7 +261,8 @@ async function cleanupRegisteredWorktreeForBranch(gitAdapter, branchName, expect
         }
     }
     catch (err) {
-        console.warn(`${logPrefix} ⚠️  Could not check worktree list: ${err.message}`);
+        const errMsg = err instanceof Error ? err.message : String(err);
+        console.warn(`${logPrefix} ⚠️  Could not check worktree list: ${errMsg}`);
     }
 }
 /**
@@ -269,7 +282,8 @@ async function deleteBranchSafe(gitAdapter, branchName, logPrefix) {
         }
     }
     catch (err) {
-        console.warn(`${logPrefix} ⚠️  Could not delete branch: ${err.message}`);
+        const errMsg = err instanceof Error ? err.message : String(err);
+        console.warn(`${logPrefix} ⚠️  Could not delete branch: ${errMsg}`);
     }
 }
 /**
@@ -307,6 +321,7 @@ export async function formatFiles(files, worktreePath, logPrefix = DEFAULT_LOG_P
     const absolutePaths = files.map((f) => join(worktreePath, f));
     const pathArgs = absolutePaths.map((p) => JSON.stringify(p)).join(' ');
     try {
+        // eslint-disable-next-line sonarjs/os-command -- CLI tool executing known safe prettier command with validated paths
         execSync(`${PKG_MANAGER} ${SCRIPTS.PRETTIER} ${PRETTIER_FLAGS.WRITE} ${pathArgs}`, {
             encoding: 'utf-8',
             stdio: STDIO_MODES.PIPE,
@@ -316,7 +331,8 @@ export async function formatFiles(files, worktreePath, logPrefix = DEFAULT_LOG_P
     }
     catch (err) {
         // Log warning but don't fail - some files may not need formatting
-        console.warn(`${logPrefix} ⚠️  Formatting warning: ${err.message}`);
+        const errMsg = err instanceof Error ? err.message : String(err);
+        console.warn(`${logPrefix} ⚠️  Formatting warning: ${errMsg}`);
     }
 }
 /**
@@ -349,9 +365,64 @@ export async function mergeWithRetry(tempBranchName, microWorktreePath, logPrefi
                 await gitWorktree.rebase(BRANCHES.MAIN);
             }
             else {
+                const errMsg = mergeErr instanceof Error ? mergeErr.message : String(mergeErr);
                 throw new Error(`FF-only merge failed after ${MAX_MERGE_RETRIES} attempts. ` +
                     `Main branch may have significant divergence.\n` +
-                    `Error: ${mergeErr.message}`);
+                    `Error: ${errMsg}`);
+            }
+        }
+    }
+}
+/**
+ * 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.
+ *
+ * This prevents the scenario where local main is left diverged from origin
+ * after a push failure.
+ *
+ * @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
+ * @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++) {
+        try {
+            console.log(`${logPrefix} Pushing to ${remote}/${branch} (attempt ${attempt}/${MAX_PUSH_RETRIES})...`);
+            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
+                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
+                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` +
+                    `Error: ${errMsg}`);
             }
         }
     }
@@ -388,13 +459,13 @@ export async function pushRefspecWithForce(gitAdapter, remote, localRef, remoteR
     finally {
         // Restore original env values
         if (originalForce === undefined) {
-            delete process.env[LUMENFLOW_FORCE_ENV];
+            Reflect.deleteProperty(process.env, LUMENFLOW_FORCE_ENV);
         }
         else {
             process.env[LUMENFLOW_FORCE_ENV] = originalForce;
         }
         if (originalReason === undefined) {
-            delete process.env[LUMENFLOW_FORCE_REASON_ENV];
+            Reflect.deleteProperty(process.env, LUMENFLOW_FORCE_REASON_ENV);
         }
         else {
             process.env[LUMENFLOW_FORCE_REASON_ENV] = originalReason;
@@ -428,6 +499,15 @@ 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
+    if (!pushOnly) {
+        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}`);
+    }
     const tempBranchName = getTempBranchName(operation, id);
     const microWorktreePath = createMicroWorktreeDir(`${operation}-`);
     console.log(`${logPrefix} Using micro-worktree isolation (WU-1262)`);
@@ -471,10 +551,11 @@ export async function withMicroWorktree(options) {
         }
         else {
             // Standard path: merge to local main, then push
+            const gitWorktree = createGitForPath(microWorktreePath);
             await mergeWithRetry(tempBranchName, microWorktreePath, logPrefix);
-            console.log(`${logPrefix} Pushing to ${REMOTES.ORIGIN}/${BRANCHES.MAIN}...`);
-            await mainGit.push(REMOTES.ORIGIN, BRANCHES.MAIN);
-            console.log(`${logPrefix} ✅ Pushed to ${REMOTES.ORIGIN}/${BRANCHES.MAIN}`);
+            // WU-1179: Use pushWithRetry to handle race conditions
+            // On push failure, rollback local main and retry with rebase
+            await pushWithRetry(mainGit, gitWorktree, REMOTES.ORIGIN, BRANCHES.MAIN, tempBranchName, logPrefix);
             return { ...result, ref: BRANCHES.MAIN };
         }
     }

package/dist/migration-deployer.d.ts

@@ -1,5 +1,5 @@
 /**
- * @file migration-deployer.mjs
+ * @file migration-deployer.ts
  * @description Migration deployment utilities for Supabase schema sync
  * WU-1983: Sync production schema and establish migration deployment workflow
  *

package/dist/migration-deployer.js

@@ -1,5 +1,5 @@
 /**
- * @file migration-deployer.mjs
+ * @file migration-deployer.ts
  * @description Migration deployment utilities for Supabase schema sync
  * WU-1983: Sync production schema and establish migration deployment workflow
  *

package/dist/orchestration-advisory-loader.d.ts

@@ -5,8 +5,8 @@
  * Uses minimatch for glob pattern matching (same as TypeScript version).
  *
  * @module orchestration-advisory-loader
- * @see {@link ./orchestration-advisory.mjs} - TypeScript version for tests
- * @see {@link ./domain/orchestration.constants.mjs} - Pattern definitions
+ * @see {@link ./orchestration-advisory.ts} - TypeScript version for tests
+ * @see {@link ./domain/orchestration.constants.ts} - Pattern definitions
  */
 /**
  * Emit mandatory agent advisory based on code paths.

package/dist/orchestration-advisory-loader.js

@@ -5,18 +5,22 @@
  * Uses minimatch for glob pattern matching (same as TypeScript version).
  *
  * @module orchestration-advisory-loader
- * @see {@link ./orchestration-advisory.mjs} - TypeScript version for tests
- * @see {@link ./domain/orchestration.constants.mjs} - Pattern definitions
+ * @see {@link ./orchestration-advisory.ts} - TypeScript version for tests
+ * @see {@link ./domain/orchestration.constants.ts} - Pattern definitions
  */
 import { minimatch } from 'minimatch';
 import picocolors from 'picocolors';
 /**
  * Mandatory agent trigger patterns.
- * Mirrors MANDATORY_TRIGGERS from orchestration.constants.mjs.
+ * Mirrors MANDATORY_TRIGGERS from orchestration.constants.ts.
+ *
+ * Note: For LumenFlow framework development, this is empty since we don't have
+ * application-specific concerns like PHI, auth, or RLS. Projects using LumenFlow
+ * should configure their own triggers based on their domain requirements.
  */
 const MANDATORY_TRIGGERS = {
-    'security-auditor': ['supabase/migrations/**', '**/auth/**', '**/rls/**', '**/permissions/**'],
-    'beacon-guardian': ['**/prompts/**', '**/classification/**', '**/detector/**', '**/llm/**'],
+// No mandatory triggers for LumenFlow framework development.
+// Projects should configure their own triggers based on their domain.
 };
 /**
  * Detect mandatory agents based on code paths.
@@ -64,7 +68,7 @@ export function emitMandatoryAgentAdvisory(codePaths, wuId) {
         console.log(picocolors.cyan(`  • ${agent}`));
     }
     console.log('');
-    console.log(picocolors.gray(`Run: pnpm orchestrate:suggest --wu ${wuId}`));
+    console.log(picocolors.gray(`Run: pnpm orchestrate:monitor to check agent status`));
     console.log(picocolors.yellow(horizontalLine));
     console.log('');
 }

package/dist/orchestration-advisory.d.ts

@@ -2,11 +2,11 @@
  * Orchestration Advisory Emitter
  *
  * Utility functions for emitting mandatory agent advisories and checking compliance.
- * Used by wu-claim.mjs (emit advisory) and wu-done.mjs (check compliance).
+ * Used by wu-claim.ts (emit advisory) and wu-done.ts (check compliance).
  *
  * @module orchestration-advisory
- * @see {@link ./orchestration-rules.mjs} - detectMandatoryAgents function
- * @see {@link ./domain/orchestration.constants.mjs} - MANDATORY_TRIGGERS patterns
+ * @see {@link ./orchestration-rules.ts} - detectMandatoryAgents function
+ * @see {@link ./domain/orchestration.constants.ts} - MANDATORY_TRIGGERS patterns
  */
 import type { MandatoryAgentName } from './domain/orchestration.types.js';
 /**

package/dist/orchestration-advisory.js

@@ -2,11 +2,11 @@
  * Orchestration Advisory Emitter
  *
  * Utility functions for emitting mandatory agent advisories and checking compliance.
- * Used by wu-claim.mjs (emit advisory) and wu-done.mjs (check compliance).
+ * Used by wu-claim.ts (emit advisory) and wu-done.ts (check compliance).
  *
  * @module orchestration-advisory
- * @see {@link ./orchestration-rules.mjs} - detectMandatoryAgents function
- * @see {@link ./domain/orchestration.constants.mjs} - MANDATORY_TRIGGERS patterns
+ * @see {@link ./orchestration-rules.ts} - detectMandatoryAgents function
+ * @see {@link ./domain/orchestration.constants.ts} - MANDATORY_TRIGGERS patterns
  */
 import picocolors from 'picocolors';
 import { detectMandatoryAgents } from './orchestration-rules.js';
@@ -59,7 +59,7 @@ export function emitMandatoryAgentAdvisory(codePaths, wuId) {
         console.log(picocolors.cyan(`  ${BOX_CHARS.BULLET} ${agent}`));
     }
     console.log('');
-    console.log(picocolors.gray(`Run: pnpm orchestrate:suggest --wu ${wuId}`));
+    console.log(picocolors.gray(`Run: pnpm orchestrate:monitor to check agent status`));
     console.log(picocolors.yellow(horizontalLine));
     console.log('');
 }

package/dist/orchestration-di.d.ts

@@ -6,10 +6,10 @@
  * implementations are coupled.
  *
  * @module orchestration-di
- * @see {@link ./ports/metrics-collector.port.mjs} - Input port
- * @see {@link ./ports/dashboard-renderer.port.mjs} - Output port
- * @see {@link ./adapters/filesystem-metrics.adapter.mjs} - Input adapter
- * @see {@link ./adapters/terminal-renderer.adapter.mjs} - Output adapter
+ * @see {@link ./ports/metrics-collector.port.ts} - Input port
+ * @see {@link ./ports/dashboard-renderer.port.ts} - Output port
+ * @see {@link ./adapters/filesystem-metrics.adapter.ts} - Input adapter
+ * @see {@link ./adapters/terminal-renderer.adapter.ts} - Output adapter
  */
 import { GetDashboardDataUseCase } from './usecases/get-dashboard-data.usecase.js';
 import { GetSuggestionsUseCase } from './usecases/get-suggestions.usecase.js';

package/dist/orchestration-di.js

@@ -6,10 +6,10 @@
  * implementations are coupled.
  *
  * @module orchestration-di
- * @see {@link ./ports/metrics-collector.port.mjs} - Input port
- * @see {@link ./ports/dashboard-renderer.port.mjs} - Output port
- * @see {@link ./adapters/filesystem-metrics.adapter.mjs} - Input adapter
- * @see {@link ./adapters/terminal-renderer.adapter.mjs} - Output adapter
+ * @see {@link ./ports/metrics-collector.port.ts} - Input port
+ * @see {@link ./ports/dashboard-renderer.port.ts} - Output port
+ * @see {@link ./adapters/filesystem-metrics.adapter.ts} - Input adapter
+ * @see {@link ./adapters/terminal-renderer.adapter.ts} - Output adapter
  */
 import { FileSystemMetricsCollector } from './adapters/filesystem-metrics.adapter.js';
 import { TerminalDashboardRenderer } from './adapters/terminal-renderer.adapter.js';

package/dist/orchestration-rules.d.ts

@@ -5,8 +5,8 @@
  * Uses minimatch for glob pattern matching (NOT regex).
  *
  * @module orchestration-rules
- * @see {@link ./domain/orchestration.constants.mjs} - MANDATORY_TRIGGERS patterns
- * @see {@link ../../../docs/04-operations/_frameworks/lumenflow/agent/onboarding/agent-selection-guide.md} - Agent selection rules
+ * @see {@link ./domain/orchestration.constants.ts} - MANDATORY_TRIGGERS patterns
+ * @see {@link https://lumenflow.dev/reference/agent-selection-guide/} - Agent selection rules
  */
 import { type MandatoryAgentName } from './domain/orchestration.constants.js';
 /**
@@ -47,11 +47,11 @@ export declare function buildMandatoryAgentsErrorMessage(wuId: any, missingAgent
 export declare function checkMandatoryAgentsComplianceBlocking(codePaths: any, wuId: any, options: any): {
     compliant: boolean;
     blocking: boolean;
-    missing: ("security-auditor" | "beacon-guardian")[];
+    missing: any[];
     errorMessage?: undefined;
 } | {
     compliant: boolean;
     blocking: boolean;
-    missing: ("security-auditor" | "beacon-guardian")[];
+    missing: never[];
     errorMessage: string;
 };

package/dist/orchestration-rules.js

@@ -5,8 +5,8 @@
  * Uses minimatch for glob pattern matching (NOT regex).
  *
  * @module orchestration-rules
- * @see {@link ./domain/orchestration.constants.mjs} - MANDATORY_TRIGGERS patterns
- * @see {@link ../../../docs/04-operations/_frameworks/lumenflow/agent/onboarding/agent-selection-guide.md} - Agent selection rules
+ * @see {@link ./domain/orchestration.constants.ts} - MANDATORY_TRIGGERS patterns
+ * @see {@link https://lumenflow.dev/reference/agent-selection-guide/} - Agent selection rules
  */
 import { minimatch } from 'minimatch';
 import { MANDATORY_TRIGGERS } from './domain/orchestration.constants.js';
@@ -74,8 +74,10 @@ export function generateSuggestions(wuProgress, _agentHistory) {
 function generateWUSuggestions(wu, nextId) {
     const suggestions = [];
     // Check for pending mandatory agents (HIGH priority)
-    const mandatoryAgents = ['security-auditor', 'beacon-guardian'];
-    for (const agentName of mandatoryAgents) {
+    // Note: For LumenFlow framework development, MANDATORY_TRIGGERS is empty.
+    // Projects using LumenFlow can configure their own mandatory agents.
+    const mandatoryAgentNames = Object.keys(MANDATORY_TRIGGERS);
+    for (const agentName of mandatoryAgentNames) {
         if (wu.agents[agentName] === 'pending') {
             suggestions.push({
                 id: `sug-${nextId().toString().padStart(3, '0')}`,
@@ -116,10 +118,16 @@ function generateWUSuggestions(wu, nextId) {
 /**
  * WU-1542: Agent trigger descriptions for error messages.
  * Maps agent names to human-readable descriptions of their trigger patterns.
+ *
+ * Note: For LumenFlow framework development, this is empty since we don't have
+ * application-specific mandatory agents. Projects using LumenFlow should
+ * configure their own trigger descriptions based on their domain requirements.
  */
 const AGENT_TRIGGER_DESCRIPTIONS = {
-    'security-auditor': 'supabase/migrations/**, **/auth/**, **/rls/**, **/permissions/**',
-    'beacon-guardian': '**/prompts/**, **/classification/**, **/detector/**, **/llm/**',
+// No mandatory agent triggers for LumenFlow framework development.
+// Example for application-specific triggers:
+// 'security-auditor': 'supabase/migrations/**, auth/**, rls/**',
+// 'beacon-guardian': 'prompts/**, llm/**',
 };
 /**
  * WU-1542: Build a formatted error message for mandatory agent enforcement failures.
@@ -156,13 +164,13 @@ export function buildMandatoryAgentsErrorMessage(wuId, missingAgents, codePaths)
     lines.push('');
     lines.push('Required action:');
     lines.push('  1. Invoke the required agents BEFORE calling wu:done');
-    lines.push('  2. For security-auditor: Review PHI/auth/RLS implications');
-    lines.push('  3. For beacon-guardian: Validate LLM/prompt compliance');
+    lines.push("  2. Check your project's mandatory agent configuration");
+    lines.push('  3. Consult agent documentation for compliance requirements');
     lines.push('');
-    lines.push('To bypass (NOT RECOMMENDED for PHI/auth work):');
+    lines.push('To bypass (only if appropriate for your project):');
     lines.push('  Remove --require-agents flag from wu:done command');
     lines.push('');
-    lines.push('See: docs/04-operations/_frameworks/lumenflow/agent/onboarding/agent-selection-guide.md for agent invocation guidance');
+    lines.push('See: https://lumenflow.dev/reference/agent-selection-guide/ for agent invocation guidance');
     lines.push('='.repeat(70));
     return lines.join('\n');
 }

package/dist/orphan-detector.d.ts

@@ -14,9 +14,9 @@
  * - Layer 3: Pre-flight check in wu:claim
  * - Layer 4: Manual utility wu:cleanup-orphans
  *
- * @see {@link tools/wu-prune.mjs} - Primary consumer
- * @see {@link tools/wu-claim.mjs} - Pre-flight orphan check
- * @see {@link tools/lib/git-adapter.mjs} - worktreeRemove with cleanup
+ * @see {@link packages/@lumenflow/cli/src/wu-prune.ts} - Primary consumer
+ * @see {@link packages/@lumenflow/cli/src/wu-claim.ts} - Pre-flight orphan check
+ * @see {@link packages/@lumenflow/cli/src/lib/git-adapter.ts} - worktreeRemove with cleanup
  */
 import { existsSync } from 'node:fs';
 /**

package/dist/orphan-detector.js

@@ -14,9 +14,9 @@
  * - Layer 3: Pre-flight check in wu:claim
  * - Layer 4: Manual utility wu:cleanup-orphans
  *
- * @see {@link tools/wu-prune.mjs} - Primary consumer
- * @see {@link tools/wu-claim.mjs} - Pre-flight orphan check
- * @see {@link tools/lib/git-adapter.mjs} - worktreeRemove with cleanup
+ * @see {@link packages/@lumenflow/cli/src/wu-prune.ts} - Primary consumer
+ * @see {@link packages/@lumenflow/cli/src/wu-claim.ts} - Pre-flight orphan check
+ * @see {@link packages/@lumenflow/cli/src/lib/git-adapter.ts} - worktreeRemove with cleanup
  */
 import { readdirSync, statSync, existsSync, rmSync } from 'node:fs';
 import path from 'node:path';

package/dist/patrol-loop.d.ts

@@ -0,0 +1,170 @@
+/**
+ * Patrol Loop Module (WU-1242)
+ *
+ * Continuous patrol loop for monitoring spawn health.
+ * The 'Witness patrol' pattern - keeps the spawn fleet healthy by
+ * checking status at configurable intervals with exponential backoff
+ * on repeated failures.
+ *
+ * Features:
+ * - Configurable patrol interval (default 5min)
+ * - Exponential backoff on failures (max 1hr)
+ * - Graceful shutdown support
+ * - Cycle callbacks for status reporting
+ * - Error handling with continuation
+ *
+ * @see {@link packages/@lumenflow/cli/src/orchestrate-monitor.ts} - CLI integration
+ * @see {@link packages/@lumenflow/core/src/__tests__/patrol-loop.test.ts} - Tests
+ */
+/**
+ * Default patrol interval (5 minutes in milliseconds)
+ */
+export declare const DEFAULT_PATROL_INTERVAL_MS: number;
+/**
+ * Maximum backoff interval (1 hour in milliseconds)
+ */
+export declare const MAX_BACKOFF_MS: number;
+/**
+ * Result of a patrol check
+ */
+export interface PatrolCheckResult {
+    /** Whether the spawn fleet is healthy (no stuck spawns or zombies) */
+    healthy: boolean;
+    /** Number of stuck spawns detected */
+    stuckCount: number;
+    /** Number of zombie locks detected */
+    zombieCount: number;
+    /** Optional suggestions for recovery */
+    suggestions?: string[];
+}
+/**
+ * Metadata passed to cycle callbacks
+ */
+export interface CycleMetadata {
+    /** The cycle number (1-indexed) */
+    cycleNumber: number;
+    /** Current interval in milliseconds */
+    intervalMs: number;
+    /** Number of consecutive failures */
+    consecutiveFailures: number;
+    /** Timestamp of the cycle */
+    timestamp: Date;
+}
+/**
+ * Callback invoked on each patrol cycle
+ */
+export type OnCycleCallback = (result: PatrolCheckResult, meta: CycleMetadata) => void;
+/**
+ * Callback invoked when an error occurs
+ */
+export type OnErrorCallback = (error: Error, cycleNumber: number) => void;
+/**
+ * Options for creating a PatrolLoop
+ */
+export interface PatrolLoopOptions {
+    /**
+     * Function to check spawn health
+     */
+    checkFn: () => Promise<PatrolCheckResult>;
+    /**
+     * Patrol interval in milliseconds (default: 5 minutes)
+     */
+    intervalMs?: number;
+    /**
+     * Callback invoked after each patrol cycle
+     */
+    onCycle?: OnCycleCallback;
+    /**
+     * Callback invoked when checkFn throws an error
+     */
+    onError?: OnErrorCallback;
+}
+/**
+ * Calculates the backoff interval based on consecutive failures.
+ * Uses exponential backoff with a maximum of 1 hour.
+ *
+ * Backoff formula: baseInterval * 2^(failures-1), capped at MAX_BACKOFF_MS
+ *
+ * @param consecutiveFailures - Number of consecutive failures (1-indexed)
+ * @param baseIntervalMs - Base interval in milliseconds
+ * @returns Backoff interval in milliseconds
+ *
+ * @example
+ * calculateBackoff(1, 5*60*1000) // 5 minutes (no backoff yet)
+ * calculateBackoff(2, 5*60*1000) // 10 minutes (2x)
+ * calculateBackoff(3, 5*60*1000) // 20 minutes (4x)
+ */
+export declare function calculateBackoff(consecutiveFailures: number, baseIntervalMs: number): number;
+/**
+ * Patrol loop for continuous spawn monitoring.
+ *
+ * @example
+ * const patrol = new PatrolLoop({
+ *   checkFn: async () => {
+ *     const result = await runMonitor();
+ *     return {
+ *       healthy: result.stuckSpawns.length === 0,
+ *       stuckCount: result.stuckSpawns.length,
+ *       zombieCount: result.zombieLocks.length,
+ *     };
+ *   },
+ *   intervalMs: 5 * 60 * 1000, // 5 minutes
+ *   onCycle: (result, meta) => {
+ *     console.log(`Cycle ${meta.cycleNumber}: ${result.healthy ? 'healthy' : 'issues detected'}`);
+ *   },
+ * });
+ *
+ * patrol.start();
+ * // Later...
+ * patrol.stop();
+ */
+export declare class PatrolLoop {
+    private readonly checkFn;
+    private readonly baseIntervalMs;
+    private readonly onCycle?;
+    private readonly onError?;
+    private timer;
+    private running;
+    private failures;
+    private cycles;
+    /**
+     * Creates a new PatrolLoop instance.
+     *
+     * @param options - Patrol loop configuration
+     */
+    constructor(options: PatrolLoopOptions);
+    /**
+     * The configured base interval in milliseconds.
+     */
+    get intervalMs(): number;
+    /**
+     * Whether the patrol loop is currently running.
+     */
+    get isRunning(): boolean;
+    /**
+     * Number of consecutive failures (resets on success).
+     */
+    get consecutiveFailures(): number;
+    /**
+     * Total number of completed patrol cycles.
+     */
+    get totalCycles(): number;
+    /**
+     * Starts the patrol loop.
+     * Does nothing if already running.
+     */
+    start(): void;
+    /**
+     * Stops the patrol loop.
+     * Safe to call even if not running.
+     */
+    stop(): void;
+    /**
+     * Schedules the next patrol cycle.
+     */
+    private scheduleNextCycle;
+    /**
+     * Runs a single patrol cycle.
+     */
+    private runCycle;
+}