@songsid/agend 2.1.12 → 2.2.0-alpha.2

package/dist/ui/settings-wizard.js

@@ -0,0 +1,140 @@
+// #1408 step 3: the setup wizard — the same four steps as `agend quickstart`, one dialog. It pre-fills from the running
+// configuration and, when it finishes, writes the files (a write an admin may have to confirm, #1423) and hands over
+// to the ordinary Apply: the app's runner (settings-apply.js) posts the apply and watches its job, with the same
+// progress, deadline and restart recovery as every other change.
+import { html, useEffect, useState } from "/assets/app-html.js";
+import { t } from "/assets/app-i18n.js";
+import { useLease } from "/assets/app-ctx.js";
+import { Dialog } from "/assets/ui-dialog.js";
+import { api } from "./settings-confirm.js";
+import { startOperation } from "./settings-apply.js";
+import { BACKENDS, DEFAULT_SCHEMA, impactOf, toYaml } from "./settings-model.js";
+import { Select } from "./settings-dialogs.js";
+
+const tn = (k, ...v) => t(`settings.${k}`, ...v);
+const STEPS = 4;
+const post = (path, body) => api(path, { method: "POST", body: JSON.stringify(body) }).catch(() => ({ ok: false, status: 0, body: { error: tn("failed") } }));
+
+export function SetupWizard({ ctx, onClose }) {
+  const lease = useLease("wizard");
+  const [w, setW] = useState(null);
+  const [busy, setBusy] = useState("");
+  const [err, setErr] = useState("");
+  useEffect(() => {
+    (async () => {
+      const env = await api("/api/settings/quickstart/environment").catch(() => null);
+      if (!lease.current()) return;
+      const e = (env && env.body) || { backends: [], channels: [], has_fleet: false };
+      setW({ step: 1, env: e, backend: (e.backends || [])[0] || "claude-code", working_directory: "", instance_name: "agent-1",
+        platform: "telegram", token: "", token_env: "AGEND_BOT_TOKEN", group_id: "", guild_id: "", general_channel_id: "", admin_user_id: "",
+        identity: null, guilds: [], plan: null, offset: 0 });
+    })();
+  }, [lease]);
+  if (!w) return html`<${Dialog} title=${tn("wizardTitle")} onClose=${onClose}><p class="note">…</p></${Dialog}>`;
+  const set = (k) => (v) => setW((x) => ({ ...x, [k]: v }));
+  const input = () => ({
+    platform: w.platform, token_env: w.token_env, backend: w.backend, working_directory: w.working_directory, instance_name: w.instance_name,
+    group_id: w.group_id || undefined, guild_id: w.guild_id || undefined, general_channel_id: w.general_channel_id || undefined,
+    admin_user_id: w.admin_user_id || undefined,
+  });
+
+  const verify = async () => {
+    setBusy(tn("wizardVerifying")); setErr("");
+    const res = await post("/api/settings/quickstart/probe", { action: "verify", platform: w.platform, token: w.token });
+    if (!lease.current()) return;
+    const identity = (res.body && res.body.identity) || { valid: false };
+    let guilds = [];
+    if (identity.valid && w.platform === "discord") {
+      const g = await post("/api/settings/quickstart/probe", { action: "guilds", token: w.token });
+      if (!lease.current()) return;
+      guilds = (g.body && g.body.guilds) || [];
+    }
+    setBusy("");
+    setW((x) => ({ ...x, identity, guilds }));
+  };
+  const detect = async () => {
+    setBusy(tn("wizardWaitingStart")); setErr("");
+    const res = await post("/api/settings/quickstart/probe", { action: "await-telegram-start", token: w.token, offset: w.offset || 0 });
+    if (!lease.current()) return;
+    setBusy("");
+    if (!res.ok) { setErr((res.body && res.body.error) || tn("applyFailed")); return; }
+    if (res.body.found) setW((x) => ({ ...x, offset: res.body.offset, group_id: String(res.body.found.groupId), admin_user_id: String(res.body.found.userId) }));
+    else { setW((x) => ({ ...x, offset: res.body.offset })); setErr(tn("wizardNoStartYet")); }
+  };
+  const next = async () => {
+    setErr("");
+    if (w.step === 1) { if (!w.working_directory.startsWith("/")) { setErr(tn("wizardNeedDir")); return; } setW({ ...w, step: 2 }); return; }
+    if (w.step === 2) { setW({ ...w, step: 3 }); return; }
+    if (w.step === 3) {
+      if (!w.identity || !w.identity.valid) { setErr(tn("wizardNeedVerify")); return; }
+      setBusy(tn("wizardPlanLoading"));
+      const res = await post("/api/settings/quickstart/plan", input());
+      if (!lease.current()) return;
+      setBusy("");
+      if (!res.ok) { setErr((res.body && res.body.error) || tn("applyFailed")); return; }
+      setW((x) => ({ ...x, plan: res.body, step: 4 }));
+      return;
+    }
+    await finish();
+  };
+  /**
+   * Write the files, then the ordinary Apply — one operation, handed to the app before the commit is even sent
+   * (#1453 review): the commit (which may wait for an admin's confirmation), then the apply and its job. While it runs
+   * no other Apply can start, leaving the page warns. The token leaves the form now; the operation holds it in the
+ * commit's body until that write completes, then drops it.
+   */
+  const finish = () => {
+    const body = { ...input(), token: w.token };
+    // It writes the connection and the first agent: it costs what a connection change does (the server's schema).
+    const handed = startOperation([{ label: tn("wizardTitle"), impact: impactOf((ctx && ctx.schema) || DEFAULT_SCHEMA, "fleet.channels"),
+      request: { method: "POST", url: "/api/settings/quickstart/commit", body, sensitive: true } }]);
+    if (!handed) { setErr(tn("applyBusyLocal")); return; }
+    setW((x) => ({ ...x, token: "" }));
+    onClose();
+  };
+
+  let body;
+  if (w.step === 1) {
+    body = html`<div class="field"><label for="wz-be">${tn("wizardBackend")}</label>
+        <${Select} id="wz-be" value=${w.backend} onChange=${set("backend")} options=${w.env.backends && w.env.backends.length ? w.env.backends : BACKENDS} />
+        <p class="note">${w.env.backends && w.env.backends.length ? tn("wizardBackendFound", w.env.backends.join(", ")) : tn("wizardBackendNone")}</p></div>
+      <div class="field"><label for="wz-wd">${tn("workingDir")}</label><input id="wz-wd" type="text" placeholder="/home/you/projects/app" value=${w.working_directory} onInput=${(e) => set("working_directory")(e.target.value.trim())} /></div>
+      <div class="field"><label for="wz-name">${tn("wizardAgentName")}</label><input id="wz-name" type="text" value=${w.instance_name} onInput=${(e) => set("instance_name")(e.target.value.trim())} /></div>`;
+  } else if (w.step === 2) {
+    body = html`<div class="seg-inline" role="group" aria-label=${tn("wizardPlatform")}>
+        ${["telegram", "discord"].map((p) => html`<button key=${p} type="button" class=${`btn${w.platform === p ? " btn-primary" : ""}`} aria-pressed=${w.platform === p ? "true" : "false"}
+          onClick=${() => setW({ ...w, platform: p, identity: null })}>${p === "telegram" ? "Telegram" : "Discord"}</button>`)}</div>
+      <p class="note">${w.platform === "telegram" ? tn("wizardTelegramHint") : tn("wizardDiscordHint")}</p>`;
+  } else if (w.step === 3) {
+    body = html`<div class="field"><label for="wz-token">${tn("wizardToken")}</label>
+        <input id="wz-token" type="password" autocomplete="new-password" placeholder="123456:ABC-DEF…" value=${w.token} onInput=${(e) => setW({ ...w, token: e.target.value.trim(), identity: null })} />
+        <p class="note">${w.platform === "telegram" ? tn("wizardTokenTelegram") : tn("wizardTokenDiscord")}</p></div>
+      <div class="field"><label for="wz-env">${tn("tokenEnv")}</label><input id="wz-env" type="text" value=${w.token_env} onInput=${(e) => set("token_env")(e.target.value.trim())} /></div>
+      <div class="dlg-inline-actions"><button type="button" class="btn btn-sm" disabled=${!!busy} onClick=${verify}>${tn("wizardVerify")}</button>
+        ${w.identity ? html`<span class=${`feedback${w.identity.valid ? "" : " error"}`} role="status">${w.identity.valid ? (w.identity.username || tn("verified")) : (w.identity.reason || tn("verifyFailed"))}</span>` : null}</div>
+      ${w.platform === "discord" ? html`
+        <div class="field"><label for="wz-guild">${tn("guildIdField")}</label><${Select} id="wz-guild" value=${w.guild_id} onChange=${set("guild_id")}
+          options=${["", ...w.guilds.map((g) => ({ value: g.id, label: `${g.name} (${g.id})` }))]} /></div>
+        <div class="field"><label for="wz-gen">${tn("wizardGeneralChannel")}</label><input id="wz-gen" type="text" value=${w.general_channel_id} onInput=${(e) => set("general_channel_id")(e.target.value.trim())} /></div>
+        <div class="field"><label for="wz-user">${tn("wizardAdminUser")}</label><input id="wz-user" type="text" placeholder=${tn("discordUserPlaceholder")} value=${w.admin_user_id} onInput=${(e) => set("admin_user_id")(e.target.value.trim())} /></div>`
+      : html`
+        <div class="field"><label for="wz-group">${tn("groupIdField")}</label><input id="wz-group" type="text" placeholder="-1001234567890" value=${w.group_id} onInput=${(e) => set("group_id")(e.target.value.trim())} />
+          <p class="note">${tn("wizardDetectHint")}</p></div>
+        <div class="dlg-inline-actions"><button type="button" class="btn btn-sm" disabled=${!!busy} onClick=${detect}>${tn("wizardDetect")}</button></div>
+        <div class="field"><label for="wz-user">${tn("wizardAdminUser")}</label><input id="wz-user" type="text" placeholder=${tn("telegramUserPlaceholder")} value=${w.admin_user_id} onInput=${(e) => set("admin_user_id")(e.target.value.trim())} /></div>`}`;
+  } else {
+    body = !w.plan ? html`<p class="note">${tn("wizardPlanLoading")}</p>` : html`
+      <p><strong>${tn("wizardWillWrite")}</strong></p>
+      <pre class="s-yaml">${toYaml({ channels: [w.plan.channel], instances: { [w.plan.instance.name]: { working_directory: w.plan.instance.working_directory, backend: w.plan.instance.backend } } })}</pre>
+      <p class="note">${tn("wizardEnvKeys", (w.plan.env_keys || []).join(", "))}</p>
+      ${(w.plan.warnings || []).map((x, i) => html`<p key=${i} class="feedback warning">${x}</p>`)}`;
+  }
+  return html`<${Dialog} title=${tn("wizardTitle")} onClose=${onClose} wide=${true} busy=${busy === tn("wizardCommitting")}
+    actions=${html`<button type="button" class="btn" disabled=${w.step === 1 || !!busy} onClick=${() => setW({ ...w, step: w.step - 1 })}>${tn("wizardBack")}</button>
+      <button type="button" class="btn btn-primary" disabled=${!!busy} onClick=${next}>${w.step === STEPS ? tn("wizardFinish") : tn("wizardNext")}</button>`}>
+    <p class="note">${tn("wizardStep", w.step, STEPS)}${w.env.has_fleet ? ` · ${tn("wizardRerun")}` : ""}</p>
+    <div class="form">${body}</div>
+    ${busy ? html`<p class="note" role="status">${busy}</p>` : null}
+    ${err ? html`<p class="feedback error" role="alert">${err}</p>` : null}
+  </${Dialog}>`;
+}

