@promptctl/cc-candybar 1.21.0 → 1.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@promptctl/cc-candybar",
-  "version": "1.21.0",
+  "version": "1.22.0",
   "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",
@@ -95,10 +95,10 @@
     "mobx": "^6.15.0"
   },
   "optionalDependencies": {
-    "@promptctl/cc-candybar-darwin-arm64": "1.21.0",
-    "@promptctl/cc-candybar-darwin-x64": "1.21.0",
-    "@promptctl/cc-candybar-linux-x64": "1.21.0",
-    "@promptctl/cc-candybar-linux-arm64": "1.21.0"
+    "@promptctl/cc-candybar-darwin-arm64": "1.22.0",
+    "@promptctl/cc-candybar-darwin-x64": "1.22.0",
+    "@promptctl/cc-candybar-linux-x64": "1.22.0",
+    "@promptctl/cc-candybar-linux-arm64": "1.22.0"
   },
   "pnpm": {
     "supportedArchitectures": {

package/src/daemon/fork-bomb-breaker.ts

@@ -0,0 +1,351 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { daemonRegistryDir, ensureOwnedPrivateDir } from "./paths";
+import {
+  readStartTime,
+  sameLiveProcess,
+  type ProcessIdentity,
+} from "./process-fingerprint";
+import { pidAlive } from "./parent-watchdog";
+
+// ─── Daemon-side fork-bomb circuit breaker ───────────────────────────────────
+//
+// [FRAMING:representation] The 192-daemon storm (epic brandon-daemon-lifecycle-
+// gad) happened because every existing single-instance guard (atomic bind(),
+// the socket lease, the ownership self-check, the spawn cooldown) keys off ONE
+// socket path — daemons on DIFFERENT sockets (test isolation's per-file
+// CC_CANDYBAR_SOCKET) never arbitrate each other and pile up unboundedly. .1
+// (test/helpers/daemon-pool.ts) bounds that from the SPAWNER side, but the
+// spawner's own cleanup (afterAll, globalTeardown) fails under the exact
+// fork-exhaustion condition it exists to prevent. This module is the
+// load-INDEPENDENT backstop: a daemon refuses to boot past a sibling ceiling
+// using only its own startup-time read of a shared registry — no external
+// cleanup path required for the invariant to hold.
+//
+// [LAW:one-source-of-truth] The registry lives at daemonRegistryDir() (paths.ts)
+// — a fixed, UID-anchored /tmp path that, like socketPath(), deliberately
+// ignores XDG_STATE_HOME, so isolation overrides can't hide a daemon from the
+// count. Every daemon that does NOT explicitly override
+// CC_CANDYBAR_DAEMON_REGISTRY_DIR lands in the same directory.
+//
+// [FRAMING:representation] The production daemon is a different POPULATION
+// than an isolated (test/dev) instance, not a smaller version of the same one:
+// it is already bounded to exactly one by bind()'s kernel-enforced exclusion on
+// the canonical socket path, so no ceiling can ever be its failure mode — only
+// isolation (an explicit CC_CANDYBAR_SOCKET override) creates the "many
+// coexisting instances" population this breaker exists to bound. Classifying by
+// "is CC_CANDYBAR_SOCKET set" keeps the two populations from ever counting
+// against each other: the production daemon is exempt (and so always boots,
+// however many isolated instances are registered), and isolated instances
+// compete only with each other over the shared ceiling.
+//
+// [FRAMING:representation] admitDaemon's count-then-write (read the registry,
+// decide, write our own entry) is NOT a compare-and-swap — the same accepted
+// tradeoff as test/helpers/daemon-pool.ts's tryClaim. Two daemons starting in
+// the same instant can both observe the same below-ceiling count and both
+// admit, so the ceiling is a soft bound (liveCount can briefly overshoot by
+// the number of true simultaneous spawns), not a strict mutex. A real fix
+// needs a cross-process lock (flock, an O_EXCL pre-registration file); skipped
+// as disproportionate here — this is a load-independent BACKSTOP against a
+// 192-daemon storm, not a precision gate, and the ticket's own acceptance
+// criterion is "a small, asserted ceiling", never exact atomicity. The
+// failure mode of the race is a brief, bounded overshoot that the next boot's
+// stale-sweep does not even need to correct (the overshooting daemons are
+// live, not stale) — categorically smaller than the storm this breaker
+// exists to prevent.
+
+export interface BootDecision {
+  allow: boolean;
+  reason: string;
+}
+
+const DEFAULT_CEILING = 16;
+
+// [LAW:no-silent-failure] `Number(...)`, not `parseInt(...)` — parseInt
+// truncates trailing garbage ("16o" reads as 16, silently accepting a typo
+// that likely meant 160) instead of surfacing it. `Number` requires the
+// WHOLE string to be numeric, so a typo becomes NaN and falls through to the
+// default like any other garbage value.
+export function daemonCeiling(): number {
+  const raw = Number(process.env["CC_CANDYBAR_DAEMON_CEILING"] ?? "");
+  return Number.isInteger(raw) && raw > 0 ? raw : DEFAULT_CEILING;
+}
+
+// [LAW:dataflow-not-control-flow] The whole decision is this one pure fold —
+// full input space:
+//   isolated=false                    → allow, unconditionally (production is
+//                                        already singular via bind(); a
+//                                        ceiling here could only ever refuse
+//                                        the user's one real daemon, which the
+//                                        epic requires never happens)
+//   isolated=true,  count <  ceiling  → allow (below the backstop)
+//   isolated=true,  count >= ceiling  → deny (the fork-bomb condition)
+// [LAW:no-silent-failure] "Fails safe" is achieved by construction here, not by
+// a guard clause: an unreadable/uncountable population reads as count=0 (see
+// countLiveEntries), which always falls in the `allow` branch — the failure
+// direction is never "refuse to boot", it is "undercount and allow".
+export function decideBoot(
+  isolated: boolean,
+  liveSiblingCount: number,
+  ceiling: number,
+): BootDecision {
+  if (!isolated) {
+    return {
+      allow: true,
+      reason:
+        "canonical production socket — exempt (bind() already caps it to one)",
+    };
+  }
+  if (liveSiblingCount >= ceiling) {
+    return {
+      allow: false,
+      reason: `${liveSiblingCount} live isolated daemons registered >= ceiling ${ceiling}`,
+    };
+  }
+  return {
+    allow: true,
+    reason: `${liveSiblingCount} live isolated daemons registered < ceiling ${ceiling}`,
+  };
+}
+
+// A registry entry read, alongside its source path so a stale one can be
+// swept. `null` is every unreadable/corrupt/absent-pid outcome — collapsed
+// early here (unlike readLease's richer enumeration) because the only
+// downstream use is "count it or don't"; there is no distinct action for
+// "unreadable" vs "absent" the way socket-lease arbitration has one.
+export interface RegistryEntry {
+  path: string;
+  identity: ProcessIdentity;
+}
+
+// [LAW:no-silent-failure] Never throws: a directory that doesn't exist yet (no
+// isolated daemon has ever registered) or is transiently unreadable both mean
+// "no known siblings", which is the fail-open direction decideBoot expects.
+export function listRegistryFiles(dir: string): string[] {
+  try {
+    return fs
+      .readdirSync(dir)
+      .filter((f) => f.endsWith(".json"))
+      .map((f) => path.join(dir, f));
+  } catch {
+    return [];
+  }
+}
+
+// Mirrors readSlot (test/helpers/daemon-pool.ts) / readLease's pid validation
+// (socket-lease.ts): a corrupt or unreadable file is excluded from the count
+// rather than treated as a special decision branch — see the module header for
+// why undercounting, never overcounting, is the safe direction here.
+export function readRegistryEntry(filePath: string): ProcessIdentity | null {
+  let raw: string;
+  try {
+    raw = fs.readFileSync(filePath, "utf8");
+  } catch {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(raw) as Partial<ProcessIdentity> | null;
+    const pid = parsed?.pid;
+    if (typeof pid !== "number" || !Number.isInteger(pid) || pid <= 0) {
+      return null;
+    }
+    const startTime =
+      typeof parsed?.startTime === "string" ? parsed.startTime : null;
+    return { pid, startTime };
+  } catch {
+    return null;
+  }
+}
+
+// [LAW:dataflow-not-control-flow] Pure fold over already-read entries + an
+// injected liveness predicate — full branch coverage needs no fs, no real
+// processes: an empty list, an all-dead list, an all-live list, and a mixed
+// list are the entire input space. `sweepStale`, kept in the same pass rather
+// than a second read, is the effect side; the count itself never depends on
+// whether the sweep succeeds.
+export function countLiveEntries(
+  entries: readonly RegistryEntry[],
+  isSameLiveProcess: (pid: number, startTime: string | null) => boolean,
+  sweepStale: (filePath: string) => void,
+): number {
+  let count = 0;
+  for (const entry of entries) {
+    if (isSameLiveProcess(entry.identity.pid, entry.identity.startTime)) {
+      count++;
+    } else {
+      sweepStale(entry.path);
+    }
+  }
+  return count;
+}
+
+export interface BreakerDeps {
+  isolated: boolean;
+  registryDir: string;
+  ceiling: number;
+  pid: number;
+  startTime: string | null;
+  isSameLiveProcess: (pid: number, startTime: string | null) => boolean;
+  listFiles: (dir: string) => string[];
+  readEntry: (filePath: string) => ProcessIdentity | null;
+  removeFile: (filePath: string) => void;
+  writeEntry: (filePath: string, identity: ProcessIdentity) => void;
+  ensureDirSafe: (dir: string) => void;
+}
+
+export interface BreakerResult {
+  decision: BootDecision;
+  // The path this daemon registered at, or null when exempt/refused. Callers
+  // that boot successfully thread this into their shutdown cleanup so the slot
+  // is released promptly instead of waiting for the next boot's stale-sweep.
+  registryPath: string | null;
+}
+
+// [LAW:effects-at-boundaries] The one place that turns the pure fold into a
+// boot/refuse decision by reading + writing the real registry. Exempt
+// (production) daemons never touch the registry at all — not even to read
+// it — so a corrupt or unreadable registry can never affect the one instance
+// the epic requires to always boot.
+export function admitDaemon(deps: BreakerDeps): BreakerResult {
+  if (!deps.isolated) {
+    return { decision: decideBoot(false, 0, deps.ceiling), registryPath: null };
+  }
+  // [LAW:single-enforcer] `ensureDirSafe` — not a bare `ensureOwnedPrivateDir`
+  // call — because the safety boundary differs by registry: the default,
+  // UID-anchored registry sits under the same shared /tmp root the socket
+  // does and needs the two-level check `realBreakerDeps` builds for it (see
+  // its comment); an overridden registry (tests) is the caller's own
+  // directory and needs only the one-level leaf check. `admitDaemon` stays
+  // agnostic to which — it just asks the injected dependency to prove the
+  // directory is safe to use.
+  deps.ensureDirSafe(deps.registryDir);
+  const entries: RegistryEntry[] = [];
+  for (const filePath of deps.listFiles(deps.registryDir)) {
+    const identity = deps.readEntry(filePath);
+    // [LAW:no-silent-failure] Exclude any entry named with OUR OWN pid,
+    // unconditionally — no other currently-live process can ever share it
+    // (the kernel guarantees pid uniqueness among live processes), so such an
+    // entry is always either a stale pid-recycled ghost from a past
+    // incarnation, or moot (we haven't written our own entry yet). This
+    // matters specifically when `ps` is unavailable: `isSameLiveProcess`'s
+    // fallback (bare `pidAlive`) would read OUR OWN pid as alive and
+    // misclassify the ghost as a live sibling, consuming a ceiling slot and
+    // risking a spurious refusal of the one daemon that pid actually names.
+    // Excluding it here means it never reaches that ambiguous check at all.
+    if (identity !== null && identity.pid !== deps.pid) {
+      entries.push({ path: filePath, identity });
+    }
+  }
+  const liveCount = countLiveEntries(
+    entries,
+    deps.isSameLiveProcess,
+    deps.removeFile,
+  );
+  const decision = decideBoot(true, liveCount, deps.ceiling);
+  if (!decision.allow) {
+    return { decision, registryPath: null };
+  }
+  const registryPath = path.join(deps.registryDir, `pid-${deps.pid}.json`);
+  deps.writeEntry(registryPath, { pid: deps.pid, startTime: deps.startTime });
+  return { decision, registryPath };
+}
+
+// Best-effort self-cleanup on shutdown — mirrors removeLeaseIfOwned
+// (socket-lease.ts): only remove the entry if it still names us, so a
+// displaced/superseded record from a different process is never deleted.
+export function releaseRegistration(
+  registryPath: string,
+  myPid: number,
+  readEntry: (filePath: string) => ProcessIdentity | null,
+  removeFile: (filePath: string) => void,
+): void {
+  const entry = readEntry(registryPath);
+  if (entry !== null && entry.pid === myPid) {
+    try {
+      removeFile(registryPath);
+    } catch {
+      // Best-effort; a leftover entry naming a dead pid is harmless — the
+      // next boot's sweep reclaims it.
+    }
+  }
+}
+
+// `myStartTime` is threaded in rather than recomputed here so callers (only
+// server.ts today) fingerprint themselves exactly once at startup and reuse
+// that same read for both the registry entry and the socket lease — two
+// independent `ps` calls could theoretically observe different processes if
+// this pid were somehow recycled between them.
+export function realBreakerDeps(
+  myStartTime: string | null,
+  overrides: Partial<BreakerDeps> = {},
+): BreakerDeps {
+  return {
+    isolated: Boolean(process.env["CC_CANDYBAR_SOCKET"]),
+    registryDir: daemonRegistryDir(),
+    ceiling: daemonCeiling(),
+    pid: process.pid,
+    startTime: myStartTime,
+    isSameLiveProcess: (pid, startTime) =>
+      sameLiveProcess(pid, startTime, { readStartTime, pidAlive }),
+    listFiles: listRegistryFiles,
+    readEntry: readRegistryEntry,
+    removeFile: (filePath) => {
+      try {
+        fs.unlinkSync(filePath);
+      } catch {
+        // best-effort
+      }
+    },
+    // [LAW:one-source-of-truth] Same write-tmp-then-rename shape as
+    // socket-lease.ts's writeLease, so it gets the same cleanup: if
+    // writeFileSync succeeds but renameSync fails, best-effort unlink the tmp
+    // file (tolerating ENOENT — writeFileSync itself may have been what
+    // failed) before rethrowing, so a write failure never leaves an orphaned
+    // `.tmp` file behind (listRegistryFiles only collects `*.json`, so a
+    // stray `.tmp` would never be swept).
+    writeEntry: (filePath, identity) => {
+      const tmp = `${filePath}.${identity.pid}.tmp`;
+      try {
+        fs.writeFileSync(tmp, JSON.stringify(identity), { mode: 0o600 });
+        fs.renameSync(tmp, filePath);
+      } catch (e) {
+        try {
+          fs.unlinkSync(tmp);
+        } catch (cleanupErr) {
+          if ((cleanupErr as NodeJS.ErrnoException).code !== "ENOENT") {
+            // Best-effort cleanup failed for a reason other than "never
+            // created" — the original error is still the one that matters,
+            // so it is not swallowed; a leaked tmp file here is a secondary
+            // symptom the next admission's stale-sweep does not reclaim
+            // (only *.json is collected), but it is not this daemon's job to
+            // retry a failing filesystem.
+          }
+        }
+        throw e;
+      }
+    },
+    // [LAW:single-enforcer] Two levels, mirroring ensureSocketParentSafe's own
+    // shape, but ONLY for the default (unoverridden) registry path: its
+    // parent is the shared UID-anchored /tmp root an attacker could pre-plant
+    // as a symlink before any daemon has ever run, and `lstatSync` only
+    // inspects a path's FINAL component — verifying the leaf alone lets a
+    // symlinked parent be silently followed by `mkdirSync({recursive:true})`,
+    // after which the freshly-created leaf looks perfectly clean (owned by
+    // us, 0700) despite living inside attacker-controlled storage. An
+    // OVERRIDDEN registry dir (CC_CANDYBAR_DAEMON_REGISTRY_DIR, tests only)
+    // has no such shared root by construction — its parent is whatever
+    // directory the caller happened to put it under (a system tmpdir on some
+    // platforms), which is not a boundary this breaker owns or should assert
+    // on; there the one-level leaf check alone is the correct, portable
+    // parity with how ensureSocketParentSafe treats an overridden
+    // CC_CANDYBAR_SOCKET (exactly one level, whatever that parent is).
+    ensureDirSafe: process.env["CC_CANDYBAR_DAEMON_REGISTRY_DIR"]
+      ? ensureOwnedPrivateDir
+      : (dir: string): void => {
+          ensureOwnedPrivateDir(path.dirname(dir));
+          ensureOwnedPrivateDir(dir);
+        },
+    ...overrides,
+  };
+}

package/src/daemon/parent-watchdog.ts

@@ -20,7 +20,14 @@ import process from "node:process";
 
 export const PARENT_PID_ENV = "CC_CANDYBAR_PARENT_PID";
 
-const DEFAULT_POLL_INTERVAL_MS = 1000;
+// [LAW:verifiable-goals] Only ever consulted for an ANCHORED (test) daemon —
+// "outlives-nobody" (the production daemon) arms no timer at all, so
+// tightening this is invisible to production. A dead-runner orphan can live
+// at most one poll tick before the watchdog trips; 250ms (down from 1000ms,
+// brandon-daemon-lifecycle-gad.1) shrinks that window fourfold without
+// meaningfully increasing CPU — polling a single `kill(pid,0)` 4x/sec is
+// negligible next to the daemon work it guards.
+const DEFAULT_POLL_INTERVAL_MS = 250;
 
 export type LivenessAnchor =
   | { kind: "outlives-nobody" }

package/src/daemon/paths.ts

@@ -66,32 +66,43 @@ export function socketPath(): string {
 // Throws on any unsafe state; callers are expected to let the daemon exit.
 // [LAW:no-silent-fallbacks] do NOT auto-rmdir + recreate — a wrong-owner dir
 // is hostile state, not a recoverable error.
-export function ensureSocketParentSafe(sockPath: string): void {
-  const parent = path.dirname(sockPath);
+// [LAW:one-source-of-truth] The owner/mode/symlink verification a private
+// per-uid directory needs is declared once here — both the socket parent
+// (below) and the fork-bomb breaker's daemon registry dir
+// (daemonRegistryDir(), fork-bomb-breaker.ts) sit under the same untrusted
+// shared /tmp root and must reject the identical attack (a pre-created
+// world-writable dir, a planted symlink), so they share one enforcer instead
+// of two copies that could silently drift apart on what "safe" means.
+export function ensureOwnedPrivateDir(dir: string): void {
   // mkdir with mode 0o700; harmless if already exists (mode is not applied
   // post-hoc — we verify it next).
-  fs.mkdirSync(parent, { recursive: true, mode: 0o700 });
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
 
-  const st = fs.lstatSync(parent);
+  const st = fs.lstatSync(dir);
   if (st.isSymbolicLink()) {
-    throw new Error(`socket parent is a symlink: ${parent}`);
+    throw new Error(`directory is a symlink: ${dir}`);
   }
   if (!st.isDirectory()) {
-    throw new Error(`socket parent is not a directory: ${parent}`);
+    throw new Error(`not a directory: ${dir}`);
   }
   const myUid = os.userInfo().uid;
   // getuid is undefined on Windows; we don't ship there, but guard cheaply.
   if (typeof myUid === "number" && st.uid !== myUid) {
     throw new Error(
-      `socket parent is not owned by uid ${myUid}: ${parent} (owner uid=${st.uid})`,
+      `directory is not owned by uid ${myUid}: ${dir} (owner uid=${st.uid})`,
     );
   }
   // Reject any group/world bits — only the owner may traverse.
   if ((st.mode & 0o077) !== 0) {
     throw new Error(
-      `socket parent has unsafe permissions: ${parent} (mode=${(st.mode & 0o777).toString(8)}, expected 0700)`,
+      `directory has unsafe permissions: ${dir} (mode=${(st.mode & 0o777).toString(8)}, expected 0700)`,
     );
   }
+}
+
+export function ensureSocketParentSafe(sockPath: string): void {
+  const parent = path.dirname(sockPath);
+  ensureOwnedPrivateDir(parent);
   // 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.
@@ -138,6 +149,23 @@ export function sessionStatePath(): string {
   return path.join(stateDir(), "session-state.json");
 }
 
+// [LAW:one-source-of-truth] The fork-bomb breaker's daemon-population registry
+// (fork-bomb-breaker.ts) shares socketPath()'s UID-anchored /tmp root and, like
+// it, deliberately ignores XDG_STATE_HOME — the very isolation
+// `CC_CANDYBAR_SOCKET`/`XDG_STATE_HOME` overrides grant a test daemon is the
+// thing this registry exists to see THROUGH, so every daemon on this machine
+// (production and every isolated instance) that does not explicitly override
+// this path lands in the same directory and is counted together.
+// `CC_CANDYBAR_DAEMON_REGISTRY_DIR` is the explicit override, used only by
+// tests of the breaker itself so they don't contend over the machine's real
+// shared registry.
+export function daemonRegistryDir(): string {
+  const override = process.env.CC_CANDYBAR_DAEMON_REGISTRY_DIR;
+  if (override) return override;
+  const uid = os.userInfo().uid;
+  return path.join("/tmp", `cc-candybar-${uid}`, "daemons");
+}
+
 // [LAW:single-enforcer] Caller-side spawn dedup. Held by a client *only* during
 // the spawn window — never for the daemon's lifetime. The actual one-daemon
 // invariant is enforced by atomic bind() on socketPath() inside the daemon.

package/src/daemon/process-fingerprint.ts

@@ -25,6 +25,17 @@ import { launchSync, type LaunchOpts, type LaunchResult } from "../proc/launch";
 // `TZ=UTC` — so the token is a locale- and timezone-invariant UTC rendering of
 // the start instant, and equality is sound.
 
+// [LAW:one-source-of-truth] The (pid, start-time) pair IS a process identity
+// (see the file header) — every owner-of-a-resource record in this codebase
+// (a socket lease, a test-pool slot) names its owner with exactly this shape.
+// Declared once here, the module that owns the process-identity concept, so
+// a future field addition to "what identifies a process" can't drift between
+// independent copies.
+export interface ProcessIdentity {
+  pid: number;
+  startTime: string | null;
+}
+
 // 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

package/src/daemon/server.ts

@@ -27,6 +27,12 @@ import {
   readOwnStartTime,
   sameLiveProcess,
 } from "./process-fingerprint";
+import {
+  admitDaemon,
+  realBreakerDeps,
+  releaseRegistration,
+  readRegistryEntry,
+} from "./fork-bomb-breaker";
 import { dlog, closeLog } from "./log";
 import {
   PROTOCOL_VERSION,
@@ -141,28 +147,23 @@ const BIN_CHECK_INTERVAL_MS = 60 * 1000;
 // 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
-  // squat the socket name. The check applies regardless of CC_CANDYBAR_SOCKET
-  // location — every bind path goes through the same trust precondition.
-  // No symmetric client-side check: the daemon is the sole creator, so a
-  // successful bind already proves the parent is trusted. Failure here surfaces
-  // as a daemon exit; the client falls back to the last cached render.
-  ensureSocketParentSafe(socketPath());
-
-  // Bind disk persistence now that we know we are the daemon process — load
-  // prior session state and become the sole writer of the state file.
-  sessionState.useStorage(
-    new FileSessionStorage(sessionStatePath(), 500, dlog),
-  );
+// The registry path this daemon claimed in the fork-bomb breaker's population
+// registry (fork-bomb-breaker.ts), or null when exempt (the canonical
+// production socket) or never reached (refused before claiming one). Released
+// on shutdown so a graceful exit frees its slot immediately rather than
+// waiting for the next boot's stale-sweep.
+let breakerRegistryPath: string | null = null;
 
+export function runDaemon(): void {
   // Catch-alls log + exit so the supervisor (the next client) can restart us.
   // [LAW:no-defensive-null-guards] These are *trust boundaries* — we are
   // catching all of unknown space, not skipping known optional values.
+  // [LAW:single-enforcer] Registered FIRST, before any of the startup calls
+  // below that can throw synchronously (admitDaemon's ensureDirSafe/writeEntry,
+  // ensureSocketParentSafe) — otherwise an early throw is a raw unhandled
+  // exception (stack trace to stderr, bypassing the clean shutdown(1) log +
+  // SIGKILL backstop) rather than funneling through the same death path as
+  // every other failure mode.
   process.on("uncaughtException", (err) => {
     dlog("error", `uncaughtException: ${err.stack || err.message}`);
     shutdown(1);
@@ -178,6 +179,42 @@ export function runDaemon(): void {
     });
   }
 
+  // [LAW:single-enforcer] The fork-bomb circuit breaker runs FIRST among the
+  // resource-committing steps (no dir created, no socket touched, no session
+  // state loaded) — the whole point of a load-independent backstop is that it
+  // holds even when everything downstream of it is thrashing. Own start-time
+  // must be read first: it is both this check's identity and the lease's
+  // fingerprint later, so it is read exactly once and threaded through both
+  // (see realBreakerDeps' doc comment).
+  myStartTime = readOwnStartTime(process.pid);
+  const admission = admitDaemon(realBreakerDeps(myStartTime));
+  if (!admission.decision.allow) {
+    dlog(
+      "warn",
+      `fork-bomb breaker: ${admission.decision.reason}; refusing to boot`,
+    );
+    shutdown(1);
+    return;
+  }
+  breakerRegistryPath = admission.registryPath;
+
+  fs.mkdirSync(daemonDir(), { recursive: true });
+  // [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
+  // squat the socket name. The check applies regardless of CC_CANDYBAR_SOCKET
+  // location — every bind path goes through the same trust precondition.
+  // No symmetric client-side check: the daemon is the sole creator, so a
+  // successful bind already proves the parent is trusted. Failure here surfaces
+  // as a daemon exit; the client falls back to the last cached render.
+  ensureSocketParentSafe(socketPath());
+
+  // Bind disk persistence now that we know we are the daemon process — load
+  // prior session state and become the sole writer of the state file.
+  sessionState.useStorage(
+    new FileSessionStorage(sessionStatePath(), 500, dlog),
+  );
+
   // [LAW:single-enforcer] Same death funnel as the signals and the RSS backstop:
   // the watchdog calls shutdown(0), it never exits on its own. A production
   // daemon has no spawner to outlive (env unset) and arms an inert handle; only
@@ -515,6 +552,18 @@ function shutdown(code: number): void {
   // 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);
+  // [LAW:one-source-of-truth] Same "only if it still names us" guard as the
+  // lease above, reused via releaseRegistration — a slot this daemon never
+  // claimed (exempt production, or refused before claiming one) is null and
+  // skipped.
+  if (breakerRegistryPath !== null) {
+    releaseRegistration(
+      breakerRegistryPath,
+      process.pid,
+      readRegistryEntry,
+      (p) => fs.unlinkSync(p),
+    );
+  }
   closeLog();
   process.exit(code);
 }

package/src/daemon/socket-lease.ts

@@ -1,6 +1,8 @@
 import fs from "node:fs";
 import process from "node:process";
 
+import type { ProcessIdentity } from "./process-fingerprint";
+
 // ─── Socket ownership lease ──────────────────────────────────────────────────
 //
 // [LAW:one-source-of-truth] The authority for "who owns this socket path" is a
@@ -30,7 +32,7 @@ import process from "node:process";
 export type LeaseRead =
   | { kind: "absent" }
   | { kind: "unreadable"; detail: string }
-  | { kind: "owned"; pid: number; startTime: string | null };
+  | ({ kind: "owned" } & ProcessIdentity);
 
 // The EADDRINUSE arbitration outcome. The path already exists (something bound
 // it or a stale file remains); this says whether a LIVE owner holds it.
@@ -44,11 +46,9 @@ export type SocketArbitration =
 // 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;
+export interface LeaseRecord extends ProcessIdentity {
   version: number;
   binPath: string | undefined;
-  startTime: string | null;
 }
 
 // [LAW:effects-at-boundaries][LAW:dataflow-not-control-flow] The whole