@lumenflow/core 3.2.0 → 3.2.1

package/dist/wu-checkpoint.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Schema version for checkpoint files
+ * Increment when checkpoint format changes
+ */
+export declare const CHECKPOINT_SCHEMA_VERSION = 1;
+/**
+ * @typedef {Object} Checkpoint
+ * @property {number} schemaVersion - Checkpoint format version
+ * @property {string} checkpointId - Unique checkpoint identifier
+ * @property {string} wuId - WU ID this checkpoint is for
+ * @property {string} worktreePath - Path to worktree when checkpoint was created
+ * @property {string} branchName - Lane branch name
+ * @property {string} worktreeHeadSha - Git HEAD SHA of worktree at checkpoint time
+ * @property {string} createdAt - ISO timestamp when checkpoint was created
+ * @property {boolean} gatesPassed - Whether gates passed at this checkpoint
+ * @property {string} [gatesPassedAt] - ISO timestamp when gates passed
+ */
+/**
+ * Options for checkpoint operations
+ */
+interface CheckpointBaseDirOptions {
+    /** Base directory (defaults to cwd) */
+    baseDir?: string;
+}
+/**
+ * Options for creating pre-gates checkpoint
+ */
+export interface CreatePreGatesCheckpointOptions extends CheckpointBaseDirOptions {
+    /** Whether gates already passed (for testing) */
+    gatesPassed?: boolean;
+}
+/**
+ * Create a checkpoint before running gates
+ *
+ * @param {Object} params - Checkpoint parameters
+ * @param {string} params.wuId - WU ID
+ * @param {string} params.worktreePath - Path to worktree
+ * @param {string} params.branchName - Lane branch name
+ * @param {CreatePreGatesCheckpointOptions} [options]
+ * @returns {Promise<Checkpoint>} Created checkpoint
+ */
+export declare function createPreGatesCheckpoint(params: UnsafeAny, options?: CreatePreGatesCheckpointOptions): Promise<{
+    schemaVersion: number;
+    checkpointId: string;
+    wuId: any;
+    worktreePath: any;
+    branchName: any;
+    worktreeHeadSha: string;
+    createdAt: string;
+    gatesPassed: any;
+    gatesPassedAt: string | null;
+}>;
+/**
+ * Mark a checkpoint as having passed gates
+ *
+ * @param {string} wuId - WU ID
+ * @param {CheckpointBaseDirOptions} [options]
+ * @returns {boolean} True if checkpoint was updated
+ */
+export declare function markGatesPassed(wuId: UnsafeAny, options?: CheckpointBaseDirOptions): boolean;
+/**
+ * Get a checkpoint for a WU
+ *
+ * @param {string} wuId - WU ID
+ * @param {CheckpointBaseDirOptions} [options]
+ * @returns {Checkpoint|null} Checkpoint or null if not found
+ */
+export declare function getCheckpoint(wuId: UnsafeAny, options?: CheckpointBaseDirOptions): any;
+/**
+ * Clear a checkpoint for a WU
+ *
+ * @param {string} wuId - WU ID
+ * @param {CheckpointBaseDirOptions} [options]
+ */
+export declare function clearCheckpoint(wuId: UnsafeAny, options?: CheckpointBaseDirOptions): void;
+/**
+ * @typedef {Object} CanSkipResult
+ * @property {boolean} canSkip - Whether gates can be skipped
+ * @property {string} [reason] - Reason if canSkip is false
+ * @property {Checkpoint} [checkpoint] - Checkpoint if canSkip is true
+ */
+/**
+ * Check if gates can be skipped based on checkpoint
+ *
+ * Gates can be skipped if:
+ * 1. A valid checkpoint exists
+ * 2. Schema version matches
+ * 3. Gates already passed at checkpoint
+ * 4. Worktree HEAD SHA hasn't changed
+ * 5. Checkpoint isn't stale
+ *
+ * @param {string} wuId - WU ID
+ * @param {CanSkipGatesOptions} [options]
+ * @returns {CanSkipResult} Result indicating if gates can be skipped
+ */
+export interface CanSkipGatesOptions extends CheckpointBaseDirOptions {
+    /** Current worktree HEAD SHA to compare */
+    currentHeadSha?: string;
+}
+export declare function canSkipGates(wuId: UnsafeAny, options?: CanSkipGatesOptions): {
+    canSkip: boolean;
+    reason: string;
+    checkpoint?: undefined;
+} | {
+    canSkip: boolean;
+    checkpoint: any;
+    reason?: undefined;
+};
+export {};
+//# sourceMappingURL=wu-checkpoint.d.ts.map

