@promptctl/cc-candybar 1.0.0

package/src/daemon/session-state-file.ts

@@ -0,0 +1,108 @@
+import fs from "node:fs";
+import path from "node:path";
+import { debug } from "../utils/logger";
+import type { DaemonLogger } from "./log";
+import type { SessionSnapshot, SessionStorage } from "./session-state";
+
+// [LAW:locality-or-seam] Logging is injected, not hard-wired to daemon.log.
+// The daemon passes `dlog`; tests and non-daemon callers take this quiet
+// default, which stays silent unless CC_CANDYBAR_DEBUG is set — so unit tests
+// never open the real daemon log stream.
+const quietLogger: DaemonLogger = (_level, message) => debug(message);
+
+// [LAW:no-silent-fallbacks] Corrupt/missing file → empty state is the *defined*
+// recovery, not a hidden fallback to different data: an empty store re-rolls
+// random picks exactly as a first-ever boot would. Anything that isn't the
+// expected sessionId→key→value shape is rejected here so the store never
+// hydrates from a half-written or hand-edited file.
+function isSnapshot(value: unknown): value is SessionSnapshot {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return false;
+  }
+  for (const kv of Object.values(value)) {
+    if (kv === null || typeof kv !== "object" || Array.isArray(kv))
+      return false;
+    for (const leaf of Object.values(kv)) {
+      if (typeof leaf !== "string") return false;
+    }
+  }
+  return true;
+}
+
+// [LAW:single-enforcer] The debounce + atomic write lives here, not in
+// SessionState. The store calls save() on every mutation; this coalesces the
+// bursty 22-session × 1 Hz write load into at most one disk write per window.
+export class FileSessionStorage implements SessionStorage {
+  private timer: ReturnType<typeof setTimeout> | null = null;
+  private pending: SessionSnapshot | null = null;
+
+  constructor(
+    private readonly filePath: string,
+    private readonly debounceMs: number = 500,
+    private readonly logger: DaemonLogger = quietLogger,
+  ) {}
+
+  load(): SessionSnapshot {
+    let raw: string;
+    try {
+      raw = fs.readFileSync(this.filePath, "utf8");
+    } catch (e) {
+      // [LAW:no-silent-fallbacks] A missing file is the expected first-boot
+      // recovery (silent → empty). Any other read failure (EACCES, EIO) is an
+      // anomaly worth surfacing before recovering to empty.
+      const code = (e as NodeJS.ErrnoException).code;
+      if (code !== "ENOENT") {
+        this.logger(
+          "warn",
+          `session-state read failed (${code}); starting empty`,
+        );
+      }
+      return {};
+    }
+    try {
+      const parsed: unknown = JSON.parse(raw);
+      if (isSnapshot(parsed)) return parsed;
+      this.logger(
+        "warn",
+        `session-state load: unexpected shape, starting empty`,
+      );
+      return {};
+    } catch {
+      this.logger("warn", `session-state load: corrupt JSON, starting empty`);
+      return {};
+    }
+  }
+
+  save(snapshot: SessionSnapshot): void {
+    this.pending = snapshot;
+    if (this.timer) return;
+    this.timer = setTimeout(() => this.flush(), this.debounceMs);
+    this.timer.unref();
+  }
+
+  flush(): void {
+    if (this.timer) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+    if (this.pending === null) return;
+    const snapshot = this.pending;
+    try {
+      fs.mkdirSync(path.dirname(this.filePath), { recursive: true });
+      const tmp = `${this.filePath}.tmp`;
+      // [LAW:single-enforcer] Daemon runtime files are owner-only (0o600), like
+      // pid/spawn.lock. Session state carries conversation identifiers, so it
+      // gets the same perms — chmod defeats umask and re-perms a reused tmp.
+      fs.writeFileSync(tmp, JSON.stringify(snapshot), { mode: 0o600 });
+      fs.chmodSync(tmp, 0o600);
+      fs.renameSync(tmp, this.filePath);
+      // [LAW:one-source-of-truth] `pending` is "state not yet durably written".
+      // Clear it only once the rename lands, so a transient EIO/ENOSPC leaves
+      // the snapshot for a later flush (e.g. shutdown) to retry rather than
+      // silently dropping the last known state.
+      this.pending = null;
+    } catch (e) {
+      this.logger("warn", `session-state save failed: ${(e as Error).message}`);
+    }
+  }
+}

