@promptctl/cc-candybar 1.19.0 → 1.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@promptctl/cc-candybar",
-  "version": "1.19.0",
+  "version": "1.21.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",
@@ -95,10 +95,10 @@
     "mobx": "^6.15.0"
   },
   "optionalDependencies": {
-    "@promptctl/cc-candybar-darwin-arm64": "1.19.0",
-    "@promptctl/cc-candybar-darwin-x64": "1.19.0",
-    "@promptctl/cc-candybar-linux-x64": "1.19.0",
-    "@promptctl/cc-candybar-linux-arm64": "1.19.0"
+    "@promptctl/cc-candybar-darwin-arm64": "1.21.0",
+    "@promptctl/cc-candybar-darwin-x64": "1.21.0",
+    "@promptctl/cc-candybar-linux-x64": "1.21.0",
+    "@promptctl/cc-candybar-linux-arm64": "1.21.0"
   },
   "pnpm": {
     "supportedArchitectures": {

package/schema/cc-candybar.schema.json

@@ -26,6 +26,9 @@
         "palette": {
           "type": "string"
         },
+        "look": {
+          "type": "string"
+        },
         "style": {
           "enum": [
             "powerline",
@@ -1140,7 +1143,8 @@
               "from": {
                 "enum": [
                   "themes",
-                  "styles"
+                  "styles",
+                  "looks"
                 ]
               }
             },
@@ -1239,6 +1243,28 @@
         ]
       }
     },