package/dist/wu-checkpoint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wu-checkpoint.d.ts","sourceRoot":"","sources":["../src/wu-checkpoint.ts"],"names":[],"mappings":"AAyBA;;;GAGG;AACH,eAAO,MAAM,yBAAyB,IAAI,CAAC;AAa3C;;;;;;;;;;;GAWG;AAEH;;GAEG;AACH,UAAU,wBAAwB;IAChC,uCAAuC;IACvC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AA2FD;;GAEG;AACH,MAAM,WAAW,+BAAgC,SAAQ,wBAAwB;IAC/E,iDAAiD;IACjD,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;;;;;;;;GASG;AACH,wBAAsB,wBAAwB,CAC5C,MAAM,EAAE,SAAS,EACjB,OAAO,GAAE,+BAAoC;;;;;;;;;;GAyB9C;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,GAAE,wBAA6B,WAetF;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,GAAE,wBAA6B,OAcpF;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,GAAE,wBAA6B,QAOtF;AAED;;;;;GAKG;AAEH;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,mBAAoB,SAAQ,wBAAwB;IACnE,2CAA2C;IAC3C,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,GAAE,mBAAwB;;;;;;;;EA2C9E"}

package/dist/wu-checkpoint.js

@@ -0,0 +1,238 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * WU-1747: WU Checkpoint Module
+ *
+ * Provides checkpoint-based gate resumption for wu:done operations.
+ * Allows failed wu:done to resume from checkpoint without re-running gates
+ * if nothing has changed since the checkpoint was created.
+ *
+ * Features:
+ * - Pre-gates checkpoint creation with worktree state
+ * - SHA-based change detection
+ * - Schema versioning for forward compatibility
+ * - Automatic stale checkpoint cleanup
+ *
+ * @module wu-checkpoint
+ */
+import { existsSync, readFileSync, writeFileSync, unlinkSync, mkdirSync } from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { LOG_PREFIX, EMOJI, LUMENFLOW_PATHS } from './wu-constants.js';
+import { MS_PER_DAY } from './constants/duration-constants.js';
+/**
+ * Schema version for checkpoint files
+ * Increment when checkpoint format changes
+ */
+export const CHECKPOINT_SCHEMA_VERSION = 1;
+/**
+ * Checkpoint directory within .lumenflow
+ */
+const CHECKPOINT_DIR = 'checkpoints';
+/**
+ * Maximum age for a checkpoint before it's considered stale (24 hours)
+ * WU-2044: Uses canonical MS_PER_DAY from duration-constants.ts
+ */
+const CHECKPOINT_MAX_AGE_MS = MS_PER_DAY;
+/**
+ * Get the path to a checkpoint file
+ *
+ * @param {string} wuId - WU ID
+ * @param {CheckpointBaseDirOptions} [options]
+ * @returns {string} Path to checkpoint file
+ */
+function getCheckpointPath(wuId, options = {}) {
+    const baseDir = options.baseDir || process.cwd();
+    return path.join(baseDir, LUMENFLOW_PATHS.BASE, CHECKPOINT_DIR, `${wuId}.checkpoint.json`);
+}
+/**
+ * Ensure checkpoint directory exists
+ *
+ * @param {CheckpointBaseDirOptions} [options]
+ */
+function ensureCheckpointDir(options = {}) {
+    const baseDir = options.baseDir || process.cwd();
+    const checkpointDir = path.join(baseDir, LUMENFLOW_PATHS.BASE, CHECKPOINT_DIR);
+    if (!existsSync(checkpointDir)) {
+        mkdirSync(checkpointDir, { recursive: true });
+    }
+}
+/**
+ * Generate a unique checkpoint ID
+ *
+ * @returns {string} Unique checkpoint ID
+ */
+function generateCheckpointId() {
+    return `ckpt-${crypto.randomUUID().slice(0, 8)}`;
+}
+/**
+ * Get the current HEAD SHA from a git directory
+ * Falls back to placeholder if git operations fail
+ *
+ * @param {string} dir - Directory to get HEAD SHA from
+ * @returns {string} HEAD SHA or placeholder
+ */
+function getHeadSha(dir) {
+    try {
+        // Try to read .git/HEAD directly for speed
+        const gitDir = path.join(dir, '.git');
+        if (existsSync(gitDir)) {
+            const headPath = path.join(gitDir, 'HEAD');
+            if (existsSync(headPath)) {
+                const headContent = readFileSync(headPath, 'utf8').trim();
+                // If it's a ref, read the ref file
+                if (headContent.startsWith('ref: ')) {
+                    const refPath = path.join(gitDir, headContent.slice(5));
+                    if (existsSync(refPath)) {
+                        return readFileSync(refPath, 'utf8').trim();
+                    }
+                }
+                // It's a direct SHA
+                return headContent;
+            }
+        }
+        // For worktrees, .git is a file pointing to the main repo
+        const gitFile = path.join(dir, '.git');
+        if (existsSync(gitFile)) {
+            const gitFileContent = readFileSync(gitFile, 'utf8').trim();
+            if (gitFileContent.startsWith('gitdir: ')) {
+                const worktreeGitDir = gitFileContent.slice(8);
+                const headPath = path.join(worktreeGitDir, 'HEAD');
+                if (existsSync(headPath)) {
+                    const headContent = readFileSync(headPath, 'utf8').trim();
+                    if (headContent.startsWith('ref: ')) {
+                        // Need to resolve from main repo's refs
+                        const mainGitDir = path.resolve(worktreeGitDir, '..', '..');
+                        const refPath = path.join(mainGitDir, headContent.slice(5));
+                        if (existsSync(refPath)) {
+                            return readFileSync(refPath, 'utf8').trim();
+                        }
+                    }
+                    return headContent;
+                }
+            }
+        }
+        return 'unknown-sha';
+    }
+    catch {
+        return 'unknown-sha';
+    }
+}
+/**
+ * Create a checkpoint before running gates
+ *
+ * @param {Object} params - Checkpoint parameters
+ * @param {string} params.wuId - WU ID
+ * @param {string} params.worktreePath - Path to worktree
+ * @param {string} params.branchName - Lane branch name
+ * @param {CreatePreGatesCheckpointOptions} [options]
+ * @returns {Promise<Checkpoint>} Created checkpoint
+ */
+export async function createPreGatesCheckpoint(params, options = {}) {
+    const { wuId, worktreePath, branchName, gatesPassed = false } = params;
+    const { baseDir } = options;
+    ensureCheckpointDir({ baseDir });
+    const checkpoint = {
+        schemaVersion: CHECKPOINT_SCHEMA_VERSION,
+        checkpointId: generateCheckpointId(),
+        wuId,
+        worktreePath,
+        branchName,
+        worktreeHeadSha: getHeadSha(worktreePath),
+        createdAt: new Date().toISOString(),
+        gatesPassed,
+        gatesPassedAt: gatesPassed ? new Date().toISOString() : null,
+    };
+    const checkpointPath = getCheckpointPath(wuId, { baseDir });
+    writeFileSync(checkpointPath, JSON.stringify(checkpoint, null, 2));
+    console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Created pre-gates checkpoint for ${wuId}`);
+    return checkpoint;
+}
+/**
+ * Mark a checkpoint as having passed gates
+ *
+ * @param {string} wuId - WU ID
+ * @param {CheckpointBaseDirOptions} [options]
+ * @returns {boolean} True if checkpoint was updated
+ */
+export function markGatesPassed(wuId, options = {}) {
+    const checkpoint = getCheckpoint(wuId, options);
+    if (!checkpoint) {
+        return false;
+    }
+    checkpoint.gatesPassed = true;
+    checkpoint.gatesPassedAt = new Date().toISOString();
+    const checkpointPath = getCheckpointPath(wuId, options);
+    writeFileSync(checkpointPath, JSON.stringify(checkpoint, null, 2));
+    console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Marked gates passed for ${wuId}`);
+    return true;
+}
+/**
+ * Get a checkpoint for a WU
+ *
+ * @param {string} wuId - WU ID
+ * @param {CheckpointBaseDirOptions} [options]
+ * @returns {Checkpoint|null} Checkpoint or null if not found
+ */
+export function getCheckpoint(wuId, options = {}) {
+    const checkpointPath = getCheckpointPath(wuId, options);
+    if (!existsSync(checkpointPath)) {
+        return null;
+    }
+    try {
+        const content = readFileSync(checkpointPath, 'utf8');
+        return JSON.parse(content);
+    }
+    catch {
+        // Corrupted checkpoint - treat as non-existent
+        return null;
+    }
+}
+/**
+ * Clear a checkpoint for a WU
+ *
+ * @param {string} wuId - WU ID
+ * @param {CheckpointBaseDirOptions} [options]
+ */
+export function clearCheckpoint(wuId, options = {}) {
+    const checkpointPath = getCheckpointPath(wuId, options);
+    if (existsSync(checkpointPath)) {
+        unlinkSync(checkpointPath);
+        console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Cleared checkpoint for ${wuId}`);
+    }
+}
+export function canSkipGates(wuId, options = {}) {
+    const { baseDir, currentHeadSha } = options;
+    const checkpoint = getCheckpoint(wuId, { baseDir });
+    // No checkpoint exists
+    if (!checkpoint) {
+        return { canSkip: false, reason: 'No checkpoint exists' };
+    }
+    // Schema version mismatch
+    if (checkpoint.schemaVersion !== CHECKPOINT_SCHEMA_VERSION) {
+        return {
+            canSkip: false,
+            reason: `Checkpoint schema version mismatch (got ${checkpoint.schemaVersion}, expected ${CHECKPOINT_SCHEMA_VERSION})`,
+        };
+    }
+    // Gates didn't pass at checkpoint
+    if (!checkpoint.gatesPassed) {
+        return { canSkip: false, reason: 'Gates did not pass at checkpoint' };
+    }
+    // Check if checkpoint is stale
+    const checkpointAge = Date.now() - new Date(checkpoint.createdAt).getTime();
+    if (checkpointAge > CHECKPOINT_MAX_AGE_MS) {
+        return { canSkip: false, reason: 'Checkpoint is stale (older than 24 hours)' };
+    }
+    // SHA has changed since checkpoint
+    if (currentHeadSha && currentHeadSha !== checkpoint.worktreeHeadSha) {
+        return {
+            canSkip: false,
+            reason: 'Worktree has changed since checkpoint (SHA mismatch)',
+        };
+    }
+    // All checks passed - gates can be skipped
+    console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Gates can be skipped - checkpoint valid (${checkpoint.checkpointId})`);
+    return { canSkip: true, checkpoint };
+}
+//# sourceMappingURL=wu-checkpoint.js.map

