@geraldmaron/construct 1.2.2 → 1.3.0

package/lib/specialists/schema.mjs

@@ -1,5 +1,5 @@
 /**
- * lib/specialists/schema.mjs — validation contract for specialists/registry.json entries.
+ * lib/specialists/schema.mjs — validation contract for specialists/org entries.
  *
  * Catches drift before it ships: missing description, unknown tool names,
  * promptFile pointing at a path that does not resolve, unrecognized
@@ -23,7 +23,7 @@ export const ALLOWED_TOOLS = new Set([
   'WebSearch', 'WebFetch', 'TodoWrite', 'NotebookEdit', 'Task',
   // Construct MCP tools (from construct-mcp server)
   'list_skills', 'get_skill', 'search_skills',
-  'list_teams', 'get_team',
+  'list_teams', 'suggest_skills',
   'list_templates', 'get_template',
   'agent_contract', 'orchestration_policy',
   'cx_trace', 'cx_score',
@@ -90,13 +90,16 @@ export function validateAgentRecord(record, { rootDir, registryKey } = {}) {
  * Validate every agent in a registry. Returns { errors: string[], agentCount }.
  */
 export function validateRegistry(registry, { rootDir } = {}) {
-  if (!registry || !Array.isArray(registry.specialists)) {
+  if (!registry) {
     return { errors: ['registry.specialists is missing or not an array'], agentCount: 0 };
   }
+  const specialists = Array.isArray(registry.specialists)
+    ? registry.specialists
+    : Object.values(registry.specialists || {});
   const errors = [];
   const seenNames = new Set();
-  for (let i = 0; i < registry.specialists.length; i += 1) {
-    const record = registry.specialists[i];
+  for (let i = 0; i < specialists.length; i += 1) {
+    const record = specialists[i];
     const recordErrors = validateAgentRecord(record, { rootDir, registryKey: i });
     errors.push(...recordErrors);
     if (record?.name) {
@@ -104,7 +107,7 @@ export function validateRegistry(registry, { rootDir } = {}) {
       seenNames.add(record.name);
     }
   }
-  return { errors, agentCount: registry.specialists.length };
+  return { errors, agentCount: specialists.length };
 }
 
 /**

package/lib/status.mjs

@@ -1,11 +1,12 @@
 /**
- * lib/status.mjs — Project health summary for the Construct dashboard and CLI.
+ * lib/status.mjs — Project health summary for the Construct CLI.
  *
  * Reads workflow state, plan.md, tracker config, and MCP surface to produce a
  * structured health object. Called by `construct status`, the MCP status tool,
  * and the session-start bootstrap to surface blocked tasks and open questions.
  */
 import { readFileSync, statSync, existsSync, readdirSync } from 'node:fs';
+import { loadRegistry } from './registry/loader.mjs';
 import { join, dirname } from 'node:path';
 import { homedir } from 'node:os';
 import { fileURLToPath } from 'node:url';
@@ -23,6 +24,8 @@ import { readEfficiencyLog, summarizeEfficiencyData } from './efficiency.mjs';
 import { triggerAutoBackfillIfSparse } from './telemetry/backfill.mjs';
 import { resolveTraceBackend, telemetryProviderLabel } from './telemetry/client.mjs';
 import { doctorRoot } from './config/xdg.mjs';
+import { resolveUiColors } from './ui/theme.mjs';
+import { applyLinks, terminalLinksEnabled } from './ui/links.mjs';
 const TOTAL_BYTES_WARNING_THRESHOLD = 750_000;
 
 function readJSON(path) {
@@ -250,9 +253,9 @@ function parsePort(value, fallback) {
 }
 
 async function probeHttp(url, { method = 'GET', headers, body, timeout = 5000 } = {}) {
-  // 5s is generous on purpose. The dashboard runs many concurrent requests when
-  // a page first loads (status + insights + registry + auth + …), which can stall
-  // its own event loop just long enough that a 2s timeout fires on a healthy
+  // 5s is generous on purpose. A local service can batch many concurrent requests
+  // at startup, which can stall its own event loop just long enough that a 2s
+  // timeout fires on a healthy
   // localhost service. Reachability is a yes/no signal — a hung remote dies
   // visibly via ECONNREFUSED long before this, so the extra headroom is free.
   const controller = new AbortController();
@@ -539,89 +542,11 @@ function traceBackendDefinition(env) {
   };
 }
 
-/**
- * In-process self-check for when Construct is serving its own dashboard.
- * Rather than skipping the probe and asserting "healthy", we actually measure
- * the process state and surface real problems.
- *
- * Checks:
- *   - Heap usage — warn at 80%, critical at 95%
- *   - Process uptime — surface as context
- *   - Embed daemon — read state file and report if stale or crashed
- *
- * Returns { status: 'healthy'|'degraded'|'unavailable', message: string }
- */
-function buildSelfCheck() {
-  const problems = [];
-  const notes = [];
-
-  // Memory
-  try {
-    const mem = process.memoryUsage();
-    const heapPct = mem.heapUsed / mem.heapTotal;
-    if (heapPct >= 0.95) {
-      problems.push(`heap ${Math.round(heapPct * 100)}% (critical)`);
-    } else if (heapPct >= 0.80) {
-      problems.push(`heap ${Math.round(heapPct * 100)}% (high)`);
-    } else {
-      notes.push(`heap ${Math.round(heapPct * 100)}%`);
-    }
-  } catch { /* non-fatal */ }
-
-  // Uptime
-  try {
-    const uptimeSec = process.uptime();
-    const h = Math.floor(uptimeSec / 3600);
-    const m = Math.floor((uptimeSec % 3600) / 60);
-    notes.push(`up ${h}h${m}m`);
-  } catch { /* non-fatal */ }
-
-  // Embed daemon state
-  try {
-    const stateFile = join(doctorRoot(), 'runtime', 'embed-daemon.json');
-    if (existsSync(stateFile)) {
-      const state = JSON.parse(readFileSync(stateFile, 'utf8'));
-      if (state.status === 'running' && state.pid) {
-        // Verify the PID is actually alive
-        try {
-          process.kill(state.pid, 0);
-          notes.push(`embed daemon pid ${state.pid}`);
-        } catch {
-          problems.push(`embed daemon pid ${state.pid} is not running (state file stale)`);
-        }
-      } else if (state.status === 'stopped') {
-        notes.push('embed daemon stopped');
-      }
-    }
-  } catch { /* non-fatal */ }
-
-  if (problems.length) {
-    return {
-      status: problems.some(p => p.includes('critical')) ? 'unavailable' : 'degraded',
-      message: problems.join('; ') + (notes.length ? ` — ${notes.join(', ')}` : ''),
-    };
-  }
-
-  return {
-    status: 'healthy',
-    message: ['Serving status API', ...notes].join(' — '),
-  };
-}
-
-function serviceDefinitions(env, dashboardPort, selfDashboard) {
+function serviceDefinitions(env) {
   const memoryPort = parsePort(env.MEMORY_PORT, 8765);
   const bridgePort = parsePort(env.BRIDGE_PORT, 5173);
 
   return [
-    {
-      id: 'dashboard',
-      name: 'Dashboard',
-      url: `http://127.0.0.1:${dashboardPort}`,
-      runtime: 'live',
-      note: selfDashboard ? 'Current process' : 'Dashboard API',
-      healthyMessage: selfDashboard ? 'Serving status API' : 'Reachable',
-      selfCheck: selfDashboard ? buildSelfCheck() : null,
-    },
     traceBackendDefinition(env),
     {
       id: 'memory',
@@ -652,23 +577,25 @@ export async function buildStatus({
   cwd = process.cwd(),
   homeDir = homedir(),
   env = process.env,
-  dashboardPort,
-  selfDashboard = false,
   probeService = defaultProbeService,
 } = {}) {
   if (!rootDir) throw new Error('rootDir is required');
 
   const mergedEnv = loadConstructEnv({ rootDir, homeDir, env });
-  const resolvedDashboardPort = parsePort(dashboardPort ?? mergedEnv.DASHBOARD_PORT, 4242);
 
   const pkg = readJSON(join(rootDir, 'package.json')) ?? {};
-  const registry = readJSON(join(rootDir, 'specialists', 'registry.json')) ?? {};
+  let registry;
+  try {
+    registry = loadRegistry({ rootDir });
+  } catch {
+    registry = { teams: {}, specialists: {}, contracts: {}, policies: {} };
+  }
   const settings = readJSON(join(homeDir, '.claude', 'settings.json')) ?? {};
   const features = await checkAllFeatures({ homeDir, cwd, env: mergedEnv });
   const pluginRegistry = loadPluginRegistry({ cwd, homeDir, rootDir, env: mergedEnv });
   const services = [];
 
-  for (const definition of serviceDefinitions(mergedEnv, resolvedDashboardPort, selfDashboard)) {
+  for (const definition of serviceDefinitions(mergedEnv)) {
     if (definition.selfCheck) {
       const check = definition.selfCheck;
       services.push({
@@ -734,7 +661,7 @@ export async function buildStatus({
     : null;
 
   const prefix = `${registry.prefix ?? 'cx'}-`;
-  const specialists = (registry.specialists ?? []).map((specialist) => ({
+  const specialists = Object.values(registry.specialists ?? {}).map((specialist) => ({
     name: `${prefix}${specialist.name}`,
     description: specialist.description ?? '',
     modelTier: specialist.modelTier ?? 'standard',
@@ -922,7 +849,15 @@ export function formatStatusReport(status) {
       lines.push(`  ${serviceIcon('degraded')} manifest error — ${error}`);
     }
   }
-  return `${lines.join('\n')}\n`;
+
+  // Service URLs and repo paths become Cmd-clickable on an interactive stream; on
+  // a pipe or in CI links resolve off and colors are empty, so the report stays
+  // byte-identical for machine consumers and tests.
+
+  const colors = resolveUiColors();
+  const enabled = terminalLinksEnabled(process.env, { stream: process.stdout });
+  const rendered = lines.map((line) => applyLinks(line, colors, { enabled })).join('\n');
+  return `${rendered}\n`;
 }
 
 export async function printStatus(options = {}) {

package/lib/storage/file-lock.mjs

@@ -31,6 +31,7 @@ const LOCK_TIMEOUT_MS = 5_000;
 const POLL_INTERVAL_MS = 50;
 
 const heldLocks = new Set();
+const SLEEP_ARRAY = new Int32Array(new SharedArrayBuffer(4));
 
 function isHolderAlive(holderPid) {
   if (!holderPid || !Number.isFinite(holderPid)) return false;
@@ -77,6 +78,10 @@ function release(lockPath) {
   heldLocks.delete(lockPath);
 }
 
+function sleepSync(ms) {
+  Atomics.wait(SLEEP_ARRAY, 0, 0, ms);
+}
+
 let exitHandlerInstalled = false;
 function installExitHandler() {
   if (exitHandlerInstalled) return;
@@ -124,9 +129,7 @@ export function withFileLockSync(filePath, fn) {
 
   while (!tryAcquire(lockPath)) {
     if (Date.now() >= deadline) break;
-    // Crude sleep — node has no native sync sleep, so we busy-wait briefly.
-    const stop = Date.now() + POLL_INTERVAL_MS;
-    while (Date.now() < stop) { /* spin */ }
+    sleepSync(POLL_INTERVAL_MS);
   }
 
   try {

package/lib/telemetry/skill-calls.mjs

@@ -31,7 +31,7 @@ export const DEFAULT_LOG_PATH = path.join(doctorRoot(), 'skill-calls.jsonl');
  * Fire-and-forget log of a skill load event.
  *
  * @param {object} event
- * @param {string} event.skillId — path-relative-to-skills/ without the .md, e.g. "roles/engineer.platform"
+ * @param {string} event.skillId — path-relative-to-skills/ without the .md, e.g. "roles/platform-engineer"
  * @param {'mcp'|'prompt-composer'|'role-preload'|'validation'|'other'} event.source
  * @param {string} [event.callerContext] — optional free-form context (agent name, MCP client id, etc.)
  * @param {object} [opts]

package/lib/templates/doc-presentation.mjs

@@ -0,0 +1,63 @@
+/**
+ * lib/templates/doc-presentation.mjs — Presentation lint for Construct artifacts.
+ *
+ * Complements lintDocStructure with spacing, bullet walls, heading hierarchy,
+ * and diagram heuristics aligned with skills/brand/output-vibe.md.
+ */
+import { readFileSync } from 'node:fs';
+
+export function lintDocPresentation(body, { type } = {}) {
+  const errors = [];
+  const warnings = [];
+  const lines = body.split(/\r?\n/);
+
+  const h1Count = (body.match(/^#\s+/gm) || []).length;
+  if (h1Count > 1) errors.push('multiple H1 headings (use single title)');
+
+  let consecutiveBullets = 0;
+  let maxConsecutiveBullets = 0;
+  for (const line of lines) {
+    if (/^\s*[-*]\s+/.test(line)) {
+      consecutiveBullets++;
+      maxConsecutiveBullets = Math.max(maxConsecutiveBullets, consecutiveBullets);
+    } else if (line.trim() !== '') {
+      consecutiveBullets = 0;
+    }
+  }
+  if (maxConsecutiveBullets > 7) {
+    errors.push(`bullet wall: ${maxConsecutiveBullets} consecutive bullets (max 7 without prose bridge)`);
+  }
+
+  if (/\n{4,}/.test(body)) {
+    warnings.push('more than three consecutive blank lines');
+  }
+
+  for (let i = 0; i < lines.length; i++) {
+    if (/^##\s+/.test(lines[i]) && i > 0 && lines[i - 1].trim() !== '') {
+      errors.push(`missing blank line before heading: ${lines[i].trim()}`);
+      break;
+    }
+  }
+
+  if (/```mermaid[\s\S]*?flowchart/i.test(body)) {
+    if (!/error|fail|rollback|escalat/i.test(body)) {
+      warnings.push('flowchart may lack error/rollback path (output-vibe expects one non-happy path)');
+    }
+  }
+
+  if (/!\[[^\]]*\]\([^)]+\)/.test(body)) {
+    if (/!\[\s*\]\(/.test(body)) errors.push('image missing alt text');
+  }
+
+  if (type?.startsWith('prd') && !/\bFR-\d/i.test(body) && !/^## Requirements/m.test(body)) {
+    warnings.push('prd-family: consider FR-* or ## Requirements section');
+  }
+
+  return { errors, warnings };
+}
+
+export function lintDocPresentationFile(filePath, type) {
+  const raw = readFileSync(filePath, 'utf8');
+  const body = raw.replace(/^---\n[\s\S]*?\n---\n/, '');
+  return lintDocPresentation(body, { type });
+}

package/lib/templates/visual-requirements.mjs

@@ -6,6 +6,7 @@
  * Paired with docs/guides/concepts/doc-visual-matrix.md; pinned by template tests.
  */
 
+import { readFileSync } from 'node:fs';
 import { validateArtifactPostconditions } from '../contracts/validate.mjs';
 import {
   structureRequirementsFromManifest,
@@ -42,6 +43,31 @@ export function resolveTemplatePath(type, rootDir) {
   return `templates/docs/${type}.md`;
 }
 
+function hasMarkdownHeading(body, titles) {
+  const targets = new Set(titles.map((title) => title.trim().toLowerCase()));
+  const headingRe = /^#{1,6}\s+(.+)$/gm;
+  let match;
+  while ((match = headingRe.exec(body))) {
+    if (targets.has(match[1].trim().toLowerCase())) return true;
+  }
+  return false;
+}
+
+export function lintPrdDeliveryDepth(body) {
+  const errors = [];
+  const hasRequirements = hasMarkdownHeading(body, ['Requirements', 'Functional requirements'])
+    || /\*\*FR-\d+\.\d+\*\*:|\bFR-\d+\.\d+:/.test(body);
+  if (!hasRequirements) {
+    errors.push('prd missing functional requirements (## Requirements or FR-* entries)');
+  }
+  const hasAcceptance = hasMarkdownHeading(body, ['Acceptance criteria', 'Acceptance'])
+    || /\*Acceptance(\*:|:\*)|\*\*Acceptance\*\*:/i.test(body);
+  if (!hasAcceptance) {
+    errors.push('prd missing acceptance criteria (## Acceptance criteria or *Acceptance* / *Acceptance:* markers)');
+  }
+  return errors;
+}
+
 export function lintDocStructure(filePath, type) {
   const sectionChecks = (STRUCTURE_REQUIREMENTS[type] || []).map((section) => ({
     id: `${type}-section-${section}`,
@@ -49,8 +75,15 @@ export function lintDocStructure(filePath, type) {
     section,
   }));
   const postconditions = [...sectionChecks, ...(VISUAL_REQUIREMENTS[type] || [])];
-  if (postconditions.length === 0) return [];
-  return validateArtifactPostconditions({ contract: { postconditions }, artifactPath: filePath });
+  let errors = postconditions.length === 0
+    ? []
+    : validateArtifactPostconditions({ contract: { postconditions }, artifactPath: filePath });
+  if (type === 'prd') {
+    const raw = readFileSync(filePath, 'utf8');
+    const body = raw.replace(/^---\n[\s\S]*?\n---\n/, '');
+    errors = [...errors, ...lintPrdDeliveryDepth(body)];
+  }
+  return errors;
 }
 
 export function lintDocVisuals(filePath, type) {

package/lib/term-format.mjs

@@ -9,12 +9,15 @@
  */
 
 const ESC = "[";
+const ANSI_TOKEN_RE = /\x1b\[[0-9;?]*[ -\/]*[@-~]|\x1b\]8;;.*?(?:\x07|\x1b\\)/gs;
 
 const CODES = { bold: "1", dim: "2", reset: "0", red: "31", green: "32", yellow: "33", cyan: "36" };
 
 const PALETTE_KEYS = Object.keys(CODES);
 
 const EMPTY_PALETTE = Object.freeze(Object.fromEntries(PALETTE_KEYS.map((k) => [k, ""])));
+const GRAPHEME_SEGMENTER = globalThis.Intl?.Segmenter ? new Intl.Segmenter(undefined, { granularity: "grapheme" }) : null;
+const ZERO_WIDTH_RE = /^(?:\p{Mark}|\p{Control}|\p{Format})$/u;
 
 // Color is opt-in by the caller AND gated on an interactive, color-capable stream. Any
 // NO_COLOR value and TERM=dumb force plain text; a non-TTY stream (pipe, file, CI) does too.
@@ -43,6 +46,108 @@ export function termWidth(stream = process.stdout, { fallback = 80, max = 100 }
   return Math.min(cols, max);
 }
 
+function graphemes(text) {
+  const value = String(text);
+  if (!value) return [];
+  if (!GRAPHEME_SEGMENTER) return [...value];
+  return Array.from(GRAPHEME_SEGMENTER.segment(value), (segment) => segment.segment);
+}
+
+function isFullwidthCodePoint(codePoint) {
+  return codePoint >= 0x1100 && (
+    codePoint <= 0x115f ||
+    codePoint === 0x2329 ||
+    codePoint === 0x232a ||
+    (codePoint >= 0x2e80 && codePoint <= 0xa4cf && codePoint !== 0x303f) ||
+    (codePoint >= 0xac00 && codePoint <= 0xd7a3) ||
+    (codePoint >= 0xf900 && codePoint <= 0xfaff) ||
+    (codePoint >= 0xfe10 && codePoint <= 0xfe19) ||
+    (codePoint >= 0xfe30 && codePoint <= 0xfe6f) ||
+    (codePoint >= 0xff00 && codePoint <= 0xff60) ||
+    (codePoint >= 0xffe0 && codePoint <= 0xffe6) ||
+    (codePoint >= 0x1f300 && codePoint <= 0x1f64f) ||
+    (codePoint >= 0x1f680 && codePoint <= 0x1f6ff) ||
+    (codePoint >= 0x1f900 && codePoint <= 0x1f9ff) ||
+    (codePoint >= 0x20000 && codePoint <= 0x3fffd)
+  );
+}
+
+function graphemeWidth(grapheme) {
+  const value = String(grapheme);
+  if (!value) return 0;
+  if (!GRAPHEME_SEGMENTER && value.length === 1) {
+    const codePoint = value.codePointAt(0);
+    if (codePoint === undefined) return 0;
+    if (ZERO_WIDTH_RE.test(value)) return 0;
+    return isFullwidthCodePoint(codePoint) ? 2 : 1;
+  }
+  if ([...value].every((char) => ZERO_WIDTH_RE.test(char))) return 0;
+  for (const char of value) {
+    const codePoint = char.codePointAt(0);
+    if (codePoint !== undefined && isFullwidthCodePoint(codePoint)) return 2;
+  }
+  return 1;
+}
+
+export function displayWidth(text) {
+  let width = 0;
+  for (const token of graphemes(stripAnsi(text))) width += graphemeWidth(token);
+  return width;
+}
+
+export function clipToWidth(text, width) {
+  const input = String(text);
+  if (width <= 0 || input === "") return "";
+  if (displayWidth(input) <= width) return input;
+
+  const parts = [];
+  let visible = 0;
+  let searchIndex = 0;
+  let sawAnsi = false;
+  let openHyperlink = false;
+
+  for (const match of input.matchAll(ANSI_TOKEN_RE)) {
+    const token = match[0];
+    const index = match.index ?? searchIndex;
+    const chunk = input.slice(searchIndex, index);
+    for (const grapheme of graphemes(chunk)) {
+      const nextWidth = graphemeWidth(grapheme);
+      if (visible + nextWidth > width) {
+        if (sawAnsi) parts.push("\x1b[0m");
+        if (openHyperlink) parts.push("\x1b]8;;\x07");
+        return parts.join("");
+      }
+      parts.push(grapheme);
+      visible += nextWidth;
+    }
+
+    parts.push(token);
+    sawAnsi = true;
+    if (token.startsWith("\x1b]8;;")) openHyperlink = token !== "\x1b]8;;\x07" && token !== "\x1b]8;;\x1b\\";
+    searchIndex = index + token.length;
+  }
+
+  const tail = input.slice(searchIndex);
+  for (const grapheme of graphemes(tail)) {
+    const nextWidth = graphemeWidth(grapheme);
+    if (visible + nextWidth > width) {
+      if (sawAnsi) parts.push("\x1b[0m");
+      if (openHyperlink) parts.push("\x1b]8;;\x07");
+      return parts.join("");
+    }
+    parts.push(grapheme);
+    visible += nextWidth;
+  }
+
+  return parts.join("");
+}
+
+export function padToWidth(text, width) {
+  const input = String(text);
+  const padding = Math.max(0, width - displayWidth(input));
+  return padding ? `${input}${" ".repeat(padding)}` : input;
+}
+
 // Word-wrap one paragraph to width. Existing newlines stay as hard breaks; a single word
 // longer than width is never split — it sits on its own line and overflows rather than
 // becoming two unreadable fragments.
@@ -58,7 +163,7 @@ export function wrapText(text, width = termWidth()) {
     for (const word of hardLine.split(/\s+/)) {
       if (line === "") {
         line = word;
-      } else if (line.length + 1 + word.length <= width) {
+      } else if (displayWidth(line) + 1 + displayWidth(word) <= width) {
         line += ` ${word}`;
       } else {
         out.push(line);
@@ -71,5 +176,5 @@ export function wrapText(text, width = termWidth()) {
 }
 
 export function stripAnsi(text) {
-  return String(text).replace(/\[[0-9;]*m/g, "");
+  return String(text).replace(ANSI_TOKEN_RE, "");
 }

package/lib/test-env-setup.mjs

@@ -0,0 +1,21 @@
+/**
+ * lib/test-env-setup.mjs — Shared test environment setup.
+ *
+ * Centralizes XDG environment clearing for all test runners so the logic
+ * stays in sync across scripts/run-tests.mjs, npm test:functional, and
+ * direct node --test invocations.
+ *
+ * Tests isolate user state by overriding HOME to a tmp dir, but lib/config/xdg.mjs
+ * honors an absolute XDG_CONFIG_HOME/STATE_HOME/CACHE_HOME over HOME. A CI runner or
+ * dev shell that exports those vars routes every test's config/state/cache to one
+ * shared real location, collapsing per-test HOME isolation: suites cross-pollute (a
+ * seeded dashboard token leaks into "config absent" assertions) and writes can land
+ * in real host state. Clear them so resolution falls back to each test's HOME, as on
+ * a stock local machine; tests that exercise XDG set it explicitly per call.
+ */
+
+export function clearXdgVars(env = process.env) {
+  delete env.XDG_CONFIG_HOME;
+  delete env.XDG_STATE_HOME;
+  delete env.XDG_CACHE_HOME;
+}

package/lib/ui/components.mjs

@@ -0,0 +1,42 @@
+/**
+ * lib/ui/components.mjs — branded line primitives shared across surfaces.
+ *
+ * Status lines and section labels drawn from the shared glyph registry and a
+ * resolved color palette. Every primitive returns a string (never writes) so
+ * callers compose freely, and degrades to plain labeled text when color is
+ * unavailable so meaning never depends on a hue or glyph alone.
+ */
+
+import { UNICODE_GLYPHS } from './glyphs.mjs';
+
+// A status line pairs a tinted glyph with a message. Tints map to semantic palette
+// keys so success/warn/danger/info read consistently with the rest of the surface.
+
+export function statusLine(message, { colors = {}, tint = 'muted', glyph = '•', indent = '  ' } = {}) {
+  const color = colors[tint] || colors.muted || '';
+  return `${indent}${color}${glyph}${colors.reset || ''}  ${message}`;
+}
+
+export function ok(message, { colors = {}, glyphs = UNICODE_GLYPHS } = {}) {
+  return statusLine(message, { colors, tint: 'ok', glyph: glyphs.check });
+}
+
+export function warn(message, { colors = {} } = {}) {
+  return statusLine(message, { colors, tint: 'warn', glyph: '⚠' });
+}
+
+export function info(message, { colors = {}, glyphs = UNICODE_GLYPHS } = {}) {
+  return statusLine(message, { colors, tint: 'highlight', glyph: glyphs.arrow });
+}
+
+export function fail(message, { colors = {}, glyphs = UNICODE_GLYPHS } = {}) {
+  return statusLine(message, { colors, tint: 'danger', glyph: glyphs.cross });
+}
+
+// A section label is a tinted glyph plus a heading that opens a logical block in
+// flowing command output, lighter than a full box.
+
+export function section(label, { colors = {}, tint = 'highlight', glyph = '▸' } = {}) {
+  const color = colors[tint] || colors.highlight || '';
+  return `${color}${colors.bold || ''}${glyph} ${label}${colors.reset || ''}`;
+}

package/lib/ui/glyphs.mjs

@@ -0,0 +1,58 @@
+/**
+ * lib/ui/glyphs.mjs — single glyph registry for every construct surface.
+ *
+ * One source of truth for status marks, spinner frames, bullets, and box-drawing
+ * characters, with an ASCII fallback for terminals that cannot render Unicode.
+ * The CLI command surface and adapter diagnostics resolve glyphs here so they never
+ * drift apart. Tool status marks map raw status strings to the registry.
+ */
+
+export const UNICODE_GLYPHS = Object.freeze({
+  spinner: ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'],
+  bullet: '•',
+  check: '✓',
+  cross: '✗',
+  arrow: '→',
+  chevron: '›',
+  dot: '·',
+  diamond: '◆',
+  play: '▸',
+  boxH: '─',
+  boxV: '│',
+  boxTL: '╭',
+  boxTR: '╮',
+  boxBL: '╰',
+  boxBR: '╯',
+});
+
+export const ASCII_GLYPHS = Object.freeze({
+  spinner: ['|', '/', '-', '\\'],
+  bullet: '*',
+  check: 'OK',
+  cross: 'X',
+  arrow: '->',
+  chevron: '>',
+  dot: '.',
+  diamond: '*',
+  play: '>',
+  boxH: '-',
+  boxV: '|',
+  boxTL: '+',
+  boxTR: '+',
+  boxBL: '+',
+  boxBR: '+',
+});
+
+export function glyphs({ ascii = false } = {}) {
+  return ascii ? ASCII_GLYPHS : UNICODE_GLYPHS;
+}
+
+// Tool lifecycle status resolves to a stable mark: done, failed, running, else
+// pending. Callers pass the glyph set so ASCII terminals stay legible.
+
+export function statusGlyph(status, set = UNICODE_GLYPHS) {
+  if (status === 'completed') return set.check;
+  if (status === 'failed') return set.cross;
+  if (status === 'in_progress') return set.chevron;
+  return set.dot;
+}