fix(server): refuse to start a second server against a live data directory#8442

@@ -0,0 +1,210 @@
+/**
+ * One server per data directory.
+ *
+ * Two T3 Code servers pointed at the same `--base-dir` both open `state.sqlite`
+ * and both write `settings.json`, and they overwrite each other. The observed
+ * incident: a desktop app auto-updated to a newer server while the old one was
+ * still running, the new process found its port taken, silently bound a random
+ * one, and ran blind against shared state. The visible symptom was a settings
+ * toggle that would not stick — hours away from the actual cause.
+ *
+ * Nothing about that is detectable after the fact, so the fix is to refuse at
+ * startup. A second server against a held directory exits with one clear
+ * message instead of corrupting state.
+ *
+ * ## Why a pid file rather than `flock`
+ *
+ * An advisory `flock` is the better primitive: the kernel drops it when the
+ * holder dies, so a crashed server leaves nothing stale to clean up. Node has no
+ * binding for it, and adding a native dependency to the server for one lock is a
+ * worse trade than handling staleness here.
+ *
+ * So the lock is an atomically created file holding the owner's identity, and
+ * liveness is checked with signal 0. The tradeoff is honest: if a server is
+ * killed and its pid is later reused by an unrelated process, this refuses to
+ * start until the file is removed. That is the safe direction to fail, and the
+ * message names the file so recovery is one `rm`.
+ */
+import * as DateTime from "effect/DateTime";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import * as Schema from "effect/Schema";
+
+export const SERVER_LOCK_FILENAME = "server.lock";
+
+export const ServerLockHolder = Schema.Struct({
+  version: Schema.Literal(1),
+  pid: Schema.Int,
+  startedAt: Schema.String,
+  /** Absent until the server binds; the lock is taken before a port exists. */
+  port: Schema.optional(Schema.Int),
+});
+export type ServerLockHolder = typeof ServerLockHolder.Type;
+
+const ServerLockHolderFromJson = Schema.fromJsonString(ServerLockHolder);
+const decodeHolder = Schema.decodeUnknownOption(ServerLockHolderFromJson);
+const encodeHolder = Schema.encodeSync(ServerLockHolderFromJson);
+
+export class ServerAlreadyRunningError extends Schema.TaggedErrorClass<ServerAlreadyRunningError>()(
+  "ServerAlreadyRunningError",
+  {
+    stateDir: Schema.String,
+    lockPath: Schema.String,
+    holderPid: Schema.Int,
+    holderPort: Schema.optional(Schema.Int),
+    holderStartedAt: Schema.String,
+  },
+) {
+  override get message(): string {
+    const where =
+      this.holderPort === undefined
+        ? `pid ${this.holderPid}`
+        : `pid ${this.holderPid}, listening on port ${this.holderPort}`;
+    return [
+      "Another T3 Code server is already using this data directory.",
+      "",
+      `  data directory: ${this.stateDir}`,
+      `  held by:        ${where}`,
+      `  since:          ${this.holderStartedAt}`,
+      "",
+      "Two servers sharing one data directory overwrite each other's state.sqlite",
+      "and settings.json. Stop the running server, or start this one with a",
+      "different --base-dir.",
+      "",
+      `If that process is gone, remove ${this.lockPath} and start again.`,
+    ].join("\n");
+  }
+}
+
+export class ServerLockUnavailableError extends Schema.TaggedErrorClass<ServerLockUnavailableError>()(
+  "ServerLockUnavailableError",
+  {
+    lockPath: Schema.String,
+    reason: Schema.String,
+  },
+) {
+  override get message(): string {
+    return `Could not claim the server lock at ${this.lockPath}: ${this.reason}`;
+  }
+}
+
+/**
+ * Whether a pid is a live process.
+ *
+ * `EPERM` means it exists and belongs to someone else, which still counts — a
+ * server started under a different user is exactly the case that must not be
+ * trampled.
+ */
+export const processIsAlive = (pid: number): boolean => {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (cause) {
+    return (cause as NodeJS.ErrnoException).code === "EPERM";
+  }
+};
+
+const readHolder = Effect.fn("serverSingleton.readHolder")(function* (lockPath: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const raw = yield* fs.readFileString(lockPath).pipe(Effect.orElseSucceed(() => ""));
+  return Option.getOrUndefined(decodeHolder(raw));
+});
+
+/**
+ * Claims the directory, or explains who holds it.
+ *
+ * A lock file whose owner is gone — or which is unreadable, which means a
+ * half-written file from a crash mid-write — is reclaimed rather than treated as
+ * a permanent block. Reclaiming re-races the exclusive create, so two servers
+ * starting together still produce exactly one winner.
+ */
+const claimLock = Effect.fn("serverSingleton.claimLock")(function* (input: {
+  readonly stateDir: string;
+  readonly lockPath: string;
+  readonly startedAt: string;
+}) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const payload = encodeHolder({ version: 1, pid: process.pid, startedAt: input.startedAt });
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    yield* fs.makeDirectory(path.dirname(input.lockPath), { recursive: true }).pipe(Effect.ignore);
+    const created = yield* fs.writeFileString(input.lockPath, payload, { flag: "wx" }).pipe(
+      Effect.as(true),
+      Effect.orElseSucceed(() => false),
+    );
+    if (created) return undefined;
+
+    const holder = yield* readHolder(input.lockPath);
+    if (holder !== undefined && processIsAlive(holder.pid)) {
+      return new ServerAlreadyRunningError({
+        stateDir: input.stateDir,
+        lockPath: input.lockPath,
+        holderPid: holder.pid,
+        ...(holder.port === undefined ? {} : { holderPort: holder.port }),
+        holderStartedAt: holder.startedAt,
+      });
+    }
+    // Owner is gone, or the file is unreadable because a crash tore a write in
+    // half. Reclaim and re-race the exclusive create, which still yields one
+    // winner when two servers start together.
+    yield* fs.remove(input.lockPath).pipe(Effect.ignore);
+  }
+  return new ServerLockUnavailableError({
+    lockPath: input.lockPath,
+    reason: "the lock was repeatedly reclaimed by another starting server",
+  });
+});
+
+/** Releases only a lock this process still owns, so a reclaimer is never evicted. */
+export const releaseServerLock = Effect.fn("serverSingleton.release")(function* (lockPath: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const holder = yield* readHolder(lockPath);
+  if (holder !== undefined && holder.pid !== process.pid) return;
+  yield* fs.remove(lockPath).pipe(Effect.ignore);
+});
+
+/**
+ * Records the bound port on the lock we already hold.
+ *
+ * Only for the error message a *later* server prints: knowing the holder's port
+ * turns "something else is running" into an address the user can open. Failure
+ * is ignored — the lock's job is done once it is held.
+ */
+export const recordServerLockPort = Effect.fn("serverSingleton.recordPort")(function* (
+  lockPath: string,
+  port: number,
+) {
+  const fs = yield* FileSystem.FileSystem;
+  const holder = yield* readHolder(lockPath);
+  if (holder === undefined || holder.pid !== process.pid) return;
+  yield* fs.writeFileString(lockPath, encodeHolder({ ...holder, port })).pipe(Effect.ignore);

@@ -0,0 +1,210 @@
+/**
+ * One server per data directory.
+ *
+ * Two T3 Code servers pointed at the same `--base-dir` both open `state.sqlite`
+ * and both write `settings.json`, and they overwrite each other. The observed
+ * incident: a desktop app auto-updated to a newer server while the old one was
+ * still running, the new process found its port taken, silently bound a random
+ * one, and ran blind against shared state. The visible symptom was a settings
+ * toggle that would not stick — hours away from the actual cause.
+ *
+ * Nothing about that is detectable after the fact, so the fix is to refuse at
+ * startup. A second server against a held directory exits with one clear
+ * message instead of corrupting state.
+ *
+ * ## Why a pid file rather than `flock`
+ *
+ * An advisory `flock` is the better primitive: the kernel drops it when the
+ * holder dies, so a crashed server leaves nothing stale to clean up. Node has no
+ * binding for it, and adding a native dependency to the server for one lock is a
+ * worse trade than handling staleness here.
+ *
+ * So the lock is an atomically created file holding the owner's identity, and
+ * liveness is checked with signal 0. The tradeoff is honest: if a server is
+ * killed and its pid is later reused by an unrelated process, this refuses to
+ * start until the file is removed. That is the safe direction to fail, and the
+ * message names the file so recovery is one `rm`.
+ */
+import * as DateTime from "effect/DateTime";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import * as Schema from "effect/Schema";
+
+export const SERVER_LOCK_FILENAME = "server.lock";
+
+export const ServerLockHolder = Schema.Struct({
+  version: Schema.Literal(1),
+  pid: Schema.Int,
+  startedAt: Schema.String,
+  /** Absent until the server binds; the lock is taken before a port exists. */
+  port: Schema.optional(Schema.Int),
+});
+export type ServerLockHolder = typeof ServerLockHolder.Type;
+
+const ServerLockHolderFromJson = Schema.fromJsonString(ServerLockHolder);
+const decodeHolder = Schema.decodeUnknownOption(ServerLockHolderFromJson);
+const encodeHolder = Schema.encodeSync(ServerLockHolderFromJson);
+
+export class ServerAlreadyRunningError extends Schema.TaggedErrorClass<ServerAlreadyRunningError>()(
+  "ServerAlreadyRunningError",
+  {
+    stateDir: Schema.String,
+    lockPath: Schema.String,
+    holderPid: Schema.Int,
+    holderPort: Schema.optional(Schema.Int),
+    holderStartedAt: Schema.String,
+  },
+) {
+  override get message(): string {
+    const where =
+      this.holderPort === undefined
+        ? `pid ${this.holderPid}`
+        : `pid ${this.holderPid}, listening on port ${this.holderPort}`;
+    return [
+      "Another T3 Code server is already using this data directory.",
+      "",
+      `  data directory: ${this.stateDir}`,
+      `  held by:        ${where}`,
+      `  since:          ${this.holderStartedAt}`,
+      "",
+      "Two servers sharing one data directory overwrite each other's state.sqlite",
+      "and settings.json. Stop the running server, or start this one with a",
+      "different --base-dir.",
+      "",
+      `If that process is gone, remove ${this.lockPath} and start again.`,
+    ].join("\n");
+  }
+}
+
+export class ServerLockUnavailableError extends Schema.TaggedErrorClass<ServerLockUnavailableError>()(
+  "ServerLockUnavailableError",
+  {
+    lockPath: Schema.String,
+    reason: Schema.String,
+  },
+) {
+  override get message(): string {
+    return `Could not claim the server lock at ${this.lockPath}: ${this.reason}`;
+  }
+}
+
+/**
+ * Whether a pid is a live process.
+ *
+ * `EPERM` means it exists and belongs to someone else, which still counts — a
+ * server started under a different user is exactly the case that must not be
+ * trampled.
+ */
+export const processIsAlive = (pid: number): boolean => {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (cause) {
+    return (cause as NodeJS.ErrnoException).code === "EPERM";
+  }
+};
+
+const readHolder = Effect.fn("serverSingleton.readHolder")(function* (lockPath: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const raw = yield* fs.readFileString(lockPath).pipe(Effect.orElseSucceed(() => ""));
+  return Option.getOrUndefined(decodeHolder(raw));
+});
+
+/**
+ * Claims the directory, or explains who holds it.
+ *
+ * A lock file whose owner is gone — or which is unreadable, which means a
+ * half-written file from a crash mid-write — is reclaimed rather than treated as
+ * a permanent block. Reclaiming re-races the exclusive create, so two servers
+ * starting together still produce exactly one winner.
+ */
+const claimLock = Effect.fn("serverSingleton.claimLock")(function* (input: {
+  readonly stateDir: string;
+  readonly lockPath: string;
+  readonly startedAt: string;
+}) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const payload = encodeHolder({ version: 1, pid: process.pid, startedAt: input.startedAt });
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    yield* fs.makeDirectory(path.dirname(input.lockPath), { recursive: true }).pipe(Effect.ignore);
+    const created = yield* fs.writeFileString(input.lockPath, payload, { flag: "wx" }).pipe(
+      Effect.as(true),
+      Effect.orElseSucceed(() => false),
+    );
+    if (created) return undefined;
+
+    const holder = yield* readHolder(input.lockPath);
+    if (holder !== undefined && processIsAlive(holder.pid)) {
+      return new ServerAlreadyRunningError({
+        stateDir: input.stateDir,
+        lockPath: input.lockPath,
+        holderPid: holder.pid,
+        ...(holder.port === undefined ? {} : { holderPort: holder.port }),
+        holderStartedAt: holder.startedAt,
+      });
+    }
+    // Owner is gone, or the file is unreadable because a crash tore a write in
+    // half. Reclaim and re-race the exclusive create, which still yields one
+    // winner when two servers start together.
+    yield* fs.remove(input.lockPath).pipe(Effect.ignore);

@@ -0,0 +1,374 @@
+/**
+ * One server per data directory.
+ *
+ * Two T3 Code servers pointed at the same `--base-dir` both open `state.sqlite`
+ * and both write `settings.json`, and they overwrite each other. The observed
+ * incident: a desktop app auto-updated to a newer server while the old one was
+ * still running, the new process found its port taken, silently bound a random
+ * one, and ran blind against shared state. The visible symptom was a settings
+ * toggle that would not stick — hours away from the actual cause.
+ *
+ * Nothing about that is detectable after the fact, so the fix is to refuse at
+ * startup. A second server against a held directory exits with one clear
+ * message instead of corrupting state.
+ *
+ * ## Why a pid file rather than `flock`
+ *
+ * An advisory `flock` is the better primitive: the kernel drops it when the
+ * holder dies, so a crashed server leaves nothing stale to clean up. Node has no
+ * binding for it, and adding a native dependency to the server for one lock is a
+ * worse trade than handling staleness here.
+ *
+ * So the lock is an atomically created file holding the owner's identity, and
+ * liveness is checked with signal 0. The tradeoff is honest: if a server is
+ * killed and its pid is later reused by an unrelated process, this refuses to
+ * start until the file is removed. That is the safe direction to fail, and the
+ * message names the file so recovery is one `rm`.
+ *
+ * ## Upgrading from a pre-lock version
+ *
+ * A pre-lock server writes no `server.lock`, so the file alone cannot see one.
+ * It does persist `server-runtime.json` with its live pid though, so before
+ * claiming the directory a live legacy runtime state is read as a held lock
+ * and refused the same way. Otherwise the desktop auto-update incident this
+ * exists to prevent still happens once on upgrade day — the new server starts
+ * next to the old one against the same state.
+ */
+import * as Data from "effect/Data";
+import * as DateTime from "effect/DateTime";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import * as PlatformError from "effect/PlatformError";
+import * as Schedule from "effect/Schedule";
+import * as Schema from "effect/Schema";
+
+import { writeFileStringAtomically } from "./atomicWrite.ts";
+import { readPersistedServerRuntimeState } from "./serverRuntimeState.ts";
+
+export const SERVER_LOCK_FILENAME = "server.lock";
+export const SERVER_RUNTIME_STATE_FILENAME = "server-runtime.json";
+
+export const ServerLockHolder = Schema.Struct({
+  version: Schema.Literal(1),
+  pid: Schema.Int,
+  startedAt: Schema.String,
+  /** Absent until the server binds; the lock is taken before a port exists. */
+  port: Schema.optional(Schema.Int),
+});
+export type ServerLockHolder = typeof ServerLockHolder.Type;
+
+const ServerLockHolderFromJson = Schema.fromJsonString(ServerLockHolder);
+const decodeHolder = Schema.decodeUnknownOption(ServerLockHolderFromJson);
+const encodeHolder = Schema.encodeSync(ServerLockHolderFromJson);
+
+export class ServerAlreadyRunningError extends Schema.TaggedErrorClass<ServerAlreadyRunningError>()(
+  "ServerAlreadyRunningError",
+  {
+    stateDir: Schema.String,
+    lockPath: Schema.String,
+    holderPid: Schema.Int,
+    holderPort: Schema.optional(Schema.Int),
+    holderStartedAt: Schema.String,
+  },
+) {
+  override get message(): string {
+    const where =
+      this.holderPort === undefined
+        ? `pid ${this.holderPid}`
+        : `pid ${this.holderPid}, listening on port ${this.holderPort}`;
+    return [
+      "Another T3 Code server is already using this data directory.",
+      "",
+      `  data directory: ${this.stateDir}`,
+      `  held by:        ${where}`,
+      `  since:          ${this.holderStartedAt}`,
+      "",
+      "Two servers sharing one data directory overwrite each other's state.sqlite",
+      "and settings.json. Stop the running server, or start this one with a",
+      "different --base-dir.",
+      "",
+      `If that process is gone, remove ${this.lockPath} and start again.`,
+    ].join("\n");
+  }
+}
+
+export class ServerLockUnavailableError extends Schema.TaggedErrorClass<ServerLockUnavailableError>()(
+  "ServerLockUnavailableError",
+  {
+    lockPath: Schema.String,
+    attempts: Schema.Int,
+    cause: Schema.optional(Schema.Defect()),
+  },
+) {
+  override get message(): string {
+    return `Could not claim the server lock at ${this.lockPath} after ${this.attempts} attempts; another starting server kept reclaiming it.`;
+  }
+}
+
+/**
+ * Whether a pid is a live process.
+ *
+ * `EPERM` means it exists and belongs to someone else, which still counts — a
+ * server started under a different user is exactly the case that must not be
+ * trampled.
+ */
+export const processIsAlive = (pid: number): boolean => {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (cause) {
+    return (cause as NodeJS.ErrnoException).code === "EPERM";
+  }
+};
+
+const readHolder = Effect.fn("serverSingleton.readHolder")(function* (lockPath: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const raw = yield* fs
+    .readFileString(lockPath)
+    .pipe(
+      Effect.catch((error) =>
+        error.reason._tag === "NotFound" ? Effect.succeed("") : Effect.fail(error),
+      ),
+    );
+  return Option.getOrUndefined(decodeHolder(raw));
+});
+
+// A dead holder's lock is not unlinked outright: between one starter reading a
+// stale lock and another recreating it, an unconditional unlink would remove a
+// live successor's claim. Reclamation instead refreshes the file's mtime
+// `MAX_CLAIM_ATTEMPTS` times; only a file that stays the same dead content
+// across every attempt is removed, so a live recreation always survives. The
+// holder bumps the mtime once between attempts while it owns the lock, so no
+// sequence of slower starters can reclaim out from under it either — and a
+// dead holder still recycles its lock inside a second of startup time.
+const MAX_CLAIM_ATTEMPTS = 3;
+const RECLAIM_OBSERVATION_DELAY_MILLIS = 200;
+
+const isAlreadyExists = (error: PlatformError.PlatformError): boolean =>
+  error.reason._tag === "AlreadyExists";
+
+/**
+ * A pre-lock server is live against this directory. Failure-phase marker rather
+ * than an error: `serverRuntimeState.ts` already owns the file's decode-error
+ * type, and the refusal shown to the user is the same `ServerAlreadyRunningError`
+ * either way — `server.ts` converts this at the boundary where the config with
+ * the path lives.
+ */
+export class LiveLegacyServerRuntime extends Data.TaggedError("LiveLegacyServerRuntime")<{
+  readonly state: {
+    readonly pid: number;
+    readonly port: number;
+    readonly startedAt: string;
+  };
+}> {}
+
+/**
+ * Claims the directory, or explains who holds it.
+ *
+ * A lock file whose owner is gone is reclaimed rather than treated as a
+ * permanent block: a dead holder must not lock its own directory forever.
+ * Reclaiming re-races the exclusive create, so two servers starting together
+ * still produce exactly one winner.
+ */
+const claimLock = Effect.fn("serverSingleton.claimLock")(function* (input: {
+  readonly stateDir: string;
+  readonly lockPath: string;
+  readonly legacyRuntimeStatePath: string;
+  readonly startedAt: string;
+}) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const payload = encodeHolder({ version: 1, pid: process.pid, startedAt: input.startedAt });
+
+  // A pre-lock server writes no lock, so the file alone is blind to one — but
+  // it does persist its live pid in `server-runtime.json`. Refuse a live
+  // legacy runtime exactly like a live lock holder, before the lock is ever
+  // created; otherwise the upgrade that introduces this guard still starts
+  // next to the very server it is meant to replace. A dead legacy pid is
+  // ignored here: reclaim of its leftover lock is what removes the file.
+  const legacyState = yield* readPersistedServerRuntimeState(input.legacyRuntimeStatePath);
+  if (Option.isSome(legacyState) && processIsAlive(legacyState.value.pid)) {
+    return yield* new LiveLegacyServerRuntime({ state: legacyState.value });
+  }
+
+  yield* fs.makeDirectory(path.dirname(input.lockPath), { recursive: true });
+
+  // Counts how often this starter was forced to refresh a candidate stale lock
+  // before believing it is really dead (see the constants above).
+  let reclaimRefreshes = 0;
+  while (true) {
+    // A scheduler yield between attempts, so a reclaim observation round lets
+    // other starters (and the holder's heartbeat) run before this starter
+    // concludes a lock never changed. Real time only — resolvable under
+    // `TestClock`.
+    yield* Effect.yieldNow;
+    const created = yield* fs.writeFileString(input.lockPath, payload, { flag: "wx" }).pipe(
+      Effect.as(true),
+      Effect.catch((error) =>
+        isAlreadyExists(error) ? Effect.succeed(false) : Effect.fail(error),
+      ),
+    );
+    if (created) return undefined;
+
+    const holder = yield* readHolder(input.lockPath);
+    if (holder !== undefined && processIsAlive(holder.pid)) {
+      return new ServerAlreadyRunningError({
+        stateDir: input.stateDir,
+        lockPath: input.lockPath,
+        holderPid: holder.pid,
+        ...(holder.port === undefined ? {} : { holderPort: holder.port }),
+        holderStartedAt: holder.startedAt,
+      });
+    }
+
+    if (reclaimRefreshes >= MAX_CLAIM_ATTEMPTS) {
+      // The lock stayed untouched across every observation round, which only a
+      // dead holder allows — a live one's heartbeat always refreshes inside
+      // one round. Removing it now frees the directory for the winner of the
+      // next create, and cannot delete a successor's claim.
+      yield* fs.remove(input.lockPath, { force: true });
+      return new ServerLockUnavailableError({
+        lockPath: input.lockPath,
+        attempts: reclaimRefreshes,
+      });
+    }
+
+    // Owner is gone, or the file is unreadable because a crash tore a write
+    // in half. Never unlink unconditionally: between this starter's read and
+    // its remove, a successor can win the re-race and recreate its own live
+    // lock, and the unlink would delete that. Reclaim instead refreshes the
+    // file's mtime once per observation round and only removes it after it has
+    // stayed untouched across `MAX_CLAIM_ATTEMPTS` rounds — a live
+    // successor's heartbeat always refreshes inside that window, so the file
+    // this starter removes is provably still a dead one's. The wait lands in
+    // the *next* loop head's `Effect.yieldNow`, which keeps `claimLock`
+    // real-time-only so tests can drive it without a fake clock.
+    reclaimRefreshes += 1;
+    const now = yield* DateTime.now;
+    yield* fs.utimes(input.lockPath, DateTime.toDateUtc(now), DateTime.toDateUtc(now));
+  }
+});
+
+/**
+ * A live lock holder refreshes its claim's mtime once per reclaim-observation
+ * round while it owns the lock. Any starter mid-reclaim then sees the file
+ * change and backs off, so the holder's lock cannot be reclaimed from under it
+ * no matter how many starters race. Stops with the scope that holds the lock.
+ */
+const holdServerLock = Effect.fn("serverSingleton.hold")(function* (lockPath: string) {
+  const fs = yield* FileSystem.FileSystem;
+  // `Effect.repeat` with a spaced schedule (rather than `Effect.schedule`) so
+  // a failure wakes the loop on the next tick instead of terminating it: the
+  // holder must keep refreshing for as long as it owns the lock, through
+  // whatever transient filesystem errors come and go.
+  const reschedule = Schedule.spaced(RECLAIM_OBSERVATION_DELAY_MILLIS);
+  yield* Effect.forkScoped(
+    Effect.gen(function* () {
+      const holder = yield* readHolder(lockPath);
+      if (holder === undefined || holder.pid !== process.pid) return;
+      const now = yield* DateTime.now;
+      const date = DateTime.toDateUtc(now);
+      yield* fs.utimes(lockPath, date, date);
+    }).pipe(
+      Effect.repeat({ schedule: reschedule, while: () => true }),
+      Effect.catch(() => Effect.void),
+    ),
+  );
+});

@@ -794,7 +820,7 @@ const makeServerLayer = Layer.unwrap(
       Layer.provideMerge(runtimeServicesLive),
       Layer.provide(activationLayer),
       Layer.provideMerge(serverRelayBrokerTracingLayer),
-      Layer.provideMerge(HttpServerLive),
+      Layer.provideMerge(HttpServerLive.pipe(Layer.provide(ServerSingletonLive))),

@@ -0,0 +1,210 @@
+/**
+ * One server per data directory.
+ *
+ * Two T3 Code servers pointed at the same `--base-dir` both open `state.sqlite`
+ * and both write `settings.json`, and they overwrite each other. The observed
+ * incident: a desktop app auto-updated to a newer server while the old one was
+ * still running, the new process found its port taken, silently bound a random
+ * one, and ran blind against shared state. The visible symptom was a settings
+ * toggle that would not stick — hours away from the actual cause.
+ *
+ * Nothing about that is detectable after the fact, so the fix is to refuse at
+ * startup. A second server against a held directory exits with one clear
+ * message instead of corrupting state.
+ *
+ * ## Why a pid file rather than `flock`
+ *
+ * An advisory `flock` is the better primitive: the kernel drops it when the
+ * holder dies, so a crashed server leaves nothing stale to clean up. Node has no
+ * binding for it, and adding a native dependency to the server for one lock is a
+ * worse trade than handling staleness here.
+ *
+ * So the lock is an atomically created file holding the owner's identity, and
+ * liveness is checked with signal 0. The tradeoff is honest: if a server is
+ * killed and its pid is later reused by an unrelated process, this refuses to
+ * start until the file is removed. That is the safe direction to fail, and the
+ * message names the file so recovery is one `rm`.
+ */
+import * as DateTime from "effect/DateTime";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import * as Schema from "effect/Schema";
+
+export const SERVER_LOCK_FILENAME = "server.lock";
+
+export const ServerLockHolder = Schema.Struct({
+  version: Schema.Literal(1),
+  pid: Schema.Int,
+  startedAt: Schema.String,
+  /** Absent until the server binds; the lock is taken before a port exists. */
+  port: Schema.optional(Schema.Int),
+});
+export type ServerLockHolder = typeof ServerLockHolder.Type;
+
+const ServerLockHolderFromJson = Schema.fromJsonString(ServerLockHolder);
+const decodeHolder = Schema.decodeUnknownOption(ServerLockHolderFromJson);
+const encodeHolder = Schema.encodeSync(ServerLockHolderFromJson);
+
+export class ServerAlreadyRunningError extends Schema.TaggedErrorClass<ServerAlreadyRunningError>()(
+  "ServerAlreadyRunningError",
+  {
+    stateDir: Schema.String,
+    lockPath: Schema.String,
+    holderPid: Schema.Int,
+    holderPort: Schema.optional(Schema.Int),
+    holderStartedAt: Schema.String,
+  },
+) {
+  override get message(): string {
+    const where =
+      this.holderPort === undefined
+        ? `pid ${this.holderPid}`
+        : `pid ${this.holderPid}, listening on port ${this.holderPort}`;
+    return [
+      "Another T3 Code server is already using this data directory.",
+      "",
+      `  data directory: ${this.stateDir}`,
+      `  held by:        ${where}`,
+      `  since:          ${this.holderStartedAt}`,
+      "",
+      "Two servers sharing one data directory overwrite each other's state.sqlite",
+      "and settings.json. Stop the running server, or start this one with a",
+      "different --base-dir.",
+      "",
+      `If that process is gone, remove ${this.lockPath} and start again.`,
+    ].join("\n");
+  }
+}
+
+export class ServerLockUnavailableError extends Schema.TaggedErrorClass<ServerLockUnavailableError>()(
+  "ServerLockUnavailableError",
+  {
+    lockPath: Schema.String,
+    reason: Schema.String,
+  },
+) {
+  override get message(): string {
+    return `Could not claim the server lock at ${this.lockPath}: ${this.reason}`;

@@ -0,0 +1,210 @@
+/**
+ * One server per data directory.
+ *
+ * Two T3 Code servers pointed at the same `--base-dir` both open `state.sqlite`
+ * and both write `settings.json`, and they overwrite each other. The observed
+ * incident: a desktop app auto-updated to a newer server while the old one was
+ * still running, the new process found its port taken, silently bound a random
+ * one, and ran blind against shared state. The visible symptom was a settings
+ * toggle that would not stick — hours away from the actual cause.
+ *
+ * Nothing about that is detectable after the fact, so the fix is to refuse at
+ * startup. A second server against a held directory exits with one clear
+ * message instead of corrupting state.
+ *
+ * ## Why a pid file rather than `flock`
+ *
+ * An advisory `flock` is the better primitive: the kernel drops it when the
+ * holder dies, so a crashed server leaves nothing stale to clean up. Node has no
+ * binding for it, and adding a native dependency to the server for one lock is a
+ * worse trade than handling staleness here.
+ *
+ * So the lock is an atomically created file holding the owner's identity, and
+ * liveness is checked with signal 0. The tradeoff is honest: if a server is
+ * killed and its pid is later reused by an unrelated process, this refuses to
+ * start until the file is removed. That is the safe direction to fail, and the
+ * message names the file so recovery is one `rm`.
+ */
+import * as DateTime from "effect/DateTime";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import * as Schema from "effect/Schema";
+
+export const SERVER_LOCK_FILENAME = "server.lock";
+
+export const ServerLockHolder = Schema.Struct({
+  version: Schema.Literal(1),
+  pid: Schema.Int,
+  startedAt: Schema.String,
+  /** Absent until the server binds; the lock is taken before a port exists. */
+  port: Schema.optional(Schema.Int),
+});
+export type ServerLockHolder = typeof ServerLockHolder.Type;
+
+const ServerLockHolderFromJson = Schema.fromJsonString(ServerLockHolder);
+const decodeHolder = Schema.decodeUnknownOption(ServerLockHolderFromJson);
+const encodeHolder = Schema.encodeSync(ServerLockHolderFromJson);
+
+export class ServerAlreadyRunningError extends Schema.TaggedErrorClass<ServerAlreadyRunningError>()(
+  "ServerAlreadyRunningError",
+  {
+    stateDir: Schema.String,
+    lockPath: Schema.String,
+    holderPid: Schema.Int,
+    holderPort: Schema.optional(Schema.Int),
+    holderStartedAt: Schema.String,
+  },
+) {
+  override get message(): string {
+    const where =
+      this.holderPort === undefined
+        ? `pid ${this.holderPid}`
+        : `pid ${this.holderPid}, listening on port ${this.holderPort}`;
+    return [
+      "Another T3 Code server is already using this data directory.",
+      "",
+      `  data directory: ${this.stateDir}`,
+      `  held by:        ${where}`,
+      `  since:          ${this.holderStartedAt}`,
+      "",
+      "Two servers sharing one data directory overwrite each other's state.sqlite",
+      "and settings.json. Stop the running server, or start this one with a",
+      "different --base-dir.",
+      "",
+      `If that process is gone, remove ${this.lockPath} and start again.`,
+    ].join("\n");
+  }
+}
+
+export class ServerLockUnavailableError extends Schema.TaggedErrorClass<ServerLockUnavailableError>()(
+  "ServerLockUnavailableError",
+  {
+    lockPath: Schema.String,
+    reason: Schema.String,
+  },
+) {
+  override get message(): string {
+    return `Could not claim the server lock at ${this.lockPath}: ${this.reason}`;
+  }
+}
+
+/**
+ * Whether a pid is a live process.
+ *
+ * `EPERM` means it exists and belongs to someone else, which still counts — a
+ * server started under a different user is exactly the case that must not be
+ * trampled.
+ */
+export const processIsAlive = (pid: number): boolean => {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (cause) {
+    return (cause as NodeJS.ErrnoException).code === "EPERM";
+  }
+};
+
+const readHolder = Effect.fn("serverSingleton.readHolder")(function* (lockPath: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const raw = yield* fs.readFileString(lockPath).pipe(Effect.orElseSucceed(() => ""));
+  return Option.getOrUndefined(decodeHolder(raw));
+});
+
+/**
+ * Claims the directory, or explains who holds it.
+ *
+ * A lock file whose owner is gone — or which is unreadable, which means a
+ * half-written file from a crash mid-write — is reclaimed rather than treated as
+ * a permanent block. Reclaiming re-races the exclusive create, so two servers
+ * starting together still produce exactly one winner.
+ */
+const claimLock = Effect.fn("serverSingleton.claimLock")(function* (input: {
+  readonly stateDir: string;
+  readonly lockPath: string;
+  readonly startedAt: string;
+}) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const payload = encodeHolder({ version: 1, pid: process.pid, startedAt: input.startedAt });
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    yield* fs.makeDirectory(path.dirname(input.lockPath), { recursive: true }).pipe(Effect.ignore);
+    const created = yield* fs.writeFileString(input.lockPath, payload, { flag: "wx" }).pipe(
+      Effect.as(true),
+      Effect.orElseSucceed(() => false),
+    );

@@ -0,0 +1,465 @@
+/**
+ * One server per data directory.
+ *
+ * Two T3 Code servers pointed at the same `--base-dir` both open `state.sqlite`
+ * and both write `settings.json`, and they overwrite each other. The observed
+ * incident: a desktop app auto-updated to a newer server while the old one was
+ * still running, the new process found its port taken, silently bound a random
+ * one, and ran blind against shared state. The visible symptom was a settings
+ * toggle that would not stick — hours away from the actual cause.
+ *
+ * Nothing about that is detectable after the fact, so the fix is to refuse at
+ * startup. A second server against a held directory exits with one clear
+ * message instead of corrupting state.
+ *
+ * ## Why a pid file rather than `flock`
+ *
+ * An advisory `flock` is the better primitive: the kernel drops it when the
+ * holder dies, so a crashed server leaves nothing stale to clean up. Node has no
+ * binding for it, and adding a native dependency to the server for one lock is a
+ * worse trade than handling staleness here.
+ *
+ * So the lock is an atomically created file holding the owner's identity, and
+ * liveness is checked with signal 0. The tradeoff is honest: if a server is
+ * killed and its pid is later reused by an unrelated process, this refuses to
+ * start until the file is removed. That is the safe direction to fail, and the
+ * message names the file so recovery is one `rm`.
+ *
+ * ## Upgrading from a pre-lock version
+ *
+ * A pre-lock server writes no `server.lock`, so the file alone cannot see one.
+ * It does persist `server-runtime.json` with its live pid though, so before
+ * claiming the directory a live legacy runtime state is read as a held lock
+ * and refused the same way. Otherwise the desktop auto-update incident this
+ * exists to prevent still happens once on upgrade day — the new server starts
+ * next to the old one against the same state.
+ */
+import * as Data from "effect/Data";
+import * as DateTime from "effect/DateTime";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import * as PlatformError from "effect/PlatformError";
+import * as Schedule from "effect/Schedule";
+import * as Schema from "effect/Schema";
+
+import { writeFileStringAtomically } from "./atomicWrite.ts";
+import { readPersistedServerRuntimeState } from "./serverRuntimeState.ts";
+
+export const SERVER_LOCK_FILENAME = "server.lock";
+export const SERVER_RUNTIME_STATE_FILENAME = "server-runtime.json";
+
+export const ServerLockHolder = Schema.Struct({
+  version: Schema.Literal(1),
+  pid: Schema.Int,
+  startedAt: Schema.String,
+  /** Absent until the server binds; the lock is taken before a port exists. */
+  port: Schema.optional(Schema.Int),
+});
+export type ServerLockHolder = typeof ServerLockHolder.Type;
+
+const ServerLockHolderFromJson = Schema.fromJsonString(ServerLockHolder);
+const decodeHolder = Schema.decodeUnknownOption(ServerLockHolderFromJson);
+const encodeHolder = Schema.encodeSync(ServerLockHolderFromJson);
+
+export class ServerAlreadyRunningError extends Schema.TaggedError<ServerAlreadyRunningError>()(
+  "ServerAlreadyRunningError",
+  {
+    stateDir: Schema.String,
+    lockPath: Schema.String,
+    holderPid: Schema.Int,
+    holderPort: Schema.optional(Schema.Int),
+    holderStartedAt: Schema.String,
+  },
+) {
+  override get message(): string {
+    const where =
+      this.holderPort === undefined
+        ? `pid ${this.holderPid}`
+        : `pid ${this.holderPid}, listening on port ${this.holderPort}`;
+    return [
+      "Another T3 Code server is already using this data directory.",
+      "",
+      `  data directory: ${this.stateDir}`,
+      `  held by:        ${where}`,
+      `  since:          ${this.holderStartedAt}`,
+      "",
+      "Two servers sharing one data directory overwrite each other's state.sqlite",
+      "and settings.json. Stop the running server, or start this one with a",
+      "different --base-dir.",
+      "",
+      `If that process is gone, remove ${this.lockPath} and start again.`,
+    ].join("\n");
+  }
+}
+
+export class ServerLockUnavailableError extends Schema.TaggedError<ServerLockUnavailableError>()(
+  "ServerLockUnavailableError",
+  {
+    lockPath: Schema.String,
+    attempts: Schema.Int,
+    cause: Schema.optional(Schema.Defect()),
+  },
+) {
+  override get message(): string {
+    return `Could not claim the server lock at ${this.lockPath} after ${this.attempts} attempts; another starting server kept reclaiming it.`;
+  }
+}
+
+// How many reclaim-and-retry rounds against a confirmed-dead lock a starter
+// tolerates before concluding something else keeps recreating it: nothing a
+// real dead holder produces, everything a permission wall or a competing
+// starter produces.
+const MAX_RECLAIM_CYCLES = 3;
+
+/**
+ * Whether a pid is a live process.
+ *
+ * `EPERM` means it exists and belongs to someone else, which still counts — a
+ * server started under a different user is exactly the case that must not be
+ * trampled.
+ */
+export const processIsAlive = (pid: number): boolean => {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (cause) {
+    return (cause as NodeJS.ErrnoException).code === "EPERM";
+  }
+};
+
+const readHolder = Effect.fn("serverSingleton.readHolder")(function* (lockPath: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const raw = yield* fs
+    .readFileString(lockPath)
+    .pipe(
+      Effect.catch((error) =>
+        error.reason._tag === "NotFound" ? Effect.succeed("") : Effect.fail(error),
+      ),
+    );
+  return Option.getOrUndefined(decodeHolder(raw));
+});
+
+// A dead holder's lock is not unlinked outright: between one starter reading a
+// stale lock and another recreating it, an unconditional unlink would remove a
+// live successor's claim. Reclamation instead refreshes the file's mtime
+// `MAX_CLAIM_ATTEMPTS` times; only a file that stays the same dead content
+// across every attempt is removed, so a live recreation always survives. The
+// holder bumps the mtime once between attempts while it owns the lock, so no
+// sequence of slower starters can reclaim out from under it either — and a
+// dead holder still recycles its lock inside a second of startup time.
+const MAX_CLAIM_ATTEMPTS = 3;
+const RECLAIM_OBSERVATION_DELAY_MILLIS = 200;
+
+const isAlreadyExists = (error: PlatformError.PlatformError): boolean =>
+  error.reason._tag === "AlreadyExists";
+
+const isNotFound = (error: PlatformError.PlatformError): boolean => error.reason._tag === "NotFound";
+
+const reclaimGatePath = (lockPath: string): string => `${lockPath}.reclaim`;
+
+/**
+ * Serialize stale-lock takeover. Two reclaimers can both finish the last
+ * stale read, then both `remove` — the second deletes the first's fresh
+ * claim. An exclusive gate file makes exactly one reclaimer allowed to
+ * touch `server.lock`; everyone else backs off and retries the create.
+ */
+const takeReclaimGate = Effect.fn("serverSingleton.takeReclaimGate")(function* (lockPath: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const gatePath = reclaimGatePath(lockPath);
+  const existing = yield* fs.readFileString(gatePath).pipe(
+    Effect.catch((error) => (isNotFound(error) ? Effect.succeed(undefined) : Effect.fail(error))),
+  );
+  if (existing !== undefined) {
+    const gatePid = Number.parseInt(existing.trim(), 10);
+    if (processIsAlive(gatePid)) return false;
+    yield* fs.remove(gatePath, { force: true }).pipe(Effect.ignore);

@@ -0,0 +1,401 @@
+/**
+ * One server per data directory.
+ *
+ * Two T3 Code servers pointed at the same `--base-dir` both open `state.sqlite`
+ * and both write `settings.json`, and they overwrite each other. The observed
+ * incident: a desktop app auto-updated to a newer server while the old one was
+ * still running, the new process found its port taken, silently bound a random
+ * one, and ran blind against shared state. The visible symptom was a settings
+ * toggle that would not stick — hours away from the actual cause.
+ *
+ * Nothing about that is detectable after the fact, so the fix is to refuse at
+ * startup. A second server against a held directory exits with one clear
+ * message instead of corrupting state.
+ *
+ * ## Why a pid file rather than `flock`
+ *
+ * An advisory `flock` is the better primitive: the kernel drops it when the
+ * holder dies, so a crashed server leaves nothing stale to clean up. Node has no
+ * binding for it, and adding a native dependency to the server for one lock is a
+ * worse trade than handling staleness here.
+ *
+ * So the lock is an atomically created file holding the owner's identity, and
+ * liveness is checked with signal 0. The tradeoff is honest: if a server is
+ * killed and its pid is later reused by an unrelated process, this refuses to
+ * start until the file is removed. That is the safe direction to fail, and the
+ * message names the file so recovery is one `rm`.
+ *
+ * ## Upgrading from a pre-lock version
+ *
+ * A pre-lock server writes no `server.lock`, so the file alone cannot see one.
+ * It does persist `server-runtime.json` with its live pid though, so before
+ * claiming the directory a live legacy runtime state is read as a held lock
+ * and refused the same way. Otherwise the desktop auto-update incident this
+ * exists to prevent still happens once on upgrade day — the new server starts
+ * next to the old one against the same state.
+ */
+import * as Data from "effect/Data";
+import * as DateTime from "effect/DateTime";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import * as PlatformError from "effect/PlatformError";
+import * as Schedule from "effect/Schedule";
+import * as Schema from "effect/Schema";
+
+import { writeFileStringAtomically } from "./atomicWrite.ts";
+import { readPersistedServerRuntimeState } from "./serverRuntimeState.ts";
+
+export const SERVER_LOCK_FILENAME = "server.lock";
+export const SERVER_RUNTIME_STATE_FILENAME = "server-runtime.json";
+
+export const ServerLockHolder = Schema.Struct({
+  version: Schema.Literal(1),
+  pid: Schema.Int,
+  startedAt: Schema.String,
+  /** Absent until the server binds; the lock is taken before a port exists. */
+  port: Schema.optional(Schema.Int),
+});
+export type ServerLockHolder = typeof ServerLockHolder.Type;
+
+const ServerLockHolderFromJson = Schema.fromJsonString(ServerLockHolder);
+const decodeHolder = Schema.decodeUnknownOption(ServerLockHolderFromJson);
+const encodeHolder = Schema.encodeSync(ServerLockHolderFromJson);
+
+export class ServerAlreadyRunningError extends Schema.TaggedError<ServerAlreadyRunningError>()(
+  "ServerAlreadyRunningError",
+  {
+    stateDir: Schema.String,
+    lockPath: Schema.String,
+    holderPid: Schema.Int,
+    holderPort: Schema.optional(Schema.Int),
+    holderStartedAt: Schema.String,
+  },
+) {
+  override get message(): string {
+    const where =
+      this.holderPort === undefined
+        ? `pid ${this.holderPid}`
+        : `pid ${this.holderPid}, listening on port ${this.holderPort}`;
+    return [
+      "Another T3 Code server is already using this data directory.",
+      "",
+      `  data directory: ${this.stateDir}`,
+      `  held by:        ${where}`,
+      `  since:          ${this.holderStartedAt}`,
+      "",
+      "Two servers sharing one data directory overwrite each other's state.sqlite",
+      "and settings.json. Stop the running server, or start this one with a",
+      "different --base-dir.",
+      "",
+      `If that process is gone, remove ${this.lockPath} and start again.`,
+    ].join("\n");
+  }
+}
+
+export class ServerLockUnavailableError extends Schema.TaggedError<ServerLockUnavailableError>()(
+  "ServerLockUnavailableError",
+  {
+    lockPath: Schema.String,
+    attempts: Schema.Int,
+    cause: Schema.optional(Schema.Defect()),
+  },
+) {
+  override get message(): string {
+    return `Could not claim the server lock at ${this.lockPath} after ${this.attempts} attempts; another starting server kept reclaiming it.`;
+  }
+}
+
+// How many reclaim-and-retry rounds against a confirmed-dead lock a starter
+// tolerates before concluding something else keeps recreating it: nothing a
+// real dead holder produces, everything a permission wall or a competing
+// starter produces.
+const MAX_RECLAIM_CYCLES = 3;
+
+/**
+ * Whether a pid is a live process.
+ *
+ * `EPERM` means it exists and belongs to someone else, which still counts — a
+ * server started under a different user is exactly the case that must not be
+ * trampled.
+ */
+export const processIsAlive = (pid: number): boolean => {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (cause) {
+    return (cause as NodeJS.ErrnoException).code === "EPERM";
+  }
+};
+
+const readHolder = Effect.fn("serverSingleton.readHolder")(function* (lockPath: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const raw = yield* fs
+    .readFileString(lockPath)
+    .pipe(
+      Effect.catch((error) =>
+        error.reason._tag === "NotFound" ? Effect.succeed("") : Effect.fail(error),
+      ),
+    );
+  return Option.getOrUndefined(decodeHolder(raw));
+});
+
+// A dead holder's lock is not unlinked outright: between one starter reading a
+// stale lock and another recreating it, an unconditional unlink would remove a
+// live successor's claim. Reclamation instead refreshes the file's mtime
+// `MAX_CLAIM_ATTEMPTS` times; only a file that stays the same dead content
+// across every attempt is removed, so a live recreation always survives. The
+// holder bumps the mtime once between attempts while it owns the lock, so no
+// sequence of slower starters can reclaim out from under it either — and a
+// dead holder still recycles its lock inside a second of startup time.
+const MAX_CLAIM_ATTEMPTS = 3;
+const RECLAIM_OBSERVATION_DELAY_MILLIS = 200;
+
+const isAlreadyExists = (error: PlatformError.PlatformError): boolean =>
+  error.reason._tag === "AlreadyExists";
+
+/**
+ * A pre-lock server is live against this directory. Failure-phase marker rather
+ * than an error: `serverRuntimeState.ts` already owns the file's decode-error
+ * type, and the refusal shown to the user is the same `ServerAlreadyRunningError`
+ * either way — `server.ts` converts this at the boundary where the config with
+ * the path lives.
+ */
+export class LiveLegacyServerRuntime extends Data.TaggedError("LiveLegacyServerRuntime")<{
+  readonly state: {
+    readonly pid: number;
+    readonly port: number;
+    readonly startedAt: string;
+  };
+}> {}
+
+/**
+ * Claims the directory, or explains who holds it.
+ *
+ * A lock file whose owner is gone is reclaimed rather than treated as a
+ * permanent block: a dead holder must not lock its own directory forever.
+ * Reclaiming re-races the exclusive create, so two servers starting together
+ * still produce exactly one winner.
+ */
+const claimLock = Effect.fn("serverSingleton.claimLock")(function* (input: {
+  readonly stateDir: string;
+  readonly lockPath: string;
+  readonly legacyRuntimeStatePath: string;
+  readonly startedAt: string;
+}) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const payload = encodeHolder({ version: 1, pid: process.pid, startedAt: input.startedAt });
+
+  // A pre-lock server writes no lock, so the file alone is blind to one — but
+  // it does persist its live pid in `server-runtime.json`. Refuse a live
+  // legacy runtime exactly like a live lock holder, before the lock is ever
+  // created; otherwise the upgrade that introduces this guard still starts
+  // next to the very server it is meant to replace. A dead legacy pid is
+  // ignored here: reclaim of its leftover lock is what removes the file.
+  const legacyState = yield* readPersistedServerRuntimeState(input.legacyRuntimeStatePath);
+  if (Option.isSome(legacyState) && processIsAlive(legacyState.value.pid)) {
+    return yield* new LiveLegacyServerRuntime({ state: legacyState.value });
+  }
+
+  yield* fs.makeDirectory(path.dirname(input.lockPath), { recursive: true });
+
+  // Counts how often this starter was forced to refresh a candidate stale lock
+  // before believing it is really dead, and how often a confirmed-dead lock
+  // bounced it back to another round (see the constants above).
+  let reclaimRefreshes = 0;
+  let reclaimCycles = 0;
+  while (true) {
+    // A scheduler yield between attempts, so a reclaim observation round lets
+    // other starters (and the holder's heartbeat) run before this starter
+    // concludes a lock never changed. Real time only — resolvable under
+    // `TestClock`.
+    yield* Effect.yieldNow;
+    const created = yield* fs.writeFileString(input.lockPath, payload, { flag: "wx" }).pipe(
+      Effect.as(true),
+      Effect.catch((error) =>
+        isAlreadyExists(error) ? Effect.succeed(false) : Effect.fail(error),
+      ),
+    );
+    if (created) return undefined;
+
+    const holder = yield* readHolder(input.lockPath);
+    if (holder !== undefined && processIsAlive(holder.pid)) {
+      return new ServerAlreadyRunningError({
+        stateDir: input.stateDir,
+        lockPath: input.lockPath,
+        holderPid: holder.pid,
+        ...(holder.port === undefined ? {} : { holderPort: holder.port }),
+        holderStartedAt: holder.startedAt,
+      });
+    }
+
+    // The read found no live owner — either a decodeable dead holder, or
+    // `undefined` because the file is missing (another starter mid-reclaim)
+    // or undecodable (a crash tore a write in half). Never unlink after one
+    // read: between this starter's read and its remove, a successor can win
+    // the re-race and recreate its own live lock, and the unlink would delete
+    // that. The candidate is mtime-refreshed and re-observed across
+    // `MAX_CLAIM_ATTEMPTS` rounds, and only a file that stayed untouched
+    // through every round is removed — a live successor's heartbeat always
+    // refreshes inside one round, so the file a reclaimer finally removes is
+    // provably still dead. The wait lands in the *next* loop head's
+    // `Effect.yieldNow`, which keeps `claimLock` real-time-only so tests can
+    // drive it without a fake clock.
+    if (reclaimRefreshes >= MAX_CLAIM_ATTEMPTS) {
+      // Removing frees the directory, and the create is retried on the next
+      // pass: a cleanly restarted server after a crash claims its directory
+      // here, not on a later manual retry. Bounded, so a lock another starter
+      // keeps recreating (or a permissions wall keeps failing to remove for)
+      // still surfaces as itself.
+      yield* fs.remove(input.lockPath, { force: true });

@@ -0,0 +1,210 @@
+/**
+ * One server per data directory.
+ *
+ * Two T3 Code servers pointed at the same `--base-dir` both open `state.sqlite`
+ * and both write `settings.json`, and they overwrite each other. The observed
+ * incident: a desktop app auto-updated to a newer server while the old one was
+ * still running, the new process found its port taken, silently bound a random
+ * one, and ran blind against shared state. The visible symptom was a settings
+ * toggle that would not stick — hours away from the actual cause.
+ *
+ * Nothing about that is detectable after the fact, so the fix is to refuse at
+ * startup. A second server against a held directory exits with one clear
+ * message instead of corrupting state.
+ *
+ * ## Why a pid file rather than `flock`
+ *
+ * An advisory `flock` is the better primitive: the kernel drops it when the
+ * holder dies, so a crashed server leaves nothing stale to clean up. Node has no
+ * binding for it, and adding a native dependency to the server for one lock is a
+ * worse trade than handling staleness here.
+ *
+ * So the lock is an atomically created file holding the owner's identity, and
+ * liveness is checked with signal 0. The tradeoff is honest: if a server is
+ * killed and its pid is later reused by an unrelated process, this refuses to
+ * start until the file is removed. That is the safe direction to fail, and the
+ * message names the file so recovery is one `rm`.
+ */
+import * as DateTime from "effect/DateTime";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import * as Schema from "effect/Schema";
+
+export const SERVER_LOCK_FILENAME = "server.lock";
+
+export const ServerLockHolder = Schema.Struct({
+  version: Schema.Literal(1),
+  pid: Schema.Int,
+  startedAt: Schema.String,
+  /** Absent until the server binds; the lock is taken before a port exists. */
+  port: Schema.optional(Schema.Int),
+});
+export type ServerLockHolder = typeof ServerLockHolder.Type;
+
+const ServerLockHolderFromJson = Schema.fromJsonString(ServerLockHolder);
+const decodeHolder = Schema.decodeUnknownOption(ServerLockHolderFromJson);
+const encodeHolder = Schema.encodeSync(ServerLockHolderFromJson);
+
+export class ServerAlreadyRunningError extends Schema.TaggedErrorClass<ServerAlreadyRunningError>()(
+  "ServerAlreadyRunningError",
+  {
+    stateDir: Schema.String,
+    lockPath: Schema.String,
+    holderPid: Schema.Int,
+    holderPort: Schema.optional(Schema.Int),
+    holderStartedAt: Schema.String,
+  },
+) {
+  override get message(): string {
+    const where =
+      this.holderPort === undefined
+        ? `pid ${this.holderPid}`
+        : `pid ${this.holderPid}, listening on port ${this.holderPort}`;
+    return [
+      "Another T3 Code server is already using this data directory.",
+      "",
+      `  data directory: ${this.stateDir}`,
+      `  held by:        ${where}`,
+      `  since:          ${this.holderStartedAt}`,
+      "",
+      "Two servers sharing one data directory overwrite each other's state.sqlite",
+      "and settings.json. Stop the running server, or start this one with a",
+      "different --base-dir.",
+      "",
+      `If that process is gone, remove ${this.lockPath} and start again.`,
+    ].join("\n");
+  }
+}
+
+export class ServerLockUnavailableError extends Schema.TaggedErrorClass<ServerLockUnavailableError>()(
+  "ServerLockUnavailableError",
+  {
+    lockPath: Schema.String,
+    reason: Schema.String,
+  },
+) {
+  override get message(): string {
+    return `Could not claim the server lock at ${this.lockPath}: ${this.reason}`;
+  }
+}
+
+/**
+ * Whether a pid is a live process.
+ *
+ * `EPERM` means it exists and belongs to someone else, which still counts — a
+ * server started under a different user is exactly the case that must not be
+ * trampled.
+ */
+export const processIsAlive = (pid: number): boolean => {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (cause) {
+    return (cause as NodeJS.ErrnoException).code === "EPERM";
+  }
+};
+
+const readHolder = Effect.fn("serverSingleton.readHolder")(function* (lockPath: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const raw = yield* fs.readFileString(lockPath).pipe(Effect.orElseSucceed(() => ""));
+  return Option.getOrUndefined(decodeHolder(raw));
+});
+
+/**
+ * Claims the directory, or explains who holds it.
+ *
+ * A lock file whose owner is gone — or which is unreadable, which means a
+ * half-written file from a crash mid-write — is reclaimed rather than treated as
+ * a permanent block. Reclaiming re-races the exclusive create, so two servers
+ * starting together still produce exactly one winner.
+ */
+const claimLock = Effect.fn("serverSingleton.claimLock")(function* (input: {
+  readonly stateDir: string;
+  readonly lockPath: string;
+  readonly startedAt: string;
+}) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const payload = encodeHolder({ version: 1, pid: process.pid, startedAt: input.startedAt });
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    yield* fs.makeDirectory(path.dirname(input.lockPath), { recursive: true }).pipe(Effect.ignore);
+    const created = yield* fs.writeFileString(input.lockPath, payload, { flag: "wx" }).pipe(
+      Effect.as(true),
+      Effect.orElseSucceed(() => false),
+    );
+    if (created) return undefined;
+
+    const holder = yield* readHolder(input.lockPath);
+    if (holder !== undefined && processIsAlive(holder.pid)) {
+      return new ServerAlreadyRunningError({
+        stateDir: input.stateDir,
+        lockPath: input.lockPath,
+        holderPid: holder.pid,
+        ...(holder.port === undefined ? {} : { holderPort: holder.port }),
+        holderStartedAt: holder.startedAt,
+      });
+    }
+    // Owner is gone, or the file is unreadable because a crash tore a write in
+    // half. Reclaim and re-race the exclusive create, which still yields one
+    // winner when two servers start together.
+    yield* fs.remove(input.lockPath).pipe(Effect.ignore);

@@ -622,6 +637,17 @@ const makeServerLayer = Layer.unwrap(
           }
 
           const launcher = yield* ServiceLauncherClient.ServiceLauncherClient;
+
+          // Stamp the port onto the lock we already hold. It is only ever read
+          // by a *later* server's refusal message, which turns "something else
+          // is running" into an address the user can open.
+          yield* ServerSingleton.serverLockPath(config.stateDir).pipe(
+            Effect.flatMap((lockPath) =>
+              ServerSingleton.recordServerLockPort(lockPath, address.port),
+            ),
+            Effect.ignore,
+          );

@@ -0,0 +1,210 @@
+/**
+ * One server per data directory.
+ *
+ * Two T3 Code servers pointed at the same `--base-dir` both open `state.sqlite`
+ * and both write `settings.json`, and they overwrite each other. The observed
+ * incident: a desktop app auto-updated to a newer server while the old one was
+ * still running, the new process found its port taken, silently bound a random
+ * one, and ran blind against shared state. The visible symptom was a settings
+ * toggle that would not stick — hours away from the actual cause.
+ *
+ * Nothing about that is detectable after the fact, so the fix is to refuse at
+ * startup. A second server against a held directory exits with one clear
+ * message instead of corrupting state.
+ *
+ * ## Why a pid file rather than `flock`
+ *
+ * An advisory `flock` is the better primitive: the kernel drops it when the
+ * holder dies, so a crashed server leaves nothing stale to clean up. Node has no
+ * binding for it, and adding a native dependency to the server for one lock is a
+ * worse trade than handling staleness here.
+ *
+ * So the lock is an atomically created file holding the owner's identity, and
+ * liveness is checked with signal 0. The tradeoff is honest: if a server is
+ * killed and its pid is later reused by an unrelated process, this refuses to
+ * start until the file is removed. That is the safe direction to fail, and the
+ * message names the file so recovery is one `rm`.
+ */
+import * as DateTime from "effect/DateTime";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import * as Schema from "effect/Schema";
+
+export const SERVER_LOCK_FILENAME = "server.lock";
+
+export const ServerLockHolder = Schema.Struct({
+  version: Schema.Literal(1),
+  pid: Schema.Int,
+  startedAt: Schema.String,
+  /** Absent until the server binds; the lock is taken before a port exists. */
+  port: Schema.optional(Schema.Int),
+});
+export type ServerLockHolder = typeof ServerLockHolder.Type;
+
+const ServerLockHolderFromJson = Schema.fromJsonString(ServerLockHolder);
+const decodeHolder = Schema.decodeUnknownOption(ServerLockHolderFromJson);
+const encodeHolder = Schema.encodeSync(ServerLockHolderFromJson);
+
+export class ServerAlreadyRunningError extends Schema.TaggedErrorClass<ServerAlreadyRunningError>()(
+  "ServerAlreadyRunningError",
+  {
+    stateDir: Schema.String,
+    lockPath: Schema.String,
+    holderPid: Schema.Int,
+    holderPort: Schema.optional(Schema.Int),
+    holderStartedAt: Schema.String,
+  },
+) {
+  override get message(): string {
+    const where =
+      this.holderPort === undefined
+        ? `pid ${this.holderPid}`
+        : `pid ${this.holderPid}, listening on port ${this.holderPort}`;
+    return [
+      "Another T3 Code server is already using this data directory.",
+      "",
+      `  data directory: ${this.stateDir}`,
+      `  held by:        ${where}`,
+      `  since:          ${this.holderStartedAt}`,
+      "",
+      "Two servers sharing one data directory overwrite each other's state.sqlite",
+      "and settings.json. Stop the running server, or start this one with a",
+      "different --base-dir.",
+      "",
+      `If that process is gone, remove ${this.lockPath} and start again.`,
+    ].join("\n");
+  }
+}
+
+export class ServerLockUnavailableError extends Schema.TaggedErrorClass<ServerLockUnavailableError>()(
+  "ServerLockUnavailableError",
+  {
+    lockPath: Schema.String,
+    reason: Schema.String,
+  },
+) {
+  override get message(): string {
+    return `Could not claim the server lock at ${this.lockPath}: ${this.reason}`;
+  }
+}
+
+/**
+ * Whether a pid is a live process.
+ *
+ * `EPERM` means it exists and belongs to someone else, which still counts — a
+ * server started under a different user is exactly the case that must not be
+ * trampled.
+ */
+export const processIsAlive = (pid: number): boolean => {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (cause) {
+    return (cause as NodeJS.ErrnoException).code === "EPERM";
+  }
+};
+
+const readHolder = Effect.fn("serverSingleton.readHolder")(function* (lockPath: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const raw = yield* fs.readFileString(lockPath).pipe(Effect.orElseSucceed(() => ""));
+  return Option.getOrUndefined(decodeHolder(raw));
+});
+
+/**
+ * Claims the directory, or explains who holds it.
+ *
+ * A lock file whose owner is gone — or which is unreadable, which means a
+ * half-written file from a crash mid-write — is reclaimed rather than treated as
+ * a permanent block. Reclaiming re-races the exclusive create, so two servers
+ * starting together still produce exactly one winner.
+ */
+const claimLock = Effect.fn("serverSingleton.claimLock")(function* (input: {
+  readonly stateDir: string;
+  readonly lockPath: string;
+  readonly startedAt: string;
+}) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const payload = encodeHolder({ version: 1, pid: process.pid, startedAt: input.startedAt });
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    yield* fs.makeDirectory(path.dirname(input.lockPath), { recursive: true }).pipe(Effect.ignore);
+    const created = yield* fs.writeFileString(input.lockPath, payload, { flag: "wx" }).pipe(
+      Effect.as(true),
+      Effect.orElseSucceed(() => false),
+    );
+    if (created) return undefined;
+
+    const holder = yield* readHolder(input.lockPath);
+    if (holder !== undefined && processIsAlive(holder.pid)) {
+      return new ServerAlreadyRunningError({
+        stateDir: input.stateDir,
+        lockPath: input.lockPath,
+        holderPid: holder.pid,
+        ...(holder.port === undefined ? {} : { holderPort: holder.port }),
+        holderStartedAt: holder.startedAt,
+      });
+    }
+    // Owner is gone, or the file is unreadable because a crash tore a write in
+    // half. Reclaim and re-race the exclusive create, which still yields one
+    // winner when two servers start together.
+    yield* fs.remove(input.lockPath).pipe(Effect.ignore);

@@ -0,0 +1,210 @@
+/**
+ * One server per data directory.
+ *
+ * Two T3 Code servers pointed at the same `--base-dir` both open `state.sqlite`
+ * and both write `settings.json`, and they overwrite each other. The observed
+ * incident: a desktop app auto-updated to a newer server while the old one was
+ * still running, the new process found its port taken, silently bound a random
+ * one, and ran blind against shared state. The visible symptom was a settings
+ * toggle that would not stick — hours away from the actual cause.
+ *
+ * Nothing about that is detectable after the fact, so the fix is to refuse at
+ * startup. A second server against a held directory exits with one clear
+ * message instead of corrupting state.
+ *
+ * ## Why a pid file rather than `flock`
+ *
+ * An advisory `flock` is the better primitive: the kernel drops it when the
+ * holder dies, so a crashed server leaves nothing stale to clean up. Node has no
+ * binding for it, and adding a native dependency to the server for one lock is a
+ * worse trade than handling staleness here.
+ *
+ * So the lock is an atomically created file holding the owner's identity, and
+ * liveness is checked with signal 0. The tradeoff is honest: if a server is
+ * killed and its pid is later reused by an unrelated process, this refuses to
+ * start until the file is removed. That is the safe direction to fail, and the
+ * message names the file so recovery is one `rm`.
+ */
+import * as DateTime from "effect/DateTime";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import * as Schema from "effect/Schema";
+
+export const SERVER_LOCK_FILENAME = "server.lock";
+
+export const ServerLockHolder = Schema.Struct({
+  version: Schema.Literal(1),
+  pid: Schema.Int,
+  startedAt: Schema.String,
+  /** Absent until the server binds; the lock is taken before a port exists. */
+  port: Schema.optional(Schema.Int),
+});
+export type ServerLockHolder = typeof ServerLockHolder.Type;
+
+const ServerLockHolderFromJson = Schema.fromJsonString(ServerLockHolder);
+const decodeHolder = Schema.decodeUnknownOption(ServerLockHolderFromJson);
+const encodeHolder = Schema.encodeSync(ServerLockHolderFromJson);
+
+export class ServerAlreadyRunningError extends Schema.TaggedErrorClass<ServerAlreadyRunningError>()(
+  "ServerAlreadyRunningError",
+  {
+    stateDir: Schema.String,
+    lockPath: Schema.String,
+    holderPid: Schema.Int,
+    holderPort: Schema.optional(Schema.Int),
+    holderStartedAt: Schema.String,
+  },
+) {
+  override get message(): string {
+    const where =
+      this.holderPort === undefined
+        ? `pid ${this.holderPid}`
+        : `pid ${this.holderPid}, listening on port ${this.holderPort}`;
+    return [
+      "Another T3 Code server is already using this data directory.",
+      "",
+      `  data directory: ${this.stateDir}`,
+      `  held by:        ${where}`,
+      `  since:          ${this.holderStartedAt}`,
+      "",
+      "Two servers sharing one data directory overwrite each other's state.sqlite",
+      "and settings.json. Stop the running server, or start this one with a",
+      "different --base-dir.",
+      "",
+      `If that process is gone, remove ${this.lockPath} and start again.`,
+    ].join("\n");
+  }
+}
+
+export class ServerLockUnavailableError extends Schema.TaggedErrorClass<ServerLockUnavailableError>()(
+  "ServerLockUnavailableError",
+  {
+    lockPath: Schema.String,
+    reason: Schema.String,
+  },
+) {
+  override get message(): string {
+    return `Could not claim the server lock at ${this.lockPath}: ${this.reason}`;
+  }
+}
+
+/**
+ * Whether a pid is a live process.
+ *
+ * `EPERM` means it exists and belongs to someone else, which still counts — a
+ * server started under a different user is exactly the case that must not be
+ * trampled.
+ */
+export const processIsAlive = (pid: number): boolean => {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (cause) {
+    return (cause as NodeJS.ErrnoException).code === "EPERM";
+  }
+};
+
+const readHolder = Effect.fn("serverSingleton.readHolder")(function* (lockPath: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const raw = yield* fs.readFileString(lockPath).pipe(Effect.orElseSucceed(() => ""));
+  return Option.getOrUndefined(decodeHolder(raw));
+});
+
+/**
+ * Claims the directory, or explains who holds it.
+ *
+ * A lock file whose owner is gone — or which is unreadable, which means a
+ * half-written file from a crash mid-write — is reclaimed rather than treated as
+ * a permanent block. Reclaiming re-races the exclusive create, so two servers
+ * starting together still produce exactly one winner.
+ */
+const claimLock = Effect.fn("serverSingleton.claimLock")(function* (input: {
+  readonly stateDir: string;
+  readonly lockPath: string;
+  readonly startedAt: string;
+}) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const payload = encodeHolder({ version: 1, pid: process.pid, startedAt: input.startedAt });
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    yield* fs.makeDirectory(path.dirname(input.lockPath), { recursive: true }).pipe(Effect.ignore);
+    const created = yield* fs.writeFileString(input.lockPath, payload, { flag: "wx" }).pipe(
+      Effect.as(true),
+      Effect.orElseSucceed(() => false),
+    );
+    if (created) return undefined;
+
+    const holder = yield* readHolder(input.lockPath);
+    if (holder !== undefined && processIsAlive(holder.pid)) {
+      return new ServerAlreadyRunningError({
+        stateDir: input.stateDir,
+        lockPath: input.lockPath,
+        holderPid: holder.pid,
+        ...(holder.port === undefined ? {} : { holderPort: holder.port }),
+        holderStartedAt: holder.startedAt,
+      });
+    }
+    // Owner is gone, or the file is unreadable because a crash tore a write in
+    // half. Reclaim and re-race the exclusive create, which still yields one
+    // winner when two servers start together.
+    yield* fs.remove(input.lockPath).pipe(Effect.ignore);
+  }
+  return new ServerLockUnavailableError({
+    lockPath: input.lockPath,
+    reason: "the lock was repeatedly reclaimed by another starting server",
+  });
+});
+
+/** Releases only a lock this process still owns, so a reclaimer is never evicted. */
+export const releaseServerLock = Effect.fn("serverSingleton.release")(function* (lockPath: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const holder = yield* readHolder(lockPath);
+  if (holder !== undefined && holder.pid !== process.pid) return;
+  yield* fs.remove(lockPath).pipe(Effect.ignore);
+});
+
+/**
+ * Records the bound port on the lock we already hold.
+ *
+ * Only for the error message a *later* server prints: knowing the holder's port
+ * turns "something else is running" into an address the user can open. Failure
+ * is ignored — the lock's job is done once it is held.
+ */
+export const recordServerLockPort = Effect.fn("serverSingleton.recordPort")(function* (
+  lockPath: string,
+  port: number,
+) {
+  const fs = yield* FileSystem.FileSystem;
+  const holder = yield* readHolder(lockPath);
+  if (holder === undefined || holder.pid !== process.pid) return;
+  yield* fs.writeFileString(lockPath, encodeHolder({ ...holder, port })).pipe(Effect.ignore);
+});
+
+export const serverLockPath = Effect.fn("serverSingleton.lockPath")(function* (stateDir: string) {
+  const path = yield* Path.Path;
+  return path.join(stateDir, SERVER_LOCK_FILENAME);
+});
+
+/**
+ * Holds the data directory for the lifetime of the returned scope.
+ *
+ * Acquired before anything opens the database or binds a port, and released on
+ * shutdown.
+ */
+export const acquireServerSingleton = Effect.fn("serverSingleton.acquire")(function* (
+  stateDir: string,
+) {
+  const lockPath = yield* serverLockPath(stateDir);
+  const startedAt = DateTime.formatIso(yield* DateTime.now);
+  return yield* Effect.acquireRelease(
+    Effect.gen(function* () {
+      const failure = yield* claimLock({ stateDir, lockPath, startedAt });
+      if (failure !== undefined) return yield* failure;

@@ -0,0 +1,373 @@
+/**
+ * One server per data directory.
+ *
+ * Two T3 Code servers pointed at the same `--base-dir` both open `state.sqlite`
+ * and both write `settings.json`, and they overwrite each other. The observed
+ * incident: a desktop app auto-updated to a newer server while the old one was
+ * still running, the new process found its port taken, silently bound a random
+ * one, and ran blind against shared state. The visible symptom was a settings
+ * toggle that would not stick — hours away from the actual cause.
+ *
+ * Nothing about that is detectable after the fact, so the fix is to refuse at
+ * startup. A second server against a held directory exits with one clear
+ * message instead of corrupting state.
+ *
+ * ## Why a pid file rather than `flock`
+ *
+ * An advisory `flock` is the better primitive: the kernel drops it when the
+ * holder dies, so a crashed server leaves nothing stale to clean up. Node has no
+ * binding for it, and adding a native dependency to the server for one lock is a
+ * worse trade than handling staleness here.
+ *
+ * So the lock is an atomically created file holding the owner's identity, and
+ * liveness is checked with signal 0. The tradeoff is honest: if a server is
+ * killed and its pid is later reused by an unrelated process, this refuses to
+ * start until the file is removed. That is the safe direction to fail, and the
+ * message names the file so recovery is one `rm`.
+ *
+ * ## Upgrading from a pre-lock version
+ *
+ * A pre-lock server writes no `server.lock`, so the file alone cannot see one.
+ * It does persist `server-runtime.json` with its live pid though, so before
+ * claiming the directory a live legacy runtime state is read as a held lock
+ * and refused the same way. Otherwise the desktop auto-update incident this
+ * exists to prevent still happens once on upgrade day — the new server starts
+ * next to the old one against the same state.
+ */
+import * as Data from "effect/Data";
+import * as DateTime from "effect/DateTime";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import * as PlatformError from "effect/PlatformError";
+import * as Schedule from "effect/Schedule";
+import * as Schema from "effect/Schema";
+
+import { writeFileStringAtomically } from "./atomicWrite.ts";
+import { readPersistedServerRuntimeState } from "./serverRuntimeState.ts";
+
+export const SERVER_LOCK_FILENAME = "server.lock";
+export const SERVER_RUNTIME_STATE_FILENAME = "server-runtime.json";
+
+export const ServerLockHolder = Schema.Struct({
+  version: Schema.Literal(1),
+  pid: Schema.Int,
+  startedAt: Schema.String,
+  /** Absent until the server binds; the lock is taken before a port exists. */
+  port: Schema.optional(Schema.Int),
+});
+export type ServerLockHolder = typeof ServerLockHolder.Type;
+
+const ServerLockHolderFromJson = Schema.fromJsonString(ServerLockHolder);
+const decodeHolder = Schema.decodeUnknownOption(ServerLockHolderFromJson);
+const encodeHolder = Schema.encodeSync(ServerLockHolderFromJson);
+
+export class ServerAlreadyRunningError extends Schema.TaggedErrorClass<ServerAlreadyRunningError>()(
+  "ServerAlreadyRunningError",
+  {
+    stateDir: Schema.String,
+    lockPath: Schema.String,
+    holderPid: Schema.Int,
+    holderPort: Schema.optional(Schema.Int),
+    holderStartedAt: Schema.String,
+  },
+) {
+  override get message(): string {
+    const where =
+      this.holderPort === undefined
+        ? `pid ${this.holderPid}`
+        : `pid ${this.holderPid}, listening on port ${this.holderPort}`;
+    return [
+      "Another T3 Code server is already using this data directory.",
+      "",
+      `  data directory: ${this.stateDir}`,
+      `  held by:        ${where}`,
+      `  since:          ${this.holderStartedAt}`,
+      "",
+      "Two servers sharing one data directory overwrite each other's state.sqlite",
+      "and settings.json. Stop the running server, or start this one with a",
+      "different --base-dir.",
+      "",
+      `If that process is gone, remove ${this.lockPath} and start again.`,
+    ].join("\n");
+  }
+}
+
+export class ServerLockUnavailableError extends Schema.TaggedErrorClass<ServerLockUnavailableError>()(
+  "ServerLockUnavailableError",
+  {
+    lockPath: Schema.String,
+    attempts: Schema.Int,
+    cause: Schema.optional(Schema.Defect()),
+  },
+) {
+  override get message(): string {
+    return `Could not claim the server lock at ${this.lockPath} after ${this.attempts} attempts; another starting server kept reclaiming it.`;
+  }
+}
+
+/**
+ * Whether a pid is a live process.
+ *
+ * `EPERM` means it exists and belongs to someone else, which still counts — a
+ * server started under a different user is exactly the case that must not be
+ * trampled.
+ */
+export const processIsAlive = (pid: number): boolean => {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (cause) {
+    return (cause as NodeJS.ErrnoException).code === "EPERM";
+  }
+};
+
+const readHolder = Effect.fn("serverSingleton.readHolder")(function* (lockPath: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const raw = yield* fs
+    .readFileString(lockPath)
+    .pipe(
+      Effect.catch((error) =>
+        error.reason._tag === "NotFound" ? Effect.succeed("") : Effect.fail(error),
+      ),
+    );
+  return Option.getOrUndefined(decodeHolder(raw));
+});
+
+// A dead holder's lock is not unlinked outright: between one starter reading a
+// stale lock and another recreating it, an unconditional unlink would remove a
+// live successor's claim. Reclamation instead refreshes the file's mtime
+// `MAX_CLAIM_ATTEMPTS` times; only a file that stays the same dead content
+// across every attempt is removed, so a live recreation always survives. The
+// holder bumps the mtime once between attempts while it owns the lock, so no
+// sequence of slower starters can reclaim out from under it either — and a
+// dead holder still recycles its lock inside a second of startup time.
+const MAX_CLAIM_ATTEMPTS = 3;
+const RECLAIM_OBSERVATION_DELAY_MILLIS = 200;
+
+const isAlreadyExists = (error: PlatformError.PlatformError): boolean =>
+  error.reason._tag === "AlreadyExists";
+
+/**
+ * A pre-lock server is live against this directory. Failure-phase marker rather
+ * than an error: `serverRuntimeState.ts` already owns the file's decode-error
+ * type, and the refusal shown to the user is the same `ServerAlreadyRunningError`
+ * either way — `server.ts` converts this at the boundary where the config with
+ * the path lives.
+ */
+export class LiveLegacyServerRuntime extends Data.TaggedError("LiveLegacyServerRuntime")<{
+  readonly state: {
+    readonly pid: number;
+    readonly port: number;
+    readonly startedAt: string;
+  };
+}> {}
+
+/**
+ * Claims the directory, or explains who holds it.
+ *
+ * A lock file whose owner is gone is reclaimed rather than treated as a
+ * permanent block: a dead holder must not lock its own directory forever.
+ * Reclaiming re-races the exclusive create, so two servers starting together
+ * still produce exactly one winner.
+ */
+const claimLock = Effect.fn("serverSingleton.claimLock")(function* (input: {
+  readonly stateDir: string;
+  readonly lockPath: string;
+  readonly legacyRuntimeStatePath: string;
+  readonly startedAt: string;
+}) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const payload = encodeHolder({ version: 1, pid: process.pid, startedAt: input.startedAt });
+
+  // A pre-lock server writes no lock, so the file alone is blind to one — but
+  // it does persist its live pid in `server-runtime.json`. Refuse a live
+  // legacy runtime exactly like a live lock holder, before the lock is ever
+  // created; otherwise the upgrade that introduces this guard still starts
+  // next to the very server it is meant to replace. A dead legacy pid is
+  // ignored here: reclaim of its leftover lock is what removes the file.
+  const legacyState = yield* readPersistedServerRuntimeState(input.legacyRuntimeStatePath);
+  if (Option.isSome(legacyState) && processIsAlive(legacyState.value.pid)) {
+    return yield* new LiveLegacyServerRuntime({ state: legacyState.value });
+  }
+
+  yield* fs.makeDirectory(path.dirname(input.lockPath), { recursive: true });
+
+  // Counts how often this starter was forced to refresh a candidate stale lock
+  // before believing it is really dead (see the constants above).
+  let reclaimRefreshes = 0;
+  while (true) {
+    // A scheduler yield between attempts, so a reclaim observation round lets
+    // other starters (and the holder's heartbeat) run before this starter
+    // concludes a lock never changed. Real time only — resolvable under
+    // `TestClock`.
+    yield* Effect.yieldNow;
+    const created = yield* fs.writeFileString(input.lockPath, payload, { flag: "wx" }).pipe(
+      Effect.as(true),
+      Effect.catch((error) =>
+        isAlreadyExists(error) ? Effect.succeed(false) : Effect.fail(error),
+      ),
+    );
+    if (created) return undefined;
+
+    const holder = yield* readHolder(input.lockPath);
+    if (holder !== undefined && processIsAlive(holder.pid)) {
+      return new ServerAlreadyRunningError({
+        stateDir: input.stateDir,
+        lockPath: input.lockPath,
+        holderPid: holder.pid,
+        ...(holder.port === undefined ? {} : { holderPort: holder.port }),
+        holderStartedAt: holder.startedAt,
+      });
+    }
+
+    if (reclaimRefreshes >= MAX_CLAIM_ATTEMPTS) {
+      // The lock stayed untouched across every observation round, which only a
+      // dead holder allows — a live one's heartbeat always refreshes inside
+      // one round. Removing it now frees the directory for the winner of the
+      // next create, and cannot delete a successor's claim.
+      yield* fs.remove(input.lockPath, { force: true });
+      return new ServerLockUnavailableError({

@@ -0,0 +1,373 @@
+/**
+ * One server per data directory.
+ *
+ * Two T3 Code servers pointed at the same `--base-dir` both open `state.sqlite`
+ * and both write `settings.json`, and they overwrite each other. The observed
+ * incident: a desktop app auto-updated to a newer server while the old one was
+ * still running, the new process found its port taken, silently bound a random
+ * one, and ran blind against shared state. The visible symptom was a settings
+ * toggle that would not stick — hours away from the actual cause.
+ *
+ * Nothing about that is detectable after the fact, so the fix is to refuse at
+ * startup. A second server against a held directory exits with one clear
+ * message instead of corrupting state.
+ *
+ * ## Why a pid file rather than `flock`
+ *
+ * An advisory `flock` is the better primitive: the kernel drops it when the
+ * holder dies, so a crashed server leaves nothing stale to clean up. Node has no
+ * binding for it, and adding a native dependency to the server for one lock is a
+ * worse trade than handling staleness here.
+ *
+ * So the lock is an atomically created file holding the owner's identity, and
+ * liveness is checked with signal 0. The tradeoff is honest: if a server is
+ * killed and its pid is later reused by an unrelated process, this refuses to
+ * start until the file is removed. That is the safe direction to fail, and the
+ * message names the file so recovery is one `rm`.
+ *
+ * ## Upgrading from a pre-lock version
+ *
+ * A pre-lock server writes no `server.lock`, so the file alone cannot see one.
+ * It does persist `server-runtime.json` with its live pid though, so before
+ * claiming the directory a live legacy runtime state is read as a held lock
+ * and refused the same way. Otherwise the desktop auto-update incident this
+ * exists to prevent still happens once on upgrade day — the new server starts
+ * next to the old one against the same state.
+ */
+import * as Data from "effect/Data";
+import * as DateTime from "effect/DateTime";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import * as PlatformError from "effect/PlatformError";
+import * as Schedule from "effect/Schedule";
+import * as Schema from "effect/Schema";
+
+import { writeFileStringAtomically } from "./atomicWrite.ts";
+import { readPersistedServerRuntimeState } from "./serverRuntimeState.ts";
+
+export const SERVER_LOCK_FILENAME = "server.lock";
+export const SERVER_RUNTIME_STATE_FILENAME = "server-runtime.json";
+
+export const ServerLockHolder = Schema.Struct({
+  version: Schema.Literal(1),
+  pid: Schema.Int,
+  startedAt: Schema.String,
+  /** Absent until the server binds; the lock is taken before a port exists. */
+  port: Schema.optional(Schema.Int),
+});
+export type ServerLockHolder = typeof ServerLockHolder.Type;
+
+const ServerLockHolderFromJson = Schema.fromJsonString(ServerLockHolder);
+const decodeHolder = Schema.decodeUnknownOption(ServerLockHolderFromJson);
+const encodeHolder = Schema.encodeSync(ServerLockHolderFromJson);
+
+export class ServerAlreadyRunningError extends Schema.TaggedErrorClass<ServerAlreadyRunningError>()(
+  "ServerAlreadyRunningError",
+  {
+    stateDir: Schema.String,
+    lockPath: Schema.String,
+    holderPid: Schema.Int,
+    holderPort: Schema.optional(Schema.Int),
+    holderStartedAt: Schema.String,
+  },
+) {
+  override get message(): string {
+    const where =
+      this.holderPort === undefined
+        ? `pid ${this.holderPid}`
+        : `pid ${this.holderPid}, listening on port ${this.holderPort}`;
+    return [
+      "Another T3 Code server is already using this data directory.",
+      "",
+      `  data directory: ${this.stateDir}`,
+      `  held by:        ${where}`,
+      `  since:          ${this.holderStartedAt}`,
+      "",
+      "Two servers sharing one data directory overwrite each other's state.sqlite",
+      "and settings.json. Stop the running server, or start this one with a",
+      "different --base-dir.",
+      "",
+      `If that process is gone, remove ${this.lockPath} and start again.`,
+    ].join("\n");
+  }
+}
+
+export class ServerLockUnavailableError extends Schema.TaggedErrorClass<ServerLockUnavailableError>()(
+  "ServerLockUnavailableError",
+  {
+    lockPath: Schema.String,
+    attempts: Schema.Int,
+    cause: Schema.optional(Schema.Defect()),
+  },
+) {
+  override get message(): string {
+    return `Could not claim the server lock at ${this.lockPath} after ${this.attempts} attempts; another starting server kept reclaiming it.`;
+  }
+}
+
+/**
+ * Whether a pid is a live process.
+ *
+ * `EPERM` means it exists and belongs to someone else, which still counts — a
+ * server started under a different user is exactly the case that must not be
+ * trampled.
+ */
+export const processIsAlive = (pid: number): boolean => {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (cause) {
+    return (cause as NodeJS.ErrnoException).code === "EPERM";
+  }
+};
+
+const readHolder = Effect.fn("serverSingleton.readHolder")(function* (lockPath: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const raw = yield* fs
+    .readFileString(lockPath)
+    .pipe(
+      Effect.catch((error) =>
+        error.reason._tag === "NotFound" ? Effect.succeed("") : Effect.fail(error),
+      ),
+    );
+  return Option.getOrUndefined(decodeHolder(raw));
+});
+
+// A dead holder's lock is not unlinked outright: between one starter reading a
+// stale lock and another recreating it, an unconditional unlink would remove a
+// live successor's claim. Reclamation instead refreshes the file's mtime
+// `MAX_CLAIM_ATTEMPTS` times; only a file that stays the same dead content
+// across every attempt is removed, so a live recreation always survives. The
+// holder bumps the mtime once between attempts while it owns the lock, so no
+// sequence of slower starters can reclaim out from under it either — and a
+// dead holder still recycles its lock inside a second of startup time.
+const MAX_CLAIM_ATTEMPTS = 3;
+const RECLAIM_OBSERVATION_DELAY_MILLIS = 200;
+
+const isAlreadyExists = (error: PlatformError.PlatformError): boolean =>
+  error.reason._tag === "AlreadyExists";
+
+/**
+ * A pre-lock server is live against this directory. Failure-phase marker rather
+ * than an error: `serverRuntimeState.ts` already owns the file's decode-error
+ * type, and the refusal shown to the user is the same `ServerAlreadyRunningError`
+ * either way — `server.ts` converts this at the boundary where the config with
+ * the path lives.
+ */
+export class LiveLegacyServerRuntime extends Data.TaggedError("LiveLegacyServerRuntime")<{
+  readonly state: {
+    readonly pid: number;
+    readonly port: number;
+    readonly startedAt: string;
+  };
+}> {}
+
+/**
+ * Claims the directory, or explains who holds it.
+ *
+ * A lock file whose owner is gone is reclaimed rather than treated as a
+ * permanent block: a dead holder must not lock its own directory forever.
+ * Reclaiming re-races the exclusive create, so two servers starting together
+ * still produce exactly one winner.
+ */
+const claimLock = Effect.fn("serverSingleton.claimLock")(function* (input: {
+  readonly stateDir: string;
+  readonly lockPath: string;
+  readonly legacyRuntimeStatePath: string;
+  readonly startedAt: string;
+}) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const payload = encodeHolder({ version: 1, pid: process.pid, startedAt: input.startedAt });
+
+  // A pre-lock server writes no lock, so the file alone is blind to one — but
+  // it does persist its live pid in `server-runtime.json`. Refuse a live
+  // legacy runtime exactly like a live lock holder, before the lock is ever
+  // created; otherwise the upgrade that introduces this guard still starts
+  // next to the very server it is meant to replace. A dead legacy pid is
+  // ignored here: reclaim of its leftover lock is what removes the file.
+  const legacyState = yield* readPersistedServerRuntimeState(input.legacyRuntimeStatePath);
+  if (Option.isSome(legacyState) && processIsAlive(legacyState.value.pid)) {
+    return yield* new LiveLegacyServerRuntime({ state: legacyState.value });
+  }
+
+  yield* fs.makeDirectory(path.dirname(input.lockPath), { recursive: true });
+
+  // Counts how often this starter was forced to refresh a candidate stale lock
+  // before believing it is really dead (see the constants above).
+  let reclaimRefreshes = 0;
+  while (true) {
+    // A scheduler yield between attempts, so a reclaim observation round lets
+    // other starters (and the holder's heartbeat) run before this starter
+    // concludes a lock never changed. Real time only — resolvable under
+    // `TestClock`.
+    yield* Effect.yieldNow;
+    const created = yield* fs.writeFileString(input.lockPath, payload, { flag: "wx" }).pipe(
+      Effect.as(true),
+      Effect.catch((error) =>
+        isAlreadyExists(error) ? Effect.succeed(false) : Effect.fail(error),
+      ),
+    );
+    if (created) return undefined;
+
+    const holder = yield* readHolder(input.lockPath);
+    if (holder !== undefined && processIsAlive(holder.pid)) {
+      return new ServerAlreadyRunningError({
+        stateDir: input.stateDir,
+        lockPath: input.lockPath,
+        holderPid: holder.pid,
+        ...(holder.port === undefined ? {} : { holderPort: holder.port }),
+        holderStartedAt: holder.startedAt,
+      });
+    }
+
+    if (reclaimRefreshes >= MAX_CLAIM_ATTEMPTS) {
+      // The lock stayed untouched across every observation round, which only a
+      // dead holder allows — a live one's heartbeat always refreshes inside
+      // one round. Removing it now frees the directory for the winner of the
+      // next create, and cannot delete a successor's claim.
+      yield* fs.remove(input.lockPath, { force: true });
+      return new ServerLockUnavailableError({
+        lockPath: input.lockPath,
+        attempts: reclaimRefreshes,
+      });
+    }
+
+    // Owner is gone, or the file is unreadable because a crash tore a write
+    // in half. Never unlink unconditionally: between this starter's read and
+    // its remove, a successor can win the re-race and recreate its own live
+    // lock, and the unlink would delete that. Reclaim instead refreshes the
+    // file's mtime once per observation round and only removes it after it has
+    // stayed untouched across `MAX_CLAIM_ATTEMPTS` rounds — a live
+    // successor's heartbeat always refreshes inside that window, so the file
+    // this starter removes is provably still a dead one's. The wait lands in
+    // the *next* loop head's `Effect.yieldNow`, which keeps `claimLock`
+    // real-time-only so tests can drive it without a fake clock.
+    reclaimRefreshes += 1;
+    const now = yield* DateTime.now;
+    yield* fs.utimes(input.lockPath, DateTime.toDateUtc(now), DateTime.toDateUtc(now));
+  }
+});
+
+/**
+ * A live lock holder refreshes its claim's mtime once per reclaim-observation
+ * round while it owns the lock. Any starter mid-reclaim then sees the file
+ * change and backs off, so the holder's lock cannot be reclaimed from under it
+ * no matter how many starters race. Stops with the scope that holds the lock.
+ */
+const holdServerLock = Effect.fn("serverSingleton.hold")(function* (lockPath: string) {
+  const fs = yield* FileSystem.FileSystem;
+  // `Effect.repeat` with a spaced schedule (rather than `Effect.schedule`) so
+  // a failure wakes the loop on the next tick instead of terminating it: the
+  // holder must keep refreshing for as long as it owns the lock, through
+  // whatever transient filesystem errors come and go.
+  const reschedule = Schedule.spaced(RECLAIM_OBSERVATION_DELAY_MILLIS);
+  yield* Effect.forkScoped(
+    Effect.gen(function* () {
+      const holder = yield* readHolder(lockPath);
+      if (holder === undefined || holder.pid !== process.pid) return;
+      const now = yield* DateTime.now;
+      const date = DateTime.toDateUtc(now);
+      yield* fs.utimes(lockPath, date, date);
+    }).pipe(
+      Effect.repeat({ schedule: reschedule, while: () => true }),
+      Effect.catch(() => Effect.void),
+    ),
+  );
+});
+
+/**
+ * Releases only a lock this process verifiably owns, so a successor is never
+ * evicted. An undecodable file is left alone: it is either a live re-entrant
+ * claim (the winning starter's just-created file, or another process's) or a
+ * crash fragment, and crash fragments are what reclaim exists for.
+ */
+export const releaseServerLock = Effect.fn("serverSingleton.release")(function* (lockPath: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const holder = yield* readHolder(lockPath);
+  if (holder === undefined || holder.pid !== process.pid) return;
+  yield* fs.remove(lockPath, { force: true }).pipe(Effect.ignore);
+});
+
+/**
+ * Records the bound port on the lock we already hold.
+ *
+ * The rewrite goes through write-temp-then-rename so a reader never observes
+ * an empty or partial file: with an in-place rewrite, a concurrent starter
+ * could mistake the truncated file for a crashed owner and reclaim a live
+ * lock — the exact concurrent-servers corruption the lock exists to prevent.
+ *
+ * Only for the error message a *later* server prints: knowing the holder's port
+ * turns "something else is running" into an address the user can open. Failure
+ * is ignored — the lock's job is done once it is held.
+ */
+export const recordServerLockPort = Effect.fn("serverSingleton.recordPort")(function* (
+  lockPath: string,
+  port: number,
+) {
+  const holder = yield* readHolder(lockPath);
+  if (holder === undefined || holder.pid !== process.pid) return;
+  yield* writeFileStringAtomically({
+    filePath: lockPath,
+    contents: encodeHolder({ ...holder, port }),
+  }).pipe(Effect.ignore);
+});
+
+export const serverLockPath = Effect.fn("serverSingleton.lockPath")(function* (stateDir: string) {
+  const path = yield* Path.Path;
+  return path.join(stateDir, SERVER_LOCK_FILENAME);
+});
+
+export const legacyServerRuntimeStatePath = Effect.fn("serverSingleton.legacyStatePath")(function* (
+  stateDir: string,
+) {
+  const path = yield* Path.Path;
+  return path.join(stateDir, SERVER_RUNTIME_STATE_FILENAME);
+});
+
+/**
+ * Holds the data directory for the lifetime of the returned scope.
+ *
+ * Acquired before anything opens the database or binds a port, and released on
+ * shutdown. A live pre-lock server reads as a held lock here too: callers see
+ * one refusal type regardless of which generation holds the directory.
+ */
+export const acquireServerSingleton = Effect.fn("serverSingleton.acquire")(function* (
+  stateDir: string,
+) {
+  const lockPath = yield* serverLockPath(stateDir);
+  const legacyRuntimeStatePath = yield* legacyServerRuntimeStatePath(stateDir);
+  const startedAt = DateTime.formatIso(yield* DateTime.now);
+  return yield* Effect.acquireRelease(
+    Effect.gen(function* () {
+      const failure = yield* claimLock({
+        stateDir,
+        lockPath,
+        legacyRuntimeStatePath,
+        startedAt,
+      }).pipe(
+        // The message names `server-runtime.json` (not `server.lock`) as the
+        // file to remove if the process is gone — that is all a pre-lock
+        // server ever wrote.
+        Effect.catchTag("LiveLegacyServerRuntime", (legacy) =>
+          Effect.fail(
+            new ServerAlreadyRunningError({
+              stateDir,
+              lockPath: legacyRuntimeStatePath,
+              holderPid: legacy.state.pid,
+              holderPort: legacy.state.port,
+              holderStartedAt: legacy.state.startedAt,
+            }),
+          ),
+        ),

@@ -0,0 +1,465 @@
+/**
+ * One server per data directory.
+ *
+ * Two T3 Code servers pointed at the same `--base-dir` both open `state.sqlite`
+ * and both write `settings.json`, and they overwrite each other. The observed
+ * incident: a desktop app auto-updated to a newer server while the old one was
+ * still running, the new process found its port taken, silently bound a random
+ * one, and ran blind against shared state. The visible symptom was a settings
+ * toggle that would not stick — hours away from the actual cause.
+ *
+ * Nothing about that is detectable after the fact, so the fix is to refuse at
+ * startup. A second server against a held directory exits with one clear
+ * message instead of corrupting state.
+ *
+ * ## Why a pid file rather than `flock`
+ *
+ * An advisory `flock` is the better primitive: the kernel drops it when the
+ * holder dies, so a crashed server leaves nothing stale to clean up. Node has no
+ * binding for it, and adding a native dependency to the server for one lock is a
+ * worse trade than handling staleness here.
+ *
+ * So the lock is an atomically created file holding the owner's identity, and
+ * liveness is checked with signal 0. The tradeoff is honest: if a server is
+ * killed and its pid is later reused by an unrelated process, this refuses to
+ * start until the file is removed. That is the safe direction to fail, and the
+ * message names the file so recovery is one `rm`.
+ *
+ * ## Upgrading from a pre-lock version
+ *
+ * A pre-lock server writes no `server.lock`, so the file alone cannot see one.
+ * It does persist `server-runtime.json` with its live pid though, so before
+ * claiming the directory a live legacy runtime state is read as a held lock
+ * and refused the same way. Otherwise the desktop auto-update incident this
+ * exists to prevent still happens once on upgrade day — the new server starts
+ * next to the old one against the same state.
+ */
+import * as Data from "effect/Data";
+import * as DateTime from "effect/DateTime";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import * as PlatformError from "effect/PlatformError";
+import * as Schedule from "effect/Schedule";
+import * as Schema from "effect/Schema";
+
+import { writeFileStringAtomically } from "./atomicWrite.ts";
+import { readPersistedServerRuntimeState } from "./serverRuntimeState.ts";
+
+export const SERVER_LOCK_FILENAME = "server.lock";
+export const SERVER_RUNTIME_STATE_FILENAME = "server-runtime.json";
+
+export const ServerLockHolder = Schema.Struct({
+  version: Schema.Literal(1),
+  pid: Schema.Int,
+  startedAt: Schema.String,
+  /** Absent until the server binds; the lock is taken before a port exists. */
+  port: Schema.optional(Schema.Int),
+});
+export type ServerLockHolder = typeof ServerLockHolder.Type;
+
+const ServerLockHolderFromJson = Schema.fromJsonString(ServerLockHolder);
+const decodeHolder = Schema.decodeUnknownOption(ServerLockHolderFromJson);
+const encodeHolder = Schema.encodeSync(ServerLockHolderFromJson);
+
+export class ServerAlreadyRunningError extends Schema.TaggedError<ServerAlreadyRunningError>()(
+  "ServerAlreadyRunningError",
+  {
+    stateDir: Schema.String,
+    lockPath: Schema.String,
+    holderPid: Schema.Int,
+    holderPort: Schema.optional(Schema.Int),
+    holderStartedAt: Schema.String,
+  },
+) {
+  override get message(): string {
+    const where =
+      this.holderPort === undefined
+        ? `pid ${this.holderPid}`
+        : `pid ${this.holderPid}, listening on port ${this.holderPort}`;
+    return [
+      "Another T3 Code server is already using this data directory.",
+      "",
+      `  data directory: ${this.stateDir}`,
+      `  held by:        ${where}`,
+      `  since:          ${this.holderStartedAt}`,
+      "",
+      "Two servers sharing one data directory overwrite each other's state.sqlite",
+      "and settings.json. Stop the running server, or start this one with a",
+      "different --base-dir.",
+      "",
+      `If that process is gone, remove ${this.lockPath} and start again.`,
+    ].join("\n");
+  }
+}
+
+export class ServerLockUnavailableError extends Schema.TaggedError<ServerLockUnavailableError>()(
+  "ServerLockUnavailableError",
+  {
+    lockPath: Schema.String,
+    attempts: Schema.Int,
+    cause: Schema.optional(Schema.Defect()),
+  },
+) {
+  override get message(): string {
+    return `Could not claim the server lock at ${this.lockPath} after ${this.attempts} attempts; another starting server kept reclaiming it.`;
+  }
+}
+
+// How many reclaim-and-retry rounds against a confirmed-dead lock a starter
+// tolerates before concluding something else keeps recreating it: nothing a
+// real dead holder produces, everything a permission wall or a competing
+// starter produces.
+const MAX_RECLAIM_CYCLES = 3;
+
+/**
+ * Whether a pid is a live process.
+ *
+ * `EPERM` means it exists and belongs to someone else, which still counts — a
+ * server started under a different user is exactly the case that must not be
+ * trampled.
+ */
+export const processIsAlive = (pid: number): boolean => {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (cause) {
+    return (cause as NodeJS.ErrnoException).code === "EPERM";
+  }
+};
+
+const readHolder = Effect.fn("serverSingleton.readHolder")(function* (lockPath: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const raw = yield* fs
+    .readFileString(lockPath)
+    .pipe(
+      Effect.catch((error) =>
+        error.reason._tag === "NotFound" ? Effect.succeed("") : Effect.fail(error),
+      ),
+    );
+  return Option.getOrUndefined(decodeHolder(raw));
+});
+
+// A dead holder's lock is not unlinked outright: between one starter reading a
+// stale lock and another recreating it, an unconditional unlink would remove a
+// live successor's claim. Reclamation instead refreshes the file's mtime
+// `MAX_CLAIM_ATTEMPTS` times; only a file that stays the same dead content
+// across every attempt is removed, so a live recreation always survives. The
+// holder bumps the mtime once between attempts while it owns the lock, so no
+// sequence of slower starters can reclaim out from under it either — and a
+// dead holder still recycles its lock inside a second of startup time.
+const MAX_CLAIM_ATTEMPTS = 3;
+const RECLAIM_OBSERVATION_DELAY_MILLIS = 200;
+
+const isAlreadyExists = (error: PlatformError.PlatformError): boolean =>
+  error.reason._tag === "AlreadyExists";
+
+const isNotFound = (error: PlatformError.PlatformError): boolean => error.reason._tag === "NotFound";
+
+const reclaimGatePath = (lockPath: string): string => `${lockPath}.reclaim`;
+
+/**
+ * Serialize stale-lock takeover. Two reclaimers can both finish the last
+ * stale read, then both `remove` — the second deletes the first's fresh
+ * claim. An exclusive gate file makes exactly one reclaimer allowed to
+ * touch `server.lock`; everyone else backs off and retries the create.
+ */
+const takeReclaimGate = Effect.fn("serverSingleton.takeReclaimGate")(function* (lockPath: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const gatePath = reclaimGatePath(lockPath);
+  const existing = yield* fs.readFileString(gatePath).pipe(
+    Effect.catch((error) => (isNotFound(error) ? Effect.succeed(undefined) : Effect.fail(error))),
+  );
+  if (existing !== undefined) {
+    const gatePid = Number.parseInt(existing.trim(), 10);
+    if (processIsAlive(gatePid)) return false;
+    yield* fs.remove(gatePath, { force: true }).pipe(Effect.ignore);
+  }
+  return yield* fs.writeFileString(gatePath, `${process.pid}\n`, { flag: "wx" }).pipe(
+    Effect.as(true),
+    Effect.catch((error) => (isAlreadyExists(error) ? Effect.succeed(false) : Effect.fail(error))),
+  );
+});
+
+/**
+ * A pre-lock server is live against this directory. Failure-phase marker rather
+ * than an error: `serverRuntimeState.ts` already owns the file's decode-error
+ * type, and the refusal shown to the user is the same `ServerAlreadyRunningError`
+ * either way — `server.ts` converts this at the boundary where the config with
+ * the path lives.
+ */
+export class LiveLegacyServerRuntime extends Data.TaggedError("LiveLegacyServerRuntime")<{
+  readonly state: {
+    readonly pid: number;
+    readonly port: number;
+    readonly startedAt: string;
+  };
+}> {}
+
+/**
+ * Claims the directory, or explains who holds it.
+ *
+ * A lock file whose owner is gone is reclaimed rather than treated as a
+ * permanent block: a dead holder must not lock its own directory forever.
+ * Reclaiming re-races the exclusive create, so two servers starting together
+ * still produce exactly one winner.
+ */
+const claimLock = Effect.fn("serverSingleton.claimLock")(function* (input: {
+  readonly stateDir: string;
+  readonly lockPath: string;
+  readonly legacyRuntimeStatePath: string;
+  readonly startedAt: string;
+}) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const payload = encodeHolder({ version: 1, pid: process.pid, startedAt: input.startedAt });
+
+  // A pre-lock server writes no lock, so the file alone is blind to one — but
+  // it does persist its live pid in `server-runtime.json`. Refuse a live
+  // legacy runtime exactly like a live lock holder, before the lock is ever
+  // created; otherwise the upgrade that introduces this guard still starts
+  // next to the very server it is meant to replace. A dead legacy pid is
+  // ignored here: reclaim of its leftover lock is what removes the file.
+  const legacyState = yield* readPersistedServerRuntimeState(input.legacyRuntimeStatePath);
+  if (Option.isSome(legacyState) && processIsAlive(legacyState.value.pid)) {
+    return yield* new LiveLegacyServerRuntime({ state: legacyState.value });
+  }
+
+  yield* fs.makeDirectory(path.dirname(input.lockPath), { recursive: true });
+
+  // Counts how often this starter was forced to refresh a candidate stale lock
+  // before believing it is really dead, and how often a confirmed-dead lock
+  // bounced it back to another round (see the constants above).
+  let reclaimRefreshes = 0;
+  let reclaimCycles = 0;
+  while (true) {
+    // A scheduler yield between attempts, so a reclaim observation round lets
+    // other starters (and the holder's heartbeat) run before this starter
+    // concludes a lock never changed. Real time only — resolvable under
+    // `TestClock`.
+    yield* Effect.yieldNow;
+    const created = yield* fs.writeFileString(input.lockPath, payload, { flag: "wx" }).pipe(
+      Effect.as(true),
+      Effect.catch((error) =>
+        isAlreadyExists(error) ? Effect.succeed(false) : Effect.fail(error),
+      ),
+    );
+    if (created) return undefined;
+
+    const holder = yield* readHolder(input.lockPath);
+    if (holder !== undefined && processIsAlive(holder.pid)) {
+      return new ServerAlreadyRunningError({
+        stateDir: input.stateDir,
+        lockPath: input.lockPath,
+        holderPid: holder.pid,
+        ...(holder.port === undefined ? {} : { holderPort: holder.port }),
+        holderStartedAt: holder.startedAt,
+      });
+    }
+
+    // The read found no live owner — either a decodeable dead holder, or
+    // `undefined` because the file is missing (another starter mid-reclaim)
+    // or undecodable (a crash tore a write in half). Never unlink after one
+    // read: between this starter's read and its remove, a successor can win
+    // the re-race and recreate its own live lock, and the unlink would delete
+    // that. The candidate is mtime-refreshed and re-observed across
+    // `MAX_CLAIM_ATTEMPTS` rounds, and only a file that stayed untouched
+    // through every round is removed — a live successor's heartbeat always
+    // refreshes inside one round, so the file a reclaimer finally removes is
+    // provably still dead. The wait lands in the *next* loop head's
+    // `Effect.yieldNow`, which keeps `claimLock` real-time-only so tests can
+    // drive it without a fake clock.
+    if (reclaimRefreshes >= MAX_CLAIM_ATTEMPTS) {
+      // Removing frees the directory, and the create is retried on the next
+      // pass: a cleanly restarted server after a crash claims its directory
+      // here, not on a later manual retry. Bounded, so a lock another starter
+      // keeps recreating (or a permissions wall keeps failing to remove for)
+      // still surfaces as itself.
+      const wonGate = yield* takeReclaimGate(input.lockPath);
+      if (!wonGate) {
+        reclaimRefreshes = 0;
+        reclaimCycles += 1;
+        if (reclaimCycles >= MAX_RECLAIM_CYCLES) {
+          return new ServerLockUnavailableError({
+            lockPath: input.lockPath,
+            attempts: reclaimCycles,
+          });
+        }
+        continue;
+      }
+      const gatePath = reclaimGatePath(input.lockPath);
+      const takeover = yield* Effect.gen(function* () {
+        const holderAfterGate = yield* readHolder(input.lockPath);
+        if (holderAfterGate !== undefined && processIsAlive(holderAfterGate.pid)) {
+          return new ServerAlreadyRunningError({
+            stateDir: input.stateDir,
+            lockPath: input.lockPath,
+            holderPid: holderAfterGate.pid,
+            ...(holderAfterGate.port === undefined ? {} : { holderPort: holderAfterGate.port }),
+            holderStartedAt: holderAfterGate.startedAt,
+          });
+        }
+        yield* fs.remove(input.lockPath, { force: true });

@@ -0,0 +1,210 @@
+/**
+ * One server per data directory.
+ *
+ * Two T3 Code servers pointed at the same `--base-dir` both open `state.sqlite`
+ * and both write `settings.json`, and they overwrite each other. The observed
+ * incident: a desktop app auto-updated to a newer server while the old one was
+ * still running, the new process found its port taken, silently bound a random
+ * one, and ran blind against shared state. The visible symptom was a settings
+ * toggle that would not stick — hours away from the actual cause.
+ *
+ * Nothing about that is detectable after the fact, so the fix is to refuse at
+ * startup. A second server against a held directory exits with one clear
+ * message instead of corrupting state.
+ *
+ * ## Why a pid file rather than `flock`
+ *
+ * An advisory `flock` is the better primitive: the kernel drops it when the
+ * holder dies, so a crashed server leaves nothing stale to clean up. Node has no
+ * binding for it, and adding a native dependency to the server for one lock is a
+ * worse trade than handling staleness here.
+ *
+ * So the lock is an atomically created file holding the owner's identity, and
+ * liveness is checked with signal 0. The tradeoff is honest: if a server is
+ * killed and its pid is later reused by an unrelated process, this refuses to
+ * start until the file is removed. That is the safe direction to fail, and the
+ * message names the file so recovery is one `rm`.
+ */
+import * as DateTime from "effect/DateTime";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import * as Schema from "effect/Schema";
+
+export const SERVER_LOCK_FILENAME = "server.lock";
+
+export const ServerLockHolder = Schema.Struct({
+  version: Schema.Literal(1),
+  pid: Schema.Int,
+  startedAt: Schema.String,
+  /** Absent until the server binds; the lock is taken before a port exists. */
+  port: Schema.optional(Schema.Int),
+});
+export type ServerLockHolder = typeof ServerLockHolder.Type;
+
+const ServerLockHolderFromJson = Schema.fromJsonString(ServerLockHolder);
+const decodeHolder = Schema.decodeUnknownOption(ServerLockHolderFromJson);
+const encodeHolder = Schema.encodeSync(ServerLockHolderFromJson);
+
+export class ServerAlreadyRunningError extends Schema.TaggedErrorClass<ServerAlreadyRunningError>()(
+  "ServerAlreadyRunningError",
+  {
+    stateDir: Schema.String,
+    lockPath: Schema.String,
+    holderPid: Schema.Int,
+    holderPort: Schema.optional(Schema.Int),
+    holderStartedAt: Schema.String,
+  },
+) {
+  override get message(): string {
+    const where =
+      this.holderPort === undefined
+        ? `pid ${this.holderPid}`
+        : `pid ${this.holderPid}, listening on port ${this.holderPort}`;
+    return [
+      "Another T3 Code server is already using this data directory.",
+      "",
+      `  data directory: ${this.stateDir}`,
+      `  held by:        ${where}`,
+      `  since:          ${this.holderStartedAt}`,
+      "",
+      "Two servers sharing one data directory overwrite each other's state.sqlite",
+      "and settings.json. Stop the running server, or start this one with a",
+      "different --base-dir.",
+      "",
+      `If that process is gone, remove ${this.lockPath} and start again.`,
+    ].join("\n");
+  }
+}
+
+export class ServerLockUnavailableError extends Schema.TaggedErrorClass<ServerLockUnavailableError>()(
+  "ServerLockUnavailableError",
+  {
+    lockPath: Schema.String,
+    reason: Schema.String,
+  },
+) {
+  override get message(): string {
+    return `Could not claim the server lock at ${this.lockPath}: ${this.reason}`;
+  }
+}
+
+/**
+ * Whether a pid is a live process.
+ *
+ * `EPERM` means it exists and belongs to someone else, which still counts — a
+ * server started under a different user is exactly the case that must not be
+ * trampled.
+ */
+export const processIsAlive = (pid: number): boolean => {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (cause) {
+    return (cause as NodeJS.ErrnoException).code === "EPERM";
+  }
+};
+
+const readHolder = Effect.fn("serverSingleton.readHolder")(function* (lockPath: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const raw = yield* fs.readFileString(lockPath).pipe(Effect.orElseSucceed(() => ""));
+  return Option.getOrUndefined(decodeHolder(raw));
+});
+
+/**
+ * Claims the directory, or explains who holds it.
+ *
+ * A lock file whose owner is gone — or which is unreadable, which means a
+ * half-written file from a crash mid-write — is reclaimed rather than treated as
+ * a permanent block. Reclaiming re-races the exclusive create, so two servers
+ * starting together still produce exactly one winner.
+ */
+const claimLock = Effect.fn("serverSingleton.claimLock")(function* (input: {
+  readonly stateDir: string;
+  readonly lockPath: string;
+  readonly startedAt: string;
+}) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const payload = encodeHolder({ version: 1, pid: process.pid, startedAt: input.startedAt });
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    yield* fs.makeDirectory(path.dirname(input.lockPath), { recursive: true }).pipe(Effect.ignore);
+    const created = yield* fs.writeFileString(input.lockPath, payload, { flag: "wx" }).pipe(
+      Effect.as(true),
+      Effect.orElseSucceed(() => false),
+    );
+    if (created) return undefined;
+
+    const holder = yield* readHolder(input.lockPath);
+    if (holder !== undefined && processIsAlive(holder.pid)) {
+      return new ServerAlreadyRunningError({
+        stateDir: input.stateDir,
+        lockPath: input.lockPath,
+        holderPid: holder.pid,
+        ...(holder.port === undefined ? {} : { holderPort: holder.port }),
+        holderStartedAt: holder.startedAt,
+      });
+    }
+    // Owner is gone, or the file is unreadable because a crash tore a write in
+    // half. Reclaim and re-race the exclusive create, which still yields one
+    // winner when two servers start together.
+    yield* fs.remove(input.lockPath).pipe(Effect.ignore);
+  }
+  return new ServerLockUnavailableError({
+    lockPath: input.lockPath,
+    reason: "the lock was repeatedly reclaimed by another starting server",
+  });
+});
+
+/** Releases only a lock this process still owns, so a reclaimer is never evicted. */
+export const releaseServerLock = Effect.fn("serverSingleton.release")(function* (lockPath: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const holder = yield* readHolder(lockPath);
+  if (holder !== undefined && holder.pid !== process.pid) return;
+  yield* fs.remove(lockPath).pipe(Effect.ignore);
+});
+
+/**
+ * Records the bound port on the lock we already hold.
+ *
+ * Only for the error message a *later* server prints: knowing the holder's port
+ * turns "something else is running" into an address the user can open. Failure
+ * is ignored — the lock's job is done once it is held.
+ */
+export const recordServerLockPort = Effect.fn("serverSingleton.recordPort")(function* (
+  lockPath: string,
+  port: number,
+) {
+  const fs = yield* FileSystem.FileSystem;
+  const holder = yield* readHolder(lockPath);
+  if (holder === undefined || holder.pid !== process.pid) return;
+  yield* fs.writeFileString(lockPath, encodeHolder({ ...holder, port })).pipe(Effect.ignore);

@@ -0,0 +1,374 @@
+/**
+ * One server per data directory.
+ *
+ * Two T3 Code servers pointed at the same `--base-dir` both open `state.sqlite`
+ * and both write `settings.json`, and they overwrite each other. The observed
+ * incident: a desktop app auto-updated to a newer server while the old one was
+ * still running, the new process found its port taken, silently bound a random
+ * one, and ran blind against shared state. The visible symptom was a settings
+ * toggle that would not stick — hours away from the actual cause.
+ *
+ * Nothing about that is detectable after the fact, so the fix is to refuse at
+ * startup. A second server against a held directory exits with one clear
+ * message instead of corrupting state.
+ *
+ * ## Why a pid file rather than `flock`
+ *
+ * An advisory `flock` is the better primitive: the kernel drops it when the
+ * holder dies, so a crashed server leaves nothing stale to clean up. Node has no
+ * binding for it, and adding a native dependency to the server for one lock is a
+ * worse trade than handling staleness here.
+ *
+ * So the lock is an atomically created file holding the owner's identity, and
+ * liveness is checked with signal 0. The tradeoff is honest: if a server is
+ * killed and its pid is later reused by an unrelated process, this refuses to
+ * start until the file is removed. That is the safe direction to fail, and the
+ * message names the file so recovery is one `rm`.
+ *
+ * ## Upgrading from a pre-lock version
+ *
+ * A pre-lock server writes no `server.lock`, so the file alone cannot see one.
+ * It does persist `server-runtime.json` with its live pid though, so before
+ * claiming the directory a live legacy runtime state is read as a held lock
+ * and refused the same way. Otherwise the desktop auto-update incident this
+ * exists to prevent still happens once on upgrade day — the new server starts
+ * next to the old one against the same state.
+ */
+import * as Data from "effect/Data";
+import * as DateTime from "effect/DateTime";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import * as PlatformError from "effect/PlatformError";
+import * as Schedule from "effect/Schedule";
+import * as Schema from "effect/Schema";
+
+import { writeFileStringAtomically } from "./atomicWrite.ts";
+import { readPersistedServerRuntimeState } from "./serverRuntimeState.ts";
+
+export const SERVER_LOCK_FILENAME = "server.lock";
+export const SERVER_RUNTIME_STATE_FILENAME = "server-runtime.json";
+
+export const ServerLockHolder = Schema.Struct({
+  version: Schema.Literal(1),
+  pid: Schema.Int,
+  startedAt: Schema.String,
+  /** Absent until the server binds; the lock is taken before a port exists. */
+  port: Schema.optional(Schema.Int),
+});
+export type ServerLockHolder = typeof ServerLockHolder.Type;
+
+const ServerLockHolderFromJson = Schema.fromJsonString(ServerLockHolder);
+const decodeHolder = Schema.decodeUnknownOption(ServerLockHolderFromJson);
+const encodeHolder = Schema.encodeSync(ServerLockHolderFromJson);
+
+export class ServerAlreadyRunningError extends Schema.TaggedErrorClass<ServerAlreadyRunningError>()(
+  "ServerAlreadyRunningError",
+  {
+    stateDir: Schema.String,
+    lockPath: Schema.String,
+    holderPid: Schema.Int,
+    holderPort: Schema.optional(Schema.Int),
+    holderStartedAt: Schema.String,
+  },
+) {
+  override get message(): string {
+    const where =
+      this.holderPort === undefined
+        ? `pid ${this.holderPid}`
+        : `pid ${this.holderPid}, listening on port ${this.holderPort}`;
+    return [
+      "Another T3 Code server is already using this data directory.",
+      "",
+      `  data directory: ${this.stateDir}`,
+      `  held by:        ${where}`,
+      `  since:          ${this.holderStartedAt}`,
+      "",
+      "Two servers sharing one data directory overwrite each other's state.sqlite",
+      "and settings.json. Stop the running server, or start this one with a",
+      "different --base-dir.",
+      "",
+      `If that process is gone, remove ${this.lockPath} and start again.`,
+    ].join("\n");
+  }
+}
+
+export class ServerLockUnavailableError extends Schema.TaggedErrorClass<ServerLockUnavailableError>()(
+  "ServerLockUnavailableError",
+  {
+    lockPath: Schema.String,
+    attempts: Schema.Int,
+    cause: Schema.optional(Schema.Defect()),
+  },
+) {
+  override get message(): string {
+    return `Could not claim the server lock at ${this.lockPath} after ${this.attempts} attempts; another starting server kept reclaiming it.`;
+  }
+}
+
+/**
+ * Whether a pid is a live process.
+ *
+ * `EPERM` means it exists and belongs to someone else, which still counts — a
+ * server started under a different user is exactly the case that must not be
+ * trampled.
+ */
+export const processIsAlive = (pid: number): boolean => {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (cause) {
+    return (cause as NodeJS.ErrnoException).code === "EPERM";
+  }
+};
+
+const readHolder = Effect.fn("serverSingleton.readHolder")(function* (lockPath: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const raw = yield* fs
+    .readFileString(lockPath)
+    .pipe(
+      Effect.catch((error) =>
+        error.reason._tag === "NotFound" ? Effect.succeed("") : Effect.fail(error),
+      ),
+    );
+  return Option.getOrUndefined(decodeHolder(raw));
+});
+
+// A dead holder's lock is not unlinked outright: between one starter reading a
+// stale lock and another recreating it, an unconditional unlink would remove a
+// live successor's claim. Reclamation instead refreshes the file's mtime
+// `MAX_CLAIM_ATTEMPTS` times; only a file that stays the same dead content
+// across every attempt is removed, so a live recreation always survives. The
+// holder bumps the mtime once between attempts while it owns the lock, so no
+// sequence of slower starters can reclaim out from under it either — and a
+// dead holder still recycles its lock inside a second of startup time.
+const MAX_CLAIM_ATTEMPTS = 3;
+const RECLAIM_OBSERVATION_DELAY_MILLIS = 200;
+
+const isAlreadyExists = (error: PlatformError.PlatformError): boolean =>
+  error.reason._tag === "AlreadyExists";
+
+/**
+ * A pre-lock server is live against this directory. Failure-phase marker rather
+ * than an error: `serverRuntimeState.ts` already owns the file's decode-error
+ * type, and the refusal shown to the user is the same `ServerAlreadyRunningError`
+ * either way — `server.ts` converts this at the boundary where the config with
+ * the path lives.
+ */
+export class LiveLegacyServerRuntime extends Data.TaggedError("LiveLegacyServerRuntime")<{
+  readonly state: {
+    readonly pid: number;
+    readonly port: number;
+    readonly startedAt: string;
+  };
+}> {}
+
+/**
+ * Claims the directory, or explains who holds it.
+ *
+ * A lock file whose owner is gone is reclaimed rather than treated as a
+ * permanent block: a dead holder must not lock its own directory forever.
+ * Reclaiming re-races the exclusive create, so two servers starting together
+ * still produce exactly one winner.
+ */
+const claimLock = Effect.fn("serverSingleton.claimLock")(function* (input: {
+  readonly stateDir: string;
+  readonly lockPath: string;
+  readonly legacyRuntimeStatePath: string;
+  readonly startedAt: string;
+}) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const payload = encodeHolder({ version: 1, pid: process.pid, startedAt: input.startedAt });
+
+  // A pre-lock server writes no lock, so the file alone is blind to one — but
+  // it does persist its live pid in `server-runtime.json`. Refuse a live
+  // legacy runtime exactly like a live lock holder, before the lock is ever
+  // created; otherwise the upgrade that introduces this guard still starts
+  // next to the very server it is meant to replace. A dead legacy pid is
+  // ignored here: reclaim of its leftover lock is what removes the file.
+  const legacyState = yield* readPersistedServerRuntimeState(input.legacyRuntimeStatePath);
+  if (Option.isSome(legacyState) && processIsAlive(legacyState.value.pid)) {
+    return yield* new LiveLegacyServerRuntime({ state: legacyState.value });
+  }
+
+  yield* fs.makeDirectory(path.dirname(input.lockPath), { recursive: true });
+
+  // Counts how often this starter was forced to refresh a candidate stale lock
+  // before believing it is really dead (see the constants above).
+  let reclaimRefreshes = 0;
+  while (true) {
+    // A scheduler yield between attempts, so a reclaim observation round lets
+    // other starters (and the holder's heartbeat) run before this starter
+    // concludes a lock never changed. Real time only — resolvable under
+    // `TestClock`.
+    yield* Effect.yieldNow;
+    const created = yield* fs.writeFileString(input.lockPath, payload, { flag: "wx" }).pipe(
+      Effect.as(true),
+      Effect.catch((error) =>
+        isAlreadyExists(error) ? Effect.succeed(false) : Effect.fail(error),
+      ),
+    );
+    if (created) return undefined;
+
+    const holder = yield* readHolder(input.lockPath);
+    if (holder !== undefined && processIsAlive(holder.pid)) {
+      return new ServerAlreadyRunningError({
+        stateDir: input.stateDir,
+        lockPath: input.lockPath,
+        holderPid: holder.pid,
+        ...(holder.port === undefined ? {} : { holderPort: holder.port }),
+        holderStartedAt: holder.startedAt,
+      });
+    }
+
+    if (reclaimRefreshes >= MAX_CLAIM_ATTEMPTS) {
+      // The lock stayed untouched across every observation round, which only a
+      // dead holder allows — a live one's heartbeat always refreshes inside
+      // one round. Removing it now frees the directory for the winner of the
+      // next create, and cannot delete a successor's claim.
+      yield* fs.remove(input.lockPath, { force: true });
+      return new ServerLockUnavailableError({
+        lockPath: input.lockPath,
+        attempts: reclaimRefreshes,
+      });
+    }
+
+    // Owner is gone, or the file is unreadable because a crash tore a write
+    // in half. Never unlink unconditionally: between this starter's read and
+    // its remove, a successor can win the re-race and recreate its own live
+    // lock, and the unlink would delete that. Reclaim instead refreshes the
+    // file's mtime once per observation round and only removes it after it has
+    // stayed untouched across `MAX_CLAIM_ATTEMPTS` rounds — a live
+    // successor's heartbeat always refreshes inside that window, so the file
+    // this starter removes is provably still a dead one's. The wait lands in
+    // the *next* loop head's `Effect.yieldNow`, which keeps `claimLock`
+    // real-time-only so tests can drive it without a fake clock.
+    reclaimRefreshes += 1;
+    const now = yield* DateTime.now;
+    yield* fs.utimes(input.lockPath, DateTime.toDateUtc(now), DateTime.toDateUtc(now));