@promptctl/cc-candybar 1.40.0 → 1.41.1

package/src/config/settings-menu.ts

@@ -49,8 +49,13 @@ import {
   DISCLOSURE_GLYPH_CLOSED,
   DISCLOSURE_GLYPH_OPEN,
   disclosureCycleAction,
+  disclosureGate,
   disclosureStateVar,
+  disclosureTrigger,
+  type DisclosureRef,
 } from "./disclosure.js";
+import { declareHelp, type HelpDisclosure } from "./help.js";
+import { PERSIST_HELP } from "../help-text.js";
 import {
   EDIT_MODE_KEY,
   EDIT_MODE_OPEN,
@@ -127,11 +132,34 @@ const CONFIG_SEG = `${SETTINGS_NS}config`;
 // cannot silently write a durable default today — SessionState is per session.
 const PERSIST_KEY = PERSIST_SEG;
 
-// [LAW:one-source-of-truth] The config menu's own disclosure, spelled the same
-// way the anchor above is: ONE name that is the segment, the state variable and
-// the cycle action, so its toggle's click and its body's `when` cannot address
-// different keys.
-const CONFIG_OPEN_GATE = `{{ and (eq .${SETTINGS_ANCHOR} "${SETTINGS_OPEN}") (eq .${CONFIG_SEG} "${SETTINGS_OPEN}") }}`;
+// [LAW:one-source-of-truth] The two disclosures this menu IS, as refs rather
+// than as gate strings: every gate below — and every `(?)` nested inside them —
+// derives from these, so the toggle that writes a key and the `when` that reads
+// it cannot name different variables.
+const SETTINGS_REF: DisclosureRef = {
+  variable: SETTINGS_ANCHOR,
+  member: SETTINGS_OPEN,
+};
+const CONFIG_REF: DisclosureRef = {
+  variable: CONFIG_SEG,
+  member: SETTINGS_OPEN,
+};
+
+// Gated on BOTH keys — a config row left open yesterday must not render beside
+// a closed menu today. Nesting is conjunction, which is why it is one list.
+const CONFIG_OPEN_GATE = disclosureGate(SETTINGS_REF, CONFIG_REF);
+
+// The `(?)` that explains `persist?` — the one control in this menu whose
+// behaviour a user cannot infer from its label, which is exactly why the ticket
+// named it as a required use site. Its body says what the NEXT click does, in
+// the same two sentences `--help` prints.
+const PERSIST_HELP_SEG = `${SETTINGS_NS}help.persist`;
+
+// [LAW:one-source-of-truth] The panel's surface colours, spelled once. The help
+// cells must wear the same ones as the controls they explain — a `(?)` body in
+// a different colour reads as a different panel — and that agreement is only
+// guaranteed if there is one value to hand both.
+const SETTINGS_SURFACE = { bg: "surface", fg: "foreground" } as const;
 
 // [LAW:one-source-of-truth] One accordion key for every picker in the menu:
 // one key holds one open member, so opening a theme picker closes the look
@@ -278,7 +306,7 @@ const controlReset = (name: string): string => `${SETTINGS_NS}reset.${name}`;
 // from the same anchor string the toggle's cycle writes — spelled once here,
 // exactly as lowerGroup derives a group body's `when` from the group's own
 // reference name.
-const SETTINGS_OPEN_GATE = `{{ eq .${SETTINGS_ANCHOR} "${SETTINGS_OPEN}" }}`;
+const SETTINGS_OPEN_GATE = disclosureGate(SETTINGS_REF);
 
 // [LAW:single-enforcer] The one answer to "is this segment reference the global
 // menu's anchor". cross-ref.ts asks it to accept an authored placement of a name
@@ -379,7 +407,10 @@ export function countAnchors(node: LayoutNode): number {
 // a vertical pair of the toggle segment and a `when`-gated body. Replaces the
 // anchor leaf wherever it sits, so the author's chosen position is the menu's
 // position with nothing else moved.
-function expandAnchor(node: AnchoredRoot | LayoutNode): LayoutNode {
+function expandAnchor(
+  node: AnchoredRoot | LayoutNode,
+  help: HelpDisclosure,
+): LayoutNode {
   if (node.kind === "segment") {
     return isSettingsAnchor(node.name)
       ? {
@@ -395,6 +426,32 @@ function expandAnchor(node: AnchoredRoot | LayoutNode): LayoutNode {
               direction: "horizontal",
               children: [
                 { kind: "segment", name: PERSIST_SEG },
+                // The `(?)` rides the row that already exists, immediately
+                // after the control it explains — so closed help costs no row
+                // and widens the bar by one cell, and open help reads as an
+                // answer to the checkbox on its left.
+                //
+                // Mid-row, DELIBERATELY, unlike edit mode's `(?)`, which
+                // edit-chrome.ts goes to lengths to trail. The difference is
+                // structural, not a discipline applied in one file and skipped
+                // here. `nextHueShift` (src/dsl/render.ts:697) counts segment
+                // leaves in pre-order, so a leaf's hue index is the number of
+                // leaves before it — which makes the consequence arithmetic:
+                // reordering leaves WITHIN a subtree cannot change the index of
+                // any leaf AFTER it, since the subtree's leaf count does not
+                // move. Edit chrome WRAPS the whole tree, so trailing there is
+                // after every existing leaf and costs zero. This menu splices
+                // MID-TREE at an anchor `withAnchor` lets the author put
+                // anywhere, so no position inside it is after the rest of the
+                // bar: the leaves it adds — this trigger plus one per
+                // PERSIST_HELP line, a count that lives in help-text.ts and is
+                // deliberately not copied here — shift everything past the
+                // anchor wherever inside the menu they sit. Trailing would cost
+                // the adjacency that IS the affordance. The fix is decoupling
+                // colour from tree position — candybar-render-y5h, which fixes
+                // every mid-tree synthesis at once rather than one file at a
+                // time.
+                help.trigger,
                 ...PRIMARY_CONTROLS.map(
                   (c): LayoutNode => ({
                     kind: "segment",
@@ -406,6 +463,9 @@ function expandAnchor(node: AnchoredRoot | LayoutNode): LayoutNode {
               ],
               when: SETTINGS_OPEN_GATE,
             },
+            // The help body: one row, present only while the `(?)` is open,
+            // directly under the row that asked the question.
+            help.body,
             // Row two: the display settings, behind their own disclosure so
             // the menu opens narrow. Gated on BOTH keys — a config row left
             // open yesterday must not render beside a closed menu today; one
@@ -429,7 +489,10 @@ function expandAnchor(node: AnchoredRoot | LayoutNode): LayoutNode {
         }
       : node;
   }
-  return { ...node, children: node.children.map(expandAnchor) };
+  return {
+    ...node,
+    children: node.children.map((child) => expandAnchor(child, help)),
+  };
 }
 
 // ─── The artifacts ──────────────────────────────────────────────────────────
@@ -476,7 +539,10 @@ function declareHostedMenu(
 // reference, and a second reference to one declaration is a reuse, not the
 // self-collision a second `kind: "group"` node would be (see the settingsDrawer
 // comment in default-dsl-config.ts for that hazard in its original form).
-function settingsArtifacts(): MenuArtifacts {
+function settingsArtifacts(): {
+  artifacts: MenuArtifacts;
+  help: HelpDisclosure;
+} {
   const artifacts: MenuArtifacts = {
     variables: {
       [SETTINGS_ANCHOR]: disclosureStateVar(SETTINGS_ANCHOR, DISCLOSURE_CLOSED),
@@ -497,22 +563,27 @@ function settingsArtifacts(): MenuArtifacts {
       // [LAW:representation] The glyph trails the label it gates, per the
       // disclosure vocabulary every other toggle in the bar reads by.
       [SETTINGS_ANCHOR]: {
-        template: `{{ action "${SETTINGS_ANCHOR}" "☰ ${DISCLOSURE_GLYPH_CLOSED}" "☰ ${DISCLOSURE_GLYPH_OPEN}" }}`,
-        bg: "surface",
-        fg: "foreground",
+        template: disclosureTrigger(
+          SETTINGS_ANCHOR,
+          `☰ ${DISCLOSURE_GLYPH_CLOSED}`,
+          `☰ ${DISCLOSURE_GLYPH_OPEN}`,
+        ),
+        ...SETTINGS_SURFACE,
       },
       // [LAW:representation] The checkbox states what the NEXT write does,
       // which is why the glyph and the word live together: "☑ persist?" is
       // the whole explanation of where the click below it lands.
       [PERSIST_SEG]: {
         template: `{{ action "${PERSIST_SEG}" "☐ persist?" "☑ persist?" }}`,
-        bg: "surface",
-        fg: "foreground",
+        ...SETTINGS_SURFACE,
       },
       [CONFIG_SEG]: {
-        template: `{{ action "${CONFIG_SEG}" "⚙ config ${DISCLOSURE_GLYPH_CLOSED}" "⚙ config ${DISCLOSURE_GLYPH_OPEN}" }}`,
-        bg: "surface",
-        fg: "foreground",
+        template: disclosureTrigger(
+          CONFIG_SEG,
+          `⚙ config ${DISCLOSURE_GLYPH_CLOSED}`,
+          `⚙ config ${DISCLOSURE_GLYPH_OPEN}`,
+        ),
+        ...SETTINGS_SURFACE,
       },
       // [LAW:one-type-per-behavior] Both non-picker controls read the same
       // `.effective` projection their picker siblings read, and write the
@@ -522,8 +593,7 @@ function settingsArtifacts(): MenuArtifacts {
         template:
           `{{ action "${controlApply("wrap")}" "wrap: on" "wrap: off" }} ` +
           `{{ action "${controlReset("wrap")}" "↺" }}`,
-        bg: "surface",
-        fg: "foreground",
+        ...SETTINGS_SURFACE,
       },
       [PADDING_SEG]: {
         template:
@@ -531,8 +601,7 @@ function settingsArtifacts(): MenuArtifacts {
           "padding {{ .padding.effective }} " +
           `{{ action "${controlApply("padding")}.up" "▶" }} ` +
           `{{ action "${controlReset("padding")}" "↺" }}`,
-        bg: "surface",
-        fg: "foreground",
+        ...SETTINGS_SURFACE,
       },
       // The entry point edit mode never had: `edit.toggle` is a reserved action
       // whose only bundled reference lives in the `toolbar` segment, which a
@@ -540,8 +609,7 @@ function settingsArtifacts(): MenuArtifacts {
       // from a segment no config can drop.
       [EDIT_SEG]: {
         template: `{{ action "${EDIT_TOGGLE_ACTION}" "✎ edit" "✎ done" }}`,
-        bg: "surface",
-        fg: "foreground",
+        ...SETTINGS_SURFACE,
       },
     },
   };
@@ -555,7 +623,19 @@ function settingsArtifacts(): MenuArtifacts {
     DISCLOSURE_CLOSED,
   );
   declareSettingControls(artifacts);
-  return artifacts;
+  // [LAW:one-source-of-truth] The `(?)` is minted here, with the panel it
+  // belongs to, and its two NODES are returned so `expandAnchor` places them by
+  // the value it is handed rather than by re-deriving names this pass already
+  // owns. Nested in SETTINGS_REF, so closing the menu takes the open help with
+  // it.
+  const help = declareHelp(
+    PERSIST_HELP_SEG,
+    PERSIST_HELP,
+    [SETTINGS_REF],
+    artifacts,
+    SETTINGS_SURFACE,
+  );
+  return { artifacts, help };
 }
 
 // [LAW:one-source-of-truth] Every setting the menu offers, minted from the one
@@ -581,8 +661,7 @@ function declareSettingControls(artifacts: MenuArtifacts): void {
         `{{ menu "${apply}" "${DISCLOSURE_GLYPH_CLOSED}" "${DISCLOSURE_GLYPH_OPEN}" ` +
         `(dict "key" "${PICKER_KEY}" "closeOnPick" true) }} ` +
         `{{ action "${controlReset(c.name)}" "↺" }}`,
-      bg: "surface",
-      fg: "foreground",
+      ...SETTINGS_SURFACE,
     };
     artifacts.actions[apply] = {
       set: c.sessionKey,
@@ -676,14 +755,14 @@ export function canHostSessionState(config: DslConfig): boolean {
 // and every name now declares one.
 export function synthesizeSettingsMenu(config: DslConfig): DslConfig {
   if (!canHostSessionState(config)) return config;
-  const artifacts = settingsArtifacts();
+  const { artifacts, help } = settingsArtifacts();
   ensureEditToggle(artifacts);
   const presets: Record<string, PresetDecl> = { ...config.presets };
   for (const name of presetNames(config.presets)) {
     const { node } = presetRoot(config, name);
     presets[name] = {
       ...presetByName(config.presets, name),
-      root: expandAnchor(withAnchor(node)),
+      root: expandAnchor(withAnchor(node), help),
     };
   }
   return {

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,66 @@ 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): a cold daemon seeding a large transcript tree
+// for a dozen sessions 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 = 2048;
+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 +98,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/help-text.ts

@@ -1,4 +1,5 @@
 import { DISCLOSURE_GLYPH_CLOSED } from "./config/disclosure";
+import { HELP_GLYPH_CLOSED } from "./config/help";
 
 // [LAW:effects-at-boundaries] Pure data, no I/O — index.ts owns the console.log
 // effect. Kept as its own module so the text is importable (and testable) without
@@ -6,6 +7,29 @@ import { DISCLOSURE_GLYPH_CLOSED } from "./config/disclosure";
 // [LAW:one-source-of-truth] The disclosure glyph comes from config/disclosure.ts
 // (the same constant the theme/look picker itself renders with), so this text
 // can't drift from what a user actually sees on the bar.
+// [LAW:one-source-of-truth] THE help corpus, as data. `--help` and the bar's
+// own `(?)` disclosures are two RENDERINGS of these arrays, never two copies of
+// the sentences: a `(?)` segment's template IS one of these strings, and the
+// paragraphs below interpolate the same values. A help sentence typed into a
+// segment template — where nothing would ever notice it drifting from the CLI's
+// wording — is the defect this shape exists to make unrepresentable.
+//
+// [LAW:representation] One line is one CELL on the bar, so each is a complete
+// thought that stands alone and each stays short: `(?)` bodies drop below their
+// row, and a body that overflows `term.cols` wraps into more rows than the fact
+// it explains is worth. Every line leads with the glyph it explains, so the
+// reader matches text to affordance by shape rather than by reading order.
+export const EDIT_MODE_HELP = [
+  "+ inserts here",
+  "- removes the one left of it",
+  "↺ undoes edits",
+] as const;
+
+export const PERSIST_HELP = [
+  "☐ this session only",
+  "☑ default for every session",
+] as const;
+
 export const HELP_TEXT = `
 cc-candybar - Beautiful powerline statusline for Claude Code
 
@@ -27,8 +51,10 @@ Configuration:
   needed, and writing your own \`root\` cannot delete it. Click
   ☰ ${DISCLOSURE_GLYPH_CLOSED} on the bar for preset switching, edit mode, and a config menu
   of clickable theme/look/style/wrap/padding controls. The \`persist?\`
-  checkbox there chooses where a change lands: unchecked it applies to this
-  session only, checked it becomes the default every session opens with.
+  checkbox there chooses where a change lands: ${PERSIST_HELP.join(", ")}.
+
+  Anywhere the bar shows ${HELP_GLYPH_CLOSED}, clicking it reveals these same instructions
+  in place. In edit mode: ${EDIT_MODE_HELP.join(", ")}.
 
 Subcommands:
   install                  One-shot setup: stages the runtime (native render