An AI-powered task-management system you can drop into Cursor, Lovable, Windsurf, Roo, and others.
JavaScript aicursorcursor-aicursorailovablelovable-devroocodetask-managertaskstasks-listwindsurfwindsurf-ai
fix: Add cross-process file locking to prevent race conditions (#1566)
Ben Coombs3cc6174b471f
diff --git a/.changeset/fix-file-locking.md b/.changeset/fix-file-locking.mdnew file mode 100644index 00000000..4ffebd13--- /dev/null+++ b/.changeset/fix-file-locking.md@@ -0,0 +1,13 @@+---+"task-master-ai": patch+---++Fix race condition when multiple Claude Code windows write to tasks.json simultaneously++- Add cross-process file locking to prevent concurrent write collisions+- Implement atomic writes using temp file + rename pattern to prevent partial writes+- Re-read file inside lock to get current state, preventing lost updates from stale snapshots+- Add stale lock detection and automatic cleanup (10-second timeout)+- Export `withFileLock` and `withFileLockSync` utilities for use by other modules++This fix prevents data loss that could occur when multiple Task Master instances (e.g., multiple Claude Code windows) access the same tasks.json file concurrently.diff --git a/package-lock.json b/package-lock.jsonindex 003ca692..6d8c5edc 100644--- a/package-lock.json+++ b/package-lock.json@@ -13713,6 +13713,16 @@"integrity": "sha512-PIzZZlEppgrpoT2QgbnDU+MMzuR6BbCjllj0bM70lWoejMeNJAxCchxnv7J3XFkI8MpygtRpzXrIlmWUBclP5A==","license": "MIT"},+ "node_modules/@types/proper-lockfile": {+ "version": "4.1.4",+ "resolved": "https://registry.npmjs.org/@types/proper-lockfile/-/proper-lockfile-4.1.4.tgz",+ "integrity": "sha512-uo2ABllncSqg9F1D4nugVl9v93RmjxF6LJzQLMLDdPaXCUIDPeOJ21Gbqi43xNKzBi/WQ0Q0dICqufzQbMjipQ==",+ "dev": true,+ "license": "MIT",+ "dependencies": {+ "@types/retry": "*"+ }+ },"node_modules/@types/react": {"version": "19.1.8","resolved": "https://registry.npmjs.org/@types/react/-/react-19.1.8.tgz",@@ -13783,6 +13793,13 @@"node": ">= 0.6"}},+ "node_modules/@types/retry": {+ "version": "0.12.5",+ "resolved": "https://registry.npmjs.org/@types/retry/-/retry-0.12.5.tgz",+ "integrity": "sha512-3xSjTp3v03X/lSQLkczaN9UIEwJMoMCA1+Nb5HfbJEQWogdeQIyVtTvxPXDQjZ5zws8rFQfVfRdz03ARihPJgw==",+ "dev": true,+ "license": "MIT"+ },"node_modules/@types/stack-utils": {"version": "2.0.3","resolved": "https://registry.npmjs.org/@types/stack-utils/-/stack-utils-2.0.3.tgz",@@ -29634,6 +29651,23 @@"node": ">= 6"}},+ "node_modules/proper-lockfile": {+ "version": "4.1.2",+ "resolved": "https://registry.npmjs.org/proper-lockfile/-/proper-lockfile-4.1.2.tgz",+ "integrity": "sha512-TjNPblN4BwAWMXU8s9AEz4JmQxnD1NNL7bNOY/AKUzyamc379FWASUhc/K1pL2noVb+XmZKLL68cjzLsiOAMaA==",+ "license": "MIT",+ "dependencies": {+ "graceful-fs": "^4.2.4",+ "retry": "^0.12.0",+ "signal-exit": "^3.0.2"+ }+ },+ "node_modules/proper-lockfile/node_modules/signal-exit": {+ "version": "3.0.7",+ "resolved": "https://registry.npmjs.org/signal-exit/-/signal-exit-3.0.7.tgz",+ "integrity": "sha512-wnD2ZE+l+SPC/uoS0vXeE9L1+0wuaMqKlfz9AMUo38JsyLSBWSFcHR1Rri62LZc12vLr1gb3jl7iwQhgwpAbGQ==",+ "license": "ISC"+ },"node_modules/property-information": {"version": "7.1.0","resolved": "https://registry.npmjs.org/property-information/-/property-information-7.1.0.tgz",@@ -31111,6 +31145,15 @@"url": "https://opencollective.com/unified"}},+ "node_modules/retry": {+ "version": "0.12.0",+ "resolved": "https://registry.npmjs.org/retry/-/retry-0.12.0.tgz",+ "integrity": "sha512-9LkiTwjUh6rT555DtE9rTX+BKByPfrMzEAtnlEtdEwr3Nkffwiihqe2bWADg+OQRjt9gl6ICdmB/ZFDCGAtSow==",+ "license": "MIT",+ "engines": {+ "node": ">= 4"+ }+ },"node_modules/retry-request": {"version": "7.0.2","resolved": "https://registry.npmjs.org/retry-request/-/retry-request-7.0.2.tgz",@@ -36324,6 +36367,7 @@"@supabase/supabase-js": "^2.57.4","date-fns": "^4.1.0","fs-extra": "^11.3.2",+ "proper-lockfile": "^4.1.2","simple-git": "^3.28.0","steno": "^4.0.2","zod": "^4.1.11"@@ -36331,6 +36375,7 @@"devDependencies": {"@types/fs-extra": "^11.0.4","@types/node": "^22.10.5",+ "@types/proper-lockfile": "^4.1.4","@vitest/coverage-v8": "^4.0.10","strip-literal": "3.1.0","typescript": "^5.9.2",diff --git a/packages/tm-core/package.json b/packages/tm-core/package.jsonindex 4724649e..47e0c345 100644--- a/packages/tm-core/package.json+++ b/packages/tm-core/package.json@@ -34,12 +34,14 @@"@supabase/supabase-js": "^2.57.4","date-fns": "^4.1.0","fs-extra": "^11.3.2",+ "proper-lockfile": "^4.1.2","simple-git": "^3.28.0","steno": "^4.0.2","zod": "^4.1.11"},"devDependencies": {"@types/fs-extra": "^11.0.4",+ "@types/proper-lockfile": "^4.1.4","@types/node": "^22.10.5","@vitest/coverage-v8": "^4.0.10","strip-literal": "3.1.0",diff --git a/packages/tm-core/src/modules/storage/adapters/file-storage/file-operations.spec.ts b/packages/tm-core/src/modules/storage/adapters/file-storage/file-operations.spec.tsnew file mode 100644index 00000000..a7ea6069--- /dev/null+++ b/packages/tm-core/src/modules/storage/adapters/file-storage/file-operations.spec.ts@@ -0,0 +1,264 @@+/**+ * Tests for FileOperations class+ * Focuses on modifyJson and cross-process locking functionality+ */++import { describe, it, expect, beforeEach, afterEach } from 'vitest';+import fs from 'node:fs/promises';+import fsSync from 'node:fs';+import path from 'node:path';+import os from 'node:os';+import { FileOperations } from './file-operations.js';++describe('FileOperations', () => {+ let tempDir: string;+ let testFilePath: string;+ let fileOps: FileOperations;++ beforeEach(async () => {+ // Create a temp directory for each test+ tempDir = fsSync.mkdtempSync(path.join(os.tmpdir(), 'tm-core-test-'));+ testFilePath = path.join(tempDir, 'test.json');+ fileOps = new FileOperations();+ });++ afterEach(async () => {+ // Clean up+ await fileOps.cleanup();+ if (tempDir && fsSync.existsSync(tempDir)) {+ fsSync.rmSync(tempDir, { recursive: true, force: true });+ }+ });++ describe('modifyJson', () => {+ it('should modify existing JSON data', async () => {+ // Set up initial data+ await fs.writeFile(testFilePath, JSON.stringify({ count: 0 }));++ // Modify data+ await fileOps.modifyJson(testFilePath, (data: { count: number }) => ({+ ...data,+ count: data.count + 1+ }));++ // Verify+ const result = JSON.parse(await fs.readFile(testFilePath, 'utf-8'));+ expect(result.count).toBe(1);+ });++ it('should create file if it does not exist', async () => {+ const newFilePath = path.join(tempDir, 'new-file.json');++ await fileOps.modifyJson(newFilePath, () => ({ created: true }));++ expect(fsSync.existsSync(newFilePath)).toBe(true);+ const result = JSON.parse(await fs.readFile(newFilePath, 'utf-8'));+ expect(result.created).toBe(true);+ });++ it('should handle async modifier functions', async () => {+ await fs.writeFile(testFilePath, JSON.stringify({ value: 'initial' }));++ await fileOps.modifyJson(+ testFilePath,+ async (data: { value: string }) => {+ // Simulate async operation+ await new Promise((resolve) => setTimeout(resolve, 10));+ return { ...data, value: 'modified' };+ }+ );++ const result = JSON.parse(await fs.readFile(testFilePath, 'utf-8'));+ expect(result.value).toBe('modified');+ });++ it('should re-read file inside lock to prevent stale data', async () => {+ // Initial data+ await fs.writeFile(testFilePath, JSON.stringify({ version: 1 }));++ // Simulate two sequential modifications+ await fileOps.modifyJson(testFilePath, (data: { version: number }) => ({+ version: data.version + 1+ }));++ await fileOps.modifyJson(testFilePath, (data: { version: number }) => ({+ version: data.version + 1+ }));++ // Both modifications should have been applied+ const result = JSON.parse(await fs.readFile(testFilePath, 'utf-8'));+ expect(result.version).toBe(3);+ });++ it('should not leave lock files on success', async () => {+ await fs.writeFile(testFilePath, JSON.stringify({}));++ await fileOps.modifyJson(testFilePath, (data) => ({+ ...data,+ modified: true+ }));++ // Check no lock files exist+ const files = await fs.readdir(tempDir);+ const lockFiles = files.filter((f) => f.endsWith('.lock'));+ expect(lockFiles).toHaveLength(0);+ });++ it('should release lock even if modifier throws', async () => {+ await fs.writeFile(testFilePath, JSON.stringify({}));++ await expect(+ fileOps.modifyJson(testFilePath, () => {+ throw new Error('Modifier error');+ })+ ).rejects.toThrow('Modifier error');++ // Should still be able to acquire lock for another operation+ await fileOps.modifyJson(testFilePath, () => ({ recovered: true }));++ const result = JSON.parse(await fs.readFile(testFilePath, 'utf-8'));+ expect(result.recovered).toBe(true);+ });++ it('should handle empty file gracefully', async () => {+ // Create empty file+ await fs.writeFile(testFilePath, '');++ await fileOps.modifyJson(testFilePath, () => ({ initialized: true }));++ const result = JSON.parse(await fs.readFile(testFilePath, 'utf-8'));+ expect(result.initialized).toBe(true);+ });++ it('should handle file with only whitespace', async () => {+ await fs.writeFile(testFilePath, ' \n ');++ await fileOps.modifyJson(testFilePath, () => ({ initialized: true }));++ const result = JSON.parse(await fs.readFile(testFilePath, 'utf-8'));+ expect(result.initialized).toBe(true);+ });++ it('should throw on corrupted JSON', async () => {+ // Write invalid JSON that is not empty+ await fs.writeFile(testFilePath, '{ invalid json content');++ await expect(+ fileOps.modifyJson(testFilePath, (data) => data)+ ).rejects.toThrow(/Corrupted JSON/);+ });++ it('should preserve complex nested structures', async () => {+ const complexData = {+ tasks: [+ {+ id: 1,+ title: 'Task 1',+ subtasks: [{ id: '1.1', title: 'Subtask' }]+ }+ ],+ metadata: {+ created: '2024-01-01',+ tags: ['tag1', 'tag2']+ }+ };+ await fs.writeFile(testFilePath, JSON.stringify(complexData, null, 2));++ await fileOps.modifyJson(testFilePath, (data: typeof complexData) => ({+ ...data,+ tasks: [...data.tasks, { id: 2, title: 'Task 2', subtasks: [] }]+ }));++ const result = JSON.parse(await fs.readFile(testFilePath, 'utf-8'));+ expect(result.tasks).toHaveLength(2);+ expect(result.tasks[0].subtasks).toHaveLength(1);+ expect(result.metadata.tags).toEqual(['tag1', 'tag2']);+ });+ });++ describe('concurrent operations', () => {+ it('should serialize truly concurrent modifyJson calls', async () => {+ // Initial data+ await fs.writeFile(testFilePath, JSON.stringify({ count: 0 }));++ const numConcurrentWrites = 5;+ const writes = [];++ for (let i = 0; i < numConcurrentWrites; i++) {+ writes.push(+ fileOps.modifyJson(testFilePath, (data: { count: number }) => ({+ count: data.count + 1+ }))+ );+ }++ await Promise.all(writes);++ const result = JSON.parse(await fs.readFile(testFilePath, 'utf-8'));+ expect(result.count).toBe(numConcurrentWrites);+ });++ it('should handle concurrent writes from multiple FileOperations instances', async () => {+ // Initial data+ await fs.writeFile(testFilePath, JSON.stringify({ count: 0 }));++ const numInstances = 3;+ const instances = Array.from(+ { length: numInstances },+ () => new FileOperations()+ );+ const writes = instances.map((ops) =>+ ops.modifyJson(testFilePath, (data: { count: number }) => ({+ count: data.count + 1+ }))+ );++ await Promise.all(writes);++ // Cleanup all instances+ await Promise.all(instances.map((ops) => ops.cleanup()));++ const result = JSON.parse(await fs.readFile(testFilePath, 'utf-8'));+ expect(result.count).toBe(numInstances);+ });+ });++ describe('writeJson', () => {+ it('should write JSON atomically', async () => {+ const data = { test: 'value' };++ await fileOps.writeJson(testFilePath, data);++ const result = JSON.parse(await fs.readFile(testFilePath, 'utf-8'));+ expect(result.test).toBe('value');+ });++ it('should not leave temp files on success', async () => {+ await fileOps.writeJson(testFilePath, { test: true });++ const files = await fs.readdir(tempDir);+ const tempFiles = files.filter((f) => f.includes('.tmp'));+ expect(tempFiles).toHaveLength(0);++ // Also verify no lock files remain+ const lockFiles = files.filter((f) => f.endsWith('.lock'));+ expect(lockFiles).toHaveLength(0);+ });+ });++ describe('cleanup', () => {+ it('should clear cached writers', async () => {+ // Write to create a cached writer+ await fileOps.writeJson(testFilePath, { test: 1 });++ // Cleanup+ await fileOps.cleanup();++ // Should still work after cleanup (creates new writer)+ await fileOps.writeJson(testFilePath, { test: 2 });++ const result = JSON.parse(await fs.readFile(testFilePath, 'utf-8'));+ expect(result.test).toBe(2);+ });+ });+});diff --git a/packages/tm-core/src/modules/storage/adapters/file-storage/file-operations.ts b/packages/tm-core/src/modules/storage/adapters/file-storage/file-operations.tsindex 5fff7b40..0ff1220b 100644--- a/packages/tm-core/src/modules/storage/adapters/file-storage/file-operations.ts+++ b/packages/tm-core/src/modules/storage/adapters/file-storage/file-operations.ts@@ -1,16 +1,52 @@/**- * @fileoverview File operations with atomic writes and locking+ * @fileoverview File operations with atomic writes and cross-process locking+ *+ * Uses steno for atomic writes (same pattern as workflow-state-manager.ts)+ * and proper-lockfile for cross-process locking to prevent lost updates.*/import { constants } from 'node:fs';import fs from 'node:fs/promises';+import path from 'node:path';+import lockfile from 'proper-lockfile';+import { Writer } from 'steno';import type { FileStorageData } from './format-handler.js';/**- * Handles atomic file operations with locking mechanism+ * File locking configuration for cross-process safety+ */+const LOCK_OPTIONS = {+ stale: 10000, // Consider lock stale after 10 seconds+ retries: {+ retries: 5,+ factor: 2,+ minTimeout: 100,+ maxTimeout: 1000+ },+ realpath: false // Don't resolve symlinks (faster)+};++/**+ * Handles atomic file operations with cross-process locking mechanism.+ *+ * Writers are cached for reuse. Call {@link cleanup} when disposing of+ * long-lived instances to prevent memory leaks.*/export class FileOperations {- private fileLocks: Map<string, Promise<void>> = new Map();+ /** Map of file paths to steno Writers for reuse */+ private writers = new Map<string, Writer>();++ /**+ * Get or create a steno Writer for a file path+ */+ private getWriter(filePath: string): Writer {+ let writer = this.writers.get(filePath);+ if (!writer) {+ writer = new Writer(filePath);+ this.writers.set(filePath, writer);+ }+ return writer;+ }/*** Read and parse JSON file@@ -31,52 +67,132 @@ export class FileOperations {}/**- * Write JSON file with atomic operation and locking+ * Write JSON file with atomic operation and cross-process locking.+ * Uses steno for atomic writes and proper-lockfile for cross-process safety.+ * WARNING: This replaces the entire file. For concurrent modifications,+ * use modifyJson() instead to prevent lost updates.*/async writeJson(filePath: string,data: FileStorageData | any): Promise<void> {- // Use file locking to prevent concurrent writes- const lockKey = filePath;- const existingLock = this.fileLocks.get(lockKey);-- if (existingLock) {- await existingLock;- }-- const lockPromise = this.performAtomicWrite(filePath, data);- this.fileLocks.set(lockKey, lockPromise);+ // Ensure file exists for locking (proper-lockfile requires this)+ await this.ensureFileExists(filePath);+ // Acquire cross-process lock+ let release: (() => Promise<void>) | null = null;try {- await lockPromise;+ release = await lockfile.lock(filePath, LOCK_OPTIONS);++ // Use steno Writer for atomic writes (same pattern as workflow-state-manager)+ const content = JSON.stringify(data, null, 2);+ const writer = this.getWriter(filePath);+ await writer.write(content);} finally {- this.fileLocks.delete(lockKey);+ if (release) {+ try {+ await release();+ } catch (err: any) {+ // Log but don't throw - lock may have been released already+ // Other errors should be visible for debugging+ if (process.env.DEBUG || process.env.TASKMASTER_DEBUG === 'true') {+ console.warn(+ `[WARN] Lock release warning for ${filePath}: ${err.message}`+ );+ }+ }+ }}}/**- * Perform atomic write operation using temporary file+ * Read-modify-write JSON file with cross-process locking.+ * Uses steno for atomic writes and proper-lockfile for cross-process safety.+ * Re-reads file inside lock to prevent lost updates from stale snapshots.+ * @param filePath - Path to the JSON file+ * @param modifier - Function that receives current data and returns modified data*/- private async performAtomicWrite(filePath: string, data: any): Promise<void> {- const tempPath = `${filePath}.tmp`;+ async modifyJson<T = any>(+ filePath: string,+ modifier: (currentData: T) => T | Promise<T>+ ): Promise<void> {+ // Ensure file exists for locking (proper-lockfile requires this)+ await this.ensureFileExists(filePath);+ // Acquire cross-process lock+ let release: (() => Promise<void>) | null = null;try {- // Write to temp file first- const content = JSON.stringify(data, null, 2);- await fs.writeFile(tempPath, content, 'utf-8');+ release = await lockfile.lock(filePath, LOCK_OPTIONS);- // Atomic rename- await fs.rename(tempPath, filePath);- } catch (error: any) {- // Clean up temp file if it exists+ // Re-read file INSIDE lock to get current state+ // This prevents lost updates from stale snapshots+ let currentData: T;try {- await fs.unlink(tempPath);- } catch {- // Ignore cleanup errors+ const content = await fs.readFile(filePath, 'utf-8');+ currentData = JSON.parse(content);+ } catch (err: any) {+ // Distinguish between expected empty/new files and actual corruption+ if (err.code === 'ENOENT') {+ // File doesn't exist yet - start fresh+ currentData = {} as T;+ } else if (err instanceof SyntaxError) {+ // Check if it's just an empty file (our ensureFileExists writes '{}')+ const content = await fs.readFile(filePath, 'utf-8').catch(() => '');+ if (content.trim() === '' || content.trim() === '{}') {+ currentData = {} as T;+ } else {+ // Actual JSON corruption - this is a serious error+ throw new Error(+ `Corrupted JSON in ${filePath}: ${err.message}. File contains: ${content.substring(0, 100)}...`+ );+ }+ } else {+ // Other errors (permission, I/O) should be surfaced+ throw new Error(+ `Failed to read ${filePath} for modification: ${err.message}`+ );+ }+ }++ // Apply modification+ const newData = await modifier(currentData);++ // Write atomically using steno (same pattern as workflow-state-manager)+ const content = JSON.stringify(newData, null, 2);+ const writer = this.getWriter(filePath);+ await writer.write(content);+ } finally {+ if (release) {+ try {+ await release();+ } catch (err: any) {+ // Log but don't throw - lock may have been released already+ // Other errors should be visible for debugging+ if (process.env.DEBUG || process.env.TASKMASTER_DEBUG === 'true') {+ console.warn(+ `[WARN] Lock release warning for ${filePath}: ${err.message}`+ );+ }+ }}+ }+ }- throw new Error(`Failed to write file ${filePath}: ${error.message}`);+ /**+ * Ensure file exists for locking (proper-lockfile requires the file to exist).+ * Uses atomic creation with 'wx' flag to prevent TOCTOU race conditions.+ */+ private async ensureFileExists(filePath: string): Promise<void> {+ const dir = path.dirname(filePath);+ await fs.mkdir(dir, { recursive: true });+ try {+ // Use 'wx' flag for atomic create - fails if file exists (prevents race)+ await fs.writeFile(filePath, '{}', { flag: 'wx' });+ } catch (err: any) {+ // EEXIST is expected if another process created the file - that's fine+ if (err.code !== 'EEXIST') {+ throw err;+ }}}@@ -159,13 +275,14 @@ export class FileOperations {}/**- * Clean up all pending file operations+ * Clean up resources - releases cached steno Writers+ * Call this when the FileOperations instance is no longer needed+ * to prevent memory leaks in long-running processes.*/async cleanup(): Promise<void> {- const locks = Array.from(this.fileLocks.values());- if (locks.length > 0) {- await Promise.all(locks);- }- this.fileLocks.clear();+ // Clear cached Writers to allow garbage collection+ // Note: steno Writers don't have explicit close methods;+ // they handle file descriptor cleanup internally+ this.writers.clear();}}diff --git a/scripts/modules/utils.js b/scripts/modules/utils.jsindex 4532fc11..5ef1f814 100644--- a/scripts/modules/utils.js+++ b/scripts/modules/utils.js@@ -19,6 +19,278 @@ import * as gitUtils from './utils/git-utils.js';// Global silent mode flaglet silentMode = false;+// File locking configuration for cross-process safety+const LOCK_CONFIG = {+ maxRetries: 5,+ retryDelay: 100, // ms+ staleLockAge: 10000 // 10 seconds+};++/**+ * Async sleep helper+ */+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));++/**+ * Synchronous sleep helper with Atomics.wait fallback+ * Uses Atomics.wait when SharedArrayBuffer is available (proper non-busy wait),+ * otherwise falls back to a busy-wait loop (less efficient but always works).+ * @param {number} ms - Milliseconds to sleep+ */+function sleepSync(ms) {+ // Check if SharedArrayBuffer and Atomics.wait are available+ // They may not be available in some environments (e.g., browsers without proper headers)+ if (+ typeof SharedArrayBuffer !== 'undefined' &&+ typeof Atomics !== 'undefined' &&+ typeof Atomics.wait === 'function'+ ) {+ try {+ const sharedBuffer = new SharedArrayBuffer(4);+ const int32 = new Int32Array(sharedBuffer);+ Atomics.wait(int32, 0, 0, ms);+ return;+ } catch {+ // Fall through to busy-wait fallback+ }+ }++ // Fallback: busy-wait loop (less efficient but universally compatible)+ // Note: This may cause high CPU usage for longer waits. Consider if this+ // becomes an issue with large exponential backoff delays.+ const end = Date.now() + ms;+ while (Date.now() < end) {+ // Busy wait - intentionally empty+ }+}++/**+ * Acquires an exclusive lock on a file and executes a callback+ * Uses same lock file format as withFileLockSync for cross-process compatibility+ * @param {string} filepath - Path to the file to lock+ * @param {Function} callback - Async function to execute while holding the lock+ * @param {Object} [options] - Options for lock behavior+ * @param {boolean} [options.createIfMissing=false] - If true, creates the file with '{}' if it doesn't exist.+ * Set to true for write operations. Leave false for read-only operations that should handle+ * file-not-found scenarios in the callback.+ * @returns {Promise<*>} Result of the callback+ */+async function withFileLock(filepath, callback, options = {}) {+ const { createIfMissing = false } = options;+ const fsPromises = fs.promises;++ // Ensure parent directory exists+ const dir = path.dirname(filepath);+ await fsPromises.mkdir(dir, { recursive: true });++ // Only create the file if explicitly requested (for write operations)+ if (createIfMissing) {+ try {+ // Use 'wx' flag for atomic create - fails if file exists (prevents race)+ await fsPromises.writeFile(filepath, '{}', { flag: 'wx' });+ } catch (err) {+ // EEXIST is expected if another process created the file - that's fine+ if (err.code !== 'EEXIST') {+ throw err;+ }+ }+ }++ const lockPath = `${filepath}.lock`;+ const { maxRetries, retryDelay, staleLockAge } = LOCK_CONFIG;++ // Try to acquire lock with retries+ let acquired = false;+ for (let attempt = 0; attempt < maxRetries; attempt++) {+ try {+ // Try to create lock file exclusively first+ const lockContent = JSON.stringify({+ pid: process.pid,+ timestamp: Date.now()+ });+ await fsPromises.writeFile(lockPath, lockContent, { flag: 'wx' });+ acquired = true;+ break;+ } catch (err) {+ if (err.code === 'EEXIST') {+ // Lock file exists - check if it's stale+ try {+ const lockStat = await fsPromises.stat(lockPath);+ const age = Date.now() - lockStat.mtimeMs;+ if (age > staleLockAge) {+ // Stale lock - use atomic rename to safely take ownership+ // This prevents race where we delete another process's fresh lock+ const stalePath = `${lockPath}.stale.${process.pid}.${Date.now()}`;+ try {+ await fsPromises.rename(lockPath, stalePath);+ // We successfully took ownership of the stale lock+ // Clean it up and retry immediately+ try {+ await fsPromises.unlink(stalePath);+ } catch {+ // Ignore cleanup errors+ }+ continue; // Retry lock acquisition+ } catch {+ // Rename failed - another process handled it or lock was refreshed+ // Just continue to retry+ }+ }+ } catch (statErr) {+ // Lock was removed between writeFile and stat - retry immediately+ if (statErr.code === 'ENOENT') {+ continue;+ }+ throw statErr;+ }++ // Lock exists and isn't stale (or we couldn't handle it), wait and retry+ if (attempt < maxRetries - 1) {+ const waitMs = retryDelay * Math.pow(2, attempt);+ await sleep(waitMs);+ }+ } else {+ throw err;+ }+ }+ }++ if (!acquired) {+ throw new Error(+ `Failed to acquire lock on ${filepath} after ${maxRetries} attempts`+ );+ }++ try {+ return await callback();+ } finally {+ // Release lock+ try {+ await fsPromises.unlink(lockPath);+ } catch (releaseError) {+ // Always log lock release failures - they indicate potential issues+ log(+ 'warn',+ `Failed to release lock for ${filepath}: ${releaseError.message}`+ );+ }+ }+}++/**+ * Synchronous version of file locking for compatibility with existing sync code+ * Uses a lock file approach with retries and stale lock detection+ * @param {string} filepath - Path to the file to lock+ * @param {Function} callback - Sync function to execute while holding the lock+ * @param {Object} [options] - Options for lock behavior+ * @param {boolean} [options.createIfMissing=false] - If true, creates the file with '{}' if it doesn't exist.+ * Set to true for write operations. Leave false for read-only operations that should handle+ * file-not-found scenarios in the callback.+ * @returns {*} Result of the callback+ */+function withFileLockSync(filepath, callback, options = {}) {+ const { createIfMissing = false } = options;++ // Ensure parent directory exists+ const dir = path.dirname(filepath);+ if (!fs.existsSync(dir)) {+ fs.mkdirSync(dir, { recursive: true });+ }++ // Only create the file if explicitly requested (for write operations)+ if (createIfMissing) {+ try {+ // Use 'wx' flag for atomic create - fails if file exists (prevents race)+ fs.writeFileSync(filepath, '{}', { flag: 'wx' });+ } catch (err) {+ // EEXIST is expected if another process created the file - that's fine+ if (err.code !== 'EEXIST') {+ throw err;+ }+ }+ }++ const lockPath = `${filepath}.lock`;+ const { maxRetries, retryDelay, staleLockAge } = LOCK_CONFIG;++ // Try to acquire lock with retries+ let acquired = false;+ for (let attempt = 0; attempt < maxRetries; attempt++) {+ try {+ // Try to create lock file exclusively first+ const lockContent = JSON.stringify({+ pid: process.pid,+ timestamp: Date.now()+ });+ fs.writeFileSync(lockPath, lockContent, { flag: 'wx' });+ acquired = true;+ break;+ } catch (err) {+ if (err.code === 'EEXIST') {+ // Lock file exists - check if it's stale+ try {+ const lockStat = fs.statSync(lockPath);+ const age = Date.now() - lockStat.mtimeMs;+ if (age > staleLockAge) {+ // Stale lock - use atomic rename to safely take ownership+ // This prevents race where we delete another process's fresh lock+ const stalePath = `${lockPath}.stale.${process.pid}.${Date.now()}`;+ try {+ fs.renameSync(lockPath, stalePath);+ // We successfully took ownership of the stale lock+ // Clean it up and retry immediately+ try {+ fs.unlinkSync(stalePath);+ } catch {+ // Ignore cleanup errors+ }+ continue; // Retry lock acquisition+ } catch {+ // Rename failed - another process handled it or lock was refreshed+ // Just continue to retry+ }+ }+ } catch (statErr) {+ // Lock was removed between writeFile and stat - retry immediately+ if (statErr.code === 'ENOENT') {+ continue;+ }+ throw statErr;+ }++ // Lock exists and isn't stale (or we couldn't handle it), wait and retry+ if (attempt < maxRetries - 1) {+ const waitMs = retryDelay * Math.pow(2, attempt);+ sleepSync(waitMs);+ }+ } else {+ throw err;+ }+ }+ }++ if (!acquired) {+ throw new Error(+ `Failed to acquire lock on ${filepath} after ${maxRetries} attempts`+ );+ }++ try {+ return callback();+ } finally {+ // Release lock+ try {+ fs.unlinkSync(lockPath);+ } catch (releaseError) {+ // Always log lock release failures - they indicate potential issues+ log(+ 'warn',+ `Failed to release lock for ${filepath}: ${releaseError.message}`+ );+ }+ }+}+// --- Environment Variable Resolution Utility ---/*** Resolves an environment variable's value.@@ -703,6 +975,7 @@ function markMigrationForNotice(tasksJsonPath) {/*** Writes and saves a JSON file. Handles tagged task lists properly.+ * Uses cross-process file locking and atomic writes to prevent race conditions.* @param {string} filepath - Path to the JSON file* @param {Object} data - Data to write (can be resolved tag data or raw tagged data)* @param {string} projectRoot - Optional project root for tag context@@ -712,107 +985,172 @@ function writeJSON(filepath, data, projectRoot = null, tag = null) {const isDebug = process.env.TASKMASTER_DEBUG === 'true';try {- let finalData = data;+ // Use file locking to prevent concurrent write race conditions+ // This ensures the entire read-modify-write cycle is atomic+ // createIfMissing: true because writeJSON is a write operation+ withFileLockSync(+ filepath,+ () => {+ let finalData = data;++ // If data represents resolved tag data but lost _rawTaggedData (edge-case observed in MCP path)+ if (+ data &&+ !data._rawTaggedData &&+ projectRoot &&+ Array.isArray(data.tasks) &&+ !hasTaggedStructure(data)+ ) {+ const resolvedTag = tag || getCurrentTag(projectRoot);- // If data represents resolved tag data but lost _rawTaggedData (edge-case observed in MCP path)- if (- !data._rawTaggedData &&- projectRoot &&- Array.isArray(data.tasks) &&- !hasTaggedStructure(data)- ) {- const resolvedTag = tag || getCurrentTag(projectRoot);+ if (isDebug) {+ console.log(+ `writeJSON: Detected resolved tag data missing _rawTaggedData. Re-reading raw data to prevent data loss for tag '${resolvedTag}'.`+ );+ }- if (isDebug) {- console.log(- `writeJSON: Detected resolved tag data missing _rawTaggedData. Re-reading raw data to prevent data loss for tag '${resolvedTag}'.`- );- }+ // Re-read the full file to get the complete tagged structure+ // This is now safe because we hold the lock+ let rawFullData = {};+ try {+ rawFullData = JSON.parse(fs.readFileSync(filepath, 'utf8'));+ } catch (readError) {+ // File might be empty or invalid, start fresh+ if (isDebug) {+ console.log(+ `writeJSON: Could not read existing file, starting fresh: ${readError.message}`+ );+ }+ }- // Re-read the full file to get the complete tagged structure- const rawFullData = JSON.parse(fs.readFileSync(filepath, 'utf8'));-- // Merge the updated data into the full structure- finalData = {- ...rawFullData,- [resolvedTag]: {- // Preserve existing tag metadata if it exists, otherwise use what's passed- ...(rawFullData[resolvedTag]?.metadata || {}),- ...(data.metadata ? { metadata: data.metadata } : {}),- tasks: data.tasks // The updated tasks array is the source of truth here+ // Merge the updated data into the full structure+ finalData = {+ ...rawFullData,+ [resolvedTag]: {+ // Preserve existing tag metadata, merged with any new metadata+ metadata: {+ ...(rawFullData[resolvedTag]?.metadata || {}),+ ...(data.metadata || {})+ },+ tasks: data.tasks // The updated tasks array is the source of truth here+ }+ };}- };- }- // If we have _rawTaggedData, this means we're working with resolved tag data- // and need to merge it back into the full tagged structure- else if (data && data._rawTaggedData && projectRoot) {- const resolvedTag = tag || getCurrentTag(projectRoot);-- // Get the original tagged data- const originalTaggedData = data._rawTaggedData;+ // If we have _rawTaggedData, this means we're working with resolved tag data+ // and need to merge it back into the full tagged structure+ else if (data && data._rawTaggedData && projectRoot) {+ const resolvedTag = tag || getCurrentTag(projectRoot);++ // IMPORTANT: Re-read the file to get the CURRENT state instead of using+ // potentially stale _rawTaggedData. This prevents lost updates from other processes.+ let currentTaggedData;+ try {+ currentTaggedData = JSON.parse(fs.readFileSync(filepath, 'utf8'));+ } catch (readError) {+ // Fall back to _rawTaggedData if file can't be read+ currentTaggedData = data._rawTaggedData;+ if (isDebug) {+ console.log(+ `writeJSON: Using _rawTaggedData as fallback: ${readError.message}`+ );+ }+ }- // Create a clean copy of the current resolved data (without internal properties)- const { _rawTaggedData, tag: _, ...cleanResolvedData } = data;+ // Create a clean copy of the current resolved data (without internal properties)+ const { _rawTaggedData, tag: _, ...cleanResolvedData } = data;- // Update the specific tag with the resolved data- finalData = {- ...originalTaggedData,- [resolvedTag]: cleanResolvedData- };+ // Update the specific tag with the resolved data, preserving other tags+ finalData = {+ ...currentTaggedData,+ [resolvedTag]: cleanResolvedData+ };- if (isDebug) {- console.log(- `writeJSON: Merging resolved data back into tag '${resolvedTag}'`- );- }- }+ if (isDebug) {+ console.log(+ `writeJSON: Merging resolved data back into tag '${resolvedTag}'`+ );+ }+ }- // Clean up any internal properties that shouldn't be persisted- let cleanData = finalData;- if (cleanData && typeof cleanData === 'object') {- // Remove any _rawTaggedData or tag properties from root level- const { _rawTaggedData, tag: tagProp, ...rootCleanData } = cleanData;- cleanData = rootCleanData;-- // Additional cleanup for tag objects- if (typeof cleanData === 'object' && !Array.isArray(cleanData)) {- const finalCleanData = {};- for (const [key, value] of Object.entries(cleanData)) {- if (- value &&- typeof value === 'object' &&- Array.isArray(value.tasks)- ) {- // This is a tag object - clean up any rogue root-level properties- const { created, description, ...cleanTagData } = value;-- // Only keep the description if there's no metadata.description- if (- description &&- (!cleanTagData.metadata || !cleanTagData.metadata.description)- ) {- cleanTagData.description = description;+ // Clean up any internal properties that shouldn't be persisted+ let cleanData = finalData;+ if (cleanData && typeof cleanData === 'object') {+ // Remove any _rawTaggedData or tag properties from root level+ const { _rawTaggedData, tag: tagProp, ...rootCleanData } = cleanData;+ cleanData = rootCleanData;++ // Additional cleanup for tag objects+ if (typeof cleanData === 'object' && !Array.isArray(cleanData)) {+ const finalCleanData = {};+ for (const [key, value] of Object.entries(cleanData)) {+ if (+ value &&+ typeof value === 'object' &&+ Array.isArray(value.tasks)+ ) {+ // This is a tag object - clean up any rogue root-level properties+ // Move created/description to metadata if they're at root level+ const { created, description, ...cleanTagData } = value;++ // Ensure metadata object exists+ if (!cleanTagData.metadata) {+ cleanTagData.metadata = {};+ }++ // Preserve created timestamp in metadata if it exists at root level+ if (created && !cleanTagData.metadata.created) {+ cleanTagData.metadata.created = created;+ }++ // Preserve description in metadata if it exists at root level+ if (description && !cleanTagData.metadata.description) {+ cleanTagData.metadata.description = description;+ }++ finalCleanData[key] = cleanTagData;+ } else {+ finalCleanData[key] = value;+ }}-- finalCleanData[key] = cleanTagData;- } else {- finalCleanData[key] = value;+ cleanData = finalCleanData;}}- cleanData = finalCleanData;- }- }- fs.writeFileSync(filepath, JSON.stringify(cleanData, null, 2), 'utf8');+ // Use atomic write: write to temp file then rename+ // This prevents partial writes from corrupting the file+ const tempPath = `${filepath}.tmp.${process.pid}`;+ try {+ fs.writeFileSync(+ tempPath,+ JSON.stringify(cleanData, null, 2),+ 'utf8'+ );+ fs.renameSync(tempPath, filepath);+ } catch (writeError) {+ // Clean up temp file on failure+ try {+ if (fs.existsSync(tempPath)) {+ fs.unlinkSync(tempPath);+ }+ } catch {+ // Ignore cleanup errors+ }+ throw writeError;+ }- if (isDebug) {- console.log(`writeJSON: Successfully wrote to ${filepath}`);- }+ if (isDebug) {+ console.log(`writeJSON: Successfully wrote to ${filepath}`);+ }+ },+ { createIfMissing: true }+ );} catch (error) {log('error', `Error writing JSON file ${filepath}:`, error.message);if (isDebug) {log('error', 'Full error details:', error);}+ // Re-throw so callers know the write failed+ throw error;}}@@ -1616,5 +1954,7 @@ export {flattenTasksWithSubtasks,ensureTagMetadata,stripAnsiCodes,- normalizeTaskIds+ normalizeTaskIds,+ withFileLock,+ withFileLockSync};diff --git a/tests/unit/file-locking.test.js b/tests/unit/file-locking.test.jsnew file mode 100644index 00000000..3a8ca62c--- /dev/null+++ b/tests/unit/file-locking.test.js@@ -0,0 +1,602 @@+/**+ * Tests for file locking and atomic write functionality+ * Verifies that concurrent access to tasks.json is properly serialized+ */++import {+ jest,+ describe,+ it,+ expect,+ beforeEach,+ afterEach+} from '@jest/globals';+import fs from 'fs';+import path from 'path';+import os from 'os';+import { fileURLToPath } from 'url';++const __filename = fileURLToPath(import.meta.url);+const __dirname = path.dirname(__filename);++// Import the utils module+const utilsPath = path.join(__dirname, '../../scripts/modules/utils.js');++describe('File Locking and Atomic Writes', () => {+ let tempDir;+ let testFilePath;+ let utils;++ beforeEach(async () => {+ // Create a temp directory for each test+ tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'taskmaster-test-'));+ testFilePath = path.join(tempDir, 'tasks.json');++ // Initialize with empty tasks structure+ fs.writeFileSync(+ testFilePath,+ JSON.stringify(+ {+ master: {+ tasks: [],+ metadata: { created: new Date().toISOString() }+ }+ },+ null,+ 2+ )+ );++ // Import utils fresh for each test+ utils = await import(utilsPath + `?cachebust=${Date.now()}`);+ });++ afterEach(() => {+ // Clean up temp directory and any lock files+ if (tempDir && fs.existsSync(tempDir)) {+ fs.rmSync(tempDir, { recursive: true, force: true });+ }+ });++ describe('withFileLockSync', () => {+ it('should execute callback while holding lock', () => {+ const result = utils.withFileLockSync(testFilePath, () => {+ return 'callback executed';+ });++ expect(result).toBe('callback executed');+ });++ it('should release lock after callback completes', () => {+ utils.withFileLockSync(testFilePath, () => {+ // First lock+ });++ // Should be able to acquire lock again+ const result = utils.withFileLockSync(testFilePath, () => {+ return 'second lock acquired';+ });++ expect(result).toBe('second lock acquired');+ });++ it('should release lock even if callback throws', () => {+ expect(() => {+ utils.withFileLockSync(testFilePath, () => {+ throw new Error('Test error');+ });+ }).toThrow('Test error');++ // Should still be able to acquire lock+ const result = utils.withFileLockSync(testFilePath, () => 'recovered');+ expect(result).toBe('recovered');+ });++ it('should create file if createIfMissing is true', () => {+ const newFilePath = path.join(tempDir, 'new-file.json');++ utils.withFileLockSync(+ newFilePath,+ () => {+ // Lock acquired on new file+ },+ { createIfMissing: true }+ );++ expect(fs.existsSync(newFilePath)).toBe(true);+ });++ it('should not create file if createIfMissing is false (default)', () => {+ const newFilePath = path.join(tempDir, 'should-not-exist.json');++ utils.withFileLockSync(newFilePath, () => {+ // Lock acquired, but file should not be created+ });++ expect(fs.existsSync(newFilePath)).toBe(false);+ });++ it('should clean up lock file after completion', () => {+ utils.withFileLockSync(testFilePath, () => {+ // Do something+ });++ // Lock file should be cleaned up+ expect(fs.existsSync(`${testFilePath}.lock`)).toBe(false);+ });++ it('should clean up lock file even on error', () => {+ try {+ utils.withFileLockSync(testFilePath, () => {+ throw new Error('Test error');+ });+ } catch {+ // Expected+ }++ // Lock file should be cleaned up+ expect(fs.existsSync(`${testFilePath}.lock`)).toBe(false);+ });+ });++ describe('withFileLock (async)', () => {+ it('should execute async callback while holding lock', async () => {+ const result = await utils.withFileLock(testFilePath, async () => {+ await new Promise((resolve) => setTimeout(resolve, 10));+ return 'async callback executed';+ });++ expect(result).toBe('async callback executed');+ });++ it('should release lock after async callback completes', async () => {+ await utils.withFileLock(testFilePath, async () => {+ // First lock+ });++ // Should be able to acquire lock again+ const result = await utils.withFileLock(testFilePath, async () => {+ return 'second lock acquired';+ });++ expect(result).toBe('second lock acquired');+ });++ it('should release lock even if async callback rejects', async () => {+ await expect(+ utils.withFileLock(testFilePath, async () => {+ throw new Error('Async error');+ })+ ).rejects.toThrow('Async error');++ // Should still be able to acquire lock+ const result = await utils.withFileLock(+ testFilePath,+ async () => 'recovered'+ );+ expect(result).toBe('recovered');+ });++ it('should create file if createIfMissing is true', async () => {+ const newFilePath = path.join(tempDir, 'new-async-file.json');++ await utils.withFileLock(+ newFilePath,+ async () => {+ // Lock acquired on new file+ },+ { createIfMissing: true }+ );++ expect(fs.existsSync(newFilePath)).toBe(true);+ });++ it('should not create file if createIfMissing is false (default)', async () => {+ const newFilePath = path.join(tempDir, 'should-not-exist-async.json');++ await utils.withFileLock(newFilePath, async () => {+ // Lock acquired, but file should not be created+ });++ expect(fs.existsSync(newFilePath)).toBe(false);+ });++ it('should clean up lock file after completion', async () => {+ await utils.withFileLock(testFilePath, async () => {+ // Do something+ });++ // Lock file should be cleaned up+ expect(fs.existsSync(`${testFilePath}.lock`)).toBe(false);+ });++ it('should clean up lock file even on error', async () => {+ try {+ await utils.withFileLock(testFilePath, async () => {+ throw new Error('Test error');+ });+ } catch {+ // Expected+ }++ // Lock file should be cleaned up+ expect(fs.existsSync(`${testFilePath}.lock`)).toBe(false);+ });++ it('should serialize truly concurrent writes', async () => {+ const numConcurrentWrites = 5;+ const writes = [];++ for (let i = 0; i < numConcurrentWrites; i++) {+ writes.push(+ utils.withFileLock(testFilePath, async () => {+ const data = JSON.parse(fs.readFileSync(testFilePath, 'utf8'));+ data.master.tasks.push({+ id: String(data.master.tasks.length + 1)+ });+ fs.writeFileSync(testFilePath, JSON.stringify(data, null, 2));+ })+ );+ }++ await Promise.all(writes);++ const finalData = JSON.parse(fs.readFileSync(testFilePath, 'utf8'));+ expect(finalData.master.tasks).toHaveLength(numConcurrentWrites);+ });+ });++ describe('writeJSON atomic writes', () => {+ it('should not leave temp files on success', () => {+ // Create a tagged structure that writeJSON expects+ const taggedData = {+ master: {+ tasks: [{ id: '1', title: 'Test task', status: 'pending' }],+ metadata: { created: new Date().toISOString() }+ }+ };++ utils.writeJSON(testFilePath, taggedData, null, null);++ const files = fs.readdirSync(tempDir);+ const tempFiles = files.filter((f) => f.includes('.tmp'));+ expect(tempFiles).toHaveLength(0);+ });++ it('should preserve data from other tags when writing to one tag', () => {+ // Set up initial data with multiple tags+ const initialData = {+ master: {+ tasks: [{ id: '1', title: 'Master task', status: 'pending' }],+ metadata: { created: new Date().toISOString() }+ },+ feature: {+ tasks: [{ id: '1', title: 'Feature task', status: 'pending' }],+ metadata: { created: new Date().toISOString() }+ }+ };+ fs.writeFileSync(testFilePath, JSON.stringify(initialData, null, 2));++ // Write directly with tagged structure (simulating what commands do internally)+ const updatedData = {+ ...initialData,+ master: {+ ...initialData.master,+ tasks: [+ { id: '1', title: 'Updated master task', status: 'pending' },+ { id: '2', title: 'New task', status: 'pending' }+ ]+ }+ };++ utils.writeJSON(testFilePath, updatedData, null, null);++ const written = JSON.parse(fs.readFileSync(testFilePath, 'utf8'));++ // Master should be updated+ expect(written.master.tasks).toHaveLength(2);+ expect(written.master.tasks[0].title).toBe('Updated master task');++ // Feature should be preserved+ expect(written.feature.tasks).toHaveLength(1);+ expect(written.feature.tasks[0].title).toBe('Feature task');+ });++ it('should not leave lock files on success', () => {+ const taggedData = {+ master: {+ tasks: [{ id: '1', title: 'Test task', status: 'pending' }],+ metadata: {}+ }+ };++ utils.writeJSON(testFilePath, taggedData, null, null);++ expect(fs.existsSync(`${testFilePath}.lock`)).toBe(false);+ });+ });++ describe('Concurrent write simulation', () => {+ it('should handle rapid sequential writes without data loss', () => {+ // Perform many rapid writes+ const numWrites = 10;++ for (let i = 0; i < numWrites; i++) {+ // Read current data+ let currentData;+ try {+ currentData = JSON.parse(fs.readFileSync(testFilePath, 'utf8'));+ } catch {+ currentData = { master: { tasks: [], metadata: {} } };+ }++ // Add a new task+ currentData.master.tasks.push({+ id: String(i + 1),+ title: `Task ${i + 1}`,+ status: 'pending'+ });++ // Write with locking+ utils.writeJSON(testFilePath, currentData, null, null);+ }++ const finalData = JSON.parse(fs.readFileSync(testFilePath, 'utf8'));+ expect(finalData.master.tasks).toHaveLength(numWrites);+ });+ });++ describe('True concurrent process writes', () => {+ it('should handle multiple processes writing simultaneously without data loss', async () => {+ const { spawn } = await import('child_process');++ const numProcesses = 5;+ const tasksPerProcess = 3;++ // Create a worker script with inline locking implementation+ // This mirrors the withFileLockSync implementation but without external dependencies+ const workerScript = `+ import fs from 'fs';++ const filepath = process.argv[2];+ const processId = process.argv[3];+ const numTasks = parseInt(process.argv[4], 10);++ const LOCK_CONFIG = {+ maxRetries: 10,+ retryDelay: 50,+ staleLockAge: 10000+ };++ function sleepSync(ms) {+ const end = Date.now() + ms;+ while (Date.now() < end) {+ // Busy wait+ }+ }++ function withFileLockSync(filepath, callback) {+ const lockPath = filepath + '.lock';+ const { maxRetries, retryDelay, staleLockAge } = LOCK_CONFIG;++ let acquired = false;+ for (let attempt = 0; attempt < maxRetries; attempt++) {+ try {+ const lockContent = JSON.stringify({+ pid: process.pid,+ timestamp: Date.now()+ });+ fs.writeFileSync(lockPath, lockContent, { flag: 'wx' });+ acquired = true;+ break;+ } catch (err) {+ if (err.code === 'EEXIST') {+ try {+ const lockStat = fs.statSync(lockPath);+ const age = Date.now() - lockStat.mtimeMs;+ if (age > staleLockAge) {+ const stalePath = lockPath + '.stale.' + process.pid + '.' + Date.now();+ try {+ fs.renameSync(lockPath, stalePath);+ try { fs.unlinkSync(stalePath); } catch {}+ continue;+ } catch {}+ }+ } catch (statErr) {+ if (statErr.code === 'ENOENT') continue;+ throw statErr;+ }+ if (attempt < maxRetries - 1) {+ const waitMs = retryDelay * Math.pow(2, attempt);+ sleepSync(waitMs);+ }+ } else {+ throw err;+ }+ }+ }++ if (!acquired) {+ throw new Error('Failed to acquire lock on ' + filepath + ' after ' + maxRetries + ' attempts');+ }++ try {+ return callback();+ } finally {+ try {+ fs.unlinkSync(lockPath);+ } catch {}+ }+ }++ async function main() {+ for (let i = 0; i < numTasks; i++) {+ withFileLockSync(filepath, () => {+ let currentData;+ try {+ currentData = JSON.parse(fs.readFileSync(filepath, 'utf8'));+ } catch {+ currentData = { master: { tasks: [], metadata: {} } };+ }++ currentData.master.tasks.push({+ id: 'P' + processId + '-' + (i + 1),+ title: 'Task from process ' + processId + ' #' + (i + 1),+ status: 'pending'+ });++ fs.writeFileSync(filepath, JSON.stringify(currentData, null, 2), 'utf8');+ });++ // Small delay to increase chance of interleaving+ await new Promise(r => setTimeout(r, 10));+ }+ }++ main().catch(err => {+ console.error(err);+ process.exit(1);+ });+ `;++ // Write worker script to temp file+ const workerPath = path.join(tempDir, 'worker.mjs');+ fs.writeFileSync(workerPath, workerScript);++ // Spawn multiple processes that write concurrently+ const processes = [];+ for (let i = 0; i < numProcesses; i++) {+ const proc = spawn(+ 'node',+ [workerPath, testFilePath, String(i), String(tasksPerProcess)],+ {+ stdio: ['ignore', 'pipe', 'pipe']+ }+ );+ processes.push(+ new Promise((resolve, reject) => {+ let stderr = '';+ proc.stderr.on('data', (data) => {+ stderr += data.toString();+ });+ proc.on('close', (code) => {+ if (code === 0) {+ resolve();+ } else {+ reject(+ new Error(`Process ${i} exited with code ${code}: ${stderr}`)+ );+ }+ });+ proc.on('error', reject);+ })+ );+ }++ // Wait for all processes to complete+ await Promise.all(processes);++ // Verify all tasks were written+ const finalData = JSON.parse(fs.readFileSync(testFilePath, 'utf8'));+ const expectedTasks = numProcesses * tasksPerProcess;++ expect(finalData.master.tasks.length).toBe(expectedTasks);++ // Verify we have tasks from all processes+ for (let i = 0; i < numProcesses; i++) {+ const tasksFromProcess = finalData.master.tasks.filter((t) =>+ t.id.startsWith(`P${i}-`)+ );+ expect(tasksFromProcess.length).toBe(tasksPerProcess);+ }+ }, 30000); // 30 second timeout for concurrent test+ });+});++describe('readJSON', () => {+ let tempDir;+ let testFilePath;+ let utils;++ beforeEach(async () => {+ tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'taskmaster-test-'));+ testFilePath = path.join(tempDir, 'tasks.json');++ // Create .taskmaster directory for state.json+ fs.mkdirSync(path.join(tempDir, '.taskmaster'), { recursive: true });+ fs.writeFileSync(+ path.join(tempDir, '.taskmaster', 'state.json'),+ JSON.stringify({+ currentTag: 'master'+ })+ );++ utils = await import(utilsPath + `?cachebust=${Date.now()}`);+ });++ afterEach(() => {+ if (tempDir && fs.existsSync(tempDir)) {+ fs.rmSync(tempDir, { recursive: true, force: true });+ }+ });++ it('should read tagged task data correctly', () => {+ const data = {+ master: {+ tasks: [{ id: '1', title: 'Test', status: 'pending' }],+ metadata: { created: new Date().toISOString() }+ }+ };+ fs.writeFileSync(testFilePath, JSON.stringify(data, null, 2));++ const result = utils.readJSON(testFilePath, tempDir, 'master');++ expect(result.tasks).toHaveLength(1);+ expect(result.tasks[0].title).toBe('Test');+ });++ it('should return null for non-existent file', () => {+ const result = utils.readJSON(path.join(tempDir, 'nonexistent.json'));+ expect(result).toBeNull();+ });+});++describe('Lock file stale detection', () => {+ let tempDir;+ let testFilePath;+ let utils;++ beforeEach(async () => {+ tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'taskmaster-test-'));+ testFilePath = path.join(tempDir, 'tasks.json');+ fs.writeFileSync(testFilePath, '{}');+ utils = await import(utilsPath + `?cachebust=${Date.now()}`);+ });++ afterEach(() => {+ if (tempDir && fs.existsSync(tempDir)) {+ fs.rmSync(tempDir, { recursive: true, force: true });+ }+ });++ it('should remove stale lock files', () => {+ const lockPath = `${testFilePath}.lock`;++ // Create a lock file with old timestamp+ fs.writeFileSync(+ lockPath,+ JSON.stringify({+ pid: 99999, // Non-existent PID+ timestamp: Date.now() - 20000 // 20 seconds ago+ })+ );++ // Touch the file to make it old+ const pastTime = new Date(Date.now() - 20000);+ fs.utimesSync(lockPath, pastTime, pastTime);++ // Should be able to acquire lock despite existing lock file+ const result = utils.withFileLockSync(testFilePath, () => 'acquired');+ expect(result).toBe('acquired');+ });+});