feat(stability): add 4 critical stability improvements for 1.0.0

1. Replace Linear sync boolean lock with AsyncMutex
   - Prevents race conditions during concurrent sync attempts
   - Includes stale lock detection (5 min timeout)
   - Thread-safe acquire/tryAcquire/release pattern

2. Add timeout to SMS action execution
   - 60 second timeout prevents hanging requests
   - Uses Promise.race pattern for clean timeout handling

3. Persist rate limiting to disk
   - Rate limits now survive server restarts
   - Uses in-memory cache with periodic persistence (30s)
   - Auto-cleanup of expired entries on load

4. Atomic write pattern for JSON files
   - writeFileSecure now writes to temp file first, then renames
   - Prevents file corruption on crash/interrupt
   - Cleanup of temp files on failure

Author: jonathanpeterwu

src/core/utils/async-mutex.ts

@@ -0,0 +1,132 @@
+/**
+ * Simple async mutex implementation for thread-safe operations
+ * Prevents race conditions when multiple async operations compete for the same resource
+ */
+
+export class AsyncMutex {
+  private locked = false;
+  private waiting: Array<() => void> = [];
+  private lockHolder: string | null = null;
+  private lockAcquiredAt: number = 0;
+  private readonly lockTimeout: number;
+
+  constructor(lockTimeoutMs: number = 300000) {
+    // Default 5 minute timeout
+    this.lockTimeout = lockTimeoutMs;
+  }
+
+  /**
+   * Acquire the lock. Waits if already locked.
+   * Returns a release function that MUST be called when done.
+   */
+  async acquire(holder?: string): Promise<() => void> {
+    // Check for stale lock (lock timeout)
+    if (this.locked && this.lockAcquiredAt > 0) {
+      const elapsed = Date.now() - this.lockAcquiredAt;
+      if (elapsed > this.lockTimeout) {
+        console.warn(
+          `[AsyncMutex] Stale lock detected (held by ${this.lockHolder} for ${elapsed}ms), forcing release`
+        );
+        this.forceRelease();
+      }
+    }
+
+    if (!this.locked) {
+      this.locked = true;
+      this.lockHolder = holder || 'unknown';
+      this.lockAcquiredAt = Date.now();
+      return () => this.release();
+    }
+
+    // Wait for lock to be released
+    return new Promise((resolve) => {
+      this.waiting.push(() => {
+        this.locked = true;
+        this.lockHolder = holder || 'unknown';
+        this.lockAcquiredAt = Date.now();
+        resolve(() => this.release());
+      });
+    });
+  }
+
+  /**
+   * Try to acquire the lock without waiting
+   * Returns release function if acquired, null if already locked
+   */
+  tryAcquire(holder?: string): (() => void) | null {
+    // Check for stale lock
+    if (this.locked && this.lockAcquiredAt > 0) {
+      const elapsed = Date.now() - this.lockAcquiredAt;
+      if (elapsed > this.lockTimeout) {
+        console.warn(
+          `[AsyncMutex] Stale lock detected (held by ${this.lockHolder} for ${elapsed}ms), forcing release`
+        );
+        this.forceRelease();
+      }
+    }
+
+    if (!this.locked) {
+      this.locked = true;
+      this.lockHolder = holder || 'unknown';
+      this.lockAcquiredAt = Date.now();
+      return () => this.release();
+    }
+    return null;
+  }
+
+  private release(): void {
+    const next = this.waiting.shift();
+    if (next) {
+      next();
+    } else {
+      this.locked = false;
+      this.lockHolder = null;
+      this.lockAcquiredAt = 0;
+    }
+  }
+
+  private forceRelease(): void {
+    this.locked = false;
+    this.lockHolder = null;
+    this.lockAcquiredAt = 0;
+  }
+
+  /**
+   * Execute a function while holding the lock
+   */
+  async withLock<T>(fn: () => Promise<T>, holder?: string): Promise<T> {
+    const release = await this.acquire(holder);
+    try {
+      return await fn();
+    } finally {
+      release();
+    }
+  }
+
+  /**
+   * Check if currently locked
+   */
+  isLocked(): boolean {
+    return this.locked;
+  }
+
+  /**
+   * Get current lock status
+   */
+  getStatus(): {
+    locked: boolean;
+    holder: string | null;
+    acquiredAt: number;
+    waitingCount: number;
+  } {
+    return {
+      locked: this.locked,
+      holder: this.lockHolder,
+      acquiredAt: this.lockAcquiredAt,
+      waitingCount: this.waiting.length,
+    };
+  }
+}
+
+// Singleton instance for sync operations
+export const syncMutex = new AsyncMutex(300000); // 5 minute timeout

src/hooks/secure-fs.ts

@@ -3,12 +3,21 @@
  * Ensures config files have restricted permissions (0600)
  */
 
