@songsid/agend 2.2.0-alpha.1 → 2.2.0-alpha.3

package/dist/ui/shared/panel-view.js

@@ -2,7 +2,7 @@
 // panel, in the app shell. Public (/assets/): under `web.view_access: open` an anonymous reader opens it in the
 // View-only shell, so nothing here needs a session to show, and the one write (Edit profile) asks for one.
 //
-// Its roster is the sidebar's section while it is mounted: groups by tag, the #999 filter, this browser's order (drag).
+// Its roster read also feeds the sidebar's list for an anonymous reader (instance-nav.js is the list on every page).
 // Everything recurring is a passive read (#1374) taken through the navigation's lease: the pane every 800 ms and the
 // roster every 5 s while the panel is mounted and the tab is visible, usage every 60 s while its dialog is open. They
 // stop when the panel goes.
@@ -10,7 +10,9 @@ import { html, useEffect, useLayoutEffect, useMemo, useRef, useState } from "./a
 import { t } from "./app-i18n.js";
 import { appStore, createStore, useStore } from "./app-store.js";
 import { useLease } from "./app-ctx.js";
-import { PanelHeader, setTitle, setSideSection, closeDrawer, onPanelKey, signInHref } from "./app-shell.js";
+import { PanelHeader, setTitle, onPanelKey, signInHref } from "./app-shell.js";
+import { backendLabel, STATUS_KEYS } from "./instance-nav.js";
+import { viewStore } from "./view-roster-store.js";
 import { navigate } from "./app-nav.js";
 import { viewPath } from "./app-route.js";
 import { Dialog } from "./ui-dialog.js";
@@ -88,190 +90,10 @@ function paintAnsi(root) {
   }
 }
 