package/dist/ui/shared/agend-auth.js

@@ -0,0 +1,93 @@
+// Shared by the panels. Loaded from /assets/agend-auth.js.
+//
+// Writes are authorized by the session cookie *and* a per-session CSRF value, which this
+// script fetches once and adds to every same-origin write. It wraps `fetch` so the panels'
+// own request code did not have to change; the shared shell (design Phase 2) replaces this.
+// It also says so — once, and without losing the page — when the session has ended.
+(() => {
+  "use strict";
+  if (window.AgendAuth) return;
+
+  // An old link carries `?token=` (e.g. /view?token=…, which is open to read and so is served, not
+  // answered with the sign-in page). It is not a credential any more, but it is still the fleet's
+  // token: take it out of the address bar and this history entry at once.
+  try {
+    const here = new URL(location.href);
+    if (here.searchParams.has("token")) {
+      here.searchParams.delete("token");
+      history.replaceState(null, "", here.pathname + here.search + here.hash);
+    }
+  } catch { /* nothing to clean */ }
+
+  // Before U2, /view kept the fleet's web token in localStorage ("agend_web_token") and sent it with every request.
+  // It is not read any more, but the token still opens every write through X-Agend-Token: remove that one key — and
+  // nothing else of the page's preferences — on any panel this browser opens. Storage can be blocked (privacy mode,
+  // a sandboxed frame); that must not stop the rest of this script.
+  try { window.localStorage.removeItem("agend_web_token"); } catch { /* no storage, nothing stored */ }
+
+  const nativeFetch = window.fetch.bind(window);
+  let csrfPending = null;
+
+  function csrf() {
+    if (!csrfPending) {
+      csrfPending = nativeFetch("/auth/session", { credentials: "same-origin", cache: "no-store" })
+        .then((r) => (r.ok ? r.json() : null))
+        .then((j) => (j && typeof j.csrf === "string" ? j.csrf : null))
+        .catch(() => null)
+        .then((value) => { if (!value) csrfPending = null; return value; });
+    }
+    return csrfPending;
+  }
+
+  let bannerShown = false;
+  function sessionEndedBanner() {
+    if (bannerShown || !document.body) return;
+    bannerShown = true;
+    const bar = document.createElement("div");
+    bar.setAttribute("role", "alert");
+    bar.style.cssText = "position:fixed;top:0;left:0;right:0;z-index:2147483647;padding:10px 16px;background:#f85149;color:#fff;font:14px system-ui,sans-serif;text-align:center";
+    const zh = /^zh/i.test(navigator.language || "");
+    bar.append(document.createTextNode(zh ? "登入已結束。" : "Your session has ended. "));
+    const link = document.createElement("a");
+    link.href = "/signin?next=" + encodeURIComponent(location.pathname + location.search);
+    link.textContent = zh ? "重新登入" : "Sign in again";
+    link.style.cssText = "color:#fff;font-weight:600;text-decoration:underline";
+    bar.append(link);
+    document.body.prepend(bar);
+  }
+
+  window.fetch = async function (input, init) {
+    const isRequest = typeof Request !== "undefined" && input instanceof Request;
+    const method = String((init && init.method) || (isRequest ? input.method : "GET")).toUpperCase();
+    let target;
+    try { target = new URL(isRequest ? input.url : String(input), location.href); } catch { return nativeFetch(input, init); }
+    const sameOrigin = target.origin === location.origin;
+    if (sameOrigin && method !== "GET" && method !== "HEAD" && method !== "OPTIONS") {
+      const value = await csrf();
+      if (value) {
+        const headers = new Headers((init && init.headers) || (isRequest ? input.headers : undefined));
+        headers.set("X-Agend-CSRF", value);
+        init = Object.assign({}, init, { headers });
+      }
+    }
+    const response = await nativeFetch(input, init);
+    if (sameOrigin && response.status === 401 && !target.pathname.startsWith("/auth/")) sessionEndedBanner();
+    return response;
+  };
+
+  window.AgendAuth = {
+    csrf,
+    async signOut() {
+      const value = await csrf();
+      const r = await nativeFetch("/auth/logout", { method: "POST", credentials: "same-origin", headers: value ? { "X-Agend-CSRF": value } : {} });
+      // A sign-out the server could not make durable is not quietly reported as done: say so before leaving.
+      if (r.status === 500) {
+        let message = "Signed out for now, but the change could not be saved — a fleet restart may sign this browser back in.";
+        try { const body = await r.json(); if (body && typeof body.error === "string") message = body.error; } catch { /* keep the default */ }
+        // Said on the sign-in page this goes to (#1408 step 5: no browser alert): the page shows it once.
+        try { sessionStorage.setItem("agend_signout_note", message); } catch { /* private mode: nothing to carry it */ }
+      }
+      location.href = "/signin";
+    },
+  };
+})();