+    "looks": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "hueShift": {
+            "type": "number"
+          },
+          "chromaScale": {
+            "type": "number",
+            "minimum": 0
+          },
+          "lightnessScale": {
+            "type": "number"
+          },
+          "lightnessShift": {
+            "type": "number"
+          }
+        },
+        "additionalProperties": false
+      }
+    },
     "helpers": {
       "type": "object",
       "additionalProperties": {

package/src/check.ts

@@ -0,0 +1,398 @@
+// [LAW:verifiable-goals] `cc-candybar check [path]` — the authoring agent's eyes.
+// Config diagnostics otherwise surface VISUALLY (composeWithDiagnostics renders
+// error/warning icons into the bar), a channel a blind config author never sees.
+// This command runs the production pipeline and projects its verdict onto a
+// text + exit-code contract a script can close its own loop on:
+//   0 — config loads and renders (warnings, if any, on stderr)
+//   1 — config is invalid (parse / validate / register / render failure)
+//   2 — usage error or a named file could not be read
+//
+// [LAW:single-enforcer] No parallel validation path: the verdict is reached
+// through the exact functions the daemon runs (RenderCache.reloadInto →
+// buildState, then the per-request render in server.ts) — resolveDslConfigPath →
+// detectConfigCollisions → loadConfig → validateConfig → registerDslConfig →
+// deriveActionValidators → renderDsl. "check passes" and "the daemon renders"
+// cannot diverge, because they are one code path.
+
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import {
+  loadConfig,
+  validateConfig,
+  resolveDslConfigPath,
+  detectConfigCollisions,
+  ConfigError,
+} from "./config/dsl-loader.js";
+import { expandHome } from "./config/loader/discovery.js";
+import { VariableStore } from "./var-system/store.js";
+import { SourceRegistry } from "./var-system/sources.js";
+import { SessionState } from "./daemon/session-state.js";
+import { registerDslConfig, renderDsl } from "./dsl/render.js";
+import { deriveActionValidators } from "./daemon/verbs/state-validators.js";
+import {
+  effectiveThemeName,
+  effectiveLookName,
+  lookKeyByName,
+  effectiveStripStyle,
+} from "./themes/policy.js";
+import { resolverForThemeName } from "./themes/palette-resolvers.js";
+import {
+  DEFAULT_CHARSET,
+  DEFAULT_COLOR_COMPATIBILITY,
+  DEFAULT_PADDING,
+  DEFAULT_WRAP,
+} from "./render/strip.js";
+
+// [LAW:no-ambient-temporal-coupling] A fixed width keeps the verdict a function
+// of the config alone, not of whichever terminal invoked the check. Templates
+// evaluate in full before any width-driven wrap/pagination, so width shapes
+// layout, never diagnostics.
+const CHECK_WIDTH = 200;
+
+// One faked Claude Code hook event, shaped like the daemon's augmented payload
+// (see src/daemon/render-payload.ts) — the `input` vars read out of it by their
+// dotted `path`. [LAW:verifiable-goals] It is deliberately RICH (dirty git with
+// every worktree count, an upstream, a stash, a recent commit; home set; live
+// session/today/context/metrics/rate-limit data) so gated segments actually
+// RENDER their content instead of gating off. A minimal payload would let a
+// field-name typo in the git/directory/metrics/budget branches slip through —
+// those branches only run when their data is present.
+//
+// `effectiveTheme` is threaded in exactly as the daemon threads it (server.ts
+// resolves effectiveThemeName once and feeds BOTH the payload's
+// `theme.effective` field and the basePalette below) [LAW:one-source-of-truth].
+//
+// test/example-configs.test.ts asserts rendered content against these literal
+// values (780s → "◷ 13m", cost $0.39, version 1.15.0, …); changing one here
+// fails that suite loudly rather than drifting silently.
+export function checkPayload(
+  effectiveTheme: string,
+  effectiveLook: string,
+): Record<string, unknown> {
+  const home = "/home/tester";
+  const nowSec = Math.floor(Date.now() / 1000);
+  return {
+    hook_event_name: "Status",
+    session_id: "test0a1b-2c3d-4e5f-6a7b-8c9d0e1f2a3b",
+    version: "1.15.0",
+    home,
+    cwd: `${home}/code/cc-candybar/src`,
+    transcript_path: `${home}/.claude/projects/x/test.jsonl`,
+    model: { id: "claude-opus-4-8", display_name: "Opus 4.8" },
+    workspace: {
+      current_dir: `${home}/code/cc-candybar/src`,
+      project_dir: `${home}/code/cc-candybar`,
+    },
+    git: {
+      repoName: "cc-candybar",
+      branch: "main",
+      sha: "abc1234",
+      ahead: 2,
+      behind: 1,
+      staged: 3,
+      unstaged: 2,
+      untracked: 1,
+      conflicts: 0,
+      upstream: "origin/main",
+      stash: 1,
+      status: "dirty",
+      operation: "rebase",
+      timeSinceCommit: 780,
+    },
+    session: { cost: 0.39, tokens: 241400 },
+    today: { cost: 12.5, tokens: 3_400_000 },
+    context: { totalTokens: 48487, contextLeft: 24 },
+    metrics: {
+      lastResponseTime: 8.2,
+      responseTime: 4.2,
+      sessionDuration: 930,
+      messageCount: 8,
+      linesAdded: 512,
+      linesRemoved: 88,
+    },
+    block: { nativeUtilization: 63, resetsAt: nowSec + 2 * 3600 },
+    weekly: { percentage: 21, resetsAt: nowSec + 5 * 86400 },
+    cache: { expiresAt: nowSec + 15 * 60 },
+    tmux: { session: "work" },
+    theme: { effective: effectiveTheme },
+    look: { effective: effectiveLook },
+  };
+}
+
+// [LAW:dataflow-not-control-flow] The check result is DATA — a pure function of
+// the target file's contents — discriminated into the three outcomes the exit-
+// code contract projects. `checkConfig` carries the decision; `runCheck` only
+// maps it to (streams, exit), so the contract is testable without spawning a
+// process or stubbing process.exit.
+//
+// `configPath` null means the bundled default was checked (no config file
+// found — the daemon renders the same default in that state).
+export type CheckOutcome =
+  | {
+      readonly kind: "clean";
+      readonly configPath: string | null;
+      readonly warnings: readonly string[];
+      readonly rendered: string;
+    }
+  | {
+      readonly kind: "fatal";
+      readonly configPath: string | null;
+      readonly message: string;
+      readonly warnings: readonly string[];
+    }
+  | {
+      readonly kind: "unreadable";
+      readonly path: string;
+      readonly message: string;
+    };
+
+// Run the daemon's load-and-render pipeline against one config target.
+//
+// With no target, the path resolves exactly as the daemon resolves it
+// (resolveDslConfigPath: $CC_CANDYBAR_CONFIG → project/cwd → XDG), so the file
+// this checks IS the file the daemon would load from this directory.
+//
+// [LAW:no-silent-failure] With an explicit target, the named file must exist
+// and be readable — a missing file is `unreadable`, never a fall-through to the
+// bundled default. (The daemon's --config-to-missing-file behavior — render the
+// default, watch for the file to appear — is liveness for a long-running
+// renderer; a verdict command must not report "clean" about a file it never
+// read.)
+export function checkConfig(
+  target: string | undefined,
+  cwd: string = process.cwd(),
+): CheckOutcome {
+  // [LAW:one-source-of-truth] No pre-read: the ONE content read of the config
+  // file is the readFileSync inside loadConfig. Readability is established by
+  // the same read that parses (no double I/O); the catch below classifies its
+  // errno failure as `unreadable`. The explicit-target statSync is a metadata
+  // probe at the argv trust boundary, not a second read: a directory target
+  // (`check .`) fails read() with a path-less EISDIR the catch could not
+  // attribute, so the not-a-file usage error is decided here.
+  const configPath =
+    target !== undefined
+      ? path.resolve(expandHome(target))
+      : resolveDslConfigPath(cwd, cwd);
+  if (target !== undefined && configPath !== null) {
+    // throwIfNoEntry suppresses only ENOENT (left for the content read to
+    // classify); EACCES/EPERM on the probe itself is equally "could not read
+    // the named file" — same outcome, not an uncaught stack.
+    let st: fs.Stats | undefined;
+    try {
+      st = fs.statSync(configPath, { throwIfNoEntry: false });
+    } catch (e) {
+      return {
+        kind: "unreadable",
+        path: configPath,
+        message: e instanceof Error ? e.message : String(e),
+      };
+    }
+    if (st !== undefined && !st.isFile()) {
+      return {
+        kind: "unreadable",
+        path: configPath,
+        message: "not a file",
+      };
+    }
+  }
+
+  // [LAW:dataflow-not-control-flow] Collision detection runs independent of
+  // load success — mirror of RenderCache.reloadInto: even if the .json5 fails
+  // to parse, the author still wants to know a shadowed .json sibling exists.
+  const warnings: string[] = [];
+  const collision = detectConfigCollisions(cwd, cwd);
+  if (collision !== null) warnings.push(collision);
+
+  try {
+    const rendered = loadRegisterRender(configPath, cwd, warnings);
+    return { kind: "clean", configPath, warnings, rendered };
+  } catch (e) {
+    // A filesystem error on the config file itself (ENOENT/EACCES from
+    // loadConfig's read — errno errors carry the failing `.path`, which is the
+    // discriminator against deeper fs failures) is the `unreadable` outcome:
+    // the named file could not be read at all, distinct from a file that read
+    // but is invalid. [LAW:no-silent-failure] — never a fall-through to the
+    // bundled default. Duck-typed, not `instanceof Error`: fs errors can cross
+    // a realm boundary (jest/graceful-fs), where instanceof lies.
+    const errno = e as Partial<NodeJS.ErrnoException> | null;
+    if (
+      configPath !== null &&
+      typeof errno === "object" &&
+      errno !== null &&
+      typeof errno.code === "string" &&
+      errno.path === configPath &&
+      typeof errno.message === "string"
+    ) {
+      return { kind: "unreadable", path: configPath, message: errno.message };
+    }
+    // Same classification RenderCache.reloadInto applies: ConfigError and
+    // register/render throws (template parse, MissingFieldError, action arity)
+    // are all author-facing diagnostics — the daemon would surface each via
+    // composeWithDiagnostics, so check surfaces each as fatal text.
+    const message =
+      e instanceof ConfigError
+        ? e.message
+        : e instanceof Error
+          ? e.message
+          : String(e);
+    return { kind: "fatal", configPath, message, warnings };
+  }
+}
+
+// The buildState + per-request-render mirror: every call below is the function
+// the daemon calls, in the daemon's order [LAW:single-enforcer]. Returns the
+// rendered line; appends the register pass's advisory `loadWarnings` (partial
+// declaration failures) to `warnings` — the same channel RenderCache merges
+// them into.
+function loadRegisterRender(
+  configPath: string | null,
+  cwd: string,
+  warnings: string[],
+): string {
+  const { config: merged, source } = loadConfig(configPath);
+  const config = validateConfig(merged, configPath ?? "<default>", source);
+
+  const store = new VariableStore();
+  const registry = new SourceRegistry(
+    store,
+    config.globals.default_empty_value ?? "",
+    undefined,
+    new SessionState(),
+  );
+  try {
+    const compiled = registerDslConfig(config, registry, { cwd });
+    // Registered before the validator pass so a derive throw (a key-kind
+    // clash) still carries the partial-load warnings into the fatal outcome.
+    warnings.push(...compiled.loadWarnings);
+    // Derivation only (the throw-on-clash coherence pass over the action
+    // table); the daemon additionally registers the results in its global
+    // validator registry, which a one-shot check has no wire to serve.
+    deriveActionValidators(config);
+
+    // Fresh session (no clicked theme/style), so the session half of each
+    // resolution is null — the config default over the floor, exactly what the
+    // daemon renders for a session that has never clicked.
+    const effectiveTheme = effectiveThemeName(null, config.globals.palette);
+    // Same fresh-session shape one dimension over: no clicked look, so the
+    // config default over the "none" floor — exactly what the daemon renders
+    // for a session that has never clicked.
+    const effectiveLook = effectiveLookName(
+      null,
+      config.globals.look,
+      config.looks,
+    );
+    // [LAW:no-silent-failure] A segment whose template THROWS while evaluating
+    // (an `{{ action }}` display-arity mismatch, a MissingFieldError from a
+    // partially-declared variable) renders as a visible ⚠ error cell — partial
+    // rendering, the daemon's channel for a human looking at the bar. The blind
+    // authoring agent is not looking at the bar; check collects the same errors
+    // through the render's observer seam and fails the verdict, so exit 0 never
+    // blesses a bar that renders ⚠.
+    const segmentErrors: string[] = [];
+    const rendered = renderDsl(
+      config,
+      compiled,
+      store,
+      registry,
+      checkPayload(effectiveTheme, effectiveLook),
+      resolverForThemeName(effectiveTheme),
+      {
+        style: effectiveStripStyle(null, config.globals.style),
+        width: CHECK_WIDTH,
+        colorCompatibility:
+          config.globals.colorCompatibility ?? DEFAULT_COLOR_COMPATIBILITY,
+        wrap: config.globals.autoWrap ?? DEFAULT_WRAP,
+        padding: config.globals.padding ?? DEFAULT_PADDING,
+        charset: config.globals.charset ?? DEFAULT_CHARSET,
+      },
+      {
+        onSegmentError: (segName, message) =>
+          segmentErrors.push(`segment "${segName}": ${message}`),
+      },
+      lookKeyByName(config.looks, effectiveLook),
+    );
+    if (segmentErrors.length > 0) {
+      throw new Error(
+        `config renders with ${segmentErrors.length} segment error${
+          segmentErrors.length === 1 ? "" : "s"
+        } (the daemon would render ⚠ error cells):\n` +
+          segmentErrors.map((m) => `  ${m}`).join("\n"),
+      );
+    }
+    return rendered;
+  } finally {
+    // [LAW:single-enforcer] The registry owns every async handle the config
+    // declared (timers, fs watchers, git subscriptions); a one-shot check must
+    // not leak them past the verdict.
+    registry.dispose();
+  }
+}
+
+const EXIT_CLEAN = 0;
+const EXIT_FATAL = 1;
+const EXIT_USAGE = 2;
+
+// [LAW:dataflow-not-control-flow] The outcome → (streams, exit-code) mapping is
+// DATA: a total fold over CheckOutcome returning one descriptor; runCheck runs
+// the two unconditional writes + exit against it. Verdict on stdout, every
+// diagnostic (warnings included) on stderr — so `check` in a pipeline yields a
+// parseable verdict while a human still sees the advisories.
+export interface CheckPlan {
+  readonly stdout: string;
+  readonly stderr: string;
+  readonly code: number;
+}
+
+function warningLines(warnings: readonly string[]): string {
+  return warnings.map((w) => `warning: ${w}\n`).join("");
+}
+
+export function checkPlan(o: CheckOutcome): CheckPlan {
+  switch (o.kind) {
+    case "clean": {
+      const where = o.configPath ?? "bundled default (no config file found)";
+      const count =
+        o.warnings.length > 0
+          ? ` (${o.warnings.length} warning${o.warnings.length === 1 ? "" : "s"})`
+          : "";
+      return {
+        stdout: `✓ ${where}: config OK${count}\n`,
+        stderr: warningLines(o.warnings),
+        code: EXIT_CLEAN,
+      };
+    }
+    case "fatal":
+      return {
+        stdout: "",
+        stderr:
+          warningLines(o.warnings) +
+          `✗ ${o.configPath ?? "<default>"}\n${o.message}\n`,
+        code: EXIT_FATAL,
+      };
+    case "unreadable":
+      return {
+        stdout: "",
+        stderr: `check: cannot read ${o.path}: ${o.message}\n`,
+        code: EXIT_USAGE,
+      };
+  }
+}
+
+// `cc-candybar check [path]` — the argv binding. Extra arguments and an empty
+// path argument are usage errors (loud, not silently ignored — the likeliest
+// cause is an unquoted or mis-expanded shell variable). An empty string is not
+// "no argument": `checkConfig(undefined)` means "resolve like the daemon",
+// while `""` is a malformed target that would otherwise EISDIR on the cwd.
+export function runCheck(args: readonly string[]): never {
+  if (args.length > 1 || args[0] === "") {
+    process.stderr.write(
+      "check: expected at most one non-empty path\nUsage: cc-candybar check [config-file]\n",
+    );
+    process.exit(EXIT_USAGE);
+  }
+  const plan = checkPlan(checkConfig(args[0]));
+  process.stdout.write(plan.stdout);
+  process.stderr.write(plan.stderr);
+  process.exit(plan.code);
+}

package/src/config/action.ts

@@ -25,11 +25,18 @@
 // discriminator the loader and the validator-derivation match on.
 
 // [LAW:one-source-of-truth] The domain lists a picker draws options from. Same
-// canonical sources the `themes()`/`styles()` bindings and the set-state
-// validators consult — the rendered options and the derived gate cannot diverge
-// because there is no second enumeration.
-export type OptionSource = "themes" | "styles";
-export const OPTION_SOURCES: readonly OptionSource[] = ["themes", "styles"];
+// canonical sources the `themes()`/`styles()`/`looks()` bindings and the
+// set-state validators consult — the rendered options and the derived gate
+// cannot diverge because there is no second enumeration. themes/styles are
+// static registry lists; "looks" is the one PER-CONFIG domain (the merged
+// `looks` block's names), so its resolution sites take the config's look names
+// as data rather than consulting a module constant.
+export type OptionSource = "themes" | "styles" | "looks";
+export const OPTION_SOURCES: readonly OptionSource[] = [
+  "themes",
+  "styles",
+  "looks",
+];
 
 // [LAW:types-are-the-program] The top-level discriminator of an ActionDecl — the
 // click effect is keyed by which of these is present. The loader proves

package/src/config/cli.ts

@@ -1,128 +1,17 @@
-// [LAW:single-enforcer] Config-tooling CLI entry points. `lint` and `schema`
-// share one module because they share one change-reason: the config grammar.
-// Neither carries validation or schema LOGIC — `lint` is a second entry point
-// into the loader (the single config-validation enforcer the daemon also uses),
-// and `schema` serves the build-generated artifact (derived from the config
-// types). Both are bindings, not reimplementations [LAW:one-source-of-truth].
+// [LAW:single-enforcer] Config-tooling CLI entry point for `schema`. It carries
+// no schema LOGIC — it serves the build-generated artifact (derived from the
+// loader's declarations), so it is a binding, not a reimplementation
+// [LAW:one-source-of-truth]. Config *validation* lives in `cc-candybar check`
+// (src/check.ts) — the full-pipeline verdict command; the old `lint` is its
+// alias.
 
 import fs from "node:fs";
 import path from "node:path";
 import process from "node:process";
-import { loadConfig, validateConfig } from "./dsl-loader.js";
-import { ConfigError } from "./loader/diagnostics.js";
 
-// Exit codes are a contract (the CLI guideline: not just 0/1), so scripts and
-// editors can distinguish "your config is wrong" from "I couldn't run":
-//   0 — config is valid
-//   1 — config is invalid (ConfigError: structural, cross-ref, or cycle)
-//   2 — usage error or the file could not be read
 const EXIT_VALID = 0;
-const EXIT_INVALID = 1;
 const EXIT_USAGE = 2;
 
-// [LAW:dataflow-not-control-flow] The lint result is DATA — a pure function of
-// the target file's contents — discriminated into the three outcomes the exit-
-// code contract projects. `lintConfig` carries the decision; `runLint` only maps
-// it to (stream, exit). The decision is unit-testable without spawning a process
-// or stubbing process.exit, which is what makes the exit-code goal verifiable.
-export type LintOutcome =
-  | { readonly kind: "valid"; readonly path: string }
-  | { readonly kind: "invalid"; readonly message: string }
-  | {
-      readonly kind: "unreadable";
-      readonly path: string;
-      readonly message: string;
-    };
-
-// Run the real loader (parse → merge-with-default → cross-ref + cycle validation)
-// against an arbitrary file. No daemon: the loader imports only fs, JSON5, and
-// pure validators, so the same errors the daemon would surface at render time are
-// surfaced here ahead of time.
-//
-// [LAW:single-enforcer] loadConfig + validateConfig is the identical pipeline
-// RenderCache.reloadInto runs in the daemon — the validation authority is one
-// function, so lint cannot drift from production. The source we read is passed to
-// validateConfig only to sharpen line numbers (semantic issues map to lines).
-export function lintConfig(target: string): LintOutcome {
-  const resolved = path.resolve(target);
-
-  let source: string;
-  try {
-    source = fs.readFileSync(resolved, "utf-8");
-  } catch (e) {
-    return {
-      kind: "unreadable",
-      path: target,
-      message: e instanceof Error ? e.message : String(e),
-    };
-  }
-
-  try {
-    const { config } = loadConfig(resolved);
-    validateConfig(config, resolved, source);
-  } catch (e) {
-    if (e instanceof ConfigError)
-      return { kind: "invalid", message: e.message };
-    throw e;
-  }
-
-  return { kind: "valid", path: target };
-}
-
-// `cc-candybar lint <path>` — the argv binding. Missing-arg is a usage concern
-// (not a lint outcome), handled here; everything else is the projection of
-// lintConfig's outcome onto the stream + exit-code contract.
-export function runLint(args: readonly string[]): void {
-  const target = args[0];
-  if (target === undefined || target === "") {
-    process.stderr.write(
-      "lint: missing <path>\nUsage: cc-candybar lint <config-file>\n",
-    );
-    process.exit(EXIT_USAGE);
-  }
-  applyLintOutcome(lintConfig(target));
-}
-
-// [LAW:dataflow-not-control-flow] The outcome → (stream, text, exit-code) mapping
-// is DATA. `lintPlan` is a total fold returning that descriptor (a non-returning
-// arm fails the typecheck, so the projection stays exhaustive over LintOutcome);
-// `applyLintOutcome` runs the single write + exit against it. The side effects
-// are unconditional; the data decides their content.
-interface LintPlan {
-  readonly stream: NodeJS.WriteStream;
-  readonly text: string;
-  readonly code: number;
-}
-
-function lintPlan(o: LintOutcome): LintPlan {
-  switch (o.kind) {
-    case "valid":
-      return {
-        stream: process.stdout,
-        text: `✓ ${o.path}: config valid\n`,
-        code: EXIT_VALID,
-      };
-    case "invalid":
-      return {
-        stream: process.stderr,
-        text: o.message + "\n",
-        code: EXIT_INVALID,
-      };
-    case "unreadable":
-      return {
-        stream: process.stderr,
-        text: `lint: cannot read ${o.path}: ${o.message}\n`,
-        code: EXIT_USAGE,
-      };
-  }
-}
-
-function applyLintOutcome(o: LintOutcome): never {
-  const plan = lintPlan(o);
-  plan.stream.write(plan.text);
-  process.exit(plan.code);
-}
-
 // Read the build-generated JSON Schema for the config file shape (RawDslConfig),
 // or null when the artifact is absent. Pure read — `runSchema` owns the side
 // effects, so the locate-and-read path is testable.
@@ -137,7 +26,19 @@ export function loadSchemaText(): string | null {
 // time (scripts/gen-schema.ts → emitConfigSchema); served verbatim here (the
 // emitter runs at build, not ship time).
 export function runSchema(): void {
-  const text = loadSchemaText();
+  // [LAW:no-silent-failure] A schema that exists but cannot be read (EACCES, a
+  // deletion racing the existsSync in locateSchema) is a distinct failure from
+  // schema-not-found — report it as what it is, not a misleading top-level
+  // render error.
+  let text: string | null;
+  try {
+    text = loadSchemaText();
+  } catch (e) {
+    process.stderr.write(
+      `schema: cannot read bundled schema: ${e instanceof Error ? e.message : String(e)}\n`,
+    );
+    process.exit(EXIT_USAGE);
+  }
   if (text === null) {
     process.stderr.write(
       "schema: bundled schema not found (expected schema/cc-candybar.schema.json). " +