@promptctl/cc-candybar 1.17.0 → 1.17.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@promptctl/cc-candybar",
-  "version": "1.17.0",
+  "version": "1.17.2",
   "description": "Statusline renderer for Claude Code — a JSON5-configurable DSL with daemon-cached data sources, byte-clean palette-aware composition, and OSC8 click verbs.",
   "type": "module",
   "main": "./dist/index.mjs",
@@ -91,10 +91,10 @@
     "mobx": "^6.15.0"
   },
   "optionalDependencies": {
-    "@promptctl/cc-candybar-darwin-arm64": "1.17.0",
-    "@promptctl/cc-candybar-darwin-x64": "1.17.0",
-    "@promptctl/cc-candybar-linux-x64": "1.17.0",
-    "@promptctl/cc-candybar-linux-arm64": "1.17.0"
+    "@promptctl/cc-candybar-darwin-arm64": "1.17.2",
+    "@promptctl/cc-candybar-darwin-x64": "1.17.2",
+    "@promptctl/cc-candybar-linux-x64": "1.17.2",
+    "@promptctl/cc-candybar-linux-arm64": "1.17.2"
   },
   "pnpm": {
     "supportedArchitectures": {

package/src/daemon/paths.ts

@@ -95,19 +95,43 @@ export function ensureSocketParentSafe(sockPath: string): void {
   // If a stale socket file is a symlink, refuse — an attacker who briefly
   // had write access to a previously-permissive dir could have planted a
   // symlink even after we tighten perms.
-  try {
-    const sst = fs.lstatSync(sockPath);
-    if (sst.isSymbolicLink()) {
-      throw new Error(`socket path is a symlink: ${sockPath}`);
+  //
+  // [LAW:single-enforcer] The lease (`${sockPath}.lease`) gets the SAME gate:
+  // it is now load-bearing (ownership authority — readLease follows a symlink
+  // and a planted `lease → /dev/null` would read `absent`/`unreadable`, forcing
+  // a false reclaim that unlinks a live daemon's socket). One enforcer certifies
+  // every path we bind/read/write under this parent, so the socket and its lease
+  // can never diverge on "is this a symlink".
+  for (const p of [sockPath, leasePathFor(sockPath)]) {
+    try {
+      if (fs.lstatSync(p).isSymbolicLink()) {
+        throw new Error(`path is a symlink: ${p}`);
+      }
+    } catch (e) {
+      const code = (e as NodeJS.ErrnoException).code;
+      if (code !== "ENOENT") throw e;
     }
-  } catch (e) {
-    const code = (e as NodeJS.ErrnoException).code;
-    if (code !== "ENOENT") throw e;
   }
 }
 
-export function pidPath(): string {
-  return path.join(stateDir(), "pid");
+// [LAW:one-source-of-truth] The socket-ownership lease is DERIVED FROM the
+// socket path, so it shares the socket's identity root. The old diagnostic
+// pidfile lived under $XDG_STATE_HOME while the socket lived under /tmp — two
+// identity roots for one instance, and CC_CANDYBAR_SOCKET isolated only one of
+// them. Anchoring the lease to socketPath() means test/dev isolation via
+// CC_CANDYBAR_SOCKET isolates the lease too. The lease subsumes the old
+// diagnostic pidfile: it carries the owner pid (the reclaim authority) plus the
+// same diagnostic fields.
+// [LAW:one-source-of-truth] The socket→lease derivation lives here alone, so
+// leasePath() (the runtime authority path) and ensureSocketParentSafe's symlink
+// gate agree by construction. Takes the socket path explicitly so the safety
+// check certifies the exact path it was handed, not a re-derived one.
+export function leasePathFor(sockPath: string): string {
+  return `${sockPath}.lease`;
+}
+
+export function leasePath(): string {
+  return leasePathFor(socketPath());
 }
 
 export function sessionStatePath(): string {

package/src/daemon/server.ts

@@ -6,10 +6,22 @@ import { parseArgs } from "node:util";
 import {
   daemonDir,
   ensureSocketParentSafe,
-  pidPath,
+  leasePath,
+  leasePathFor,
   socketPath,
   sessionStatePath,
 } from "./paths";
+import {
+  arbitrateSocket,
+  readLease,
+  removeLeaseIfOwned,
+  writeLease,
+} from "./socket-lease";
+import {
+  makeOwnershipWatch,
+  readSocketIdentity,
+  type SocketIdentity,
+} from "./socket-ownership";
 import { dlog, closeLog } from "./log";
 import {
   PROTOCOL_VERSION,
@@ -184,6 +196,13 @@ function bindOrAttachAndExit(
   retried: boolean,
 ): void {
   server.removeAllListeners("error");
+  // [LAW:no-ambient-temporal-coupling] server.listen(path, cb) registers cb as
+  // a ONE-TIME 'listening' listener. A first listen that fails EADDRINUSE never
+  // fires 'listening', so its callback stays pending; the reclaim retry adds a
+  // second. Without clearing the stale one, a successful rebind fires BOTH and
+  // onListening runs twice — double-arming the RSS backstop + watchers. Clear
+  // pending 'listening' listeners so exactly one onListening fires per bind.
+  server.removeAllListeners("listening");
   server.once("error", (err) => {
     const code = (err as NodeJS.ErrnoException).code;
     if (code !== "EADDRINUSE") {
@@ -198,36 +217,40 @@ function bindOrAttachAndExit(
       process.exit(0);
       return;
     }
-    void handleAddressInUse(server, sockPath);
+    handleAddressInUse(server, sockPath);
   });
   server.listen(sockPath, () => onListening(sockPath));
 }
 
-async function handleAddressInUse(
-  server: net.Server,
-  sockPath: string,
-): Promise<void> {
-  // EADDRINUSE: either a live daemon (we are a duplicate — exit), or a stale
-  // socket file from a crashed prior daemon (unlink + rebind).
-  const alive = await isSocketAlive(sockPath);
-  if (alive) {
-    dlog("info", "another daemon is listening on socket — exiting");
-    process.exit(0);
-  }
-  // Race-window guard: between our first `isSocketAlive` returning false and
-  // our `unlinkSync` running, another concurrent recoverer could unlink+bind
-  // the path. Without re-checking, our unlink would remove their *live*
-  // socket, leaving two daemons (one orphaned-but-listening, one freshly
-  // bound). Re-check immediately before unlink. If a live listener appeared
-  // between checks, exit instead of stomping on it.
-  if (await isSocketAlive(sockPath)) {
-    dlog(
-      "info",
-      "race: another daemon claimed the socket during recovery — exiting",
-    );
+// [LAW:one-source-of-truth] EADDRINUSE arbitration consults the socket-derived
+// pid lease, NEVER a connect probe. The path already exists (a live daemon, or
+// a stale file from a crashed one); the lease's owner pid + kill(pid,0) decides
+// which. This is fully synchronous — reading the lease and testing liveness are
+// both sync — so there is no await gap for a concurrent recoverer to race
+// through (the old async probe had two such gaps and a hand-rolled re-check).
+//
+// [LAW:effects-at-boundaries] The decision is the pure arbitrateSocket fold
+// over the lease read + injected pidAlive; the kill / unlink / rebind effects
+// are performed here at the edge.
+function handleAddressInUse(server: net.Server, sockPath: string): void {
+  // [LAW:one-source-of-truth] Derive the lease from the SAME sockPath threaded
+  // through unlink + rebind below, not the re-derived global — one identity
+  // source for the whole arbitration.
+  const decision = arbitrateSocket(readLease(leasePathFor(sockPath)), pidAlive);
+  if (decision.kind === "attach-and-exit") {
+    dlog("info", `EADDRINUSE: ${decision.reason} — exiting`);
     process.exit(0);
+    // [LAW:no-ambient-temporal-coupling] process.exit() halts synchronously, so
+    // the reclaim below is already unreachable — but the explicit return makes
+    // that structural, matching the sibling `retried` branch, so no future
+    // refactor of the exit path can accidentally fall through to unlinking a
+    // live daemon's socket.
+    return;
   }
-  dlog("warn", "stale socket from crashed daemon — unlinking and rebinding");
+  dlog(
+    "warn",
+    `EADDRINUSE: ${decision.reason} — unlinking stale socket and rebinding`,
+  );
   // [LAW:no-defensive-null-guards] If unlink fails (permissions, read-only
   // FS), the retry will hit EADDRINUSE again, exit 0, and leave the system
   // in the worst state: no daemon + stale socket blocking future starts.
@@ -248,67 +271,77 @@ async function handleAddressInUse(
   bindOrAttachAndExit(server, sockPath, /* retried */ true);
 }
 
-// [LAW:no-defensive-null-guards] Three-state outcome distinguishes
-// "definitely no listener" from "probably alive but slow." Callers that
-// might destroy state on "no listener" (the stale-socket unlink path) must
-// treat "unknown" as alive to avoid stomping on a slow live daemon.
-type SocketAliveness = "alive" | "dead" | "unknown";
-
-function probeSocket(sockPath: string): Promise<SocketAliveness> {
-  return new Promise((resolve) => {
-    const sock = net.connect(sockPath);
-    let settled = false;
-    let timer: ReturnType<typeof setTimeout> | null = null;
-    const done = (result: SocketAliveness): void => {
-      if (settled) return;
-      settled = true;
-      if (timer) clearTimeout(timer);
-      sock.removeAllListeners();
-      sock.destroy();
-      resolve(result);
-    };
-    sock.once("connect", () => done("alive"));
-    sock.once("error", (err) => {
-      // Only these error codes definitively mean "no listener at this path":
-      //   ECONNREFUSED — socket file present, kernel rejected connect
-      //   ENOENT       — socket file absent
-      //   ENOTSOCK     — path exists but isn't a socket
-      // Anything else (EPERM, EACCES, EAGAIN, …) is ambiguous — assume the
-      // daemon is alive to avoid destructive false negatives.
-      const code = (err as NodeJS.ErrnoException).code;
-      const dead =
-        code === "ECONNREFUSED" || code === "ENOENT" || code === "ENOTSOCK";
-      done(dead ? "dead" : "unknown");
-    });
-    // 50ms is generous; localhost AF_UNIX connect is sub-ms when a listener
-    // exists. Timeout means "we couldn't tell" — treat as unknown so the
-    // stale-socket recovery path doesn't unlink a live (but slow) daemon's
-    // socket.
-    timer = setTimeout(() => done("unknown"), 50);
-    timer.unref();
-  });
-}
-
-// Convenience: callers that just want "is something listening" treat
-// "unknown" as alive (conservative — used by the EADDRINUSE attach branch).
-async function isSocketAlive(sockPath: string): Promise<boolean> {
-  const result = await probeSocket(sockPath);
-  return result !== "dead";
-}
-
 function onListening(sockPath: string): void {
+  // [LAW:no-ambient-temporal-coupling] Capture the bound socket's kernel
+  // identity (dev+ino) as the fingerprint the ownership self-check re-stats
+  // against, BEFORE claiming the lease. Captured from the PATH, not the bound
+  // FD: for an AF_UNIX listener, fstat(fd) reports the socket's inode in the
+  // socket namespace — not the filesystem-entry inode that stat(path) sees — so
+  // the FD yields no path-comparable identity. stat(path), taken as close to the
+  // bind as possible, is the only path-comparable truth available.
+  //
+  // [FRAMING:representation] Be honest about the ONE window this capture cannot
+  // close. It catches an absent/unreadable path (below): we could not form a
+  // fingerprint, so we have no proof of ownership and exit toward the SAFE
+  // direction (a false-displaced daemon just lets whoever holds the path serve —
+  // no orphan) WITHOUT writing a lease that would stomp a thief's. It does NOT
+  // catch a path that is present but already holds a THIEF's socket — if a second
+  // daemon completed its full EADDRINUSE → read-lease → unlink → rebind cycle in
+  // the single event-loop tick between bind() and this 'listening' callback, we
+  // fingerprint the thief's identity and the self-check reads `owned` forever
+  // (the orphan this module exists to kill). That race is irreducible at this
+  // layer (no race-free handle on our own socket's path-identity exists) and
+  // vanishingly narrow; fully closing it needs the lock-based liveness the epic
+  // deferred (a flock/start-time fingerprint) — the same residual sibling .1's
+  // arbitrateSocket documents for its false-alive direction.
+  const boundRead = readSocketIdentity(sockPath);
+  if (boundRead.kind !== "present") {
+    dlog(
+      "warn",
+      `no ownable socket at bind callback (${boundRead.kind}); exiting`,
+    );
+    shutdown(0);
+    return;
+  }
+
+  // [LAW:no-ambient-temporal-coupling] Claim ownership FIRST among the post-bind
+  // effects — before chmod or any other work — so the window between winning the
+  // bind and the lease naming us is as small as possible. A second daemon that
+  // binds in that sub-ms gap reads an absent lease and reclaims (displacing us);
+  // the ownership self-check below makes that self-healing, but keeping the
+  // window minimal keeps it vanishingly rare.
+  // [LAW:one-source-of-truth] Derive the lease from the same sockPath we bound,
+  // matching handleAddressInUse's read — one identity source across write + read.
+  writeLeaseFile(sockPath);
   try {
     fs.chmodSync(sockPath, 0o600);
   } catch (e) {
     dlog("warn", `chmod socket failed: ${(e as Error).message}`);
   }
-  writePidfileDiagnostic();
   dlog(
     "info",
     `daemon up: pid=${process.pid} v=${PROTOCOL_VERSION} sock=${sockPath}`,
   );
   armBinaryWatch();
   armLimits();
+  armOwnershipWatch(sockPath, boundRead.identity);
+}
+
+// --- socket-ownership self-check ---
+//
+// [LAW:single-enforcer] The sole enforcer of "serving implies owning the socket
+// path over time" (brandon-daemon-lifecycle-2b3.2). Periodically re-stats the
+// path; if its kernel identity no longer matches what we bound, we were
+// displaced (its socket unlinked + rebound by a reclaimer) and drain through the
+// SAME shutdown funnel as signals, the RSS backstop, and the watchdog — no
+// parallel exit path.
+function armOwnershipWatch(sockPath: string, bound: SocketIdentity): void {
+  makeOwnershipWatch({
+    bound,
+    readIdentity: () => readSocketIdentity(sockPath),
+    shutdown: (code) => shutdown(code),
+    log: dlog,
+  }).arm();
 }
 
 // --- binary-mtime self-restart ---
@@ -365,40 +398,29 @@ function armLimits(): void {
   limits.arm();
 }
 
-// --- diagnostic pidfile ---
+// --- socket-ownership lease ---
 //
-// [LAW:one-source-of-truth] The pidfile is *diagnostic only*. It records who
-// the running daemon is so `daemon-stats` can report it; it plays no role in
-// exclusion. Exclusion is the atomic bind() in bindOrAttachAndExit().
+// [LAW:one-source-of-truth] The lease is the authority for socket ownership —
+// its owner pid + kill(pid,0) is what the next daemon's EADDRINUSE arbitration
+// consults (handleAddressInUse). Exclusion RIGHT NOW is still the atomic bind()
+// in bindOrAttachAndExit(); the lease answers the separate question "may I
+// destroy this existing path" over time. It also carries the same diagnostic
+// fields the old pidfile did, so one file serves both roles.
 //
-// Overwrite-on-write (no EEXIST check). If a stale pidfile exists from a
-// crashed prior daemon, we replace it. The bind() above already proved no
-// other daemon is alive.
+// Overwrite-on-write (no EEXIST check). We only reach onListening after winning
+// the bind, so whatever stale lease a dead owner left is ours to replace. Write
+// failure is non-fatal: the lease is best-effort ownership signalling on top of
+// bind()'s hard exclusion; a missing lease degrades a future arbitration to
+// "reclaim" (unlink + rebind), never to a wrong attach.
 
-function writePidfileDiagnostic(): void {
-  const payload = JSON.stringify({
+function writeLeaseFile(sockPath: string): void {
+  const reason = writeLease(leasePathFor(sockPath), {
     pid: process.pid,
     version: PROTOCOL_VERSION,
     binPath: process.argv[1],
     startedAt: new Date().toISOString(),
   });
-  try {
-    fs.writeFileSync(pidPath(), payload, { mode: 0o600 });
-    // [LAW:single-enforcer] writeFileSync's `mode` only applies when the file
-    // is created. If a stale pidfile from a prior run was left with broader
-    // permissions, the write above won't tighten them — chmod explicitly so
-    // 0600 is the invariant regardless of prior state.
-    fs.chmodSync(pidPath(), 0o600);
-  } catch (e) {
-    // Diagnostic only — failure does not block the daemon from serving.
-    dlog("warn", `pidfile write failed: ${(e as Error).message}`);
-  }
-}
-
-function removePidfileDiagnostic(): void {
-  try {
-    fs.unlinkSync(pidPath());
-  } catch {}
+  if (reason !== null) dlog("warn", `lease write failed: ${reason}`);
 }
 
 let inFlight = 0;
@@ -465,7 +487,11 @@ function shutdown(code: number): void {
   } catch (e) {
     dlog("warn", `sessionState flush failed: ${(e as Error).message}`);
   }
-  removePidfileDiagnostic();
+  // [LAW:one-source-of-truth] Remove the lease only if it still names us. A
+  // displaced daemon (socket stolen, thief wrote its own lease) must not delete
+  // the live owner's lease on its way out, or the next EADDRINUSE would read
+  // `absent` and reclaim the thief's live socket — cascading the theft.
+  removeLeaseIfOwned(leasePath(), process.pid);
   closeLog();
   process.exit(code);
 }

package/src/daemon/socket-lease.ts

@@ -0,0 +1,181 @@
+import fs from "node:fs";
+import process from "node:process";
+
+// ─── Socket ownership lease ──────────────────────────────────────────────────
+//
+// [LAW:one-source-of-truth] The authority for "who owns this socket path" is a
+// lease file DERIVED FROM the socket path (one lease per socket identity), not a
+// connect probe. The prior probe (connect + classify the error code) was a
+// representation lie on macOS/BSD: connect(2) on a LIVE AF_UNIX listener whose
+// accept backlog is full returns ECONNREFUSED — indistinguishable from a dead
+// socket — so under load the probe judged healthy-but-slow daemons dead and
+// their sockets were stolen, minting immortal orphans (see
+// brandon-daemon-lifecycle-2b3).
+//
+// [FRAMING:representation] The lease records the owner's pid; liveness is
+// kill(pid, 0) — the kernel's process table, which is load-independent truth
+// about process existence. A connect sample is load-dependent hearsay and must
+// never be the authority that destroys another daemon's socket.
+
+// What a lease read yielded. Distinguishing absent / unreadable / owned keeps
+// the arbitration decision a full enumeration over raw inputs (see
+// arbitrateSocket) rather than collapsing the ambiguous cases early.
+export type LeaseRead =
+  | { kind: "absent" }
+  | { kind: "unreadable"; detail: string }
+  | { kind: "owned"; pid: number };
+
+// The EADDRINUSE arbitration outcome. The path already exists (something bound
+// it or a stale file remains); this says whether a LIVE owner holds it.
+export type SocketArbitration =
+  | { kind: "attach-and-exit"; reason: string }
+  | { kind: "reclaim"; reason: string };
+
+// Diagnostic-rich lease payload. `pid` is the authority (liveness); the rest is
+// operator diagnostics carried in the same file so the lease subsumes the old
+// diagnostic pidfile — one file, one identity root.
+export interface LeaseRecord {
+  pid: number;
+  version: number;
+  binPath: string | undefined;
+  startedAt: string;
+}
+
+// [LAW:effects-at-boundaries][LAW:dataflow-not-control-flow] The whole
+// arbitration is a pure fold: (raw lease read, injected liveness predicate) →
+// decision. kill(2) is the sole effect and it is injected, so every branch is
+// exercised by input enumeration with no real processes. Full input space:
+//   owned + alive  → attach-and-exit (a live owner holds the path; we are a
+//                    duplicate — exit so the incumbent keeps serving)
+//   owned + dead   → reclaim (owner crashed; the socket is stale)
+//   absent         → reclaim (no lease to consult — a pre-lease or crashed
+//                    daemon left a stale socket; prefer availability)
+//   unreadable     → reclaim (can't prove a live owner — same)
+//
+// Failure directions:
+//   false-dead (steal a live socket) — made self-healing by the ownership
+//     self-check (brandon-daemon-lifecycle-2b3.2).
+//   false-alive (the lease pid is alive but is NOT this daemon — a crashed
+//     daemon's pid recycled to an unrelated process) — we attach-and-exit
+//     without serving. Short-lived recycle self-corrects next tick; a LONG-LIVED
+//     recycle reads alive on every start, so no daemon comes up until the stale
+//     lease is cleared. Fully closing this needs a pid-identity fingerprint
+//     (process start-time, or an fd/flock held for the daemon's lifetime) — the
+//     lock-based liveness the epic deferred. connect() can't substitute: it
+//     can't tell a busy-live daemon with a full accept backlog (ECONNREFUSED —
+//     the exact storm this replaces) from a recycled non-daemon pid. It is
+//     strictly rarer than that storm (needs an unclean death skipping lease
+//     cleanup AND a pid recycle to a long-lived process within the respawn
+//     window).
+// Reclaiming on missing/unreadable is the availability-preferring direction — a
+// stale socket with no reclaimer is a hard no-service stall, strictly worse than
+// a transient double-serve that self-heals.
+export function arbitrateSocket(
+  read: LeaseRead,
+  isAlive: (pid: number) => boolean,
+): SocketArbitration {
+  if (read.kind === "owned") {
+    return isAlive(read.pid)
+      ? {
+          kind: "attach-and-exit",
+          reason: `live owner pid=${read.pid} holds the socket`,
+        }
+      : { kind: "reclaim", reason: `owner pid=${read.pid} is gone (ESRCH)` };
+  }
+  if (read.kind === "absent") {
+    return {
+      kind: "reclaim",
+      reason: "no lease — stale socket, no live owner",
+    };
+  }
+  return {
+    kind: "reclaim",
+    reason: `unreadable lease (${read.detail}) — cannot prove a live owner`,
+  };
+}
+
+// [LAW:no-silent-failure] Every non-happy path becomes a typed `unreadable`
+// with the reason inline, never a swallowed default that pretends the lease said
+// something. ENOENT is the one benign case → `absent`.
+export function readLease(leasePath: string): LeaseRead {
+  let raw: string;
+  try {
+    raw = fs.readFileSync(leasePath, "utf8");
+  } catch (e) {
+    const code = (e as NodeJS.ErrnoException).code;
+    if (code === "ENOENT") return { kind: "absent" };
+    return {
+      kind: "unreadable",
+      detail: `read failed: ${(e as Error).message}`,
+    };
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (e) {
+    return { kind: "unreadable", detail: `bad JSON: ${(e as Error).message}` };
+  }
+  const pid = (parsed as { pid?: unknown } | null)?.pid;
+  if (typeof pid !== "number" || !Number.isInteger(pid) || pid <= 0) {
+    return {
+      kind: "unreadable",
+      detail: `no valid pid (got ${JSON.stringify(pid)})`,
+    };
+  }
+  return { kind: "owned", pid };
+}
+
+// Write our lease after we win the bind. Overwrite-on-write: whoever holds the
+// socket right now replaces whatever stale lease a dead owner left.
+//
+// [LAW:no-ambient-temporal-coupling] Atomic publish: write a uniquely-named temp
+// sibling then rename onto the lease path. POSIX rename within a directory is
+// atomic, so a concurrent reader (a second daemon's EADDRINUSE arbitration) sees
+// either the old lease or the complete new one — never a truncated/empty file
+// mid-write, which would read as `unreadable` and force a false reclaim of this
+// daemon's live socket. The unique temp name means it is always freshly created,
+// so its 0600 mode always applies (0600 has no group/world bits for any umask to
+// need re-tightening) and rename carries that mode across. Returns null on
+// success, a reason on failure.
+export function writeLease(
+  leasePath: string,
+  record: LeaseRecord,
+): string | null {
+  const tmp = `${leasePath}.${process.pid}.tmp`;
+  try {
+    fs.writeFileSync(tmp, JSON.stringify(record), { mode: 0o600 });
+    fs.renameSync(tmp, leasePath);
+    return null;
+  } catch (e) {
+    const reason = (e as Error).message;
+    // [LAW:no-silent-failure] Best-effort temp cleanup, but don't swallow a real
+    // failure: ENOENT means the temp was never created (write failed first) —
+    // benign; any other unlink error means the temp WAS created and now leaks,
+    // so append it to the reason rather than hiding it behind the primary error.
+    try {
+      fs.unlinkSync(tmp);
+    } catch (cleanupErr) {
+      if ((cleanupErr as NodeJS.ErrnoException).code !== "ENOENT") {
+        return `${reason}; also failed to remove temp ${tmp}: ${(cleanupErr as Error).message}`;
+      }
+    }
+    return reason;
+  }
+}
+
+// [LAW:one-source-of-truth] Only the owner mutates its lease. A daemon that was
+// displaced (its socket stolen, the thief wrote a new lease) must NOT delete the
+// current owner's lease on its way out — that would make the next EADDRINUSE
+// read `absent` and reclaim the live thief's socket, cascading the theft. So
+// remove only when the lease still names us.
+export function removeLeaseIfOwned(leasePath: string, myPid: number): void {
+  const read = readLease(leasePath);
+  if (read.kind === "owned" && read.pid === myPid) {
+    try {
+      fs.unlinkSync(leasePath);
+    } catch {
+      // Best-effort cleanup; a leftover lease naming a dead pid is harmless
+      // (the next daemon reads it, kill(pid,0)→ESRCH, reclaims).
+    }
+  }
+}