@promptctl/cc-candybar 1.0.0

package/src/render/action.ts

@@ -0,0 +1,458 @@
+// [LAW:locality-or-seam] The runtime half of the actions seam. A `{{ action
+// "name" display [boundValue] }}` call binds one clickable region (an OSC-8 span)
+// to a statically-declared, named action. This module compiles the action table
+// (pre-parsing copy/open templates once) and realizes a named action against the
+// live state into ONE RichText whose span carries the click URL.
+//
+// [LAW:one-source-of-truth] The action NAME is the seam: the template supplies
+// the REPRESENTATION (the display text), the action declaration supplies the
+// BEHAVIOR (what value is written / copied / opened). The same declaration that
+// realizes this click derives the wire gate (deriveActionValidators), so the
+// rendered click and the gate cannot diverge.
+//
+// [LAW:dataflow-not-control-flow] `{{ action … }}` is ONE template expression, so
+// it emits ONE value — a RichText carrying one OSC-8 span. The realization is a
+// single total fold over the compiled-action union: each arm projects (effect,
+// active) as DATA, never a branch that skips work.
+//
+// [LAW:one-way-deps] This is the action feature's runtime. It lives in render/
+// (which depends on template-engine/), reads template-engine/scope, and is
+// injected into the engine by the caller (registerDslConfig hands the action
+// FuncMap in as data). The generic engine never imports this module.
+
+import { RichText, Style } from "@promptctl/rich-js";
+import type { FuncMap, Template } from "@promptctl/go-template-js";
+import type { VariableStore } from "../var-system/store.js";
+import { toString as varToString } from "../var-system/types.js";
+import { buildScope } from "../template-engine/scope.js";
+import type { ActionDecl, OptionSource } from "../config/action.js";
+import { listResolvablePaletteNames, STYLE_ORDER } from "../themes/policy.js";
+import {
+  effectsUrl,
+  VERB_COPY,
+  VERB_OPEN_VSCODE,
+  VERB_SET_STATE,
+  VERB_STEP_STATE,
+  type Effect,
+} from "../click/wire.js";
+
+// ─── Compiled shapes ───────────────────────────────────────────────────────────
+
+// [LAW:types-are-the-program] A compiled action mirrors ActionDecl, discriminated
+// by `kind`. Each `set` arm carries the SessionState `key` it writes plus the
+// `stateVar` that reads it back (resolved from the key, so the displayed/active
+// value and the written value are one source — the same resolution a stepper
+// widget uses). A literal carries its fixed `value`; an option binds the value
+// from the template at render; a bounded carries its [min,max]/by navigation.
+// copy/open carry a pre-parsed template evaluated against the live scope.
+export type CompiledActionDecl =
+  | {
+      readonly kind: "set-literal";
+      readonly key: string;
+      readonly value: string;
+      readonly stateVar: string;
+    }
+  | {
+      readonly kind: "set-option";
+      readonly key: string;
+      readonly stateVar: string;
+      // The resolved option domain. Stored at compile so a picker can iterate it
+      // without re-resolving the source list, and so the set-option IS
+      // self-describing (it knows its own domain), not just a key.
+      readonly options: readonly string[];
+    }
+  | {
+      // [LAW:types-are-the-program] A stepper affordance. It carries ONLY the
+      // render-invariant click intent: the state `key` and the signed delta `by`.
+      // It deliberately holds NO stateVar/min/max and reads NO current value at
+      // render — the absolute target is computed at APPLY time from live state
+      // (the daemon's step-state handler), so the emitted link is byte-identical
+      // across renders and N rapid clicks each re-read-and-step. [LAW:one-source-
+      // of-truth] the bounds live once in the range validator the handler reads.
+      readonly kind: "set-bounded";
+      readonly key: string;
+      readonly by: number;
+    }
+  | {
+      // [LAW:types-are-the-program] An int cursor: it writes whatever integer the
+      // render binds (the picker's page nav supplies -1/p±1; a bare `{{ action }}`
+      // supplies its display/boundValue). The gate is an unbounded int — the
+      // renderer owns clamping to valid pages, exactly as set-bounded owns wrap.
+      readonly kind: "set-int";
+      readonly key: string;
+      readonly stateVar: string;
+    }
+  | {
+      // [LAW:types-are-the-program] An enumerated-domain stepper: the click
+      // writes the SUCCESSOR of the current value in `members` (wrapping; a
+      // current value outside the domain counts as the first member). Unlike
+      // set-bounded — which emits a RELATIVE nudge so rapid clicks accumulate —
+      // a cycle emits the ABSOLUTE successor computed at render: the rendered
+      // display names the current state, so the click's meaning is "go to the
+      // successor of what I showed you". A stale link then lands on the state
+      // the user saw promised, not an extra flip past it — for toggles the
+      // absolute write IS the correct intent.
+      readonly kind: "set-cycle";
+      readonly key: string;
+      readonly stateVar: string;
+      readonly members: readonly string[];
+    }
+  | { readonly kind: "copy"; readonly text: Template<RichText> }
+  | { readonly kind: "open"; readonly target: Template<RichText> };
+
+export type CompiledActions = ReadonlyMap<string, CompiledActionDecl>;
+
+// [LAW:one-source-of-truth] An option source resolves to the SAME canonical list
+// the `themes()`/`styles()` bindings and the derived gate consult — rendered
+// options and the gate cannot diverge. The render-side resolver (the daemon's
+// validator-derivation has its own that must agree, both reading themes/policy).
+export function optionDomain(src: OptionSource): readonly string[] {
+  return src === "themes" ? listResolvablePaletteNames() : STYLE_ORDER;
+}
+
+// [LAW:locality-or-seam] The runtime holder the `action` template function closes
+// over. Populated after the engine is constructed (the func references the
+// engine, the compiled actions reference the engine — the holder breaks the
+// cycle). `store` is the live VariableStore the renderer reads, so the action
+// reads session.id and the current value from the same source the rest of the
+// render does.
+export interface ActionRuntime {
+  store: VariableStore | null;
+  compiled: CompiledActions;
+}
+
+// ─── Compilation ───────────────────────────────────────────────────────────────
+
+// Pre-parse the copy/open templates for every action once, at config
+// registration; set actions stay literal. [LAW:one-source-of-truth] parse-once,
+// evaluate-many — renderAction only evaluates. `stateKeyToVar` maps a
+// SessionState key → the variable that reads it (same map widgets use), so a
+// set action reads its current/active value from the SAME value the templates
+// read, regardless of whether the config named the variable after the key.
+// [LAW:single-enforcer] `parse` is the config's ONE helper-aware parse closure
+// (registerDslConfig owns it), not a bare engine — action copy/open templates
+// resolve the same shared `{{ template "name" }}` helpers every segment does,
+// through one boundary. compileActions needs only the ability to parse a source.
+export function compileActions(
+  parse: (src: string) => Template<RichText>,
+  actions: Readonly<Record<string, ActionDecl>>,
+  stateKeyToVar: ReadonlyMap<string, string>,
+): CompiledActions {
+  const out = new Map<string, CompiledActionDecl>();
+  for (const [name, action] of Object.entries(actions)) {
+    out.set(name, compileAction(parse, name, action, stateKeyToVar));
+  }
+  return out;
+}
+
+// [LAW:dataflow-not-control-flow] One total fold maps each ActionDecl to its
+// compiled shape — the discriminator is which key is present (set's value SOURCE
+// for the three set arms; copy/open otherwise). Every arm reads only its own
+// fields; a new arm is one new branch.
+function compileAction(
+  parse: (src: string) => Template<RichText>,
+  name: string,
+  action: ActionDecl,
+  stateKeyToVar: ReadonlyMap<string, string>,
+): CompiledActionDecl {
+  if ("set" in action) {
+    const stateVar = stateKeyToVar.get(action.set) ?? action.set;
+    if ("to" in action) {
+      return {
+        kind: "set-literal",
+        key: action.set,
+        value: action.to,
+        stateVar,
+      };
+    }
+    if ("from" in action) {
+      return {
+        kind: "set-option",
+        key: action.set,
+        stateVar,
+        options: [...optionDomain(action.from)],
+      };
+    }
+    if ("int" in action) {
+      return { kind: "set-int", key: action.set, stateVar };
+    }
+    if ("cycle" in action) {
+      return {
+        kind: "set-cycle",
+        key: action.set,
+        stateVar,
+        members: action.cycle,
+      };
+    }
+    return {
+      kind: "set-bounded",
+      key: action.set,
+      by: action.by,
+    };
+  }
+  if ("copy" in action) {
+    return {
+      kind: "copy",
+      text: parseActionTemplate(parse, action.copy, name),
+    };
+  }
+  return {
+    kind: "open",
+    target: parseActionTemplate(parse, action.open, name),
+  };
+}
+
+function parseActionTemplate(
+  parse: (src: string) => Template<RichText>,
+  src: string,
+  name: string,
+): Template<RichText> {
+  try {
+    return parse(src);
+  } catch (e) {
+    throw new Error(
+      `Template parse error in actions.${name}: ${(e as Error).message}`,
+      { cause: e },
+    );
+  }
+}
+
+// ─── Rendering ───────────────────────────────────────────────────────────────
+
+// [LAW:one-source-of-truth] Exported so the picker reads SessionState through the
+// SAME boundary (has() discriminates "never written" → "").
+export function readVar(store: VariableStore, name: string): string {
+  // [LAW:no-defensive-null-guards] "current value may not exist" is a legitimate
+  // state (the key was never written) — guard the store lookup, not a downstream
+  // operation. has() is the discriminator; absence yields "".
+  return store.has(name) ? varToString(store.read(name)) : "";
+}
+
+function evalTemplate(tpl: Template<RichText>, scope: object): string {
+  return tpl
+    .evaluate(scope)
+    .map((f) => f.plain)
+    .join("");
+}
+
+// [LAW:single-enforcer] One link-span constructor for both action and picker
+// cells — a Style carrying the OSC-8 url, `active` riding as bold.
+export function linkFragment(
+  text: string,
+  url: string,
+  active: boolean,
+): RichText {
+  // [LAW:one-source-of-truth] Build the link span exactly as rich-js's `link`
+  // does: a Style carrying the OSC-8 url. `active` rides as bold so the
+  // currently-selected value reads as current — a value on the span, not a
+  // branch in the walk.
+  const rt = new RichText(text, {
+    style: new Style({ link: url, bold: active }),
+  });
+  rt.noWrap = true;
+  rt.end = "";
+  return rt;
+}
+
+// [LAW:one-source-of-truth] THE "unknown current counts as the first member"
+// rule — the one resolution both the display selection and the successor write
+// fold over. Members are ordered default-state-first, so an unset/foreign value
+// renders the first display and clicks to the second member (an accordion
+// sibling's path "counts as closed", a never-written toggle "counts as off").
+function cycleIndex(
+  c: Extract<CompiledActionDecl, { kind: "set-cycle" }>,
+  store: VariableStore,
+): number {
+  return Math.max(c.members.indexOf(readVar(store, c.stateVar)), 0);
+}
+
+// [LAW:dataflow-not-control-flow] The single total projection of a compiled action
+// onto (effect, active) — the click's wire effect plus whether this region is the
+// current selection. The template supplies `display` (the clickable text) and an
+// optional `boundValue` (an option picker binds each option's value); the action
+// declaration supplies everything else. Consumers never re-switch on the action
+// kind: this fold is the one place the union is matched.
+//   • set-literal: writes its fixed value; active when the key already holds it.
+//   • set-option:  writes boundValue ?? display (the bound option); active when
+//                  the key already holds it (the picker's current-mark).
+//   • set-bounded: emits a RELATIVE step-state nudge (key + signed by); never
+//                  reads current and never "active". The wrap + bounds + the
+//                  unset seed are applied at APPLY time by the daemon handler
+//                  reading live state, not snapshotted into the link here.
+//   • copy/open:   one copy/open effect of the evaluated template; never active.
+// [LAW:dataflow-not-control-flow] The template scope is an input only the copy/
+// open arms consume, so it is built WHERE consumed (buildScope snapshots
+// store.names() into a Set per call — paying it for a set-* region, e.g. every
+// cell of an option picker, is pure waste). set-* arms read individual vars
+// directly. This is data locality, not a control-flow guard: the scope simply
+// flows into the arms that need it.
+function realize(
+  c: CompiledActionDecl,
+  display: string,
+  boundValue: string | undefined,
+  store: VariableStore,
+  sessionId: string,
+): { effect: Effect; active: boolean } {
+  switch (c.kind) {
+    case "set-literal": {
+      const current = readVar(store, c.stateVar);
+      return {
+        effect: { verb: VERB_SET_STATE, args: [sessionId, c.key, c.value] },
+        active: current === c.value,
+      };
+    }
+    case "set-option": {
+      const value = boundValue ?? display;
+      const current = readVar(store, c.stateVar);
+      return {
+        effect: { verb: VERB_SET_STATE, args: [sessionId, c.key, value] },
+        active: current === value,
+      };
+    }
+    case "set-int": {
+      // The render binds the integer to write (a picker's page nav passes the
+      // target page as boundValue; a bare `{{ action }}` passes its display).
+      // The unbounded int gate accepts it; active when the key already holds it.
+      const value = boundValue ?? display;
+      const current = readVar(store, c.stateVar);
+      return {
+        effect: { verb: VERB_SET_STATE, args: [sessionId, c.key, value] },
+        active: current === value,
+      };
+    }
+    case "set-cycle": {
+      // [LAW:one-source-of-truth] The same current-index resolution that picked
+      // the rendered display picks the write target — display and write derive
+      // from one read, so the click delivers exactly the transition the glyph
+      // promised.
+      const next = c.members[(cycleIndex(c, store) + 1) % c.members.length]!;
+      return {
+        effect: { verb: VERB_SET_STATE, args: [sessionId, c.key, next] },
+        active: false,
+      };
+    }
+    case "set-bounded": {
+      // [LAW:one-source-of-truth] Emit a RELATIVE nudge — the irreducible intent
+      // (key + signed delta), never an absolute target derived from a render-time
+      // snapshot of `current`. The daemon's step-state handler reads live state,
+      // applies the wrap against the registry's bounds, and writes through the
+      // single range gate. So the link is byte-identical across renders and N
+      // rapid clicks each accumulate (the idempotent absolute-write bug is gone).
+      return {
+        effect: {
+          verb: VERB_STEP_STATE,
+          args: [sessionId, c.key, String(c.by)],
+        },
+        active: false,
+      };
+    }
+    case "copy":
+      return {
+        effect: {
+          verb: VERB_COPY,
+          args: [evalTemplate(c.text, buildScope(store))],
+        },
+        active: false,
+      };
+    case "open":
+      return {
+        effect: {
+          verb: VERB_OPEN_VSCODE,
+          args: [evalTemplate(c.target, buildScope(store))],
+        },
+        active: false,
+      };
+  }
+}
+
+// [LAW:dataflow-not-control-flow] Which text a region shows is a pure function
+// of (action kind, bound displays, current state). A cycle binds one display per
+// member positionally (the toggle/N-state-cycler form: `{{ action "t" "▸" "▾"
+// }}`) or one static display for all states; every other kind binds one display
+// plus an optional boundValue (the option-picker form). Wrong arity is an author
+// error surfaced loudly at render (composeWithDiagnostics shows it), never a
+// silently dropped argument.
+function selectDisplay(
+  name: string,
+  action: CompiledActionDecl,
+  displays: readonly string[],
+  store: VariableStore,
+): { display: string; boundValue: string | undefined } {
+  if (displays.length === 0) {
+    throw new Error(`action "${name}" needs a display (the clickable text)`);
+  }
+  if (action.kind === "set-cycle") {
+    if (displays.length !== 1 && displays.length !== action.members.length) {
+      throw new Error(
+        `action "${name}" cycles ${action.members.length} members; bind one display per member (${action.members.length}) or one static display, got ${displays.length}`,
+      );
+    }
+    const display =
+      displays.length === 1
+        ? displays[0]!
+        : displays[cycleIndex(action, store)]!;
+    return { display, boundValue: undefined };
+  }
+  if (displays.length > 2) {
+    throw new Error(
+      `action "${name}" takes a display and an optional bound value, got ${displays.length} arguments (per-state displays are a cycle action's form)`,
+    );
+  }
+  return { display: displays[0]!, boundValue: displays[1] };
+}
+
+// Realize a named action against the live state into ONE clickable RichText. The
+// `action` template function delegates here.
+export function renderAction(
+  name: string,
+  displays: readonly string[],
+  runtime: ActionRuntime,
+): RichText {
+  const action = runtime.compiled.get(name);
+  // [LAW:no-defensive-null-guards] The loader validates every `{{ action "x" }}`
+  // reference resolves to a declared action, and compileActions compiled every
+  // declared action for THIS config's engine. A miss is a caller/wiring bug.
+  if (!action) {
+    throw new Error(`action "${name}" is not declared in this config`);
+  }
+  const store = runtime.store;
+  if (!store) {
+    throw new Error(
+      `action "${name}" rendered without a VariableStore — registerDslConfig was not given one`,
+    );
+  }
+  const { display, boundValue } = selectDisplay(name, action, displays, store);
+  const sessionId = readVar(store, "session.id");
+  const { effect, active } = realize(
+    action,
+    display,
+    boundValue,
+    store,
+    sessionId,
+  );
+  return linkFragment(display, effectsUrl([effect]), active);
+}
+
+// ─── FuncMap entry ─────────────────────────────────────────────────────────────
+
+// [LAW:dataflow-not-control-flow] One func; the action NAME selects which declared
+// effect fires, the trailing strings are the bound displays. For most kinds that
+// is the clickable text plus an optional boundValue (absent ⇒ the option IS the
+// display, the common picker form `{{ action "applyTheme" . }}`); for a cycle it
+// is one display per member (the current member's display renders) or one static
+// display. Returns T (RichText), the single fragment go-template-js emits for
+// `{{ action … }}`.
+//
+// [LAW:one-way-deps] The caller injects this FuncMap into createCcCandybarEngine
+// (capabilities-over-context) so the generic engine never imports the action
+// feature.
+export function actionFuncs(runtime: ActionRuntime): FuncMap {
+  return {
+    action: {
+      fn: (name: string, ...displays: string[]) =>
+        renderAction(name, displays, runtime),
+      argTypes: ["string", "string"],
+      returnType: "T",
+    },
+  };
+}

