@promptctl/cc-candybar 1.41.0 → 1.41.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@promptctl/cc-candybar",
-  "version": "1.41.0",
+  "version": "1.41.2",
   "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",
@@ -85,15 +85,15 @@
     "tsdown": "^0.21.4",
     "tsx": "^4.21.0",
     "typescript": "^5.0.0",
-    "@promptctl/go-template-js": "^0.7.0",
+    "@promptctl/go-template-js": "^0.8.0",
     "@promptctl/rich-js": "^0.7.0",
     "json5": "^2.2.3",
     "mobx": "^6.15.0"
   },
   "optionalDependencies": {
-    "@promptctl/cc-candybar-darwin-arm64": "1.41.0",
-    "@promptctl/cc-candybar-darwin-x64": "1.41.0",
-    "@promptctl/cc-candybar-linux-x64": "1.41.0",
-    "@promptctl/cc-candybar-linux-arm64": "1.41.0"
+    "@promptctl/cc-candybar-darwin-arm64": "1.41.2",
+    "@promptctl/cc-candybar-darwin-x64": "1.41.2",
+    "@promptctl/cc-candybar-linux-x64": "1.41.2",
+    "@promptctl/cc-candybar-linux-arm64": "1.41.2"
   }
 }

package/src/config/dsl-types.ts

