@promptctl/cc-candybar 1.34.1 → 1.36.0

package/src/config/settings-menu.ts

@@ -0,0 +1,373 @@
+// [LAW:one-source-of-truth] candybar-settings-ui-aok.1 — THE global settings
+// menu: one disclosure that every rendered bar carries, whatever the config
+// says. It exists because `root` replaces wholesale: a user who writes `root:`
+// (the ordinary reason to write a config at all) silently deletes every
+// interactive surface the bundled default placed there — presets, edit mode,
+// the value controls. A door the user can delete by accident is not a door.
+//
+// [LAW:dataflow-not-control-flow] Placement is a POSITION, never a mode. The
+// synthesis runs the same two total functions on every preset root, in the same
+// order, every load: `withAnchor` yields a tree that CONTAINS the anchor — the
+// author's own placement untouched, or the default position appended — and
+// `expandAnchor` replaces that one leaf with the lowered disclosure subtree.
+// "The author placed it" and "the author did not" differ only in the VALUE
+// handed to one splice; there is no second code path to keep in agreement.
+//
+// [LAW:one-type-per-behavior] Nothing here is a new render or interaction
+// concept. The menu is the disclosure primitive's fourth instance, alongside
+// group sugar, `{{ menu }}`, and edit mode's toggle: it calls the SAME
+// `disclosureStateVar`/`disclosureCycleAction`/`menuStateKey` functions those
+// three call, so a synthesized global menu and a hand-authored group are
+// indistinguishable to the render walk.
+//
+// WHY THIS RUNS FROM validateConfig, BEFORE synthesizeEditChrome — the two
+// passes both rewrite every preset root, so their order is a real decision:
+//   • It cannot run at parse time (loader/*.ts) like group/menu synthesis,
+//     because the tree it must splice into only exists after merge: the user's
+//     `root` replaces the bundled default's, and it is the MERGED root the menu
+//     has to be present in.
+//   • It runs BEFORE edit chrome so edit chrome walks the final content tree.
+//     Every name minted here lives under the reserved `settings.` namespace,
+//     which `isChromeExempt` excludes, so the menu never acquires a `+`/`-`
+//     affordance and can never be edited out of the bar it is the entry point
+//     to. Running after would splice the menu into an already-chromed tree,
+//     landing it between a segment and the `-` that removes it.
+//   • It also GUARANTEES `edit.toggle` (see ensureEditToggle below), which is
+//     precisely what edit chrome's own demand gate reads — so the ordering is
+//     load-bearing in that direction too, not merely tidy.
+
+import type { ActionDecl } from "./action.js";
+import type {
+  DslConfig,
+  LayoutNode,
+  PresetDecl,
+  SegmentDecl,
+  VariableDecl,
+} from "./dsl-types.js";
+import {
+  DISCLOSURE_CLOSED,
+  DISCLOSURE_GLYPH_CLOSED,
+  DISCLOSURE_GLYPH_OPEN,
+  disclosureCycleAction,
+  disclosureStateVar,
+} from "./disclosure.js";
+import {
+  EDIT_MODE_KEY,
+  EDIT_MODE_OPEN,
+  EDIT_TOGGLE_ACTION,
+} from "./loader/edit-mode.js";
+import {
+  menuActionName,
+  menuMember,
+  menuPageKey,
+  menuStateKey,
+} from "./menu-keys.js";
+import { presetByName, presetNames, presetRoot } from "./presets.js";
+
+// [LAW:one-source-of-truth] The reserved namespace every artifact this pass
+// mints lives under, mirroring `groups.`/`menus.`/`edit.`. Reserved at parse
+// time (reservedNamespaceCollisions, from dsl-loader's validateTopLevel) so a
+// user name under it is a loud load error rather than a silent shadowing of
+// the one surface they cannot afford to lose.
+export const SETTINGS_NS = "settings.";
+
+// [LAW:one-source-of-truth] THE anchor: one string that is simultaneously the
+// segment name an author places in `root` to choose the menu's position, the
+// name of the toggle segment the synthesis puts there, the disclosure's state
+// variable, and its cycle action. Group sugar already spans those four with one
+// `groups.<name>` string for the same reason — one name means the toggle's
+// click and the body's `when` cannot address different keys.
+export const SETTINGS_ANCHOR = `${SETTINGS_NS}menu`;
+
+// The disclosure's open member. Same spelling edit mode uses for its own binary
+// toggle — a binary disclosure holds the CLOSED sentinel or this.
+const SETTINGS_OPEN = EDIT_MODE_OPEN;
+
+// The body's two content segments and the preset picker's apply action. `.1`
+// scopes the body to what its acceptance names — switch presets, enter edit
+// mode. The remaining display controls arrive with the config menu (`.3`),
+// which is the child that owns them.
+const PRESETS_SEG = `${SETTINGS_NS}presets`;
+const EDIT_SEG = `${SETTINGS_NS}edit`;
+const APPLY_PRESET_ACTION = `${SETTINGS_NS}applyPreset`;
+
+// [LAW:one-source-of-truth] The predicate the body container gates on, derived
+// 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}" }}`;
+
+// [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
+// no config declares (this pass provides it, unconditionally, immediately after
+// cross-ref passes), and to reject a SECOND placement — one key holds one open
+// state, so two anchors would be two toggles writing one disclosure.
+export function isSettingsAnchor(segmentName: string): boolean {
+  return segmentName === SETTINGS_ANCHOR;
+}
+
+// ─── The anchored-root stamp ────────────────────────────────────────────────
+
+declare const anchored: unique symbol;
+
+// [LAW:parse-dont-validate] A tree that is KNOWN to contain the anchor. The
+// stamp is the proof, so `expandAnchor` has no "anchor missing" arm to guard
+// and no answer-shaped void to return: the only way to obtain this type is to
+// go through `withAnchor`, which establishes the fact by construction.
+//
+// The theorem includes the anchor inheriting no gate the DEFAULT placement
+// descended into — a weaker stamp ("contains an anchor" alone) is what let a
+// `when`-gated first row silently swallow the menu. Two gates are exempt
+// because they are explicit authorial statements rather than accidents: the
+// author's own placement of the anchor (they chose that position, gate and
+// all) and a `when` on the root itself (there is no bar at all under that
+// condition, so there is nothing to host a menu on).
+type AnchoredRoot = LayoutNode & { readonly [anchored]: true };
+
+// [LAW:dataflow-not-control-flow] The default position, as structural recursion
+// over the LayoutNode union rather than a placement mode: descend to the bar's
+// FIRST horizontal row and append there — where the bundled default's own
+// settings affordance already sits, and the place a one-row user config puts
+// everything. Total over every tree shape, including the degenerate ones: a
+// bare-segment root (the A-grammar collapses a lone top-level ref) grows a
+// horizontal wrapper, and an empty container simply becomes the row.
+function appendAnchor(node: LayoutNode): LayoutNode {
+  const anchorRef: LayoutNode = { kind: "segment", name: SETTINGS_ANCHOR };
+  if (node.kind === "segment") {
+    // [LAW:no-silent-failure] A bare-segment root may carry its OWN `when` — an
+    // author gating their whole bar behind a condition. This wrapper is a brand
+    // new node, so without carrying that gate up, everything spliced beside the
+    // segment (this menu, and the reset banner edit chrome later prepends by
+    // reading `splicedRoot.when`) would render past a gate the author wrote.
+    // The identical carry-up spliceEditChromeForPreset performs, one pass over.
+    return {
+      kind: "container",
+      direction: "horizontal",
+      children: [node, anchorRef],
+      ...(node.when !== undefined && { when: node.when }),
+    };
+  }
+  const [first, ...rest] = node.children;
+  // [LAW:no-silent-failure] Descend only into an UNGATED child. A gate on an
+  // inner row is a statement about that row's content, not about the bar — an
+  // author writing an ordinary conditional first row (a git row shown only
+  // inside a repo) has no idea the default placement attaches the menu there,
+  // and inheriting that gate would silently delete the one surface this pass
+  // exists to make undeletable, under exactly their condition. When the first
+  // row is gated the anchor becomes its own ungated row on this container
+  // instead, which is a position the author can still override by placing the
+  // anchor themselves.
+  //
+  // The ROOT's own `when` is deliberately NOT lifted out of, here or in the
+  // segment arm above: gating the whole tree is an explicit statement that
+  // there is no bar under this condition, and there is no bar to host a menu
+  // on. That is the same "the author's explicit choice is the answer" rule
+  // that honors an author-placed anchor inside a gated row — and it is what
+  // keeps edit chrome's reset banner gated with the content it describes.
+  if (
+    node.direction === "vertical" &&
+    first !== undefined &&
+    first.when === undefined
+  ) {
+    return { ...node, children: [appendAnchor(first), ...rest] };
+  }
+  return { ...node, children: [...node.children, anchorRef] };
+}
+
+// [LAW:parse-dont-validate] The checkpoint: in, a tree that may or may not name
+// the anchor; out, a tree that provably does. The author's placement passes
+// through byte-identical — the position they chose IS the answer — and its
+// absence is answered with the default position. One value, two sources.
+function withAnchor(node: LayoutNode): AnchoredRoot {
+  const placed = countAnchors(node) > 0 ? node : appendAnchor(node);
+  return placed as AnchoredRoot;
+}
+
+// [LAW:single-enforcer] THE anchor census, read by both consumers of the count:
+// `withAnchor` (is there a placement to honor?) and the loader's duplicate check
+// (is there more than one?). One traversal definition, so "placed" cannot mean
+// different things to the two.
+export function countAnchors(node: LayoutNode): number {
+  if (node.kind === "segment") return isSettingsAnchor(node.name) ? 1 : 0;
+  return node.children.reduce((n, child) => n + countAnchors(child), 0);
+}
+
+// [LAW:one-type-per-behavior] The lowering, identical in shape to lowerGroup's:
+// 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 {
+  if (node.kind === "segment") {
+    return isSettingsAnchor(node.name)
+      ? {
+          kind: "container",
+          direction: "vertical",
+          children: [
+            node,
+            {
+              kind: "container",
+              direction: "horizontal",
+              children: [
+                { kind: "segment", name: PRESETS_SEG },
+                { kind: "segment", name: EDIT_SEG },
+              ],
+              when: SETTINGS_OPEN_GATE,
+            },
+          ],
+        }
+      : node;
+  }
+  return { ...node, children: node.children.map(expandAnchor) };
+}
+
+// ─── The artifacts ──────────────────────────────────────────────────────────
+
+interface MenuArtifacts {
+  readonly variables: Record<string, VariableDecl>;
+  readonly actions: Record<string, ActionDecl>;
+  readonly segments: Record<string, SegmentDecl>;
+}
+
+// [LAW:single-enforcer] The `{{ menu }}` disclosure a body segment hosts,
+// synthesized by calling the SAME pure functions menu-synth.ts's parse-time pass
+// calls — the identical move edit-chrome.ts's insertChrome makes, and for the
+// identical reason: this pass runs too late to piggyback on that one, so parity
+// comes from sharing the derivation, never from restating it.
+function declareHostedMenu(
+  segName: string,
+  applyName: string,
+  artifacts: MenuArtifacts,
+): void {
+  const member = menuMember(applyName);
+  const stateKey = menuStateKey(segName, applyName, undefined);
+  const pageKey = menuPageKey(stateKey);
+  artifacts.variables[stateKey] = disclosureStateVar(
+    stateKey,
+    DISCLOSURE_CLOSED,
+  );
+  artifacts.variables[pageKey] = { kind: "state", key: pageKey, default: "0" };
+  artifacts.actions[menuActionName(stateKey, member)] = disclosureCycleAction(
+    stateKey,
+    member,
+  );
+  artifacts.actions[pageKey] = { set: pageKey, int: true };
+}
+
+// [LAW:one-source-of-truth] Everything the menu is, minted ONCE per config and
+// merely REFERENCED from each preset root. This is what makes the pass
+// idempotent across N presets for free: a preset root carries a segment
+// 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 {
+  const artifacts: MenuArtifacts = {
+    variables: {
+      [SETTINGS_ANCHOR]: disclosureStateVar(SETTINGS_ANCHOR, DISCLOSURE_CLOSED),
+    },
+    actions: {
+      [SETTINGS_ANCHOR]: disclosureCycleAction(SETTINGS_ANCHOR, SETTINGS_OPEN),
+      // [LAW:single-enforcer] The picker's apply effect, gated by derivation
+      // like every other `from`-sourced set: `presets` is a per-config domain
+      // both deriveActionValidators and the rendered options resolve through
+      // one `resolveOptionDomain`, so this adds a control, never a gate.
+      [APPLY_PRESET_ACTION]: { set: "preset", from: "presets" },
+    },
+    segments: {
+      // [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",
+      },
+      [PRESETS_SEG]: {
+        template: `▦ {{ menu "${APPLY_PRESET_ACTION}" (dict "closeOnPick" true) }}`,
+        bg: "surface",
+        fg: "foreground",
+      },
+      // The entry point edit mode never had: `edit.toggle` is a reserved action
+      // whose only bundled reference lives in the `toolbar` segment, which a
+      // user config's `root` drops like everything else. Here it is reachable
+      // from a segment no config can drop.
+      [EDIT_SEG]: {
+        template: `{{ action "${EDIT_TOGGLE_ACTION}" "✎ edit" "✎ done" }}`,
+        bg: "surface",
+        fg: "foreground",
+      },
+    },
+  };
+  declareHostedMenu(PRESETS_SEG, APPLY_PRESET_ACTION, artifacts);
+  return artifacts;
+}
+
+// [LAW:one-source-of-truth] Edit mode's toggle, ensured rather than duplicated:
+// both this pass and synthesizeEditModeToggle produce it by calling the same two
+// disclosure functions on the same two exported constants, so the two mints are
+// the same value by construction and whichever lands first is the only one.
+// Ensuring it here is not an optional courtesy — the EDIT_SEG segment above
+// references `edit.toggle`, and that pass is demand-driven off a scan of the
+// segments a FILE declared, which cannot see a segment this pass mints later.
+function ensureEditToggle(artifacts: MenuArtifacts): void {
+  artifacts.variables[EDIT_MODE_KEY] = disclosureStateVar(
+    EDIT_MODE_KEY,
+    DISCLOSURE_CLOSED,
+  );
+  artifacts.actions[EDIT_TOGGLE_ACTION] = disclosureCycleAction(
+    EDIT_MODE_KEY,
+    EDIT_MODE_OPEN,
+  );
+}
+
+// [LAW:one-source-of-truth] The variable whose presence IS the precondition,
+// named once so the predicate below and the load error cross-ref.ts raises when
+// it fails cannot describe different variables.
+export const SESSION_ID_VAR = "session.id";
+
+// [LAW:types-are-the-program] The menu's one structural prerequisite, read as a
+// value: a global `session.id`. It is not a demand gate and not a preference —
+// the menu is a CLICK surface, every click composes a URL whose first segment is
+// `session.id` read from the store, and cross-ref.ts already rejects an AUTHORED
+// state read or `set` write in a config that declares no such variable. A config
+// without it describes a static, non-interactive bar, and there is no menu to
+// place on one. Every config the daemon renders merges the bundled default,
+// which declares `session.id`, so in production this is universally true; what
+// it excludes is the hand-built static config, not a user.
+//
+// [LAW:one-source-of-truth] Exported because this is THE fact "will the anchor
+// resolve to a segment?" — asked here to decide whether to mint the menu, and
+// asked by cross-ref.ts to decide whether an authored placement of the anchor is
+// a reference this pass is about to satisfy or a dangling one. Two readers, one
+// predicate: when they were two predicates, cross-ref accepted an anchor this
+// pass then declined to provide, and the un-lowered reference reached the render
+// walk to throw at `lookupSegment`.
+export function canHostSessionState(config: DslConfig): boolean {
+  return Object.prototype.hasOwnProperty.call(config.variables, SESSION_ID_VAR);
+}
+
+// [LAW:single-enforcer] THE synthesis entry point, called once from
+// validateConfig after cross-ref/cycle checks pass and before edit chrome.
+// Every declared preset — the floor `default` included — gets an explicit
+// `presets[name].root` carrying its anchored, expanded tree; `config.root`
+// itself is left untouched, exactly as synthesizeEditChrome leaves it, because
+// presetRoot falls back to it only for a preset declaring no root of its own
+// and every name now declares one.
+export function synthesizeSettingsMenu(config: DslConfig): DslConfig {
+  if (!canHostSessionState(config)) return config;
+  const artifacts = 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)),
+    };
+  }
+  return {
+    ...config,
+    variables: { ...config.variables, ...artifacts.variables },
+    actions: { ...config.actions, ...artifacts.actions },
+    segments: { ...config.segments, ...artifacts.segments },
+    presets,
+  };
+}

