@promptctl/cc-candybar 1.17.3 → 1.17.4

package/package.json

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

package/src/daemon/process-fingerprint.ts

@@ -0,0 +1,135 @@
+import { launchSync, type LaunchOpts, type LaunchResult } from "../proc/launch";
+
+// ─── Process start-time fingerprint ──────────────────────────────────────────
+//
+// [FRAMING:representation] A bare pid is an under-constrained identity: the
+// kernel recycles pids, so "a process with pid 989 exists" does NOT prove "989
+// is the same process that wrote this lease". A crashed daemon whose pid the OS
+// later hands to an unrelated long-lived process reads `alive` on every
+// subsequent start, so no daemon ever comes up (brandon-daemon-lifecycle-2b3.4
+// RESIDUAL 1 — the inverse of the socket-theft storm). The kernel ALSO stamps
+// each process with a start-time it never rewinds within that pid's life;
+// (pid, start-time) is the pair that actually IS a process identity, so a
+// recycled pid is provably a DIFFERENT process (different start-time).
+//
+// [LAW:one-source-of-truth] The authority is the kernel's process identity, not
+// a bare pid. `ps -o lstart=` exposes the start-time on every Unix we ship to
+// (darwin + linux). The reported token is treated as OPAQUE — compared by string
+// equality, never parsed — so there is no date-format representation to drift
+// [FRAMING:representation]: a producer/consumer parse mismatch is unrepresentable
+// when neither side parses. That opaque-equality invariant holds ONLY if the
+// GENERATOR is deterministic. `ps -o lstart=` is strftime-formatted (locale) via
+// `localtime()` (timezone), so the SAME process renders different tokens across a
+// locale change OR a timezone change (TZ env, DST, tzdata update). We pin BOTH on
+// the `ps` subprocess — `LC_ALL=C` (dominates any ambient LC_TIME/LC_ALL) and
+// `TZ=UTC` — so the token is a locale- and timezone-invariant UTC rendering of
+// the start instant, and equality is sound.
+
+// A read of a pid's kernel start-time. Only TWO outcomes, because nothing
+// derivable from a `ps` exit code can SOUNDLY prove a process is dead — a
+// non-zero exit means "no start-time to report", which conflates a genuinely
+// absent pid with an access failure (hardened `/proc`/`hidepid`, a
+// permission-denied read of a live process). A `gone` state produced from that
+// would be an over-claim ([LAW:types-are-the-program]) that could false-dead a
+// live owner and reclaim its socket. So:
+//   start       — the pid is live and this is its start-time token (the ONLY
+//                 thing `ps` can assert soundly: it printed a row).
+//   unavailable — `ps` reported no start-time (absent OR unreadable OR errored).
+//                 Callers defer to kill(pid,0), the sound liveness test, which
+//                 correctly reclaims a truly-dead pid and spares a live one.
+// The fingerprint's unique contribution is the `start`+mismatch case (a recycled
+// pid whose live start-time differs from the lease); everything else falls back
+// to kill, no worse than before the fingerprint existed.
+export type StartTimeRead =
+  | { kind: "start"; token: string }
+  | { kind: "unavailable"; detail: string };
+
+// The subprocess boundary, injected so the parse/branch logic is exercised by
+// input enumeration with a fake launcher while the real path runs the real `ps`.
+export type Launcher = (opts: LaunchOpts) => LaunchResult;
+
+// [LAW:effects-at-boundaries][LAW:single-enforcer] The sole effect (spawning
+// `ps`) goes through the one subprocess enforcer, `launchSync`. The ONLY sound
+// signal `ps` gives is a printed start-time row (a live pid we could read);
+// [LAW:no-silent-failure] every other outcome — absent pid, access failure,
+// spawn-error, timeout — is `unavailable`, deferring the alive/dead call to
+// kill(pid,0) rather than risk declaring a live owner dead from a `ps` exit
+// code that cannot distinguish "gone" from "cannot read".
+export function readStartTime(
+  pid: number,
+  launch: Launcher = launchSync,
+): StartTimeRead {
+  const res = launch({
+    bin: "ps",
+    args: ["-o", "lstart=", "-p", String(pid)],
+    category: "process-fingerprint",
+    timeoutMs: 2000,
+    // [FRAMING:representation] Pin BOTH locale and timezone so the token is
+    // deterministic across daemons — the writer and reader must render the same
+    // process identically for opaque string equality to be sound. LC_ALL=C fixes
+    // the strftime format; TZ=UTC fixes localtime(), so DST / TZ / tzdata changes
+    // can't make one live process render two different start-time strings.
+    env: { ...process.env, LC_ALL: "C", TZ: "UTC" },
+  });
+  if (res.ok) {
+    const token = res.stdout.trim();
+    if (token.length > 0) return { kind: "start", token };
+    // Exit 0 with empty output is anomalous (a live pid always lists) — don't
+    // mint an empty-string fingerprint; defer to kill.
+    return { kind: "unavailable", detail: "ps produced no start-time" };
+  }
+  const detail =
+    res.reason === "spawn-error"
+      ? (res.error ?? "ps spawn failed")
+      : `ps ${res.reason} (exit ${res.exitCode})`;
+  return { kind: "unavailable", detail };
+}
+
+export interface LivenessDeps {
+  readStartTime: (pid: number) => StartTimeRead;
+  pidAlive: (pid: number) => boolean;
+}
+
+// [LAW:dataflow-not-control-flow] The liveness verdict is a pure fold over the
+// start-time read + the lease's recorded token. Full input space:
+//   read=start + token matches lease   → true  (same process still alive)
+//   read=start + token differs         → false (a DIFFERENT process holds the
+//                                        pid — a recycle, or a restarted daemon)
+//   read=unavailable                   → kill(pid,0) fallback (the sound
+//                                        alive/dead test: a truly-dead pid →
+//                                        false → reclaim; a live pid ps couldn't
+//                                        read → true → spared)
+//   lease token = null (unfingerprinted at write, e.g. a host without `ps`) →
+//                                        kill(pid,0) fallback for the same reason
+//
+// [LAW:no-silent-failure] Only the `start`+mismatch case comes from the
+// fingerprint; every ambiguous `ps` outcome defers to kill, so the DANGEROUS
+// direction (declaring a live daemon dead → stealing its socket, the storm this
+// epic fights) never happens merely because `ps` could not answer. The only
+// thing forfeited when `ps` cannot answer is detecting a recycled pid.
+export function sameLiveProcess(
+  pid: number,
+  leaseToken: string | null,
+  deps: LivenessDeps,
+): boolean {
+  if (leaseToken === null) return deps.pidAlive(pid);
+  const read = deps.readStartTime(pid);
+  switch (read.kind) {
+    case "start":
+      return read.token === leaseToken;
+    case "unavailable":
+      return deps.pidAlive(pid);
+  }
+}
+
+// Read THIS process's own start-time to stamp into its lease. `unavailable`
+// (no `ps`) collapses to `null` — the lease records "unfingerprinted", and every
+// reader of it falls back to kill(pid,0) via sameLiveProcess. A dead result is
+// impossible for our own live pid; if it somehow occurs we also record null.
+export function readOwnStartTime(
+  pid: number,
+  read: (pid: number) => StartTimeRead = readStartTime,
+): string | null {
+  const r = read(pid);
+  return r.kind === "start" ? r.token : null;
+}

