@songsid/agend 2.3.0-beta.1 → 2.3.0-beta.3

package/dist/ui/fleet-traffic.js

@@ -0,0 +1,224 @@
+// #1918 phase 3: live cross-instance traffic on the org canvas (fleet-canvas.js) — what src/fleet-traffic.ts sends: the
+// stream's `traffic` items, and GET /ui/traffic's snapshot when the tab opens (and on the public link, which has no
+// stream, every POLL_MS while the page is shown — the user's decision 1). Ids are opaque; there is never any text.
+//
+// - The store keeps each message's latest state: queued (a dotted line), delivering (a dash and a pulse), delivered
+//   (the line stays FADE_MS while it fades, then goes); consumed, failed, uncertain or cancelled ends it at once (a
+//   failed or uncertain delivery is Needs you's to show, #1386). A finished message never comes back.
+// - Edges are routed metro-style through the lanes the layout keeps empty (beside the columns and between card rows
+//   inside a box; the bus above each row of teams; the trunk at the left), so a line never crosses a card.
+// - Near: one edge per (from, to, kind, phase), ×N when several share it. Far (zoomed out): one edge per team pair.
+//   A broadcast (one message per recipient, sharing an `op`) is a fan-out from its sender; more than BUNDLE_AT
+//   recipients, or far, it is one edge per recipient team, ×N (the user's decision 3). At most MAX_EDGES are drawn.
+import { OC } from "./fleet-canvas-layout.js";
+
+export const FADE_MS = 3000;
+export const POLL_MS = 5000;
+export const MAX_EDGES = 60;
+export const BUNDLE_AT = 8;
+export const FAR_K = 0.55;
+const MAX_ITEMS = 400, MAX_DONE = 2000;
+const LIVE = new Set(["queued", "delivering"]);
+const ENDS = new Set(["consumed", "failed", "uncertain", "cancelled"]);
+const KINDS = new Set(["task", "report", "query", "update", "send", "broadcast"]);
+const mono = () => (typeof performance !== "undefined" && typeof performance.now === "function" ? performance.now() : Date.now());
+
+/** A traffic item as the server sends it, checked; null for anything else. */
+export function itemOk(x) {
+  if (!x || typeof x !== "object") return null;
+  const { id, from, to, kind, state, op } = x;
+  if (typeof id !== "string" || !/^[0-9a-f]{16}$/.test(id) || typeof from !== "string" || !from || typeof to !== "string" || !to) return null;
+  if (!KINDS.has(kind) || !(LIVE.has(state) || state === "delivered" || ENDS.has(state))) return null;
+  return { id, from, to, kind, state, ...(typeof op === "string" && /^[0-9a-f]{16}$/.test(op) ? { op } : {}) };
+}
+
+/**
+ * The page's traffic: `apply(item, nowMs)` one stream item, `load(snapshot, nowMs)` a snapshot, `sweep(nowMs)` drops
+ * faded lines; each returns whether anything shown changed. `items()` what to draw: { …item, fading }.
+ */
+export function createTrafficStore() {
+  const items = new Map();          // id → { item, fadeAt }
+  const done = new Set();           // ids that ended: a late item for one is ignored
+  const finish = (id) => {
+    items.delete(id);
+    done.add(id);
+    if (done.size > MAX_DONE) done.delete(done.values().next().value);
+  };
+  const store = {
+    apply(raw, now = mono()) {
+      const it = itemOk(raw);
+      if (!it || done.has(it.id)) return false;
+      const prev = items.get(it.id);
+      if (ENDS.has(it.state)) { const had = !!prev; finish(it.id); return had; }
+      if (prev && prev.item.state === "delivered") return false;                 // delivered never goes back
+      if (prev && prev.item.state === it.state) return false;
+      items.delete(it.id);
+      items.set(it.id, { item: it, fadeAt: it.state === "delivered" ? now + FADE_MS : null });
+      while (items.size > MAX_ITEMS) items.delete(items.keys().next().value);
+      return true;
+    },
+    /** A snapshot is the truth for what is in flight: anything live it no longer lists has ended (missed while away). */
+    load(snap, now = mono()) {
+      const list = snap && Array.isArray(snap.items) ? snap.items.map(itemOk).filter(Boolean) : [];
+      const listed = new Set(list.map((i) => i.id));
+      let changed = false;
+      for (const [id, e] of items) if (!listed.has(id) && LIVE.has(e.item.state)) { finish(id); changed = true; }
+      // Delivered, for a line drawn here: it fades now (with no stream, the snapshot is the only news of it). Any other
+      // finished message is not drawn (it finished up to two minutes ago), and an ended one goes.
+      for (const it of list) {
+        if (LIVE.has(it.state) || (it.state === "delivered" && items.has(it.id))) changed = store.apply(it, now) || changed;
+        else { const had = items.has(it.id); finish(it.id); changed = changed || had; }
+      }
+      return changed;
+    },
+    sweep(now = mono()) {
+      let changed = false;
+      for (const [id, e] of items) if (e.fadeAt !== null && now >= e.fadeAt) { finish(id); changed = true; }
+      return changed;
+    },
+    items: () => [...items.values()].map((e) => ({ ...e.item, fading: e.fadeAt !== null })),
+    fadingCount: () => [...items.values()].filter((e) => e.fadeAt !== null).length,
+  };
+  return store;
+}
+
+// ── Where a name is on the canvas ──
+
+/** The team a name is drawn in (its first, if it is in two), null for General, undefined when it is not on the canvas. */
+function teamOf(L, name) {
+  if (L.tops.some((c) => c.node.name === name)) return null;
+  const b = L.boxes.find((x) => x.nodes.some((n) => n.name === name));
+  return b ? b : undefined;
+}
+/** An end of a line: General's card, a member's card, or its folded team's box. */
+function endOf(L, name) {
+  const top = L.tops.find((c) => c.node.name === name);
+  if (top) return { kind: "top", c: top, key: top.key };
+  const b = teamOf(L, name);
+  if (!b) return null;
+  if (b.folded) return { kind: "box", b, key: `box:${b.key}` };
+  const i = b.cells.findIndex((c) => c.node.name === name);
+  return { kind: "cell", b, i, c: b.cells[i], key: b.cells[i].key };
+}
+
+// ── Routing: lanes the layout keeps empty ──
+
+const firstBusOf = (L) => Math.min(...L.boxes.map((b) => b.busY));
+/** From an end up to its row's bus lane: the points, and the lane's y. `o` spreads lines sharing a lane. */
+function outward(L, end, o) {
+  if (end.kind === "top") {
+    const x = end.c.x + end.c.w / 2 + Math.max(-end.c.w / 2 + 12, Math.min(end.c.w / 2 - 12, o * 2.4));
+    const bus = firstBusOf(L) + o;
+    return { pts: [{ x, y: end.c.y + end.c.h }, { x, y: bus }], bus };
+  }
+  const b = end.b;
+  if (end.kind === "box") {
+    const x = b.x + b.w / 2 + o * 1.5;
+    return { pts: [{ x, y: b.y }, { x, y: b.busY + o }], bus: b.busY + o };
+  }
+  const { PAD, GAP, NW, NH } = OC;
+  const card = end.c, col = end.i % b.cols, rowI = Math.floor(end.i / b.cols), lines = Math.ceil(b.cells.length / b.cols);
+  const io = Math.max(-PAD / 2 + 3, Math.min(PAD / 2 - 3, o * 0.5));
+  const leftLane = b.x + PAD / 2 + io, rightLane = b.x + b.w - PAD / 2 + io;
+  let pts;
+  if (col === 0 || col === b.cols - 1) {
+    const left = col === 0, lane = left ? leftLane : rightLane, cy = card.y + NH / 2 + io;
+    pts = [{ x: left ? card.x : card.x + NW, y: cy }, { x: lane, y: cy }, { x: lane, y: b.y }];
+  } else {
+    // A middle column: down into the gutter below its row, across to the nearer side lane.
+    const gy = card.y + NH + (rowI === lines - 1 ? PAD : GAP) / 2 + io / 2, cx = card.x + NW / 2 + o;
+    const lane = cx - b.x < b.w / 2 ? leftLane : rightLane;
+    pts = [{ x: cx, y: card.y + NH }, { x: cx, y: gy }, { x: lane, y: gy }, { x: lane, y: b.y }];
+  }
+  const top = pts[pts.length - 1];
+  pts.push({ x: top.x, y: b.busY + o });
+  return { pts, bus: b.busY + o };
+}
+/** The points of a line from one end to the other: up to the bus, along it (and the trunk, between rows), down. */
+export function route(L, a, z, o) {
+  const p = outward(L, a, o), q = outward(L, z, o);
+  const back = [...q.pts].reverse();
+  if (Math.abs(p.bus - q.bus) < 1) return [...p.pts, ...back];
+  const tx = OC.TRUNK - 12 - o;
+  return [...p.pts, { x: tx, y: p.bus }, { x: tx, y: q.bus }, ...back];
+}
+/** An orthogonal polyline as SVG path data, its corners rounded. */
+export function pathOf(pts, r = 8) {
+  const q = pts.filter((pt, i) => !i || pt.x !== pts[i - 1].x || pt.y !== pts[i - 1].y);
+  let d = `M${q[0].x} ${q[0].y}`;
+  for (let i = 1; i < q.length - 1; i++) {
+    const a = q[i - 1], b = q[i], c = q[i + 1];
+    const r1 = Math.min(r, Math.hypot(b.x - a.x, b.y - a.y) / 2, Math.hypot(c.x - b.x, c.y - b.y) / 2);
+    const u = { x: Math.sign(a.x - b.x), y: Math.sign(a.y - b.y) }, v = { x: Math.sign(c.x - b.x), y: Math.sign(c.y - b.y) };
+    d += ` L${b.x + u.x * r1} ${b.y + u.y * r1} Q${b.x} ${b.y} ${b.x + v.x * r1} ${b.y + v.y * r1}`;
+  }
+  const last = q[q.length - 1];
+  return `${d} L${last.x} ${last.y}`;
+}
+/** Where a line's ×N goes: the middle of its longest straight run. */
+export function badgeAt(pts) {
+  let best = pts[0], len = -1;
+  for (let i = 1; i < pts.length; i++) {
+    const l = Math.hypot(pts[i].x - pts[i - 1].x, pts[i].y - pts[i - 1].y);
+    if (l > len) { len = l; best = { x: (pts[i].x + pts[i - 1].x) / 2, y: (pts[i].y + pts[i - 1].y) / 2 }; }
+  }
+  return best;
+}
+
+// ── Edges ──
+
+/** The colour family of a kind: task, report, broadcast, and the rest (send, query, update). */
+export const hue = (kind) => (kind === "task" || kind === "report" || kind === "broadcast" ? kind : "send");
+const phaseOf = (it) => (it.fading ? "fading" : it.state === "queued" ? "queued" : "live");
+const RANK = { live: 0, queued: 1, fading: 2 };
+
+/**
+ * The lines to draw from the store's items on layout `L`. `far`: zoomed out (one line per team pair). Each edge:
+ * { key, hue, phase, n, from, to, d, pts, badge } — `from`/`to` the instance (or team) names it joins, for search.
+ */
+export function trafficEdges(items, L, { far = false, max = MAX_EDGES } = {}) {
+  if (!L.boxes.length && L.tops.length < 2) return [];
+  const groups = new Map();
+  const add = (key, g) => { const cur = groups.get(key); if (cur) { cur.n += g.n; cur.names.push(...g.names); } else groups.set(key, g); };
+  const teamKey = (name) => { const t = teamOf(L, name); return t === null ? "\u0000general" : t ? t.key : undefined; };
+  const teamEnd = (name) => { const t = teamOf(L, name); return t === null ? endOf(L, name) : t ? { kind: "box", b: t, key: `box:${t.key}` } : null; };
+  // Broadcasts: one fan-out per op; big ones (or far) bundle per recipient team.
+  const byOp = new Map();
+  for (const it of items) if (it.kind === "broadcast" && it.op) { const l = byOp.get(it.op) || []; l.push(it); byOp.set(it.op, l); }
+  const bundled = new Set();
+  for (const list of byOp.values()) if (far || list.length > BUNDLE_AT) for (const it of list) bundled.add(it.id);
+  for (const it of items) {
+    const phase = phaseOf(it), names = [it.from, it.to];
+    if (far || bundled.has(it.id)) {
+      const ta = teamKey(it.from), tb = teamKey(it.to);
+      if (ta === tb) continue;                                                     // inside one team: not drawn far away
+      const k = far ? "team" : "broadcast";
+      const a = far ? teamEnd(it.from) : endOf(L, it.from), z = teamEnd(it.to);
+      if (!a || !z) continue;
+      add(`${k}|${a.key}>${z.key}|${phase === "fading" ? "fading" : "live"}`, { a, z, hue: k === "team" ? "team" : "broadcast", phase: phase === "fading" ? "fading" : phase, n: 1, names });
+      continue;
+    }
+    const a = endOf(L, it.from), z = endOf(L, it.to);
+    if (!a || !z || a.key === z.key) continue;                                     // both in one folded team
+    add(`${a.key}>${z.key}|${hue(it.kind)}|${phase}`, { a, z, hue: hue(it.kind), phase, n: 1, names });
+  }
+  const list = [...groups.entries()].sort((x, y) => RANK[x[1].phase] - RANK[y[1].phase]).slice(0, max);
+  return list.map(([key, g], i) => {
+    const o = ((i % 7) - 3) * 7;                                                    // neighbours 7 px apart (within the ±22 px bus lane)
+    const pts = route(L, g.a, g.z, o);
+    return { key, hue: g.hue, phase: g.phase, n: g.n, names: [...new Set(g.names)], d: pathOf(pts), pts, badge: g.n > 1 ? badgeAt(pts) : null };
+  });
+}
+
+/** For the list: what each instance is sending now, in words ("task → quill"), live messages only. */
+export function sendingBy(items) {
+  const out = new Map();
+  for (const it of items) {
+    if (it.fading) continue;
+    const l = out.get(it.from) || [];
+    const key = `${it.kind}>${it.to}>${it.state}`;
+    if (!l.some((x) => x.key === key)) l.push({ key, kind: it.kind, to: it.to, queued: it.state === "queued" });
+    out.set(it.from, l);
+  }
+  return out;
+}