package/dist/wu-checkpoint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wu-checkpoint.js","sourceRoot":"","sources":["../src/wu-checkpoint.ts"],"names":[],"mappings":"AAAA,iCAAiC;AACjC,yCAAyC;AAEzC;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACzF,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,MAAM,MAAM,aAAa,CAAC;AACjC,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACvE,OAAO,EAAE,UAAU,EAAE,MAAM,mCAAmC,CAAC;AAE/D;;;GAGG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC;AAE3C;;GAEG;AACH,MAAM,cAAc,GAAG,aAAa,CAAC;AAErC;;;GAGG;AACH,MAAM,qBAAqB,GAAG,UAAU,CAAC;AAuBzC;;;;;;GAMG;AACH,SAAS,iBAAiB,CAAC,IAAe,EAAE,UAAoC,EAAE;IAChF,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IACjD,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,eAAe,CAAC,IAAI,EAAE,cAAc,EAAE,GAAG,IAAI,kBAAkB,CAAC,CAAC;AAC7F,CAAC;AAED;;;;GAIG;AACH,SAAS,mBAAmB,CAAC,UAAoC,EAAE;IACjE,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IACjD,MAAM,aAAa,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,eAAe,CAAC,IAAI,EAAE,cAAc,CAAC,CAAC;IAC/E,IAAI,CAAC,UAAU,CAAC,aAAa,CAAC,EAAE,CAAC;QAC/B,SAAS,CAAC,aAAa,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAChD,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,SAAS,oBAAoB;IAC3B,OAAO,QAAQ,MAAM,CAAC,UAAU,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;AACnD,CAAC;AAED;;;;;;GAMG;AACH,SAAS,UAAU,CAAC,GAAc;IAChC,IAAI,CAAC;QACH,2CAA2C;QAC3C,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QACtC,IAAI,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;YACvB,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;YAC3C,IAAI,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;gBACzB,MAAM,WAAW,GAAG,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC;gBAC1D,mCAAmC;gBACnC,IAAI,WAAW,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;oBACpC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;oBACxD,IAAI,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;wBACxB,OAAO,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC;oBAC9C,CAAC;gBACH,CAAC;gBACD,oBAAoB;gBACpB,OAAO,WAAW,CAAC;YACrB,CAAC;QACH,CAAC;QAED,0DAA0D;QAC1D,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QACvC,IAAI,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;YACxB,MAAM,cAAc,GAAG,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC;YAC5D,IAAI,cAAc,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;gBAC1C,MAAM,cAAc,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;gBAC/C,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC;gBACnD,IAAI,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;oBACzB,MAAM,WAAW,GAAG,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC;oBAC1D,IAAI,WAAW,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;wBACpC,wCAAwC;wBACxC,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC,cAAc,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;wBAC5D,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;wBAC5D,IAAI,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;4BACxB,OAAO,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC;wBAC9C,CAAC;oBACH,CAAC;oBACD,OAAO,WAAW,CAAC;gBACrB,CAAC;YACH,CAAC;QACH,CAAC;QAED,OAAO,aAAa,CAAC;IACvB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,aAAa,CAAC;IACvB,CAAC;AACH,CAAC;AAUD;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAC5C,MAAiB,EACjB,UAA2C,EAAE;IAE7C,MAAM,EAAE,IAAI,EAAE,YAAY,EAAE,UAAU,EAAE,WAAW,GAAG,KAAK,EAAE,GAAG,MAAM,CAAC;IACvE,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;IAE5B,mBAAmB,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC;IAEjC,MAAM,UAAU,GAAG;QACjB,aAAa,EAAE,yBAAyB;QACxC,YAAY,EAAE,oBAAoB,EAAE;QACpC,IAAI;QACJ,YAAY;QACZ,UAAU;QACV,eAAe,EAAE,UAAU,CAAC,YAAY,CAAC;QACzC,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACnC,WAAW;QACX,aAAa,EAAE,WAAW,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,IAAI;KAC7D,CAAC;IAEF,MAAM,cAAc,GAAG,iBAAiB,CAAC,IAAI,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;IAC5D,aAAa,CAAC,cAAc,EAAE,IAAI,CAAC,SAAS,CAAC,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IAEnE,OAAO,CAAC,GAAG,CAAC,GAAG,UAAU,CAAC,IAAI,IAAI,KAAK,CAAC,OAAO,qCAAqC,IAAI,EAAE,CAAC,CAAC;IAE5F,OAAO,UAAU,CAAC;AACpB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,IAAe,EAAE,UAAoC,EAAE;IACrF,MAAM,UAAU,GAAG,aAAa,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAChD,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,OAAO,KAAK,CAAC;IACf,CAAC;IAED,UAAU,CAAC,WAAW,GAAG,IAAI,CAAC;IAC9B,UAAU,CAAC,aAAa,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAEpD,MAAM,cAAc,GAAG,iBAAiB,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACxD,aAAa,CAAC,cAAc,EAAE,IAAI,CAAC,SAAS,CAAC,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IAEnE,OAAO,CAAC,GAAG,CAAC,GAAG,UAAU,CAAC,IAAI,IAAI,KAAK,CAAC,OAAO,4BAA4B,IAAI,EAAE,CAAC,CAAC;IAEnF,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,IAAe,EAAE,UAAoC,EAAE;IACnF,MAAM,cAAc,GAAG,iBAAiB,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAExD,IAAI,CAAC,UAAU,CAAC,cAAc,CAAC,EAAE,CAAC;QAChC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,YAAY,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC;QACrD,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAC7B,CAAC;IAAC,MAAM,CAAC;QACP,+CAA+C;QAC/C,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,IAAe,EAAE,UAAoC,EAAE;IACrF,MAAM,cAAc,GAAG,iBAAiB,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAExD,IAAI,UAAU,CAAC,cAAc,CAAC,EAAE,CAAC;QAC/B,UAAU,CAAC,cAAc,CAAC,CAAC;QAC3B,OAAO,CAAC,GAAG,CAAC,GAAG,UAAU,CAAC,IAAI,IAAI,KAAK,CAAC,OAAO,2BAA2B,IAAI,EAAE,CAAC,CAAC;IACpF,CAAC;AACH,CAAC;AA4BD,MAAM,UAAU,YAAY,CAAC,IAAe,EAAE,UAA+B,EAAE;IAC7E,MAAM,EAAE,OAAO,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC;IAE5C,MAAM,UAAU,GAAG,aAAa,CAAC,IAAI,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;IAEpD,uBAAuB;IACvB,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,sBAAsB,EAAE,CAAC;IAC5D,CAAC;IAED,0BAA0B;IAC1B,IAAI,UAAU,CAAC,aAAa,KAAK,yBAAyB,EAAE,CAAC;QAC3D,OAAO;YACL,OAAO,EAAE,KAAK;YACd,MAAM,EAAE,2CAA2C,UAAU,CAAC,aAAa,cAAc,yBAAyB,GAAG;SACtH,CAAC;IACJ,CAAC;IAED,kCAAkC;IAClC,IAAI,CAAC,UAAU,CAAC,WAAW,EAAE,CAAC;QAC5B,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,kCAAkC,EAAE,CAAC;IACxE,CAAC;IAED,+BAA+B;IAC/B,MAAM,aAAa,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,CAAC;IAC5E,IAAI,aAAa,GAAG,qBAAqB,EAAE,CAAC;QAC1C,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,2CAA2C,EAAE,CAAC;IACjF,CAAC;IAED,mCAAmC;IACnC,IAAI,cAAc,IAAI,cAAc,KAAK,UAAU,CAAC,eAAe,EAAE,CAAC;QACpE,OAAO;YACL,OAAO,EAAE,KAAK;YACd,MAAM,EAAE,sDAAsD;SAC/D,CAAC;IACJ,CAAC;IAED,2CAA2C;IAC3C,OAAO,CAAC,GAAG,CACT,GAAG,UAAU,CAAC,IAAI,IAAI,KAAK,CAAC,OAAO,6CAA6C,UAAU,CAAC,YAAY,GAAG,CAC3G,CAAC;IAEF,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;AACvC,CAAC"}