package/src/daemon/session-state.ts

@@ -0,0 +1,237 @@
+// [LAW:one-type-per-behavior] One generic store for all per-session state.
+// Adding a new per-session value is just picking a string key — no new class,
+// no DI wiring, no cache invalidation.
+//
+// [LAW:single-enforcer] Reads are MobX-tracked through a single internal atom.
+// Every get() reports observed; every set/clear/prune reports changed. A DSL
+// computed that reads SessionState via this object will re-evaluate whenever
+// any (sessionId, key) pair mutates — coarse-grained on purpose, since
+// session-state mutations are rare (clicks) and computeds are cheap. The
+// alternative — per-key atoms — would be lower-cardinality reactivity at the
+// cost of a much wider API surface; we don't need it.
+//
+// Outside a reactive context (the common case: ad-hoc gets from the segments
+// renderer), atom.reportObserved is a no-op. Tests that construct SessionState
+// without any observer see no change in behavior.
+
+import { createAtom, type IAtom, runInAction } from "mobx";
+
+export interface SessionStateReader {
+  get(sessionId: string, key: string): string | null;
+}
+
+// [LAW:locality-or-seam] Renderer needs to *cache* per-session random picks
+// so subsequent renders are stable. Writing them back into the same store
+// click verbs use keeps state in one place — no parallel cache to drift.
+//
+// setBatch commits multiple (key, value) pairs as a single reactive
+// transaction: observers fire ONCE after every pair has landed, never
+// between pairs. The set-state verb's batched-pair URL (a Menu click that
+// writes the chosen value AND collapses the menu) depends on this — if
+// observers saw the first write before the second, an autorun could
+// render half-applied state. The atomicity contract lives in the seam,
+// not in each consumer. [LAW:single-enforcer]
+export interface SessionStateRW extends SessionStateReader {
+  set(sessionId: string, key: string, value: string): void;
+  setBatch(
+    sessionId: string,
+    pairs: ReadonlyArray<{ key: string; value: string }>,
+  ): void;
+  clear(sessionId: string, key: string): void;
+}
+
+// Flat, JSON-shaped mirror of the store: sessionId → key → value. This is the
+// on-disk representation and the load/save currency between store and storage.
+export type SessionSnapshot = Record<string, Record<string, string>>;
+
+// [LAW:locality-or-seam] The store depends on this seam, not on the filesystem.
+// The daemon injects a disk-backed impl; tests and non-daemon callers get the
+// ephemeral default. Persistence is a property of the *storage*, not the store.
+export interface SessionStorage {
+  load(): SessionSnapshot;
+  save(snapshot: SessionSnapshot): void;
+  flush(): void;
+}
+
+// [LAW:dataflow-not-control-flow] Null-object so the store always calls
+// save()/flush() — no "am I persisting?" branch. The ephemeral case is data
+// (a storage that discards), not a special control path.
+const EPHEMERAL_STORAGE: SessionStorage = {
+  load: () => ({}),
+  save: () => {},
+  flush: () => {},
+};
+
+function hydrate(snapshot: SessionSnapshot): Map<string, Map<string, string>> {
+  const sessions = new Map<string, Map<string, string>>();
+  for (const [sessionId, kv] of Object.entries(snapshot)) {
+    sessions.set(sessionId, new Map(Object.entries(kv)));
+  }
+  return sessions;
+}
+
+// Generous headroom over realistic concurrent-session counts; matches the
+// render cache's LRU bound. Active sessions stay hot via get-promotion, so only
+// genuinely-idle sessions are ever evicted — eviction *is* "drop dead sessions".
+const DEFAULT_MAX_SESSIONS = 256;
+
+export class SessionState implements SessionStateReader, SessionStateRW {
+  // [LAW:types-are-the-program] Insertion order is recency order: the store
+  // cannot hold more than maxSessions, so "bounded on disk" is structural, not
+  // dependent on an external prune caller.
+  private sessions: Map<string, Map<string, string>>;
+  private storage: SessionStorage;
+  // [LAW:single-enforcer] One atom; every read reports observed against it,
+  // every mutation reports changed. Coarse-grained reactivity is correct for
+  // session-state's load — mutations are rare and computeds are cheap.
+  private readonly atom: IAtom = createAtom("SessionState");
+
+  constructor(
+    storage: SessionStorage = EPHEMERAL_STORAGE,
+    private readonly maxSessions: number = DEFAULT_MAX_SESSIONS,
+  ) {
+    this.storage = storage;
+    this.sessions = new Map();
+    this.hydrateFromStorage();
+  }
+
+  // [LAW:single-enforcer] Bind a persistence backend after construction. Only
+  // the daemon process calls this (with the disk-backed storage), so importers
+  // that merely load this module — the CLI relay, subcommands — keep the
+  // ephemeral default and never read or write the state file. Must run before
+  // the daemon serves requests, since it replaces in-memory state with disk.
+  useStorage(storage: SessionStorage): void {
+    this.storage = storage;
+    this.hydrateFromStorage();
+  }
+
+  private hydrateFromStorage(): void {
+    this.sessions = hydrate(this.storage.load());
+    this.evictOldest();
+    // [LAW:dataflow-not-control-flow] The disk mirror always reflects the built
+    // in-memory state. An over-cap file trimmed by evictOldest is written back
+    // here, so the on-disk bound holds even if no mutation ever follows.
+    this.persist();
+  }
+
+  get(sessionId: string, key: string): string | null {
+    // [LAW:single-enforcer] reportObserved is the reactive-dep registration —
+    // outside a tracking context (the common direct-read case) it is a no-op.
+    this.atom.reportObserved();
+    const session = this.sessions.get(sessionId);
+    if (!session) return null;
+    // [LAW:dataflow-not-control-flow] A read promotes recency but never
+    // triggers a disk write itself; the reordered insertion order only reaches
+    // disk if a later mutation persists.
+    this.touch(sessionId, session);
+    return session.get(key) ?? null;
+  }
+
+  // [LAW:one-source-of-truth] set is the degenerate single-pair form of
+  // setBatch — one write path through the store. The previous shape (a
+  // standalone set body) split the write semantics across two routes
+  // once setBatch was introduced; collapsing keeps mutation, persistence,
+  // and notification in exactly one place.
+  set(sessionId: string, key: string, value: string): void {
+    this.setBatch(sessionId, [{ key, value }]);
+  }
+
+  // [LAW:no-silent-fallbacks] Atomic commit of N pairs: every write
+  // lands BEFORE the single reportChanged() that scheduler-visibly
+  // marks the transaction complete. Observers cannot see an
+  // intermediate "half-applied" snapshot — `runInAction` defers
+  // reaction scheduling until the outermost call exits, and we hold
+  // ALL writes inside this one block. Previously, the verb's "loop and
+  // call set N times" pattern fired reportChanged() N times, which
+  // scheduled autoruns between pairs (visible to consumers as the menu
+  // value changing while toolbar-expanded was still old). The batch
+  // method is the structural fix: there is no way to get half-applied
+  // state because there is no intermediate scheduler tick.
+  //
+  // [LAW:dataflow-not-control-flow] An empty pairs array is no-work-
+  // to-do, returned without firing reportChanged or persisting. The
+  // verb body validates that pairs is non-empty before calling, so
+  // this is the public-API safety net rather than the hot path.
+  setBatch(
+    sessionId: string,
+    pairs: ReadonlyArray<{ key: string; value: string }>,
+  ): void {
+    if (pairs.length === 0) return;
+    runInAction(() => {
+      const session = this.sessions.get(sessionId) ?? new Map<string, string>();
+      for (const { key, value } of pairs) session.set(key, value);
+      this.touch(sessionId, session);
+      this.evictOldest();
+      this.persist();
+      this.atom.reportChanged();
+    });
+  }
+
+  clear(sessionId: string, key: string): void {
+    runInAction(() => {
+      const session = this.sessions.get(sessionId);
+      if (session) {
+        session.delete(key);
+        // An emptied session is a non-state — drop it so it neither occupies a
+        // cap slot nor persists as a `{ "sid": {} }` husk. [LAW:one-source-of-truth]
+        // A surviving session is promoted: every interaction is a recency signal,
+        // uniform with get()/set(). [LAW:one-type-per-behavior]
+        if (session.size === 0) this.sessions.delete(sessionId);
+        else this.touch(sessionId, session);
+      }
+      this.persist();
+      this.atom.reportChanged();
+    });
+  }
+
+  // [LAW:one-source-of-truth] Drop state for sessions that no longer exist.
+  prune(activeSessionIds: Set<string>): void {
+    runInAction(() => {
+      for (const id of this.sessions.keys()) {
+        if (!activeSessionIds.has(id)) this.sessions.delete(id);
+      }
+      this.persist();
+      this.atom.reportChanged();
+    });
+  }
+
+  // Move-to-end: re-inserting at the tail makes this the most-recently-used.
+  private touch(sessionId: string, session: Map<string, string>): void {
+    this.sessions.delete(sessionId);
+    this.sessions.set(sessionId, session);
+  }
+
+  private evictOldest(): void {
+    let overflow = this.sessions.size - this.maxSessions;
+    if (overflow <= 0) return;
+    // Delete the oldest keys in insertion order. Cost is proportional to the
+    // number of evictions, not the total loaded set — deleting an already-
+    // yielded key mid-iteration is well-defined for a Map.
+    for (const id of this.sessions.keys()) {
+      this.sessions.delete(id);
+      if (--overflow === 0) break;
+    }
+  }
+
+  // Synchronous write of any debounced-pending snapshot. Called on daemon
+  // shutdown so a pending pick isn't lost when the process exits.
+  flush(): void {
+    this.storage.flush();
+  }
+
+  private persist(): void {
+    this.storage.save(this.serialize());
+  }
+
+  private serialize(): SessionSnapshot {
+    // [LAW:types-are-the-program] sessionIds are external (hook JSON / click
+    // URLs). A null-prototype root makes "__proto__"/"constructor" ordinary
+    // own keys instead of prototype-mutation vectors — pollution is
+    // unrepresentable rather than guarded against.
+    const snapshot = Object.create(null) as SessionSnapshot;
+    for (const [sessionId, kv] of this.sessions) {
+      snapshot[sessionId] = Object.fromEntries(kv);
+    }
+    return snapshot;
+  }
+}