package/dist/ui/shared/app-ctx.js

@@ -0,0 +1,80 @@
+// #1408 §4: what a panel may own while it is mounted, and nothing it can leak.
+//
+// Every navigation — a new panel, the same panel on another route (View A → B), a language switch, Retry — gets a
+// new lease. Work started under a lease asks lease.current() after EVERY await and before any DOM write, title,
+// focus or action it publishes; once the lease is superseded or disposed the answer is false and the continuation
+// does nothing. An AbortController cannot do this alone: a fetch that already has its body, or an import, still
+// resumes. Timers, listeners, fetches and stream subscriptions taken through the lease are released by dispose().
+import { useEffect, useMemo, useRef } from "./app-html.js";
+
+let leases = 0;
+const live = new Set();            // leases not yet disposed (the leak tests read leaseCount())
+
+export function createLease(timers = globalThis) {
+  const id = ++leases;
+  let alive = true;
+  const timeouts = new Set(), intervals = new Set(), offs = new Set(), aborts = new Set();
+  const lease = {
+    id,
+    current: () => alive,
+    /** setTimeout that never fires after dispose, and is cleared by it. */
+    timeout(fn, ms) {
+      if (!alive) return null;
+      const h = timers.setTimeout(() => { timeouts.delete(h); if (alive) fn(); }, ms);
+      timeouts.add(h);
+      return h;
+    },
+    interval(fn, ms) {
+      if (!alive) return null;
+      const h = timers.setInterval(() => { if (alive) fn(); }, ms);
+      intervals.add(h);
+      return h;
+    },
+    clear(h) { if (timeouts.delete(h)) timers.clearTimeout(h); if (intervals.delete(h)) timers.clearInterval(h); },
+    /** addEventListener, removed on dispose. */
+    on(target, type, fn, opts) {
+      if (!alive || !target) return () => {};
+      target.addEventListener(type, fn, opts);
+      const off = () => { if (offs.delete(off)) target.removeEventListener(type, fn, opts); };
+      offs.add(off);
+      return off;
+    },
+    /** Keep an unsubscribe function (a stream subscription, a store listener) until dispose. */
+    hold(off) { if (!alive) { off(); return off; } offs.add(off); return off; },
+    /** fetch with this lease's abort signal. The caller still checks current() after each await. */
+    fetch(url, opts = {}) {
+      const ac = new AbortController();
+      aborts.add(ac);
+      return timers.fetch(url, { ...opts, signal: ac.signal }).finally(() => aborts.delete(ac));
+    },
+    dispose() {
+      if (!alive) return;
+      alive = false;
+      live.delete(lease);
+      for (const h of timeouts) timers.clearTimeout(h);
+      for (const h of intervals) timers.clearInterval(h);
+      for (const off of [...offs]) off();
+      for (const ac of aborts) ac.abort();
+      timeouts.clear(); intervals.clear(); offs.clear(); aborts.clear();
+    },
+    /** For the leak tests: what this lease still holds. */
+    holding: () => timeouts.size + intervals.size + offs.size + aborts.size,
+  };
+  live.add(lease);
+  return lease;
+}
+
+/** Leases created and not yet disposed, across the page (the 50-mount leak tests assert this returns to its base). */
+export function leaseCount() { return live.size; }
+
+/**
+ * A panel's lease for one navigation: a new one whenever `key` changes (route, language, retry), the old one
+ * disposed before the new route's effects run, and the last one disposed on unmount.
+ */
+export function useLease(key) {
+  const prev = useRef(null);
+  // The old lease ends the moment the new navigation renders, not one effect later: nothing of A lands after B began.
+  const lease = useMemo(() => { if (prev.current) prev.current.dispose(); return (prev.current = createLease()); }, [key]);
+  useEffect(() => () => lease.dispose(), [lease]);
+  return lease;
+}

