@promptctl/cc-candybar 1.17.1 → 1.17.3

package/package.json

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

package/src/daemon/acquire.ts

@@ -1,8 +1,14 @@
 import fs from "node:fs";
 import net from "node:net";
+import path from "node:path";
 import { launchDetachedSync } from "../proc/launch";
 import process from "node:process";
-import { socketPath, spawnLockPath, daemonDir } from "./paths";
+import {
+  socketPath,
+  spawnLockPath,
+  spawnCooldownPath,
+  daemonDir,
+} from "./paths";
 
 // [LAW:single-enforcer] One primitive per runtime that owns the entire
 // "obtain a daemon" verb. Every spawn site in the Node runtime now flows
@@ -133,6 +139,28 @@ async function spawnAndWaitForReady(
   outerDeadline: number,
   reasonSuffix: string,
 ): Promise<ObtainResult> {
+  const readyDeadline = Math.min(
+    Date.now() + spawnReadyTimeoutMs,
+    outerDeadline,
+  );
+
+  // [LAW:dataflow-not-control-flow] The spawn-rate bound is consulted as data,
+  // not a mode. If a spawn was attempted within SPAWN_COOLDOWN_MS, one is
+  // already in flight — do NOT add another Node process; wait for the in-flight
+  // boot. This keeps obtainDaemon under the same global rate cap as the kick
+  // path, so the rate bound holds for EVERY spawn site [LAW:one-source-of-truth].
+  if (!claimSpawnCooldown()) {
+    // [LAW:no-silent-failure] This failure's cause is the cooldown gate, not the
+    // lock path we arrived through — so it does NOT inherit reasonSuffix (which
+    // tags lock-held vs lock-fallback *spawn* provenance). We never spawned here.
+    return (await pollUntilReady(connectTimeoutMs, readyDeadline))
+      ? { kind: "attached" }
+      : {
+          kind: "failed",
+          reason: "spawn on cooldown; no daemon became ready during the wait",
+        };
+  }
+
   // [LAW:no-defensive-null-guards] obtainDaemon is typed Promise<ObtainResult>.
   // A synchronous throw from child_process.spawn (ENOENT, invalid options)
   // must become a typed failure, not a rejected promise.
@@ -151,20 +179,27 @@ async function spawnAndWaitForReady(
       reason: `spawn returned false${reasonSuffix}`,
     };
   }
-  const readyDeadline = Math.min(
-    Date.now() + spawnReadyTimeoutMs,
-    outerDeadline,
-  );
+  return (await pollUntilReady(connectTimeoutMs, readyDeadline))
+    ? { kind: "started" }
+    : {
+        kind: "failed",
+        reason: `daemon did not bind in time${reasonSuffix}`,
+      };
+}
+
+// Poll the socket until a daemon answers or the deadline elapses. Shared by the
+// spawn path (→ "started") and the cooldown-blocked wait path (→ "attached"):
+// both need "did a daemon come up in time", they differ only in how they label
+// the outcome.
+async function pollUntilReady(
+  connectTimeoutMs: number,
+  readyDeadline: number,
+): Promise<boolean> {
   while (Date.now() < readyDeadline) {
-    if (await canConnect(socketPath(), connectTimeoutMs)) {
-      return { kind: "started" };
-    }
+    if (await canConnect(socketPath(), connectTimeoutMs)) return true;
     await sleep(20);
   }
-  return {
-    kind: "failed",
-    reason: `daemon did not bind in time${reasonSuffix}`,
-  };
+  return false;
 }
 
 // Synchronous fire-and-forget kick — used for "daemon-miss" recovery where
@@ -214,7 +249,7 @@ export function obtainDaemonKick(opts: { spawn?: () => boolean } = {}): void {
       process.stderr.write(
         `cc-candybar: spawn-lock held ${ageMs}ms (likely crashed holder) — spawning unlocked\n`,
       );
-      safeSpawn(spawnFn);
+      cooldownGatedSpawn(spawnFn);
     }
     return;
   }
@@ -222,16 +257,26 @@ export function obtainDaemonKick(opts: { spawn?: () => boolean } = {}): void {
     process.stderr.write(
       `cc-candybar: spawn-lock unavailable (${lock.reason}) — spawning unlocked\n`,
     );
-    safeSpawn(spawnFn);
+    cooldownGatedSpawn(spawnFn);
     return;
   }
   try {
-    safeSpawn(spawnFn);
+    cooldownGatedSpawn(spawnFn);
   } finally {
     releaseSpawnLock();
   }
 }
 
