@promptctl/cc-candybar 1.21.0 → 1.23.0

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.
@@ -157,6 +185,17 @@ export function spawnCooldownPath(): string {
   return path.join(stateDir(), SPAWN_COOLDOWN_FILE);
 }
 
+// [LAW:one-source-of-truth] Sibling of spawn.cooldown: that file's mtime
+// answers "when was a spawn last attempted"; this file's content answers
+// "how many attempts in a row have failed to converge on a live daemon" —
+// the consecutive-non-convergence streak that widens the cooldown window
+// (see effectiveCooldownMs in acquire.ts). Same filename mirrored TS↔Rust,
+// diffed by scripts/check-protocol.mjs.
+const SPAWN_BACKOFF_FILE = "spawn.backoff";
+export function spawnBackoffPath(): string {
+  return path.join(stateDir(), SPAWN_BACKOFF_FILE);
+}
+
 export function logPath(): string {
   return path.join(stateDir(), "daemon.log");
 }

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,
@@ -42,6 +48,7 @@ import { WatcherRegistry } from "./cache/watchers";
 import { RuntimeStats } from "./stats";
 import { makeLimits, realLimitsDeps, type LimitsHandle } from "./limits";
 import { armParentWatchdog, anchorFromEnv, pidAlive } from "./parent-watchdog";
+import { resetSpawnBackoff } from "./acquire";
 import { SessionState } from "./session-state";
 import { FileSessionStorage } from "./session-state-file";
 import { VERBS, BadVerbArgs, SESSION_CONFIG_OVERRIDE_KEY } from "./verbs";
@@ -141,28 +148,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 +180,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
@@ -340,6 +378,11 @@ function onListening(sockPath: string): void {
     "info",
     `daemon up: pid=${process.pid} v=${PROTOCOL_VERSION} sock=${sockPath}`,
   );
+  // [LAW:single-enforcer] This bind is the one process-wide fact that answers
+  // "did an outage just end" — see resetSpawnBackoff's doc comment in
+  // acquire.ts. Any consecutive-spawn backoff accumulated getting here no
+  // longer applies once a daemon is actually serving.
+  resetSpawnBackoff();
   armBinaryWatch();
   armLimits();
   armOwnershipWatch(sockPath, boundRead.identity);
@@ -515,6 +558,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

package/src/index.ts

@@ -53,12 +53,14 @@ Configuration:
   to point at a specific file. See the default config for all available options:
     node dist/index.mjs debug --project-dir . --cwd .
 
-Subcommands (macOS):
-  install                  One-shot setup: creates the URL handler app, registers
-                           the cc-candybar:// scheme, and writes the statusLine
-                           command into ~/.claude/settings.json.
-  install-url-handler      Just create + register the URL handler app
-                           (~/Applications/CCCandybarURLHandler.app).
+Subcommands:
+  install                  One-shot setup: stages the runtime (native render
+                           binary + dist bundle) at a stable path, creates the
+                           URL handler app + cc-candybar:// scheme (macOS), and
+                           writes the staged entry as the statusLine command in
+                           ~/.claude/settings.json. Re-run to update.
+  install-url-handler      Just stage the runtime and create + register the URL
+                           handler app (macOS only).
   url-handle URL           Internal — invoked by the URL handler app on
                            cmd-click. Parses cc-candybar://<verb>/<value> and
                            dispatches (currently: copy to clipboard).