package/dist/ui/shared/app-html.js

@@ -0,0 +1,9 @@
+// #1408: the app's view layer — the vendored Preact (10.29.8) and htm (3.1.1), byte-checked against
+// vendor/vendor.json. Templates are tagged literals (html`<div class="x">…</div>`): no JSX, no build step.
+// No `style` prop anywhere (the CSP has no 'unsafe-inline' for styles): classes and tokens only.
+import { h, render, Fragment, createContext, createRef, cloneElement, toChildArray } from "./preact.module.js";
+import htm from "./htm.module.js";
+
+export { h, render, Fragment, createContext, createRef, cloneElement, toChildArray };
+export { useState, useEffect, useLayoutEffect, useRef, useMemo, useCallback, useContext, useReducer, useId } from "./preact-hooks.module.js";
+export const html = htm.bind(h);

package/dist/ui/shared/app-i18n.js

@@ -0,0 +1,95 @@
+// #1408 §4: one dictionary for the app, namespaced (app.*, chat.*, fleet.*, …). A panel registers its own namespace
+// when it loads; t("chat.send") resolves it in the chosen language and falls back to English, then to the key.
+// The language is this browser's choice (agend_lang, the key every panel has used), else the device's.
+
+const tables = { en: {}, "zh-TW": {} };
+const listeners = new Set();
+
+function stored() {
+  try { const v = localStorage.getItem("agend_lang"); return v === "en" || v === "zh-TW" ? v : null; } catch { return null; }
+}
+let current = stored() || (typeof navigator !== "undefined" && /^zh/i.test(navigator.language || "") ? "zh-TW" : "en");
+
+/** Add a namespace: `register("chat", { en: {...}, "zh-TW": {...} })`. */
+export function register(ns, byLang) {
+  for (const lang of Object.keys(tables)) {
+    for (const [k, v] of Object.entries((byLang && byLang[lang]) || {})) tables[lang][`${ns}.${k}`] = v;
+  }
+}
+
+export function lang() { return current; }
+
+/** Choose a language for this browser; every subscriber re-renders (a new navigation lease, §4). */
+export function setLang(next) {
+  if (next !== "en" && next !== "zh-TW") return;
+  current = next;
+  try { localStorage.setItem("agend_lang", next); } catch { /* this page only */ }
+  if (typeof document !== "undefined" && document.documentElement) document.documentElement.lang = next === "zh-TW" ? "zh-Hant" : "en";
+  for (const fn of listeners) fn(next);
+}
+export function onLang(fn) { listeners.add(fn); return () => listeners.delete(fn); }
+
+/** "{0} is working…" with its values filled in. Text only: callers render it as text, never as markup. */
+export function t(key, ...values) {
+  let s = tables[current][key] ?? tables.en[key] ?? key;
+  values.forEach((v, i) => { s = s.split(`{${i}}`).join(String(v)); });
+  return s;
+}
+
+register("app", {
+  en: {
+    brand: "AgEnD", fleet: "Fleet", view: "View", settings: "Settings", instances: "Instances", newInstance: "New instance",
+    collapse: "Hide the sidebar", expand: "Show the sidebar", openMenu: "Open the sidebar", closeMenu: "Close the sidebar",
+    theme: "Theme", themeSystem: "System", themeLight: "Light", themeDark: "Dark", language: "Language",
+    previews: "Allow HTML previews on this device", tour: "Tour", tourTitle: "Show the web chat tour again",
+    needsYou: "needs you", approxNote: "Read from the terminal, so approximate", chat: "Chat",
+    statusRunning: "running", statusStopped: "stopped", statusCrashed: "crashed", statusWorking: "working", statusStuck: "looks stuck", statusIdle: "idle",
+    connPolling: "Live updates paused — refreshing every 5 s", connDown: "Disconnected — trying again…", connConnecting: "Connecting…",
+    hydrating: "Loading what is open now…", hydrateFailed: "Could not load what is open now (prompts, ticks).",
+    skip: "Skip to the conversation", loadFailed: "This could not be loaded.", retry: "Try again", loading: "Loading…",
+    noInstances: "No instances yet", noInstancesHint: "Create one to start chatting.",
+    session: "Session", signIn: "Sign in", signedIn: "Signed in", signedOut: "Not signed in", thisDevice: "This device",
+    lastActive: "active {0}", justNow: "just now", minAgo: "{0} min ago", hrAgo: "{0} h ago", signOut: "Sign out",
+    signOutAll: "Sign out everywhere", devices: "Signed-in devices", expires: "Ends by {0} at the latest, or after {1} unused",
+    failed: "That did not work — try again.", close: "Close", more: "More actions", menu: "Menu",
+    pendingTitle: "Changes waiting for confirmation", pending_pending: "Waiting for confirmation", pending_applying: "Confirmed — applying…",
+    pending_applied: "Confirmed and applied", pending_rejected: "Not applied", pending_expired: "Expired — nothing was changed",
+    pending_stale: "Not applied — settings changed meanwhile", pending_failed: "Confirmed, but applying it failed",
+    pendingChat: "A fleet admin confirms this in chat (General topic).", pendingHost: "Confirm it on the host: {0}", pendingLeft: "{0} left", withdraw: "Withdraw",
+    opWriting: "Applying settings… {0}/{1}", opWaiting: "Settings: waiting for confirmation in chat", opApplying: "Applying settings…",
+    opDone: "Settings applied", opRestart: "Settings saved — AgEnD needs a restart to use them", opPartial: "Some settings were not applied",
+    opFailed: "Settings were not applied", openSettings: "Open Settings",
+    pendingSent: "Sent for confirmation — a fleet admin confirms it in chat.",
+    needsNav: "Needs you", needsTab: "Needs you", needsCount: "{0} waiting",
+    confirmTitle: "Please confirm", confirmOk: "Continue", cancel: "Cancel",
+    // The server's own wording (src/locale.ts needs.reason.*), so the web says what Discord says.
+    needs_reason_hang: "Not responding", needs_reason_exited: "Exited", needs_reason_assist: "Waiting at its terminal", needs_reason_permission: "Permission needed", needs_reason_dangerous_command: "Dangerous command waiting", needs_reason_login: "Sign-in needed", needs_reason_dialog: "Waiting at a dialog", needs_reason_terminal_input: "May be waiting for input", needs_reason_auth_paused: "Paused: sign-in needed", needs_reason_crashed: "Crashed", needs_reason_delivery_uncertain: "Could not confirm delivery", needs_reason_delivery_failed: "Delivery failed",
+  },
+  "zh-TW": {
+    brand: "AgEnD", fleet: "Fleet", view: "檢視", settings: "設定", instances: "Instances", newInstance: "新增 instance",
+    collapse: "隱藏側邊欄", expand: "顯示側邊欄", openMenu: "打開側邊欄", closeMenu: "關閉側邊欄",
+    theme: "主題", themeSystem: "跟隨系統", themeLight: "淺色", themeDark: "深色", language: "語言",
+    previews: "允許這台裝置預覽 HTML", tour: "導覽", tourTitle: "再看一次網頁聊天導覽",
+    needsYou: "等你回應", approxNote: "從終端畫面判讀，僅供參考", chat: "聊天",
+    statusRunning: "執行中", statusStopped: "已停止", statusCrashed: "已當掉", statusWorking: "工作中", statusStuck: "似乎卡住", statusIdle: "閒置",
+    connPolling: "即時更新暫停中——每 5 秒重新整理", connDown: "已斷線——正在重試…", connConnecting: "連線中…",
+    hydrating: "正在載入目前的狀態…", hydrateFailed: "無法載入目前的狀態（提示、送達標記）。",
+    skip: "跳到對話", loadFailed: "無法載入。", retry: "再試一次", loading: "載入中…",
+    noInstances: "還沒有 instance", noInstancesHint: "建立一個就能開始聊天。",
+    session: "登入狀態", signIn: "登入", signedIn: "已登入", signedOut: "尚未登入", thisDevice: "這台裝置",
+    lastActive: "{0}活動", justNow: "剛剛", minAgo: "{0} 分鐘前", hrAgo: "{0} 小時前", signOut: "登出",
+    signOutAll: "全部登出", devices: "已登入的裝置", expires: "最晚 {0} 結束；閒置 {1} 也會結束",
+    failed: "沒有成功，請再試一次。", close: "關閉", more: "更多動作", menu: "選單",
+    pendingTitle: "等待確認的變更", pending_pending: "等待確認", pending_applying: "已確認——套用中…",
+    pending_applied: "已確認並套用", pending_rejected: "未套用", pending_expired: "已逾時——沒有任何變更",
+    pending_stale: "未套用——設定在這期間已變動", pending_failed: "已確認，但套用失敗",
+    pendingChat: "由 fleet 管理員在聊天（General topic）中確認。", pendingHost: "請在主機上確認：{0}", pendingLeft: "剩 {0}", withdraw: "撤回",
+    opWriting: "正在套用設定… {0}/{1}", opWaiting: "設定：等待在聊天中確認", opApplying: "正在套用設定…",
+    opDone: "設定已套用", opRestart: "設定已儲存——需要重新啟動 AgEnD 才會生效", opPartial: "部分設定沒有套用",
+    opFailed: "設定沒有套用", openSettings: "開啟設定",
+    pendingSent: "已送出確認——由 fleet 管理員在聊天中確認。",
+    needsNav: "等你處理", needsTab: "待處理", needsCount: "{0} 件待處理",
+    confirmTitle: "請確認", confirmOk: "繼續", cancel: "取消",
+    needs_reason_hang: "沒有回應", needs_reason_exited: "已結束", needs_reason_assist: "在終端機上等待", needs_reason_permission: "需要權限", needs_reason_dangerous_command: "危險指令待確認", needs_reason_login: "需要登入", needs_reason_dialog: "停在對話框", needs_reason_terminal_input: "可能在等輸入", needs_reason_auth_paused: "已暫停：需要登入", needs_reason_crashed: "已崩潰", needs_reason_delivery_uncertain: "無法確認是否送達", needs_reason_delivery_failed: "傳送失敗",
+  },
+});

