@lumenflow/core 1.3.5 → 1.3.6

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.3.6",
   "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.3.6",
+    "@lumenflow/initiatives": "1.3.6"
   },
   "peerDependenciesMeta": {
     "@lumenflow/memory": {