package/src/daemon/server.ts

@@ -22,6 +22,11 @@ import {
   readSocketIdentity,
   type SocketIdentity,
 } from "./socket-ownership";
+import {
+  readStartTime,
+  readOwnStartTime,
+  sameLiveProcess,
+} from "./process-fingerprint";
 import { dlog, closeLog } from "./log";
 import {
   PROTOCOL_VERSION,
@@ -127,8 +132,16 @@ const BIN_CHECK_INTERVAL_MS = 60 * 1000;
 // connection. Any uncaught error exits non-zero; the next client obtains a
 // fresh daemon via obtainDaemonKick() (fire-and-forget caller) or
 // obtainDaemon() (caller waits for readiness) in src/daemon/acquire.ts.
+// [LAW:one-source-of-truth] Our own kernel start-time, read once at startup and
+// stamped into our lease so a future daemon's arbitration can prove whether our
+// pid still names THIS process or a recycled ghost (process-fingerprint.ts).
+// null when this host cannot fingerprint (no `ps`) — readers then fall back to
+// kill(pid,0), no worse than before the fingerprint existed.
+let myStartTime: string | null = null;
+
 export function runDaemon(): void {
   fs.mkdirSync(daemonDir(), { recursive: true });
+  myStartTime = readOwnStartTime(process.pid);
   // [LAW:single-enforcer] Verify the socket parent is uid==me + mode 0700 +
   // not a symlink before we bind. Without this check, a same-host attacker
   // could pre-create the predictable `/tmp/cc-candybar-<uid>` directory and
@@ -236,7 +249,11 @@ 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);
+  const decision = arbitrateSocket(
+    readLease(leasePathFor(sockPath)),
+    (pid, startTime) =>
+      sameLiveProcess(pid, startTime, { readStartTime, pidAlive }),
+  );
   if (decision.kind === "attach-and-exit") {
     dlog("info", `EADDRINUSE: ${decision.reason} — exiting`);
     process.exit(0);
@@ -280,20 +297,19 @@ function onListening(sockPath: string): void {
   // 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.
+  // [FRAMING:representation] This inode capture still cannot close the capture
+  // race on its own: 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 stat the path and capture the
+  // THIEF's inode as "ours". No race-free handle on our own socket's path
+  // identity exists (an AF_UNIX listener's fstat is a different namespace's
+  // inode), so the captured inode cannot be made trustworthy. But that is no
+  // longer the immortal orphan it was (brandon-daemon-lifecycle-2b3.4 RESIDUAL
+  // 2): the ownership self-check now ALSO requires the lease to still name us,
+  // and a real thief writes its own pid into the lease — so a displaced daemon
+  // drains within a bounded number of intervals instead of reading `owned`
+  // forever (see checkOwnership). The absent/unreadable case below still exits
+  // toward the SAFE direction without writing a lease that would stomp a thief's.
   const boundRead = readSocketIdentity(sockPath);
   if (boundRead.kind !== "present") {
     dlog(
@@ -330,15 +346,20 @@ function onListening(sockPath: string): void {
 // --- 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.
+// path over time" (brandon-daemon-lifecycle-2b3.2). Each interval it re-reads
+// BOTH representations a displacer can touch — the path's kernel identity (still
+// the inode we bound?) and the lease (still names our pid?) — and drains through
+// the SAME shutdown funnel as signals, the RSS backstop, and the watchdog on
+// either mismatch. The lease arm closes the capture race (RESIDUAL 2): a thief
+// that stole our socket inside the bind→listening tick, which the inode arm
+// cannot see because we captured the thief's inode, is caught the moment the
+// thief writes its own pid into the lease. No parallel exit path.
 function armOwnershipWatch(sockPath: string, bound: SocketIdentity): void {
   makeOwnershipWatch({
     bound,
+    myPid: process.pid,
     readIdentity: () => readSocketIdentity(sockPath),
+    readLease: () => readLease(leasePathFor(sockPath)),
     shutdown: (code) => shutdown(code),
     log: dlog,
   }).arm();
@@ -418,7 +439,7 @@ function writeLeaseFile(sockPath: string): void {
     pid: process.pid,
     version: PROTOCOL_VERSION,
     binPath: process.argv[1],
-    startedAt: new Date().toISOString(),
+    startTime: myStartTime,
   });
   if (reason !== null) dlog("warn", `lease write failed: ${reason}`);
 }

package/src/daemon/socket-lease.ts

@@ -12,18 +12,25 @@ import process from "node:process";
 // 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.
+// [FRAMING:representation] The lease records the owner's pid AND its kernel
+// start-time (see process-fingerprint.ts). Liveness is "the SAME process is
+// still alive" — kill(pid,0) alone lies when a crashed daemon's pid is recycled
+// to an unrelated live process (reads `alive` forever → no daemon ever comes up,
+// brandon-daemon-lifecycle-2b3.4 RESIDUAL 1). Comparing the start-time makes a
+// recycled pid provably a different process. Both signals are the kernel's
+// load-independent truth about process identity; 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.
+// arbitrateSocket) rather than collapsing the ambiguous cases early. `startTime`
+// is the owner's kernel start-time fingerprint, or null when the writing host
+// could not fingerprint (no `ps`) — the reader then falls back to kill(pid,0).
 export type LeaseRead =
   | { kind: "absent" }
   | { kind: "unreadable"; detail: string }
-  | { kind: "owned"; pid: number };
+  | { kind: "owned"; pid: number; startTime: string | null };
 
 // The EADDRINUSE arbitration outcome. The path already exists (something bound
 // it or a stale file remains); this says whether a LIVE owner holds it.
@@ -31,56 +38,61 @@ 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.
+// Diagnostic-rich lease payload. `(pid, startTime)` is the authority (process
+// identity → liveness); the rest is operator diagnostics carried in the same
+// file so the lease subsumes the old diagnostic pidfile — one file, one identity
+// root. `startTime` is the kernel start-time token (also human-readable, so it
+// doubles as the "daemon started at" diagnostic the old `startedAt` gave), or
+// null when this host could not fingerprint.
 export interface LeaseRecord {
   pid: number;
   version: number;
   binPath: string | undefined;
-  startedAt: string;
+  startTime: string | null;
 }
 
 // [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)
+// decision. Reading process identity is the sole effect and it is injected via
+// `isSameLiveProcess`, so every branch is exercised by input enumeration with no
+// real processes. Full input space:
+//   owned + same-live  → attach-and-exit (the SAME live owner holds the path; we
+//                        are a duplicate — exit so the incumbent keeps serving)
+//   owned + not-same   → reclaim (owner crashed, OR its pid was recycled to an
+//                        unrelated process — either way 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)
+//
+// [LAW:one-source-of-truth] `isSameLiveProcess(pid, startTime)` consults the
+// kernel's process identity ((pid, start-time), see process-fingerprint.ts), not
+// a bare pid. This closes RESIDUAL 1: a crashed daemon's pid recycled to a
+// long-lived process now reads NOT-same (different start-time) → reclaim, so a
+// daemon comes up instead of every start attaching to a ghost forever.
 //
 // 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).
+//     self-check (brandon-daemon-lifecycle-2b3.2), and now far rarer: the
+//     start-time match will not false-negative a live owner unless the host
+//     cannot fingerprint at all, in which case sameLiveProcess falls back to
+//     kill(pid,0) — the prior behavior, no worse.
 // 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,
+  isSameLiveProcess: (pid: number, startTime: string | null) => boolean,
 ): SocketArbitration {
   if (read.kind === "owned") {
-    return isAlive(read.pid)
+    return isSameLiveProcess(read.pid, read.startTime)
       ? {
           kind: "attach-and-exit",
           reason: `live owner pid=${read.pid} holds the socket`,
         }
-      : { kind: "reclaim", reason: `owner pid=${read.pid} is gone (ESRCH)` };
+      : {
+          kind: "reclaim",
+          reason: `owner pid=${read.pid} is gone or recycled`,
+        };
   }
   if (read.kind === "absent") {
     return {
@@ -115,14 +127,30 @@ export function readLease(leasePath: string): LeaseRead {
   } catch (e) {
     return { kind: "unreadable", detail: `bad JSON: ${(e as Error).message}` };
   }
-  const pid = (parsed as { pid?: unknown } | null)?.pid;
+  const record = parsed as { pid?: unknown; startTime?: unknown } | null;
+  const pid = record?.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 };
+  // startTime is the process fingerprint. A present value must be a string;
+  // absent/null means "unfingerprinted" (an older lease, or a host without
+  // `ps`) and the reader falls back to kill(pid,0). A present-but-non-string is
+  // malformed → unreadable (never silently coerce a lie into a fingerprint).
+  const rawStartTime = record?.startTime;
+  if (
+    rawStartTime !== undefined &&
+    rawStartTime !== null &&
+    typeof rawStartTime !== "string"
+  ) {
+    return {
+      kind: "unreadable",
+      detail: `invalid startTime (got ${JSON.stringify(rawStartTime)})`,
+    };
+  }
+  return { kind: "owned", pid, startTime: rawStartTime ?? null };
 }
 
 // Write our lease after we win the bind. Overwrite-on-write: whoever holds the

package/src/daemon/socket-ownership.ts

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import { type DaemonLogger } from "./log";
+import { type LeaseRead } from "./socket-lease";
 
 // ─── Socket ownership self-check ─────────────────────────────────────────────
 //
@@ -21,6 +22,21 @@ import { type DaemonLogger } from "./log";
 // I bound" is the exact, load-independent test for continued ownership — unlike
 // a connect probe, which the sibling .1 removed precisely because it lied under
 // load.
+//
+// [FRAMING:representation] The inode alone leaves ONE hole (RESIDUAL 2, the
+// capture race): if a thief completes unlink + rebind inside the sub-millisecond
+// window between our bind() and our 'listening' callback, we stat the path and
+// capture the THIEF's inode as "ours" — so the inode check reads `owned` forever
+// against the wrong identity. We cannot make that captured inode trustworthy (an
+// AF_UNIX listener's fstat reports a different namespace's inode than stat(path),
+// so there is no race-free "the inode I truly bound"). But a real thief, being a
+// daemon, writes its OWN pid into the lease. So ownership requires a SECOND
+// condition: the lease must still name us. A displacer must touch one of the two
+// representations — steal the socket (inode changes) or overwrite the lease (pid
+// changes) — so requiring BOTH drains any orphan within a bounded number of
+// intervals. No live process can share our live pid, so the lease pid alone
+// distinguishes "the lease still names me" (the start-time fingerprint is only
+// needed by the sibling arbitration, which reasons about a possibly-DEAD pid).
 
 // The kernel identity of the bound socket file. (dev, ino) is the unique
 // identity of a filesystem entry; ino alone can be reused across devices.
@@ -64,43 +80,64 @@ export function readSocketIdentity(sockPath: string): IdentityRead {
 }
 
 // [LAW:effects-at-boundaries][LAW:dataflow-not-control-flow] A pure fold:
-// (identity captured at bind, current identity read) → decision. No effects, so
-// every branch is exercised by input enumeration. Full input space:
-//   present + same identity → owned      (we still hold the path we bound)
-//   present + different     → displaced  (a reclaimer unlinked + rebound; new inode)
-//   absent (ENOENT)         → displaced  (path unlinked, reclaimer not yet rebound)
-//   unreadable              → displaced  (cannot PROVE ownership → fail toward exit)
+// (identity captured at bind, current identity read, my pid, current lease read)
+// → decision. No effects, so every branch is exercised by input enumeration.
+// Ownership is the CONJUNCTION of two conditions; either failing → displaced:
+//   inode:  present + same identity as bound     (we still hold the path we bound)
+//   lease:  owned + pid == mine                  (the lease still names us)
+// Inode failures:  different inode / absent / unreadable → a reclaimer displaced
+//   us (or we cannot prove otherwise). Lease failures: a thief overwrote the
+//   lease with its own pid, or the lease vanished/broke — either way we no
+//   longer hold the authority.
 //
-// [FRAMING:representation] Only `present + same identity` proves ownership;
-// everything else is `displaced`. This is the strongest-true theorem: serving
-// must IMPLY owning, so anything short of positive proof drains and exits. The
-// failure direction is deliberately safe — a false `displaced` (exit while
-// actually owning, e.g. a transient stat error) just lets the real owner/thief
-// serve and the next client respawns; a false `owned` is the immortal orphan we
-// are killing. Always err toward exit.
+// [FRAMING:representation] Only "still holding my bound socket AND still named by
+// the lease" proves ownership; anything short is `displaced`. This is the
+// strongest-true theorem for "serving implies owning", checked against BOTH
+// mutable representations a displacer can touch. The failure direction is
+// deliberately safe — a false `displaced` (exit while actually owning) just lets
+// the real owner serve and the next client respawns; a false `owned` is the
+// immortal orphan we are killing. Always err toward exit.
 export function checkOwnership(
   bound: SocketIdentity,
   now: IdentityRead,
+  myPid: number,
+  lease: LeaseRead,
 ): OwnershipCheck {
-  if (now.kind === "present") {
-    if (now.identity.dev === bound.dev && now.identity.ino === bound.ino) {
-      return { kind: "owned" };
-    }
+  const inodeFailure = inodeDisplacement(bound, now);
+  if (inodeFailure !== null) {
+    return { kind: "displaced", reason: inodeFailure };
+  }
+  if (lease.kind !== "owned") {
     return {
       kind: "displaced",
-      reason: `socket replaced (bound dev=${bound.dev} ino=${bound.ino}, now dev=${now.identity.dev} ino=${now.identity.ino})`,
+      reason: `lease not held (${lease.kind}) — no longer the socket owner`,
     };
   }
-  if (now.kind === "absent") {
+  if (lease.pid !== myPid) {
     return {
       kind: "displaced",
-      reason: "socket path gone (ENOENT) — unlinked by a reclaimer",
+      reason: `lease reassigned (names pid=${lease.pid}, we are pid=${myPid}) — a reclaimer overwrote it`,
     };
   }
-  return {
-    kind: "displaced",
-    reason: `socket path unreadable (${now.detail}) — cannot prove ownership`,
-  };
+  return { kind: "owned" };
+}
+
+// Returns the displacement reason if the current path identity no longer matches
+// what we bound, or null if the inode still proves ownership.
+function inodeDisplacement(
+  bound: SocketIdentity,
+  now: IdentityRead,
+): string | null {
+  if (now.kind === "present") {
+    if (now.identity.dev === bound.dev && now.identity.ino === bound.ino) {
+      return null;
+    }
+    return `socket replaced (bound dev=${bound.dev} ino=${bound.ino}, now dev=${now.identity.dev} ino=${now.identity.ino})`;
+  }
+  if (now.kind === "absent") {
+    return "socket path gone (ENOENT) — unlinked by a reclaimer";
+  }
+  return `socket path unreadable (${now.detail}) — cannot prove ownership`;
 }
 
 // [LAW:locality-or-seam] The identity read, the shutdown funnel, and the log
@@ -110,7 +147,9 @@ export function checkOwnership(
 // `() => readSocketIdentity(sockPath)` and the daemon's single shutdown().
 export interface OwnershipWatchDeps {
   bound: SocketIdentity;
+  myPid: number;
   readIdentity: () => IdentityRead;
+  readLease: () => LeaseRead;
   shutdown: (code: number) => void;
   log: DaemonLogger;
   intervalMs?: number;
@@ -132,7 +171,12 @@ export function makeOwnershipWatch(
   let displaced = false;
 
   function check(): OwnershipCheck {
-    const decision = checkOwnership(deps.bound, deps.readIdentity());
+    const decision = checkOwnership(
+      deps.bound,
+      deps.readIdentity(),
+      deps.myPid,
+      deps.readLease(),
+    );
     if (decision.kind === "displaced" && !displaced) {
       displaced = true;
       deps.log(

package/src/proc/launch.ts

@@ -45,6 +45,10 @@ export const LAUNCH_CATEGORIES = [
   "install.pbcopy",
   "install.open",
   "daemon-spawn",
+  // Process start-time fingerprint (`ps -o lstart=`) for socket-lease liveness
+  // (process-fingerprint.ts). Spawned only at daemon start + EADDRINUSE
+  // arbitration — never per render — so it needs no rate limit.
+  "process-fingerprint",
 ] as const;
 
 export type LaunchCategory = (typeof LAUNCH_CATEGORIES)[number];