package/src/render/diagnostic-style.ts

@@ -0,0 +1,23 @@
+// The cc-candybar diagnostic visual identity: the ANSI style constants for
+// every error/warning surface we draw (the client's permanent-failure glyph
+// and the daemon's per-render diagnostic strip).
+//
+// [LAW:one-source-of-truth] This leaf module is the single TS definition of
+// the diagnostic style. Recoloring diagnostics is an edit here, nowhere else
+// — a partial restyle that ships an inconsistent error language is no longer
+// expressible within the Node runtime.
+//
+// [LAW:one-way-deps] A leaf: imports nothing, so both the daemon
+// (src/daemon/server.ts) and the client render path
+// (src/render/error-glyph.ts) can import it without daemon↔client coupling —
+// the same direction already used for ./diagnostic-text.
+//
+// The Rust client (rust-client/src/error_glyph.rs) cannot import a TS module,
+// so it mirrors the error trio as literal consts; scripts/check-protocol.mjs
+// diffs that mirror against this file and fails prepublishOnly on drift.
+
+export const DIAGNOSTIC_ERROR_FG = "\x1b[38;2;255;255;255m";
+export const DIAGNOSTIC_ERROR_BG = "\x1b[48;2;200;40;40m";
+export const DIAGNOSTIC_WARNING_FG = "\x1b[38;2;0;0;0m";
+export const DIAGNOSTIC_WARNING_BG = "\x1b[48;2;220;160;40m";
+export const ANSI_RESET = "\x1b[0m";

