@promptctl/cc-candybar 1.0.0

package/src/daemon/client-debug.ts

@@ -0,0 +1,120 @@
+// [LAW:single-enforcer] The `vars` / `segments` / `config` CLIs are ONE behavior
+// — fetch a debug snapshot from the running daemon and render it — parameterized
+// by `what`, not three commands. The daemon's `debug` protocol message is the
+// single introspection authority (src/daemon/debug.ts produces DebugSnapshot);
+// this is its client binding, the mirror of client-stats.ts. Like daemon-stats,
+// it does NOT spawn a daemon: introspecting a dead daemon is meaningless.
+
+import process from "node:process";
+import { describeFailure, requestOutcome } from "./client-transport";
+import type { RoundTripBudgets, RoundTripOutcome } from "./client-transport";
+import type {
+  DebugSnapshot,
+  DebugWhat,
+  SegmentSnapshot,
+  VarSnapshot,
+} from "./debug-types";
+import type { DslConfig } from "../config/dsl-types";
+
+// Operator-driven introspection path: legitimately slower budgets than the
+// render hot path, carried as this caller's values through the shared
+// round-trip in ./client-transport. [LAW:dataflow-not-control-flow]
+const BUDGETS: RoundTripBudgets = { connectMs: 200, budgetMs: 500 };
+
+// `cc-candybar <vars|segments|config> [--json]` — `what` selects the projection.
+export async function runDebug(
+  what: DebugWhat,
+  args: readonly string[],
+): Promise<void> {
+  const wantJson = args.includes("--json");
+
+  const outcome = await fetchDebug(what);
+  if (outcome.kind !== "ok") {
+    process.stderr.write(`${what}: ${describeFailure(outcome)}\n`);
+    process.exit(1);
+  }
+
+  if (wantJson) {
+    process.stdout.write(JSON.stringify(outcome.value, null, 2) + "\n");
+    return;
+  }
+
+  process.stdout.write(formatDebug(outcome.value));
+}
+
+function fetchDebug(what: DebugWhat): Promise<RoundTripOutcome<DebugSnapshot>> {
+  // [LAW:no-defensive-null-guards] exception: trust boundary. The response is
+  // an unchecked cast from socket JSON; the presence check is the explicit
+  // narrowing at the wire edge (an ok response without `debug` classifies as
+  // permanent/malformed_response in the transport).
+  return requestOutcome({ kind: "debug", what }, BUDGETS, (resp) =>
+    "debug" in resp ? resp.debug : undefined,
+  );
+}
+
+// [LAW:types-are-the-program] One total fold over the DebugSnapshot union; each
+// arm renders its own shape. The switch is exhaustive (the `never` default makes
+// a new `what` a compile error here), so the renderer can never fall out of
+// lockstep with the protocol's `what` set — the projection is residue of the
+// union, not a hand-maintained dispatch.
+export function formatDebug(s: DebugSnapshot): string {
+  switch (s.what) {
+    case "vars":
+      return formatVars(s.vars);
+    case "segments":
+      return formatSegments(s.segments);
+    case "config":
+      return formatConfig(s.config);
+    default: {
+      const _exhaustive: never = s;
+      return _exhaustive;
+    }
+  }
+}
+
+function formatVars(vars: readonly VarSnapshot[]): string {
+  if (vars.length === 0) return "no variables (DSL not active)\n";
+  const lines: string[] = [`variables (${vars.length})`, ``];
+  const nameW = vars.reduce((w, v) => Math.max(w, v.name.length), 4);
+  const srcW = vars.reduce((w, v) => Math.max(w, (v.source ?? "—").length), 6);
+  for (const v of vars) {
+    const age = v.ageMs === null ? "" : `  ${fmtAge(v.ageMs)}`;
+    const err = v.lastError ? `  ✗ ${v.lastError.message}` : "";
+    lines.push(
+      `  ${v.name.padEnd(nameW)}  ${(v.source ?? "—").padEnd(srcW)}  ${v.type.padEnd(7)}  ${fmtValue(v.value)}${age}${err}`,
+    );
+  }
+  return lines.join("\n") + "\n";
+}
+
+function formatSegments(segments: readonly SegmentSnapshot[]): string {
+  if (segments.length === 0) return "no segments (DSL not active)\n";
+  const lines: string[] = [`segments (${segments.length})`, ``];
+  for (const seg of segments) {
+    lines.push(`  ${seg.name}`);
+    lines.push(`    template  ${seg.template}`);
+    if (seg.referencedVars.length > 0) {
+      lines.push(`    vars      ${seg.referencedVars.join(", ")}`);
+    }
+    if (seg.lastRender !== null) {
+      lines.push(`    last      ${seg.lastRender}`);
+    }
+  }
+  return lines.join("\n") + "\n";
+}
+
+function formatConfig(config: DslConfig | null): string {
+  if (config === null) return "config: DSL not active\n";
+  return JSON.stringify(config, null, 2) + "\n";
+}
+
+function fmtValue(v: unknown): string {
+  const s = typeof v === "string" ? v : JSON.stringify(v);
+  return s.length > 60 ? s.slice(0, 57) + "…" : s;
+}
+
+function fmtAge(ms: number): string {
+  if (ms < 1000) return `${ms}ms`;
+  if (ms < 60_000) return `${(ms / 1000).toFixed(1)}s`;
+  return `${Math.floor(ms / 60_000)}m`;
+}

