@promptctl/cc-candybar 1.22.0 → 1.24.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@promptctl/cc-candybar",
-  "version": "1.22.0",
+  "version": "1.24.0",
   "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",
@@ -31,8 +31,6 @@
     "check:protocol": "node scripts/check-protocol.mjs",
     "gen:schema": "tsx scripts/gen-schema.ts",
     "check:schema": "tsx scripts/check-schema.ts",
-    "prepack": "node scripts/write-bin-placeholder.mjs",
-    "postinstall": "node scripts/postinstall.mjs",
     "prepublishOnly": "npm run lint && npm run typecheck && npm run check:protocol && npm run check:schema && npm run build"
   },
   "keywords": [
@@ -86,30 +84,16 @@
     "ts-jest": "^29.4.1",
     "tsdown": "^0.21.4",
     "tsx": "^4.21.0",
-    "typescript": "^5.0.0"
-  },
-  "dependencies": {
+    "typescript": "^5.0.0",
     "@promptctl/go-template-js": "^0.7.0",
     "@promptctl/rich-js": "^0.6.0",
     "json5": "^2.2.3",
     "mobx": "^6.15.0"
   },
   "optionalDependencies": {
-    "@promptctl/cc-candybar-darwin-arm64": "1.22.0",
-    "@promptctl/cc-candybar-darwin-x64": "1.22.0",
-    "@promptctl/cc-candybar-linux-x64": "1.22.0",
-    "@promptctl/cc-candybar-linux-arm64": "1.22.0"
-  },
-  "pnpm": {
-    "supportedArchitectures": {
-      "os": [
-        "darwin",
-        "linux"
-      ],
-      "cpu": [
-        "x64",
-        "arm64"
-      ]
-    }
+    "@promptctl/cc-candybar-darwin-arm64": "1.24.0",
+    "@promptctl/cc-candybar-darwin-x64": "1.24.0",
+    "@promptctl/cc-candybar-linux-x64": "1.24.0",
+    "@promptctl/cc-candybar-linux-arm64": "1.24.0"
   }
 }

package/src/check.ts

@@ -25,6 +25,7 @@ import {
   ConfigError,
 } from "./config/dsl-loader.js";
 import { expandHome } from "./config/loader/discovery.js";
+import { DEFAULT_DSL_CONFIG } from "./config/default-dsl-config.js";
 import { VariableStore } from "./var-system/store.js";
 import { SourceRegistry } from "./var-system/sources.js";
 import { SessionState } from "./daemon/session-state.js";