package/dist/wu-claim-helpers.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Validates if a string is a valid email address.
+ *
+ * @param {string} value - The string to validate
+ * @returns {boolean} True if valid email, false otherwise
+ */
+export declare function isValidEmail(value: UnsafeAny): boolean;
+/**
+ * Gets a valid email address for WU assignment.
+ *
+ * Fallback chain (WU-1423):
+ * 1. git config user.email
+ * 2. GIT_AUTHOR_EMAIL environment variable
+ * 3. Error (no silent fallback to username)
+ *
+ * @param {object} gitAdapter - Git adapter with getConfigValue method
+ * @returns {Promise<string>} Valid email address
+ * @throws {Error} If no valid email can be determined
+ */
+export declare function getAssignedEmail(gitAdapter: UnsafeAny): Promise<any>;
+//# sourceMappingURL=wu-claim-helpers.d.ts.map

package/dist/wu-claim-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wu-claim-helpers.d.ts","sourceRoot":"","sources":["../src/wu-claim-helpers.ts"],"names":[],"mappings":"AAkBA;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,SAAS,WAK5C;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,gBAAgB,CAAC,UAAU,EAAE,SAAS,gBA6B3D"}

package/dist/wu-claim-helpers.js

@@ -0,0 +1,66 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * @file wu-claim-helpers.ts
+ * Helper functions for wu:claim (WU-1423)
+ *
+ * Extracted email validation logic for testability and SOLID compliance.
+ */
+import { z } from 'zod';
+/**
+ * Zod schema for validating email addresses.
+ * Uses Zod's built-in email validation (library-first, no regex).
+ */
+const emailSchema = z.string().email();
+/**
+ * Validates if a string is a valid email address.
+ *
+ * @param {string} value - The string to validate
+ * @returns {boolean} True if valid email, false otherwise
+ */
+export function isValidEmail(value) {
+    if (!value || typeof value !== 'string') {
+        return false;
+    }
+    return emailSchema.safeParse(value).success;
+}
+/**
+ * Gets a valid email address for WU assignment.
+ *
+ * Fallback chain (WU-1423):
+ * 1. git config user.email
+ * 2. GIT_AUTHOR_EMAIL environment variable
+ * 3. Error (no silent fallback to username)
+ *
+ * @param {object} gitAdapter - Git adapter with getConfigValue method
+ * @returns {Promise<string>} Valid email address
+ * @throws {Error} If no valid email can be determined
+ */
+export async function getAssignedEmail(gitAdapter) {
+    // Try git config user.email first (WU-1427: properly await async method)
+    try {
+        const gitEmail = await gitAdapter.getConfigValue('user.email');
+        const trimmed = gitEmail?.trim();
+        if (trimmed && isValidEmail(trimmed)) {
+            return trimmed;
+        }
+    }
+    catch {
+        // Git config not available, continue to fallback
+    }
+    // Fallback to GIT_AUTHOR_EMAIL (commonly set in CI/scripting)
+    const authorEmail = process.env.GIT_AUTHOR_EMAIL?.trim();
+    if (authorEmail && isValidEmail(authorEmail)) {
+        return authorEmail;
+    }
+    // WU-1423: NO silent fallback to username (GIT_USER, USER)
+    // These are usernames, not email addresses, and would cause wu:done validation failures
+    throw new Error('Cannot determine assigned_to email address.\n\n' +
+        'Checked:\n' +
+        '  1. git config user.email - not set or invalid\n' +
+        '  2. GIT_AUTHOR_EMAIL env var - not set or invalid\n\n' +
+        'Fix:\n' +
+        '  git config --global user.email "you@example.com"\n' +
+        '  OR export GIT_AUTHOR_EMAIL="you@example.com"');
+}
+//# sourceMappingURL=wu-claim-helpers.js.map