-// ── The roster: groups, the #999 filter, this browser's order ──
-export function groupOf(it) {
-  const tags = it.tags || [];
-  if (tags.includes("classic")) return "Classic";
-  if (tags.length) return tags[0];
-  return "Other";
-}
-const BACKEND_LABELS = { "claude-code": "Claude Code", "kiro-cli": "Kiro CLI", codex: "Codex", grok: "Grok Build", antigravity: "Antigravity", opencode: "OpenCode" };
-export function backendLabel(backend) { return BACKEND_LABELS[backend] || backend || "Unknown"; }
-const KNOWN_BACKENDS = new Set(Object.keys(BACKEND_LABELS));
-const STATUS_KEYS = { running: "statusRunning", paused: "statusPaused", stopped: "statusStopped", crashed: "statusCrashed" };
-
-export function normalizeFilter(query) { return String(query == null ? "" : query).trim().toLowerCase(); }
-/** Case-insensitive substring on name (incl. display name), model and backend. */
-export function instanceMatchesFilter(it, needle, labelOf) {
-  if (!needle) return true;
-  const fields = [it.instance_name, it.display_name, it.model, it.backend, labelOf ? labelOf(it.backend) : null];
-  return fields.some((value) => typeof value === "string" && value.toLowerCase().includes(needle));
-}
-/** Visible groups in display order, and the "N / M" counts. */
-export function filterSidebar(groupNames, instByGroup, rosterByName, query, labelOf) {
-  const needle = normalizeFilter(query);
-  const groups = [];
-  let shown = 0, total = 0;
-  for (const g of groupNames) {
-    const names = (instByGroup.get(g) || []).filter((name) => rosterByName.has(name));
-    total += names.length;
-    const visible = names.filter((name) => instanceMatchesFilter(rosterByName.get(name), needle, labelOf));
-    shown += visible.length;
-    if (visible.length) groups.push({ group: g, names: visible });
-  }
-  return { groups, shown, total, active: needle.length > 0 };
-}
-export function instanceTooltip(it) {
-  const context = it.context_pct != null && Number.isFinite(it.context_pct) ? `${Math.round(Math.min(100, Math.max(0, it.context_pct)))}%` : tn("tooltipUnavailable");
-  const status = STATUS_KEYS[it.status] ? tn(STATUS_KEYS[it.status]) : it.status || tn("statusUnknown");
-  const line = (key, value) => tn(key, { value });
-  const lines = [];
-  if (it.display_name && it.display_name !== it.instance_name) lines.push(it.display_name, `(${it.instance_name})`);
-  else lines.push(it.instance_name);
-  lines.push(line("tooltipBackend", backendLabel(it.backend)));
-  const src = (s) => (s === "instance" || s === "classic" ? " (configured)" : s === "fleet-default" ? " (fleet default)" : "");
-  lines.push(line("tooltipModel", (it.model || tn("tooltipUnavailable")) + src(it.model_source)));
-  lines.push(line("tooltipStatus", status));
-  lines.push(line("tooltipContext", context));
-  if (it.effort) lines.push(line("tooltipEffort", it.effort + src(it.effort_source)));
-  if (typeof it.description === "string" && it.description.trim()) lines.push("", it.description.trim());
-  return lines.join("\n");
-}
-
-const SIDEBAR_ORDER_KEY = "agend_view_sidebar_order";
-function readOrder() {
-  const groups = new Map(), insts = new Map();
-  try {
-    const rows = JSON.parse(stored(SIDEBAR_ORDER_KEY) || "[]");
-    if (Array.isArray(rows)) for (const row of rows) {
-      if (row && row.item_type === "group" && typeof row.item_name === "string") groups.set(row.item_name, Number(row.sort_index) || 0);
-      else if (row && row.item_type === "instance" && typeof row.item_name === "string") insts.set(row.item_name, Number(row.sort_index) || 0);
-    }
-  } catch { /* ignore invalid browser-local state */ }
-  return { groups, insts };
-}
-/** Display order: this browser's saved order first, then new groups/instances by tag and name. */
-export function computeOrder(roster, order) {
-  const groups = new Map();
-  for (const it of roster) { const g = groupOf(it); if (!groups.has(g)) groups.set(g, []); groups.get(g).push(it); }
-  const gidx = (g) => (order.groups.has(g) ? order.groups.get(g) : Infinity);
-  const groupNames = [...groups.keys()].sort((a, b) => {
-    const ia = gidx(a), ib = gidx(b);
-    if (ia !== ib) return ia - ib;
-    if (a === "Other") return 1;
-    if (b === "Other") return -1;
-    return a.localeCompare(b);
-  });
-  const instByGroup = new Map();
-  for (const [g, items] of groups) {
-    instByGroup.set(g, items.map((it) => it.instance_name).sort((a, b) => {
-      const ia = order.insts.has(a) ? order.insts.get(a) : Infinity, ib = order.insts.has(b) ? order.insts.get(b) : Infinity;
-      return ia - ib;
-    }));
-  }
-  return { groupNames, instByGroup };
-}
-function moveIn(arr, moving, target, before) {
-  if (!arr) return;
-  const from = arr.indexOf(moving);
-  if (from === -1) return;
-  arr.splice(from, 1);
-  let to = arr.indexOf(target);
-  if (to === -1) { arr.push(moving); return; }
-  if (!before) to += 1;
-  arr.splice(to, 0, moving);
-}
-
-/** The roster shared by the panel and its sidebar section, for as long as the page lives. */
-export const viewStore = createStore({ loaded: false, error: null, roster: [], filter: "", collapsed: new Set(), current: null, order: readOrder() });
-const byName = (roster) => new Map(roster.map((r) => [r.instance_name, r]));
-
-function persistOrder(groupNames, instByGroup) {
-  const rows = [];
-  groupNames.forEach((g, i) => rows.push({ item_type: "group", item_name: g, sort_index: i, group_name: null }));
-  for (const g of groupNames) (instByGroup.get(g) || []).forEach((n, j) => rows.push({ item_type: "instance", item_name: n, sort_index: j, group_name: g }));
-  store(SIDEBAR_ORDER_KEY, JSON.stringify(rows));
-  viewStore.set({ order: { groups: new Map(groupNames.map((g, i) => [g, i])), insts: new Map(rows.filter((r) => r.item_type === "instance").map((r) => [r.item_name, r.sort_index])) } });
-}
-
-/** The sidebar section while View is mounted: the filter, then the groups and their instances (links to /view/<name>). */
-function ViewRoster() {
-  const v = useStore(viewStore);
-  const filterRef = useRef(null);
-  const drag = useRef(null);
-  const rosterByName = byName(v.roster);
-  const { groupNames, instByGroup } = computeOrder(v.roster, v.order);
-  const shown = filterSidebar(groupNames, instByGroup, rosterByName, v.filter, backendLabel);
-  const setFilter = (value) => viewStore.set({ filter: value });
-  const toggle = (g) => { const c = new Set(v.collapsed); if (c.has(g)) c.delete(g); else c.add(g); viewStore.set({ collapsed: c }); };
-  // Drag to reorder: only the full list (a filtered subset would be ambiguous), groups among groups, instances within
-  // their group.
-  const dragProps = (item) => shown.active ? {} : {
-    draggable: "true",
-    onDragStart: (e) => { drag.current = item; e.currentTarget.classList.add("dragging"); try { e.dataTransfer.effectAllowed = "move"; e.dataTransfer.setData("text/plain", item.name); } catch { /* Firefox needs data */ } },
-    onDragEnd: (e) => { e.currentTarget.classList.remove("dragging"); drag.current = null; },
-    onDragOver: (e) => {
-      const d = drag.current;
-      if (!d || d.type !== item.type || d.name === item.name || (item.type === "instance" && d.group !== item.group)) return;
-      e.preventDefault();
-      const r = e.currentTarget.getBoundingClientRect();
-      const before = e.clientY < r.top + r.height / 2;
-      e.currentTarget.classList.toggle("drop-before", before);
-      e.currentTarget.classList.toggle("drop-after", !before);
-    },
-    onDragLeave: (e) => e.currentTarget.classList.remove("drop-before", "drop-after"),
-    onDrop: (e) => {
-      e.preventDefault();
-      const before = e.currentTarget.classList.contains("drop-before");
-      e.currentTarget.classList.remove("drop-before", "drop-after");
-      const d = drag.current;
-      if (!d || d.type !== item.type) return;
-      const names = [...groupNames], insts = new Map([...instByGroup].map(([g, n]) => [g, [...n]]));
-      if (item.type === "group") moveIn(names, d.name, item.name, before);
-      else if (d.group === item.group) moveIn(insts.get(item.group), d.name, item.name, before);
-      else return;
-      persistOrder(names, insts);
-    },
-  };
-  // The list scrolls; the filter under it stays in view (#999), so it sits outside the scrolling section.
-  return html`<div class="view-roster">
-    <div class="side-section" id="instanceList">
-    <h2 class="side-label">${tn("instancesLabel")}</h2>
-    ${!v.loaded ? html`<${Skeleton} lines=${4} />` : !v.roster.length ? html`<p class="side-empty">${tn("noInstances")}</p>` : null}
-    ${shown.groups.map(({ group: g, names }) => {
-      const folded = v.collapsed.has(g);
-      return html`<div key=${g} class="v-group">
-        <button type="button" class="v-group-head" aria-expanded=${folded ? "false" : "true"} onClick=${() => toggle(g)}
-          title=${tn(folded ? "expandGroup" : "collapseGroup", { group: g })} ...${dragProps({ type: "group", name: g })}>
-          <${Icon} name="chevron" size=${14} cls=${folded ? "caret folded" : "caret"} /><span class="grow">${g}</span><span class="count">${names.length}</span></button>
-        ${folded ? null : html`<ul class="inst-list">${names.map((name) => {
-          const it = rosterByName.get(name);
-          const alias = typeof it.display_name === "string" && it.display_name.trim() && it.display_name.trim() !== name ? it.display_name.trim() : "";
-          const active = name === v.current;
-          return html`<li key=${name}><a class=${`inst v-inst${active ? " active" : ""}`} href=${viewPath(name)} title=${instanceTooltip(it)}
-              aria-current=${active ? "page" : undefined} onClick=${closeDrawer} ...${dragProps({ type: "instance", name, group: g })}>
-            <span class=${`dot ${it.status === "running" ? "ok" : it.status === "crashed" ? "bad" : "off"}`} aria-hidden="true"></span>
-            <span class="inst-text"><span class="inst-name">${name}</span>${alias ? html`<span class="inst-sub"><span class="inst-alias">${alias}</span></span>` : null}</span>
-            <span class="v-meta">${it.context_pct != null ? `${Math.round(it.context_pct)}%` : ""}</span>
-            <span class=${`cli-icon cli-${KNOWN_BACKENDS.has(it.backend) ? it.backend : "other"}`} title=${backendLabel(it.backend)} aria-label=${tn("tooltipBackend", { value: backendLabel(it.backend) })}></span>
-          </a></li>`;
-        })}</ul>`}
-      </div>`;
-    })}
-    ${v.loaded && shown.active && !shown.groups.length ? html`<p class="side-empty">${tn("filterNone")}</p>` : null}
-    </div>
-    <div class="v-filter">
-      <label class="v-filter-box"><${Icon} name="search" size=${14} /><span class="sr-only">${tn("filterPh")}</span>
-        <input ref=${filterRef} id="filterInput" type="text" autocomplete="off" spellcheck="false" placeholder=${tn("filterPh")} value=${v.filter}
-          onInput=${(e) => setFilter(e.target.value)}
-          onKeyDown=${(e) => { if (e.key === "Escape" && v.filter) { e.preventDefault(); e.stopPropagation(); setFilter(""); } }} />
-        ${v.filter ? html`<button type="button" class="icon-btn v-filter-clear" aria-label=${tn("filterClear")} title=${tn("filterClear")}
-          onClick=${() => { setFilter(""); filterRef.current && filterRef.current.focus(); }}><${Icon} name="close" size=${14} /></button>` : null}
-      </label>
-      <p class="note" aria-live="polite">${shown.shown} / ${shown.total}${shown.active ? ` ${tn("filterShown")}` : ""}</p>
-    </div>
-  </div>`;
-}
+// ── The roster ── The sidebar's list is instance-nav.js on every page (alpha.2, N1); its helpers are re-exported here
+// for the View code and tests that used them from this module.
+export { groupOf, backendLabel, normalizeFilter, instanceMatchesFilter, filterSidebar, instanceTooltip, computeOrder } from "./instance-nav.js";
+export { viewStore };
 
 // ── The panel ──
 