@@ -181,9 +181,9 @@ export interface RawDslConfig {
   // per session exactly like theme/style (session key `look`).
   readonly looks?: Readonly<Record<string, ThemeKey>>;
   // [LAW:single-enforcer] Config-level shared helper templates: name → Go-template
-  // body. Each compiles to one `{{ define "name" }}body{{ end }}` block, and the
-  // whole set into a single output-neutral preamble prepended to every template
-  // this config parses — so a formatter (`{{ template "formatCost" .x }}`) is
+  // body. Each compiles to one `{{ define "name" }}body{{ end }}` unit, and the
+  // whole set into one shared define set every template this config parses
+  // inherits — so a formatter (`{{ template "formatCost" .x }}`) is
   // defined ONCE and callable from any segment/predicate, never re-inlined per
   // segment. Absent ≡ no helpers; merges by-name (user overrides a helper).
   readonly helpers?: Readonly<Record<string, string>>;
@@ -240,7 +240,7 @@ export interface DslConfig {
   // [LAW:dataflow-not-control-flow].
   readonly editGlobals: Partial<Globals>;
   // [LAW:single-enforcer] The effective helper set: a name → template-body map
-  // compiled to a defines-preamble at registerDslConfig. Empty when no config
+  // compiled to one shared define set at registerDslConfig. Empty when no config
   // declares helpers — an absent `helpers` key merges to `{}` (same cascade as
   // actions). The single definition site for each formatter/transform a template
   // calls via `{{ template "name" .arg }}`.

package/src/config/loader/helpers.ts

@@ -2,7 +2,7 @@
 // record of name → template-body STRING. Each value is a Go-template source the
 // renderer compiles into a `{{ define }}` block; whether the body PARSES (and
 // whether a `{{ template "name" }}` reference resolves) is a render-time concern
-// (registerDslConfig parses the preamble and throws a per-helper diagnostic).
+// (registerDslConfig parses each helper and throws a per-helper diagnostic).
 // This file changes only if the helper authoring shape changes.
 
 import { findKeyLine } from "./diagnostics.js";

package/src/daemon/acquire.ts

@@ -2,6 +2,7 @@ import fs from "node:fs";
 import net from "node:net";
 import path from "node:path";
 import { launchDetachedSync } from "../proc/launch";
+import { heapCapMb } from "./limits";
 import process from "node:process";
 import {
   socketPath,
@@ -656,9 +657,11 @@ function sleep(ms: number): Promise<void> {
 
 // ─── Default spawn implementation ───────────────────────────────────────────
 //
-// Cap V8 old-generation at 400 MB so GC fires before RSS hits the 512 MB hard
-// limit. The Rust client mirrors this in rust-client/src/main.rs
-// (spawn_daemon_detached) — keep the two in sync when changing this value.
+// [LAW:one-source-of-truth] The V8 old-space cap is derived from the daemon's
+// RSS budget (limits.ts: heapCapMb), never a literal here — the cap must sit
+// ABOVE the RSS backstop so the graceful path fires first, and only one owner
+// of the budget can keep that order true. The Rust client derives the same
+// value the same way (rust-client/src/launch.rs).
 //
 // [LAW:single-enforcer] Routes through src/proc/launch so daemon-spawn shows
 // up in subprocess metering (category "daemon-spawn"). The launch primitive
@@ -674,7 +677,7 @@ function spawnDaemonDetachedReal(): boolean {
   // discarded the Promise and unconditionally returned true.
   const result = launchDetachedSync({
     bin: node,
-    args: ["--max-old-space-size=400", script, "daemon"],
+    args: [`--max-old-space-size=${heapCapMb(process.env)}`, script, "daemon"],
     category: "daemon-spawn",
   });
   return result.ok;

package/src/daemon/limits.ts

@@ -8,10 +8,67 @@ import { dlog, type DaemonLogger } from "./log";
 // Only the RSS trigger remains — idle and age limits were removed because they
 // interrupted active sessions. The RSS limit is a true anomaly backstop; normal
 // operation should never approach it now that transcript parsing is pruned.
-const DEFAULT_RSS_LIMIT =
-  (parseInt(process.env["CC_CANDYBAR_RSS_LIMIT_MB"] ?? "", 10) || 512) *
-  1024 *
-  1024;
+//
+// [LAW:one-source-of-truth] The daemon's memory budget is ONE number, read from
+// ONE place. Two limits derive from it and their ORDER is the whole point:
+//
+//   RSS backstop (this module)   — graceful: heap snapshot, logged shutdown,
+//                                  clean restart on the next tick.
+//   V8 old-space cap (spawners)  — hard: V8 aborts with SIGABRT below every JS
+//                                  handler, so no log line, no snapshot, and
+//                                  the next daemon finds only a stale socket.
+//
+// The cap sits at HEAP_CAP_OVER_RSS × the backstop, a margin wide enough that
+// the graceful path fires first under any growth the 60 s poll can see (a
+// burst that doubles RSS inside one poll window can still reach the hard cap).
+// Before this the two were unrelated literals (400 MB heap in each spawner,
+// 512 MB RSS here), and the 2026-09-03 outage found the gap: a daemon holding
+// twenty configs' worth of duplicated helper-template ASTs (since fixed in
+// src/dsl/render.ts compileHelpers) blew the heap in seconds, aborted
+// silently, and crash-looped on every render tick while the backstop — a 60 s
+// poll — never got a turn. Raising the env override raises BOTH, because both
+// spawners derive the cap through heapCapMb below. The Rust client mirrors
+// RSS_LIMIT_ENV, DEFAULT_RSS_LIMIT_MB, and HEAP_CAP_OVER_RSS as literals
+// (rust-client/src/launch.rs); scripts/check-protocol.mjs fails the build on
+// drift.
+export const RSS_LIMIT_ENV = "CC_CANDYBAR_RSS_LIMIT_MB";
+export const DEFAULT_RSS_LIMIT_MB = 512;
+export const HEAP_CAP_OVER_RSS = 2;
+
+// [LAW:parse-dont-validate] Absent → default; a positive integer → that; present
+// but malformed → throw. Only an operator ever sets this variable, so garbage
+// is an operator error, and `|| default` would silently run at a budget they
+// did not ask for. [LAW:no-silent-failure]
+//
+// [LAW:one-source-of-truth] The grammar is ONE rule both runtimes apply
+// verbatim — ASCII digits only, > 0, within the safe-integer range —
+// so the spawner and the daemon it spawns accept and reject the same values
+// (rust-client/src/launch.rs heap_cap_mb). A grammar that differed by so much
+// as a leading `+` would let a client spawn a daemon that refuses to boot.
+export function rssLimitMb(env: NodeJS.ProcessEnv): number {
+  const raw = env[RSS_LIMIT_ENV];
+  if (raw === undefined) return DEFAULT_RSS_LIMIT_MB;
+  const mb = /^\d+$/.test(raw) ? Number(raw) : NaN;
+  if (!Number.isSafeInteger(mb) || mb <= 0) {
+    throw new Error(
+      `${RSS_LIMIT_ENV} must be a positive integer (MB), got ${JSON.stringify(raw)}`,
+    );
+  }
+  return mb;
+}
+
+// The `--max-old-space-size` value a spawner hands node for the daemon.
+export function heapCapMb(env: NodeJS.ProcessEnv): number {
+  return rssLimitMb(env) * HEAP_CAP_OVER_RSS;
+}
+
+const BYTES_PER_MB = 1024 * 1024;
+
+// The budget in the unit `process.memoryUsage().rss` reports.
+export function rssLimitBytes(env: NodeJS.ProcessEnv): number {
+  return rssLimitMb(env) * BYTES_PER_MB;
+}
+
 const DEFAULT_CHECK_INTERVAL = 60 * 1000;
 const HEAP_SNAPSHOT_KEEP = 3;
 
@@ -42,7 +99,7 @@ export interface LimitsHandle {
 }
 
 export function makeLimits(deps: LimitsDeps): LimitsHandle {
-  const rssLimit = deps.rssLimitBytes ?? DEFAULT_RSS_LIMIT;
+  const rssLimit = deps.rssLimitBytes ?? DEFAULT_RSS_LIMIT_MB * BYTES_PER_MB;
   const keep = deps.snapshotsKeep ?? HEAP_SNAPSHOT_KEEP;
   let triggered = false;
 

package/src/daemon/log.ts

@@ -2,35 +2,34 @@ import fs from "node:fs";
 import path from "node:path";
 import { logPath } from "./paths";
 
-const MAX_BYTES = 5 * 1024 * 1024;
+export const MAX_BYTES = 5 * 1024 * 1024;
 const KEEP_GENERATIONS = 3;
 
-let stream: fs.WriteStream | null = null;
-let bytesWritten = 0;
+// [LAW:no-ambient-temporal-coupling] Every line is a synchronous append, so a
+// line is on disk the moment the call returns — including the death line each
+// shutdown path writes last, which an async stream dropped whenever
+// `process.exit` outran its flush. The daemon writes a handful of short lines
+// per second; a sync append is microseconds. No stream means nothing to flush,
+// nothing to close, and no window in which a late writer can reopen a sink
+// that nobody waits for. [LAW:polishing-by-subtraction]
+let bytesWritten: number | null = null;
 
-function ensureStream(): fs.WriteStream {
-  if (stream) return stream;
-  const filePath = logPath();
+// Pre-load size once so rotation triggers correctly across daemon restarts.
+function currentBytes(filePath: string): number {
+  if (bytesWritten !== null) return bytesWritten;
   fs.mkdirSync(path.dirname(filePath), { recursive: true });
-  // Pre-load size so rotation triggers correctly across daemon restarts.
   try {
     bytesWritten = fs.statSync(filePath).size;
   } catch {
     bytesWritten = 0;
   }
-  stream = fs.createWriteStream(filePath, { flags: "a" });
-  return stream;
+  return bytesWritten;
 }
 
 // Self-rotation: when daemon.log exceeds MAX_BYTES, shift .1→.2, .2→.3, drop
 // the oldest, and start fresh. Daemon-internal so we don't depend on any
 // external rotator. Cheap because rotation only runs at the rollover boundary.
-function rotate(): void {
-  const filePath = logPath();
-  if (stream) {
-    stream.end();
-    stream = null;
-  }
+function rotate(filePath: string): void {
   for (let i = KEEP_GENERATIONS - 1; i >= 1; i--) {
     const src = `${filePath}.${i}`;
     const dst = `${filePath}.${i + 1}`;
@@ -44,26 +43,39 @@ function rotate(): void {
   bytesWritten = 0;
 }
 
+export type LogLevel = "info" | "warn" | "error";
+
 // [LAW:locality-or-seam] The logging capability daemon components depend on.
 // `dlog` is the daemon's implementation (writes to daemon.log); consumers that
 // inject a different impl (a quiet default in tests) take this shape.
-export type DaemonLogger = (
-  level: "info" | "warn" | "error",
-  msg: string,
-) => void;
+export type DaemonLogger = (level: LogLevel, msg: string) => void;
 
-export function dlog(level: "info" | "warn" | "error", msg: string): void {
+export function dlog(level: LogLevel, msg: string): void {
   const line = `${new Date().toISOString()} [${level}] ${msg}\n`;
-  const buf = Buffer.from(line, "utf8");
-  const s = ensureStream();
-  s.write(buf);
-  bytesWritten += buf.length;
-  if (bytesWritten >= MAX_BYTES) rotate();
-}
-
-export function closeLog(): void {
-  if (stream) {
-    stream.end();
-    stream = null;
+  try {
+    // [LAW:single-enforcer] Path resolution reaches os.homedir(); it lives
+    // inside the one boundary that makes dlog total.
+    const filePath = logPath();
+    const before = currentBytes(filePath);
+    fs.appendFileSync(filePath, line);
+    bytesWritten = before + Buffer.byteLength(line, "utf8");
+    if (bytesWritten >= MAX_BYTES) rotate(filePath);
+  } catch (e) {
+    // [LAW:no-silent-failure] exception: the failure IS the log sink, so it
+    // cannot be reported through the log sink. A throw here would escape the
+    // crash handlers that call dlog first (uncaughtException → dlog →
+    // shutdown), taking the clean-death path down with it. stderr carries the
+    // line and the reason — the terminal when the daemon runs by hand, and
+    // /dev/null under a detached spawn; the daemon keeps serving either way.
+    // Nulling the counter re-runs the lazy init on the next call, so a state
+    // dir removed out from under the daemon is recreated for the next line.
+    bytesWritten = null;
+    try {
+      process.stderr.write(
+        `${line}cc-candybar: daemon.log unwritable: ${(e as Error).message}\n`,
+      );
+    } catch {
+      // stderr was the last channel.
+    }
   }
 }

package/src/daemon/server.ts

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import net from "node:net";
+import v8 from "node:v8";
 import process from "node:process";
 import { fileURLToPath } from "node:url";
 import { parseArgs } from "node:util";
@@ -33,7 +34,7 @@ import {
   releaseRegistration,
   readRegistryEntry,
 } from "./fork-bomb-breaker";
-import { dlog, closeLog } from "./log";
+import { dlog } from "./log";
 import {
   PROTOCOL_VERSION,
   encodeFrame,
@@ -46,7 +47,12 @@ import { SessionUsageStore } from "./cache/session-usage-store";
 import { RenderCache } from "./cache/render";
 import { WatcherRegistry } from "./cache/watchers";
 import { RuntimeStats } from "./stats";
-import { makeLimits, realLimitsDeps, type LimitsHandle } from "./limits";
+import {
+  makeLimits,
+  realLimitsDeps,
+  rssLimitBytes,
+  type LimitsHandle,
+} from "./limits";
 import { armParentWatchdog, anchorFromEnv, pidAlive } from "./parent-watchdog";
 import { resetSpawnBackoff } from "./acquire";
 import { SessionState } from "./session-state";
@@ -154,6 +160,9 @@ let myStartTime: string | null = null;
 // waiting for the next boot's stale-sweep.
 let breakerRegistryPath: string | null = null;
 
+// The parsed memory budget (bytes); set first thing in runDaemon.
+let budgetBytes = 0;
+
 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
@@ -179,6 +188,23 @@ export function runDaemon(): void {
     });
   }
 
+  // [LAW:effects-at-boundaries] The memory budget is parsed here, before any
+  // resource is committed — a malformed override is refused before the breaker
+  // registers us, before the bind, before the lease, and before a `daemon up`
+  // line could claim a boot that is about to die. Parsed once, threaded into
+  // armLimits and the boot line.
+  // [LAW:single-enforcer] Refused through the same death funnel as every other
+  // boot failure. A synchronous throw here is NOT uncaught — it lands in
+  // index.ts's catch, whose stderr the detached spawn discards — so the one
+  // line that says why the daemon never came up would go nowhere.
+  try {
+    budgetBytes = rssLimitBytes(process.env);
+  } catch (err) {
+    dlog("error", `refusing to boot: ${(err as Error).message}`);
+    shutdown(1);
+    return;
+  }
+
   // [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
@@ -375,7 +401,12 @@ function onListening(sockPath: string): void {
   }
   dlog(
     "info",
-    `daemon up: pid=${process.pid} v=${PROTOCOL_VERSION} sock=${sockPath}`,
+    // [FRAMING:representation] Report the heap cap V8 actually applied (the
+    // territory), not the flag the spawner meant to pass (the map) — the one
+    // question a silent SIGABRT crash-loop leaves open is "which cap was live".
+    `daemon up: pid=${process.pid} v=${PROTOCOL_VERSION} sock=${sockPath} ` +
+      `heapCap=${Math.round(v8.getHeapStatistics().heap_size_limit / 1048576)}MB ` +
+      `rssLimit=${Math.round(budgetBytes / 1048576)}MB`,
   );
   // [LAW:single-enforcer] This bind is the one process-wide fact that answers
   // "did an outage just end" — see resetSpawnBackoff's doc comment in
@@ -458,7 +489,9 @@ function armBinaryWatch(): void {
 let limits: LimitsHandle | null = null;
 function armLimits(): void {
   limits = makeLimits(
-    realLimitsDeps(stats.startedAt.getTime(), (code) => shutdown(code)),
+    realLimitsDeps(stats.startedAt.getTime(), (code) => shutdown(code), {
+      rssLimitBytes: budgetBytes,
+    }),
   );
   limits.arm();
 }
@@ -569,7 +602,8 @@ function shutdown(code: number): void {
       (p) => fs.unlinkSync(p),
     );
   }
-  closeLog();
+  // Every dlog above was a synchronous append (log.ts), so the death line is
+  // already on disk; nothing to flush before exit.
   process.exit(code);
 }
 

package/src/dsl/render.ts

@@ -13,7 +13,7 @@
 
 import type { RichText, Palette, ThemeKey } from "@promptctl/rich-js";
 import { ColorSpec, Style, lighten, IDENTITY } from "@promptctl/rich-js";
-import type { Engine, Template } from "@promptctl/go-template-js";
+import { Defines, type Engine, type Template } from "@promptctl/go-template-js";
 import type {
   ValidatedConfig,
   VariableDecl,
@@ -213,38 +213,40 @@ function declareOne(
   }
 }
 
-// ─── Helper preamble ─────────────────────────────────────────────────────────
+// ─── Helpers ─────────────────────────────────────────────────────────────────
 
 // [LAW:single-enforcer] Compile the config's shared helper templates into ONE
-// output-neutral preamble: each name→body becomes a `{{ define "name" }}body{{ end }}`
-// block, concatenated with no interstitial text so the preamble emits nothing.
-// Prepended to every template this config parses, the defines resolve a
-// `{{ template "name" .arg }}` call locally — go-template-js scopes defines to a
-// single parse unit, so the define and the call MUST share one parse.
-// [LAW:no-silent-fallbacks] Each body is parsed in ISOLATION first, so a malformed
-// helper surfaces a per-helper diagnostic rather than a confusing error blamed on
-// the first segment that happens to call it.
-// [LAW:dataflow-not-control-flow] Empty helpers ⇒ "" ⇒ `engine.parse("" + src)`
-// is byte-identical to `engine.parse(src)`: existing configs are unaffected with
-// no special-case branch.
-function compileHelperPreamble(
+// define set: each name→body is parsed as its own `{{ define "name" }}body{{ end }}`
+// unit, chained onto the previous helpers' set, so the result is one `Defines`
+// every template this config parses inherits (`engine.parse(src, helpers)`).
+// [LAW:one-source-of-truth] Inherited by link, never by copy. The previous
+// shape — the defines' SOURCE prepended to every parse — re-parsed the whole
+// helper block into every template: ~100 KB of AST per parse for the 2 KB
+// stdlib block, ~287 parses per config, ~30 MB per config, and a daemon
+// holding twenty configs sat at 600 MB of nothing but duplicated helper ASTs
+// (the 2026-09-02 RSS-breach snapshot and the 2026-09-03 crash-loop).
+// [LAW:no-silent-fallbacks] Each body is parsed in ISOLATION, so a malformed
+// helper surfaces a per-helper diagnostic rather than a confusing error blamed
+// on the first segment that happens to call it; the redefinition check the
+// parser applies against the inherited set is what makes helper names unique.
+function compileHelpers(
   engine: Engine<RichText>,
   helpers: Readonly<Record<string, string>>,
-): string {
-  let preamble = "";
+): Defines {
+  let defines = Defines.EMPTY;
   for (const [name, body] of Object.entries(helpers)) {
-    const define = `{{ define "${name}" }}${body}{{ end }}`;
     try {
-      engine.parse(define);
+      defines = engine
+        .parse(`{{ define "${name}" }}${body}{{ end }}`, defines)
+        .defines();
     } catch (e) {
       throw new Error(
         `Template parse error in helpers.${name}: ${(e as Error).message}`,
         { cause: e },
       );
     }
-    preamble += define;
   }
-  return preamble;
+  return defines;
 }
 
 // ─── registerDslConfig ────────────────────────────────────────────────────────
@@ -379,16 +381,14 @@ export function registerDslConfig(
     },
     opts?.clock,
   );
-  // [LAW:single-enforcer] THE one parse path for this config: prepend the helper
-  // preamble so every template — segment template/when/bg/fg, node `when`, and
-  // action copy/open — resolves `{{ template "name" }}` calls against the same
-  // shared helpers. One closure, not raw engine.parse scattered across sites, so
-  // there is exactly one boundary where helpers come into scope (and one place a
-  // helper could fail to be visible). The preamble is compiled ONCE here, not per
-  // parse, and is "" when no helpers are declared.
-  const helperPreamble = compileHelperPreamble(engine, config.helpers);
-  const parse = (src: string): Template<RichText> =>
-    engine.parse(helperPreamble + src);
+  // [LAW:single-enforcer] THE one parse path for this config: every template —
+  // segment template/when/bg/fg, node `when`, and action copy/open — inherits
+  // the same helper define set, so `{{ template "name" }}` resolves against one
+  // shared AST. One closure, not raw engine.parse scattered across sites, so
+  // there is exactly one boundary where helpers come into scope (and one place
+  // a helper could fail to be visible). The helpers are parsed ONCE here.
+  const helpers = compileHelpers(engine, config.helpers);
+  const parse = (src: string): Template<RichText> => engine.parse(src, helpers);
   // [LAW:one-source-of-truth] Map each SessionState key → the variable that
   // reads it, so an option picker marks its current selection by reading the
   // SAME value the templates read — independent of whether the config named the