-import { writeFileSync, mkdirSync, chmodSync, existsSync } from 'fs';
-import { dirname } from 'path';
+import {
+  writeFileSync,
+  mkdirSync,
+  chmodSync,
+  existsSync,
+  renameSync,
+  unlinkSync,
+} from 'fs';
+import { dirname, join } from 'path';
+import { randomBytes } from 'crypto';
 
 /**
  * Write file with secure permissions (0600 - user read/write only)
- * Also ensures parent directory has 0700 permissions
+ * Uses atomic write pattern: write to temp file, then rename
+ * This prevents corruption if process crashes mid-write
  */
 export function writeFileSecure(filePath: string, data: string): void {
   const dir = dirname(filePath);
@@ -18,11 +27,29 @@ export function writeFileSecure(filePath: string, data: string): void {
     mkdirSync(dir, { recursive: true, mode: 0o700 });
   }
 
-  // Write file
-  writeFileSync(filePath, data);
+  // Generate temp file path in same directory (required for atomic rename)
+  const tempPath = join(dir, `.tmp-${randomBytes(8).toString('hex')}`);
 
-  // Set secure permissions (user read/write only)
-  chmodSync(filePath, 0o600);
+  try {
+    // Write to temp file first
+    writeFileSync(tempPath, data);
+
+    // Set secure permissions on temp file
+    chmodSync(tempPath, 0o600);
+
+    // Atomic rename (same filesystem, so this is atomic on POSIX)
+    renameSync(tempPath, filePath);
+  } catch (error) {
+    // Clean up temp file on failure
+    try {
+      if (existsSync(tempPath)) {
+        unlinkSync(tempPath);
+      }
+    } catch {
+      // Ignore cleanup errors
+    }
+    throw error;
+  }
 }
 
 /**

src/hooks/sms-action-runner.ts

@@ -141,6 +141,12 @@ function isActionAllowed(action: string): boolean {
   });
 }
 
+export interface ActionResult {
+  success: boolean;
+  output?: string;
+  error?: string;
+}
+
 export interface PendingAction {
   id: string;
   promptId: string;

src/hooks/sms-webhook.ts

@@ -27,6 +27,7 @@ import {
   queueAction,
   executeActionSafe,
   cleanupOldActions,
+  type ActionResult,
 } from './sms-action-runner.js';
 import {
   isCommand,
@@ -56,16 +57,91 @@ const MAX_PHONE_LENGTH = 50; // WhatsApp format: whatsapp:+12345678901
 const MAX_BODY_SIZE = 50 * 1024; // 50KB max body
 const RATE_LIMIT_WINDOW_MS = 60 * 1000; // 1 minute
 const RATE_LIMIT_MAX_REQUESTS = 30; // 30 requests per minute per IP
+const ACTION_TIMEOUT_MS = 60000; // 60 second timeout for action execution
 
-// Rate limiting store (in production, use Redis)
-const rateLimitStore = new Map<string, { count: number; resetTime: number }>();
+/**
+ * Execute action with timeout to prevent hanging requests
+ */
+async function executeActionWithTimeout(
+  action: string,
+  response: string
+): Promise<ActionResult> {
+  return Promise.race([
+    executeActionSafe(action, response),
+    new Promise<ActionResult>((_, reject) =>
+      setTimeout(
+        () =>
+          reject(new Error(`Action timed out after ${ACTION_TIMEOUT_MS}ms`)),
+        ACTION_TIMEOUT_MS
+      )
+    ),
+  ]).catch((error) => ({
+    success: false,
+    error: error instanceof Error ? error.message : String(error),
+  }));
+}
+
+// Rate limiting store - persisted to disk to survive restarts
+const RATE_LIMIT_PATH = join(homedir(), '.stackmemory', 'rate-limits.json');
+
+interface RateLimitRecord {
+  count: number;
+  resetTime: number;
+}
+
+interface RateLimitStore {
+  [ip: string]: RateLimitRecord;
+}
+
+// In-memory cache with periodic persistence
+let rateLimitCache: RateLimitStore = {};
+let rateLimitCacheDirty = false;
+
+function loadRateLimits(): RateLimitStore {
+  try {
+    if (existsSync(RATE_LIMIT_PATH)) {
+      const data = JSON.parse(readFileSync(RATE_LIMIT_PATH, 'utf8'));
+      // Clean up expired entries on load
+      const now = Date.now();
+      const cleaned: RateLimitStore = {};
+      for (const [ip, record] of Object.entries(data)) {
+        const r = record as RateLimitRecord;
+        if (r.resetTime > now) {
+          cleaned[ip] = r;
+        }
+      }
+      return cleaned;
+    }
+  } catch {
+    // Use empty store on error
+  }
+  return {};
+}
+
+function saveRateLimits(): void {
+  if (!rateLimitCacheDirty) return;
+  try {
+    ensureSecureDir(join(homedir(), '.stackmemory'));
+    writeFileSecure(RATE_LIMIT_PATH, JSON.stringify(rateLimitCache));
+    rateLimitCacheDirty = false;
+  } catch {
+    // Ignore save errors - rate limiting is best-effort
+  }
+}
+
+// Persist rate limits periodically (every 30 seconds)
+setInterval(saveRateLimits, 30000);
+
+// Load on startup
+rateLimitCache = loadRateLimits();
 
 function checkRateLimit(ip: string): boolean {
   const now = Date.now();
-  const record = rateLimitStore.get(ip);
+  const record = rateLimitCache[ip];
 
   if (!record || now > record.resetTime) {
-    rateLimitStore.set(ip, { count: 1, resetTime: now + RATE_LIMIT_WINDOW_MS });
+    rateLimitCache[ip] = { count: 1, resetTime: now + RATE_LIMIT_WINDOW_MS };
+    rateLimitCacheDirty = true;
     return true;
   }
 
@@ -74,6 +150,7 @@ function checkRateLimit(ip: string): boolean {
   }
 
   record.count++;
+  rateLimitCacheDirty = true;
   return true;
 }
 
@@ -298,11 +375,11 @@ export async function handleSMSWebhook(payload: TwilioWebhookPayload): Promise<{
   // Trigger notification to alert user/Claude
   triggerResponseNotification(result.response || Body);
 
-  // Execute action safely if present (no shell injection)
+  // Execute action safely if present (no shell injection, with timeout)
   if (result.action) {
     console.log(`[sms-webhook] Executing action: ${result.action}`);
 
-    const actionResult = await executeActionSafe(
+    const actionResult = await executeActionWithTimeout(
       result.action,
       result.response || Body
     );