package/src/daemon/client.ts

@@ -12,7 +12,7 @@
 import type { ClaudeHookData } from "../utils/claude";
 import { requestOutcome } from "./client-transport";
 import type { RoundTripBudgets, RoundTripOutcome } from "./client-transport";
-import type { Response } from "./protocol";
+import type { ClientHints, Response } from "./protocol";
 
 const CONNECT_TIMEOUT_MS = 50;
 const TOTAL_BUDGET_MS = 150;
@@ -47,14 +47,17 @@ function projectOutput(
 // There is no inline render path; see src/index.ts. The caller is responsible
 // for branching on outcome.kind and deciding whether to kick, display an
 // error glyph, or print the rendered output.
+// [LAW:one-source-of-truth] `hints` carries every fact the daemon cannot
+// observe for itself; it is spread onto the request verbatim so this relay
+// never becomes a second place that decides what the client saw.
 export function tryRenderViaDaemon(
   hookData: ClaudeHookData,
   args: string[],
   cwd: string,
-  termCols?: number,
+  hints: ClientHints,
 ): Promise<ClientOutcome> {
   return requestOutcome(
-    { kind: "render", hookData, args, cwd, termCols },
+    { kind: "render", hookData, args, cwd, ...hints },
     RENDER_BUDGETS,
     projectOutput,
   );

package/src/daemon/protocol.ts

@@ -34,12 +34,61 @@ export interface RenderRequest {
   hookData: ClaudeHookData;
   args: string[];
   cwd: string;
-  // [LAW:single-enforcer] Terminal width is captured at the trust boundary
-  // (the client's env, where COLUMNS/ioctl are meaningful) and trusted by the
-  // daemon. Absence means the client couldn't determine it. The wire field is
-  // typed `number` but the wire is untrusted JSON — callers MUST run it
-  // through sanitizeTermCols at the receive boundary before using it.
+  // ─── Client hints ────────────────────────────────────────────────────────
+  // [LAW:single-enforcer] Facts only the LIVE CLIENT can observe, captured at
+  // the trust boundary and trusted by the daemon. The daemon is detached and
+  // one-per-user, so its own env answers for whichever shell spawned it —
+  // possibly a different session, possibly hours ago. Every field below is
+  // typed here but arrives as untrusted JSON: callers MUST route the request
+  // through parseClientHints at the receive boundary, never read these
+  // directly. See the ClientHints doc block for the absence semantics.
   termCols?: number;
+  ssh?: boolean;
+}
+
+// [LAW:locality-or-seam] The seam for "a fact the daemon cannot observe about
+// the session it is rendering for". `termCols` established the pattern; `ssh`
+// is the second member, and the documented-but-unbuilt client-aware
+// `colorCompatibility: "auto"` is the next. Naming the set as ONE type is what
+// keeps that third addition a field rather than another sanitizer, another
+// wire read, and another parameter threaded through the render path.
+//
+// [LAW:parse-dont-validate] This is the stamped type. `RenderRequest`'s
+// same-named fields are raw JSON of unknown provenance; a `ClientHints` has
+// crossed the checkpoint, so nothing downstream re-checks them.
+//
+// [LAW:types-are-the-program] Both fields are optional, but they mean
+// DIFFERENT things by absence, and each is the strongest true theorem for its
+// own fact:
+//   • `termCols` absent — the client tried and could not determine a width
+//     (no COLUMNS, no TTY on stderr). A genuine "unknown", reachable from any
+//     client version.
+//   • `ssh` absent — the client did not REPORT. A current client always knows
+//     (its own env is total on this question) and so always sends `true` or
+//     `false`; absence therefore means one thing only: a client too old to
+//     carry the field — a real case, because `cc-candybar install` stages a
+//     native binary that does not turn over with the npm package. Collapsing
+//     that to `false` here would fuse "we know it's local" with "we don't
+//     know" ([LAW:no-silent-failure]); instead it travels onward as an absent
+//     payload field, where the DSL input-fallback chain emits the declared
+//     default AND records a `last_error` that `cc-candybar debug vars`
+//     surfaces.
+export interface ClientHints {
+  readonly termCols?: number;
+  readonly ssh?: boolean;
+}
+
+// [LAW:single-enforcer] The ONE checkpoint where wire-supplied client hints
+// become trusted values. Per-field sanitizers stay separate (each fact has its
+// own validity rule) but nothing outside this function calls them, so a new
+// hint cannot reach the render path un-sanitized.
+export function parseClientHints(req: RenderRequest): ClientHints {
+  const termCols = sanitizeTermCols(req.termCols);
+  const ssh = sanitizeSsh(req.ssh);
+  return {
+    ...(termCols !== undefined && { termCols }),
+    ...(ssh !== undefined && { ssh }),
+  };
 }
 
 // [LAW:no-defensive-null-guards] exception: trust boundary. The wire is
@@ -58,6 +107,14 @@ export function sanitizeTermCols(v: unknown): number | undefined {
   return n > MAX_TERM_COLS ? MAX_TERM_COLS : n;
 }
 
+// [LAW:no-defensive-null-guards] exception: trust boundary, same shape as
+// sanitizeTermCols. A non-boolean (absent, or a malformed/hostile frame) is
+// NOT coerced to `false` — the three wire states stay three
+// ([LAW:no-silent-failure]): true, false, and "no answer from this client".
+export function sanitizeSsh(v: unknown): boolean | undefined {
+  return typeof v === "boolean" ? v : undefined;
+}
+
 export interface ShutdownRequest {
   v: number;
   kind: "shutdown";

package/src/daemon/render-payload.ts

@@ -17,7 +17,9 @@
 // resolve falls back to the variable's declared default).
 
 import path from "node:path";
+import os from "node:os";
 import type { ClaudeHookData } from "../utils/claude.js";
+import type { ClientHints } from "./protocol.js";
 import type { DslConfig, VariableDecl } from "../config/dsl-types.js";
 import { walkNodes } from "../config/dsl-types.js";
 import { extractTemplateRefs } from "../config/dsl-loader.js";
@@ -96,6 +98,11 @@ export interface RenderPayload extends ClaudeHookData {
 
   readonly git?: GitPayload;
   readonly tmux?: { readonly session: string };
+  // [LAW:types-are-the-program] REQUIRED for the same reason theme/look are:
+  // the daemon assembles it every render from sources that cannot be "not
+  // requested" (two syscalls and one already-parsed wire hint). The fields
+  // INSIDE it carry the real optionality — see HostPayload.
+  readonly host: HostPayload;
   // [LAW:one-source-of-truth] The daemon-resolved effective theme name —
   // effectiveThemeName(sessionState.theme, globals.palette). The SAME value the
   // rendered basePalette is built from, surfaced so a trigger label can display
@@ -200,6 +207,41 @@ export interface GitPayload {
   readonly prError?: string;
 }
 
+// Which machine this session is on, and whether the user got here over the
+// network. The two halves have DIFFERENT provenance and that is the whole
+// design ([LAW:one-source-of-truth]):
+//
+//   • `name`/`user` are MACHINE facts. Client and daemon are the same machine
+//     by construction — the socket path is UID-derived and the pid mutex is
+//     per-user — so the daemon reading them directly cannot drift from what
+//     the client would have reported. Sending them over the wire would buy
+//     nothing and add a second source.
+//   • `ssh` is a SESSION fact and is the exact opposite: one daemon serves a
+//     local session and an SSH session simultaneously, so the daemon's own env
+//     answers for whichever shell spawned it. It can ONLY arrive as a client
+//     hint. This is the same reasoning that makes `globals.colorCompatibility:
+//     "auto"` deliberately unrepresentable.
+//
+// [LAW:no-silent-failure] Every field is optional because each can genuinely
+// be unknown, and absence is preserved rather than defaulted here: `user` when
+// the uid has no passwd entry, `ssh` when the client predates the hint. Both
+// travel as missing keys to the DSL input-fallback chain, which emits the
+// declared default AND records a `last_error` that `cc-candybar debug vars`
+// surfaces — so "we don't know" stays distinguishable from "we know it's
+// local", which a `?? false` here would have destroyed.
+export interface HostPayload {
+  // The SHORT hostname — `os.hostname()` up to the first dot, the same
+  // projection zsh's `%m` makes. A statusbar cell identifies a machine to a
+  // human; the FQDN is a network address, a different fact, and a separate
+  // field the day something needs it.
+  readonly name?: string;
+  // The EFFECTIVE username from the passwd database, not `$USER`. The env var
+  // is a map that drifts (su/sudo leave it stale); the passwd entry for the
+  // running uid is the territory. Matches zsh's `%n`.
+  readonly user?: string;
+  readonly ssh?: boolean;
+}
+
 export interface SessionPayload {
   readonly cost?: number;
   readonly tokens?: number;
@@ -463,6 +505,72 @@ function projectSpeedHistory(obs: SpeedObservation): string | undefined {
   return rates.join(",");
 }
 
+// ─── Host identity ───────────────────────────────────────────────────────────
+
+/**
+ * The short hostname: everything before the first dot, or the whole string when
+ * there is no dot. `os.hostname()` yields an FQDN on some hosts (macOS's
+ * `mymachine.local`, a DNS-configured server's `web1.prod.example.com`) and a
+ * bare name on others; this makes the rendered cell identify the machine the
+ * same way on both, which is zsh's `%m` and the projection git-taculous shows.
+ *
+ * [LAW:effects-at-boundaries] Pure and total — the syscall stays in readHost.
+ */
+export function shortHostname(hostname: string): string {
+  const dot = hostname.indexOf(".");
+  return dot < 0 ? hostname : hostname.slice(0, dot);
+}
+
+/**
+ * Assemble the host identity for one render.
+ *
+ * [LAW:effects-at-boundaries] Named `read*`, not `project*`, because it is not
+ * pure: two syscalls happen here. That is in bounds — this module IS the
+ * daemon's data-assembly edge, the same edge that reads `process.env.HOME`
+ * below — and the point of the seam is that nothing downstream reads them
+ * again.
+ *
+ * [LAW:no-silent-failure] A throwing syscall (a uid with no passwd entry is the
+ * realistic case, in a stripped container) yields an ABSENT field plus a
+ * description for the caller to log, exactly like a failed git lane — never a
+ * fabricated name, and never an exception: the whole bar must not blank over a
+ * cosmetic cell.
+ */
+function readHost(hints: ClientHints): {
+  readonly host: HostPayload;
+  readonly failures: readonly string[];
+} {
+  const failures: string[] = [];
+  const attempt = (field: string, read: () => string): string | undefined => {
+    try {
+      const value = read();
+      // "" is not a usable identity; treat it as absence so the DSL default
+      // applies rather than rendering an empty `@host` fragment.
+      return value === "" ? undefined : value;
+    } catch (e) {
+      failures.push(`host.${field}: ${String(e)}`);
+      return undefined;
+    }
+  };
+
+  const name = attempt("name", () => shortHostname(os.hostname()));
+  const user = attempt("user", () => os.userInfo().username);
+  return {
+    host: {
+      ...(name !== undefined && { name }),
+      ...(user !== undefined && { user }),
+      // [LAW:one-source-of-truth] Passed straight through from the parsed
+      // hint. The daemon deliberately does NOT consult its own SSH_* env as a
+      // fallback: that env belongs to whichever shell spawned it, so a
+      // "helpful" fallback would confidently mislabel every session that
+      // daemon serves. Absent hint → absent field → declared default + a
+      // recorded last_error, which is the honest report of "not answered".
+      ...(hints.ssh !== undefined && { ssh: hints.ssh }),
+    },
+    failures,
+  };
+}
+
 // ─── Builder ─────────────────────────────────────────────────────────────────
 
 // ─── Config-driven provider gating ───────────────────────────────────────────
@@ -666,6 +774,13 @@ export async function buildRenderPayload(
   // daemon already computes every one of these for renderDsl's options; this
   // is that same struct, threaded to the sole payload assembler.
   effective: EffectiveGlobals,
+  // [LAW:locality-or-seam] The parsed client hints, NOT the raw request — this
+  // function is downstream of the wire checkpoint and never re-sanitizes.
+  // Separate from `effective` on purpose: that struct is resolved globals (what
+  // the config and the session chose), this is observed session context (what
+  // the client saw). Fusing them would put a config-precedence chain and a
+  // trust boundary behind one name.
+  hints: ClientHints,
 ): Promise<RenderPayload> {
   const wants = (prefix: string): boolean =>
     anyPathStartsWith(neededInputPaths, prefix);
@@ -756,6 +871,10 @@ export async function buildRenderPayload(
 
   const gitProjection = projectGitInfo(gitOutcome);
   failures.push(...gitProjection.failures);
+  // Ungated, like `home` below: two syscalls and a hint already in hand, so a
+  // `wants` gate would add a branch and save nothing.
+  const hostProjection = readHost(hints);
+  failures.push(...hostProjection.failures);
   const usageValue = take(usage);
   const todayValue = take(today);
   const contextValue = take(context);
@@ -867,6 +986,7 @@ export async function buildRenderPayload(
     ...(home !== undefined && { home }),
     ...(gitProjection.git !== undefined && { git: gitProjection.git }),
     ...(tmuxValue !== undefined && { tmux: { session: tmuxValue } }),
+    host: hostProjection.host,
     // [LAW:one-source-of-truth] Always present — the daemon resolves every
     // one of these each render (for BuildLineOptions/basePalette), and these
     // are those exact values. No `wants` gate: each costs nothing (already in