feat(durability): atomic writes + registry lock for Theme N1 (#29)

- Add src/infra/fs/atomic-write.ts: temp-file write, fsync(fd), chmod before
  rename, rename, fsync(dir). Dir fsync gated on non-Windows per POSIX.
- Add src/infra/fs/registry-lock.ts: O_EXCL lock with PID-liveness probe and
  30 s wall-clock stale-lock heuristic. In-process callers block instead of
  reaping each other.
- Make secureWriteFile a thin wrapper over atomicWriteFile so every snapshot,
  current, and sessions.json write fsyncs.
- Add persistRegistryAtomic: single registry write path that reloads under
  the lock and unions account entries before writing.
- Route AccountService.persistRegistry and useAccount's direct saveRegistry
  call through the locked atomic path; no public method signature changes.
- Add src/tests/registry-durability.test.ts covering the rename-fails-mid-
  write window, in-process lock serialization, and stale-lock reaping.
- Release notes in releases/v0.1.25.md include a Durability section.

Refs: docs/future/17-ROADMAP.md Theme N1, docs/future/01-ARCHITECTURE.md §5.

Co-authored-by: NagyVikt <nagy.viktordp@gmail.com>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: 3 people

releases/v0.1.25.md

@@ -0,0 +1,66 @@
+# authmux v0.1.25
+
+## Added
+- `src/infra/fs/atomic-write.ts` — single durable file-write primitive with
+  fsync-before-rename and POSIX dir-fsync after rename, plus mode applied
+  before rename so 0600 files are never visible at a looser mode.
+- `src/infra/fs/registry-lock.ts` — advisory lock around `registry.json`
+  with PID-liveness probing plus a 30 s wall-clock stale-lock heuristic.
+- `persistRegistryAtomic` in `src/lib/accounts/registry.ts` is now the single
+  registry write path; it reloads under the lock and merges accounts so two
+  concurrent writers (daemon + interactive) no longer race-lose each other's
+  mutations.
+- `src/tests/registry-durability.test.ts` covers the SIGKILL-between-
+  writeFile-and-rename window and the stale-lock-reaping path.
+
+## Changed
+- `secureWriteFile` now delegates to `atomicWriteFile`; behavior is the same
+  (atomic temp+rename, 0600 perms) but every snapshot, `current`, and
+  `sessions.json` write now also fsyncs the file and the containing directory
+  before returning.
+- `AccountService.useAccount` no longer calls `saveRegistry` directly; all
+  registry writes go through the locked `persistRegistry` path.
+
+## Fixed
+- Half-written `registry.json` after SIGKILL or laptop sleep no longer
+  shadows the on-disk file: the rename is the commit point.
+- Concurrent `authmux daemon --watch` + `authmux use foo` mutations are
+  serialized through the registry lock.
+
+## Deprecated
+- None.
+
+## Removed
+- None.
+
+## Security
+- File mode 0600 is applied to the temp file BEFORE the rename, closing the
+  brief window where the previous chmod-after-rename path could expose
+  freshly-renamed files at the umask default.
+
+## Durability
+
+This release closes the two data-loss windows tracked under Theme N1 of
+`docs/future/17-ROADMAP.md`:
+
+1. **Partial-write corruption.** `atomicWriteFile` writes to a temp file,
+   `fsync`s the file fd, applies the final mode, renames over the target,
+   and (on POSIX) `fsync`s the containing directory. A power loss between
+   any of these steps leaves the previous content of the target intact.
+2. **Concurrent-writer lost mutations.** `withRegistryLock` serializes
+   writers; `persistRegistryAtomic` reloads the registry under the lock and
+   merges accounts before writing so neither writer silently discards the
+   other.
+
+Crash-safety guarantees promised after this release match the table in
+`docs/future/01-ARCHITECTURE.md` §5.3 rows 1, 2, and 4.
+
+`fsync` adds latency on spinning disks; on SSDs it is dominated by the
+network/parse work the CLI was already doing and is not user-visible. The
+dir-fsync is gated on `process.platform !== "win32"` because Windows does
+not allow opening a directory as a file.
+
+## Migration
+
+No migration is required. The on-disk layout of `registry.json`, `current`,
+`sessions.json`, and the per-account snapshot files is unchanged.

src/infra/fs/atomic-write.ts

@@ -0,0 +1,120 @@
+import fsp from "node:fs/promises";
+import path from "node:path";
+import crypto from "node:crypto";
+
+/**
+ * Default mode for atomically-written files. Callers that want world-readable
+ * content can override via the `mode` option (e.g. 0o644). For secrets we use
+ * 0o600 and apply it BEFORE rename so the final inode is never visible at a
+ * looser mode.
+ */
+export const DEFAULT_FILE_MODE = 0o600;
+
+const IS_WINDOWS = process.platform === "win32";
+
+export interface AtomicWriteOptions {
+  /** Final file mode applied to the temp file before the rename. Default 0o600. */
+  mode?: number;
+  /**
+   * Encoding for string payloads. Default "utf8". Buffer payloads ignore this.
+   */
+  encoding?: BufferEncoding;
+  /**
+   * Skip fsync on the directory after the rename. Default false. Set true only
+   * if the caller has already fsynced the dir (e.g. batch writes).
+   */
+  skipDirSync?: boolean;
+}
+
+/**
+ * Write `data` to `target` atomically.
+ *
+ * Order: mkdir -> open temp -> writeFile -> fsync(file) -> chmod -> close ->
+ * rename -> fsync(dir).
+ *
+ * fsync on the directory is the POSIX requirement to make a rename durable;
+ * we skip it on Windows where opening a directory as a file is not allowed.
+ *
+ * This is the single durable write path for authmux. `secureWriteFile`
+ * delegates here; callers should prefer this helper directly.
+ */
+export async function atomicWriteFile(
+  target: string,
+  data: string | Buffer,
+  options: AtomicWriteOptions = {},
+): Promise<void> {
+  const mode = options.mode ?? DEFAULT_FILE_MODE;
+  const encoding = options.encoding ?? "utf8";
+  const dir = path.dirname(target);
+  const base = path.basename(target);
+
+  await fsp.mkdir(dir, { recursive: true });
+
+  const suffix = `${process.pid}.${crypto.randomBytes(4).toString("hex")}.tmp`;
+  const tmp = path.join(dir, `.${base}.${suffix}`);
+
+  const handle = await fsp.open(tmp, "w", mode);
+  let renamed = false;
+  try {
+    if (typeof data === "string") {
+      await handle.writeFile(data, encoding);
+    } else {
+      await handle.writeFile(data);
+    }
+    // fsync the file fd so the bytes survive a power loss.
+    try {
+      await handle.sync();
+    } catch {
+      // Some filesystems (tmpfs, network mounts) reject fsync; not fatal.
+    }
+  } finally {
+    await handle.close();
+  }
+
+  // Apply final perms BEFORE rename so the final inode is never visible at a
+  // looser mode (chmod-after-rename has a tiny window where the file is at the
+  // umask default).
+  if (!IS_WINDOWS) {
+    try {
+      await fsp.chmod(tmp, mode);
+    } catch {
+      // best-effort
+    }
+  }
+
+  try {
+    await fsp.rename(tmp, target);
+    renamed = true;
+  } finally {
+    if (!renamed) {
+      // Clean up the temp file if the rename failed; do not mask the original
+      // error.
+      try {
+        await fsp.unlink(tmp);
+      } catch {
+        // ignore
+      }
+    }
+  }
+
+  // fsync the containing directory so the rename itself is durable on
+  // ext4/xfs etc. POSIX-only; Windows does not let us open a directory as a
+  // file. tmpfs / network filesystems may also reject this — non-fatal.
+  if (!IS_WINDOWS && !options.skipDirSync) {
+    let dirHandle: fsp.FileHandle | undefined;
+    try {
+      dirHandle = await fsp.open(dir, "r");
+      await dirHandle.sync();
+    } catch {
+      // best-effort durability hint; not all FS / OS allow dir fsync.
+    } finally {
+      if (dirHandle) {
+        try {
+          await dirHandle.close();
+        } catch {
+          // ignore
+        }
+      }
+    }
+  }
+}

src/infra/fs/registry-lock.ts

@@ -0,0 +1,189 @@
+import fs from "node:fs";
+import fsp from "node:fs/promises";
+import path from "node:path";
+
+import { resolveRegistryPath } from "../../lib/config/paths";
+
+/**
+ * Advisory lock for the accounts registry.
+ *
+ * Cooperating writers (interactive commands + daemon) call
+ * `withRegistryLock(fn)` to serialize their reload-merge-write sequence. The
+ * lock file is a sibling of `registry.json` named `registry.json.lock` and
+ * contains the locking process's PID plus an ISO timestamp.
+ *
+ * Stale-lock reaping: if `O_EXCL` create fails, we read the file. If the
+ * recorded PID is no longer alive, or the timestamp is older than
+ * `STALE_LOCK_MS`, we steal the lock by overwriting it with our own PID.
+ *
+ * The lock is best-effort within a single host; it does NOT protect against
+ * NFS / shared filesystems. Authmux state is per-user / local, so that is
+ * acceptable.
+ */
+
+export const LOCK_ACQUIRE_TIMEOUT_MS = 5000;
+export const STALE_LOCK_MS = 30_000;
+const INITIAL_BACKOFF_MS = 25;
+const MAX_BACKOFF_MS = 250;
+
+export interface LockOptions {
+  /** Override the default path used for the lock file (testing only). */
+  lockPath?: string;
+  /** Maximum wall-clock time to wait for the lock. Default 5000 ms. */
+  timeoutMs?: number;
+  /** Threshold past which a lock with a live-looking PID is still reaped. */
+  staleMs?: number;
+}
+
+interface LockPayload {
+  pid: number;
+  at: string;
+}
+
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function isAlive(pid: number): boolean {
+  if (!Number.isFinite(pid) || pid <= 0) return false;
+  try {
+    // Signal 0 is the standard POSIX liveness probe; on Windows Node maps it
+    // to a process-exists check too.
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code;
+    // EPERM means the process exists but we can't signal it (different user).
+    return code === "EPERM";
+  }
+}
+
+function parsePayload(raw: string): LockPayload | null {
+  try {
+    const parsed = JSON.parse(raw) as { pid?: unknown; at?: unknown };
+    const pid = typeof parsed.pid === "number" ? parsed.pid : NaN;
+    const at = typeof parsed.at === "string" ? parsed.at : "";
+    if (!Number.isFinite(pid)) return null;
+    return { pid, at };
+  } catch {
+    return null;
+  }
+}
+
+async function tryCreateExclusive(lockPath: string, payload: string): Promise<boolean> {
+  try {
+    // wx = write + O_EXCL + O_CREAT — fails atomically if the file exists.
+    // We deliberately do NOT go through atomicWriteFile here: an atomic
+    // temp+rename would defeat the O_EXCL semantics that make the lock work.
+    await fsp.writeFile(lockPath, payload, { flag: "wx", mode: 0o600 });
+    return true;
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code === "EEXIST") return false;
+    throw err;
+  }
+}
+
+async function readLock(lockPath: string): Promise<{ payload: LockPayload | null; mtimeMs: number } | null> {
+  try {
+    const [raw, stat] = await Promise.all([
+      fsp.readFile(lockPath, "utf8"),
+      fsp.stat(lockPath),
+    ]);
+    return { payload: parsePayload(raw), mtimeMs: stat.mtimeMs };
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code === "ENOENT") return null;
+    throw err;
+  }
+}
+
+function shouldReap(lock: { payload: LockPayload | null; mtimeMs: number }, staleMs: number): boolean {
+  if (!lock.payload) return true; // unparseable -> reap
+  // NOTE: do NOT reap on `pid === process.pid` — within a single Node process
+  // multiple async callers legitimately share a PID, and they must block each
+  // other rather than stomp the lock. Cross-process stale ownership is what
+  // the liveness probe and wall-clock heuristic below cover.
+  if (!isAlive(lock.payload.pid)) return true;
+  const ageMs = Date.now() - lock.mtimeMs;
+  return ageMs > staleMs;
+}
+
+async function acquire(lockPath: string, timeoutMs: number, staleMs: number): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  const payload = JSON.stringify({ pid: process.pid, at: new Date().toISOString() });
+  let backoff = INITIAL_BACKOFF_MS;
+
+  await fsp.mkdir(path.dirname(lockPath), { recursive: true });
+
+  // Loop until we either acquire or time out.
+  for (;;) {
+    if (await tryCreateExclusive(lockPath, payload)) return;
+
+    const current = await readLock(lockPath);
+    if (current && shouldReap(current, staleMs)) {
+      // Steal the lock. Use an unlink-then-create dance; if another process
+      // beat us to either step, we just loop again.
+      try {
+        await fsp.unlink(lockPath);
+      } catch (err) {
+        const code = (err as NodeJS.ErrnoException).code;
+        if (code !== "ENOENT") {
+          // Could not remove; fall through to retry.
+        }
+      }
+      if (await tryCreateExclusive(lockPath, payload)) return;
+    }
+
+    if (Date.now() >= deadline) {
+      throw new Error(
+        `registry lock at ${lockPath} held by pid=${current?.payload?.pid ?? "unknown"} ` +
+          `(timed out after ${timeoutMs} ms)`,
+      );
+    }
+
+    await delay(backoff);
+    backoff = Math.min(backoff * 2, MAX_BACKOFF_MS);
+  }
+}
+
+function release(lockPath: string): void {
+  try {
+    const raw = fs.readFileSync(lockPath, "utf8");
+    const parsed = parsePayload(raw);
+    if (parsed && parsed.pid !== process.pid) {
+      // Not ours anymore (we were preempted by a stale-reap). Leave it alone.
+      return;
+    }
+    fs.unlinkSync(lockPath);
+  } catch {
+    // best-effort; the next acquirer will reap a stale file if we crashed.
+  }
+}
+
+/**
+ * Run `fn` under the registry lock. Reload-merge-write logic lives in the
+ * callback so two writers cannot race-lose mutations.
+ */
+export async function withRegistryLock<T>(
+  fn: () => Promise<T>,
+  options: LockOptions = {},
+): Promise<T> {
+  const lockPath = options.lockPath ?? `${resolveRegistryPath()}.lock`;
+  const timeoutMs = options.timeoutMs ?? LOCK_ACQUIRE_TIMEOUT_MS;
+  const staleMs = options.staleMs ?? STALE_LOCK_MS;
+
+  await acquire(lockPath, timeoutMs, staleMs);
+
+  // Best-effort: drop the lock on abnormal process exit. We attach once; the
+  // listeners are idempotent (release() no-ops if the lock isn't ours).
+  const cleanup = () => release(lockPath);
+  process.once("exit", cleanup);
+
+  try {
+    return await fn();
+  } finally {
+    process.removeListener("exit", cleanup);
+    release(lockPath);
+  }
+}