@@ -250,7 +251,7 @@ function loadRegisterRender(
   cwd: string,
   warnings: string[],
 ): string {
-  const { config: merged, source } = loadConfig(configPath);
+  const { config: merged, source } = loadConfig(configPath, DEFAULT_DSL_CONFIG);
   const config = validateConfig(merged, configPath ?? "<default>", source);
 
   const store = new VariableStore();

package/src/config/default-dsl-config.ts

@@ -19,12 +19,16 @@
 // (add its name to the children), not new code. The same data flows through
 // the same render path whether the root has 1 leaf or 16.
 //
-// [LAW:types-are-the-program] `satisfies DslConfig` (not an annotation)
-// preserves the literal's narrow keys for downstream consumers — every
-// declared segment name shows up as a known key, every variable name shows
-// up in the input set the daemon must populate.
+// [LAW:types-are-the-program] The authored literal (RAW_DEFAULT_DSL_CONFIG)
+// uses `satisfies DslConfig` (not an annotation) so every declared segment
+// and variable name is checked against the real shape at the point of
+// authoring. The exported DEFAULT_DSL_CONFIG is that literal run through the
+// loader's own synthesis pass (see the bottom of this file) — a `DslConfig`,
+// the same effective shape every user config resolves to.
 
-import type { DslConfig } from "./dsl-types.js";
+import type { DslConfig, SegmentDecl } from "./dsl-types.js";
+import { parseDslConfig } from "./dsl-loader.js";
+import { mergeWithDefault } from "./loader/merge.js";
 
 // ─── Shared template fragments ───────────────────────────────────────────────
 //
@@ -144,7 +148,15 @@ function etaHeatFg(etaRef: string, warnRef: string): string {
 
 // ─── The default config ──────────────────────────────────────────────────────
 
-export const DEFAULT_DSL_CONFIG = {
+// [LAW:one-source-of-truth] The AUTHORED literal, pre-synthesis. Production
+// code wants the synthesized DEFAULT_DSL_CONFIG below; this is exported only
+// for tests that round-trip "what a user would get by copy-pasting the
+// bundled default into their own file" through the real per-file parse —
+// that round-trip must start from the AUTHORED declarations, never from
+// DEFAULT_DSL_CONFIG's own already-synthesized `menus.*` entries (reparsing
+// those would trip the reserved-namespace guard, which exists to catch a
+// user hand-declaring a name only synthesis may write).
+export const RAW_DEFAULT_DSL_CONFIG = {
   globals: {
     // Picked by the daemon's basePalette resolution; user overrides in their
     // own config. catppuccin-latte ships every spec name the default
@@ -814,20 +826,56 @@ export const DEFAULT_DSL_CONFIG = {
       bg: "surface",
       fg: "foreground",
     },
+    // Theme control — the palette switcher, wired into the DEFAULT bar
+    // (brandon-theming-8uj.1) so theme selection is discoverable without
+    // reading docs/interaction-authoring.md or hand-authoring a config.
+    // [LAW:one-source-of-truth] The trigger reads `.theme.effective` — the
+    // SAME daemon-resolved name (effectiveThemeName) the rendered basePalette
+    // is built from — so the label and the colors can never drift; unlike
+    // styleControl (no "effective style" input exists), no extra `state`
+    // variable is needed here. Shares the "pickers" accordion key with
+    // lookControl so opening one closes the other, the docs' canonical
+    // two-menu pairing.
+    themeControl: {
+      template:
+        "🎨 {{ .theme.effective }} " +
+        '{{ menu "applyTheme" (dict "key" "pickers") }}',
+      bg: "surface",
+      fg: "foreground",
+    },
+    // Look control — the theme-ADAPTATION switcher (see the `looks` block
+    // below), the exact twin of themeControl one dimension over:
+    // `.look.effective` is the daemon-resolved name (effectiveLookName) the
+    // rendered ThemeKey composes from. closeOnPick collapses the drop after a
+    // pick — looks are tried one at a time against the chosen theme, not
+    // stacked open.
+    lookControl: {
+      template:
+        "◐ {{ .look.effective }} " +
+        '{{ menu "applyLook" (dict "key" "pickers" "closeOnPick" true) }}',
+      bg: "surface",
+      fg: "foreground",
+    },
   },
 
   // Default layout — the canonical LayoutNode tree (`satisfies DslConfig`
   // requires the lowered form here; the terse Option-A `{ h/v/seg }` grammar is
   // the loader's authoring surface for user JSON, not this typed literal).
   //
-  // Two rows stacked by the vertical container: an IDENTITY + ACTIONS row
+  // Three rows stacked by the vertical container: an IDENTITY + ACTIONS row
   // (where am I / what can I do here — the directory, the verbose `gitaculous`
   // line (repo, sha, working-tree, upstream, stash, time-since-commit), then the
   // quick-action tray: copy session id, open project / transcript in the editor)
   // over a STATUS row (what's happening now — model, context-window fill,
-  // prompt-cache warmth, and the 5h / 7d rate-limit quotas). The tray sits on
-  // the identity row because its actions are workspace-scoped (this session,
-  // this project), not usage metrics. Each row zips its segments through the
+  // prompt-cache warmth, and the 5h / 7d rate-limit quotas) over an APPEARANCE
+  // row (theme + look pickers, brandon-theming-8uj.1 — the bundled default's
+  // only on-bar affordance to discover and use the theme/look feature without
+  // reading docs or hand-authoring a config). The tray sits on the identity
+  // row because its actions are workspace-scoped (this session, this
+  // project), not usage metrics; the pickers get their own row rather than
+  // crowding the identity row because a `{{ menu }}` drops its picker body
+  // onto the line immediately below its row, and that drop must not land on
+  // top of an unrelated row's content. Each row zips its segments through the
   // powerline joiner; `\n` separates the rows.
   //
   // [LAW:dataflow-not-control-flow] Every status segment is when-gated on its
@@ -861,6 +909,14 @@ export const DEFAULT_DSL_CONFIG = {
           { kind: "segment", name: "weekly" },
         ],
       },
+      {
+        kind: "container",
+        direction: "horizontal",
+        children: [
+          { kind: "segment", name: "themeControl" },
+          { kind: "segment", name: "lookControl" },
+        ],
+      },
     ],
   },
 
@@ -895,6 +951,17 @@ export const DEFAULT_DSL_CONFIG = {
     // rendered click and the wire gate share that one source — a template cannot
     // smuggle an un-gated style write.
     applyStyle: { set: "style", from: "styles" },
+
+    // [LAW:locality-or-seam] The theme/look pickers' behaviors, decoupled by
+    // NAME from themeControl/lookControl {{ menu }}s above — same seam as
+    // applyStyle. "theme" is the baseline permanent state key (validateTheme,
+    // registered in state-validators.ts); dropBaselineAllowLists reuses that
+    // gate for an allow-list contribution instead of re-registering it, so
+    // this action derives nothing new. "look" has no baseline entry, so this
+    // action derives a fresh allow-list validator ranging the merged `looks`
+    // block's names — the same derivation test/dsl-looks.test.ts exercises.
+    applyTheme: { set: "theme", from: "themes" },
+    applyLook: { set: "look", from: "looks" },
   },
 
   // ─── Looks ───────────────────────────────────────────────────────────────
@@ -1058,3 +1125,46 @@ export const DEFAULT_DSL_CONFIG = {
       "{{ else }}{{ . }}m{{ end }}",
   },
 } satisfies DslConfig;
