@promptctl/cc-candybar 1.16.0 → 1.17.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@promptctl/cc-candybar",
-  "version": "1.16.0",
+  "version": "1.17.1",
   "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.16.0",
-    "@promptctl/cc-candybar-darwin-x64": "1.16.0",
-    "@promptctl/cc-candybar-linux-x64": "1.16.0",
-    "@promptctl/cc-candybar-linux-arm64": "1.16.0"
+    "@promptctl/cc-candybar-darwin-arm64": "1.17.1",
+    "@promptctl/cc-candybar-darwin-x64": "1.17.1",
+    "@promptctl/cc-candybar-linux-x64": "1.17.1",
+    "@promptctl/cc-candybar-linux-arm64": "1.17.1"
   },
   "pnpm": {
     "supportedArchitectures": {

package/src/config/default-dsl-config.ts

@@ -185,6 +185,18 @@ export const DEFAULT_DSL_CONFIG = {
     },
     "session.id": { kind: "input", path: "session_id", default: "" },
     version: { kind: "input", path: "version", default: "" },
+    // [LAW:one-source-of-truth] The daemon-resolved effective theme name —
+    // effectiveThemeName(sessionState.theme, globals.palette), the SAME name the
+    // rendered basePalette is built from. A theme-picker config's trigger reads
+    // `{{ .theme.effective }}` to show the active theme, so the label and the
+    // colors trace to one resolution and cannot drift — no per-config restating
+    // of the initial theme (which JSON5, being inert data, cannot derive). The
+    // daemon always provides it; the "" default is the unreachable-absence floor.
+    "theme.effective": {
+      kind: "input",
+      path: "theme.effective",
+      default: "",
+    },
 
     // [LAW:one-source-of-truth] The usable terminal width for THIS render —
     // the exact post-reserve cell count FlexStrip wraps to. renderDsl injects

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/render-payload.ts

@@ -33,7 +33,6 @@ import type { ContextProvider } from "../segments/context.js";
 import type { MetricsProvider } from "../segments/metrics.js";
 import type { TmuxService } from "../segments/tmux.js";
 import type { GitDataProvider } from "./cache/git.js";
-import type { SessionStateRW } from "./session-state.js";
 
 // ─── Augmented payload shape ─────────────────────────────────────────────────
 
@@ -54,7 +53,16 @@ export interface RenderPayload extends ClaudeHookData {
 
   readonly git?: GitPayload;
   readonly tmux?: { readonly session: string };
-  readonly theme?: string;
+  // [LAW:one-source-of-truth] The daemon-resolved effective theme name —
+  // effectiveThemeName(sessionState.theme, globals.palette). The SAME value the
+  // rendered basePalette is built from, surfaced so a trigger label can display
+  // the active theme WITHOUT the config restating it (the label and the colors
+  // trace to one resolution and cannot drift).
+  // [LAW:types-are-the-program] REQUIRED, not optional: the daemon resolves it
+  // every render and buildRenderPayload includes it unconditionally, so the
+  // domain truth is "always present". A `?` here would let a callsite believe it
+  // could be undefined and guard defensively against an impossibility.
+  readonly theme: { readonly effective: string };
 
   // Usage-family. Each provider returns null when it has no data (no
   // transcript yet, no rate-limit window active, etc.); we drop the field
@@ -206,7 +214,6 @@ export interface RenderPayloadDeps {
   readonly contextProvider: ContextProvider;
   readonly metricsProvider: MetricsProvider;
   readonly tmuxService: TmuxService;
-  readonly sessionState: SessionStateRW;
   // [LAW:single-enforcer] The log capability for every provider lane:
   // buildRenderPayload is the ONE place lane failures are logged, so the
   // providers' interiors never log and never double-log.
@@ -568,6 +575,13 @@ export async function buildRenderPayload(
   // registration; passing it in (rather than recomputing per render) keeps
   // the hot path free of the BFS + extractTemplateRefs cost.
   neededInputPaths: ReadonlySet<string>,
+  // [LAW:one-source-of-truth] The effective theme name, resolved ONCE by the
+  // daemon (effectiveThemeName(sessionState.theme, globals.palette)) and used
+  // for BOTH the rendered basePalette and this payload field — so a trigger
+  // label reading `.theme.effective` can never disagree with the colors. Passed
+  // in (not re-resolved here) because the daemon already computes it for the
+  // palette; this is that same value, threaded to the sole payload assembler.
+  effectiveTheme: string,
 ): Promise<RenderPayload> {
   const wants = (prefix: string): boolean =>
     anyPathStartsWith(neededInputPaths, prefix);
@@ -718,15 +732,6 @@ export async function buildRenderPayload(
         }
       : undefined;
 
-  // [LAW:one-source-of-truth] The theme variable surfaces the session's
-  // resolved theme so the toolbar/tray DSL templates can encode it into
-  // cc-candybar:// URLs without re-resolving. SessionState owns the value;
-  // we mirror it onto the payload, not redeclare it.
-  const themeRaw = wants("theme")
-    ? deps.sessionState.get(hookData.session_id, "theme")
-    : undefined;
-  const theme = typeof themeRaw === "string" ? themeRaw : undefined;
-
   // home is always available — it's a single env-var read, no I/O cost.
   // Letting the gate skip it would add a branch with no win.
   // [LAW:single-enforcer] All path-shaped payload fields are normalized
@@ -778,7 +783,11 @@ export async function buildRenderPayload(
     ...(home !== undefined && { home }),
     ...(gitProjection.git !== undefined && { git: gitProjection.git }),
     ...(tmuxValue !== undefined && { tmux: { session: tmuxValue } }),
-    ...(theme !== undefined && { theme }),
+    // [LAW:one-source-of-truth] Always present — the daemon resolves the
+    // effective theme every render (for basePalette), and this is that value.
+    // No `wants` gate: it costs nothing (a string already in hand) and a
+    // config that reads `.theme.effective` must always find it.
+    theme: { effective: effectiveTheme },
     ...(sessionPayload !== undefined && { session: sessionPayload }),
     ...(todayPayload !== undefined && { today: todayPayload }),
     ...(costPerHour !== undefined && { burn: { costPerHour } }),

package/src/daemon/server.ts

@@ -6,10 +6,17 @@ import { parseArgs } from "node:util";
 import {
   daemonDir,
   ensureSocketParentSafe,
-  pidPath,
+  leasePath,
+  leasePathFor,
   socketPath,
   sessionStatePath,
 } from "./paths";
+import {
+  arbitrateSocket,
+  readLease,
+  removeLeaseIfOwned,
+  writeLease,
+} from "./socket-lease";
 import { dlog, closeLog } from "./log";
 import {
   PROTOCOL_VERSION,
@@ -184,6 +191,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 +212,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,61 +266,21 @@ 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] Claim ownership FIRST — before chmod or
+  // any other post-bind 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 (brandon-daemon-lifecycle-2b3.2) 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}`,
@@ -365,40 +343,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 +432,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);
 }
@@ -745,24 +716,30 @@ async function handleRequest(req: Request): Promise<HandledRequest> {
       // No special-case branches — same composition every render.
       let body = "";
       if (entry.state !== null) {
+        // [LAW:one-source-of-truth] Resolve the effective theme ONCE — the
+        // session's chosen theme (SessionState) over the config default. This
+        // single name drives BOTH the payload's `theme.effective` field (the
+        // trigger label reads it) AND the rendered basePalette below, so a label
+        // and the colors can never disagree. Resolved here, before the payload
+        // build, so it can be threaded into the sole payload assembler.
+        const effectiveTheme = effectiveThemeName(
+          sessionState.get(req.hookData.session_id, "theme"),
+          entry.state.config.globals.palette,
+        );
         const payload = await buildRenderPayload(
           req.hookData,
           payloadDeps,
           req.cwd,
           entry.state.neededInputPaths,
+          effectiveTheme,
         );
         // [LAW:one-source-of-truth][LAW:dataflow-not-control-flow] basePalette
-        // is derived per render from the effective theme — the session's chosen
-        // theme (SessionState) over the config default — so a theme click
-        // recolors the whole bar on the next render. Not frozen on the cache
-        // entry (one entry serves many sessions). resolverForThemeName memoizes,
-        // so the per-render cost is one Map lookup once the theme is warm.
-        const basePalette = resolverForThemeName(
-          effectiveThemeName(
-            sessionState.get(req.hookData.session_id, "theme"),
-            entry.state.config.globals.palette,
-          ),
-        );
+        // is derived from the same effective theme resolved above — so a theme
+        // click recolors the whole bar on the next render. Not frozen on the
+        // cache entry (one entry serves many sessions). resolverForThemeName
+        // memoizes, so the per-render cost is one Map lookup once the theme is
+        // warm.
+        const basePalette = resolverForThemeName(effectiveTheme);
         // [LAW:one-type-per-behavior][LAW:dataflow-not-control-flow] The powerline
         // cap/separator SHAPE, resolved per render the exact way the theme is: the
         // session's clicked style (SessionState) over the config default over the
@@ -1139,7 +1116,6 @@ const payloadDeps = {
   contextProvider,
   metricsProvider,
   tmuxService,
-  sessionState,
   // [LAW:single-enforcer] buildRenderPayload is the one log site for the
   // outcome-carrying provider lanes (git, cache).
   log: dlog,

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).
+    }
+  }
+}