package/src/render/diagnostic-text.ts

@@ -0,0 +1,77 @@
+// [LAW:one-source-of-truth] The single sanitize-and-truncate primitive for
+// any diagnostic text we embed inside a single-line, ANSI-styled envelope.
+// Two callers today:
+//   - src/render/error-glyph.ts (permanent client-side glyph; budget 60)
+//   - src/daemon/server.ts composeWithDiagnostics (per-render diagnostic
+//     strip carrying the actual config error/warning message)
+// A third copy in the daemon would duplicate the security-critical
+// control-char neutralization rules; sharing the primitive guarantees the
+// rules cannot drift between callers.
+//
+// [LAW:types-are-the-program] Two functions, both pure (string, number)→
+// string|boolean. The contract is exactly: "make this text safe to splice
+// into a single-line ANSI-styled cell, clipped to maxLen visible code
+// points." Anything else is the caller's responsibility (which icon, which
+// colors, which click verb).
+
+const ELLIPSIS = "…";
+
+// [LAW:dataflow-not-control-flow] Every code point flows through the same
+// predicate. No special-case branches per kind of control; the Unicode Cc
+// class is the single discriminator that decides "this byte/code point
+// could hijack the envelope and must be neutralized."
+//
+// Why the C1 range matters (0x80..0x9F):
+//   ESC (U+001B) is the obvious ANSI-escape entry point, but some
+//   terminals interpret U+009B as 8-bit CSI directly — i.e. equivalent to
+//   ESC `[`. Sanitizing only the C0 range (≤0x1F + 0x7F) would leave the
+//   8-bit bypass open. With diagnostic messages echoing user-supplied
+//   data (config paths, key names, parse errors), that's reachable from
+//   crafted input even without a malicious daemon.
+//
+// Mirrors rust-client/src/error_glyph.rs's truncate(): `char::is_control()`
+// matches the exact same Unicode Cc set, so the TS and Rust runtimes
+// neutralize the same byte classes. The Rust side also mirrors the
+// collapse-whitespace-runs + trim pass below, so the two runtimes produce
+// byte-identical output — both suites pin the same fixtures.
+export function isControlChar(code: number): boolean {
+  return code < 0x20 || code === 0x7f || (code >= 0x80 && code <= 0x9f);
+}
+
+// Sanitize control characters (→ single space) and clip to maxLen visible
+// code points, ending with an ellipsis if the input was longer. Runs of
+// whitespace (post-sanitize) collapse to a single space so multi-line
+// indented messages don't display as awkwardly-spaced single lines.
+//
+// [LAW:dataflow-not-control-flow] One pass over the input; the trailing
+// `.replace(/.$/u, ELLIPSIS)` is the only branch and only fires when we
+// hit the cap. The cap-then-ellipsis is the same pattern error-glyph used
+// pre-extraction (preserved byte-for-byte: visible length stays at maxLen
+// when truncation happens).
+export function sanitizeAndTruncate(text: string, maxLen: number): string {
+  // First pass: sanitize control chars to spaces. We do this before the
+  // length count because a control char and its replacement space are both
+  // one visible code point in the output — equal contributions to length.
+  let sanitized = "";
+  for (const ch of text) {
+    sanitized += isControlChar(ch.codePointAt(0) ?? 0) ? " " : ch;
+  }
+  // Collapse whitespace runs (introduced by newline→space + the existing
+  // indentation in multi-line error messages). One space conveys the same
+  // "this was a break in the source" information without wasting cells.
+  sanitized = sanitized.replace(/\s+/g, " ").trim();
+
+  // Truncate-with-ellipsis. The /.$/u regex matches a full code point
+  // (unicode flag), not a UTF-16 unit — important for emoji and other
+  // astral-plane chars in user-supplied paths.
+  let out = "";
+  let count = 0;
+  for (const ch of sanitized) {
+    if (count === maxLen) {
+      return out.replace(/.$/u, ELLIPSIS);
+    }
+    out += ch;
+    count++;
+  }
+  return out;
+}