+
+// [LAW:locality-or-seam] The palette names this module-level parse is allowed
+// to accept — DERIVED from RAW_DEFAULT_DSL_CONFIG itself (globals.palette +
+// every per-segment palette: pin), never from the live theme registry
+// (listResolvablePaletteNames()). A real user file must validate against the
+// live registry (an author can type any name); this file validates against
+// ITSELF (every name here is a literal we wrote and every render test below
+// exercises against the real registry already). This is what keeps the
+// module-load parse below from ever depending on the registry being healthy
+// at import time — a registry-loading bug elsewhere would surface where it
+// actually matters (a real render failing), never as an uncatchable crash on
+// every importer of this file before any daemon/CLI error handling runs.
+const AUTHORED_PALETTE_NAMES = new Set(
+  [
+    RAW_DEFAULT_DSL_CONFIG.globals.palette,
+    ...(Object.values(RAW_DEFAULT_DSL_CONFIG.segments) as SegmentDecl[]).map(
+      (s) => s.palette,
+    ),
+  ].filter((name): name is string => name !== undefined),
+);
+
+// [LAW:single-enforcer] Run the authored literal through the SAME
+// parse → synthesize pipeline every user config goes through (JSON5 stage +
+// synthesizeMenuDecls' `menus.*` synthesis, and any future group/menu
+// synthesis pass) instead of hand-duplicating that logic here. Without this,
+// the zero-config daemon path (loadConfig: no config file found ⇒ raw={},
+// merged directly against this constant — see src/config/dsl-loader.ts and
+// src/config/loader/merge.ts) would ship an UNSYNTHESIZED default: a
+// `{{ menu (dict "key" …) }}` accordion pairing (themeControl/lookControl,
+// brandon-theming-8uj.1) would render its glyph, but clicking it would reject
+// with "unknown state key" — the synthesis that derives a menu's `menus.*`
+// state var + cycle action only ever ran over TEXT a user typed, never over
+// this TS literal. Round-tripping through JSON is exactly what
+// test/default-dsl-config.test.ts's SERIALIZED-based tests already exercise,
+// so this is the same well-tested path, run once here instead of skipped.
+export const DEFAULT_DSL_CONFIG: DslConfig = mergeWithDefault(
+  parseDslConfig(
+    "<default>",
+    JSON.stringify(RAW_DEFAULT_DSL_CONFIG),
+    AUTHORED_PALETTE_NAMES,
+  ),
+  RAW_DEFAULT_DSL_CONFIG,
+);

