@lumenflow/core 1.3.5 → 1.4.0

package/README.md

@@ -68,6 +68,29 @@ const exists = await worktrees.exists('/path/to/worktree');
 await worktrees.remove('worktrees/operations-wu-123');
 ```
 
+### Agent Branch Patterns
+
+Check if a branch is an agent branch that can bypass worktree requirements. Patterns are fetched from a central registry with 7-day caching.
+
+```typescript
+import { isAgentBranch, getAgentPatterns } from '@lumenflow/core';
+
+// Check if branch can bypass worktree requirements (async, uses registry)
+if (await isAgentBranch('claude/session-12345')) {
+  console.log('Agent branch - bypass allowed');
+}
+
+// Get the current list of agent patterns
+const patterns = await getAgentPatterns();
+// ['agent/*', 'claude/*', 'codex/*', 'copilot/*', 'cursor/*', ...]
+
+// Synchronous version (uses local config only, no registry fetch)
+import { isAgentBranchSync } from '@lumenflow/core';
+const result = isAgentBranchSync('agent/task-123');
+```
+
+Protected branches (main, master, lane/\*) are **never** bypassed, regardless of patterns.
+
 ## API Reference
 
 ### GitAdapter

package/dist/agent-patterns-registry.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Agent Patterns Registry
+ *
+ * Central registry for AI agent branch patterns (claude/*, codex/*, copilot/*, cursor/*, etc.)
+ * that bypass worktree requirements. Static JSON served from lumenflow.dev,
+ * cached locally for 7 days with fallback to defaults.
+ *
+ * @module agent-patterns-registry
+ */
+/** Default agent branch patterns (narrow: just agent/*) */
+export declare const DEFAULT_AGENT_PATTERNS: string[];
+/** Remote registry URL */
+export declare const REGISTRY_URL = "https://lumenflow.dev/registry/agent-patterns.json";
+/** Cache TTL: 7 days in milliseconds */
+export declare const CACHE_TTL_MS: number;
+/**
+ * Options for getAgentPatterns
+ */
+interface GetAgentPatternsOptions {
+    /** Override cache directory (default: ~/.lumenflow/cache) */
+    cacheDir?: string;
+    /** Fetch timeout in milliseconds (default: 5000) */
+    timeoutMs?: number;
+}
+/**
+ * Get the default cache directory
+ *
+ * @returns Path to cache directory (~/.lumenflow/cache or LUMENFLOW_HOME/cache)
+ */
+export declare function getCacheDir(): string;
+/**
+ * Get agent branch patterns from registry with caching
+ *
+ * Fetches patterns from remote registry, caches locally for 7 days,
+ * and falls back to defaults on failure.
+ *
+ * @param options - Options
+ * @returns Array of agent branch patterns (glob format)
+ *
+ * @example
+ * ```typescript
+ * const patterns = await getAgentPatterns();
+ * // ['claude/*', 'codex/*', 'copilot/*', 'cursor/*', 'agent/*']
+ * ```
+ */
+export declare function getAgentPatterns(options?: GetAgentPatternsOptions): Promise<string[]>;
+/**
+ * Clear the in-memory cache
+ *
+ * Used primarily for testing.
+ */
+export declare function clearCache(): void;
+export {};

package/dist/agent-patterns-registry.js

@@ -0,0 +1,190 @@
+/**
+ * Agent Patterns Registry
+ *
+ * Central registry for AI agent branch patterns (claude/*, codex/*, copilot/*, cursor/*, etc.)
+ * that bypass worktree requirements. Static JSON served from lumenflow.dev,
+ * cached locally for 7 days with fallback to defaults.
+ *
+ * @module agent-patterns-registry
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+/** Default agent branch patterns (narrow: just agent/*) */
+export const DEFAULT_AGENT_PATTERNS = ['agent/*'];
+/** Remote registry URL */
+export const REGISTRY_URL = 'https://lumenflow.dev/registry/agent-patterns.json';
+/** Cache TTL: 7 days in milliseconds */
+export const CACHE_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+/** Cache file name */
+const CACHE_FILE_NAME = 'agent-patterns-cache.json';
+/** Default fetch timeout in milliseconds */
+const DEFAULT_TIMEOUT_MS = 5000;
+/** In-memory cache for patterns */
+let memoryCache = null;
+/** In-memory cache timestamp */
+let memoryCacheTime = 0;
+/**
+ * Get the default cache directory
+ *
+ * @returns Path to cache directory (~/.lumenflow/cache or LUMENFLOW_HOME/cache)
+ */
+export function getCacheDir() {
+    const lumenflowHome = process.env.LUMENFLOW_HOME;
+    if (lumenflowHome) {
+        return path.join(lumenflowHome, 'cache');
+    }
+    return path.join(os.homedir(), '.lumenflow', 'cache');
+}
+/**
+ * Validate registry response
+ *
+ * @param data - Data to validate
+ * @returns True if valid registry response
+ */
+function isValidRegistryResponse(data) {
+    if (!data || typeof data !== 'object')
+        return false;
+    const obj = data;
+    if (!Array.isArray(obj.patterns))
+        return false;
+    if (!obj.patterns.every((p) => typeof p === 'string'))
+        return false;
+    return true;
+}
+/**
+ * Read cache from disk
+ *
+ * @param cacheDir - Cache directory
+ * @returns Cache data or null if not found/invalid
+ */
+function readCache(cacheDir) {
+    try {
+        const cacheFile = path.join(cacheDir, CACHE_FILE_NAME);
+        if (!fs.existsSync(cacheFile))
+            return null;
+        const content = fs.readFileSync(cacheFile, 'utf8');
+        const data = JSON.parse(content);
+        // Validate cache structure
+        if (!Array.isArray(data.patterns))
+            return null;
+        if (typeof data.fetchedAt !== 'number')
+            return null;
+        return data;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Write cache to disk
+ *
+ * @param cacheDir - Cache directory
+ * @param data - Data to cache
+ */
+function writeCache(cacheDir, data) {
+    try {
+        // Ensure cache directory exists
+        if (!fs.existsSync(cacheDir)) {
+            fs.mkdirSync(cacheDir, { recursive: true });
+        }
+        const cacheFile = path.join(cacheDir, CACHE_FILE_NAME);
+        fs.writeFileSync(cacheFile, JSON.stringify(data, null, 2));
+    }
+    catch {
+        // Fail silently - cache is optional
+    }
+}
+/**
+ * Fetch patterns from remote registry with timeout
+ *
+ * @param timeoutMs - Timeout in milliseconds
+ * @returns Registry response or null on failure
+ */
+async function fetchFromRegistry(timeoutMs) {
+    try {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+        const response = await fetch(REGISTRY_URL, {
+            signal: controller.signal,
+            headers: {
+                Accept: 'application/json',
+                'User-Agent': 'lumenflow-core',
+            },
+        });
+        clearTimeout(timeoutId);
+        if (!response.ok) {
+            return null;
+        }
+        const data = await response.json();
+        if (!isValidRegistryResponse(data)) {
+            return null;
+        }
+        return data;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Get agent branch patterns from registry with caching
+ *
+ * Fetches patterns from remote registry, caches locally for 7 days,
+ * and falls back to defaults on failure.
+ *
+ * @param options - Options
+ * @returns Array of agent branch patterns (glob format)
+ *
+ * @example
+ * ```typescript
+ * const patterns = await getAgentPatterns();
+ * // ['claude/*', 'codex/*', 'copilot/*', 'cursor/*', 'agent/*']
+ * ```
+ */
+export async function getAgentPatterns(options = {}) {
+    const { cacheDir = getCacheDir(), timeoutMs = DEFAULT_TIMEOUT_MS } = options;
+    // Check memory cache first (fast path)
+    const now = Date.now();
+    if (memoryCache && now - memoryCacheTime < CACHE_TTL_MS) {
+        return memoryCache;
+    }
+    // Check disk cache
+    const diskCache = readCache(cacheDir);
+    if (diskCache && now - diskCache.fetchedAt < CACHE_TTL_MS) {
+        // Fresh disk cache - use it and update memory cache
+        memoryCache = diskCache.patterns;
+        memoryCacheTime = diskCache.fetchedAt;
+        return diskCache.patterns;
+    }
+    // Cache is stale or missing - try to fetch
+    const registryData = await fetchFromRegistry(timeoutMs);
+    if (registryData) {
+        // Update caches
+        const cacheData = {
+            version: registryData.version,
+            patterns: registryData.patterns,
+            fetchedAt: now,
+        };
+        writeCache(cacheDir, cacheData);
+        memoryCache = registryData.patterns;
+        memoryCacheTime = now;
+        return registryData.patterns;
+    }
+    // Fetch failed - try stale cache as fallback
+    if (diskCache) {
+        memoryCache = diskCache.patterns;
+        memoryCacheTime = diskCache.fetchedAt; // Keep stale time
+        return diskCache.patterns;
+    }
+    // No cache, no network - use defaults
+    return DEFAULT_AGENT_PATTERNS;
+}
+/**
+ * Clear the in-memory cache
+ *
+ * Used primarily for testing.
+ */
+export function clearCache() {
+    memoryCache = null;
+    memoryCacheTime = 0;
+}

package/dist/branch-check.d.ts

@@ -8,12 +8,34 @@
  */
 /**
  * Check if branch is an agent branch that can bypass worktree requirements.
- * Uses the existing config loader (which handles caching/validation).
+ *
+ * Uses the central registry for agent patterns (fetched from lumenflow.dev
+ * with 7-day cache), falling back to config patterns if specified, then
+ * to defaults.
+ *
+ * @param branch - Branch name to check
+ * @returns Promise<true> if branch matches agent patterns
+ *
+ * @example
+ * ```typescript
+ * if (await isAgentBranch('claude/session-123')) {
+ *   // Allow bypass for agent branch
+ * }
+ * ```
+ */
+export declare function isAgentBranch(branch: string | null | undefined): Promise<boolean>;
+/**
+ * Synchronous version of isAgentBranch for backwards compatibility.
+ *
+ * Uses only local config patterns or defaults - does NOT fetch from registry.
+ * Prefer async isAgentBranch() when possible.
  *
  * @param branch - Branch name to check
  * @returns True if branch matches agent patterns
+ *
+ * @deprecated Use async isAgentBranch() instead for registry support
  */
-export declare function isAgentBranch(branch: string | null | undefined): boolean;
+export declare function isAgentBranchSync(branch: string | null | undefined): boolean;
 /**
  * Check if headless mode is allowed (guarded).
  * Requires LUMENFLOW_HEADLESS=1 AND (LUMENFLOW_ADMIN=1 OR CI truthy OR GITHUB_ACTIONS truthy)

package/dist/branch-check.js

@@ -8,8 +8,7 @@
  */
 import micromatch from 'micromatch';
 import { getConfig } from './lumenflow-config.js';
-/** Default agent branch patterns (narrow: just agent/*) */
-const DEFAULT_AGENT_BRANCH_PATTERNS = ['agent/*'];
+import { getAgentPatterns, DEFAULT_AGENT_PATTERNS } from './agent-patterns-registry.js';
 /** Legacy protected branch (always protected regardless of mainBranch setting) */
 const LEGACY_PROTECTED = 'master';
 /**
@@ -36,12 +35,62 @@ function getProtectedBranches() {
 }
 /**
  * Check if branch is an agent branch that can bypass worktree requirements.
- * Uses the existing config loader (which handles caching/validation).
+ *
+ * Uses the central registry for agent patterns (fetched from lumenflow.dev
+ * with 7-day cache), falling back to config patterns if specified, then
+ * to defaults.
+ *
+ * @param branch - Branch name to check
+ * @returns Promise<true> if branch matches agent patterns
+ *
+ * @example
+ * ```typescript
+ * if (await isAgentBranch('claude/session-123')) {
+ *   // Allow bypass for agent branch
+ * }
+ * ```
+ */
+export async function isAgentBranch(branch) {
+    // Fail-closed: no branch = protected
+    if (!branch)
+        return false;
+    // Detached HEAD = protected (fail-closed)
+    if (branch === 'HEAD')
+        return false;
+    // Load config (uses existing loader with caching)
+    const config = getConfig();
+    const protectedBranches = getProtectedBranches();
+    // Protected branches are NEVER bypassed (mainBranch + 'master')
+    if (protectedBranches.includes(branch))
+        return false;
+    // LumenFlow lane branches require worktrees (uses config's laneBranchPrefix)
+    if (getLaneBranchPattern().test(branch))
+        return false;
+    // Get patterns: prefer config override, then registry, then defaults
+    let patterns;
+    if (config?.git?.agentBranchPatterns?.length > 0) {
+        // Config has explicit patterns - use those
+        patterns = config.git.agentBranchPatterns;
+    }
+    else {
+        // Fetch from registry (with caching and fallback to defaults)
+        patterns = await getAgentPatterns();
+    }
+    // Use micromatch for proper glob matching
+    return micromatch.isMatch(branch, patterns);
+}
+/**
+ * Synchronous version of isAgentBranch for backwards compatibility.
+ *
+ * Uses only local config patterns or defaults - does NOT fetch from registry.
+ * Prefer async isAgentBranch() when possible.
  *
  * @param branch - Branch name to check
  * @returns True if branch matches agent patterns
+ *
+ * @deprecated Use async isAgentBranch() instead for registry support
  */
-export function isAgentBranch(branch) {
+export function isAgentBranchSync(branch) {
     // Fail-closed: no branch = protected
     if (!branch)
         return false;
@@ -51,15 +100,16 @@ export function isAgentBranch(branch) {
     // Load config (uses existing loader with caching)
     const config = getConfig();
     const protectedBranches = getProtectedBranches();
-    const patterns = config?.git?.agentBranchPatterns?.length > 0
-        ? config.git.agentBranchPatterns
-        : DEFAULT_AGENT_BRANCH_PATTERNS;
     // Protected branches are NEVER bypassed (mainBranch + 'master')
     if (protectedBranches.includes(branch))
         return false;
     // LumenFlow lane branches require worktrees (uses config's laneBranchPrefix)
     if (getLaneBranchPattern().test(branch))
         return false;
+    // Use config patterns or defaults (no registry fetch in sync version)
+    const patterns = config?.git?.agentBranchPatterns?.length > 0
+        ? config.git.agentBranchPatterns
+        : DEFAULT_AGENT_PATTERNS;
     // Use micromatch for proper glob matching
     return micromatch.isMatch(branch, patterns);
 }

package/dist/cli/is-agent-branch.d.ts

@@ -3,6 +3,8 @@
  * CLI helper for bash hooks to check if branch is an agent branch.
  * Uses the same isAgentBranch() logic as TypeScript code.
  *
+ * Now async to support registry pattern lookup with fetch + cache.
+ *
  * Usage: node dist/cli/is-agent-branch.js [branch-name]
  * Exit codes: 0 = agent branch (allowed), 1 = not agent branch (protected)
  *

package/dist/cli/is-agent-branch.js

@@ -3,13 +3,22 @@
  * CLI helper for bash hooks to check if branch is an agent branch.
  * Uses the same isAgentBranch() logic as TypeScript code.
  *
+ * Now async to support registry pattern lookup with fetch + cache.
+ *
  * Usage: node dist/cli/is-agent-branch.js [branch-name]
  * Exit codes: 0 = agent branch (allowed), 1 = not agent branch (protected)
  *
  * @module cli/is-agent-branch
  */
 import { isAgentBranch } from '../branch-check.js';
-const branch = process.argv[2] || null;
-const result = isAgentBranch(branch);
-// Exit 0 = agent branch (truthy), Exit 1 = not agent branch
-process.exit(result ? 0 : 1);
+async function main() {
+    const branch = process.argv[2] || null;
+    const result = await isAgentBranch(branch);
+    // Exit 0 = agent branch (truthy), Exit 1 = not agent branch
+    process.exit(result ? 0 : 1);
+}
+main().catch((error) => {
+    console.error('Error checking agent branch:', error.message);
+    // Fail-closed: error = not allowed
+    process.exit(1);
+});

package/dist/index.d.ts

@@ -43,6 +43,7 @@ export * from './lumenflow-config.js';
 export * from './lumenflow-config-schema.js';
 export * from './gates-config.js';
 export * from './branch-check.js';
+export * from './agent-patterns-registry.js';
 export * from './lumenflow-home.js';
 export * from './force-bypass-audit.js';
 export { LUMENFLOW_PATHS, BEACON_PATHS } from './wu-constants.js';

package/dist/index.js

@@ -65,6 +65,8 @@ export * from './lumenflow-config-schema.js';
 export * from './gates-config.js';
 // Branch check utilities
 export * from './branch-check.js';
+// WU-1082: Agent patterns registry (fetch + cache)
+export * from './agent-patterns-registry.js';
 // WU-1062: External plan storage
 export * from './lumenflow-home.js';
 // WU-1070: Force bypass audit logging

package/dist/micro-worktree.d.ts

@@ -27,6 +27,7 @@
  * @see {@link tools/wu-edit.mjs} - Spec edits (WU-1274)
  * @see {@link tools/initiative-create.mjs} - Initiative creation (WU-1439)
  */
+import type { GitAdapter } from './git-adapter.js';
 /**
  * Maximum retry attempts for ff-only merge when main moves
  *
@@ -34,6 +35,18 @@
  * concurrently. Each retry fetches latest main and rebases.
  */
 export declare const MAX_MERGE_RETRIES = 3;
+/**
+ * Environment variable name for LUMENFLOW_FORCE bypass
+ *
+ * WU-1081: Exported for use in micro-worktree push operations.
+ */
+export declare 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 declare const LUMENFLOW_FORCE_REASON_ENV = "LUMENFLOW_FORCE_REASON";
 /**
  * Default log prefix for micro-worktree operations
  *
@@ -135,6 +148,25 @@ export declare function formatFiles(files: any, worktreePath: any, logPrefix?: s
  * @throws {Error} If merge fails after all retries
  */
 export declare function mergeWithRetry(tempBranchName: any, microWorktreePath: any, logPrefix?: string): Promise<void>;
+/**
+ * Push using refspec with LUMENFLOW_FORCE to bypass pre-push hooks
+ *
+ * WU-1081: Micro-worktree pushes to origin/main need to bypass pre-push hooks
+ * because they operate from temp branches in /tmp directories, which would
+ * otherwise be blocked by hook validation.
+ *
+ * Sets LUMENFLOW_FORCE=1 and LUMENFLOW_FORCE_REASON during the push,
+ * then restores original environment values (even on error).
+ *
+ * @param {GitAdapter} gitAdapter - GitAdapter instance to use for push
+ * @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
+ * @returns {Promise<void>}
+ * @throws {Error} If push fails (env vars still restored)
+ */
+export declare function pushRefspecWithForce(gitAdapter: GitAdapter, remote: string, localRef: string, remoteRef: string, reason: string): Promise<void>;
 /**
  * Execute an operation in a micro-worktree with full isolation
  *

package/dist/micro-worktree.js

@@ -40,6 +40,18 @@ 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;
+/**
+ * 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';
 /**
  * Default log prefix for micro-worktree operations
  *
@@ -344,6 +356,51 @@ export async function mergeWithRetry(tempBranchName, microWorktreePath, logPrefi
         }
     }
 }
+/**
+ * Push using refspec with LUMENFLOW_FORCE to bypass pre-push hooks
+ *
+ * WU-1081: Micro-worktree pushes to origin/main need to bypass pre-push hooks
+ * because they operate from temp branches in /tmp directories, which would
+ * otherwise be blocked by hook validation.
+ *
+ * Sets LUMENFLOW_FORCE=1 and LUMENFLOW_FORCE_REASON during the push,
+ * then restores original environment values (even on error).
+ *
+ * @param {GitAdapter} gitAdapter - GitAdapter instance to use for push
+ * @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
+ * @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) {
+            delete process.env[LUMENFLOW_FORCE_ENV];
+        }
+        else {
+            process.env[LUMENFLOW_FORCE_ENV] = originalForce;
+        }
+        if (originalReason === undefined) {
+            delete process.env[LUMENFLOW_FORCE_REASON_ENV];
+        }
+        else {
+            process.env[LUMENFLOW_FORCE_REASON_ENV] = originalReason;
+        }
+    }
+}
 /**
  * Execute an operation in a micro-worktree with full isolation
  *
@@ -401,8 +458,9 @@ export async function withMicroWorktree(options) {
         // Step 6: Push to origin (different paths for pushOnly vs standard)
         if (pushOnly) {
             // WU-1435: Push directly to origin/main without touching local main
+            // WU-1081: Use LUMENFLOW_FORCE to bypass pre-push hooks for micro-worktree pushes
             console.log(`${logPrefix} Pushing directly to ${REMOTES.ORIGIN}/${BRANCHES.MAIN} (push-only)...`);
-            await gitWorktree.pushRefspec(REMOTES.ORIGIN, tempBranchName, BRANCHES.MAIN);
+            await pushRefspecWithForce(gitWorktree, REMOTES.ORIGIN, tempBranchName, BRANCHES.MAIN, `micro-worktree push for ${operation} (automated)`);
             console.log(`${logPrefix} ✅ Pushed to ${REMOTES.ORIGIN}/${BRANCHES.MAIN}`);
             // Fetch to update remote tracking ref (FETCH_HEAD)
             console.log(`${logPrefix} Fetching ${REMOTES.ORIGIN}/${BRANCHES.MAIN}...`);

package/dist/state-machine.d.ts

@@ -9,6 +9,7 @@
  * - in_progress → blocked (block)
  * - in_progress → waiting (implementation complete, awaiting sign-off)
  * - in_progress → done (direct completion)
+ * - in_progress → ready (release - WU-1080: orphan recovery)
  * - blocked → in_progress (unblock)
  * - blocked → done (blocker resolved, direct completion)
  * - waiting → in_progress (changes requested)

package/dist/state-machine.js

@@ -9,6 +9,7 @@
  * - in_progress → blocked (block)
  * - in_progress → waiting (implementation complete, awaiting sign-off)
  * - in_progress → done (direct completion)
+ * - in_progress → ready (release - WU-1080: orphan recovery)
  * - blocked → in_progress (unblock)
  * - blocked → done (blocker resolved, direct completion)
  * - waiting → in_progress (changes requested)
@@ -26,7 +27,7 @@ const VALID_STATES = new Set(['ready', 'in_progress', 'blocked', 'waiting', 'don
  */
 const TRANSITIONS = {
     ready: ['in_progress'],
-    in_progress: ['blocked', 'waiting', 'done'],
+    in_progress: ['blocked', 'waiting', 'done', 'ready'], // WU-1080: 'ready' via release for orphan recovery
     blocked: ['in_progress', 'done'],
     waiting: ['in_progress', 'done'],
     done: [], // Terminal state - no outgoing transitions

package/dist/wu-consistency-checker.d.ts

@@ -84,14 +84,34 @@ export interface RepairWUInconsistencyOptions {
     projectRoot?: string;
 }
 /**
- * Repair WU inconsistencies
+ * Error object structure from checkWUConsistency()
+ */
+interface ConsistencyError {
+    type: string;
+    wuId: string;
+    title?: string;
+    lane?: string;
+    description?: string;
+    repairAction?: string;
+    canAutoRepair: boolean;
+}
+/**
+ * Repair WU inconsistencies using micro-worktree isolation (WU-1078)
+ *
+ * All file modifications (stamps, YAML, markdown) are made atomically
+ * in a micro-worktree, then committed and pushed to origin/main.
+ * This prevents direct writes to the main checkout.
  *
  * @param {object} report - Report from checkWUConsistency()
  * @param {RepairWUInconsistencyOptions} [options={}] - Repair options
  * @returns {Promise<object>} Result with repaired, skipped, and failed counts
  */
-export declare function repairWUInconsistency(report: any, options?: RepairWUInconsistencyOptions): Promise<{
+export declare function repairWUInconsistency(report: {
+    valid: boolean;
+    errors: ConsistencyError[];
+}, options?: RepairWUInconsistencyOptions): Promise<{
     repaired: number;
     skipped: number;
     failed: number;
 }>;
+export {};

package/dist/wu-consistency-checker.js

@@ -13,13 +13,14 @@
  * @see {@link ../wu-repair.mjs} CLI interface
  */
 import { readFile, writeFile, readdir, mkdir, access } from 'node:fs/promises';
-import { constants } from 'node:fs';
+import { constants, existsSync, mkdirSync, writeFileSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 import { parseYAML, stringifyYAML } from './wu-yaml.js';
 import { WU_PATHS } from './wu-paths.js';
 import { CONSISTENCY_TYPES, CONSISTENCY_MESSAGES, LOG_PREFIX, REMOTES, STRING_LITERALS, toKebab, WU_STATUS, YAML_OPTIONS, } from './wu-constants.js';
 import { todayISO } from './date-utils.js';
 import { createGitForPath } from './git-adapter.js';
+import { withMicroWorktree } from './micro-worktree.js';
 /**
  * Check a single WU for state inconsistencies
  *
@@ -238,7 +239,34 @@ export async function checkLaneForOrphanDoneWU(lane, excludeId, projectRoot = pr
     };
 }
 /**
- * Repair WU inconsistencies
+ * Categorize errors into file-based repairs (need micro-worktree) and git-only repairs
+ */
+function categorizeErrors(errors) {
+    const fileRepairs = [];
+    const gitOnlyRepairs = [];
+    const nonRepairable = [];
+    for (const error of errors) {
+        if (!error.canAutoRepair) {
+            nonRepairable.push(error);
+            continue;
+        }
+        // Git-only repairs: worktree/branch cleanup doesn't need micro-worktree
+        if (error.type === CONSISTENCY_TYPES.ORPHAN_WORKTREE_DONE) {
+            gitOnlyRepairs.push(error);
+        }
+        else {
+            // All file-based repairs need micro-worktree isolation
+            fileRepairs.push(error);
+        }
+    }
+    return { fileRepairs, gitOnlyRepairs, nonRepairable };
+}
+/**
+ * Repair WU inconsistencies using micro-worktree isolation (WU-1078)
+ *
+ * All file modifications (stamps, YAML, markdown) are made atomically
+ * in a micro-worktree, then committed and pushed to origin/main.
+ * This prevents direct writes to the main checkout.
  *
  * @param {object} report - Report from checkWUConsistency()
  * @param {RepairWUInconsistencyOptions} [options={}] - Repair options
@@ -249,20 +277,72 @@ export async function repairWUInconsistency(report, options = {}) {
     if (report.valid) {
         return { repaired: 0, skipped: 0, failed: 0 };
     }
+    const { fileRepairs, gitOnlyRepairs, nonRepairable } = categorizeErrors(report.errors);
     let repaired = 0;
-    let skipped = 0;
+    let skipped = nonRepairable.length;
     let failed = 0;
-    for (const error of report.errors) {
-        if (!error.canAutoRepair) {
-            skipped++;
-            continue;
+    // Dry run mode: just count
+    if (dryRun) {
+        return {
+            repaired: fileRepairs.length + gitOnlyRepairs.length,
+            skipped,
+            failed: 0,
+        };
+    }
+    // Step 1: Process file-based repairs via micro-worktree (batched)
+    if (fileRepairs.length > 0) {
+        try {
+            // Generate a batch ID from the WU IDs being repaired
+            const batchId = `batch-${fileRepairs.map((e) => e.wuId).join('-')}`.slice(0, 50);
+            await withMicroWorktree({
+                operation: 'wu-repair',
+                id: batchId,
+                logPrefix: LOG_PREFIX.REPAIR,
+                execute: async ({ worktreePath }) => {
+                    const filesModified = [];
+                    for (const error of fileRepairs) {
+                        try {
+                            const result = await repairSingleErrorInWorktree(error, worktreePath, projectRoot);
+                            if (result.success && result.files) {
+                                filesModified.push(...result.files);
+                                repaired++;
+                            }
+                            else if (result.skipped) {
+                                skipped++;
+                                if (result.reason) {
+                                    console.warn(`${LOG_PREFIX.REPAIR} Skipped ${error.type}: ${result.reason}`);
+                                }
+                            }
+                            else {
+                                failed++;
+                            }
+                        }
+                        catch (err) {
+                            const errMessage = err instanceof Error ? err.message : String(err);
+                            console.error(`${LOG_PREFIX.REPAIR} Failed to repair ${error.type}: ${errMessage}`);
+                            failed++;
+                        }
+                    }
+                    // Deduplicate files
+                    const uniqueFiles = [...new Set(filesModified)];
+                    return {
+                        commitMessage: `fix: repair ${repaired} WU inconsistencies`,
+                        files: uniqueFiles,
+                    };
+                },
+            });
         }
-        if (dryRun) {
-            repaired++;
-            continue;
+        catch (err) {
+            // If micro-worktree fails, mark all file repairs as failed
+            const errMessage = err instanceof Error ? err.message : String(err);
+            console.error(`${LOG_PREFIX.REPAIR} Micro-worktree operation failed: ${errMessage}`);
+            failed += fileRepairs.length - repaired;
         }
+    }
+    // Step 2: Process git-only repairs (worktree/branch cleanup) directly
+    for (const error of gitOnlyRepairs) {
         try {
-            const result = await repairSingleError(error, projectRoot);
+            const result = await repairGitOnlyError(error, projectRoot);
             if (result.success) {
                 repaired++;
             }
@@ -285,34 +365,85 @@ export async function repairWUInconsistency(report, options = {}) {
     return { repaired, skipped, failed };
 }
 /**
- * Repair a single inconsistency error
+ * Repair a single file-based error inside a micro-worktree (WU-1078)
+ *
+ * This function performs file modifications inside the worktree path,
+ * which is then committed and pushed atomically by withMicroWorktree.
+ *
+ * @param {ConsistencyError} error - Error object from checkWUConsistency()
+ * @param {string} worktreePath - Path to the micro-worktree
+ * @param {string} projectRoot - Original project root (for reading source files)
+ * @returns {Promise<RepairResult>} Result with success, skipped, reason, and files modified
+ */
+async function repairSingleErrorInWorktree(error, worktreePath, projectRoot) {
+    switch (error.type) {
+        case CONSISTENCY_TYPES.YAML_DONE_NO_STAMP: {
+            const files = await createStampInWorktree(error.wuId, error.title || `WU ${error.wuId}`, worktreePath);
+            return { success: true, files };
+        }
+        case CONSISTENCY_TYPES.YAML_DONE_STATUS_IN_PROGRESS: {
+            const files = await removeWUFromSectionInWorktree(WU_PATHS.STATUS(), error.wuId, '## In Progress', worktreePath, projectRoot);
+            return { success: true, files };
+        }
+        case CONSISTENCY_TYPES.BACKLOG_DUAL_SECTION: {
+            const files = await removeWUFromSectionInWorktree(WU_PATHS.BACKLOG(), error.wuId, '## 🔧 In progress', worktreePath, projectRoot);
+            return { success: true, files };
+        }
+        case CONSISTENCY_TYPES.STAMP_EXISTS_YAML_NOT_DONE: {
+            const files = await updateYamlToDoneInWorktree(error.wuId, worktreePath, projectRoot);
+            return { success: true, files };
+        }
+        default:
+            return { skipped: true, reason: `Unknown error type: ${error.type}` };
+    }
+}
+/**
+ * Repair git-only errors (worktree/branch cleanup) without micro-worktree
+ *
+ * These operations don't modify files in the repo, they only manage git worktrees
+ * and branches, so they can run directly.
  *
- * @param {object} error - Error object from checkWUConsistency()
+ * @param {ConsistencyError} error - Error object
  * @param {string} projectRoot - Project root directory
  * @returns {Promise<RepairResult>} Result with success, skipped, and reason
  */
-async function repairSingleError(error, projectRoot) {
+async function repairGitOnlyError(error, projectRoot) {
     switch (error.type) {
-        case CONSISTENCY_TYPES.YAML_DONE_NO_STAMP:
-            await createStampInProject(error.wuId, error.title || `WU ${error.wuId}`, projectRoot);
-            return { success: true };
-        case CONSISTENCY_TYPES.YAML_DONE_STATUS_IN_PROGRESS:
-            await removeWUFromSection(path.join(projectRoot, WU_PATHS.STATUS()), error.wuId, '## In Progress');
-            return { success: true };
-        case CONSISTENCY_TYPES.BACKLOG_DUAL_SECTION:
-            await removeWUFromSection(path.join(projectRoot, WU_PATHS.BACKLOG()), error.wuId, '## 🔧 In progress');
-            return { success: true };
         case CONSISTENCY_TYPES.ORPHAN_WORKTREE_DONE:
             return await removeOrphanWorktree(error.wuId, error.lane, projectRoot);
-        case CONSISTENCY_TYPES.STAMP_EXISTS_YAML_NOT_DONE:
-            await updateYamlToDone(error.wuId, projectRoot);
-            return { success: true };
         default:
-            return { skipped: true, reason: `Unknown error type: ${error.type}` };
+            return { skipped: true, reason: `Unknown git-only error type: ${error.type}` };
     }
 }
 /**
- * Create stamp file in a specific project root
+ * Create stamp file inside a micro-worktree (WU-1078)
+ *
+ * @param {string} id - WU ID
+ * @param {string} title - WU title
+ * @param {string} worktreePath - Path to the micro-worktree
+ * @returns {Promise<string[]>} List of files created (relative paths)
+ */
+async function createStampInWorktree(id, title, worktreePath) {
+    const stampsDir = path.join(worktreePath, WU_PATHS.STAMPS_DIR());
+    const stampRelPath = WU_PATHS.STAMP(id);
+    const stampAbsPath = path.join(worktreePath, stampRelPath);
+    // Ensure stamps directory exists
+    if (!existsSync(stampsDir)) {
+        mkdirSync(stampsDir, { recursive: true });
+    }
+    // Don't overwrite existing stamp
+    if (existsSync(stampAbsPath)) {
+        return []; // Stamp already exists
+    }
+    // Create stamp file
+    const body = `WU ${id} — ${title}\nCompleted: ${todayISO()}\n`;
+    writeFileSync(stampAbsPath, body, { encoding: 'utf-8' });
+    return [stampRelPath];
+}
+/**
+ * Create stamp file in a specific project root (DEPRECATED - use createStampInWorktree)
+ *
+ * Kept for backwards compatibility with code that doesn't use micro-worktree.
  *
  * @param {string} id - WU ID
  * @param {string} title - WU title
@@ -342,7 +473,7 @@ async function createStampInProject(id, title, projectRoot) {
     await writeFile(stampPath, body, { encoding: 'utf-8' });
 }
 /**
- * Update WU YAML to done+locked+completed state (WU-2412)
+ * Update WU YAML to done+locked+completed state inside a micro-worktree (WU-1078)
  *
  * Repairs STAMP_EXISTS_YAML_NOT_DONE by setting:
  * - status: done
@@ -350,6 +481,43 @@ async function createStampInProject(id, title, projectRoot) {
  * - completed: YYYY-MM-DD (today, unless already set)
  *
  * @param {string} id - WU ID
+ * @param {string} worktreePath - Path to the micro-worktree
+ * @param {string} projectRoot - Original project root (for reading source file)
+ * @returns {Promise<string[]>} List of files modified (relative paths)
+ */
+async function updateYamlToDoneInWorktree(id, worktreePath, projectRoot) {
+    const wuRelPath = WU_PATHS.WU(id);
+    const wuSrcPath = path.join(projectRoot, wuRelPath);
+    const wuDestPath = path.join(worktreePath, wuRelPath);
+    // Read current YAML from project root
+    const content = readFileSync(wuSrcPath, { encoding: 'utf-8' });
+    const wuDoc = parseYAML(content);
+    if (!wuDoc) {
+        throw new Error(`Failed to parse WU YAML: ${wuSrcPath}`);
+    }
+    // Update fields
+    wuDoc.status = WU_STATUS.DONE;
+    wuDoc.locked = true;
+    // Preserve existing completed date if present, otherwise set to today
+    if (!wuDoc.completed) {
+        wuDoc.completed = todayISO();
+    }
+    // Ensure directory exists in worktree
+    const wuDir = path.dirname(wuDestPath);
+    if (!existsSync(wuDir)) {
+        mkdirSync(wuDir, { recursive: true });
+    }
+    // Write updated YAML to worktree
+    const updatedContent = stringifyYAML(wuDoc, { lineWidth: YAML_OPTIONS.LINE_WIDTH });
+    writeFileSync(wuDestPath, updatedContent, { encoding: 'utf-8' });
+    return [wuRelPath];
+}
+/**
+ * Update WU YAML to done+locked+completed state (DEPRECATED - use updateYamlToDoneInWorktree)
+ *
+ * Kept for backwards compatibility.
+ *
+ * @param {string} id - WU ID
  * @param {string} projectRoot - Project root directory
  * @returns {Promise<void>}
  */
@@ -373,7 +541,69 @@ async function updateYamlToDone(id, projectRoot) {
     await writeFile(wuPath, updatedContent, { encoding: 'utf-8' });
 }
 /**
- * Remove WU entry from a specific section in a markdown file
+ * Remove WU entry from a specific section in a markdown file inside a micro-worktree (WU-1078)
+ *
+ * @param {string} relFilePath - Relative path to the markdown file
+ * @param {string} id - WU ID to remove
+ * @param {string} sectionHeading - Section heading to target
+ * @param {string} worktreePath - Path to the micro-worktree
+ * @param {string} projectRoot - Original project root (for reading source file)
+ * @returns {Promise<string[]>} List of files modified (relative paths)
+ */
+async function removeWUFromSectionInWorktree(relFilePath, id, sectionHeading, worktreePath, projectRoot) {
+    const srcPath = path.join(projectRoot, relFilePath);
+    const destPath = path.join(worktreePath, relFilePath);
+    // Check if source file exists
+    if (!existsSync(srcPath)) {
+        return []; // File doesn't exist
+    }
+    const content = readFileSync(srcPath, { encoding: 'utf-8' });
+    const lines = content.split(/\r?\n/);
+    let inTargetSection = false;
+    let nextSectionIdx = -1;
+    let sectionStartIdx = -1;
+    // Normalize heading for comparison (lowercase, trim)
+    const normalizedHeading = sectionHeading.toLowerCase().trim();
+    // Find section boundaries
+    for (let i = 0; i < lines.length; i++) {
+        const normalizedLine = lines[i].toLowerCase().trim();
+        if (normalizedLine === normalizedHeading || normalizedLine.startsWith(normalizedHeading)) {
+            inTargetSection = true;
+            sectionStartIdx = i;
+            continue;
+        }
+        if (inTargetSection && lines[i].trim().startsWith('## ')) {
+            nextSectionIdx = i;
+            break;
+        }
+    }
+    if (sectionStartIdx === -1)
+        return [];
+    const endIdx = nextSectionIdx === -1 ? lines.length : nextSectionIdx;
+    // Filter out lines containing the WU ID in the target section
+    const newLines = [];
+    let modified = false;
+    for (let i = 0; i < lines.length; i++) {
+        if (i > sectionStartIdx && i < endIdx && lines[i].includes(id)) {
+            modified = true;
+            continue; // Skip this line
+        }
+        newLines.push(lines[i]);
+    }
+    if (!modified)
+        return [];
+    // Ensure directory exists in worktree
+    const destDir = path.dirname(destPath);
+    if (!existsSync(destDir)) {
+        mkdirSync(destDir, { recursive: true });
+    }
+    writeFileSync(destPath, newLines.join(STRING_LITERALS.NEWLINE), { encoding: 'utf-8' });
+    return [relFilePath];
+}
+/**
+ * Remove WU entry from a specific section in a markdown file (DEPRECATED)
+ *
+ * Kept for backwards compatibility.
  *
  * @param {string} filePath - Path to the markdown file
  * @param {string} id - WU ID to remove

package/dist/wu-state-schema.d.ts

@@ -17,8 +17,9 @@ import { z } from 'zod';
  * - complete: WU completed (transitions to done)
  * - checkpoint: Progress checkpoint (WU-1748: cross-agent visibility)
  * - spawn: WU spawned from parent (WU-1947: parent-child relationships)
+ * - release: WU released (WU-1080: transitions from in_progress to ready for orphan recovery)
  */
-export declare const WU_EVENT_TYPES: readonly ["create", "claim", "block", "unblock", "complete", "checkpoint", "spawn"];
+export declare const WU_EVENT_TYPES: readonly ["create", "claim", "block", "unblock", "complete", "checkpoint", "spawn", "release"];
 /** Type for WU event types */
 export type WUEventType = (typeof WU_EVENT_TYPES)[number];
 /**
@@ -103,6 +104,17 @@ export declare const SpawnEventSchema: z.ZodObject<{
     parentWuId: z.ZodString;
     spawnId: z.ZodString;
 }, z.core.$strip>;
+/**
+ * Release event schema (WU-1080: orphan recovery)
+ * Releases an in_progress WU back to ready state when agent is interrupted.
+ * Allows another agent to reclaim the orphaned WU.
+ */
+export declare const ReleaseEventSchema: z.ZodObject<{
+    wuId: z.ZodString;
+    timestamp: z.ZodString;
+    type: z.ZodLiteral<"release">;
+    reason: z.ZodString;
+}, z.core.$strip>;
 /**
  * Union schema for all event types
  */
@@ -145,6 +157,11 @@ export declare const WUEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"spawn">;
     parentWuId: z.ZodString;
     spawnId: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    wuId: z.ZodString;
+    timestamp: z.ZodString;
+    type: z.ZodLiteral<"release">;
+    reason: z.ZodString;
 }, z.core.$strip>], "type">;
 /**
  * TypeScript types inferred from schemas
@@ -156,6 +173,7 @@ export type UnblockEvent = z.infer<typeof UnblockEventSchema>;
 export type CompleteEvent = z.infer<typeof CompleteEventSchema>;
 export type CheckpointEvent = z.infer<typeof CheckpointEventSchema>;
 export type SpawnEvent = z.infer<typeof SpawnEventSchema>;
+export type ReleaseEvent = z.infer<typeof ReleaseEventSchema>;
 export type WUEvent = z.infer<typeof WUEventSchema>;
 /**
  * Validates WU event data against schema
@@ -210,4 +228,9 @@ export declare function validateWUEvent(data: any): z.ZodSafeParseResult<{
     type: "spawn";
     parentWuId: string;
     spawnId: string;
+} | {
+    wuId: string;
+    timestamp: string;
+    type: "release";
+    reason: string;
 }>;

package/dist/wu-state-schema.js

@@ -17,6 +17,7 @@ import { z } from 'zod';
  * - complete: WU completed (transitions to done)
  * - checkpoint: Progress checkpoint (WU-1748: cross-agent visibility)
  * - spawn: WU spawned from parent (WU-1947: parent-child relationships)
+ * - release: WU released (WU-1080: transitions from in_progress to ready for orphan recovery)
  */
 export const WU_EVENT_TYPES = [
     'create',
@@ -26,6 +27,7 @@ export const WU_EVENT_TYPES = [
     'complete',
     'checkpoint',
     'spawn',
+    'release',
 ];
 /**
  * WU status values (matches LumenFlow state machine)
@@ -125,6 +127,16 @@ export const SpawnEventSchema = BaseEventSchema.extend({
     /** Unique spawn identifier */
     spawnId: z.string().min(1, { message: 'Spawn ID is required' }),
 });
+/**
+ * Release event schema (WU-1080: orphan recovery)
+ * Releases an in_progress WU back to ready state when agent is interrupted.
+ * Allows another agent to reclaim the orphaned WU.
+ */
+export const ReleaseEventSchema = BaseEventSchema.extend({
+    type: z.literal('release'),
+    /** Reason for releasing the WU */
+    reason: z.string().min(1, { message: ERROR_MESSAGES.REASON_REQUIRED }),
+});
 /**
  * Union schema for all event types
  */
@@ -136,6 +148,7 @@ export const WUEventSchema = z.discriminatedUnion('type', [
     CompleteEventSchema,
     CheckpointEventSchema,
     SpawnEventSchema,
+    ReleaseEventSchema,
 ]);
 /**
  * Validates WU event data against schema

package/dist/wu-state-store.d.ts

@@ -217,6 +217,27 @@ export declare class WUStateStore {
      * await store.spawn('WU-200', 'WU-100', 'spawn-abc123');
      */
     spawn(childWuId: string, parentWuId: string, spawnId: string): Promise<void>;
+    /**
+     * Releases an in_progress WU back to ready state (WU-1080: orphan recovery).
+     *
+     * Use this when an agent is interrupted mid-WU and the WU needs to be
+     * made available for reclaiming by another agent.
+     *
+     * @throws Error If WU is not in_progress
+     *
+     * @example
+     * await store.release('WU-1080', 'Agent interrupted mid-WU');
+     */
+    release(wuId: string, reason: string): Promise<void>;
+    /**
+     * Create a release event without writing to disk.
+     *
+     * Used by transactional flows where event log writes are staged and committed atomically.
+     * WU-1080: Orphan recovery support.
+     *
+     * @throws Error If WU is not in_progress or event fails validation
+     */
+    createReleaseEvent(wuId: string, reason: string, timestamp?: string): WUEvent;
 }
 /**
  * Check if a lock is stale (expired or dead process)

package/dist/wu-state-store.js

@@ -171,6 +171,11 @@ export class WUStateStore {
                 this.byParent.set(parentWuId, new Set());
             }
             this.byParent.get(parentWuId).add(wuId);
+            return;
+        }
+        // WU-1080: Handle release event - transitions from in_progress to ready
+        if (type === 'release') {
+            this._transitionToStatus(wuId, 'ready');
         }
     }
     /**
@@ -446,6 +451,55 @@ export class WUStateStore {
         await this._appendEvent(event);
         this._applyEvent(event);
     }
+    /**
+     * Releases an in_progress WU back to ready state (WU-1080: orphan recovery).
+     *
+     * Use this when an agent is interrupted mid-WU and the WU needs to be
+     * made available for reclaiming by another agent.
+     *
+     * @throws Error If WU is not in_progress
+     *
+     * @example
+     * await store.release('WU-1080', 'Agent interrupted mid-WU');
+     */
+    async release(wuId, reason) {
+        // Check state machine: can only release if in_progress
+        const currentState = this.wuState.get(wuId);
+        if (!currentState || currentState.status !== 'in_progress') {
+            throw new Error(`WU ${wuId} is not in_progress`);
+        }
+        const event = {
+            type: 'release',
+            wuId,
+            reason,
+            timestamp: new Date().toISOString(),
+        };
+        await this._appendEvent(event);
+        this._applyEvent(event);
+    }
+    /**
+     * Create a release event without writing to disk.
+     *
+     * Used by transactional flows where event log writes are staged and committed atomically.
+     * WU-1080: Orphan recovery support.
+     *
+     * @throws Error If WU is not in_progress or event fails validation
+     */
+    createReleaseEvent(wuId, reason, timestamp = new Date().toISOString()) {
+        const currentState = this.wuState.get(wuId);
+        if (!currentState || currentState.status !== 'in_progress') {
+            throw new Error(`WU ${wuId} is not in_progress`);
+        }
+        const event = { type: 'release', wuId, reason, timestamp };
+        const validation = validateWUEvent(event);
+        if (!validation.success) {
+            const issues = validation.error.issues
+                .map((issue) => `${issue.path.join('.')}: ${issue.message}`)
+                .join(', ');
+            throw new Error(`Validation error: ${issues}`);
+        }
+        return validation.data;
+    }
 }
 /**
  * Check if a process with given PID is running

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumenflow/core",
-  "version": "1.3.5",
+  "version": "1.4.0",
   "description": "Core WU lifecycle tools for LumenFlow workflow framework",
   "keywords": [
     "lumenflow",
@@ -91,8 +91,8 @@
     "vitest": "^4.0.17"
   },
   "peerDependencies": {
-    "@lumenflow/memory": "1.3.5",
-    "@lumenflow/initiatives": "1.3.5"
+    "@lumenflow/memory": "1.4.0",
+    "@lumenflow/initiatives": "1.4.0"
   },
   "peerDependenciesMeta": {
     "@lumenflow/memory": {