@promptctl/cc-candybar 1.17.2 → 1.17.4

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];