@lincoln504/pi-research 1.1.0 → 1.2.0

package/src/infrastructure/file-lock-service.ts

@@ -23,6 +23,21 @@ import type { IProcessLifecycle } from '../core/interfaces/process-interfaces.ts
  */
 const lockContext = new AsyncLocalStorage<Set<string>>();
 
+/**
+ * How long cleanup() waits for an in-flight critical section to release normally
+ * before forcing the teardown. Long enough for an ordinary state write (temp file
+ * + fsync + rename) to finish, short enough that shutdown still makes progress
+ * when the holder is wedged.
+ */
+const CLEANUP_DRAIN_TIMEOUT_MS = 5_000;
+
+/**
+ * Age past which an orphaned `<lock>.trash.<hex>` copy is swept at startup. An
+ * in-flight trash-and-verify holds its copy for milliseconds; anything this old
+ * was leaked by a crash mid-dance.
+ */
+const TRASH_SWEEP_AGE_MS = 10 * 60_000;
+
 /**
  * Lock configuration options
  */
@@ -83,6 +98,9 @@ export class FileLockService implements IService {
   // PID reuse. Null when unavailable (no processLifecycle, or lookup failed) —
   // then lock content omits startTime and readers treat us as a legacy owner.
   private ownStartTime: number | null = null;
+  // Set by cleanup(). A retired instance no longer manages the lock file, so
+  // acquiring through it would hand out exclusivity it cannot honour.
+  private _retired = false;
 
   constructor(options: FileLockOptions) {
     this.lockFilePath = options.lockFilePath;
@@ -175,11 +193,111 @@ export class FileLockService implements IService {
     this.lifecycle = ServiceLifecycle.DISPOSED;
   }
 
+  /**
+   * Put a lock file back after a trash-and-verify decided not to reclaim it.
+   *
+   * The old form linked it back inside a swallowing catch and then unlinked the
+   * trash copy unconditionally — so any link failure other than "a peer already
+   * re-created it" DESTROYED the lock this branch exists to preserve. Distinguish
+   * the two: if the path is occupied again the peer's lock wins and ours is dropped;
+   * otherwise move ours back rather than deleting it.
+   */
+  private async _restoreLockFile(trashPath: string): Promise<void> {
+    try {
+      await fs.link(trashPath, this.lockFilePath);
+      await fs.unlink(trashPath).catch(() => { /* link succeeded; copy is redundant */ });
+      return;
+    } catch { /* fall through to the two cases below */ }
+
+    const peerHoldsIt = await fs.access(this.lockFilePath).then(() => true).catch(() => false);
+    if (peerHoldsIt) {
+      // Someone re-created the lock while we were checking. Theirs is authoritative.
+      await fs.unlink(trashPath).catch(() => { /* best effort */ });
+      return;
+    }
+    // Nothing there and link failed (EPERM, filesystems without hardlinks,
+    // Windows link limits): re-create the path EXCLUSIVELY rather than rename it
+    // back — rename silently REPLACES a lock a peer creates between the probe
+    // above and now, clobbering a live owner. 'wx' loses that race loudly, and
+    // then the peer's lock is authoritative.
+    try {
+      const content = await fs.readFile(trashPath, 'utf-8');
+      const handle = await fs.open(this.lockFilePath, 'wx', 0o600);
+      try {
+        await handle.write(content);
+        await handle.sync();
+      } finally {
+        await handle.close().catch(() => { /* content is on disk */ });
+      }
+      await fs.unlink(trashPath).catch(() => { /* restored; copy is redundant */ });
+    } catch {
+      // EEXIST (a peer took the path) — ours is redundant; anything else, leave
+      // the trash copy for the startup sweep. Never delete what we could not
+      // put back.
+      const occupied = await fs.access(this.lockFilePath).then(() => true).catch(() => false);
+      if (occupied) await fs.unlink(trashPath).catch(() => { /* best effort */ });
+    }
+  }
+
+  /**
+   * Hand our turn back to the next caller in the FIFO queue.
+   *
+   * Every path that stops holding the lock must run this, including the ones that
+   * find the handle already gone. `acquireLock` parks on `await previous` with no
+   * timeout of its own — the lockTimeout only starts counting once the turn has
+   * been granted — so a turn that is never resolved is not a slow acquire, it is a
+   * permanent one.
+   */
+  private _releaseTurn(): void {
+    const resolve = this.resolveTurn;
+    this.resolveTurn = null;
+    if (resolve) resolve();
+  }
+
+  /**
+   * Wait, bounded, for an in-flight critical section to finish.
+   *
+   * Yanking a held lock is not a clean teardown: unlinking the file while the
+   * holder is still mid read-modify-write drops cross-process exclusion, and a peer
+   * that acquires in that window loses the holder's update — precisely the hazard
+   * the lock exists to prevent. Since every caller of {@link cleanup} is a shutdown
+   * path, waiting briefly for a normal release is both safe and correct.
+   *
+   * Bounded because shutdown must make progress regardless: if the holder is wedged
+   * (or is itself the caller, which would otherwise deadlock), we give up and force
+   * the teardown, which is the pre-existing behaviour.
+   */
+  private async _drainHeldLock(timeoutMs: number): Promise<boolean> {
+    const deadline = Date.now() + timeoutMs;
+    while (this.lockHandle !== null && Date.now() < deadline) {
+      await this.sleep(Math.min(25, this.lockRetryDelay));
+    }
+    return this.lockHandle === null;
+  }
+
   /**
    * Clean up any stale lock files on initialization.
    * This handles cases where locks weren't released due to crashes.
    */
   private async cleanupStaleLocksOnStartup(): Promise<void> {
+    // Sweep trash copies leaked by an interrupted trash-and-verify (a crash or
+    // I/O failure between the rename and the unlink/restore). Nothing else ever
+    // collects them: the state-dir orphan sweep matches only *.tmp files. The age
+    // gate is generous — an in-flight reclaim's trash copy lives for milliseconds,
+    // and a restore-worthy one is put back on the same code path that made it.
+    try {
+      const dir = pathmod.dirname(this.lockFilePath);
+      const prefix = `${pathmod.basename(this.lockFilePath)}.trash.`;
+      for (const name of await fs.readdir(dir)) {
+        if (!name.startsWith(prefix)) continue;
+        const p = pathmod.join(dir, name);
+        const st = await fs.stat(p).catch(() => null);
+        if (st && Date.now() - st.mtimeMs > TRASH_SWEEP_AGE_MS) {
+          await fs.unlink(p).catch(() => { /* best effort */ });
+        }
+      }
+    } catch { /* best-effort hygiene; never blocks startup */ }
+
     try {
       const rawContent = await fs.readFile(this.lockFilePath, 'utf-8').catch(() => null);
       if (rawContent === null) return; // No lock file — nothing to do
@@ -201,19 +319,25 @@ export class FileLockService implements IService {
         // the UUID matches what we decided on — same guard as the contended path.
         const expectedUuid = parsed?.uuid ?? '';
         const trashPath = `${this.lockFilePath}.trash.${crypto.randomBytes(8).toString('hex')}`;
+        let renamed = false;
         try {
           await fs.rename(this.lockFilePath, trashPath);
+          renamed = true;
           const trashContent = await fs.readFile(trashPath, 'utf-8');
           const trashParsed = this._parseLockContent(trashContent);
           if ((trashParsed?.uuid ?? '') !== expectedUuid) {
             // Lock changed hands mid-check — restore it and back off.
-            try { await fs.link(trashPath, this.lockFilePath); } catch { /* ignore */ }
-            await fs.unlink(trashPath);
+            await this._restoreLockFile(trashPath);
             return;
           }
-          await fs.unlink(trashPath);
+          await fs.unlink(trashPath).catch(() => { /* leaked copy; the sweep above collects it */ });
           logger.log('[FileLockService] Stale lock removed');
-        } catch { /* best-effort startup cleanup; acquire() handles contention */ }
+        } catch {
+          // A failure AFTER the rename means the verify never ran — restore
+          // rather than leave the (possibly live) lock destroyed in the trash.
+          if (renamed) await this._restoreLockFile(trashPath);
+          /* otherwise best-effort startup cleanup; acquire() handles contention */
+        }
       }
     } catch (error: unknown) {
       // ENOENT is expected (no lock file exists)
@@ -232,6 +356,9 @@ export class FileLockService implements IService {
    * @throws Error if unable to acquire lock within timeout
    */
   async acquireLock(): Promise<void> {
+    if (this._retired) {
+      throw new Error(`Cannot acquire lock at ${this.lockFilePath}: service has been disposed`);
+    }
     const heldLocks = lockContext.getStore();
     const lockKey = `${this.lockFilePath}:${this.lockUuid}`;
 
@@ -270,6 +397,14 @@ export class FileLockService implements IService {
       return;
     }
 
+    // Re-check after the wait: cleanup() may have retired the instance while we
+    // were queued. Hand the turn straight on rather than acquiring a lock file this
+    // instance no longer owns.
+    if (this._retired) {
+      myResolve();
+      throw new Error(`Cannot acquire lock at ${this.lockFilePath}: service was disposed while queued`);
+    }
+
     // Capture resolve function so we can trigger it in releaseLock() or on failure
     this.resolveTurn = myResolve;
 
@@ -282,6 +417,15 @@ export class FileLockService implements IService {
 
     try {
       for (let _attempt = 0; _attempt < this.lockRetries; _attempt++) {
+        // cleanup() can retire the instance while we are contending here — its
+        // drain polls only the HELD handle, so a caller mid-retry (holding
+        // nothing yet) is invisible to it and would otherwise win the lock and
+        // run its critical section against torn-down services after dispose
+        // resolved. The queued-waiter check above cannot catch this: our turn was
+        // granted before retirement. Abort; the catch below hands the turn on.
+        if (this._retired) {
+          throw new Error(`Cannot acquire lock at ${this.lockFilePath}: service was disposed during acquisition`);
+        }
         // Use a LOCAL handle variable so that concurrent acquireLock() calls on
         // the same instance cannot close each other's file handle through the
         // shared this.lockHandle field. We only promote to this.lockHandle after
@@ -293,6 +437,14 @@ export class FileLockService implements IService {
           await handle.write(this._makeLockContent());
           await handle.sync(); // Ensure content is written to disk
 
+          // Retirement may have landed between the open above and this commit.
+          // cleanup()'s drain saw no held handle and already returned, so nothing
+          // would ever tear this acquisition down. Throwing here lets the catch
+          // below close the handle and remove the just-created lock file.
+          if (this._retired) {
+            throw new Error(`Cannot acquire lock at ${this.lockFilePath}: service was disposed during acquisition`);
+          }
+
           // Fully acquired — commit to instance state
           this.lockHandle = handle;
           this.lockCount = 1;
@@ -355,26 +507,47 @@ export class FileLockService implements IService {
                 // surrounding retry loop / timeout, not by stealing.
                 if (await this._shouldReclaim(parsed?.pid ?? null, parsed?.startTime ?? null, lockAge, contendedOwnerAliveMemo)) {
                   const trashPath = `${this.lockFilePath}.trash.${crypto.randomBytes(8).toString('hex')}`;
+                  let renamed = false;
                   try {
                     await fs.rename(this.lockFilePath, trashPath);
+                    renamed = true;
                     const trashContent = await fs.readFile(trashPath, 'utf-8');
                     const trashParsed = this._parseLockContent(trashContent);
                     if ((trashParsed?.uuid ?? '') !== lockUuid) {
-                      try { await fs.link(trashPath, this.lockFilePath); } catch { /* ignore */ }
-                      await fs.unlink(trashPath);
+                      await this._restoreLockFile(trashPath);
                       continue;
                     }
-                    await fs.unlink(trashPath);
-                  } catch { /* ignore */ }
+                    await fs.unlink(trashPath).catch(() => { /* leaked copy; startup sweep collects it */ });
+                  } catch {
+                    // Rename failed (nothing moved) — retry handles it. But a read
+                    // failure AFTER the rename means the verify never ran: the lock
+                    // may have changed hands to a live peer mid-check, and leaving
+                    // it in the trash destroys it unverified — the same transient
+                    // classes (EMFILE, EACCES, EBUSY) the inspect branch below
+                    // backs off for. Put it back instead.
+                    if (renamed) await this._restoreLockFile(trashPath);
+                  }
                   continue;
                 }
-              } catch (_statError) {
-                const trashPath = `${this.lockFilePath}.trash.${crypto.randomBytes(8).toString('hex')}`;
-                try {
-                  await fs.rename(this.lockFilePath, trashPath);
-                  await fs.unlink(trashPath);
-                  continue;
-                } catch { /* ignore */ }
+              } catch (inspectError) {
+                // We could not READ the lock, which says nothing about whether its
+                // owner is alive. Destroying it here — as this branch used to,
+                // with neither a UUID check nor a liveness check, unlike the
+                // verified path above — turns any transient fs failure (EMFILE
+                // under fd pressure, EACCES, EBUSY on Windows) into a stolen lock
+                // and two concurrent writers on the same file.
+                //
+                // ENOENT is the exception and the common case: the lock was
+                // released between our open() and our read, so there is nothing to
+                // destroy and retrying immediately is correct.
+                const code = (inspectError as NodeJS.ErrnoException | undefined)?.code;
+                if (code === 'ENOENT') continue;
+                logger.warn(
+                  `[FileLockService] Could not inspect contended lock at ${this.lockFilePath} ` +
+                  `(${code ?? 'unknown'}); backing off rather than reclaiming it.`,
+                );
+                metrics.increment('state_lock_inspect_failed_total', 1, { code: code ?? 'unknown' });
+                // Fall through to the timeout check + backoff below.
               }
 
               if (Date.now() - startTime >= this.lockTimeout) {
@@ -400,10 +573,7 @@ export class FileLockService implements IService {
     } catch (err) {
       // If acquisition failed (timeout/error), we MUST release our turn in the 
       // queue so the next caller can try.
-      if (this.resolveTurn) {
-        this.resolveTurn();
-        this.resolveTurn = null;
-      }
+      this._releaseTurn();
       throw err;
     }
   }
@@ -413,6 +583,11 @@ export class FileLockService implements IService {
    */
   async releaseLock(): Promise<void> {
     if (this.lockHandle === null) {
+      // cleanup() can tear the handle down underneath an in-flight critical
+      // section, so withLock()'s finally lands here with the handle already gone.
+      // The queue turn is still ours to hand back — returning without doing so
+      // leaves every queued waiter blocked on `await previous` for good.
+      this._releaseTurn();
       return;
     }
 
@@ -443,11 +618,7 @@ export class FileLockService implements IService {
       metrics.setGauge('state_lock_held', 0);
     } finally {
       // 4. Signal the next caller in the queue that it's their turn.
-      const resolve = this.resolveTurn;
-      this.resolveTurn = null;
-      if (resolve) {
-        resolve();
-      }
+      this._releaseTurn();
     }
   }
 
@@ -455,8 +626,13 @@ export class FileLockService implements IService {
    * Execute a function within the scope of a filesystem lock.
    * This is the preferred way to use the lock service.
    * Safe re-entrancy is supported within the same async flow.
+   *
+   * The acquire timeout is the one given to the constructor (`lockTimeout`). This
+   * used to take a second `_timeout` argument that was accepted and then ignored
+   * entirely — a caller passing 5000 silently got the constructed 20000 — so it is
+   * gone rather than left to mislead. No caller was passing it.
    */
-  async withLock<T>(callback: () => Promise<T> | T, _timeout: number = 30000): Promise<T> {
+  async withLock<T>(callback: () => Promise<T> | T): Promise<T> {
     const heldLocks = lockContext.getStore();
     const lockKey = `${this.lockFilePath}:${this.lockUuid}`;
 
@@ -477,9 +653,28 @@ export class FileLockService implements IService {
   }
 
   /**
-   * Force clean up any lock files owned by this instance.
+   * Clean up any lock file owned by this instance, and retire the instance.
+   *
+   * Called only from shutdown paths (`dispose`, `StateManager.cleanup`). It first
+   * gives an in-flight critical section a bounded chance to release normally, then
+   * forces the teardown if it has not. After this the instance is retired:
+   * `acquireLock` fails fast rather than blocking on a queue nothing will ever
+   * drain, which is what makes forcing the teardown safe to do at all.
    */
   async cleanup(): Promise<void> {
+    const drained = await this._drainHeldLock(CLEANUP_DRAIN_TIMEOUT_MS);
+    if (!drained) {
+      logger.warn(
+        `[FileLockService] Lock at ${this.lockFilePath} still held after ${CLEANUP_DRAIN_TIMEOUT_MS}ms; forcing teardown. ` +
+        'A concurrent writer in another process may observe the lock as free.',
+      );
+      metrics.increment('state_lock_forced_teardown_total', 1);
+    }
+
+    // Retire BEFORE releasing the turn, so a waiter woken below re-checks and
+    // fails fast instead of acquiring a lock this instance no longer manages.
+    this._retired = true;
+
     if (this.lockHandle) {
       try {
         const content = await fs.readFile(this.lockFilePath, 'utf8').catch(() => '');
@@ -494,6 +689,8 @@ export class FileLockService implements IService {
       this.lockHandle = null;
     }
     this.lockCount = 0;
+    // Unblock anyone parked on `await previous`; they will now see _retired and throw.
+    this._releaseTurn();
   }
 
   /**

package/src/infrastructure/process-lifecycle-service.ts

@@ -11,6 +11,39 @@ import type { IProcessLifecycle } from '../core/interfaces/process-interfaces.ts
 import { ServiceLifecycle } from '../core/service-registry.ts';
 import { ServiceNames } from '../core/interfaces/service-names.ts';
 
+/**
+ * Parse the POSIX `ps -o etime=` elapsed-time format into whole seconds.
+ * Accepted shapes: `MM:SS`, `HH:MM:SS`, `DD-HH:MM:SS`. Returns null if it does
+ * not parse, so a caller degrades to "unknown" rather than to a bogus number.
+ */
+export function parseEtime(value: string): number | null {
+  const m = /^(?:(\d+)-)?(?:(\d+):)?(\d+):(\d+)$/.exec(value.trim());
+  if (!m) return null;
+  const days = m[1] ? parseInt(m[1], 10) : 0;
+  const hours = m[2] ? parseInt(m[2], 10) : 0;
+  const minutes = parseInt(m[3]!, 10);
+  const seconds = parseInt(m[4]!, 10);
+  if ([days, hours, minutes, seconds].some((n) => isNaN(n))) return null;
+  return days * 86400 + hours * 3600 + minutes * 60 + seconds;
+}
+
+/**
+ * Does this `process.kill(pid, 0)` failure mean the process is GONE?
+ *
+ * Only `ESRCH` does. `EPERM` (POSIX) and `EACCES` — which is what libuv surfaces
+ * on Windows when `OpenProcess` returns ERROR_ACCESS_DENIED — both mean the
+ * process EXISTS but is not ours to signal: another user on a shared host, a CI
+ * side-car, a different Windows session. Reporting those as dead lets a caller
+ * reclaim a live lock, run slot or leader out from under its owner, which is how
+ * two writers end up racing the state file. The orphan guard and the browser
+ * sweep already get this right; this is the same rule.
+ */
+function isDefinitelyGone(err: unknown): boolean {
+  const code = (err as NodeJS.ErrnoException | undefined)?.code;
+  if (code === 'EPERM' || code === 'EACCES') return false;
+  return true;
+}
+
 /**
  * Process Lifecycle Service
  *
@@ -74,23 +107,51 @@ export class ProcessLifecycleService implements IProcessLifecycle {
       }
     }
 
-    // Cross-platform fallback (macOS/Unix): `ps -o etimes=` returns elapsed seconds.
-    try {
-      const output = await new Promise<string>((resolve, reject) => {
-        const child = execFile(
-          'ps', ['-o', 'etimes=', '-p', String(pid)],
-          { encoding: 'utf8', timeout: 3000 },
-          (err, stdout) => err ? reject(err) : resolve(stdout),
-        );
-        child.unref?.();
-      });
-      if (!output || !output.trim()) return null;
-      const elapsedSec = parseInt(output.trim(), 10);
-      if (isNaN(elapsedSec)) return null;
-      return Math.floor(Date.now() / 1000) - elapsedSec;
-    } catch {
-      return null;
+    // Cross-platform fallback (macOS/BSD): derive start time from elapsed time.
+    //
+    // `etimes` (elapsed WHOLE SECONDS) is a procps-ng/FreeBSD extension. Apple's
+    // ps (adv_cmds) does not implement it — it has only the POSIX `etime`
+    // ([[dd-]hh:]mm:ss). Asking for an unsupported keyword does not fail loudly:
+    // procps-ng writes an error to stderr and still exits 0 with EMPTY stdout,
+    // BSD ps exits non-zero. Both collapse to `null` here, which meant every
+    // PID+start-time guard on macOS silently degraded to a bare signal-0 check —
+    // the file lock, the run-slot semaphore, the GPU lock and both leader
+    // elections all advertise PID-reuse safety they were not actually getting.
+    //
+    // So: try `etimes`, and fall back to parsing POSIX `etime` when it yields
+    // nothing. `etime` is mandated by POSIX, so the fallback works everywhere.
+    const elapsedSec = await this.readElapsedSeconds(pid);
+    if (elapsedSec === null) return null;
+    return Math.floor(Date.now() / 1000) - elapsedSec;
+  }
+
+  /** Elapsed seconds for `pid` via ps, or null. Tries `etimes`, then POSIX `etime`. */
+  private async readElapsedSeconds(pid: number): Promise<number | null> {
+    const run = async (fmt: string): Promise<string | null> => {
+      try {
+        return await new Promise<string>((resolve, reject) => {
+          const child = execFile(
+            'ps', ['-o', fmt, '-p', String(pid)],
+            { encoding: 'utf8', timeout: 3000 },
+            (err, stdout) => err ? reject(err) : resolve(stdout),
+          );
+          child.unref?.();
+        });
+      } catch {
+        return null;
+      }
+    };
+
+    const etimes = await run('etimes=');
+    if (etimes && etimes.trim()) {
+      const n = parseInt(etimes.trim(), 10);
+      if (!isNaN(n)) return n;
     }
+
+    const etime = await run('etime=');
+    if (etime && etime.trim()) return parseEtime(etime.trim());
+
+    return null;
   }
 
   /**
@@ -111,11 +172,20 @@ export class ProcessLifecycleService implements IProcessLifecycle {
    * @returns true if process is alive (and matches start time if provided)
    */
   async isProcessAlive(pid: number, expectedStartTime?: number | null): Promise<boolean> {
+    // 1. EXISTENCE. Separate from identity (step 2) on purpose: a permission error
+    //    means the process exists but is not ours to signal, which must NOT
+    //    short-circuit the start-time comparison — a PID-reuse impostor owned by
+    //    another user would otherwise read as a live owner and deadlock the lock,
+    //    run slot or leadership it forged.
     try {
-      // 1. Basic liveness check via signal 0
       process.kill(pid, 0);
-      
-      // 2. If start time verification requested, check it
+    } catch (err) {
+      if (isDefinitelyGone(err)) return false;
+      // EPERM/EACCES: exists, not signalable by us — continue to the identity check.
+    }
+
+    try {
+      // 2. IDENTITY. If start time verification requested, check it.
       if (expectedStartTime !== undefined && expectedStartTime !== null) {
         const actualStartTime = await this.getProcessStartTime(pid);
         if (actualStartTime === null) {
@@ -132,14 +202,18 @@ export class ProcessLifecycleService implements IProcessLifecycle {
           // caller — a live lock/leader/run-cap owner is reclaimed from under it
           // → two writers collide (lost update) or the run-cap admits extra
           // concurrent runs (the flaky duplicate-slot/cap-breach we saw on Windows
-          // CI). So re-confirm liveness instead of guessing: if signal(0) STILL
-          // succeeds the process is alive → return true; if it now throws it died
-          // between the two probes and the outer catch returns false. A genuine
-          // death is therefore still detected within one poll tick (~100ms); the
-          // only behavioural change is that a confirmed-alive PID is never again
-          // misreported as dead on a transient start-time lookup failure.
-          process.kill(pid, 0); // re-confirm; a throw (process died) → outer catch → false
-          return true;
+          // CI). So re-confirm existence instead of guessing: if the PID is STILL
+          // there the process is alive → true; if it has gone it died between the
+          // two probes → false. A genuine death is therefore still detected within
+          // one poll tick (~100ms); the only behavioural change is that a
+          // confirmed-alive PID is never again misreported as dead on a transient
+          // start-time lookup failure.
+          try {
+            process.kill(pid, 0);
+            return true;
+          } catch (reconfirmErr) {
+            return !isDefinitelyGone(reconfirmErr);
+          }
         }
         // Allow ±1s slack. The macOS/BSD fallback derives start time as
         // floor(Date.now()/1000) - `ps etimes` (elapsed whole seconds); both terms are
@@ -149,10 +223,13 @@ export class ProcessLifecycleService implements IProcessLifecycle {
         // within a 1s window at the identical PID is not a realistic false-match.
         return Math.abs(actualStartTime - expectedStartTime) <= 1;
       }
-      
+
       return true;
     } catch {
-      return false;
+      // The start-time lookup itself blew up (not a signal error — those are
+      // handled above). Existence was already established, so treat it as alive:
+      // reclaiming a confirmed-present owner is the worse failure.
+      return true;
     }
   }
 
@@ -163,8 +240,8 @@ export class ProcessLifecycleService implements IProcessLifecycle {
     try {
       process.kill(pid, 0);
       return true;
-    } catch {
-      return false;
+    } catch (err) {
+      return !isDefinitelyGone(err);
     }
   }
 

package/src/infrastructure/state/state-backup-manager.ts

@@ -8,6 +8,7 @@ import * as fs from 'node:fs/promises';
 import * as crypto from 'node:crypto';
 import * as path from 'node:path';
 import { logger } from '../../logger.ts';
+import { replaceFile } from '../../utils/atomic-replace.ts';
 import type { IService } from '../../core/service-registry.ts';
 import { ServiceLifecycle } from '../../core/service-registry.ts';
 import { ServiceNames } from '../../core/interfaces/service-names.ts';
@@ -253,15 +254,12 @@ export class StateBackupManager implements IService {
       await fh.close();
     }
     try {
-      await fs.rename(tempPath, this.stateFilePath);
-    } catch (renameErr) {
-      if (process.platform === 'win32') {
-        await fs.copyFile(tempPath, this.stateFilePath);
-        await fs.unlink(tempPath).catch(() => { /* best-effort cleanup */ });
-      } else {
+      if (await replaceFile(tempPath, this.stateFilePath) === 'copied') {
         await fs.unlink(tempPath).catch(() => { /* best-effort cleanup */ });
-        throw renameErr;
       }
+    } catch (renameErr) {
+      await fs.unlink(tempPath).catch(() => { /* best-effort cleanup */ });
+      throw renameErr;
     }
   }
 

package/src/infrastructure/state/state-manager-service.ts

@@ -195,7 +195,7 @@ export class StateManagerService implements IStateManager {
   /**
    * Get the current embedding server information
    */
-  async getEmbeddingServer(): Promise<{ port: number; pid: number; startTime?: number; serverId: string; model?: string } | null> {
+  async getEmbeddingServer(): Promise<{ port: number; pid: number; startTime?: number; serverId: string; model?: string; authSecret?: string } | null> {
     return this.getStateManager().getEmbeddingServer();
   }
 

package/src/infrastructure/state/state-manager.ts

@@ -23,6 +23,7 @@ import * as crypto from 'node:crypto';
 import process from 'node:process';
 import { getGlobalConfigDir } from '../../config.ts';
 import { logger } from '../../logger.ts';
+import { replaceFile } from '../../utils/atomic-replace.ts';
 import { metrics } from '../../utils/metrics.ts';
 import type { IProcessLifecycle } from '../../core/interfaces/process-interfaces.ts';
 import type {
@@ -350,25 +351,23 @@ export class StateManager {
       } finally {
         await fh.close();
       }
-      try {
-        await fs.rename(tempFilePath, this.stateFilePath);
-      } catch (renameErr) {
-        // fs.rename fails on Windows if target exists (NTFS). Fall back to copy+delete.
-        if (process.platform === 'win32') {
-          await fs.copyFile(tempFilePath, this.stateFilePath);
-          // copyFile succeeded → the state IS persisted. Make the temp-file removal
-          // best-effort: a transient AV lock on the temp would otherwise throw here and
-          // fall through to the catch below, reporting "Failed to write state" (status:
-          // error) for a write that actually succeeded — a caller that retries/aborts on
-          // the false failure would act wrongly.
-          const tmp = tempFilePath;
-          tempFilePath = null;
-          await fs.unlink(tmp).catch((err) => {
-            logger.warn('[StateManager] Failed to remove temp file after copy fallback (write succeeded):', err);
-          });
-        } else {
-          throw renameErr;
-        }
+      // Atomic where the platform allows; on Windows a third-party lock on the target
+      // is retried before conceding to a non-atomic copy (see replaceFile).
+      const outcome = await replaceFile(tempFilePath, this.stateFilePath);
+      if (outcome === 'copied') {
+        logger.warn(
+          '[StateManager] State written via non-atomic copy: the rename was blocked by another ' +
+          'process holding the state file. A concurrent reader may observe a partial file.',
+        );
+        metrics.increment('state_write_non_atomic_total', 1);
+        // The state IS persisted, so removing the temp is best-effort: a transient AV lock
+        // on the temp would otherwise throw and report "Failed to write state" for a write
+        // that actually succeeded — a caller retrying or aborting on that would act wrongly.
+        const tmp = tempFilePath;
+        tempFilePath = null;
+        await fs.unlink(tmp).catch((err) => {
+          logger.warn('[StateManager] Failed to remove temp file after copy fallback (write succeeded):', err);
+        });
       }
       tempFilePath = null;
       await this.backupManager.cleanupOldBackups();
@@ -453,7 +452,7 @@ export class StateManager {
 
   // ==================== Embedding Server API ====================
 
-  public async getEmbeddingServer(): Promise<{ port: number; pid: number; startTime?: number; serverId: string; model?: string } | null> {
+  public async getEmbeddingServer(): Promise<{ port: number; pid: number; startTime?: number; serverId: string; model?: string; authSecret?: string } | null> {
     const state = await this.readState();
     return state.embeddingServer ?? null;
   }