package/dist/ui/shared/app-nav.js

@@ -0,0 +1,73 @@
+// #1408 §3: navigation without reloads. Links stay real <a href>s; a plain left click on one that names a route of the
+// app is taken over (pushState), and Back/Forward follow (popstate). A modified or middle click, a download, another
+// origin, or a path that is not a page of the app is left to the browser.
+// Every navigation bumps `seq`: panels key their lease (app-ctx.js) on the route, so work from the route left behind
+// can no longer land.
+// A panel with work that leaving would lose (Settings' staged changes, §5) sets a leave guard: every navigation of
+// the app asks it first, Back/Forward included (the address bar is put back when it says no).
+import { parseRoute, legacyHashTarget } from "./app-route.js";
+import { createStore } from "./app-store.js";
+
+export const navStore = createStore({ route: null, seq: 0 });
+
+let win = null;
+let guard = null;
+let here = null;                                 // the path the app shows now (popstate has already changed the address)
+
+/**
+ * `fn(route, path)` → false keeps the app where it is. A guard that has to ask (the app's own dialog, which answers
+ * later) returns false at once and, on a yes, goes on with `navigate(path, { force: true })`. One guard at a time;
+ * returns the remover, which only removes this one.
+ */
+export function setLeaveGuard(fn) {
+  guard = fn;
+  return () => { if (guard === fn) guard = null; };
+}
+const mayLeave = (route, path) => !guard || guard(route, path) !== false;
+
+/** Start following the address bar. An old /ui#instance=<name> link becomes /ui/chat/<name> before the first render. */
+export function startRouter(w = window) {
+  win = w;
+  const legacy = legacyHashTarget(w.location.pathname, w.location.hash);
+  if (legacy) w.history.replaceState(null, "", legacy);
+  here = w.location.pathname + w.location.search;
+  navStore.set({ route: parseRoute(w.location.pathname), seq: 1 });
+  w.addEventListener("popstate", () => {
+    const route = parseRoute(w.location.pathname);
+    const path = w.location.pathname + w.location.search;
+    if (!mayLeave(route, path)) { w.history.pushState(null, "", here); return; }
+    here = w.location.pathname + w.location.search;
+    navStore.set(s => ({ route, seq: s.seq + 1 }));
+  });
+  w.document.addEventListener("click", onLinkClick);
+}
+
+/** Go to `path`. A path that is not a route of the app is a full load. `force` skips the leave guard (it said yes). */
+export function navigate(path, opts = {}) {
+  const url = new URL(path, win.location.href);
+  const route = parseRoute(url.pathname);
+  if (!route || url.origin !== win.location.origin) { win.location.assign(url.href); return; }
+  if (!opts.force && !mayLeave(route, url.pathname + url.search)) return;
+  if (url.pathname + url.search !== win.location.pathname + win.location.search) {
+    win.history[opts.replace ? "replaceState" : "pushState"](null, "", url.pathname + url.search);
+  }
+  here = url.pathname + url.search;
+  navStore.set(s => ({ route, seq: s.seq + 1 }));
+}
+
+/** The same route again (Retry, a language switch): a new lease, no history entry. */
+export function renavigate() { navStore.set(s => ({ route: s.route, seq: s.seq + 1 })); }
+
+export function onLinkClick(e) {
+  if (e.defaultPrevented || e.button !== 0 || e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) return;
+  const a = e.target && e.target.closest ? e.target.closest("a[href]") : null;
+  if (!a || (a.target && a.target !== "_self") || a.hasAttribute("download")) return;
+  // A link to a place on this page (the skip link, #main) is the browser's: it moves focus and scrolls, and is not
+  // a navigation of the app (#1425 review).
+  if ((a.getAttribute("href") || "").startsWith("#")) return;
+  const url = new URL(a.getAttribute("href"), win.location.href);
+  if (url.hash && url.pathname === win.location.pathname && url.search === win.location.search) return;
+  if (url.origin !== win.location.origin || !parseRoute(url.pathname)) return;
+  e.preventDefault();
+  navigate(url.pathname + url.search);
+}