package/src/render/error-glyph.ts

@@ -0,0 +1,53 @@
+// One-line styled diagnostic glyph emitted on permanent daemon failures.
+//
+// [LAW:single-enforcer] One formatter per runtime. The Node entry in
+// src/index.ts calls formatPermanentGlyph; nothing else builds this string.
+//
+// [LAW:one-type-per-behavior] The Rust mirror at rust-client/src/error_glyph.rs
+// must produce byte-identical output for the same logical cause — both
+// runtimes show the same diagnostic so the user's experience does not depend
+// on which client is on the hot path. The mirrored constants are diffed by
+// scripts/check-protocol.mjs; the sanitize/collapse/truncate behavior is
+// pinned by paired fixture tests on both sides.
+//
+// [LAW:one-source-of-truth] Both shared primitives live in leaf modules under
+// ./: the style constants in ./diagnostic-style (shared with the daemon's
+// composeWithDiagnostics so the diagnostic visual language cannot drift) and
+// the sanitize-and-truncate primitive in ./diagnostic-text (shared with
+// src/daemon/server.ts so the security-critical control-char neutralization
+// (C0 + DEL + C1/8-bit-CSI) cannot drift between the two callers).
+
+import type { PermanentOutcome } from "../daemon/client-transport";
+import {
+  ANSI_RESET,
+  DIAGNOSTIC_ERROR_BG,
+  DIAGNOSTIC_ERROR_FG,
+} from "./diagnostic-style";
+import { sanitizeAndTruncate } from "./diagnostic-text";
+
+const OPEN = `${DIAGNOSTIC_ERROR_BG}${DIAGNOSTIC_ERROR_FG}`;
+const PREFIX = "⚠ cc-candybar: ";
+
+// Long messages from the daemon (parse errors, internal exception strings)
+// can be arbitrarily long. The glyph must fit on a single statusline row, so
+// truncate to a budget that leaves room for the prefix at typical widths.
+const MAX_MESSAGE_LEN = 60;
+
+export function formatPermanentGlyph(outcome: PermanentOutcome): string {
+  return `${OPEN}${PREFIX}${describe(outcome)}${ANSI_RESET}\n`;
+}
+
+function describe(outcome: PermanentOutcome): string {
+  switch (outcome.cause) {
+    case "version_mismatch": {
+      const daemon = outcome.daemonV === 0 ? "unknown" : `v${outcome.daemonV}`;
+      return `protocol mismatch (client v${outcome.clientV} ≠ daemon ${daemon})`;
+    }
+    case "bad_request":
+      return `daemon rejected request: ${sanitizeAndTruncate(outcome.message, MAX_MESSAGE_LEN)}`;
+    case "render_failed":
+      return `render failed: ${sanitizeAndTruncate(outcome.message, MAX_MESSAGE_LEN)}`;
+    case "malformed_response":
+      return `malformed daemon response: ${sanitizeAndTruncate(outcome.message, MAX_MESSAGE_LEN)}`;
+  }
+}

