@promptctl/cc-candybar 1.17.1 → 1.17.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@promptctl/cc-candybar",
-  "version": "1.17.1",
+  "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.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"
+    "@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/server.ts

@@ -17,6 +17,11 @@ import {
   removeLeaseIfOwned,
   writeLease,
 } from "./socket-lease";
+import {
+  makeOwnershipWatch,
+  readSocketIdentity,
+  type SocketIdentity,
+} from "./socket-ownership";
 import { dlog, closeLog } from "./log";
 import {
   PROTOCOL_VERSION,
@@ -267,12 +272,44 @@ function handleAddressInUse(server: net.Server, sockPath: string): void {
 }
 
 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: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);
@@ -287,6 +324,24 @@ function onListening(sockPath: string): void {
   );
   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 ---

package/src/daemon/socket-ownership.ts

@@ -0,0 +1,165 @@
+import fs from "node:fs";
+import { type DaemonLogger } from "./log";
+
+// ─── Socket ownership self-check ─────────────────────────────────────────────
+//
+// [LAW:single-enforcer] "Serving implies owning the socket path" is a temporal
+// invariant every daemon component assumes and none enforced. The socket-theft
+// storm (brandon-daemon-lifecycle-2b3) proved it false: a daemon whose socket
+// was unlinked + rebound by a reclaimer kept running forever (no idle shutdown,
+// no watchdog in production, RSS backstop only), holding ~400MB each — 28
+// daemons bound in one hour with ZERO voluntary exits. This module is that
+// invariant's single enforcer: a displaced daemon exits within one check
+// interval, making ANY displacement self-healing regardless of which bug caused
+// it.
+//
+// [FRAMING:representation] Ownership of a filesystem entry IS its kernel
+// identity: (st_dev, st_ino). We never unlink + rebind our OWN socket during our
+// lifetime, so that identity is stable for as long as we hold the path. A
+// reclaimer that displaces us unlinks the path and binds a fresh socket → a NEW
+// inode (or, briefly, no file at all). So "the identity now equals the identity
+// 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.
+
+// 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.
+export interface SocketIdentity {
+  dev: number;
+  ino: number;
+}
+
+// What re-reading the socket path's identity yielded. Distinguishing
+// present / absent / unreadable keeps the ownership decision a full enumeration
+// over raw inputs (see checkOwnership) rather than collapsing the ambiguous
+// cases early — the same shape as socket-lease.ts's LeaseRead.
+export type IdentityRead =
+  | { kind: "present"; identity: SocketIdentity }
+  | { kind: "absent" }
+  | { kind: "unreadable"; detail: string };
+
+// The self-check outcome. `owned` is the ONLY proof-of-ownership state; every
+// other input maps to `displaced` (fail toward exit).
+export type OwnershipCheck =
+  | { kind: "owned" }
+  | { kind: "displaced"; reason: string };
+
+export const DEFAULT_OWNERSHIP_CHECK_INTERVAL_MS = 5000;
+
+// [LAW:no-silent-failure] The sole effect (statSync) is lifted to a typed
+// boundary read: ENOENT → `absent` (the path was unlinked, not yet rebound),
+// any other error → `unreadable` with the reason inline, never a swallowed
+// default. statSync (not lstatSync) follows a symlink deliberately — it reads
+// the identity of whatever a CLIENT connecting to the path would actually reach,
+// which is exactly what "do I still own what clients hit" asks.
+export function readSocketIdentity(sockPath: string): IdentityRead {
+  try {
+    const st = fs.statSync(sockPath);
+    return { kind: "present", identity: { dev: st.dev, ino: st.ino } };
+  } catch (e) {
+    const code = (e as NodeJS.ErrnoException).code;
+    if (code === "ENOENT") return { kind: "absent" };
+    return { kind: "unreadable", detail: (e as Error).message };
+  }
+}
+
+// [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)
+//
+// [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.
+export function checkOwnership(
+  bound: SocketIdentity,
+  now: IdentityRead,
+): OwnershipCheck {
+  if (now.kind === "present") {
+    if (now.identity.dev === bound.dev && now.identity.ino === bound.ino) {
+      return { kind: "owned" };
+    }
+    return {
+      kind: "displaced",
+      reason: `socket replaced (bound dev=${bound.dev} ino=${bound.ino}, now dev=${now.identity.dev} ino=${now.identity.ino})`,
+    };
+  }
+  if (now.kind === "absent") {
+    return {
+      kind: "displaced",
+      reason: "socket path gone (ENOENT) — unlinked by a reclaimer",
+    };
+  }
+  return {
+    kind: "displaced",
+    reason: `socket path unreadable (${now.detail}) — cannot prove ownership`,
+  };
+}
+
+// [LAW:locality-or-seam] The identity read, the shutdown funnel, and the log
+// sink are injected, not reached for ambiently — so a unit test drives every
+// branch (swap the inode, delete the path) against a fake shutdown with no real
+// daemon, mirroring makeLimits. The real wiring injects
+// `() => readSocketIdentity(sockPath)` and the daemon's single shutdown().
+export interface OwnershipWatchDeps {
+  bound: SocketIdentity;
+  readIdentity: () => IdentityRead;
+  shutdown: (code: number) => void;
+  log: DaemonLogger;
+  intervalMs?: number;
+}
+
+export interface OwnershipWatchHandle {
+  // Run one check now; funnels through shutdown(0) on the first `displaced`.
+  // Returns the decision so callers/tests can assert without timers.
+  check(): OwnershipCheck;
+  arm(intervalMs?: number): { disarm(): void };
+}
+
+export function makeOwnershipWatch(
+  deps: OwnershipWatchDeps,
+): OwnershipWatchHandle {
+  // [LAW:single-enforcer] Latch like limits' `triggered`: displacement funnels
+  // shutdown exactly once (one log line, one shutdown call), even though
+  // shutdown() is itself idempotent. Serving implies owning through ONE exit.
+  let displaced = false;
+
+  function check(): OwnershipCheck {
+    const decision = checkOwnership(deps.bound, deps.readIdentity());
+    if (decision.kind === "displaced" && !displaced) {
+      displaced = true;
+      deps.log(
+        "warn",
+        `ownership self-check: ${decision.reason}; shutting down`,
+      );
+      deps.shutdown(0);
+    }
+    return decision;
+  }
+
+  function arm(
+    intervalMs: number = deps.intervalMs ?? DEFAULT_OWNERSHIP_CHECK_INTERVAL_MS,
+  ): { disarm(): void } {
+    const timer = setInterval(() => {
+      // [LAW:no-ambient-temporal-coupling] Self-disarm once displaced: the watch
+      // has funneled its single shutdown, so stop polling — no zombie statSync
+      // fires during the shutdown window (a hung shutdown reaches its SIGKILL
+      // backstop at 500ms). The timer's whole lifecycle lives here in arm(),
+      // mirroring armBinaryWatch which clears its interval before shutting down.
+      if (check().kind === "displaced") clearInterval(timer);
+    }, intervalMs);
+    // unref so the check never keeps the process alive on its own — it only ever
+    // hastens an exit, never delays one.
+    timer.unref();
+    return { disarm: () => clearInterval(timer) };
+  }
+
+  return { check, arm };
+}