package/src/daemon/stats.ts

@@ -0,0 +1,229 @@
+// [LAW:single-enforcer] One mutator owns runtime counters. Server, caches, and
+// watchers each receive a tiny handle they're allowed to bump, but the
+// canonical object lives here. Stats are read-only after serialization.
+
+import type { LaunchCategory } from "../proc/launch";
+import type { LaunchStatsHandle } from "../proc/stats-handle";
+import { PROTOCOL_VERSION } from "./protocol";
+
+// Rolling window for "last minute" counts. Keep timestamps for each launch in
+// a ring buffer; eviction happens lazily on read.
+//
+// [LAW:dataflow-not-control-flow] The cap is a hard bound on how many
+// launches can be counted in any 60-second window. Bursts above
+// ROLLING_BUFFER_CAP / (ROLLING_WINDOW_MS/1000) launches/sec overwrite
+// timestamps that are still inside the window, causing `lastMinute` to
+// undercount. At 16384 entries / 60s = ~273 sustained launches/sec the
+// undercount only kicks in under pathological load (well past anything kz8
+// is trying to detect). Bump this cap rather than the comment if a future
+// workload ever sustains higher rates.
+const ROLLING_WINDOW_MS = 60_000;
+const ROLLING_BUFFER_CAP = 16384;
+
+// Reservoir-sample histogram (16 entries) per category — sufficient for
+// rough p50/p99 without unbounded memory. Replacement uses a simple
+// counter-mod-N strategy: deterministic and adequate for human-eyeball
+// dashboards (no statistical claim of unbiased sampling).
+const HISTOGRAM_CAP = 16;
+
+export interface StatsSnapshot {
+  pid: number;
+  version: number;
+  startedAt: string;
+  uptimeSec: number;
+  rssBytes: number;
+  heapUsedBytes: number;
+  heapTotalBytes: number;
+  externalBytes: number;
+  arrayBuffersBytes: number;
+  requests: {
+    total: number;
+    errored: number;
+    timedOut: number;
+    inFlight: number;
+  };
+  gitCache: {
+    size: number;
+    hits: number;
+    misses: number;
+    invalidations: number;
+    watchers: number;
+  };
+  usageCache: {
+    size: number;
+    hits: number;
+    misses: number;
+    sweeps: number;
+  };
+  renderCache: {
+    size: number;
+  };
+  watchers: {
+    active: number;
+    opened: number;
+    closed: number;
+    evicted: number;
+  };
+  subprocesses: {
+    total: number;
+    inFlight: number;
+    lastMinute: number;
+    byCategory: Record<string, number>;
+    p50DurationMs: Record<string, number>;
+    p99DurationMs: Record<string, number>;
+  };
+  nextRestartReason: string | null;
+}
+
+export class RuntimeStats {
+  readonly startedAt = new Date();
+  requestsTotal = 0;
+  requestsErrored = 0;
+  requestsTimedOut = 0;
+  inFlight = 0;
+
+  watchersOpened = 0;
+  watchersClosed = 0;
+  watchersEvicted = 0;
+
+  // [LAW:dataflow-not-control-flow] Subprocess metering. Every launch carries
+  // its category through one boundary; the per-category state below is a
+  // function of that data, not of which call site fired.
+  subprocessTotal = 0;
+  subprocessInFlight = 0;
+  private readonly subprocessCount = new Map<LaunchCategory, number>();
+  private readonly subprocessHistogram = new Map<LaunchCategory, number[]>();
+  private readonly subprocessHistogramRotator = new Map<
+    LaunchCategory,
+    number
+  >();
+  private readonly rollingTimestamps: number[] = [];
+  private rollingHead = 0;
+
+  // [LAW:one-source-of-truth] The same object that owns the counters also
+  // exposes the metering handle. The launch primitive calls these two
+  // methods; nothing else mutates subprocess state.
+  readonly launchStats: LaunchStatsHandle = {
+    onStart: (category) => {
+      this.subprocessTotal++;
+      this.subprocessInFlight++;
+      this.subprocessCount.set(
+        category,
+        (this.subprocessCount.get(category) ?? 0) + 1,
+      );
+      this.recordRollingNow();
+    },
+    onEnd: (category, durationMs) => {
+      this.subprocessInFlight = Math.max(0, this.subprocessInFlight - 1);
+      this.recordDuration(category, durationMs);
+    },
+  };
+
+  private recordRollingNow(): void {
+    const now = Date.now();
+    if (this.rollingTimestamps.length < ROLLING_BUFFER_CAP) {
+      this.rollingTimestamps.push(now);
+      return;
+    }
+    // Ring buffer once cap hit. The overwritten slot may still be inside the
+    // 60s window — see the cap-rationale comment at ROLLING_BUFFER_CAP.
+    this.rollingTimestamps[this.rollingHead] = now;
+    this.rollingHead = (this.rollingHead + 1) % ROLLING_BUFFER_CAP;
+  }
+
+  private recordDuration(category: LaunchCategory, durationMs: number): void {
+    let hist = this.subprocessHistogram.get(category);
+    if (!hist) {
+      hist = [];
+      this.subprocessHistogram.set(category, hist);
+    }
+    if (hist.length < HISTOGRAM_CAP) {
+      hist.push(durationMs);
+      return;
+    }
+    const idx =
+      (this.subprocessHistogramRotator.get(category) ?? 0) % HISTOGRAM_CAP;
+    hist[idx] = durationMs;
+    this.subprocessHistogramRotator.set(category, idx + 1);
+  }
+
+  private snapshotSubprocesses(): StatsSnapshot["subprocesses"] {
+    const cutoff = Date.now() - ROLLING_WINDOW_MS;
+    let lastMinute = 0;
+    for (const ts of this.rollingTimestamps) {
+      if (ts >= cutoff) lastMinute++;
+    }
+
+    // [LAW:one-source-of-truth] Snapshot includes only categories that have
+    // actually executed — same shape as p50/p99 below. Consumers wanting the
+    // full closed list can read LAUNCH_CATEGORIES (exported from src/proc/launch)
+    // and treat missing keys as zero.
+    const byCategory: Record<string, number> = {};
+    for (const [cat, n] of this.subprocessCount) {
+      if (n > 0) byCategory[cat] = n;
+    }
+
+    const p50: Record<string, number> = {};
+    const p99: Record<string, number> = {};
+    for (const [cat, hist] of this.subprocessHistogram) {
+      if (hist.length === 0) continue;
+      const sorted = [...hist].sort((a, b) => a - b);
+      const p50idx = Math.floor(sorted.length * 0.5);
+      const p99idx = Math.min(
+        sorted.length - 1,
+        Math.floor(sorted.length * 0.99),
+      );
+      const p50val = sorted[p50idx];
+      const p99val = sorted[p99idx];
+      if (p50val !== undefined) p50[cat] = p50val;
+      if (p99val !== undefined) p99[cat] = p99val;
+    }
+
+    return {
+      total: this.subprocessTotal,
+      inFlight: this.subprocessInFlight,
+      lastMinute,
+      byCategory,
+      p50DurationMs: p50,
+      p99DurationMs: p99,
+    };
+  }
+
+  snapshot(extras: {
+    gitCache: StatsSnapshot["gitCache"];
+    usageCache: StatsSnapshot["usageCache"];
+    renderCacheSize: number;
+    watchersActive: number;
+    nextRestartReason?: string | null;
+  }): StatsSnapshot {
+    const mem = process.memoryUsage();
+    return {
+      pid: process.pid,
+      version: PROTOCOL_VERSION,
+      startedAt: this.startedAt.toISOString(),
+      uptimeSec: Math.floor((Date.now() - this.startedAt.getTime()) / 1000),
+      rssBytes: mem.rss,
+      heapUsedBytes: mem.heapUsed,
+      heapTotalBytes: mem.heapTotal,
+      externalBytes: mem.external,
+      arrayBuffersBytes: mem.arrayBuffers,
+      requests: {
+        total: this.requestsTotal,
+        errored: this.requestsErrored,
+        timedOut: this.requestsTimedOut,
+        inFlight: this.inFlight,
+      },
+      gitCache: extras.gitCache,
+      usageCache: extras.usageCache,
+      renderCache: { size: extras.renderCacheSize },
+      watchers: {
+        active: extras.watchersActive,
+        opened: this.watchersOpened,
+        closed: this.watchersClosed,
+        evicted: this.watchersEvicted,
+      },
+      subprocesses: this.snapshotSubprocesses(),
+      nextRestartReason: extras.nextRestartReason ?? null,
+    };
+  }
+}