package/src/config/dsl-loader.ts

@@ -30,7 +30,6 @@ import {
   type RawDslConfig,
   type ValidatedConfig,
 } from "./dsl-types.js";
-import { DEFAULT_DSL_CONFIG } from "./default-dsl-config.js";
 import { listResolvablePaletteNames } from "../themes/policy.js";
 import {
   ConfigError,
@@ -78,14 +77,23 @@ export {
 // ─── Three-stage pipeline ────────────────────────────────────────────────────
 
 /**
- * Load a JSON5 DSL config file from disk and merge it with the bundled
+ * Load a JSON5 DSL config file from disk and merge it with the given
  * default. Returns the effective DslConfig AND the raw source text.
  *
- * `path = null` means "no user file exists" — returns the default unchanged
- * (uniform merge against an empty raw, which is deep-equal to the default) and
+ * `path = null` means "no user file exists" — returns `dflt` unchanged
+ * (uniform merge against an empty raw, which is deep-equal to `dflt`) and
  * an empty source. No consumer branches on file presence; that branch lives
  * inside loadConfig exactly once.
  *
+ * [LAW:one-way-deps] `dflt` is a required parameter, not a default pointing at
+ * DEFAULT_DSL_CONFIG: this module is generic merge/parse machinery, and
+ * DEFAULT_DSL_CONFIG is a specific, higher-level instance built ON TOP of it
+ * (default-dsl-config.ts imports parseDslConfig/mergeWithDefault to
+ * synthesize itself — see that file). A default param here pointing back at
+ * DEFAULT_DSL_CONFIG would make this generic module depend on its own
+ * specific consumer — a cycle every caller who wants "the bundled default"
+ * resolves explicitly by importing DEFAULT_DSL_CONFIG themselves.
+ *
  * [LAW:one-source-of-truth] The source is returned alongside the config so the
  * caller can hand it to validateConfig — cross-ref diagnostics (line numbers,
  * the authored-surface discriminator) are derived from it, and the file is read
@@ -99,7 +107,7 @@ export {
  */
 export function loadConfig(
   path: string | null,
-  dflt: DslConfig = DEFAULT_DSL_CONFIG,
+  dflt: DslConfig,
   allowedPalettes?: ReadonlySet<string>,
 ): { config: DslConfig; source: string } {
   const source = path === null ? "" : fs.readFileSync(path, "utf-8");

package/src/config/loader/merge.ts

@@ -1,11 +1,19 @@
-// [LAW:one-source-of-truth] The single point that consults DEFAULT_DSL_CONFIG to
-// fill missing keys. A user file declares only what differs; the cascade here
-// (shallow-merge globals, by-name merge variables/segments/actions, wholesale
-// root replacement) is the one place "absent means inherit" is decided.
-// This file changes when the merge semantics change.
+// [LAW:one-source-of-truth] The single point that merges a raw user config
+// onto a default DslConfig to fill missing keys. A user file declares only
+// what differs; the cascade here (shallow-merge globals, by-name merge
+// variables/segments/actions, wholesale root replacement) is the one place
+// "absent means inherit" is decided. This file changes when the merge
+// semantics change.
+//
+// [LAW:one-way-deps] `dflt` is a required parameter — this module is generic
+// merge machinery and does not know about DEFAULT_DSL_CONFIG, the specific
+// bundled instance built ON TOP of it (default-dsl-config.ts imports this
+// function to synthesize itself). A default param pointing back at
+// DEFAULT_DSL_CONFIG would make this generic module depend on its own
+// specific consumer, a cycle. Callers who want "the bundled default" import
+// DEFAULT_DSL_CONFIG from default-dsl-config.ts and pass it explicitly.
 
 import { type DslConfig, type RawDslConfig } from "../dsl-types.js";
-import { DEFAULT_DSL_CONFIG } from "../default-dsl-config.js";
 
 /**
  * Merge a RawDslConfig on top of a default DslConfig. Pure function.
@@ -21,7 +29,7 @@ import { DEFAULT_DSL_CONFIG } from "../default-dsl-config.js";
  */
 export function mergeWithDefault(
   raw: RawDslConfig,
-  dflt: DslConfig = DEFAULT_DSL_CONFIG,
+  dflt: DslConfig,
 ): DslConfig {
   return {
     globals: { ...dflt.globals, ...(raw.globals ?? {}) },

package/src/daemon/acquire.ts

@@ -7,6 +7,7 @@ import {
   socketPath,
   spawnLockPath,
   spawnCooldownPath,
+  spawnBackoffPath,
   daemonDir,
 } from "./paths";
 
@@ -335,32 +336,167 @@ export type CooldownDecision =
   | { kind: "allow-future-garbage"; futureMs: number }
   | { kind: "deny" };
 
-export function cooldownDecision(ageMs: number | null): CooldownDecision {
+// [LAW:types-are-the-program] `cooldownMs` is the required window, not a
+// captured constant — the decision is the same pure fold whether the caller
+// is checking against the base SPAWN_COOLDOWN_MS or a backed-off window from
+// effectiveCooldownMs(streak) below. Generalizing the threshold into a
+// parameter is what let brandon-daemon-lifecycle-gad.3 add exponential
+// backoff without touching this function's tested boundary arithmetic.
+export function cooldownDecision(
+  ageMs: number | null,
+  cooldownMs: number,
+): CooldownDecision {
   if (ageMs === null) return { kind: "allow" };
   if (ageMs < -STALE_LOCK_MS)
     return { kind: "allow-future-garbage", futureMs: -ageMs };
-  if (ageMs < SPAWN_COOLDOWN_MS) return { kind: "deny" };
+  if (ageMs < cooldownMs) return { kind: "deny" };
   return { kind: "allow" };
 }
 
+// ─── Spawn backoff (consecutive non-convergence widens the cooldown) ────────
+//
+// [LAW:one-source-of-truth] spawn.cooldown's mtime answers "when was a spawn
+// last attempted"; this streak answers "how many attempts in a row have
+// failed to converge on a live daemon" — a fact spawn.cooldown's mtime alone
+// cannot carry (mtime is overwritten on every attempt, losing the count). One
+// small file, one fact, read/written by both runtimes exactly like
+// spawn.cooldown itself.
+//
+// [LAW:single-enforcer] The daemon is the only process that can know
+// "convergence achieved" (it just bound the socket and is about to serve) —
+// see resetSpawnBackoff(), called once from server.ts's onListening(). A
+// client-side reset would need a full successful render round-trip on the
+// hot path to detect convergence, adding fs I/O to the common case for a
+// signal the daemon already has for free at boot.
+//
+// Growth is capped at SPAWN_BACKOFF_MAX_STREAK shifts so effectiveCooldownMs
+// never has to reason about an unbounded streak (a multi-day outage would
+// otherwise grow the stored integer without bound) and so Rust's mirrored
+// `<<` cannot overflow. 3_000ms << 5 = 96_000ms, already past the 60s cap, so
+// 5 is sufficient — not tuned to any particular outage length.
+export const SPAWN_BACKOFF_CAP_MS = 60_000;
+export const SPAWN_BACKOFF_MAX_STREAK = 5;
+
+// [LAW:behavior-not-structure] Pure over the streak; no filesystem. Mirrors
+// Rust's effective_cooldown_ms exactly (diffed by check-protocol for the two
+// constants; the arithmetic itself is pinned by the boundary unit tests on
+// both sides, matching cooldownDecision's existing pattern).
+export function effectiveCooldownMs(streak: number): number {
+  const capped = Math.min(Math.max(streak, 0), SPAWN_BACKOFF_MAX_STREAK);
+  return Math.min(SPAWN_COOLDOWN_MS * 2 ** capped, SPAWN_BACKOFF_CAP_MS);
+}
+
+// [LAW:no-defensive-null-guards] Number(raw) — not parseInt — so trailing
+// garbage ("5abc", "5.0") fails closed to NaN instead of being silently
+// truncated to a plausible-looking integer. parseInt's truncation is exactly
+// the bug daemonCeiling() (fork-bomb-breaker.ts, brandon-daemon-lifecycle-gad.2)
+// fixed for the same "small integer parsed from an untrusted local file" shape;
+// repeating parseInt here would reintroduce it. The clamp to
+// SPAWN_BACKOFF_MAX_STREAK also bounds every value this function can ever
+// return, so no caller — including `streak + 1` — needs its own re-clamp to
+// stay overflow-safe (Rust's mirror clamps at the identical boundary, since a
+// raw u32 parsed from disk has no such guarantee otherwise).
+// Exported so the parsing-strictness contract (Number, not parseInt — see
+// the comment above) has a direct test independent of any caller's file
+// content, matching cooldownDecision/effectiveCooldownMs's own exported-for-
+// testing precedent.
+export function readBackoffStreak(filePath: string): number {
+  // [LAW:no-silent-failure] A missing or garbage streak file is NOT
+  // ambiguous the way a missing cooldown mtime is: falling back to 0 always
+  // fails toward the SAME safe direction as the rest of this module (spawn
+  // permitted at the base rate, never wedged) — matching cooldownDecision's
+  // own `ageMs === null → allow`. Never loud here; the failure mode is
+  // "one extra spawn," which bind() already arbitrates.
+  try {
+    const raw = fs.readFileSync(filePath, "utf8").trim();
+    const n = Number(raw);
+    if (!Number.isInteger(n) || n < 0) return 0;
+    return Math.min(n, SPAWN_BACKOFF_MAX_STREAK);
+  } catch {
+    return 0;
+  }
+}
+
+// [LAW:no-ambient-temporal-coupling] The read-then-write here (and in
+// claimSpawnCooldown below) is not atomic across process boundaries — two
+// client processes racing through a daemon-miss window can both read the
+// same streak and both write the same increment, undercounting by one. This
+// is an accepted, bounded trade, not an oversight: the ONLY failure direction
+// is undercounting (the streak can never advance faster than reality), so a
+// race just means backoff ramps a little slower than ideal — it can never
+// permit MORE spawning than a race-free count would. The hard rate ceiling
+// remains spawn.cooldown's mtime gate, which spawn.lock already serializes
+// for the common case; this file, like spawn.lock's own documented
+// thundering-herd tolerance, is a best-effort optimization on top of that,
+// not a second load-bearing lock.
+function writeBackoffStreak(filePath: string, streak: number): void {
+  try {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, String(streak), { mode: 0o600 });
+  } catch (e) {
+    process.stderr.write(
+      `cc-candybar: could not record spawn.backoff: ${(e as Error).message}\n`,
+    );
+  }
+}
+
+// Called once by the daemon (server.ts onListening) the moment it binds the
+// socket — the one process-wide fact that answers "did an outage just end."
+// Deletes rather than writes "0": absence already reads as streak 0 via
+// readBackoffStreak's catch branch, so there is no separate reset format to
+// keep in sync with the normal write path.
+//
+// [LAW:no-ambient-temporal-coupling] This fires on bind, not on confirmed
+// sustained liveness — in the vanishingly rare socket-capture race
+// documented above armOwnershipWatch (server.ts), a daemon that only THINKS
+// it converged resets the streak early. That daemon self-heals the same way
+// ownership does (armOwnershipWatch drains it once the mismatch is detected);
+// worst case is one redundant reset in an already-rare race window, not a
+// wrong steady-state outcome.
+export function resetSpawnBackoff(): void {
+  try {
+    fs.unlinkSync(spawnBackoffPath());
+  } catch (e) {
+    if ((e as NodeJS.ErrnoException).code !== "ENOENT") {
+      process.stderr.write(
+        `cc-candybar: could not reset spawn.backoff: ${(e as Error).message}\n`,
+      );
+    }
+  }
+}
+
 // [LAW:single-enforcer] The sole authority on daemon-spawn RATE. Returns true —
-// and RECORDS the attempt (updating spawn.cooldown's mtime to now) — when a
-// spawn is permitted; false when an attempt was recorded within
-// SPAWN_COOLDOWN_MS. Recording-on-grant (BEFORE the caller spawns) is
-// load-bearing: a spawn that then throws or returns false still counts against
-// the rate, so a broken binary is not retried in a tight loop. A future-mtime
-// garbage record warns loudly and falls toward ALLOWING the spawn
-// [LAW:no-silent-failure].
+// and RECORDS the attempt (updating spawn.cooldown's mtime to now, advancing
+// spawn.backoff's streak) — when a spawn is permitted; false when an attempt
+// was recorded within the EFFECTIVE cooldown window (SPAWN_COOLDOWN_MS,
+// widened by effectiveCooldownMs(streak) once consecutive attempts have
+// failed to converge — see brandon-daemon-lifecycle-gad.3). Recording-on-grant
+// (BEFORE the caller spawns) is load-bearing: a spawn that then throws or
+// returns false still counts against the rate, so a broken binary is not
+// retried in a tight loop. A future-mtime garbage record warns loudly and
+// falls toward ALLOWING the spawn [LAW:no-silent-failure].
 function claimSpawnCooldown(): boolean {
-  const path = spawnCooldownPath();
-  const decision = cooldownDecision(cooldownAgeMs(path));
+  const cooldownPath = spawnCooldownPath();
+  const backoffPath = spawnBackoffPath();
+  const streak = readBackoffStreak(backoffPath);
+  const decision = cooldownDecision(
+    cooldownAgeMs(cooldownPath),
+    effectiveCooldownMs(streak),
+  );
   if (decision.kind === "deny") return false;
   if (decision.kind === "allow-future-garbage") {
     process.stderr.write(
       `cc-candybar: spawn.cooldown mtime is ${decision.futureMs}ms in the future — ignoring and spawning\n`,
     );
   }
-  recordSpawnAttempt(path);
+  recordSpawnAttempt(cooldownPath);
+  // [LAW:dataflow-not-control-flow] Every granted spawn advances the streak
+  // by exactly one, unconditionally — the cap lives in the read side
+  // (effectiveCooldownMs) and here (Math.min), never as a skip.
+  writeBackoffStreak(
+    backoffPath,
+    Math.min(streak + 1, SPAWN_BACKOFF_MAX_STREAK),
+  );
   return true;
 }
 

package/src/daemon/cache/render.ts

@@ -11,6 +11,7 @@ import {
   ConfigError,
 } from "../../config/dsl-loader.js";
 import type { ValidatedConfig } from "../../config/dsl-types.js";
+import { DEFAULT_DSL_CONFIG } from "../../config/default-dsl-config.js";
 import { registerDslConfig, type CompiledConfig } from "../../dsl/render.js";
 import {
   deriveActionValidators,
@@ -272,7 +273,10 @@ export class RenderCache {
     // cross-ref diagnostics on the daemon path carry real line numbers and the
     // authored-surface (root vs layout) discriminator works — the file is read
     // once inside loadConfig, not re-read here.
-    const { config: merged, source } = loadConfig(resolvedPath);
+    const { config: merged, source } = loadConfig(
+      resolvedPath,
+      DEFAULT_DSL_CONFIG,
+    );
     const config = validateConfig(merged, resolvedPath ?? "<default>", source);
 
     const store = new VariableStore();

package/src/daemon/paths.ts

@@ -185,6 +185,17 @@ export function spawnCooldownPath(): string {
   return path.join(stateDir(), SPAWN_COOLDOWN_FILE);
 }
 
+// [LAW:one-source-of-truth] Sibling of spawn.cooldown: that file's mtime
+// answers "when was a spawn last attempted"; this file's content answers
+// "how many attempts in a row have failed to converge on a live daemon" —
+// the consecutive-non-convergence streak that widens the cooldown window
+// (see effectiveCooldownMs in acquire.ts). Same filename mirrored TS↔Rust,
+// diffed by scripts/check-protocol.mjs.
+const SPAWN_BACKOFF_FILE = "spawn.backoff";
+export function spawnBackoffPath(): string {
+  return path.join(stateDir(), SPAWN_BACKOFF_FILE);
+}
+
 export function logPath(): string {
   return path.join(stateDir(), "daemon.log");
 }

package/src/daemon/server.ts

@@ -48,6 +48,7 @@ import { WatcherRegistry } from "./cache/watchers";
 import { RuntimeStats } from "./stats";
 import { makeLimits, realLimitsDeps, type LimitsHandle } from "./limits";
 import { armParentWatchdog, anchorFromEnv, pidAlive } from "./parent-watchdog";
+import { resetSpawnBackoff } from "./acquire";
 import { SessionState } from "./session-state";
 import { FileSessionStorage } from "./session-state-file";
 import { VERBS, BadVerbArgs, SESSION_CONFIG_OVERRIDE_KEY } from "./verbs";
@@ -377,6 +378,11 @@ function onListening(sockPath: string): void {
     "info",
     `daemon up: pid=${process.pid} v=${PROTOCOL_VERSION} sock=${sockPath}`,
   );
+  // [LAW:single-enforcer] This bind is the one process-wide fact that answers
+  // "did an outage just end" — see resetSpawnBackoff's doc comment in
+  // acquire.ts. Any consecutive-spawn backoff accumulated getting here no
+  // longer applies once a daemon is actually serving.
+  resetSpawnBackoff();
   armBinaryWatch();
   armLimits();
   armOwnershipWatch(sockPath, boundRead.identity);

package/src/demo/dsl.ts

@@ -25,6 +25,7 @@ import {
   mergeWithDefault,
   validateConfig,
 } from "../config/dsl-loader.js";
+import { DEFAULT_DSL_CONFIG } from "../config/default-dsl-config.js";
 import { VariableStore } from "../var-system/store.js";
 import { SourceRegistry } from "../var-system/sources.js";
 import { SessionState } from "../daemon/session-state.js";
@@ -60,7 +61,7 @@ const source = readFileSync(configPath, "utf-8");
 // only `ValidatedConfig`, so the chain is type-enforced.
 const ALLOWED = new Set(listResolvablePaletteNames());
 const raw = parseDslConfig(configPath, source, ALLOWED);
-const merged = mergeWithDefault(raw);
+const merged = mergeWithDefault(raw, DEFAULT_DSL_CONFIG);
 const config = validateConfig(merged, configPath, source, ALLOWED);
 
 // One Claude Code status-line hook event, faked. The `input` vars in the

package/src/index.ts

@@ -53,12 +53,14 @@ Configuration:
   to point at a specific file. See the default config for all available options:
     node dist/index.mjs debug --project-dir . --cwd .
 
-Subcommands (macOS):
-  install                  One-shot setup: creates the URL handler app, registers
-                           the cc-candybar:// scheme, and writes the statusLine
-                           command into ~/.claude/settings.json.
-  install-url-handler      Just create + register the URL handler app
-                           (~/Applications/CCCandybarURLHandler.app).
+Subcommands:
+  install                  One-shot setup: stages the runtime (native render
+                           binary + dist bundle) at a stable path, creates the
+                           URL handler app + cc-candybar:// scheme (macOS), and
+                           writes the staged entry as the statusLine command in
+                           ~/.claude/settings.json. Re-run to update.
+  install-url-handler      Just stage the runtime and create + register the URL
+                           handler app (macOS only).
   url-handle URL           Internal — invoked by the URL handler app on
                            cmd-click. Parses cc-candybar://<verb>/<value> and
                            dispatches (currently: copy to clipboard).