@elaraai/e3-core 0.0.2-beta.20 → 0.0.2-beta.21

package/dist/src/objects.js

@@ -2,244 +2,23 @@
  * Copyright (c) 2025 Elara AI Pty Ltd
  * Licensed under BSL 1.1. See LICENSE for details.
  */
-import * as fs from 'fs/promises';
-import * as path from 'path';
-import * as crypto from 'crypto';
-import { Readable } from 'stream';
-import { pipeline } from 'stream/promises';
-import { createWriteStream } from 'fs';
-import { ObjectNotFoundError, isNotFoundError } from './errors.js';
-/**
- * Calculate SHA256 hash of data
- */
-export function computeHash(data) {
-    return crypto.createHash('sha256').update(data).digest('hex');
-}
 /**
- * Calculate SHA256 hash of a stream
- * @internal
- */
-async function computeHashFromStream(stream) {
-    const hash = crypto.createHash('sha256');
-    const chunks = [];
-    const reader = stream.getReader();
-    while (true) {
-        const { done, value } = await reader.read();
-        if (done)
-            break;
-        hash.update(value);
-        chunks.push(value);
-    }
-    return {
-        hash: hash.digest('hex'),
-        data: chunks,
-    };
-}
-/**
- * Atomically write an object to the repository
+ * Generic object utilities for e3.
  *
- * @param repoPath - Path to e3 repository
- * @param data - Data to store
- * @returns SHA256 hash of the data
+ * This module contains only storage-agnostic utilities.
+ * Local filesystem operations are in storage/local/LocalObjectStore.ts
  */