@@ -317,8 +139,6 @@ export function ViewPanel({ route, navKey }) {
   const name = route.instance;
   const it = name ? v.roster.find((r) => r.instance_name === name) : null;
 
-  // The roster is the sidebar's section while View is mounted.
-  useEffect(() => lease.hold(setSideSection(ViewRoster)), [lease]);
   useEffect(() => { viewStore.set({ current: name }); }, [name]);
   useEffect(() => { setTitle(it ? (it.display_name || it.instance_name) : tn("title")); }, [name, it && it.display_name, navKey]);
   if (name && it) store("agend_last_view", name);
@@ -643,10 +463,12 @@ function UsageDialog({ onClose }) {
             <button type="button" class="icon-btn" disabled=${i === 0} aria-label=${tn("usageMoveUp")} title=${tn("usageMoveUp")} onClick=${() => move(key(p), -1, data.providers)}><${Icon} name="up" size=${14} /></button>
             <button type="button" class="icon-btn" disabled=${i === providers.length - 1} aria-label=${tn("usageMoveDown")} title=${tn("usageMoveDown")} onClick=${() => move(key(p), 1, data.providers)}><${Icon} name="down" size=${14} /></button>
           </span></div>
-        ${p.status === "error" ? html`<p class="u-err">${usageText(p.error || tn("usage.error_fallback"), p.errorI18n)}</p>`
+        ${p.stale ? html`<p class="note">${usageText(p.hint || "", p.hintI18n)}</p>` : null}
+        ${p.status === "error" && !p.transient ? html`<p class="u-err">${usageText(p.error || tn("usage.error_fallback"), p.errorI18n)}</p>`
+          : p.status === "error" && p.transient ? html`<p class="note">${usageText(p.error || tn("usage.error_fallback"), p.errorI18n)}</p>`
           : p.status === "no-credentials" ? html`<p class="note">${tn("usage.not_logged_in")}</p>${p.hint ? html`<p class="note">${usageText(p.hint, p.hintI18n)}</p>` : null}`
           : html`${(p.metrics || []).map((m, j) => html`<${UsageMetric} key=${j} m=${m} />`)}
-            ${p.hint ? html`<p class="note">${usageText(p.hint, p.hintI18n)}</p>` : !(p.metrics || []).length ? html`<p class="note">${tn("usage.no_data")}</p>` : null}`}
+            ${!p.stale && p.hint ? html`<p class="note">${usageText(p.hint, p.hintI18n)}</p>` : !(p.metrics || []).length ? html`<p class="note">${tn("usage.no_data")}</p>` : null}`}
       </section>`)}
       <div class="u-foot"><span class="note">${tn("usageUpdated")} ${new Date(data.fetchedAt).toLocaleTimeString()}</span>
         <button type="button" class="btn btn-sm" onClick=${() => load(true)}>${tn("usageRefresh")}</button></div>`;

package/dist/ui/shared/signin.js

@@ -39,7 +39,17 @@
       history.replaceState(null, "", here.pathname + here.search + here.hash);
     }
   } catch { /* nothing to clean */ }
-  document.querySelectorAll("[data-i18n]").forEach((el) => { el.textContent = t(el.getAttribute("data-i18n")); });
+  // The command in the hint is a <code> that never breaks across lines (a break inside "--code" reads as two dashes
+  // and a word, alpha.2 sweep); the text around it is text.
+  const CMD = "agend web --code";
+  document.querySelectorAll("[data-i18n]").forEach((el) => {
+    const text = t(el.getAttribute("data-i18n"));
+    const at = text.indexOf(CMD);
+    if (at < 0) { el.textContent = text; return; }
+    const code = document.createElement("code");
+    code.textContent = CMD;
+    el.replaceChildren(text.slice(0, at), code, text.slice(at + CMD.length));
+  });
 
   // An old deep link, /ui#instance=<name> (#1408 §3): the fragment never reaches the server, and the sign-in page is
   // served at the URL that was asked for, so it is still in location.hash here. Exactly that one form becomes the new
@@ -94,6 +104,8 @@
     // navigation; going round again would loop, so stop and let the person type a code.
     if (recentlyBounced()) return false;
     try {
+      // Signed out, this answers 401 — and the browser logs that request in red in DevTools. That is expected: the
+      // probe asks "is there a session?", and no is a normal answer here (decided against reshaping the auth API).
       const r = await fetch("/auth/session", { credentials: "same-origin", cache: "no-store" });
       return r.ok;
     } catch { return false; }

package/dist/ui/shared/ui-icons.js

@@ -50,6 +50,8 @@ const P = {
   pause: () => html`<path d="M8 5v14M16 5v14"/>`,
   download: () => html`<path d="M12 3v12M7 10l5 5 5-5M5 21h14"/>`,
   org: () => html`<rect x="9" y="2" width="6" height="5" rx="1"/><rect x="2" y="17" width="6" height="5" rx="1"/><rect x="16" y="17" width="6" height="5" rx="1"/><path d="M12 7v5M5 17v-5h14v5"/>`,
+  panel: () => html`<rect x="3" y="4" width="18" height="16" rx="2"/><path d="M14 4v16"/>`,
+  back: () => html`<path d="M19 12H5M12 19l-7-7 7-7"/>`,
   external: () => html`<path d="M14 4h6v6M20 4l-9 9"/><path d="M18 14v5a1 1 0 0 1-1 1H5a1 1 0 0 1-1-1V7a1 1 0 0 1 1-1h5"/>`,
 };
 

package/dist/ui/shared/view-roster-store.js

@@ -0,0 +1,5 @@
+// View's roster read (/api/profiles), shared by the View panel (its cards) and the anonymous reader's sidebar list
+// (instance-nav.js), for as long as the page lives. The View panel fills it while mounted; nothing else reads the server.
+import { createStore } from "./app-store.js";
+
+export const viewStore = createStore({ loaded: false, error: null, roster: [], current: null });

package/dist/ui/shared/view-strings.js

@@ -12,6 +12,9 @@ register("view", {
   "filterClear": "Clear filter",
   "filterNone": "No instance matches",
   "filterShown": "shown",
+  "filterStatus": "Status",
+  "filterCli": "CLI",
+  "filterFacetsReset": "Clear",
   "displayName": "Display name",
   "role": "Role",
   "description": "Description",
@@ -38,6 +41,7 @@ register("view", {
   "tooltipContext": "Context: {value}",
   "tooltipModel": "Model: {value}",
   "tooltipEffort": "Effort: {value}",
+  "tooltipCost": "Cost: {value}",
   "tooltipUnavailable": "Unavailable",
   "statusRunning": "Running",
   "statusPaused": "Paused",
@@ -109,6 +113,8 @@ register("view", {
   "usage.error.unreachable": "Could not reach {0}.",
   "usage.error.token_rejected": "Token rejected. Run `{0}` once to refresh the login.",
   "usage.error.rate_limited": "Rate limited by {0} — try again later.",
+  "usage.error.rate_limited_transient": "{0}: can't fetch usage right now (rate limited). This does not affect your agents.",
+  "usage.stale_rate_limited": "data from {0} min ago — can't refresh right now",
   "usage.error.http": "Usage request failed (HTTP {0}).",
   "usage.error.billing_http": "Billing request failed (HTTP {0}).",
   "usage.error.invalid_response": "Invalid response from usage endpoint.",
@@ -163,6 +169,9 @@ register("view", {
   "filterClear": "清除篩選",
   "filterNone": "沒有符合的 instance",
   "filterShown": "顯示中",
+  "filterStatus": "狀態",
+  "filterCli": "CLI",
+  "filterFacetsReset": "清除",
   "displayName": "顯示名稱",
   "role": "角色",
   "description": "描述",
@@ -189,6 +198,7 @@ register("view", {
   "tooltipContext": "上下文：{value}",
   "tooltipModel": "模型：{value}",
   "tooltipEffort": "推理強度：{value}",
+  "tooltipCost": "費用：{value}",
   "tooltipUnavailable": "無資料",
   "statusRunning": "運行中",
   "statusPaused": "已暫停",
@@ -260,6 +270,8 @@ register("view", {
   "usage.error.unreachable": "無法連線至 {0}。",
   "usage.error.token_rejected": "Token 已被拒絕。請執行一次 `{0}` 以更新登入。",
   "usage.error.rate_limited": "{0} 暫時限制請求速率，請稍後再試。",
+  "usage.error.rate_limited_transient": "暫時查不到 {0} 用量（{0} 限制查詢頻率），不影響你的 agent。",
+  "usage.stale_rate_limited": "{0} 分鐘前的資料，暫時無法更新",
   "usage.error.http": "用量請求失敗（HTTP {0}）。",
   "usage.error.billing_http": "計費請求失敗（HTTP {0}）。",
   "usage.error.invalid_response": "用量端點回傳了無效資料。",

package/dist/ui/signin.html

@@ -27,6 +27,7 @@
   button:disabled { opacity: .6; cursor: default; }
   #msg { min-height: 1.5em; margin-top: 14px; font-size: var(--fs-sm); color: var(--danger); }
   .hint { margin-top: 18px; font-size: var(--fs-xs); color: var(--text-3); }
+  .hint code { white-space: nowrap; font-family: var(--font-mono); }
   [hidden] { display: none !important; }
 </style>
 </head>
@@ -42,7 +43,7 @@
            autocorrect="off" spellcheck="false" maxlength="12" placeholder="XXXX-XXXX" required>
     <button id="go" type="submit" data-i18n="submit">Sign in</button>
     <div id="msg" role="alert" aria-live="polite"></div>
-    <div class="hint" data-i18n="hint">Send /dashboard to your AgEnD bot, or run “agend web --code” on the host. A code works once and expires in 5 minutes.</div>
+    <div class="hint" data-i18n="hint">Send /dashboard to your AgEnD bot, or run “<code>agend web --code</code>” on the host. A code works once and expires in 5 minutes.</div>
   </form>
   <noscript>This page needs JavaScript to sign you in.</noscript>
 </main>

package/dist/update-dispatch.d.ts

@@ -0,0 +1,28 @@
+export interface DispatchDeps {
+    run(command: string, args: string[], timeoutMs: number): Promise<{
+        status: number | null;
+        stdout: string;
+    }>;
+    readFile(path: string): Promise<string>;
+    realpath(path: string): Promise<string>;
+}
+export declare const defaultDispatchDeps: DispatchDeps;
+export type InstalledAgend = {
+    ok: true;
+    agend: string;
+    version: string;
+} | {
+    ok: false;
+    reason: string;
+};
+/** npm's global root and prefix → the installed package, its bin target, and the bin link that must lead to it. */
+export declare function resolveInstalledAgend(deps?: DispatchDeps): Promise<InstalledAgend>;
+/**
+ * `<installed agend> update`, 2 s from now, from a detached `sh`. Service callers must wrap it in an independent scope before launch. The
+ * path is a positional argument, never spliced into the script.
+ */
+export declare const DELAYED_UPDATE_SCRIPT = "sleep 2 && exec \"$1\" update";
+export declare function updateCommand(agend: string): {
+    command: string;
+    args: string[];
+};

package/dist/update-dispatch.js

@@ -0,0 +1,73 @@
+/**
+ * #1450 C5: chat `/update` runs the INSTALLED `agend` — the one npm put in its global prefix, verified by identity —
+ * by absolute path, never whichever `agend` comes first on the fleet's PATH (a checkout, another prefix). That keeps
+ * the deliberate choice "update what is installed, on its own channel" (the CLI picks the channel from the version it
+ * replaces). No unverified fallback: when npm cannot say where it installed AgEnD, or what it says does not hold
+ * together, `/update` refuses and says to run `agend update` from a shell.
+ *
+ * Runs on the fleet's event loop: every step is async and bounded.
+ */
+import { execFile } from "node:child_process";
+import { readFile, realpath } from "node:fs/promises";
+import { join } from "node:path";
+import { promisify } from "node:util";
+export const defaultDispatchDeps = {
+    run: async (command, args, timeoutMs) => {
+        try {
+            const { stdout } = await promisify(execFile)(command, args, { encoding: "utf8", timeout: timeoutMs });
+            return { status: 0, stdout: String(stdout) };
+        }
+        catch (err) {
+            const code = err.code;
+            return { status: typeof code === "number" ? code : null, stdout: "" };
+        }
+    },
+    readFile: path => readFile(path, "utf8"),
+    realpath: path => realpath(path),
+};
+/** npm's global root and prefix → the installed package, its bin target, and the bin link that must lead to it. */
+export async function resolveInstalledAgend(deps = defaultDispatchDeps) {
+    const last = (text) => text.trim().split("\n").pop()?.trim() ?? "";
+    const [root, prefix] = await Promise.all([deps.run("npm", ["root", "-g"], 15_000), deps.run("npm", ["prefix", "-g"], 15_000)]);
+    if (root.status !== 0 || prefix.status !== 0 || !last(root.stdout) || !last(prefix.stdout)) {
+        return { ok: false, reason: "npm could not say where AgEnD is installed" };
+    }
+    const pkgDir = join(last(root.stdout), "@songsid", "agend");
+    const notAgend = { ok: false, reason: `${pkgDir} is not an installed AgEnD package` };
+    let parsed;
+    try {
+        parsed = JSON.parse(await deps.readFile(join(pkgDir, "package.json")));
+    }
+    catch {
+        return notAgend;
+    }
+    // Whatever parsed (null, an array, a string…) is judged by shape, never dereferenced blindly.
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+        return notAgend;
+    const manifest = parsed;
+    const bin = manifest.bin;
+    const binRel = typeof bin === "string" ? bin
+        : typeof bin === "object" && bin !== null && !Array.isArray(bin) && typeof bin.agend === "string" ? bin.agend : null;
+    if (manifest.name !== "@songsid/agend" || typeof manifest.version !== "string" || !manifest.version || !binRel)
+        return notAgend;
+    const agend = join(last(prefix.stdout), "bin", "agend");
+    let target, linked;
+    try {
+        [target, linked] = await Promise.all([deps.realpath(join(pkgDir, binRel)), deps.realpath(agend)]);
+    }
+    catch {
+        return { ok: false, reason: `${agend} does not lead to the installed package` };
+    }
+    if (target !== linked)
+        return { ok: false, reason: `${agend} leads to ${linked}, not the installed package's ${target}` };
+    return { ok: true, agend, version: manifest.version };
+}
+/**
+ * `<installed agend> update`, 2 s from now, from a detached `sh`. Service callers must wrap it in an independent scope before launch. The
+ * path is a positional argument, never spliced into the script.
+ */
+export const DELAYED_UPDATE_SCRIPT = 'sleep 2 && exec "$1" update';
+export function updateCommand(agend) {
+    return { command: "sh", args: ["-c", DELAYED_UPDATE_SCRIPT, "sh", agend] };
+}
+//# sourceMappingURL=update-dispatch.js.map