+// [LAW:single-enforcer] Every kick spawn site routes through here, so the
+// spawn-rate bound is applied at exactly one boundary — mirror of Rust's
+// spawn_daemon_rate_limited. On cooldown we do nothing: a spawn was attempted
+// within SPAWN_COOLDOWN_MS and is likely still booting; the kick is
+// fire-and-forget, so "already in flight" is a complete answer.
+function cooldownGatedSpawn(spawnFn: () => boolean): void {
+  if (!claimSpawnCooldown()) return;
+  safeSpawn(spawnFn);
+}
+
 function spawnLockAgeMs(): number | null {
   try {
     const st = fs.statSync(spawnLockPath());
@@ -260,6 +305,93 @@ function safeSpawn(spawnFn: () => boolean): void {
   }
 }
 
+// ─── Spawn cooldown (shared spawn-RATE bound) ────────────────────────────────
+//
+// [LAW:one-source-of-truth] spawn.lock dedups spawns at one INSTANT; the
+// cooldown bounds them over TIME. Without it, the Rust kick — which releases
+// spawn.lock milliseconds after forking, before the 0.5-3s Node boot window —
+// re-spawns on every render tick during an outage (spawn rate ≈ tick rate:
+// dozens/sec, process-table exhaustion). One file's mtime records the last spawn
+// ATTEMPT; both runtimes consult it. The constant and filename are mirrored TS↔
+// Rust (scripts/check-protocol.mjs). Worst case with the bound: ~20 spawns/min
+// globally, each of which exits cleanly via the sibling socket-lease defenses.
+// Exported for the boundary unit tests (test/daemon-acquire.test.ts), which pin
+// the window arithmetic against the exact constant the same way the Rust unit
+// tests do — so a TS↔Rust decision divergence at a boundary is caught even
+// though check-protocol only diffs the constant's value.
+export const SPAWN_COOLDOWN_MS = 3_000;
+
+// [LAW:effects-at-boundaries] The window arithmetic — the subtle part: a
+// future-mtime garbage record (beyond the stale-lock window) must not pin the
+// cooldown forever, while a small negative age is just ms-truncation of
+// Date.now() against the higher-precision fs mtime and still counts as a
+// just-recorded attempt — is a pure function of the record's age, extracted from
+// the fs read so it is unit-tested without touching the filesystem. Mirrors the
+// Rust cooldown_decision. `null` age (missing/unreadable file) allows (first
+// spawn); the mtime IS the timestamp, so "unparseable timestamp" is
+// unrepresentable by construction.
+export type CooldownDecision =
+  | { kind: "allow" }
+  | { kind: "allow-future-garbage"; futureMs: number }
+  | { kind: "deny" };
+
+export function cooldownDecision(ageMs: number | null): CooldownDecision {
+  if (ageMs === null) return { kind: "allow" };
+  if (ageMs < -STALE_LOCK_MS)
+    return { kind: "allow-future-garbage", futureMs: -ageMs };
+  if (ageMs < SPAWN_COOLDOWN_MS) return { kind: "deny" };
+  return { kind: "allow" };
+}
+
+// [LAW:single-enforcer] The sole authority on daemon-spawn RATE. Returns true —
+// and RECORDS the attempt (updating spawn.cooldown's mtime to now) — when a
+// spawn is permitted; false when an attempt was recorded within
+// SPAWN_COOLDOWN_MS. Recording-on-grant (BEFORE the caller spawns) is
+// load-bearing: a spawn that then throws or returns false still counts against
+// the rate, so a broken binary is not retried in a tight loop. A future-mtime
+// garbage record warns loudly and falls toward ALLOWING the spawn
+// [LAW:no-silent-failure].
+function claimSpawnCooldown(): boolean {
+  const path = spawnCooldownPath();
+  const decision = cooldownDecision(cooldownAgeMs(path));
+  if (decision.kind === "deny") return false;
+  if (decision.kind === "allow-future-garbage") {
+    process.stderr.write(
+      `cc-candybar: spawn.cooldown mtime is ${decision.futureMs}ms in the future — ignoring and spawning\n`,
+    );
+  }
+  recordSpawnAttempt(path);
+  return true;
+}
+
+function cooldownAgeMs(path: string): number | null {
+  try {
+    return Date.now() - fs.statSync(path).mtimeMs;
+  } catch {
+    return null;
+  }
+}
+
+function recordSpawnAttempt(filePath: string): void {
+  // [LAW:composability] Self-sufficient — ensure the state dir exists rather
+  // than leaning on an ambient ensureStateDir() precondition, so any spawn site
+  // routing through claimSpawnCooldown records correctly (mirrors Rust's
+  // record_spawn_attempt). Content is human-diagnostic only; the mtime is the
+  // authority. A write failure means no cooldown recorded — worst case one extra
+  // spawn, which bind() arbitrates — but surface it loudly rather than silently
+  // un-bound the rate [LAW:no-silent-failure].
+  try {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, `${process.pid} ${Date.now()}\n`, {
+      mode: 0o600,
+    });
+  } catch (e) {
+    process.stderr.write(
+      `cc-candybar: could not record spawn.cooldown: ${(e as Error).message}\n`,
+    );
+  }
+}
+
 // ─── Spawn-lock (Node side) ──────────────────────────────────────────────────
 //
 // O_EXLOCK / fcntl(F_SETLK) aren't reliably exposed across Node platforms, so
@@ -274,7 +406,9 @@ function safeSpawn(spawnFn: () => boolean): void {
 // lock is a thundering-herd optimization, so a missed dedup just means one
 // extra Node process eats a bind() race and exits.
 
-const STALE_LOCK_MS = 10_000;
+// Exported for the cooldownDecision boundary tests. Mirrored TS↔Rust (diffed by
+// check-protocol) since both runtimes apply it to the same spawn.cooldown file.
+export const STALE_LOCK_MS = 10_000;
 
 let heldLock: { fd: number; path: string } | null = null;
 

package/src/daemon/paths.ts

@@ -146,6 +146,17 @@ export function spawnLockPath(): string {
   return path.join(stateDir(), "spawn.lock");
 }
 
+// [LAW:one-source-of-truth] The spawn-RATE bound (as distinct from spawn.lock's
+// instantaneous dedup) is anchored to one file's mtime beside spawn.lock: the
+// time of the last daemon-spawn ATTEMPT. Both runtimes gate on the SAME file, so
+// the filename is mirrored TS↔Rust (rust-client/src/main.rs SPAWN_COOLDOWN_FILE)
+// and diffed by scripts/check-protocol.mjs — a drift would silently split the
+// rate bound in two.
+const SPAWN_COOLDOWN_FILE = "spawn.cooldown";
+export function spawnCooldownPath(): string {
+  return path.join(stateDir(), SPAWN_COOLDOWN_FILE);
+}
+
 export function logPath(): string {
   return path.join(stateDir(), "daemon.log");
 }

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 };
+}