package/dist/ui/panel-chat.js

@@ -10,7 +10,7 @@ import { html, useEffect, useLayoutEffect, useRef, useState } from "/assets/app-
 import { t } from "/assets/app-i18n.js";
 import { appStore, useStore } from "/assets/app-store.js";
 import { useLease } from "/assets/app-ctx.js";
-import { namesOf, namesStore } from "/assets/instance-nav.js";
+import { modelText, namesOf, namesStore } from "/assets/instance-nav.js";
 import { PanelHeader, onPanelKey, setTitle, statusClass, statusLabel, openDrawer, requestNewInstance } from "/assets/app-shell.js";
 import { detailsPath, textLinkSegments } from "/assets/app-route.js";
 import { InstanceSwitch } from "/assets/instance-switch.js";
@@ -281,7 +281,7 @@ function ChatView({ name, inst, lease, navKey, exec, awaiting }) {
   // #1269 quick actions: the model and effort it runs, each a way to /model or /effort (the same pick list).
   const pick = (command) => store.runCommand(name, command, "", { alive: () => lease.current() });
   const sub = html`<span class="status"><span class=${`dot ${cls}`} aria-hidden="true"></span>${statusLabel(inst, exec, awaiting)}</span>
-    ${inst.model ? html`<button type="button" class="hd-chip" title=${t("chat.chipModel", inst.model)} aria-label=${t("chat.chipModel", inst.model)} onClick=${() => pick("model")}>${inst.model}</button>` : null}
+    ${inst.model ? html`<button type="button" class="hd-chip" title=${t("chat.chipModel", modelText(inst))} aria-label=${t("chat.chipModel", modelText(inst))} onClick=${() => pick("model")}>${modelText(inst)}</button>` : null}
     ${inst.effort ? html`<button type="button" class="hd-chip" title=${t("chat.chipEffort", inst.effort)} aria-label=${t("chat.chipEffort", inst.effort)} onClick=${() => pick("effort")}>${inst.effort}</button>` : null}`;
   return html`<div class=${`panel p-chat${wrap ? " wrap-code" : ""}`} ref=${view}>
     <${PanelHeader} title=${headerName(namesOf(inst || { name }, names.primary))} sub=${sub} nav=${html`<${InstanceSwitch} name=${name} current="chat" />`}><${ChatEffectPosters} name=${name} lease=${lease} element=${effectSurface} /><${ChatEffects} name=${name} lease=${lease} element=${effectSurface} store=${store} open=${dialog === "effects"} onClose=${() => setDialog(null)} /><${HeaderTools} navKey=${navKey} /><${Menu} items=${items} label=${t("app.more")} /></${PanelHeader}>
@@ -312,6 +312,12 @@ function Thread({ name, th }) {
     const thread = createThread(list.current, scroller.current, {
       t, tf: t, isUser: (x) => store.isUser(x, name), onJump: setJump, onEmpty: setEmpty,
       setPreviewOptIn, copyText, download: downloadHtml, toggleWrap,
+      effectTrialStatus: x => getAppEffects()?.trialStatus(x) ?? "localAdmin",
+      fixEffectTrial: (x, reason) => {
+        if (reason === "busy") getAppEffects()?.stopTrial();
+        else if (reason === "localAdmin") location.href = "/signin?next=" + encodeURIComponent(location.pathname + location.search);
+        else navigate("/ui/settings?section=appearance");
+      },
       canTryEffect: x => getAppEffects()?.canTry(x) === true,
       startEffectTrial: x => { const seq = navStore.get().seq; void getAppEffects()?.startTrial(x).then(ok => { if (!ok && live && navStore.get().seq === seq && document.hasFocus?.() === true && document.visibilityState === "visible") toast(t("chat.effectTrialUnavailable")); }); },
       clickReplyButton: (id, index) => store.clickReplyButton(name, id, index),      // #1266

package/dist/ui/panel-details.js

@@ -14,6 +14,7 @@ import { PanelHeader, setTitle, statusClass, statusLabel, openDrawer } from "/as
 import { navigate } from "/assets/app-nav.js";
 import { settingsPath } from "/assets/app-route.js";
 import { InstanceSwitch } from "/assets/instance-switch.js";
+import { modelText } from "/assets/instance-nav.js";
 import { HeaderTools } from "/assets/header-tools.js";
 import { Menu } from "/assets/ui-menu.js";
 import { themeMenuItems, themesStore } from "/assets/app-themes.js";
@@ -143,7 +144,7 @@ function DetailsView({ name, inst, navKey, exec, awaiting }) {
           <button type="button" class="btn btn-sm d-edit-settings" onClick=${editInSettings}>${t("chat.dEditInSettings")}</button></div></section>
       <section class="card"><h3>${t("chat.dRuntime")}</h3>
         ${row(t("chat.dBackend"), d.backend || "--")}
-        ${row(t("chat.dModel"), `${d.model || sl.model?.display_name || "--"}${d.model_source === "live" ? "" : src(d.model_source)}`)}
+        ${row(t("chat.dModel"), `${(d.model && modelText(d)) || sl.model?.display_name || "--"}${d.model_source === "live" ? "" : src(d.model_source)}`)}
         ${d.effort ? row(t("chat.dEffort"), `${d.effort}${src(d.effort_source)}`) : null}
         ${row(t("chat.dCost"), `$${cost.toFixed(2)} ${t("chat.dCostNote")}`)}
         ${row(t("chat.dContext"), html`<span class="pct">${ctx != null ? `${Math.round(ctx)}%` : "--"}</span>${ctx != null ? bar(ctx, ctx > 80 ? "warn" : "") : null}`)}

package/dist/ui/panel-fleet.js

@@ -18,14 +18,23 @@ import { Icon } from "/assets/ui-icons.js";
 import { toast } from "/assets/ui-toast.js";
 import { confirmDialog } from "/assets/ui-confirm.js";
 import { confirmedWrite } from "./settings-confirm.js";
-import { OrgChart } from "./fleet-org.js";
+import { OrgCanvas } from "./fleet-canvas.js";
 import { labelOf } from "/assets/instance-nav.js";
 import { CacheReport } from "./fleet-cache.js";
 
+/** #2015: one of the largest processes as text: "python3 18.1 GB (dev-a)". */
+export function memoryHogText(p) {
+  const size = p.rssBytes >= 1024 ** 3 ? `${(p.rssBytes / 1024 ** 3).toFixed(1)} GB` : `${Math.round(p.rssBytes / 1024 ** 2)} MB`;
+  const owner = p.owner === "instance" && p.instance ? p.instance
+    : t(p.owner === "fleet" ? "fleet.hostMemory_ownerFleet" : p.owner === "tmux" ? "fleet.hostMemory_ownerTmux" : "fleet.hostMemory_ownerOther");
+  return `${p.name} ${size} (${owner})`;
+}
+
 register("fleet", {
   en: {
     hostMemory_elevated: "Host memory pressure: elevated — new agents start one at a time, at least 5 s apart",
     hostMemory_critical: "Host memory pressure: critical — new agents wait for memory to recover",
+    hostMemory_top: "Largest: {0}", hostMemory_ownerFleet: "the fleet", hostMemory_ownerTmux: "tmux", hostMemory_ownerOther: "not an instance",
     title: "Fleet", tasks: "Tasks", schedules: "Schedules", teams: "Teams", org: "Org chart", cache: "Cache", config: "Config",
     docs: "Docs", docsNewTab: "Docs (opens in a new tab)",
     newTask: "New task", newSchedule: "New schedule", newTeam: "New team",
@@ -57,6 +66,7 @@ register("fleet", {
   "zh-TW": {
     hostMemory_elevated: "主機記憶體壓力偏高：新的 agent 一次啟動一個，至少間隔 5 秒",
     hostMemory_critical: "主機記憶體壓力嚴重：新的 agent 會等記憶體恢復再啟動",
+    hostMemory_top: "最大：{0}", hostMemory_ownerFleet: "fleet 本身", hostMemory_ownerTmux: "tmux", hostMemory_ownerOther: "不屬於任何 instance",
     title: "Fleet", tasks: "Tasks", schedules: "排程", teams: "Teams", org: "組織圖", cache: "快取", config: "設定",
     docs: "文件", docsNewTab: "文件（在新分頁開啟）",
     newTask: "新增 task", newSchedule: "新增排程", newTeam: "新增 team",
@@ -132,8 +142,10 @@ export function FleetPanel({ route, navKey }) {
   useEffect(() => { setTitle(`${t("fleet.title")} · ${t(`fleet.${tab}`)}`); }, [tab, navKey]);
   const Body = { tasks: Tasks, schedules: Schedules, teams: Teams, org: Org, cache: Cache, config: Config }[tab] || Tasks;
   // #1685: host memory pressure slowing or holding new agents — shown here, where macOS's routine "elevated" is not a chat notice.
-  const { hostMemory } = useStore(appStore);
-  const sub = hostMemory ? html`<span class=${`status host-mem ${hostMemory}`} role="status"><span class=${`dot ${hostMemory === "critical" ? "bad" : "warn"}`} aria-hidden="true"></span>${t(`fleet.hostMemory_${hostMemory}`)}</span>` : null;
+  const { hostMemory, hostMemoryTop } = useStore(appStore);
+  // #2015: and which processes hold the most, and whose — text only (never chat, #1712).
+  const top = hostMemory && hostMemoryTop?.length ? t("fleet.hostMemory_top", hostMemoryTop.map(memoryHogText).join(" · ")) : "";
+  const sub = hostMemory ? html`<span class=${`status host-mem ${hostMemory}`} role="status"><span class=${`dot ${hostMemory === "critical" ? "bad" : "warn"}`} aria-hidden="true"></span>${t(`fleet.hostMemory_${hostMemory}`)}${top ? html`<span class="host-mem-top">${top}</span>` : null}</span>` : null;
   return html`<div data-effect-panel="fleet" class="panel p-fleet">
     <${PanelHeader} title=${t("fleet.title")} sub=${sub}><${DocsLink} /><${HeaderTools} navKey=${navKey} /></${PanelHeader}>
     <nav data-trust="panel-navigation" class="seg" aria-label=${t("fleet.title")}>${FLEET_TABS.map(k => html`<a key=${k} href=${fleetPath(k)} class=${`seg-item${k === tab ? " active" : ""}`}
@@ -255,11 +267,11 @@ function Teams({ lease }) {
   ${editing ? html`<${CreateTeam} team=${editing} onClose=${() => setEditing(null)} onDone=${() => setVersion(v => v + 1)} />` : null}`;
 }
 
-/** #1389: the org chart — its structure read once per opening, its live state from the app store (fleet-org.js). */
+/** #1389: the org chart — its structure read once per opening, its live state from the app store. #1918: a canvas, or the list (fleet-canvas.js). */
 function Org({ lease }) {
   const state = useLoad(lease, "/ui/org", 0);
   const app = useStore(appStore);
-  return html`<${Loaded} state=${state}>${(org) => html`<${OrgChart} org=${org} app=${app} />`}</${Loaded}>`;
+  return html`<${Loaded} state=${state}>${(org) => html`<${OrgCanvas} org=${org} app=${app} lease=${lease} />`}</${Loaded}>`;
 }
 
 /** #1468: the prompt-cache analysis — one read per opening and per window chosen; Refresh reads again (fleet-cache.js). */

package/dist/ui/panel-settings.js

@@ -20,6 +20,7 @@ import { Empty, ErrorState, Skeleton } from "/assets/ui-states.js";
 import { Icon } from "/assets/ui-icons.js";
 import { Menu } from "/assets/ui-menu.js";
 import { toast } from "/assets/ui-toast.js";
+import { groupLabel, modelText } from "/assets/instance-nav.js";
 import "./settings-strings.js";
 import { api, attach, confirmedWrite, newKey } from "./settings-confirm.js";
 import { dismissOperation, operationActive, restartFleet, startOperation, takeLeftover } from "./settings-apply.js";
@@ -87,7 +88,7 @@ async function loadLive(lease) {
   if (!lease.current()) return null;
   const live = {}, classicLive = {};
   if (f.ok && f.body && Array.isArray(f.body.instances)) for (const i of f.body.instances) {
-    live[i.name] = { status: i.status, state: i.state, backend: i.backend, model: i.model, model_display: i.model_display, effort: i.effort, effort_supported: i.effort_supported };
+    live[i.name] = { status: i.status, state: i.state, backend: i.backend, model: i.model, model_display: modelText(i, i.model_display), effort: i.effort, effort_supported: i.effort_supported };
     if (i.classic) classicLive[i.name] = { status: i.status, state: i.state };
   }
   // /api/fleet carries live state for ClassicBot rooms; the profiles are the fallback for one not listed there yet.
@@ -473,7 +474,7 @@ function Agents({ ctx, search, openDialog }) {
     return html`<section key=${group} class="s-group">
       <button type="button" class="s-group-head" aria-expanded=${folded ? "false" : "true"}
         onClick=${() => setCollapsed((c) => { const n = new Set(c); n.has(group) ? n.delete(group) : n.add(group); return n; })}>
-        <${Icon} name="chevron" size=${14} cls=${folded ? "caret folded" : "caret"} /><span class="grow">${group}</span><span class="count">${names.length}</span></button>
+        <${Icon} name="chevron" size=${14} cls=${folded ? "caret folded" : "caret"} /><span class="grow">${groupLabel(group)}</span><span class="count">${names.length}</span></button>
       ${folded ? null : names.map((name) => {
         const inst = insts[name];
         const st = (ctx.live[name] && ctx.live[name].status) || "stopped";

package/dist/ui/preview.js

@@ -100,7 +100,7 @@
       notify();
       return true;
     }
-    if (j && (j.code === "publicLinkPreviewFailed" || j.code === "publicLink" || j.code === "fleetOff")) {
+    if (j && (j.code === "publicLinkPreviewFailed" || j.code === "publicLink" || j.code === "fleetOff" || j.code === "listenFailed" || j.code === "notListening")) {
       cfg.reasonCode = j.code; cfg.reason = ""; cfg.detail = typeof j.detail === "string" ? j.detail : "";
       notify();
       return true;
@@ -191,7 +191,8 @@
     if (!cfg.previewOrigin || !cfg.boot) {
       // The server's reason, in the page's language when the server named it (a code), else as the server wrote it.
       // #1723: a failed public-link preview names why ({0} is the reason, in the page's words).
-      var arg = cfg.reasonCode === "publicLinkPreviewFailed" ? say("pvFail_" + (cfg.detail || "unknown"), Object.prototype.hasOwnProperty.call(FAIL_EN, cfg.detail) ? FAIL_EN[cfg.detail] : "an unexpected error") : cfg.dashboardOrigin;
+      var arg = cfg.reasonCode === "publicLinkPreviewFailed" ? say("pvFail_" + (cfg.detail || "unknown"), Object.prototype.hasOwnProperty.call(FAIL_EN, cfg.detail) ? FAIL_EN[cfg.detail] : "an unexpected error")
+        : cfg.reasonCode === "listenFailed" ? cfg.detail : cfg.dashboardOrigin;
       var english = cfg.reasonCode === "publicLinkPreviewFailed" ? "Previews are unavailable on this public link: {0}. The link itself keeps working."
         : cfg.reason || "Previews are not available here.";
       var server = cfg.reasonCode ? say("pvServer_" + cfg.reasonCode, english, arg) : "";

package/dist/ui/settings-appearance.js

@@ -15,7 +15,8 @@ import { AgentWidget, checkWidget, fleetBinds, setSidebarWidget, sidebarWidgetRa
 import { confirmedWrite } from "./settings-confirm.js";
 import { savePref } from "/assets/app-prefs.js";
 import { confirmDialog } from "/assets/ui-confirm.js";
-import { colorsOff, defaultPlaces, PLACEMENTS, setColorsOff, setDefaultPlaces, useIdentityColors } from "/assets/identity-color.js";
+import { colorsOff, defaultPlaces, identityClasses, identityOf, PLACEMENTS, paintIdentity, setColorsOff, setDefaultPlaces, useIdentityColors } from "/assets/identity-color.js";
+import { CardTitle } from "./settings-learn.js";
 import "./settings-strings.js";
 
 const tn = (k, ...v) => t(`settings.${k}`, ...v);
@@ -42,22 +43,38 @@ function refusal(body) {
 export function AppearanceSection() {
   const publicLink = typeof document !== "undefined" && document.body && document.body.dataset.publicLink === "1";
   if (publicLink) return html`<section class="card s-appearance"><h3>${tn("cssTitle")}</h3><p class="sub">${tn("cssPublicLink")}</p></section>`;
-  return html`<${ThemesCard} /><${IdentityColorCard} /><${CardSizeCard} /><${SidebarWidgetCard} /><${OwnerCssCard} /><${ModsCard} /><${EffectsCard} /><${DeviceCard} /><${CardLimitsCard} /><${RestoreDefaultsCard} />`;
+  const group = (key) => html`<h2 class="s-ap-group">${tn(key)}</h2>`;
+  return html`${group("groupLook")}<${ThemesCard} /><${IdentityColorCard} /><${CardSizeCard} />
+    ${group("groupLayout")}<${SidebarWidgetCard} />
+    ${group("groupCss")}<${OwnerCssCard} /><${DeviceCard} />
+    ${group("groupMods")}<${ModsCard} /><${EffectsCard} />
+    ${group("groupAdvanced")}<${CardLimitsCard} /><${RestoreDefaultsCard} />`;
+}
+
+/** #2056 B: a sample sidebar row in the host's default colour places, so the choice is seen rather than described. */
+const SAMPLE = { color: { person: "preset:teal" } };
+function ColorSample({ places, off }) {
+  const id = identityOf(SAMPLE, { hostDefault: places, off });
+  return html`<div class="idc-preview s-colors-sample" aria-hidden="true"><span class=${`inst v-inst ${identityClasses(id)}`} ref=${(el) => paintIdentity(el, id)}>
+    <span class="av"><span class="av-text">A</span></span><span class="inst-text"><span class="inst-name">${tn("colorSample")}</span></span></span></div>`;
 }
 
 /**
- * #1958: identity colours on this host — where they show for an instance nobody chose for (ring and bar unless
- * changed), and a switch that turns them off everywhere while every pick is kept.
+ * #1958: identity colours on this host — where they show for an instance nobody chose for (#2056: name, bar and
+ * ring unless changed), and a switch that turns them off everywhere while every pick is kept.
  */
 function IdentityColorCard() {
   useIdentityColors();
   const places = defaultPlaces(), off = colorsOff();
   const toggle = (p) => setDefaultPlaces(places.includes(p) ? places.filter((x) => x !== p) : [...places, p]);
-  return html`<section class="card s-appearance s-synced s-colors"><h3>${tn("colorTitle")}</h3>
+  return html`<section class="card s-appearance s-synced s-colors"><${CardTitle} title=${tn("colorTitle")} topic="colors" />
     <p class="sub">${tn("colorLead")}</p>
-    <fieldset class="idc-places" disabled=${off}><legend>${tn("colorPlaces")}</legend>
-      ${PLACEMENTS.map((p) => html`<label key=${p} class="check"><input type="checkbox" checked=${places.includes(p)} onChange=${() => toggle(p)} /> ${t(`color.place_${p}`)}</label>`)}
-    </fieldset>
+    <div class="s-colors-row">
+      <fieldset class="idc-places" disabled=${off}><legend>${tn("colorPlaces")}</legend>
+        ${PLACEMENTS.map((p) => html`<label key=${p} class="check"><input type="checkbox" checked=${places.includes(p)} onChange=${() => toggle(p)} /> ${t(`color.place_${p}`)}</label>`)}
+      </fieldset>
+      <${ColorSample} places=${places} off=${off} />
+    </div>
     <label class="check"><input type="checkbox" class="s-colors-off" checked=${off} onChange=${(e) => setColorsOff(e.target.checked)} /> <span>${tn("colorOff")}</span></label>
     <p class="sub">${tn("colorOffLead")}</p>
   </section>`;
@@ -88,7 +105,7 @@ function RestoreDefaultsCard() {
     setBusy(false);
     if (r.ok) toast(tn("restoreDone")); else toast(tn("restoreCssFailed", r.error), false);
   }
-  return html`<section class="card s-appearance s-restore"><h3>${tn("restoreTitle")}</h3>
+  return html`<section class="card s-appearance s-restore"><${CardTitle} title=${tn("restoreTitle")} topic="restore" />
     <p class="sub">${tn("restoreLead")}</p>
     <button type="button" class="btn" disabled=${busy} onClick=${go}>${tn("restoreTitle")}</button>
   </section>`;
@@ -98,7 +115,7 @@ function RestoreDefaultsCard() {
 function CardSizeCard() {
   useStore(cardSizeStore);
   const size = cardSizeDefault();
-  return html`<section class="card s-appearance s-synced"><h3>${tn("cardSizeTitle")}</h3>
+  return html`<section class="card s-appearance s-synced"><${CardTitle} title=${tn("cardSizeTitle")} topic="cards" />
     <div class="card-size" role="group" aria-label=${tn("cardSizeTitle")}>
       ${CARD_SIZES.map((s) => html`<button key=${s} type="button" class=${`seg-item${s === size ? " active" : ""}`} aria-pressed=${s === size ? "true" : "false"}
         onClick=${() => setCardSizeDefault(s)}>${t(`card.size${s.toUpperCase()}Name`)}</button>`)}
@@ -131,7 +148,7 @@ function CardLimitsCard() {
   };
   useEffect(() => { load(); }, []);
   if (!view) return null;
-  if (view.error) return html`<section class="card s-appearance"><h3>${tn("cardLimitsTitle")}</h3><p class="sub">${tn("cardLimitsUnavailable")}</p></section>`;
+  if (view.error) return html`<section class="card s-appearance"><${CardTitle} title=${tn("cardLimitsTitle")} topic="limits" /><p class="sub">${tn("cardLimitsUnavailable")}</p></section>`;
   const configured = (g, k) => (view.configured && view.configured[g] && typeof view.configured[g][k] === "number" ? view.configured[g][k] : null);
   const save = async () => {
     const body = {};
@@ -148,7 +165,7 @@ function CardLimitsCard() {
     if (r.ok) { setMsg(tn("cardLimitsSaved")); load(); } else setMsg(tn("cardLimitsFailed", (r.body && r.body.error) || r.status));
   };
   const warnings = Array.isArray(view.warnings) ? view.warnings : [];
-  return html`<section class="card s-appearance"><h3>${tn("cardLimitsTitle")}</h3>
+  return html`<section class="card s-appearance"><${CardTitle} title=${tn("cardLimitsTitle")} topic="limits" />
     <p class="sub">${tn("cardLimitsLead")}</p>
     <fieldset class="form" disabled=${busy}>
       ${["portrait", "banner", "instance_quota"].map((g) => html`<div key=${g} class="grid3">
@@ -170,7 +187,7 @@ function CardLimitsCard() {
 /** #1629 r2 (d): whether this person's screens show agents' themes (and, as they come, effects) — synced. */
 function ThemesCard() {
   const s = useStore(themesStore);
-  return html`<section class="card s-appearance s-synced"><h3>${tn("themesTitle")}</h3>
+  return html`<section class="card s-appearance s-synced"><${CardTitle} title=${tn("themesTitle")} topic="themes" />
     <label class="check"><input type="checkbox" checked=${s.shown} disabled=${safeMode()} onChange=${(e) => setThemesShown(e.target.checked)} />
       <span>${tn("themesShow")}</span></label>
     <p class="sub">${safeMode() ? tn("themesSafeMode") : tn("themesShowLead")}</p>
@@ -209,7 +226,7 @@ function SidebarWidgetCard() {
     toast(tn("widgetSaved"));
   };
   const remove = () => { setSidebarWidget(null); setText(""); setError(""); toast(tn("widgetRemoved")); };
-  return html`<section class="card s-appearance s-synced s-widget"><h3>${tn("widgetTitle")}</h3>
+  return html`<section class="card s-appearance s-synced s-widget"><${CardTitle} title=${tn("widgetTitle")} topic="widgets" />
     <p class="sub">${tn("widgetLead")}</p>
     <label class="field"><span class="sr-only">${tn("widgetTitle")}</span>
       <textarea class="s-widget-text" rows="10" spellcheck=${false} autocapitalize="off" autocomplete="off" value=${text}
@@ -240,8 +257,8 @@ function OwnerCssCard() {
   useEffect(() => { load(); }, []);
   // A trial answered (kept or reverted) changes what is in force: read it again, keeping the editor's text.
   useEffect(() => { if (state) load({ text: false }); }, [trial && trial.sha]);
-  if (!state) return html`<section class="card s-appearance"><h3>${tn("cssTitle")}</h3><p class="sub">…</p></section>`;
-  if (state.failed) return html`<section class="card s-appearance"><h3>${tn("cssTitle")}</h3><p class="err">${tn("cssLoadFailed")}</p></section>`;
+  if (!state) return html`<section class="card s-appearance"><${CardTitle} title=${tn("cssTitle")} topic="css" /><p class="sub">…</p></section>`;
+  if (state.failed) return html`<section class="card s-appearance"><${CardTitle} title=${tn("cssTitle")} topic="css" /><p class="err">${tn("cssLoadFailed")}</p></section>`;
 
   const save = async () => {
     setBusy(true); setError("");
@@ -285,7 +302,7 @@ function OwnerCssCard() {
     ? (state.pending ? tn("cssOnTrial", short(state.active)) : tn("cssInForce", short(state.active)))
     : tn("cssNone");
   const assetBytes = state.assets.reduce((n, a) => n + a.bytes, 0);
-  return html`<section class="card s-appearance s-owner-css"><h3>${tn("cssTitle")}</h3>
+  return html`<section class="card s-appearance s-owner-css"><${CardTitle} title=${tn("cssTitle")} topic="css" />
     <p class="sub">${tn("cssLead")}</p>
     <p class="s-css-status" role="status">${inForce}</p>
     <label class="field"><span class="sr-only">${tn("cssTitle")}</span>
@@ -319,7 +336,6 @@ function DeviceCard() {
   return html`<section class="card s-appearance s-local"><h3>${tn("cssDeviceTitle")}</h3>
     <label class="check"><input type="checkbox" checked=${off} onChange=${(e) => { setOwnerCssOffHere(e.target.checked); setOff(ownerCssOffHere()); }} />
       <span>${tn("cssDeviceOff")}</span></label>
-    <p class="sub">${tn("cssDeviceOffLead")}</p>
     <p class="sub">${tn("cssSafe")}</p>
   </section>`;
 }

package/dist/ui/settings-dialogs.js

@@ -17,7 +17,7 @@ import {
   ACCESS_MODES, AGENT_FIELDS, AGENT_MODES, BOT_FIELDS, CH_TYPES, CLASSIC_FIELDS, HANG_TIMEOUT_DEFAULT_MINUTES, LOG_LEVELS, TOOL_PROGRESS, TOOL_SETS,
   VISIBILITY_MODES, accessConfirmations, agentForm, agentPatch, backendOptions, changedFields, channelId, channelsOf,
   chLabel, hasOwn, impactOf, nonNegative, nonNegativeInteger, positive, replyGuardSupported, sameValue, visibilityDefault,
-  webEchoIsGroup, worstImpact,
+  classicWebEchoEffective, worstImpact,
 } from "./settings-model.js";
 
 const tn = (k, ...v) => t(`settings.${k}`, ...v);
@@ -557,7 +557,7 @@ export function ClassicDialog({ room, ctx, onClose }) {
     backend: c.backend || inherited.backend, model: c.model || "",
     auto_pause_after: String(c.auto_pause_after ?? inherited.auto_pause_after), tool_progress: c.tool_progress ?? inherited.tool_progress,
     reply_completion_guard: c.reply_completion_guard ?? inherited.reply_completion_guard,
-    collab: !!c.collab, web_echo: !!c.web_echo, context_lines: String(c.context_lines ?? cd.context_lines ?? 5),
+    collab: !!c.collab, web_echo: classicWebEchoEffective(c, fleet), context_lines: String(c.context_lines ?? cd.context_lines ?? 5),
     inherit: { auto_pause_after: !hasOwn(c, "auto_pause_after"), tool_progress: !hasOwn(c, "tool_progress"), reply_completion_guard: !hasOwn(c, "reply_completion_guard") },
   }));
   const set = (k) => (v) => setF((x) => ({ ...x, [k]: v }));
@@ -580,12 +580,9 @@ export function ClassicDialog({ room, ctx, onClose }) {
       auto_pause_after: hasOwn(c, "auto_pause_after") ? c.auto_pause_after : null,
       tool_progress: hasOwn(c, "tool_progress") ? c.tool_progress : null,
       reply_completion_guard: hasOwn(c, "reply_completion_guard") ? c.reply_completion_guard : null,
-      collab: !!c.collab, context_lines: c.context_lines ?? cd.context_lines ?? 5, web_echo: !!c.web_echo,
+      collab: !!c.collab, context_lines: c.context_lines ?? cd.context_lines ?? 5, web_echo: classicWebEchoEffective(c, fleet),
     });
     if (!Object.keys(patch).length) { onClose(); return; }
-    // #1320: turning web echo on for a group posts every web message where all its members can read it.
-    if (patch.web_echo === true && !c.web_echo && webEchoIsGroup(c.channelId)
-      && !(await ask(tn("webEchoGroupConfirm"), { confirmLabel: tn("webEchoEnable") }))) return;
     if (!lease.current()) return;
     ctx.stageClassic(c, patch);
     onClose();

package/dist/ui/settings-effects.js

@@ -4,10 +4,11 @@ import { register, t } from "/assets/app-i18n.js";
 import { appStore, useStore } from "/assets/app-store.js";
 import { confirmDialog } from "/assets/ui-confirm.js";
 import { OwnerEffects } from "./settings-owner-effects.js";
+import { CardTitle } from "./settings-learn.js";
 
 register("effectSettings", {
   en: {
-    title: "Effects", lead: "Manage effect files and save selections for a chat. Saving replaces that chat’s parameters with the values below.", folder: "Upload an effect folder", files: "Choose effect.json and worker.js, with optional raster assets. Up to 1 MiB after processing.",
+    title: "Effects", lead: "Your effect files, and which one a chat uses.", folder: "Upload an effect folder", files: "effect.json + worker.js (and pictures), up to 1 MiB.",
     inUse: "This effect is still in use and cannot be deleted.", quota: "Your library reached its 10-effect or 8 MiB limit. Delete unused copies first.", rateLimited: "Too many changes. Wait a moment, then try again.",
     loading: "Loading effects…", retry: "Reload library", empty: "No effects in your library.", failed: "Couldn't load the library. Try again.", actionFailed: "Couldn't save this change. Try again.", savedRefresh: "Saved. Reload the library to see the result.",
     uploadFailed: "Couldn't upload this folder. Check its files and size, then try again.", public: "Effect management isn't available on a temporary public link.", readOnly: "Read-only session: sign in as an admin to change effects.",
@@ -16,7 +17,7 @@ register("effectSettings", {
     fps: "Host FPS p50 / p10", tasks: "Host long task p95", noTasks: "Not observed", standard: "Standard device", constrained: "Constrained device", params: "Parameters", badParams: "Check the parameter values.", more: "Show more", count: "{0} effects", one: "1 effect", profileFailed: "Couldn't read profile history. Try again.",
   },
   "zh-TW": {
-    title: "效果", lead: "管理效果檔案，並儲存聊天的效果選擇。儲存時會以下方數值取代該聊天的效果參數。", folder: "上傳效果資料夾", files: "選擇 effect.json、worker.js，以及可選的點陣圖素材；處理後最多 1 MiB。",
+    title: "效果", lead: "你的效果檔案，以及每個聊天使用哪一個。", folder: "上傳效果資料夾", files: "effect.json + worker.js（可加圖片），最多 1 MiB。",
     inUse: "這個效果仍在使用中，無法刪除。", quota: "你的程式庫已達 10 個效果或 8 MiB 上限，請先刪除未使用的副本。", rateLimited: "變更太頻繁，請稍候再試。",
     loading: "正在載入效果…", retry: "重新載入程式庫", empty: "程式庫中還沒有效果。", failed: "無法載入程式庫，請重試。", actionFailed: "無法儲存變更，請重試。", savedRefresh: "已儲存，請重新載入程式庫查看結果。",
     uploadFailed: "無法上傳這個資料夾，請檢查檔案與大小後重試。", public: "臨時公開連結不提供效果管理。", readOnly: "目前為唯讀登入，請以管理員身分登入才能修改效果。",
@@ -180,7 +181,7 @@ export function EffectsCard() {
     if (!current(op.seq)) return; finish(op.seq);
     if (yes) await change(`/ui/effects/${id}`, undefined, "DELETE");
   };
-  return html`<section class="card s-appearance s-effects"><h3>${tn("title")}</h3><p class="sub">${tn("lead")}</p>
+  return html`<section class="card s-appearance s-effects"><${CardTitle} title=${tn("title")} topic="effects" /><p class="sub">${tn("lead")}</p>
     <div class="s-fx-actions"><button type="button" class="btn" disabled=${busy} onClick=${reload}>${tn("retry")}</button>
       ${view?.canWrite ? html`<button class="btn s-fx-choose" type="button" disabled=${busy} onClick=${() => uploadInput.current?.click()}>${tn("folder")}</button><input ref=${uploadInput} class="offscreen s-fx-upload" aria-label=${tn("folder")} tabindex="-1" type="file" webkitdirectory=${true} directory=${true} multiple disabled=${busy} onChange=${upload} />` : null}</div>
     ${busy ? html`<p class="sub" role="status">${tn("loading")}</p>` : null}${error ? html`<p class="err" role="status">${error}</p>` : null}${message ? html`<p class="sub" role="status">${message}</p>` : null}

package/dist/ui/settings-learn.js

@@ -0,0 +1,25 @@
+// #2056 B: a card title with a small "?" that opens the card's section of the docs, so Settings → Web appearance
+// keeps one short line per control and the long explanations live in docs/web-dashboard(.zh-TW).md.
+import { html } from "/assets/app-html.js";
+import { lang, t } from "/assets/app-i18n.js";
+import "./settings-strings.js";
+
+/**
+ * #2056 B: where each card's long explanation lives — a heading of docs/web-dashboard(.zh-TW).md on GitHub, so the
+ * page keeps one short line per control and a small "?" for the rest.
+ */
+const DOCS = { en: "https://github.com/songsid/AgEnD/blob/main/docs/web-dashboard.md", "zh-TW": "https://github.com/songsid/AgEnD/blob/main/docs/web-dashboard.zh-TW.md" };
+export const LEARN_ANCHORS = {
+  colors: ["identity-colours", "識別色"], css: ["custom-css-settings--web-appearance", "自訂-css設定--網頁外觀"], themes: ["agents-themes", "agent-的主題"],
+  cards: ["identity-cards", "身分卡"], limits: ["card-upload-limits", "身分卡上傳限制"], widgets: ["widgets", "小工具"], mods: ["mods", "mod"],
+  effects: ["effects", "效果"], restore: ["restore-defaults", "還原預設值"],
+};
+export function learnHref(topic, language = lang()) {
+  const zh = language === "zh-TW";
+  return `${DOCS[zh ? "zh-TW" : "en"]}#${encodeURIComponent(LEARN_ANCHORS[topic][zh ? 1 : 0])}`;
+}
+/** A card title with its "?" link to the docs (a new tab; the page itself never fetches anything). */
+export function CardTitle({ title, topic }) {
+  return html`<h3 class="s-ap-title"><span>${title}</span>${topic ? html`<a class="s-learn" href=${learnHref(topic)} target="_blank" rel="noopener noreferrer"
+    aria-label=${t("settings.learnMore", title)} title=${t("settings.learnMore", title)}>?</a>` : null}</h3>`;
+}