package/src/daemon/client-stats.ts

@@ -0,0 +1,129 @@
+import process from "node:process";
+import { describeFailure, requestOutcome } from "./client-transport";
+import type { RoundTripBudgets, RoundTripOutcome } from "./client-transport";
+import type { StatsSnapshot } from "./stats";
+
+// Operator-driven introspection path: legitimately slower budgets than the
+// render hot path, carried as this caller's values through the shared
+// round-trip in ./client-transport. [LAW:dataflow-not-control-flow]
+const BUDGETS: RoundTripBudgets = { connectMs: 200, budgetMs: 500 };
+
+// Query the running daemon for stats. Does NOT spawn a daemon — stats on a
+// dead daemon is meaningless. Exits non-zero on failure with a clear message.
+export async function runDaemonStats(args: readonly string[]): Promise<void> {
+  const wantJson = args.includes("--json");
+
+  const outcome = await fetchStats();
+  if (outcome.kind !== "ok") {
+    process.stderr.write(`daemon-stats: ${describeFailure(outcome)}\n`);
+    process.exit(1);
+  }
+
+  if (wantJson) {
+    process.stdout.write(JSON.stringify(outcome.value, null, 2) + "\n");
+    return;
+  }
+
+  process.stdout.write(formatStats(outcome.value));
+}
+
+function fetchStats(): Promise<RoundTripOutcome<StatsSnapshot>> {
+  // [LAW:no-defensive-null-guards] exception: trust boundary. The response is
+  // an unchecked cast from socket JSON; the presence check is the explicit
+  // narrowing at the wire edge (an ok response without `stats` classifies as
+  // permanent/malformed_response in the transport).
+  return requestOutcome({ kind: "stats" }, BUDGETS, (resp) =>
+    "stats" in resp ? resp.stats : undefined,
+  );
+}
+
+function fmtBytes(n: number): string {
+  if (n < 1024) return `${n}B`;
+  if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)}KB`;
+  return `${(n / 1024 / 1024).toFixed(1)}MB`;
+}
+
+function fmtRate(hits: number, misses: number): string {
+  const total = hits + misses;
+  if (total === 0) return "n/a";
+  return `${((hits / total) * 100).toFixed(1)}%`;
+}
+
+function fmtUptime(sec: number): string {
+  if (sec < 60) return `${sec}s`;
+  if (sec < 3600) return `${Math.floor(sec / 60)}m${sec % 60}s`;
+  const h = Math.floor(sec / 3600);
+  const m = Math.floor((sec % 3600) / 60);
+  return `${h}h${m}m`;
+}
+
+export function formatStats(s: StatsSnapshot): string {
+  const lines: string[] = [];
+  lines.push(`cc-candybar daemon stats`);
+  lines.push(``);
+  lines.push(`process`);
+  lines.push(`  pid           ${s.pid}`);
+  lines.push(`  version       ${s.version}`);
+  lines.push(`  startedAt     ${s.startedAt}`);
+  lines.push(`  uptime        ${fmtUptime(s.uptimeSec)}`);
+  lines.push(`  rss           ${fmtBytes(s.rssBytes)}`);
+  lines.push(`  heapUsed      ${fmtBytes(s.heapUsedBytes)}`);
+  lines.push(`  heapTotal     ${fmtBytes(s.heapTotalBytes)}`);
+  lines.push(`  external      ${fmtBytes(s.externalBytes)}`);
+  lines.push(`  arrayBuffers  ${fmtBytes(s.arrayBuffersBytes)}`);
+  lines.push(``);
+  lines.push(`requests`);
+  lines.push(`  total         ${s.requests.total}`);
+  lines.push(`  errored       ${s.requests.errored}`);
+  lines.push(`  timedOut      ${s.requests.timedOut}`);
+  lines.push(`  inFlight      ${s.requests.inFlight}`);
+  lines.push(``);
+  lines.push(`gitCache`);
+  lines.push(`  size          ${s.gitCache.size}`);
+  lines.push(
+    `  hit rate      ${fmtRate(s.gitCache.hits, s.gitCache.misses)} (${s.gitCache.hits} / ${s.gitCache.hits + s.gitCache.misses})`,
+  );
+  lines.push(`  invalidations ${s.gitCache.invalidations}`);
+  lines.push(``);
+  lines.push(`usageCache`);
+  lines.push(`  size          ${s.usageCache.size}`);
+  lines.push(
+    `  hit rate      ${fmtRate(s.usageCache.hits, s.usageCache.misses)} (${s.usageCache.hits} / ${s.usageCache.hits + s.usageCache.misses})`,
+  );
+  lines.push(`  sweeps        ${s.usageCache.sweeps}`);
+  lines.push(``);
+  lines.push(`renderCache`);
+  lines.push(`  size          ${s.renderCache.size}`);
+  lines.push(`watchers`);
+  lines.push(`  active        ${s.watchers.active}`);
+  lines.push(`  opened        ${s.watchers.opened}`);
+  lines.push(`  closed        ${s.watchers.closed}`);
+  lines.push(`  evicted       ${s.watchers.evicted}`);
+  lines.push(``);
+  lines.push(`subprocesses`);
+  lines.push(`  total         ${s.subprocesses.total}`);
+  lines.push(`  inFlight      ${s.subprocesses.inFlight}`);
+  lines.push(`  lastMinute    ${s.subprocesses.lastMinute}`);
+  // Snapshot already includes only executed categories (stats.ts:
+  // snapshotSubprocesses keeps byCategory and the histograms symmetric).
+  const activeCats = Object.entries(s.subprocesses.byCategory);
+  // [LAW:dataflow-not-control-flow] Column width is a function of the data,
+  // not a hardcoded constant that drifts when new categories are added. The
+  // padEnd(13) baseline matches the "  pid           " etc. columns above so
+  // short categories still line up; longer ones expand the column.
+  const colWidth = activeCats.reduce((w, [cat]) => Math.max(w, cat.length), 13);
+  for (const [cat, n] of activeCats) {
+    const p50 = s.subprocesses.p50DurationMs[cat];
+    const p99 = s.subprocesses.p99DurationMs[cat];
+    const timing =
+      p50 !== undefined && p99 !== undefined
+        ? `  (p50 ${p50}ms · p99 ${p99}ms)`
+        : "";
+    lines.push(`  ${cat.padEnd(colWidth)} ${n}${timing}`);
+  }
+  if (s.nextRestartReason) {
+    lines.push(``);
+    lines.push(`nextRestart    ${s.nextRestartReason}`);
+  }
+  return lines.join("\n") + "\n";
+}

package/src/daemon/client-transport.ts

@@ -0,0 +1,273 @@
+// The single client-side daemon socket round-trip: connect with a timeout,
+// send one framed request, await one framed response, always destroy the
+// socket, and classify every failure into the transient/permanent split.
+//
+// [LAW:one-type-per-behavior] This round-trip used to be implemented three
+// times (render/click in client.ts, stats in client-stats.ts, debug in
+// client-debug.ts), differing only in timeout values and which payload field
+// the caller wanted — configuration, not behavior. Callers now pass their
+// budgets and payload projector as VALUES through this one boundary; the
+// stats/debug paths inherited classification fixes (post-2l6) they had
+// silently drifted away from. [LAW:dataflow-not-control-flow] There is no
+// caller-identity flag here — a new caller is a new argument set, not a new
+// branch.
+
+import net from "node:net";
+import { socketPath } from "./paths";
+import { PROTOCOL_VERSION, ProtocolError, sendOne } from "./protocol";
+import type { Request, Response } from "./protocol";
+
+// Per-caller timeout policy, carried as data. The render hot path runs tight
+// budgets (a statusline refresh must not stall the host); operator-driven
+// CLIs (stats/debug) legitimately afford slower ones.
+export interface RoundTripBudgets {
+  readonly connectMs: number;
+  readonly budgetMs: number;
+}
+
+// [LAW:types-are-the-program] The outcome carries its own recovery
+// semantics. `transient` failures mean the daemon was unavailable/slow —
+// kicking a fresh daemon is the right response. `permanent` failures mean
+// the daemon refused our request semantically — kicking does NOT help
+// because the next daemon will refuse the same request the same way. The
+// caller's branch is no longer uniform: it matches on `kind` and routes
+// kick vs. show-error off the type, not off a stringified `reason`. This
+// asymmetry was missing in the previous shape and is the root of the
+// 452-corpse spiral (kz8.5).
+export type RoundTripOutcome<T> = { kind: "ok"; value: T } | FailureOutcome;
+
+export type FailureOutcome = TransientOutcome | PermanentOutcome;
+
+export interface TransientOutcome {
+  kind: "transient";
+  cause: "unreachable" | "timeout" | "io_error";
+  message: string;
+}
+
+export type PermanentOutcome =
+  | {
+      kind: "permanent";
+      cause: "version_mismatch";
+      clientV: number;
+      daemonV: number;
+    }
+  | { kind: "permanent"; cause: "bad_request"; message: string }
+  | { kind: "permanent"; cause: "render_failed"; message: string }
+  | { kind: "permanent"; cause: "malformed_response"; message: string };
+
+// [LAW:single-enforcer] The protocol version is stamped here, on every
+// outbound request — a caller cannot mis-stamp or omit it.
+type Unversioned<R> = R extends { v: number } ? Omit<R, "v"> : never;
+export type UnversionedRequest = Unversioned<Request>;
+
+type OkResponse = Extract<Response, { ok: true }>;
+
+// One round-trip, classified. `project` extracts the caller's payload from
+// an ok response and returns undefined when the response, though ok, does
+// not carry the expected shape (the daemon is up, it just answered the
+// wrong question) — that maps to permanent/malformed_response, not a kick.
+// The payload types themselves never enter this module [LAW:one-way-deps].
+export async function requestOutcome<T>(
+  req: UnversionedRequest,
+  budgets: RoundTripBudgets,
+  project: (resp: OkResponse) => T | undefined,
+): Promise<RoundTripOutcome<T>> {
+  let sock: net.Socket | null = null;
+  try {
+    sock = await connectWithTimeout(socketPath(), budgets.connectMs);
+    const resp: Response = await sendOne(
+      sock,
+      { v: PROTOCOL_VERSION, ...req },
+      budgets.budgetMs,
+    );
+    return interpretResponse(req.kind, resp, project);
+  } catch (e) {
+    return interpretException(e);
+  } finally {
+    if (sock) sock.destroy();
+  }
+}
+
+// [LAW:types-are-the-program] One place that turns a wire-level Response
+// into a typed Outcome. Every daemon client goes through this, so the
+// kick-vs-show-error decision has a single source of truth.
+//
+// [LAW:no-defensive-null-guards] This function sits AT the trust boundary —
+// `resp` is `frame as Response`, an unchecked cast from socket JSON. The
+// per-field type-narrowings and the default branch below are not defensive
+// guards against an internal bug; they are the explicit handling at the
+// wire edge for fields whose runtime types the JSON cast cannot enforce.
+// Every untrusted access flows through asString/asProtocolVersion so the
+// downstream Outcome shape carries values of the declared types only.
+
+// [LAW:single-enforcer] Narrowing primitives used everywhere we read a
+// field off the cast `resp`. Centralised so a future "validate the whole
+// frame" approach has one place to evolve from. Each helper expresses an
+// exact type predicate; mixing semantics (e.g. "any finite number" with
+// "non-negative integer") would weaken the type [LAW:types-are-the-program].
+function asString(v: unknown, fallback: string): string {
+  return typeof v === "string" ? v : fallback;
+}
+
+// [LAW:one-type-per-behavior] Mirrors the Rust client's `as_u64()` semantics:
+// the only valid daemonV values are non-negative integers. Negatives and
+// fractional values fall back to 0 so both runtimes derive the same
+// PermanentOutcome from the same wire payload.
+function asProtocolVersion(v: unknown): number {
+  return typeof v === "number" && Number.isInteger(v) && v >= 0 ? v : 0;
+}
+
+function interpretResponse<T>(
+  kind: Request["kind"],
+  resp: Response,
+  project: (resp: OkResponse) => T | undefined,
+): RoundTripOutcome<T> {
+  // Treat the cast `resp` as a bag of unknowns; each access is narrowed
+  // explicitly. The typed parameter still documents the *expected* shape
+  // for readers, but the runtime trusts only what it can verify per field.
+  const raw = resp as {
+    ok?: unknown;
+    error?: unknown;
+    code?: unknown;
+    daemonV?: unknown;
+  };
+  if (raw.ok === true) {
+    const value = project(resp as OkResponse);
+    if (value !== undefined) {
+      return { kind: "ok", value };
+    }
+    // Ok response without the payload this request asked for — not our
+    // shape. Treat as a permanent malformed-response so the caller does NOT
+    // kick (the daemon is up, just answered the wrong question).
+    return {
+      kind: "permanent",
+      cause: "malformed_response",
+      message: `ok response without payload for "${kind}" request`,
+    };
+  }
+  const errorMessage = asString(raw.error, "(no error message)");
+  switch (raw.code) {
+    case "VERSION_MISMATCH":
+      return {
+        kind: "permanent",
+        cause: "version_mismatch",
+        clientV: PROTOCOL_VERSION,
+        // Older daemons may not echo daemonV; non-number values from a
+        // misbehaving stub also fall back to 0 (the renderer maps 0 to
+        // "unknown" in the visible glyph).
+        daemonV: asProtocolVersion(raw.daemonV),
+      };
+    case "TIMEOUT":
+      // Daemon is alive but didn't answer in time — same recovery as
+      // unreachable: kick and emit stale/blank. This is the *only* non-ok
+      // wire code that maps to transient.
+      return { kind: "transient", cause: "timeout", message: errorMessage };
+    case "BAD_REQUEST":
+      return { kind: "permanent", cause: "bad_request", message: errorMessage };
+    case "RENDER_FAILED":
+      return {
+        kind: "permanent",
+        cause: "render_failed",
+        message: errorMessage,
+      };
+    default:
+      // Unknown wire code — mirrors rust-client's `_ => MalformedResponse(...)`
+      // so both runtimes converge on the same observable behavior for any
+      // code the client doesn't recognize. String() handles missing /
+      // non-string values without crashing.
+      return {
+        kind: "permanent",
+        cause: "malformed_response",
+        message: `unknown error code: ${String(raw.code)}`,
+      };
+  }
+}
+
+// Exceptions reaching this function come from two distinct classes:
+//   - Connect/IO/timeout failures — transient. A respawn or retry has a
+//     real chance of recovering (daemon dead, socket vanished, slow link).
+//   - Protocol violations from sendOne's reject path — permanent. The
+//     daemon is alive but produced garbage (oversized frame, JSON parse
+//     failure). Respawning would hit the same response identically; this
+//     is the same recovery class as a wire-level VERSION_MISMATCH, so we
+//     route through PermanentCause::MalformedResponse and the user sees
+//     a glyph naming the failure rather than a blank line plus a kick.
+//
+// [LAW:types-are-the-program] The protocol-violation discriminator is
+// carried structurally by `ProtocolError` (exported from protocol.ts) —
+// not by substring-matching the error message, which would silently drift
+// if Node's JSON.parse wording changes across versions/locales. The
+// `e instanceof SyntaxError` fallback covers a residual case where a
+// JSON.parse happened to escape `makeFrameReader`'s wrapping (defense in
+// depth, not the primary path).
+//
+// [LAW:one-type-per-behavior] Mirrors rust-client's classify_io_error —
+// InvalidData/InvalidInput map to Permanent(MalformedResponse), everything
+// else stays transient. The two runtimes agree on the recovery class for
+// every observable wire failure.
+function interpretException(e: unknown): FailureOutcome {
+  if (e instanceof ProtocolError || e instanceof SyntaxError) {
+    const message = e instanceof Error ? e.message : String(e);
+    return { kind: "permanent", cause: "malformed_response", message };
+  }
+  const message = e instanceof Error ? e.message : String(e);
+  if (message === "CONNECT_TIMEOUT" || message === "TIMEOUT") {
+    return { kind: "transient", cause: "timeout", message };
+  }
+  if (
+    message.includes("ECONNREFUSED") ||
+    message.includes("ENOENT") ||
+    message.includes("ENOTSOCK")
+  ) {
+    return { kind: "transient", cause: "unreachable", message };
+  }
+  return { kind: "transient", cause: "io_error", message };
+}
+
+function connectWithTimeout(
+  path: string,
+  timeoutMs: number,
+): Promise<net.Socket> {
+  return new Promise((resolve, reject) => {
+    const sock = net.createConnection({ path });
+    const timer = setTimeout(() => {
+      sock.destroy();
+      reject(new Error("CONNECT_TIMEOUT"));
+    }, timeoutMs);
+    sock.once("connect", () => {
+      clearTimeout(timer);
+      resolve(sock);
+    });
+    sock.once("error", (err) => {
+      clearTimeout(timer);
+      reject(err);
+    });
+  });
+}
+
+// [LAW:single-enforcer] One plain-text rendering of a failed outcome for
+// operator-facing CLIs (daemon-stats, vars/segments/config). The statusline
+// glyph (src/render/error-glyph.ts) and the url-handle formatter
+// (src/install/index.ts) are deliberately separate presentations with their
+// own contracts (ANSI styling and Rust-parity truncation; per-cause click
+// diagnostics). The spawn hint appears only on transient failures — on a
+// permanent failure the daemon is demonstrably running, and suggesting a
+// respawn would send the operator down the wrong path.
+export function describeFailure(outcome: FailureOutcome): string {
+  if (outcome.kind === "transient") {
+    return (
+      `daemon unavailable (${outcome.cause}: ${outcome.message})\n` +
+      "Hint: daemon may not be running. Run `cc-candybar` once to spawn it."
+    );
+  }
+  switch (outcome.cause) {
+    case "version_mismatch": {
+      const daemon = outcome.daemonV === 0 ? "unknown" : `v${outcome.daemonV}`;
+      return `daemon protocol mismatch (client v${outcome.clientV} ≠ daemon ${daemon})`;
+    }
+    case "bad_request":
+    case "render_failed":
+    case "malformed_response":
+      return `daemon error (${outcome.cause}): ${outcome.message}`;
+  }
+}

package/src/daemon/client.ts

@@ -0,0 +1,75 @@
+// The render/click client — the statusline hot path. The socket round-trip
+// and failure classification live in ./client-transport (the single
+// implementation shared with the stats/debug CLIs); this module contributes
+// only the render path's own data: tight timeout budgets and the
+// output-string payload projection. [LAW:dataflow-not-control-flow]
+//
+// [LAW:one-source-of-truth] These budget consts are mirrored by the Rust
+// client (rust-client/src/main.rs) and diffed by scripts/check-protocol.mjs,
+// which anchors on the declarations below — keep them named consts in this
+// file, or repoint the CHECKS rows in the same commit.
+
+import type { ClaudeHookData } from "../utils/claude";
+import { requestOutcome } from "./client-transport";
+import type { RoundTripBudgets, RoundTripOutcome } from "./client-transport";
+import type { Response } from "./protocol";
+
+const CONNECT_TIMEOUT_MS = 50;
+const TOTAL_BUDGET_MS = 150;
+const CLICK_BUDGET_MS = 200;
+
+const RENDER_BUDGETS: RoundTripBudgets = {
+  connectMs: CONNECT_TIMEOUT_MS,
+  budgetMs: TOTAL_BUDGET_MS,
+};
+const CLICK_BUDGETS: RoundTripBudgets = {
+  connectMs: CONNECT_TIMEOUT_MS,
+  budgetMs: CLICK_BUDGET_MS,
+};
+
+// The render/click outcome vocabulary, mirrored by the Rust client's outcome
+// enum. The ok payload is the rendered line (or click acknowledgement) to
+// print. See client-transport.ts for the transient/permanent semantics.
+export type ClientOutcome = RoundTripOutcome<string>;
+
+// [LAW:no-defensive-null-guards] exception: trust boundary. The ok response
+// is an unchecked cast from socket JSON; the typeof check is the explicit
+// narrowing at the wire edge, and its failure means "ok response without our
+// payload" (classified permanent/malformed_response by the transport).
+function projectOutput(
+  resp: Extract<Response, { ok: true }>,
+): string | undefined {
+  const output = (resp as { output?: unknown }).output;
+  return typeof output === "string" ? output : undefined;
+}
+
+// Try to render via the daemon. Returns a typed outcome — see ClientOutcome.
+// 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.
+export function tryRenderViaDaemon(
+  hookData: ClaudeHookData,
+  args: string[],
+  cwd: string,
+  termCols?: number,
+): Promise<ClientOutcome> {
+  return requestOutcome(
+    { kind: "render", hookData, args, cwd, termCols },
+    RENDER_BUDGETS,
+    projectOutput,
+  );
+}
+
+// [LAW:single-enforcer] Same outcome translator for click as for render —
+// click failures decompose into the same transient/permanent split, so the
+// caller's "ok? done : kick + fallback" logic gets the same typed input.
+export function tryClickViaDaemon(
+  verb: string,
+  value: string,
+): Promise<ClientOutcome> {
+  return requestOutcome(
+    { kind: "click", verb, value },
+    CLICK_BUDGETS,
+    projectOutput,
+  );
+}