package/dist/update-dispatch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-dispatch.js","sourceRoot":"","sources":["../src/update-dispatch.ts"],"names":[],"mappings":"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"}

package/dist/update-install.d.ts

@@ -1,3 +1,4 @@
+import { type PackagePreimage } from "./package-preimage.js";
 export interface CommandResult {
     status: number | null;
     signal: NodeJS.Signals | null;
@@ -5,10 +6,14 @@ export interface CommandResult {
     stderr: string;
 }
 export interface CommandRunner {
-    /** Run a program; `inherit` streams its output to the terminal (npm's progress), otherwise it is captured. */
+    /**
+     * Run a program; `inherit` streams its output to the terminal (npm's progress), otherwise it is captured. `env` is
+     * added to this process's environment for that one program (the install token goes to npm and nothing else).
+     */
     run(command: string, args: string[], options?: {
         inherit?: boolean;
         timeoutMs?: number;
+        env?: Record<string, string>;
     }): CommandResult;
     /** Progress for the operator, printed when it happens. */
     log(message: string): void;
@@ -22,6 +27,28 @@ export interface UpdateInstallPlan {
     viaNvm: boolean;
     /** `~/.nvm/nvm.sh`. */
     nvmSh: string;
+    /**
+     * #1450 C1: take the prefix lock for the realpath'd npm prefix this install will change, before npm runs; its token
+     * is handed to npm as AGEND_INSTALL_TOKEN. Omitted: no lock (tests of the order alone).
+     */
+    lock?(prefix: string): {
+        ok: true;
+        token: string;
+    } | {
+        ok: false;
+        reason: string;
+    };
+    /**
+     * #1450 C6: copy the installed package aside before npm (requires `lock`), and put it back when the new one does not
+     * verify. The successful outcome carries the preimage, so a later service failure can restore it too.
+     */
+    rollback?: boolean;
+    now?(): Date;
+    /**
+     * nvm's Node 22 bin directory, resolved ONCE (runUpdateInstall sets it): locking, installing and verifying then run
+     * on that exact selection, never on a fresh `nvm use 22` that could pick another Node 22 in between (#1472 review).
+     */
+    nvmBin?: string;
 }
 export type UpdateInstallOutcome = {
     ok: true;
@@ -29,10 +56,18 @@ export type UpdateInstallOutcome = {
     version: string;
     dir: string;
     bin: string;
+    entry: string;
     node: string;
+    rollback?: {
+        root: string;
+        prefix: string;
+        preimage: PackagePreimage | null;
+    }; /** nvm transition: retire the old system copy once activation settles. */
+    retireSystemCopy?: true; /** Absolute path of the npm binary used to install this version — same binary passed to sudo for retirement. */
+    npmPath?: string;
 } | {
     ok: false;
-    stage: "install" | "verify";
+    stage: "lock" | "install" | "verify";
     message: string;
 };
 /**
@@ -42,8 +77,12 @@ export type UpdateInstallOutcome = {
  * arguments or switching to its default before `nvm use 22`.
  */
 export declare const NVM_RUN_SCRIPT = "n=$1; shift; . \"$n\" --no-use >/dev/null 2>&1 && nvm use 22 >/dev/null 2>&1 && \"$@\"";
-/** The install itself, also with every path and spec as data: `$1` = nvm.sh, `$2` = the npm spec. */
-export declare const NVM_INSTALL_SCRIPT = "n=$1; p=$2; . \"$n\" --no-use && nvm install 22 && nvm use 22 && npm install -g \"$p\"";
+/** Getting nvm's Node 22, before its prefix can be locked and installed into: `$1` = nvm.sh, as data. */
+export declare const NVM_PREPARE_SCRIPT = "n=$1; . \"$n\" --no-use && nvm install 22";
+/** Which Node `nvm use 22` selects: its absolute path, printed once. `$1` = nvm.sh, as data. */
+export declare const NVM_SELECT_SCRIPT = "n=$1; . \"$n\" --no-use >/dev/null 2>&1 && nvm use 22 >/dev/null 2>&1 && command -v node";
+/** Run the remaining arguments with a frozen nvm bin directory first on PATH (`$1`, as data). */
+export declare const NVM_BIN_SCRIPT = "d=$1; shift; PATH=\"$d:$PATH\"; export PATH; exec \"$@\"";
 /**
  * How to run the NEW `agend` after the install: directly, or — for an nvm install — inside nvm's Node 22, because its
  * `#!/usr/bin/env node` would otherwise pick the parent's (old) Node from PATH (#1446 item 1). Append the subcommand.
@@ -55,11 +94,15 @@ export declare function newAgendInvocation(plan: Pick<UpdateInstallPlan, "viaNvm
 /** `npm link` leaves a symlink to a source checkout outside any node_modules tree; a registry install is a directory. */
 export declare function isLocalLinkTarget(entryIsSymlink: boolean, realTarget: string): boolean;
 /**
- * The identity of what npm installed: `$1` is the package directory in npm's global root. Prints its name, version and
- * the REAL path of its `agend` bin target, so PATH's `agend` can be held to that exact file.
+ * The identity of what npm installed: `$1` is the package directory in npm's global root. Prints its name, version, the
+ * REAL path of its `agend` bin target, so PATH's `agend` can be held to that exact file, and of its canonical inner
+ * entry `dist/cli.js` (#1450 C4: what a service starts; since the launcher, not the bin).
  */
 export declare const PACKAGE_IDENTITY_SCRIPT: string;
-/** Proves the native module loads AND works: on Node 20 better-sqlite3 13 imports fine and then SIGSEGVs on open. */
+/**
+ * Proves the native module loads AND works, in the main thread and in a worker (the fleet opens databases in both):
+ * on Node 20 better-sqlite3 13 imports fine and then SIGSEGVs on open. `$1` is the package directory.
+ */
 export declare const NATIVE_CHECK_SCRIPT: string;
 /**
  * Prove the package npm installed — read from npm's own global root and prefix in the install environment — is the
@@ -67,5 +110,32 @@ export declare const NATIVE_CHECK_SCRIPT: string;
  * shebang resolves to. Used after an install, and before restarting a fleet that predates an earlier install (#1449
  * review: an update whose verification failed must not be completed by simply running `agend update` again).
  */
-export declare function verifyInstalledPackage(plan: UpdateInstallPlan, runner: CommandRunner): UpdateInstallOutcome;
+export declare function verifyInstalledPackage(plan: UpdateInstallPlan, runner: CommandRunner, npmBin?: string): UpdateInstallOutcome;
 export declare function runUpdateInstall(plan: UpdateInstallPlan, runner: CommandRunner): UpdateInstallOutcome;
+/**
+ * Has the activation POSITIVELY settled on the new install — the moment the old system copy may go? launchd: the new
+ * job was proven running. Otherwise only a restart that reported "restarted": "pending" (systemd still running the
+ * job) and "failed" keep the old copy, as does any failed activation (#1473 review).
+ */
+export declare function activationSettled(outcome: {
+    ok: true;
+    via: "restart" | "launchd-activation";
+} | {
+    ok: false;
+}, restart: "restarted" | "pending" | "failed" | null): boolean;
+/**
+ * After an nvm transition's activation SETTLED (the fleet runs the new install): remove the old system copy. Best
+ * effort, and never waits for a password. Before that point the old copy is the rollback for the old service.
+ */
+export type RetireSystemCopyResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Remove the old system npm global after an nvm transition.
+ * @param npmPath - The absolute npm path used during this install (from UpdateInstallOutcome.npmPath).
+ *   Passing undefined or a non-absolute path is a caller error and results in a failure.
+ */
+export declare function retireSystemCopy(runner: CommandRunner, npmPath?: string): RetireSystemCopyResult;