package/dist/ui/shared/app-needs.js

@@ -0,0 +1,114 @@
+// #1386 §6.3 (#1408 step 4): browser notifications for "Needs you", per device and opt-in, desktop browsers only.
+//
+// The list itself is the app store's `needs` (SSE `needs` / the /ui/poll field — no read of its own, #1374). This
+// module only watches it, while a signed-in page is open in any panel:
+// - a notification only for an item id this page has not seen, and only while the page is hidden (a visible page
+//   shows the list; what it showed is seen);
+// - a terminal wait (awaiting_input) only once it is ≥ 5 s old, so a dialog AgEnD answers by itself never pings
+//   anyone; the list is never delayed;
+// - tag = item id, so the same item never stacks; a click focuses the tab and opens that instance's chat.
+// The toggle asks Notification.requestPermission() on that click only. Not offered on a phone (the constructor is
+// missing or throws there; Discord's notification is the one to rely on) or on a plain-HTTP LAN address.
+import { appStore, createStore } from "./app-store.js";
+import { t } from "./app-i18n.js";
+
+const STORE_KEY = "agend_needs_notify";
+const TERMINAL_WAIT_MS = 5000;
+const now = () => Date.now();          // item.since is the server's epoch ms: an age compares wall clocks
+
+/** Why notifications cannot be offered here, or "ok". */
+export function notifySupport(env = globalThis) {
+  if (typeof env.Notification !== "function") return "unsupported";
+  const ua = (env.navigator && env.navigator.userAgent) || "";
+  if (/Android|iPhone|iPad|iPod|Mobile/i.test(ua)) return "mobile";
+  if (env.isSecureContext === false) return "insecure";
+  return "ok";
+}
+
+function stored() { try { return localStorage.getItem(STORE_KEY) === "1"; } catch { return false; } }
+function store(on) { try { if (on) localStorage.setItem(STORE_KEY, "1"); else localStorage.removeItem(STORE_KEY); } catch { /* this page only */ } }
+
+/** On: chosen on this device and still permitted by the browser. */
+export function notifyOn(env = globalThis) {
+  return notifySupport(env) === "ok" && stored() && env.Notification.permission === "granted";
+}
+
+/**
+ * The choice as the page knows it, for every toggle mounted now or later (#1463 review: a toggle that mounted while a
+ * permission request was open must still learn its answer). `state`: "on" | "off" | "denied"; `asking` while the
+ * browser's permission prompt is open (the toggle is off meanwhile, and a second click asks nothing).
+ */
+export const notifyStore = createStore({ state: (() => { try { return notifyOn() ? "on" : "off"; } catch { return "off"; } })(), asking: false });
+export function refreshNotify(env = globalThis) {
+  notifyStore.set((s) => ({ ...s, state: notifyOn(env) ? "on" : s.state === "denied" ? "denied" : "off" }));
+}
+
+/** The toggle: asks the browser on this click only. Resolves to the state after it ("on", "denied", "off"). */
+export async function setNotify(on, env = globalThis) {
+  if (notifyStore.get().asking) return notifyStore.get().state;
+  if (!on) { store(false); notifyStore.set({ state: "off", asking: false }); return "off"; }
+  if (notifySupport(env) !== "ok") return "off";
+  let permission = env.Notification.permission;
+  if (permission !== "granted") {
+    notifyStore.set((s) => ({ ...s, asking: true }));
+    try { permission = await env.Notification.requestPermission(); } catch { permission = "denied"; }
+  }
+  const state = permission === "granted" ? "on" : "denied";
+  store(state === "on");
+  notifyStore.set({ state, asking: false });
+  return state;
+}
+
+export const reasonText = (item) => t(`app.needs_reason_${item.reason}`);
+
+let stop = null;
+
+/**
+ * Follow the store for the life of the page (full mode only). `open(instance)` is how a click opens a chat.
+ * Returns the stop function (for tests); a second start replaces the first.
+ */
+export function startNeedsNotifier({ open, env = globalThis } = {}) {
+  if (stop) stop();
+  const seen = new Set();
+  const timers = new Map();                       // id → a terminal wait's 5-s check
+  const doc = env.document;
+  const hidden = () => !!(doc && doc.hidden);
+  const notify = (item) => {
+    seen.add(item.id);
+    if (!notifyOn(env)) return;
+    try {
+      const n = new env.Notification(item.instance, { body: item.detail ? `${reasonText(item)}: ${item.detail}` : reasonText(item), tag: item.id });
+      n.onclick = () => { try { env.focus && env.focus(); } catch { /* ignore */ } if (open) open(item.instance); n.close(); };
+    } catch { /* a browser that refuses at the last moment: the list still shows it */ }
+  };
+  const consider = (items) => {
+    const listed = new Set(items.map((i) => i.id));
+    for (const [id, h] of timers) if (!listed.has(id)) { clearTimeout(h); timers.delete(id); }
+    for (const item of items) {
+      if (seen.has(item.id) || timers.has(item.id)) continue;
+      if (!hidden()) { seen.add(item.id); continue; }
+      const wait = item.type === "awaiting_input" ? TERMINAL_WAIT_MS - (now() - item.since) : 0;
+      if (wait > 0) {
+        timers.set(item.id, setTimeout(() => {
+          timers.delete(item.id);
+          const still = (appStore.get().needs || []).find((i) => i.id === item.id);
+          if (!still || seen.has(item.id)) return;
+          if (hidden()) notify(still); else seen.add(item.id);
+        }, wait));
+      } else notify(item);
+    }
+  };
+  // Coming back to the page: what is listed now has been seen.
+  const onVisible = () => { if (!hidden()) for (const i of appStore.get().needs || []) seen.add(i.id); };
+  if (doc && doc.addEventListener) doc.addEventListener("visibilitychange", onVisible);
+  consider(appStore.get().needs || []);
+  const off = appStore.subscribe((s) => consider(Array.isArray(s.needs) ? s.needs : []));
+  stop = () => {
+    off();
+    if (doc && doc.removeEventListener) doc.removeEventListener("visibilitychange", onVisible);
+    for (const h of timers.values()) clearTimeout(h);
+    timers.clear();
+    stop = null;
+  };
+  return stop;
+}