@promptctl/cc-candybar 1.42.1 → 1.43.0

package/src/daemon/parent-watchdog.ts

@@ -1,87 +0,0 @@
-import process from "node:process";
-
-// [LAW:single-enforcer] One owner of the invariant "I must not outlive the
-// process that spawned me." A *production* daemon is spawned detached and is
-// SUPPOSED to outlive its spawner — the render-tick client exits, leaving a
-// warm daemon — so it is anchored to nobody and this watchdog never fires. A
-// daemon spawned by a *transient* process (the Jest worker) must die WITH it:
-// on abnormal exit (SIGKILL, worker crash, suite timeout) the OS reparents the
-// orphan to init and it survives forever. That orphan-to-init survival is the
-// test-daemon leak. The spawner publishes its pid in the environment and every
-// descendant inherits it, so even a detached grand-child daemon stays anchored
-// to the original runner.
-//
-// [LAW:dataflow-not-control-flow] The watchdog runs the same poll every tick;
-// whether it ever trips lives in the anchor VALUE (a pid to outlive, or
-// nobody), derived once from the environment — never in a branch wrapped around
-// the spawn path. Like the RSS backstop in `limits.ts`, it calls `onOrphaned`
-// (the lifecycle `shutdown`) rather than exiting itself, so every daemon-death
-// path funnels through the one enforcer.
-
-export const PARENT_PID_ENV = "CC_CANDYBAR_PARENT_PID";
-
-// [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" }
-  | { kind: "anchored"; pid: number };
-
-// [LAW:no-silent-fallbacks] Three inputs, three outcomes, no overlap: absent →
-// production (outlive nobody); a positive integer → anchor to it; present but
-// malformed → throw. Only the test harness ever sets this variable, so a
-// malformed value is a harness bug; silently degrading to "outlives-nobody"
-// would re-open the very leak this module closes.
-export function anchorFromEnv(env: NodeJS.ProcessEnv): LivenessAnchor {
-  const raw = env[PARENT_PID_ENV];
-  if (raw === undefined) return { kind: "outlives-nobody" };
-  const pid = Number.parseInt(raw, 10);
-  if (!Number.isInteger(pid) || pid <= 0) {
-    throw new Error(
-      `${PARENT_PID_ENV} must be a positive integer pid, got ${JSON.stringify(raw)}`,
-    );
-  }
-  return { kind: "anchored", pid };
-}
-
-export interface ParentWatchdogDeps {
-  anchor: LivenessAnchor;
-  isAlive: (pid: number) => boolean;
-  onOrphaned: (reason: string) => void;
-  intervalMs?: number;
-}
-
-export function armParentWatchdog(deps: ParentWatchdogDeps): {
-  disarm(): void;
-} {
-  // An unanchored daemon has nothing to poll — arming a perpetual no-op timer on
-  // the user's always-running daemon would be pure waste. Returning an inert
-  // handle is the consequence of the data, not a special case in the spawn path.
-  if (deps.anchor.kind === "outlives-nobody") return { disarm: () => {} };
-
-  const { pid } = deps.anchor;
-  const timer = setInterval(() => {
-    if (!deps.isAlive(pid)) deps.onOrphaned(`spawner pid ${pid} gone`);
-  }, deps.intervalMs ?? DEFAULT_POLL_INTERVAL_MS);
-  timer.unref();
-  return { disarm: () => clearInterval(timer) };
-}
-
-export function pidAlive(pid: number): boolean {
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (e) {
-    // ESRCH: the process is gone — orphaned, trip the watchdog. EPERM: a live
-    // process we don't own (the pid was reused by another user) — treat as
-    // alive so a reused pid can never make us shut down a daemon whose real
-    // spawner is still running.
-    return (e as NodeJS.ErrnoException).code === "EPERM";
-  }
-}

package/src/daemon/paths.ts

