@crewhaus/hangar-ui 0.5.7 → 0.5.8

package/README.md

@@ -285,16 +285,60 @@ origin — never part of this one. The asset-hygiene suite pins the exception
 to that single module, and `paneSandbox` strips `allow-same-origin` even if a
 payload asks for it.
 
+## M5 — the Advisor
+
+`views/advisor.js` draws one more harness tab (`#/h/<id>/advisor`, right
+after Overview — the strip order is the triage order) and one more fleet
+screen (`#/advisor`):
+
+- **The feed** — every alert, suggestion and optimization signal the manager
+  can derive about the harness, in one severity-ranked list. Every item
+  carries a hover TOOLTIP (`withTip`/`tipIcon` in `dom.js`: a `data-tip`
+  attribute the stylesheet renders via `attr()` — text only, so the
+  injection ban holds) explaining why it matters, the fact it was derived
+  from, guidance on what to do, and a quick action: an executable button for
+  a queued CLI verb (with its CLI twin beside it) or a deep link into the
+  tab that owns the fix. Acting opens an inline confirm where a COMMENT can
+  be attached — it is recorded in the harness-local decisions ledger next to
+  the queued job. Dismissing REQUIRES a reason (the server refuses without
+  one), dismissed items keep their recorded reasoning in a collapsible fold,
+  and every dismissal can be reopened. Zero open items renders as a
+  first-class "running optimally" state, never as an empty screen.
+- **The trend** — "is it improving?": the eval pass-rate bars, the decision
+  counts, and a one-line verdict, all folded from durable sources.
+- **Reports** — generate model-usage / costs / usefulness / optimization
+  reports (each button tooltipped with what it measures); saved reports are
+  listed and re-readable in place.
+- **Issues** — describe a problem and it is tuned into an update ready to
+  run: the kind selector (tooltipped per kind) picks what gets queued, with
+  `optimize` — the eval→patch loop whose artifact is a reviewable spec
+  patch — as the default.
+- **The fleet board** (`#/advisor`) — every harness's rollup, worst first,
+  each row deep-linking its Advisor tab.
+
+The Library also becomes curatable (M5): harness rows carry a `hidden` flag
+(the row editor's Visibility checkbox), hidden rows fold out of every view
+except an explicit **Hidden** rail bucket, and a **Find harnesses…** panel
+lists the unregistered harnesses under the scan roots (via
+`GET /api/registry/discover`) with per-candidate Add buttons — discovery
+without registration, so the Library only shows what you add. The blanket
+Scan (which registers everything) stays as the labeled bulk fallback.
+
 ## Testing
 
-`bun test src` — the embed-map completeness/hygiene suite plus unit tests
-for the pure browser modules (`util.js`, `supervision.js`, `markdown.js`,
-`router.js`, `routes.js`, `shapes.js`) and the `api.js` client under a
-stubbed `fetch` (every wrapper asserted against the route map's
-method/path/body). All DOM-free at import time and imported directly by
-bun. Deterministic: clocks are injected, no network, no subprocesses. The
-server side of the same contract runs in `@crewhaus/hangar-server`'s
-`contract.test.ts`.
+`bun run test` — two `bun test` invocations, DELIBERATELY two processes:
+`bun test src` runs the unit tests for the pure browser modules
+(`util.js`, `supervision.js`, `markdown.js`, `router.js`, `routes.js`,
+`shapes.js`, the view decisions) and the `api.js` client under a stubbed
+`fetch` (every wrapper asserted against the route map's method/path/body);
+`bun test ./src/embed-suite.ts` then runs the embed-map
+completeness/hygiene suite alone. The split is load-bearing, not taste:
+the embed suite imports every asset as TEXT while the view tests import
+the same files as ES modules, and bun's module registry keys a module by
+path alone — in one process whichever load lands first poisons the other.
+All DOM-free at import time and imported directly by bun. Deterministic:
+clocks are injected, no network, no subprocesses. The server side of the
+same contract runs in `@crewhaus/hangar-server`'s `contract.test.ts`.
 
 The M2 screens stay testable without a browser by keeping the decisions —
 state → row, envelope → disabled-with-reason, SSE frame → feed item,

package/assets/hangar.css

@@ -1724,3 +1724,178 @@ tr.deflated td {
     grid-column: 2 / 3;
   }
 }
+
+/* ── tooltips (M5): data-tip rendered via attr() — text only, never markup */
+
+.has-tip {
+  position: relative;
+  cursor: help;
+}
+.has-tip::after {
+  content: attr(data-tip);
+  position: absolute;
+  left: 0;
+  bottom: calc(100% + 7px);
+  z-index: 60;
+  width: max-content;
+  max-width: min(34rem, 78vw);
+  padding: 7px 10px;
+  border: 1px solid var(--rule-2);
+  border-radius: var(--radius-sm);
+  background: var(--panel-3);
+  color: var(--ink);
+  font-size: 12.5px;
+  font-weight: 400;
+  font-family: var(--sans);
+  line-height: 1.45;
+  white-space: normal;
+  text-align: left;
+  opacity: 0;
+  pointer-events: none;
+  transition: opacity 120ms ease;
+  box-shadow: 0 6px 22px rgba(0, 0, 0, 0.35);
+}
+.has-tip:hover::after,
+.has-tip:focus-visible::after {
+  opacity: 1;
+}
+.tip-icon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 15px;
+  height: 15px;
+  border: 1px solid var(--rule-2);
+  border-radius: 50%;
+  font-size: 10.5px;
+  color: var(--ink-3);
+  background: var(--panel-2);
+  vertical-align: middle;
+  margin-left: 5px;
+}
+
+/* ── advisor (M5): the unified alert/suggestion feed ───────────────────── */
+
+.adv-item {
+  display: grid;
+  grid-template-columns: 96px minmax(0, 1fr) auto;
+  gap: 8px 12px;
+  align-items: start;
+  padding: 10px 12px;
+  border: 1px solid var(--rule);
+  border-left-width: 3px;
+  border-radius: var(--radius-sm);
+  margin: 8px 0;
+  background: var(--panel-2);
+}
+.adv-critical {
+  border-left-color: var(--bad);
+}
+.adv-warn {
+  border-left-color: var(--warn);
+}
+.adv-suggestion {
+  border-left-color: var(--info);
+}
+.adv-main {
+  min-width: 0;
+}
+.adv-title {
+  font-weight: 550;
+}
+.adv-detail {
+  margin-top: 2px;
+  font-size: 12.5px;
+}
+.adv-guidance {
+  margin-top: 4px;
+  font-size: 12.5px;
+  color: var(--ink-2);
+}
+.adv-actions {
+  display: flex;
+  flex-direction: column;
+  align-items: flex-end;
+  gap: 6px;
+}
+.adv-cli {
+  font-size: 11px;
+  color: var(--ink-3);
+  font-family: var(--mono);
+  max-width: 24rem;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.adv-form {
+  grid-column: 1 / -1;
+  display: flex;
+  gap: 8px;
+  align-items: center;
+  flex-wrap: wrap;
+}
+.adv-form .input {
+  flex: 1 1 16rem;
+}
+.adv-optimal {
+  border: 1px solid var(--ok);
+  border-radius: var(--radius);
+  background: var(--accent-ghost);
+  padding: 16px 18px;
+  margin: 10px 0;
+}
+.adv-note {
+  font-size: 12.5px;
+  color: var(--ink-2);
+}
+.adv-decision {
+  font-size: 12px;
+  color: var(--ink-3);
+}
+.adv-board-row {
+  display: grid;
+  grid-template-columns: minmax(10rem, 1fr) auto auto minmax(0, 2fr);
+  gap: 8px 14px;
+  align-items: center;
+  padding: 9px 12px;
+  border-bottom: 1px solid var(--rule);
+}
+.trend-bars {
+  display: flex;
+  align-items: flex-end;
+  gap: 3px;
+  height: 44px;
+  margin: 6px 0;
+}
+.trend-bar {
+  width: 14px;
+  min-height: 2px;
+  background: var(--accent-ghost);
+  border-top: 2px solid var(--accent);
+}
+
+/* ── find harnesses (M5): discovery without registration ───────────────── */
+
+.find-row {
+  display: flex;
+  gap: 10px;
+  align-items: center;
+  padding: 7px 10px;
+  border-bottom: 1px solid var(--rule);
+}
+.find-row .mono {
+  flex: 1 1 auto;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+@media (max-width: 720px) {
+  .adv-item {
+    grid-template-columns: minmax(0, 1fr);
+  }
+  .adv-actions {
+    align-items: flex-start;
+  }
+}

package/assets/js/api.js

@@ -262,7 +262,9 @@ export const api = {
   groupProc: (name, verb, body = {}) => call(ROUTES.groupProc, { name, verb }, body),
   setTags: (id, tags) => call(ROUTES.setTags, { id }, { tags }),
   setPin: (id, pinned) => call(ROUTES.setPin, { id }, { pinned }),
+  setHidden: (id, hidden) => call(ROUTES.setHidden, { id }, { hidden }),
   setNotes: (id, notes) => call(ROUTES.setNotes, { id }, { notes }),
+  discover: () => call(ROUTES.discover, {}),
   relocateHarness: (id, newDir) => call(ROUTES.relocate, { id }, { newDir }),
   removeHarness: (id) => call(ROUTES.removeHarness, { id }),
 

package/assets/js/app.js

@@ -37,6 +37,7 @@ import {
 import { shapeAccent, shapeLabel } from "./shapes.js";
 import { procRow } from "./supervision.js";
 import { renderActivity } from "./views/activity.js";
+import { renderAdvisor, renderAdvisorBoard } from "./views/advisor.js";
 import { renderApprovals } from "./views/approvals.js";
 import { renderChannels } from "./views/channels.js";
 import { renderCosts } from "./views/costs.js";
@@ -68,6 +69,7 @@ import { renderTokenScreen } from "./views/token.js";
 const THEME_KEY = "hangar.theme";
 const TAB_LABELS = {
   overview: "Overview",
+  advisor: "Advisor",
   spec: "Spec",
   runs: "Runs",
   schedulers: "Schedulers",
@@ -94,6 +96,7 @@ const NAV = [
   { view: "review", label: "Review" },
   { view: "activity", label: "Activity" },
   { view: "health", label: "Health" },
+  { view: "advisor", label: "Advisor" },
   { view: "credentials", label: "Credentials" },
   { view: "feedback", label: "Feedback" },
   { view: "thredz", label: "Thredz" },
@@ -352,6 +355,8 @@ async function dispatch(route) {
       await renderThredzGlobal(viewRoot);
     } else if (route.view === "health") {
       await renderHealthBoard(viewRoot);
+    } else if (route.view === "advisor") {
+      await renderAdvisorBoard(viewRoot);
     } else if (route.view === "settings") {
       await renderSettings(viewRoot);
     } else {
@@ -423,7 +428,8 @@ async function renderHarnessPage(root, route) {
   if (route.tab === "spec") {
     await renderSpec(tabRoot, ctx);
     await renderSpecEdit(section(tabRoot), ctx);
-  } else if (route.tab === "runs") await renderRuns(tabRoot, ctx);
+  } else if (route.tab === "advisor") await renderAdvisor(tabRoot, ctx);
+  else if (route.tab === "runs") await renderRuns(tabRoot, ctx);
   else if (route.tab === "schedulers") await renderSchedulers(tabRoot, ctx);
   else if (route.tab === "sessions") await renderSessions(tabRoot, ctx);
   else if (route.tab === "evals") {

package/assets/js/dom.js

@@ -161,6 +161,36 @@ export function copyBtn(value, label = "copy") {
   return btn;
 }
 
+/**
+ * Attach a rich hover tooltip. The text rides a `data-tip` attribute the
+ * stylesheet renders via `attr()` — always text, never markup, so the
+ * injection ban holds — with the native `title` kept as the fallback for
+ * assistive tech and anything that never hovers. Returns the node.
+ */
+export function withTip(node, tipText) {
+  const value = String(tipText ?? "");
+  if (value === "") return node;
+  node.classList.add("has-tip");
+  node.dataset.tip = value;
+  if (!node.getAttribute("title")) node.setAttribute("title", value);
+  return node;
+}
+
+/** A small "?" affordance carrying only its tooltip — guidance on rows where
+ *  a whole sentence inline would drown the content. Keyboard-focusable, so
+ *  the tip is reachable without a pointer. */
+export function tipIcon(tipText) {
+  return withTip(
+    el("span", {
+      class: "tip-icon",
+      tabindex: "0",
+      "aria-label": String(tipText ?? ""),
+      text: "?",
+    }),
+    tipText,
+  );
+}
+
 /** A native collapsible (<details>) card. */
 export function collapsible(summaryChildren, bodyChildren, open = false) {
   return el("details", { class: "fold", open: open || null }, [

package/assets/js/router.js

@@ -40,6 +40,9 @@
 
 export const HARNESS_TABS = [
   "overview",
+  // M5: the unified alert/suggestion feed — right after Overview because it
+  // is the "what needs doing" screen; the strip order is the triage order.
+  "advisor",
   "spec",
   "runs",
   "schedulers",
@@ -77,6 +80,9 @@ export const M3_TABS = [
   "thredz",
   "inspect",
   "dev",
+  // M5: the advisor's sub-screens (a saved report, say) are the view's to
+  // name — the same generic `rest` capture the M3 tabs use.
+  "advisor",
 ];
 
 /** The global (fleet-wide) screens, in nav order. `#/` is the Library. */
@@ -92,6 +98,9 @@ export const GLOBAL_VIEWS = [
   // notification rules, read-only mode, the plugin inventory).
   "health",
   "settings",
+  // M5: the fleet advisor board — every harness's open alerts/suggestions,
+  // worst first.
+  "advisor",
 ];
 
 /**

package/assets/js/routes.js

@@ -56,7 +56,15 @@ export const ROUTES = {
     body: "GroupProc", // {force?, acknowledge?, parallel?}
   },
   addScanRoot: { method: "POST", path: "/api/registry/scan-roots", body: "ScanRootCreate" }, // {dir}
+  // Discovery WITHOUT registration: the harnesses under the scan roots that
+  // are NOT yet registered, each one an Add away — the "find harnesses on
+  // this machine" flow. Adding stays the default gesture; a blanket scan
+  // (which registers everything) is the bulk fallback, not the front door.
+  discover: { method: "GET", path: "/api/registry/discover" },
   removeHarness: { method: "DELETE", path: "/api/h/:id" },
+  // Curation, not removal: hidden entries stay registered (state, groups,
+  // history intact) but the Library's default view omits them.
+  setHidden: { method: "PUT", path: "/api/h/:id/visibility", body: "SetVisibility" }, // {hidden}
   relocate: { method: "POST", path: "/api/h/:id/relocate", body: "Relocate" }, // {newDir}
   setGroups: { method: "PUT", path: "/api/h/:id/groups", body: "SetGroups" }, // {groups}
   // One member's BOOT position inside a group; `order: null` clears it.
@@ -741,6 +749,60 @@ export const ROUTES = {
     group: "inspect",
   },
 
+  // ---- group "advisor": the unified alert/suggestion feed + its loops ----
+  // M5. Every alert, suggestion and optimization signal the manager can read
+  // about a harness, in ONE feed: each item carries its severity, the fact it
+  // came from, a tooltip-grade explanation, guidance, the screen that owns
+  // the fix, and a quick action (a queued CLI verb from a closed vocabulary,
+  // or a deep link — a suggestion is never an application). Acting takes an
+  // optional operator comment; dismissing REQUIRES a reason; both append to
+  // a harness-local ledger and reopen supersedes rather than deletes.
+  advisor: { method: "GET", path: "/api/h/:id/advisor", group: "advisor" },
+  advisorAct: {
+    method: "POST",
+    path: "/api/h/:id/advisor/:itemId/act",
+    body: "AdvisorAct", // {comment?}
+    group: "advisor",
+  },
+  advisorDismiss: {
+    method: "POST",
+    path: "/api/h/:id/advisor/:itemId/dismiss",
+    body: "AdvisorDismiss", // {reason}
+    group: "advisor",
+  },
+  advisorReopen: {
+    method: "POST",
+    path: "/api/h/:id/advisor/:itemId/reopen",
+    body: "Empty", // {}
+    group: "advisor",
+  },
+  // Improvement over time, folded from durable sources only (the eval index,
+  // the cost ledger, the decisions ledger) — a read never stores a snapshot.
+  advisorTrend: { method: "GET", path: "/api/h/:id/advisor/trend", group: "advisor" },
+  advisorReports: { method: "GET", path: "/api/h/:id/advisor/reports", group: "advisor" },
+  advisorReportRun: {
+    method: "POST",
+    path: "/api/h/:id/advisor/reports",
+    body: "AdvisorReportRun", // {kind: model-usage|costs|usefulness|optimization}
+    group: "advisor",
+  },
+  advisorReport: {
+    method: "GET",
+    path: "/api/h/:id/advisor/reports/:reportId",
+    group: "advisor",
+  },
+  // The issue inbox: a complaint submitted here is tuned into an update
+  // ready to run — `optimize` queues the eval→patch loop whose artifact is a
+  // reviewable spec patch; `note` records without queueing anything.
+  advisorIssues: { method: "GET", path: "/api/h/:id/advisor/issues", group: "advisor" },
+  advisorIssueSubmit: {
+    method: "POST",
+    path: "/api/h/:id/advisor/issues",
+    body: "AdvisorIssue", // {title, detail?, kind?}
+    group: "advisor",
+  },
+  advisorFleet: { method: "GET", path: "/api/advisor", group: "advisor" },
+
   // ---- group "runtime": the mcp-server + dev run classes -----------------
   // Both are PROCESSES: they get runfiles, ledger rows and ledger-claimed
   // ports, and their live output rides the ONE existing SSE feed
@@ -763,8 +825,9 @@ export const ROUTES = {
   devStop: { method: "POST", path: "/api/h/:id/dev/stop", body: "Empty", group: "runtime" },
 };
 
-/** The M3 area groups, in tab order. A route's `group` names the module that
- *  owns it on the server and the view that renders it in the console. */
+/** The grouped areas, in tab order (the M3 areas plus M5's advisor). A
+ *  route's `group` names the module that owns it on the server and the view
+ *  that renders it in the console. */
 export const M3_GROUPS = [
   "spec",
   "memory",
@@ -777,6 +840,7 @@ export const M3_GROUPS = [
   "thredz",
   "inspect",
   "runtime",
+  "advisor",
 ];
 
 /** Every route key belonging to `group`, in map order. The views render

package/assets/js/util.js

@@ -180,6 +180,7 @@ export function normalizeRows(feed) {
       groups: Array.isArray(src.groups) ? src.groups.map(String) : [],
       tags: Array.isArray(src.tags) ? src.tags.map(String) : [],
       pinned: src.pinned === true,
+      hidden: src.hidden === true,
       notes: typeof src.notes === "string" ? src.notes : "",
       missingSince: typeof src.missingSince === "string" ? src.missingSince : null,
       lastSeen: typeof src.lastSeen === "string" ? src.lastSeen : null,