@promptctl/cc-candybar 1.42.1 → 1.43.0

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

@@ -1,108 +0,0 @@
-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

@@ -1,237 +0,0 @@
-// [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/socket-lease.ts

@@ -1,209 +0,0 @@
-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
-// lease file DERIVED FROM the socket path (one lease per socket identity), not a
-// connect probe. The prior probe (connect + classify the error code) was a
-// representation lie on macOS/BSD: connect(2) on a LIVE AF_UNIX listener whose
-// accept backlog is full returns ECONNREFUSED — indistinguishable from a dead
-// socket — so under load the probe judged healthy-but-slow daemons dead and
-// their sockets were stolen, minting immortal orphans (see
-// brandon-daemon-lifecycle-2b3).
-//
-// [FRAMING:representation] The lease records the owner's pid AND its kernel
-// start-time (see process-fingerprint.ts). Liveness is "the SAME process is
-// still alive" — kill(pid,0) alone lies when a crashed daemon's pid is recycled
-// to an unrelated live process (reads `alive` forever → no daemon ever comes up,
-// brandon-daemon-lifecycle-2b3.4 RESIDUAL 1). Comparing the start-time makes a
-// recycled pid provably a different process. Both signals are the kernel's
-// load-independent truth about process identity; a connect sample is
-// load-dependent hearsay and must never be the authority that destroys another
-// daemon's socket.
-
-// What a lease read yielded. Distinguishing absent / unreadable / owned keeps
-// the arbitration decision a full enumeration over raw inputs (see
-// arbitrateSocket) rather than collapsing the ambiguous cases early. `startTime`
-// is the owner's kernel start-time fingerprint, or null when the writing host
-// could not fingerprint (no `ps`) — the reader then falls back to kill(pid,0).
-export type LeaseRead =
-  | { kind: "absent" }
-  | { kind: "unreadable"; detail: string }
-  | ({ 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.
-export type SocketArbitration =
-  | { kind: "attach-and-exit"; reason: string }
-  | { kind: "reclaim"; reason: string };
-
-// Diagnostic-rich lease payload. `(pid, startTime)` is the authority (process
-// identity → liveness); the rest is operator diagnostics carried in the same
-// file so the lease subsumes the old diagnostic pidfile — one file, one identity
-// 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 extends ProcessIdentity {
-  version: number;
-  binPath: string | undefined;
-}
-
-// [LAW:effects-at-boundaries][LAW:dataflow-not-control-flow] The whole
-// arbitration is a pure fold: (raw lease read, injected liveness predicate) →
-// decision. Reading process identity is the sole effect and it is injected via
-// `isSameLiveProcess`, so every branch is exercised by input enumeration with no
-// real processes. Full input space:
-//   owned + same-live  → attach-and-exit (the SAME live owner holds the path; we
-//                        are a duplicate — exit so the incumbent keeps serving)
-//   owned + not-same   → reclaim (owner crashed, OR its pid was recycled to an
-//                        unrelated process — either way the socket is stale)
-//   absent             → reclaim (no lease to consult — a pre-lease or crashed
-//                        daemon left a stale socket; prefer availability)
-//   unreadable         → reclaim (can't prove a live owner — same)
-//
-// [LAW:one-source-of-truth] `isSameLiveProcess(pid, startTime)` consults the
-// kernel's process identity ((pid, start-time), see process-fingerprint.ts), not
-// a bare pid. This closes RESIDUAL 1: a crashed daemon's pid recycled to a
-// long-lived process now reads NOT-same (different start-time) → reclaim, so a
-// daemon comes up instead of every start attaching to a ghost forever.
-//
-// Failure directions:
-//   false-dead (steal a live socket) — made self-healing by the ownership
-//     self-check (brandon-daemon-lifecycle-2b3.2), and now far rarer: the
-//     start-time match will not false-negative a live owner unless the host
-//     cannot fingerprint at all, in which case sameLiveProcess falls back to
-//     kill(pid,0) — the prior behavior, no worse.
-// Reclaiming on missing/unreadable is the availability-preferring direction — a
-// stale socket with no reclaimer is a hard no-service stall, strictly worse than
-// a transient double-serve that self-heals.
-export function arbitrateSocket(
-  read: LeaseRead,
-  isSameLiveProcess: (pid: number, startTime: string | null) => boolean,
-): SocketArbitration {
-  if (read.kind === "owned") {
-    return isSameLiveProcess(read.pid, read.startTime)
-      ? {
-          kind: "attach-and-exit",
-          reason: `live owner pid=${read.pid} holds the socket`,
-        }
-      : {
-          kind: "reclaim",
-          reason: `owner pid=${read.pid} is gone or recycled`,
-        };
-  }
-  if (read.kind === "absent") {
-    return {
-      kind: "reclaim",
-      reason: "no lease — stale socket, no live owner",
-    };
-  }
-  return {
-    kind: "reclaim",
-    reason: `unreadable lease (${read.detail}) — cannot prove a live owner`,
-  };
-}
-
-// [LAW:no-silent-failure] Every non-happy path becomes a typed `unreadable`
-// with the reason inline, never a swallowed default that pretends the lease said
-// something. ENOENT is the one benign case → `absent`.
-export function readLease(leasePath: string): LeaseRead {
-  let raw: string;
-  try {
-    raw = fs.readFileSync(leasePath, "utf8");
-  } catch (e) {
-    const code = (e as NodeJS.ErrnoException).code;
-    if (code === "ENOENT") return { kind: "absent" };
-    return {
-      kind: "unreadable",
-      detail: `read failed: ${(e as Error).message}`,
-    };
-  }
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(raw);
-  } catch (e) {
-    return { kind: "unreadable", detail: `bad JSON: ${(e as Error).message}` };
-  }
-  const record = parsed as { pid?: unknown; startTime?: unknown } | null;
-  const pid = record?.pid;
-  if (typeof pid !== "number" || !Number.isInteger(pid) || pid <= 0) {
-    return {
-      kind: "unreadable",
-      detail: `no valid pid (got ${JSON.stringify(pid)})`,
-    };
-  }
-  // startTime is the process fingerprint. A present value must be a string;
-  // absent/null means "unfingerprinted" (an older lease, or a host without
-  // `ps`) and the reader falls back to kill(pid,0). A present-but-non-string is
-  // malformed → unreadable (never silently coerce a lie into a fingerprint).
-  const rawStartTime = record?.startTime;
-  if (
-    rawStartTime !== undefined &&
-    rawStartTime !== null &&
-    typeof rawStartTime !== "string"
-  ) {
-    return {
-      kind: "unreadable",
-      detail: `invalid startTime (got ${JSON.stringify(rawStartTime)})`,
-    };
-  }
-  return { kind: "owned", pid, startTime: rawStartTime ?? null };
-}
-
-// Write our lease after we win the bind. Overwrite-on-write: whoever holds the
-// socket right now replaces whatever stale lease a dead owner left.
-//
-// [LAW:no-ambient-temporal-coupling] Atomic publish: write a uniquely-named temp
-// sibling then rename onto the lease path. POSIX rename within a directory is
-// atomic, so a concurrent reader (a second daemon's EADDRINUSE arbitration) sees
-// either the old lease or the complete new one — never a truncated/empty file
-// mid-write, which would read as `unreadable` and force a false reclaim of this
-// daemon's live socket. The unique temp name means it is always freshly created,
-// so its 0600 mode always applies (0600 has no group/world bits for any umask to
-// need re-tightening) and rename carries that mode across. Returns null on
-// success, a reason on failure.
-export function writeLease(
-  leasePath: string,
-  record: LeaseRecord,
-): string | null {
-  const tmp = `${leasePath}.${process.pid}.tmp`;
-  try {
-    fs.writeFileSync(tmp, JSON.stringify(record), { mode: 0o600 });
-    fs.renameSync(tmp, leasePath);
-    return null;
-  } catch (e) {
-    const reason = (e as Error).message;
-    // [LAW:no-silent-failure] Best-effort temp cleanup, but don't swallow a real
-    // failure: ENOENT means the temp was never created (write failed first) —
-    // benign; any other unlink error means the temp WAS created and now leaks,
-    // so append it to the reason rather than hiding it behind the primary error.
-    try {
-      fs.unlinkSync(tmp);
-    } catch (cleanupErr) {
-      if ((cleanupErr as NodeJS.ErrnoException).code !== "ENOENT") {
-        return `${reason}; also failed to remove temp ${tmp}: ${(cleanupErr as Error).message}`;
-      }
-    }
-    return reason;
-  }
-}
-
-// [LAW:one-source-of-truth] Only the owner mutates its lease. A daemon that was
-// displaced (its socket stolen, the thief wrote a new lease) must NOT delete the
-// current owner's lease on its way out — that would make the next EADDRINUSE
-// read `absent` and reclaim the live thief's socket, cascading the theft. So
-// remove only when the lease still names us.
-export function removeLeaseIfOwned(leasePath: string, myPid: number): void {
-  const read = readLease(leasePath);
-  if (read.kind === "owned" && read.pid === myPid) {
-    try {
-      fs.unlinkSync(leasePath);
-    } catch {
-      // Best-effort cleanup; a leftover lease naming a dead pid is harmless
-      // (the next daemon reads it, kill(pid,0)→ESRCH, reclaims).
-    }
-  }
-}