package/dist/wu-claim-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wu-claim-helpers.js","sourceRoot":"","sources":["../src/wu-claim-helpers.ts"],"names":[],"mappings":"AAAA,iCAAiC;AACjC,yCAAyC;AAEzC;;;;;GAKG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;GAGG;AACH,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,CAAC;AAEvC;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,KAAgB;IAC3C,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QACxC,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,WAAW,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC;AAC9C,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,UAAqB;IAC1D,yEAAyE;IACzE,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,UAAU,CAAC,cAAc,CAAC,YAAY,CAAC,CAAC;QAC/D,MAAM,OAAO,GAAG,QAAQ,EAAE,IAAI,EAAE,CAAC;QACjC,IAAI,OAAO,IAAI,YAAY,CAAC,OAAO,CAAC,EAAE,CAAC;YACrC,OAAO,OAAO,CAAC;QACjB,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,iDAAiD;IACnD,CAAC;IAED,8DAA8D;IAC9D,MAAM,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,gBAAgB,EAAE,IAAI,EAAE,CAAC;IACzD,IAAI,WAAW,IAAI,YAAY,CAAC,WAAW,CAAC,EAAE,CAAC;QAC7C,OAAO,WAAW,CAAC;IACrB,CAAC;IAED,2DAA2D;IAC3D,wFAAwF;IACxF,MAAM,IAAI,KAAK,CACb,iDAAiD;QAC/C,YAAY;QACZ,mDAAmD;QACnD,wDAAwD;QACxD,QAAQ;QACR,sDAAsD;QACtD,gDAAgD,CACnD,CAAC;AACJ,CAAC"}

