Log lock release errors and cover acquireLock with tests

Address Copilot review on PR #24:
- Surface release() failures via log.warn so operators see why a lock
  wasn't cleared instead of the wrapper swallowing the error.
- Export acquireLock and add coverage for acquire/release, ELOCKED →
  instance-running (with rm -rf and meta-sidecar hint), legacy `.lock`
  file migration, and meta sidecar cleanup on release.

Author: slaFFik

src/server/preflight.ts

@@ -271,7 +271,7 @@ async function migrateLegacyLock(lockFilePath: string): Promise<void> {
   }
 }
 
-async function acquireLock(
+export async function acquireLock(
   storageRoot: string,
   lockFilePath: string,
 ): Promise<() => Promise<void>> {
@@ -297,7 +297,17 @@ async function acquireLock(
     throw err;
   }
   return async () => {
-    await release().catch(() => undefined);
+    try {
+      await release();
+    } catch (err) {
+      // Surface release failures so the operator knows why the lock wasn't
+      // cleared — they will have to wait out the stale window or remove the
+      // lock directory manually (see the `instance-running` hint).
+      log.warn('preflight.lock-release-failed', {
+        path: lockFilePath,
+        error: (err as Error).message,
+      });
+    }
     await unlink(metaPath).catch(() => undefined);
   };
 }

test/preflight.spec.ts

@@ -1,4 +1,7 @@
-import { authSmokeTest, PreflightError } from '../src/server/preflight.js';
+import { mkdtemp, mkdir, readdir, rm, stat, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { acquireLock, authSmokeTest, PreflightError } from '../src/server/preflight.js';
 
 const fakeBin = new URL('./fake-claude.mjs', import.meta.url).pathname;
 
@@ -83,4 +86,102 @@ await scenario('authSmokeTest: spawn-error path when binary is missing', async (
   );
 });
 
+async function withTempStorage<T>(run: (storageRoot: string) => Promise<T>): Promise<T> {
+  const dir = await mkdtemp(join(tmpdir(), 'mdredd-lock-'));
+  try {
+    return await run(dir);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+}
+
+await scenario('acquireLock: acquires, then re-acquires after release', async () => {
+  await withTempStorage(async (storageRoot) => {
+    const lockPath = join(storageRoot, '.lock');
+    const release1 = await acquireLock(storageRoot, lockPath);
+    const stat1 = await stat(lockPath);
+    if (!stat1.isDirectory()) {
+      throw new Error('expected lockfile path to be a directory after acquire');
+    }
+    await release1();
+    // Second acquire on the same storage root should succeed once the first
+    // has been released — proves the wrapper actually clears the lock.
+    const release2 = await acquireLock(storageRoot, lockPath);
+    await release2();
+  });
+});
+
+await scenario(
+  'acquireLock: surfaces ELOCKED as instance-running with rm -rf hint',
+  async () => {
+    await withTempStorage(async (storageRoot) => {
+      const lockPath = join(storageRoot, '.lock');
+      const release = await acquireLock(storageRoot, lockPath);
+      try {
+        const err = await expectPreflightError(
+          async () => {
+            await acquireLock(storageRoot, lockPath);
+          },
+          'instance-running',
+          'rm -rf',
+        );
+        if (!err.hint || !err.hint.includes(`${lockPath}.meta.json`)) {
+          throw new Error(`expected hint to mention meta sidecar, got: ${err.hint}`);
+        }
+      } finally {
+        await release();
+      }
+    });
+  },
+);
+
+await scenario('acquireLock: legacy `.lock` file is migrated away', async () => {
+  await withTempStorage(async (storageRoot) => {
+    const lockPath = join(storageRoot, '.lock');
+    // Older versions wrote `.lock` as a regular JSON file. proper-lockfile
+    // uses the same path as a mkdir-based directory, so a stale legacy file
+    // would block startup forever — acquire must remove it first.
+    await writeFile(lockPath, '{"pid":1,"port":6800}');
+    const release = await acquireLock(storageRoot, lockPath);
+    try {
+      const st = await stat(lockPath);
+      if (!st.isDirectory()) {
+        throw new Error('expected `.lock` to be a directory after migration');
+      }
+    } finally {
+      await release();
+    }
+  });
+});
+
+await scenario('acquireLock: release removes the lock directory and meta sidecar', async () => {
+  await withTempStorage(async (storageRoot) => {
+    const lockPath = join(storageRoot, '.lock');
+    const metaPath = `${lockPath}.meta.json`;
+    const release = await acquireLock(storageRoot, lockPath);
+    // Simulate writeLockMeta having run during normal startup so we can
+    // verify release() removes the sidecar too.
+    await writeFile(metaPath, '{"pid":1,"port":6800,"startedAt":""}');
+    await release();
+    const entries = await readdir(storageRoot);
+    if (entries.includes('.lock')) {
+      throw new Error(`expected .lock to be gone after release, got: ${entries.join(', ')}`);
+    }
+    if (entries.includes('.lock.meta.json')) {
+      throw new Error(`expected meta sidecar to be removed, got: ${entries.join(', ')}`);
+    }
+  });
+});
+
+await scenario('acquireLock: storageRoot must exist before acquire', async () => {
+  // Sanity check that the helper relies on the caller having ensured the
+  // directory — this matches the runPreflight() ordering (ensureDir first).
+  await withTempStorage(async (parent) => {
+    const storageRoot = join(parent, 'nested');
+    await mkdir(storageRoot, { recursive: true });
+    const release = await acquireLock(storageRoot, join(storageRoot, '.lock'));
+    await release();
+  });
+});
+
 console.log('\nAll preflight smoke scenarios passed.');