@@ -1,211 +0,0 @@
-import fs from "node:fs";
-import os from "node:os";
-import path from "node:path";
-
-// XDG Base Directory split:
-//   - daemon runtime (pid, log, heap snapshots, spawn.lock) → $XDG_STATE_HOME/cc-candybar
-//   - filesystem caches (git, usage, last-render) → $XDG_CACHE_HOME/cc-candybar
-//
-// Both default per the XDG spec ($HOME/.local/state and $HOME/.cache). Empty
-// env vars fall through to the defaults. The two roots are kept separate so
-// users can `rm -rf` either one without taking the other down.
-//
-// The socket path is NOT derived from XDG_STATE_HOME — see socketPath() below.
-// The Rust client mirrors both path families in rust-client/src/main.rs; both
-// must agree or the client can't find the daemon's socket.
-
-function xdgEnv(name: string): string | undefined {
-  const v = process.env[name];
-  return v && v.length > 0 ? v : undefined;
-}
-
-export function stateDir(): string {
-  const base =
-    xdgEnv("XDG_STATE_HOME") ?? path.join(os.homedir(), ".local", "state");
-  return path.join(base, "cc-candybar");
-}
-
-export function cacheDir(): string {
-  const base = xdgEnv("XDG_CACHE_HOME") ?? path.join(os.homedir(), ".cache");
-  return path.join(base, "cc-candybar");
-}
-
-export function configDir(): string {
-  const base = xdgEnv("XDG_CONFIG_HOME") ?? path.join(os.homedir(), ".config");
-  return path.join(base, "cc-candybar");
-}
-
-// `daemonDir` kept as the canonical name for the runtime root so existing
-// callers (limits.ts, server.ts) don't need to learn a new term. It now
-// resolves under $XDG_STATE_HOME/cc-candybar instead of ~/.claude/powerline.
-export function daemonDir(): string {
-  return stateDir();
-}
-
-// [LAW:one-source-of-truth] The socket IS the daemon's identity — same as
-// tmux's /tmp/tmux-<uid>/default model. UID is kernel identity: immutable,
-// not overridable by any env var. /tmp is guaranteed on every Unix host and
-// is cleared on reboot, which is fine — the daemon doesn't survive reboots.
-// CC_CANDYBAR_SOCKET is the only explicit override for intentional isolation
-// (tests, dev, multiple intentional instances).
-export function socketPath(): string {
-  const override = process.env.CC_CANDYBAR_SOCKET;
-  if (override) return override;
-  const uid = os.userInfo().uid;
-  return path.join("/tmp", `cc-candybar-${uid}`, "socket");
-}
-
-// [LAW:single-enforcer] The daemon is the sole creator of the socket parent
-// directory. If we enforce "this dir is uid==me + mode 0700 + not a symlink"
-// at bind time, then by induction every successful bind happened under a
-// trusted parent — and any client reaching the socket via the canonical path
-// reached one our daemon owns. A foreign-uid or world-writable squat triggers
-// a refusal, turning a silent-MITM attempt into a visible daemon failure (the
-// client sees no response, the user sees the last cached render).
-//
-// 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.
-// [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(dir, { recursive: true, mode: 0o700 });
-
-  const st = fs.lstatSync(dir);
-  if (st.isSymbolicLink()) {
-    throw new Error(`directory is a symlink: ${dir}`);
-  }
-  if (!st.isDirectory()) {
-    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(
-      `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(
-      `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.
-  //
-  // [LAW:single-enforcer] The lease (`${sockPath}.lease`) gets the SAME gate:
-  // it is now load-bearing (ownership authority — readLease follows a symlink
-  // and a planted `lease → /dev/null` would read `absent`/`unreadable`, forcing
-  // a false reclaim that unlinks a live daemon's socket). One enforcer certifies
-  // every path we bind/read/write under this parent, so the socket and its lease
-  // can never diverge on "is this a symlink".
-  for (const p of [sockPath, leasePathFor(sockPath)]) {
-    try {
-      if (fs.lstatSync(p).isSymbolicLink()) {
-        throw new Error(`path is a symlink: ${p}`);
-      }
-    } catch (e) {
-      const code = (e as NodeJS.ErrnoException).code;
-      if (code !== "ENOENT") throw e;
-    }
-  }
-}
-
-// [LAW:one-source-of-truth] The socket-ownership lease is DERIVED FROM the
-// socket path, so it shares the socket's identity root. The old diagnostic
-// pidfile lived under $XDG_STATE_HOME while the socket lived under /tmp — two
-// identity roots for one instance, and CC_CANDYBAR_SOCKET isolated only one of
-// them. Anchoring the lease to socketPath() means test/dev isolation via
-// CC_CANDYBAR_SOCKET isolates the lease too. The lease subsumes the old
-// diagnostic pidfile: it carries the owner pid (the reclaim authority) plus the
-// same diagnostic fields.
-// [LAW:one-source-of-truth] The socket→lease derivation lives here alone, so
-// leasePath() (the runtime authority path) and ensureSocketParentSafe's symlink
-// gate agree by construction. Takes the socket path explicitly so the safety
-// check certifies the exact path it was handed, not a re-derived one.
-export function leasePathFor(sockPath: string): string {
-  return `${sockPath}.lease`;
-}
-
-export function leasePath(): string {
-  return leasePathFor(socketPath());
-}
-
-export function sessionStatePath(): string {
-  return path.join(stateDir(), "session-state.json");
-}
-
-// [LAW:one-source-of-truth] The daemon-owned overrides layer for persistent
-// config writes (candybar-config-engine-71o.2): a click that mutates the
-// bundled/user-file DEFAULT (as opposed to `set`, which mutates per-session
-// state) lands here — never in the hand-authored config file itself. Sibling
-// of sessionStatePath(): same root, same single-writer daemon, same test
-// isolation via XDG_STATE_HOME/CC_CANDYBAR_SOCKET-derived overrides.
-export function configOverridesPath(): string {
-  return path.join(stateDir(), "config-overrides.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.
-// This file is a thundering-herd optimization, not the load-bearing lock.
-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);
-}
-
-// [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

@@ -1,146 +0,0 @@
-import { launchSync, type LaunchOpts, type LaunchResult } from "../proc/launch";
-
-// ─── Process start-time fingerprint ──────────────────────────────────────────
-//
-// [FRAMING:representation] A bare pid is an under-constrained identity: the
-// kernel recycles pids, so "a process with pid 989 exists" does NOT prove "989
-// is the same process that wrote this lease". A crashed daemon whose pid the OS
-// later hands to an unrelated long-lived process reads `alive` on every
-// subsequent start, so no daemon ever comes up (brandon-daemon-lifecycle-2b3.4
-// RESIDUAL 1 — the inverse of the socket-theft storm). The kernel ALSO stamps
-// each process with a start-time it never rewinds within that pid's life;
-// (pid, start-time) is the pair that actually IS a process identity, so a
-// recycled pid is provably a DIFFERENT process (different start-time).
-//
-// [LAW:one-source-of-truth] The authority is the kernel's process identity, not
-// a bare pid. `ps -o lstart=` exposes the start-time on every Unix we ship to
-// (darwin + linux). The reported token is treated as OPAQUE — compared by string
-// equality, never parsed — so there is no date-format representation to drift
-// [FRAMING:representation]: a producer/consumer parse mismatch is unrepresentable
-// when neither side parses. That opaque-equality invariant holds ONLY if the
-// GENERATOR is deterministic. `ps -o lstart=` is strftime-formatted (locale) via
-// `localtime()` (timezone), so the SAME process renders different tokens across a
-// locale change OR a timezone change (TZ env, DST, tzdata update). We pin BOTH on
-// the `ps` subprocess — `LC_ALL=C` (dominates any ambient LC_TIME/LC_ALL) and
-// `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
-// absent pid with an access failure (hardened `/proc`/`hidepid`, a
-// permission-denied read of a live process). A `gone` state produced from that
-// would be an over-claim ([LAW:types-are-the-program]) that could false-dead a
-// live owner and reclaim its socket. So:
-//   start       — the pid is live and this is its start-time token (the ONLY
-//                 thing `ps` can assert soundly: it printed a row).
-//   unavailable — `ps` reported no start-time (absent OR unreadable OR errored).
-//                 Callers defer to kill(pid,0), the sound liveness test, which
-//                 correctly reclaims a truly-dead pid and spares a live one.
-// The fingerprint's unique contribution is the `start`+mismatch case (a recycled
-// pid whose live start-time differs from the lease); everything else falls back
-// to kill, no worse than before the fingerprint existed.
-export type StartTimeRead =
-  | { kind: "start"; token: string }
-  | { kind: "unavailable"; detail: string };
-
-// The subprocess boundary, injected so the parse/branch logic is exercised by
-// input enumeration with a fake launcher while the real path runs the real `ps`.
-export type Launcher = (opts: LaunchOpts) => LaunchResult;
-
-// [LAW:effects-at-boundaries][LAW:single-enforcer] The sole effect (spawning
-// `ps`) goes through the one subprocess enforcer, `launchSync`. The ONLY sound
-// signal `ps` gives is a printed start-time row (a live pid we could read);
-// [LAW:no-silent-failure] every other outcome — absent pid, access failure,
-// spawn-error, timeout — is `unavailable`, deferring the alive/dead call to
-// kill(pid,0) rather than risk declaring a live owner dead from a `ps` exit
-// code that cannot distinguish "gone" from "cannot read".
-export function readStartTime(
-  pid: number,
-  launch: Launcher = launchSync,
-): StartTimeRead {
-  const res = launch({
-    bin: "ps",
-    args: ["-o", "lstart=", "-p", String(pid)],
-    category: "process-fingerprint",
-    timeoutMs: 2000,
-    // [FRAMING:representation] Pin BOTH locale and timezone so the token is
-    // deterministic across daemons — the writer and reader must render the same
-    // process identically for opaque string equality to be sound. LC_ALL=C fixes
-    // the strftime format; TZ=UTC fixes localtime(), so DST / TZ / tzdata changes
-    // can't make one live process render two different start-time strings.
-    env: { ...process.env, LC_ALL: "C", TZ: "UTC" },
-  });
-  if (res.ok) {
-    const token = res.stdout.trim();
-    if (token.length > 0) return { kind: "start", token };
-    // Exit 0 with empty output is anomalous (a live pid always lists) — don't
-    // mint an empty-string fingerprint; defer to kill.
-    return { kind: "unavailable", detail: "ps produced no start-time" };
-  }
-  const detail =
-    res.reason === "spawn-error"
-      ? (res.error ?? "ps spawn failed")
-      : `ps ${res.reason} (exit ${res.exitCode})`;
-  return { kind: "unavailable", detail };
-}
-
-export interface LivenessDeps {
-  readStartTime: (pid: number) => StartTimeRead;
-  pidAlive: (pid: number) => boolean;
-}
-
-// [LAW:dataflow-not-control-flow] The liveness verdict is a pure fold over the
-// start-time read + the lease's recorded token. Full input space:
-//   read=start + token matches lease   → true  (same process still alive)
-//   read=start + token differs         → false (a DIFFERENT process holds the
-//                                        pid — a recycle, or a restarted daemon)
-//   read=unavailable                   → kill(pid,0) fallback (the sound
-//                                        alive/dead test: a truly-dead pid →
-//                                        false → reclaim; a live pid ps couldn't
-//                                        read → true → spared)
-//   lease token = null (unfingerprinted at write, e.g. a host without `ps`) →
-//                                        kill(pid,0) fallback for the same reason
-//
-// [LAW:no-silent-failure] Only the `start`+mismatch case comes from the
-// fingerprint; every ambiguous `ps` outcome defers to kill, so the DANGEROUS
-// direction (declaring a live daemon dead → stealing its socket, the storm this
-// epic fights) never happens merely because `ps` could not answer. The only
-// thing forfeited when `ps` cannot answer is detecting a recycled pid.
-export function sameLiveProcess(
-  pid: number,
-  leaseToken: string | null,
-  deps: LivenessDeps,
-): boolean {
-  if (leaseToken === null) return deps.pidAlive(pid);
-  const read = deps.readStartTime(pid);
-  switch (read.kind) {
-    case "start":
-      return read.token === leaseToken;
-    case "unavailable":
-      return deps.pidAlive(pid);
-  }
-}
-
-// Read THIS process's own start-time to stamp into its lease. `unavailable`
-// (no `ps`) collapses to `null` — the lease records "unfingerprinted", and every
-// reader of it falls back to kill(pid,0) via sameLiveProcess. A dead result is
-// impossible for our own live pid; if it somehow occurs we also record null.
-export function readOwnStartTime(
-  pid: number,
-  read: (pid: number) => StartTimeRead = readStartTime,
-): string | null {
-  const r = read(pid);
-  return r.kind === "start" ? r.token : null;
-}