package/src/render/outcome-plan.ts

@@ -0,0 +1,45 @@
+// Pure mapping from ClientOutcome to a render plan: what to write, whether
+// to kick a fresh daemon, and (if relevant) the debug message that describes
+// why. All variability lives in the returned value — including the debug
+// string — so this module has no observable side effects. The runtime
+// composition in src/index.ts consumes the plan and owns every side effect
+// (debug logging, kick, write, exit).
+//
+// [LAW:dataflow-not-control-flow] Variability lives in the returned values
+// (output string, kick flag, debug message). The caller's debug/kick/write/
+// exit run unconditionally against those values — no caller-side branching
+// on outcome.kind.
+//
+// [LAW:types-are-the-program] Exhaustive over ClientOutcome.kind. Adding a
+// new variant fails typecheck rather than silently falling out the bottom
+// of the switch.
+
+import { formatPermanentGlyph } from "./error-glyph";
+import type { ClientOutcome } from "../daemon/client";
+
+export interface OutcomePlan {
+  output: string;
+  kick: boolean;
+  // Debug message the caller should log, or null when there is nothing
+  // worth logging (the "ok" path). Held as data so this module stays pure.
+  debug: string | null;
+}
+
+export function planOutcome(outcome: ClientOutcome): OutcomePlan {
+  switch (outcome.kind) {
+    case "ok":
+      return { output: outcome.value, kick: false, debug: null };
+    case "transient":
+      return {
+        output: "\n",
+        kick: true,
+        debug: `daemon unavailable (transient: ${outcome.cause}: ${outcome.message}) — kicking daemon`,
+      };
+    case "permanent":
+      return {
+        output: formatPermanentGlyph(outcome),
+        kick: false,
+        debug: `daemon refused request (permanent: ${outcome.cause}) — not kicking`,
+      };
+  }
+}