package/dist/wu-claim-resume.d.ts

@@ -0,0 +1,106 @@
+/**
+ * @typedef {Object} ResumeResult
+ * @property {boolean} success - Whether the resume operation succeeded
+ * @property {boolean} handoff - Whether this was a handoff (vs normal claim)
+ * @property {number|null} previousPid - PID of the previous lock holder
+ * @property {string|null} previousSession - Session ID of the previous lock holder
+ * @property {string|null} error - Error message if operation failed
+ * @property {string|null} uncommittedSummary - Summary of uncommitted changes in worktree
+ */
+/**
+ * Check if a process is running by sending signal 0.
+ * This doesn't actually send a signal, but checks if the process exists.
+ *
+ * @param {number} pid - Process ID to check
+ * @returns {boolean} True if process is running, false if not
+ */
+export declare function isProcessRunning(pid: UnsafeAny): boolean;
+/**
+ * Resume a WU claim from a crashed/killed agent (handoff).
+ *
+ * This function:
+ * 1. Verifies the worktree exists
+ * 2. Reads the existing lock file
+ * 3. Verifies the old PID is dead (safety check)
+ * 4. Updates the lock file with the new PID
+ *
+ * @param {Object} options - Resume options
+ * @param {string} options.wuId - WU ID (e.g., "WU-2411")
+ * @param {string} options.lane - Lane name (e.g., "Operations: Tooling")
+ * @param {string} options.worktreePath - Path to the existing worktree
+ * @param {string} [options.baseDir] - Base directory for lock files (defaults to project root)
+ * @param {string} [options.agentSession] - New agent session ID
+ * @returns {Promise<ResumeResult>} Result of the resume operation
+ */
+export declare function resumeClaimForHandoff(options: UnsafeAny): Promise<{
+    success: boolean;
+    handoff: boolean;
+    previousPid: null;
+    previousSession: null;
+    error: string;
+    uncommittedSummary: null;
+} | {
+    success: boolean;
+    handoff: boolean;
+    previousPid: number;
+    previousSession: string | null;
+    error: string;
+    uncommittedSummary: null;
+} | {
+    success: boolean;
+    handoff: boolean;
+    previousPid: number;
+    previousSession: string | null;
+    error: null;
+    uncommittedSummary: null;
+}>;
+/**
+ * Get a summary of uncommitted changes in a worktree.
+ *
+ * @param {Object} gitAdapter - Git adapter with getStatus method
+ * @returns {Promise<string|null>} Summary of uncommitted changes, or null if clean
+ */
+export declare function getWorktreeUncommittedChanges(gitAdapter: UnsafeAny): Promise<any>;
+/**
+ * Format uncommitted changes for display.
+ *
+ * @param {string} status - Raw git status output
+ * @returns {string} Formatted summary for display
+ */
+export declare function formatUncommittedChanges(status: UnsafeAny): string;
+/**
+ * Create a checkpoint in the memory layer documenting the handoff.
+ *
+ * @param {Object} options - Checkpoint options
+ * @param {string} options.wuId - WU ID
+ * @param {number} options.previousPid - Previous owner's PID
+ * @param {number} options.newPid - New owner's PID
+ * @param {string|null} options.previousSession - Previous owner's session ID
+ * @param {string|null} options.uncommittedSummary - Summary of uncommitted changes
+ * @param {Object} [options.memoryLayer] - Memory layer interface (for testing)
+ * @returns {Promise<{success: boolean, checkpointId?: string, error?: string}>}
+ */
+export declare function createHandoffCheckpoint(options: UnsafeAny): Promise<{
+    success: boolean;
+    checkpointId: any;
+    error?: undefined;
+} | {
+    success: boolean;
+    error: any;
+    checkpointId?: undefined;
+}>;
+/**
+ * Check if a worktree exists and is valid for resumption.
+ *
+ * @param {string} worktreePath - Path to check
+ * @param {string} _expectedBranch - Expected branch name (unused, for future validation)
+ * @returns {{valid: boolean, error?: string}}
+ */
+export declare function validateWorktreeForResume(worktreePath: UnsafeAny, _expectedBranch: UnsafeAny): {
+    valid: boolean;
+    error: string;
+} | {
+    valid: boolean;
+    error?: undefined;
+};
+//# sourceMappingURL=wu-claim-resume.d.ts.map

package/dist/wu-claim-resume.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wu-claim-resume.d.ts","sourceRoot":"","sources":["../src/wu-claim-resume.ts"],"names":[],"mappings":"AA0BA;;;;;;;;GAQG;AAEH;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,SAAS,WAgB9C;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,qBAAqB,CAAC,OAAO,EAAE,SAAS;;;;;;;;;;;;;;;;;;;;;GAgG7D;AAED;;;;;GAKG;AACH,wBAAsB,6BAA6B,CAAC,UAAU,EAAE,SAAS,gBAQxE;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,SAAS,UAwBzD;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,uBAAuB,CAAC,OAAO,EAAE,SAAS;;;;;;;;GA0C/D;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,YAAY,EAAE,SAAS,EAAE,eAAe,EAAE,SAAS;;;;;;EAkB5F"}