-export async function objectWrite(repoPath, data) {
-    const extension = '.beast2';
-    const hash = computeHash(data);
-    // Split hash: first 2 chars as directory
-    const dirName = hash.slice(0, 2);
-    const fileName = hash.slice(2) + extension;
-    const dirPath = path.join(repoPath, 'objects', dirName);
-    const filePath = path.join(dirPath, fileName);
-    // Check if already exists
-    try {
-        await fs.access(filePath);
-        return hash; // Already exists
-    }
-    catch {
-        // Doesn't exist, continue
-    }
-    // Create directory if needed
-    await fs.mkdir(dirPath, { recursive: true });
-    // Write atomically: stage in same directory (same filesystem) + rename
-    // Staging files use .partial extension; gc can clean up any orphaned ones
-    // Use random suffix to avoid collisions with concurrent writes
-    const randomSuffix = Math.random().toString(36).slice(2, 10);
-    const stagingPath = path.join(dirPath, `${fileName}.${Date.now()}.${randomSuffix}.partial`);
-    await fs.writeFile(stagingPath, data);
-    try {
-        await fs.rename(stagingPath, filePath);
-    }
-    catch (err) {
-        // If rename fails because target exists (concurrent write won), that's fine
-        // Clean up our staging file
-        try {
-            await fs.unlink(stagingPath);
-        }
-        catch {
-            // Ignore cleanup errors
-        }
-        // Verify the file exists (another writer should have created it)
-        try {
-            await fs.access(filePath);
-        }
-        catch {
-            // File doesn't exist and rename failed - re-throw original error
-            throw err;
-        }
-    }
-    return hash;
-}
-/**
- * Atomically write a stream to the repository
- *
- * @param repoPath - Path to e3 repository
- * @param stream - Stream to store
- * @returns SHA256 hash of the data
- */
-export async function objectWriteStream(repoPath, stream) {
-    const extension = '.beast2';
-    // First pass: compute hash while collecting data
-    const { hash, data } = await computeHashFromStream(stream);
-    // Split hash: first 2 chars as directory
-    const dirName = hash.slice(0, 2);
-    const fileName = hash.slice(2) + extension;
-    const dirPath = path.join(repoPath, 'objects', dirName);
-    const filePath = path.join(dirPath, fileName);
-    // Check if already exists
-    try {
-        await fs.access(filePath);
-        return hash; // Already exists
-    }
-    catch {
-        // Doesn't exist, continue
-    }
-    // Create directory if needed
-    await fs.mkdir(dirPath, { recursive: true });
-    // Write atomically: stage in same directory (same filesystem) + rename
-    // Staging files use .partial extension; gc can clean up any orphaned ones
-    // Use random suffix to avoid collisions with concurrent writes
-    const randomSuffix = Math.random().toString(36).slice(2, 10);
-    const stagingPath = path.join(dirPath, `${fileName}.${Date.now()}.${randomSuffix}.partial`);
-    // Reconstruct stream from collected chunks
-    const nodeStream = Readable.from(data);
-    const writeStream = createWriteStream(stagingPath);
-    await pipeline(nodeStream, writeStream);
-    try {
-        await fs.rename(stagingPath, filePath);
-    }
-    catch (err) {
-        // If rename fails because target exists (concurrent write won), that's fine
-        // Clean up our staging file
-        try {
-            await fs.unlink(stagingPath);
-        }
-        catch {
-            // Ignore cleanup errors
-        }
-        // Verify the file exists (another writer should have created it)
-        try {
-            await fs.access(filePath);
-        }
-        catch {
-            // File doesn't exist and rename failed - re-throw original error
-            throw err;
-        }
-    }
-    return hash;
-}
-/**
- * Read an object from the repository
- *
- * @param repoPath - Path to e3 repository
- * @param hash - SHA256 hash of the object
- * @returns Object data
- * @throws {ObjectNotFoundError} If object not found
- */
-export async function objectRead(repoPath, hash) {
-    const extension = '.beast2';
-    const dirName = hash.slice(0, 2);
-    const fileName = hash.slice(2) + extension;
-    const filePath = path.join(repoPath, 'objects', dirName, fileName);
-    try {
-        return await fs.readFile(filePath);
-    }
-    catch (err) {
-        if (isNotFoundError(err)) {
-            throw new ObjectNotFoundError(hash);
-        }
-        throw err;
-    }
-}
-/**
- * Check if an object exists in the repository
- *
- * @param repoPath - Path to e3 repository
- * @param hash - SHA256 hash of the object
- * @returns true if object exists
- */
-export async function objectExists(repoPath, hash) {
-    const filePath = objectPath(repoPath, hash);
-    try {
-        await fs.access(filePath);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-/**
- * Get the filesystem path for an object
- *
- * @param repoPath - Path to e3 repository
- * @param hash - SHA256 hash of the object
- * @returns Filesystem path: objects/<hash[0..2]>/<hash[2..]>.beast2
- */
-export function objectPath(repoPath, hash) {
-    const dirName = hash.slice(0, 2);
-    const fileName = hash.slice(2) + '.beast2';
-    return path.join(repoPath, 'objects', dirName, fileName);
-}
+import * as crypto from 'crypto';
 /**
- * Get the minimum unambiguous prefix length for an object hash.
+ * Calculate SHA256 hash of data.
  *
- * Scans the object store to find the shortest prefix of the given hash
- * that uniquely identifies it among all stored objects.
+ * This is the core hashing function used throughout e3 for content addressing.
+ * It's storage-agnostic and can be used with any backend.
  *
- * @param repoPath - Path to e3 repository
- * @param hash - Full SHA256 hash of the object
- * @param minLength - Minimum prefix length to return (default: 4)
- * @returns Minimum unambiguous prefix length
+ * @param data - Data to hash
+ * @returns SHA256 hash as a hex string
  */
-export async function objectAbbrev(repoPath, hash, minLength = 4) {
-    const objectsDir = path.join(repoPath, 'objects');
-    const targetPrefix = hash.slice(0, 2);
-    // Collect all hashes that share the same 2-char prefix directory
-    const hashes = [];
-    try {
-        const dirPath = path.join(objectsDir, targetPrefix);
-        const entries = await fs.readdir(dirPath);
-        for (const entry of entries) {
-            if (entry.endsWith('.beast2') && !entry.includes('.partial')) {
-                // Reconstruct full hash: dir prefix + filename without extension
-                const fullHash = targetPrefix + entry.slice(0, -7); // remove '.beast2'
-                hashes.push(fullHash);
-            }
-        }
-    }
-    catch {
-        // Directory doesn't exist - hash is unique at minimum length
-        return minLength;
-    }
-    // Find minimum length that disambiguates from all other hashes
-    let length = minLength;
-    while (length < hash.length) {
-        const prefix = hash.slice(0, length);
-        const conflicts = hashes.filter((h) => h !== hash && h.startsWith(prefix));
-        if (conflicts.length === 0) {
-            return length;
-        }
-        length++;
-    }
-    return hash.length;
+export function computeHash(data) {
+    return crypto.createHash('sha256').update(data).digest('hex');
 }
 //# sourceMappingURL=objects.js.map

package/dist/src/objects.js.map

@@ -1 +1 @@
-{"version":3,"file":"objects.js","sourceRoot":"","sources":["../../src/objects.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"objects.js","sourceRoot":"","sources":["../../src/objects.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;GAKG;AAEH,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AAEjC;;;;;;;;GAQG;AACH,MAAM,UAAU,WAAW,CAAC,IAAgB;IAC1C,OAAO,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAChE,CAAC"}

package/dist/src/storage/local/LocalLockService.d.ts

@@ -2,8 +2,91 @@
  * Copyright (c) 2025 Elara AI Pty Ltd
  * Licensed under BSL 1.1. See LICENSE for details.
  */
-import type { LockState, LockOperation } from '@elaraai/e3-types';
+import { type LockState, type LockOperation } from '@elaraai/e3-types';
+import { type LockHolderInfo } from '../../errors.js';
 import type { LockHandle, LockService } from '../interfaces.js';
+/**
+ * Handle to a held workspace lock.
+ * Call release() when done to free the lock.
+ */
+export interface WorkspaceLockHandle {
+    /** The resource (workspace name) this lock is for - compatible with LockHandle */
+    readonly resource: string;
+    /** The workspace name this lock is for */
+    readonly workspace: string;
+    /** Path to the lock file */
+    readonly lockPath: string;
+    /** Release the lock. Safe to call multiple times. */
+    release(): Promise<void>;
+}
+/**
+ * Options for acquiring a workspace lock.
+ */
+export interface AcquireLockOptions {
+    /**
+     * If true, wait for the lock to become available instead of failing immediately.
+     * Default: false (fail fast if locked)
+     */
+    wait?: boolean;
+    /**
+     * Timeout in milliseconds when wait=true. Default: 30000 (30 seconds)
+     */
+    timeout?: number;
+}
+/**
+ * Get the lock file path for a workspace.
+ */
+export declare function workspaceLockPath(repoPath: string, workspace: string): string;
+/**
+ * Convert LockState to LockHolderInfo for error display.
+ */
+export declare function lockStateToHolderInfo(state: LockState): LockHolderInfo;
+/**
+ * Check if a lock holder is still alive.
+ * @param holderStr - East text-encoded holder string
+ */
+export declare function isLockHolderAlive(holderStr: string): Promise<boolean>;
+/**
+ * Acquire an exclusive lock on a workspace.
+ *
+ * Uses Linux flock() for kernel-managed locking. The lock is automatically
+ * released when the process exits (even on crash/kill).
+ *
+ * @param repoPath - Path to e3 repository
+ * @param workspace - Workspace name to lock
+ * @param operation - What operation is acquiring the lock
+ * @param options - Lock acquisition options
+ * @returns Lock handle - call release() when done
+ * @throws {WorkspaceLockError} If workspace is locked by another process
+ *
+ * @example
+ * ```typescript
+ * const lock = await acquireWorkspaceLock(repoPath, 'production', { type: 'dataflow', value: null });
+ * try {
+ *   await dataflowExecute(repoPath, 'production', { lock });
+ * } finally {
+ *   await lock.release();
+ * }
+ * ```
+ */
+export declare function acquireWorkspaceLock(repoPath: string, workspace: string, operation: LockOperation, options?: AcquireLockOptions): Promise<WorkspaceLockHandle>;
+/**
+ * Get the lock state for a workspace.
+ *
+ * @param repoPath - Path to e3 repository
+ * @param workspace - Workspace name to check
+ * @returns Lock state if locked, null if not locked
+ */
+export declare function getWorkspaceLockState(repoPath: string, workspace: string): Promise<LockState | null>;
+/**
+ * Get lock holder info for a workspace (for backwards compatibility).
+ *
+ * @param repoPath - Path to e3 repository
+ * @param workspace - Workspace name to check
+ * @returns Lock holder info if locked, null if not locked
+ * @deprecated Use getWorkspaceLockState for full lock information
+ */
+export declare function getWorkspaceLockHolder(repoPath: string, workspace: string): Promise<LockHolderInfo | null>;
 /**
  * Local filesystem implementation of LockService.
  *

package/dist/src/storage/local/LocalLockService.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"LocalLockService.d.ts","sourceRoot":"","sources":["../../../../src/storage/local/LocalLockService.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClE,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAQhE;;;;;;GAMG;AACH,qBAAa,gBAAiB,YAAW,WAAW;IAC5C,OAAO,CACX,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,aAAa,EACxB,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAC7C,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAkB7B,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC;IAInE,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAGhD"}
+{"version":3,"file":"LocalLockService.d.ts","sourceRoot":"","sources":["../../../../src/storage/local/LocalLockService.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAqBH,OAAO,EAAoC,KAAK,SAAS,EAAE,KAAK,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACzG,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAE1E,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAkChE;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,kFAAkF;IAClF,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,0CAA0C;IAC1C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,4BAA4B;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,qDAAqD;IACrD,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IACf;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAMD;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAE7E;AA0BD;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,SAAS,GAAG,cAAc,CAgBtE;AAED;;;GAGG;AACH,wBAAsB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAc3E;AAMD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,oBAAoB,CACxC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,aAAa,EACxB,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,mBAAmB,CAAC,CAgE9B;AAuFD;;;;;;GAMG;AACH,wBAAsB,qBAAqB,CACzC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAoB3B;AAED;;;;;;;GAOG;AACH,wBAAsB,sBAAsB,CAC1C,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAGhC;AAMD;;;;;;GAMG;AACH,qBAAa,gBAAiB,YAAW,WAAW;IAC5C,OAAO,CACX,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,aAAa,EACxB,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAC7C,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAkB7B,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC;IAInE,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAGhD"}

package/dist/src/storage/local/LocalLockService.js

@@ -2,7 +2,311 @@
  * Copyright (c) 2025 Elara AI Pty Ltd
  * Licensed under BSL 1.1. See LICENSE for details.
  */
-import { acquireWorkspaceLock, getWorkspaceLockState, isLockHolderAlive, } from '../../workspaceLock.js';
+/**
+ * Local filesystem implementation of workspace locking.
+ *
+ * Provides exclusive locks on workspaces to prevent concurrent dataflow
+ * executions or writes that could corrupt workspace state. Uses Linux
+ * flock() for automatic lock release on process death.
+ *
+ * Lock mechanism:
+ * - Uses flock(LOCK_EX | LOCK_NB) via the `flock` command for kernel-managed locking
+ * - Lock is automatically released when the process dies (kernel handles this)
+ * - Lock state stored in beast2 format using LockStateType from e3-types
+ * - Holder stored as East text string (e.g., `.process (pid=1234, ...)`)
+ * - Stale lock detection via bootId comparison (handles system restarts)
+ */
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { spawn } from 'child_process';
+import { encodeBeast2For, decodeBeast2For, printFor, parseInferred, variant, none, VariantType } from '@elaraai/east';
+import { LockStateType, ProcessHolderType } from '@elaraai/e3-types';
+import { WorkspaceLockError } from '../../errors.js';
+import { getBootId, getPidStartTime, isProcessAlive } from '../../execution/processHelpers.js';
+// =============================================================================
+// Holder Encoding
+// =============================================================================
+/**
+ * Variant type for encoding holder as East text.
+ * The holder string stores `.process (...)` or other backend-specific variants.
+ */
+const HolderVariantType = VariantType({
+    process: ProcessHolderType,
+});
+/** Print a process holder to East text format */
+const printProcessHolder = printFor(HolderVariantType);
+/**
+ * Parse an East text holder string.
+ * Returns the parsed variant or null if parsing fails.
+ */
+function parseHolder(holderStr) {
+    try {
+        const [_type, value] = parseInferred(holderStr);
+        return value;
+    }
+    catch {
+        return null;
+    }
+}
+// =============================================================================
+// Lock File Helpers
+// =============================================================================
+/**
+ * Get the lock file path for a workspace.
+ */
+export function workspaceLockPath(repoPath, workspace) {
+    return path.join(repoPath, 'workspaces', `${workspace}.lock`);
+}
+/**
+ * Read lock state from a lock file.
+ * Returns null if file doesn't exist or is invalid.
+ */
+async function readLockState(lockPath) {
+    try {
+        const data = await fs.readFile(lockPath);
+        if (data.length === 0)
+            return null;
+        const decoder = decodeBeast2For(LockStateType);
+        return decoder(data);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Write lock state to a lock file in beast2 format.
+ */
+async function writeLockState(lockPath, state) {
+    const encoder = encodeBeast2For(LockStateType);
+    const data = encoder(state);
+    await fs.writeFile(lockPath, data);
+}
+/**
+ * Convert LockState to LockHolderInfo for error display.
+ */
+export function lockStateToHolderInfo(state) {
+    const info = {
+        acquiredAt: state.acquiredAt.toISOString(),
+        operation: state.operation.type,
+    };
+    // Parse the holder string to extract process-specific fields
+    const holder = parseHolder(state.holder);
+    if (holder?.type === 'process') {
+        info.pid = Number(holder.value.pid);
+        info.bootId = holder.value.bootId;
+        info.startTime = Number(holder.value.startTime);
+        info.command = holder.value.command;
+    }
+    return info;
+}
+/**
+ * Check if a lock holder is still alive.
+ * @param holderStr - East text-encoded holder string
+ */
+export async function isLockHolderAlive(holderStr) {
+    const holder = parseHolder(holderStr);
+    if (!holder)
+        return true; // Can't parse - assume alive (safer)
+    if (holder.type === 'process') {
+        return isProcessAlive(Number(holder.value.pid), Number(holder.value.startTime), holder.value.bootId);
+    }
+    // Unknown holder type - assume alive (safer default)
+    return true;
+}
+// =============================================================================
+// Lock Acquisition
+// =============================================================================
+/**
+ * Acquire an exclusive lock on a workspace.
+ *
+ * Uses Linux flock() for kernel-managed locking. The lock is automatically
+ * released when the process exits (even on crash/kill).
+ *
+ * @param repoPath - Path to e3 repository
+ * @param workspace - Workspace name to lock
+ * @param operation - What operation is acquiring the lock
+ * @param options - Lock acquisition options
+ * @returns Lock handle - call release() when done
+ * @throws {WorkspaceLockError} If workspace is locked by another process
+ *
+ * @example
+ * ```typescript
+ * const lock = await acquireWorkspaceLock(repoPath, 'production', { type: 'dataflow', value: null });
+ * try {
+ *   await dataflowExecute(repoPath, 'production', { lock });
+ * } finally {
+ *   await lock.release();
+ * }
+ * ```
+ */
+export async function acquireWorkspaceLock(repoPath, workspace, operation, options = {}) {
+    const lockPath = workspaceLockPath(repoPath, workspace);
+    // Ensure workspaces directory exists
+    await fs.mkdir(path.dirname(lockPath), { recursive: true });
+    // Gather our process identification
+    const pid = process.pid;
+    const bootId = await getBootId();
+    const startTime = await getPidStartTime(pid);
+    const command = process.argv.join(' ');
+    const acquiredAt = new Date();
+    // Encode holder as East text: .process (pid=..., bootId="...", ...)
+    const holderVariant = variant('process', {
+        pid: BigInt(pid),
+        bootId,
+        startTime: BigInt(startTime),
+        command,
+    });
+    const holder = printProcessHolder(holderVariant);
+    const lockState = {
+        operation,
+        holder,
+        acquiredAt,
+        expiresAt: none,
+    };
+    // Try to acquire flock via subprocess
+    // The subprocess holds the lock and we communicate with it via stdin/signals
+    const flockProcess = await tryAcquireFlock(lockPath, lockState, options);
+    if (!flockProcess) {
+        // Failed to acquire - read lock state to report who has it
+        const existingState = await readLockState(lockPath);
+        const holderInfo = existingState ? lockStateToHolderInfo(existingState) : undefined;
+        throw new WorkspaceLockError(workspace, holderInfo);
+    }
+    // Lock acquired! Create handle
+    let released = false;
+    const handle = {
+        resource: workspace,
+        workspace,
+        lockPath,
+        async release() {
+            if (released)
+                return;
+            released = true;
+            // Kill the flock subprocess to release the lock
+            flockProcess.kill('SIGTERM');
+            // Clean up lock file (best effort)
+            try {
+                await fs.unlink(lockPath);
+            }
+            catch {
+                // Ignore - file might already be gone
+            }
+        },
+    };
+    return handle;
+}
+/**
+ * Try to acquire flock using a subprocess.
+ *
+ * We spawn `flock --nonblock <lockfile> cat` which:
+ * 1. Tries to acquire exclusive lock (non-blocking)
+ * 2. If successful, runs `cat` which blocks reading stdin forever
+ * 3. We keep the subprocess alive to hold the lock
+ * 4. When we kill the subprocess, the lock is released
+ *
+ * Returns the subprocess if lock acquired, null if lock is held by another.
+ */
+async function tryAcquireFlock(lockPath, lockState, options) {
+    // First, check if there's a stale lock we can clean up
+    await checkAndCleanStaleLock(lockPath);
+    const args = options.wait
+        ? ['--timeout', String((options.timeout ?? 30000) / 1000), lockPath, 'cat']
+        : ['--nonblock', lockPath, 'cat'];
+    const child = spawn('flock', args, {
+        stdio: ['pipe', 'pipe', 'pipe'],
+        detached: false,
+    });
+    return new Promise((resolve) => {
+        let resolved = false;
+        // If flock fails to acquire, it exits with code 1
+        child.on('error', () => {
+            if (!resolved) {
+                resolved = true;
+                resolve(null);
+            }
+        });
+        child.on('exit', () => {
+            if (!resolved) {
+                resolved = true;
+                // Exit code 1 means lock is held by another
+                resolve(null);
+            }
+        });
+        // Give flock a moment to either acquire or fail
+        // If it's still running after 100ms, we have the lock
+        setTimeout(() => {
+            if (!resolved && !child.killed && child.exitCode === null) {
+                resolved = true;
+                // Write lock state to lock file now that we have the lock
+                void writeLockState(lockPath, lockState).catch((err) => {
+                    console.warn(`Failed to write lock state: ${err instanceof Error ? err.message : String(err)}`);
+                });
+                resolve(child);
+            }
+        }, 100);
+    });
+}
+/**
+ * Check if a lock file exists with stale lock state and clean it up.
+ * A lock is stale if the holder process no longer exists.
+ */
+async function checkAndCleanStaleLock(lockPath) {
+    const state = await readLockState(lockPath);
+    if (!state)
+        return;
+    // Check if the holder is still alive
+    const alive = await isLockHolderAlive(state.holder);
+    if (!alive) {
+        // Stale lock - try to remove it
+        try {
+            await fs.unlink(lockPath);
+        }
+        catch {
+            // Ignore - another process might have cleaned it up
+        }
+    }
+}
+/**
+ * Get the lock state for a workspace.
+ *
+ * @param repoPath - Path to e3 repository
+ * @param workspace - Workspace name to check
+ * @returns Lock state if locked, null if not locked
+ */
+export async function getWorkspaceLockState(repoPath, workspace) {
+    const lockPath = workspaceLockPath(repoPath, workspace);
+    const state = await readLockState(lockPath);
+    if (!state)
+        return null;
+    // Check if the holder is still alive
+    const alive = await isLockHolderAlive(state.holder);
+    if (!alive) {
+        // Stale lock - clean it up and report as not locked
+        try {
+            await fs.unlink(lockPath);
+        }
+        catch {
+            // Ignore
+        }
+        return null;
+    }
+    return state;
+}
+/**
+ * Get lock holder info for a workspace (for backwards compatibility).
+ *
+ * @param repoPath - Path to e3 repository
+ * @param workspace - Workspace name to check
+ * @returns Lock holder info if locked, null if not locked
+ * @deprecated Use getWorkspaceLockState for full lock information
+ */
+export async function getWorkspaceLockHolder(repoPath, workspace) {
+    const state = await getWorkspaceLockState(repoPath, workspace);
+    return state ? lockStateToHolderInfo(state) : null;
+}
+// =============================================================================
+// LockService Interface Implementation
+// =============================================================================
 /**
  * Local filesystem implementation of LockService.
  *