@songsid/agend 2.1.12 → 2.2.0-alpha.1

package/dist/ui/preview.js

@@ -0,0 +1,266 @@
+/*
+ * #1306: running an agent's HTML in the web chat — the parent side. Design: docs/design/1306-inline-html-preview.md.
+ *
+ * The HTML runs in a frame from a SEPARATE listener (the preview origin), sandboxed to an opaque origin, so it cannot
+ * act as the signed-in person: it has no dashboard origin, no cookie it can use, no CSRF value. It reaches the frame
+ * only by postMessage, after the frame proved it is this fleet's listener (the boot id). What it is NOT promised: that
+ * it cannot send data out — so previews are off on every device until that device opts in, and every preview carries
+ * the banner saying so.
+ *
+ * This file knows nothing about the chat, the composer, the fleet's API or navigation: the message listener below can
+ * reach the frames it made and nothing else (a test asserts it). Imported by the chat panel (#1408: the import sets globalThis.AgendPreview); also
+ * exports itself for the tests.
+ */
+(function (root, factory) {
+  "use strict";
+  var api = factory(root);
+  if (typeof module === "object" && module && module.exports) module.exports = api;
+  // The global as well: the chat imports this file for its side effect (#1408), in the browser and under the tests.
+  if (root) root.AgendPreview = api;
+})(typeof globalThis !== "undefined" ? globalThis : this, function (root) {
+  "use strict";
+
+  var LIMITS = { maxBytes: 1024 * 1024, minHeight: 40, maxHeight: 4000, readyMs: 3000, watchdogMs: 10000, resizePerSec: 10, minDelta: 2, growthFreeze: 5, growthWindowMs: 2000 };
+  var OPT_IN_KEY = "agend_html_preview";        // localStorage: "on" — this device allows previews
+  var NEVER_KEY = "agend_html_preview_never";   // sessionStorage: "1" — never preview on this device (this session)
+  var BANNER = "Previews run the agent's HTML in an isolated frame. It cannot use your login, but it may be able to send data out. Only preview content you trust. A preview can slow or freeze this tab.";
+
+  var cfg = { dashboardOrigin: "", previewOrigin: "", boot: "", reason: "" };
+  var changed = [];   // the page's "this device's choice changed" callbacks (checkbox, cards)
+  var live = new Map();   // cardKey → { key, iframe, ch, holder, state, … }   (at most one: one running preview per page)
+  var listening = false;
+
+  function now() { return root.performance && typeof root.performance.now === "function" ? root.performance.now() : Date.now(); }
+  function store(kind) { try { return root[kind] || null; } catch (e) { return null; } }
+  function utf8Bytes(s) { try { return new root.TextEncoder().encode(s).length; } catch (e) { return String(s).length * 3; } }
+  function randomCh() {
+    var b = new Uint8Array(16);
+    root.crypto.getRandomValues(b);
+    var s = "";
+    for (var i = 0; i < b.length; i++) s += (b[i] < 16 ? "0" : "") + b[i].toString(16);
+    return s;
+  }
+
+  /** What the server said about this page load (the <body data-*> attributes /ui was served with). */
+  function init(data) {
+    cfg = {
+      dashboardOrigin: String((data && data.dashboardOrigin) || ""),
+      previewOrigin: String((data && data.previewOrigin) || ""),
+      boot: String((data && data.previewBoot) || ""),
+      reason: String((data && data.previewReason) || ""),
+    };
+    if (!listening && typeof root.addEventListener === "function") {
+      root.addEventListener("message", onMessage);
+      // The opt-in is per device: another tab of this dashboard turning it off (or clearing storage) stops the
+      // previews running here at once. Turning it on elsewhere starts nothing here — only a click on Preview does.
+      root.addEventListener("storage", onStorage);
+      listening = true;
+    }
+  }
+  function onStorage(event) {
+    if (event && event.key !== OPT_IN_KEY && event.key !== null) return;   // key null: storage was cleared
+    if (!optedIn()) stopAll("off");
+    notify();
+  }
+  /** Call `fn` whenever this device's choice may have changed (here or in another tab). Returns the unsubscribe: a
+   *  chat that leaves takes its callback with it (#1408 §4), so 50 visits leave no callback behind. */
+  function onChange(fn) {
+    if (typeof fn !== "function") return function () {};
+    changed.push(fn);
+    return function () { var i = changed.indexOf(fn); if (i >= 0) changed.splice(i, 1); };
+  }
+  function listeners() { return changed.length; }
+  function notify() { for (var i = 0; i < changed.length; i++) { try { changed[i](); } catch (e) { /* one listener's error stops no other */ } } }
+
+  // ── This device's choice ────────────────────────────────
+
+  function optedIn() { var s = store("localStorage"); try { return !!s && s.getItem(OPT_IN_KEY) === "on"; } catch (e) { return false; } }
+  /** Allow (or stop allowing) previews on this device. Turning it off stops every running preview at once. */
+  function setOptIn(on) {
+    var s = store("localStorage");
+    try { if (s) { if (on) s.setItem(OPT_IN_KEY, "on"); else s.removeItem(OPT_IN_KEY); } } catch (e) { /* this page only */ }
+    if (!on) stopAll("off");
+    notify();
+  }
+  function never() { var s = store("sessionStorage"); try { return !!s && s.getItem(NEVER_KEY) === "1"; } catch (e) { return false; } }
+  function setNever(on) {
+    var s = store("sessionStorage");
+    try { if (s) { if (on) s.setItem(NEVER_KEY, "1"); else s.removeItem(NEVER_KEY); } } catch (e) { /* this page only */ }
+    if (on) stopAll("off");
+    notify();
+  }
+
+  /**
+   * Whether this page may run a preview at all, and why not: the server must have chosen a preview origin for this
+   * load, the browser must really be at the origin the server believed (a proxy that rewrites Host would otherwise get
+   * a frame from the wrong place), and the device must have opted in and not switched previews off.
+   */
+  function availability() {
+    if (!cfg.previewOrigin || !cfg.boot) return { ok: false, why: "server", reason: cfg.reason || "Previews are not available here." };
+    var at = root.location && root.location.origin;
+    if (!cfg.dashboardOrigin || at !== cfg.dashboardOrigin) {
+      return { ok: false, why: "origin", reason: "Previews are off: this page is at " + at + ", but the fleet believes it is at " + (cfg.dashboardOrigin || "an unknown address") + " (a proxy that rewrites Host). Pass the external Host through, or set web.preview_origin." };
+    }
+    if (never()) return { ok: false, why: "never", reason: "Previews are switched off on this device for this session." };
+    if (!optedIn()) return { ok: false, why: "optin", reason: "Previews are off on this device. Allow them from the card's menu or the sidebar." };
+    return { ok: true, why: "", reason: "" };
+  }
+
+  // ── The frame ───────────────────────────────────────────
+
+  /**
+   * The ONE place the dashboard makes an iframe or writes `sandbox` (a test fails if anything else does):
+   * opaque origin (allow-scripts only — never allow-same-origin, forms, popups, top navigation, modals, downloads),
+   * no permissions, no referrer, from <preview origin>/frame — the only URL the dashboard's frame-src allows.
+   */
+  function mountPreview(doc) {
+    var f = doc.createElement("iframe");
+    f.setAttribute("sandbox", "allow-scripts");
+    f.setAttribute("allow", "");
+    f.setAttribute("referrerpolicy", "no-referrer");
+    f.setAttribute("loading", "eager");
+    f.setAttribute("title", "Untrusted HTML preview");
+    f.className = "preview-frame";
+    f.src = cfg.previewOrigin + "/frame";
+    return f;
+  }
+
+  /**
+   * Run `html` in `holder` (a node of the card) for `key`. `ui` is told what happened: ui.state(name, reason) with
+   * "starting" | "running" | "stopped" | "unavailable". One preview at a time: any other running one stops first.
+   */
+  function start(key, holder, html, ui) {
+    var a = availability();
+    if (!a.ok) { ui.state("unavailable", a.reason); return false; }
+    if (typeof html !== "string" || utf8Bytes(html) > LIMITS.maxBytes) { ui.state("unavailable", "This HTML is over 1 MiB; it is not previewed."); return false; }
+    stopAll("another");
+    var doc = holder.ownerDocument;
+    var iframe = mountPreview(doc);
+    var card = {
+      key: key, iframe: iframe, ch: randomCh(), holder: holder, html: html, ui: ui, rendered: false,
+      height: LIMITS.minHeight, lastApplied: -Infinity, appliedInSecond: [], frozen: false, growth: [], pendingFrame: false,
+      readyTimer: null, watchdogTimer: null,
+    };
+    live.set(key, card);
+    card.readyTimer = root.setTimeout(function () {
+      if (live.get(key) === card && !card.rendered) stop(key, "unavailable", "Preview unavailable: the preview did not answer within 3 s. If an earlier preview froze, it may still be running — open the dashboard in a new tab. Over SSH, forward the preview port too.");
+    }, LIMITS.readyMs);
+    holder.appendChild(iframe);
+    setHeight(card, LIMITS.minHeight);
+    ui.state("starting", "");
+    return true;
+  }
+
+  function setHeight(card, px) { card.height = px; card.iframe.style.height = px + "px"; }   // CSSOM — never a style attribute
+
+  function armWatchdog(card) {
+    if (card.watchdogTimer) root.clearTimeout(card.watchdogTimer);
+    card.watchdogTimer = root.setTimeout(function () {
+      if (live.get(card.key) !== card) return;
+      // Best effort: a frame that froze this tab freezes this timer too. Only while the page is visible.
+      var hidden = root.document && root.document.visibilityState === "hidden";
+      if (hidden) { armWatchdog(card); return; }
+      stop(card.key, "stopped", "The preview stopped answering, so it was closed.");
+    }, LIMITS.watchdogMs);
+  }
+
+  /** Stop the preview for `key`: remove its frame and its timers. A preview is never moved or reloaded silently. */
+  function stop(key, state, reason) {
+    var card = live.get(key);
+    if (!card) return false;
+    live.delete(key);
+    if (card.readyTimer) root.clearTimeout(card.readyTimer);
+    if (card.watchdogTimer) root.clearTimeout(card.watchdogTimer);
+    if (card.iframe.parentNode) card.iframe.parentNode.removeChild(card.iframe);
+    card.ui.state(state || "stopped", reason || "");
+    return true;
+  }
+  function stopAll(why) {
+    var keys = [];
+    live.forEach(function (_c, k) { keys.push(k); });
+    for (var i = 0; i < keys.length; i++) stop(keys[i], "stopped", why === "off" ? "Previews were switched off on this device." : why === "another" ? "Another preview started." : "");
+    return keys;
+  }
+  /** Stop every preview inside `node` (before the chat replaces, moves or removes it); returns the stopped keys. */
+  function stopIn(node) {
+    var keys = [];
+    live.forEach(function (c, k) { if (node && (node === c.holder || (typeof node.contains === "function" && node.contains(c.holder)))) keys.push(k); });
+    for (var i = 0; i < keys.length; i++) stop(keys[i], "stopped", "");
+    return keys;
+  }
+  function running(key) { return live.has(key); }
+  function liveCount() { return live.size; }
+  function liveFrame(key) { var c = live.get(key); return c ? c.iframe : null; }
+
+  // ── Messages from frames (design §4.2) ──────────────────
+
+  var KEYS = { ready: "boot,ch,type,v", resize: "ch,height,type,v", heartbeat: "ch,type,v" };
+
+  /**
+   * The only window message listener. A message counts only from one of OUR frames (event.source is that frame's
+   * window, and its origin is the opaque "null"), with one of three exact shapes; each has one effect, on that frame
+   * only: ready → send the HTML once (boot checked, opt-in checked again), resize → its height, heartbeat → its
+   * watchdog. It has no reference to the chat, the composer, the fleet's API, navigation or storage.
+   */
+  function onMessage(event) {
+    var card = null;
+    live.forEach(function (c) { if (event.source && event.source === c.iframe.contentWindow) card = c; });
+    if (!card || event.origin !== "null") return;
+    var d = event.data;
+    if (!d || typeof d !== "object" || Array.isArray(d) || d.v !== 1 || typeof d.type !== "string" || !Object.prototype.hasOwnProperty.call(KEYS, d.type)) return;
+    if (Object.keys(d).sort().join(",") !== KEYS[d.type]) return;
+    if (d.type === "ready") {
+      if (d.ch !== null || typeof d.boot !== "string" || card.rendered) return;
+      if (d.boot !== cfg.boot) { stop(card.key, "unavailable", "Preview unavailable: something else answered on the preview port."); return; }
+      if (!availability().ok) { stop(card.key, "unavailable", availability().reason); return; }
+      card.rendered = true;
+      root.clearTimeout(card.readyTimer); card.readyTimer = null;
+      card.iframe.contentWindow.postMessage({ v: 1, type: "render", ch: card.ch, html: card.html }, "*");
+      armWatchdog(card);
+      card.ui.state("running", "");
+      return;
+    }
+    if (d.ch !== card.ch || !card.rendered) return;
+    if (d.type === "heartbeat") {
+      // A heartbeat never outlives the permission: if this device stopped allowing previews (and the storage event
+      // was missed), the next heartbeat ends it.
+      if (!availability().ok) { stop(card.key, "stopped", "Previews were switched off on this device."); return; }
+      armWatchdog(card);
+      return;
+    }
+    if (typeof d.height !== "number" || !isFinite(d.height) || Math.floor(d.height) !== d.height) return;
+    requestHeight(card, d.height);
+  }
+
+  /** Height rules (design §4.2): clamp to [40, 4000]; ≤ 1 per animation frame and ≤ 10 per second; Δ < 2 px ignored;
+   *  after 5 consecutive increases within 2 s the height freezes and the frame scrolls. */
+  function requestHeight(card, h) {
+    var want = Math.max(LIMITS.minHeight, Math.min(LIMITS.maxHeight, h));
+    if (Math.abs(want - card.height) < LIMITS.minDelta) return;
+    var t = now();
+    if (want > card.height) {
+      card.growth = card.growth.filter(function (x) { return t - x < LIMITS.growthWindowMs; });
+      card.growth.push(t);
+      if (card.growth.length > LIMITS.growthFreeze) card.frozen = true;
+    } else card.growth = [];
+    if (card.frozen) return;
+    card.appliedInSecond = card.appliedInSecond.filter(function (x) { return t - x < 1000; });
+    if (card.appliedInSecond.length >= LIMITS.resizePerSec) return;
+    card.wanted = want;
+    if (card.pendingFrame) return;
+    card.pendingFrame = true;
+    var raf = typeof root.requestAnimationFrame === "function" ? root.requestAnimationFrame : function (f) { return root.setTimeout(f, 16); };
+    raf(function () {
+      card.pendingFrame = false;
+      if (live.get(card.key) !== card) return;
+      card.appliedInSecond.push(now());
+      setHeight(card, card.wanted);
+    });
+  }
+
+  return {
+    init: init, availability: availability, optedIn: optedIn, setOptIn: setOptIn, never: never, setNever: setNever, onChange: onChange, listeners: listeners, onStorage: onStorage,
+    start: start, stop: stop, stopAll: stopAll, stopIn: stopIn, running: running, liveCount: liveCount, liveFrame: liveFrame,
+    mountPreview: mountPreview, onMessage: onMessage, BANNER: BANNER, LIMITS: LIMITS,
+  };
+});

package/dist/ui/settings-apply.js

@@ -0,0 +1,239 @@
+// #1408 §5: Settings' Apply belongs to the app from the moment it is confirmed. The panel hands over an operation —
+// the staged changes as data (method, URL, body, label; never a DOM closure) — before the first write, and this
+// runner performs the writes one by one, the POST /api/settings/apply (one key, made now, reused by every retry), and
+// the one watcher of its job. It publishes progress to the app store (appStore.settingsOp) and never touches a panel's
+// DOM: Settings renders from the store and re-attaches when it mounts again, the shell shows a line in any other panel.
+//
+// A write an admin must confirm (#1423) waits here, in the operation, until it is decided (settings-confirm.js).
+// Secrets (a bot token being rotated) live only inside the operation and are dropped as their write finishes, or when
+// the operation stops.
+import { appStore } from "/assets/app-store.js";
+import { t } from "/assets/app-i18n.js";
+import { toast } from "/assets/ui-toast.js";
+import "./settings-strings.js";
+import { api, confirmedWrite, newKey } from "./settings-confirm.js";
+
+const WATCH_LIMIT_MS = 10 * 60_000;
+const POST_RETRIES = [1000, 2000, 4000];
+const now = () => (typeof performance !== "undefined" ? performance.now() : Date.now());
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const ACTIVE = new Set(["writing", "posting", "watching"]);
+
+let op = null;                                   // the operation in hand (the store holds its public view)
+let seq = 0;
+
+function view() {
+  if (!op) return null;
+  return {
+    id: op.id, phase: op.phase, error: op.error, job: op.job, lostJob: op.lostJob, restart: op.restart,
+    steps: op.steps.map(({ label, impact, status, error, pendingId }) => ({ label, impact, status, error: error || null, pendingId: pendingId || null })),
+    leftover: op.leftover,
+  };
+}
+function publish() { appStore.set({ settingsOp: view() }); }
+
+/**
+ * An operation is in hand and not finished — its writes, its apply job, or a restart of AgEnD it asked for (from the
+ * press until that restart's watch ends, #1453 review): Apply stays off, and no other operation can take its place.
+ */
+export function operationActive() { return !!op && (ACTIVE.has(op.phase) || op.restart === "busy"); }
+
+/**
+ * Take over an Apply. `changes`: [{ label, impact, request: { method, url, body, sensitive? }, key? } | { label, impact,
+ * connectionSecret: { id, secret } }], in order. Returns false (and does nothing) while another operation is active.
+ * A change that brings its `key` is the retry of a write whose outcome was never learned: the same key rejoins the
+ * request the server may already hold. A `sensitive` request body (the wizard's token) is dropped when its write
+ * completes (answered, refused or failed), and such a change is never staged again.
+ */
+export function startOperation(changes) {
+  if (operationActive()) return false;
+  op = {
+    id: ++seq,
+    phase: "writing", error: null, job: null, lostJob: false, restart: "idle", leftover: [],
+    applyKey: newKey("apply"),                       // made now, before the first write; every POST retry reuses it
+    steps: changes.map((c) => ({ ...c, request: c.request ? { ...c.request } : undefined, key: c.key || newKey("write"), status: "queued" })),
+  };
+  publish();
+  run(op);
+  return true;
+}
+
+/** Forget a finished operation (its card's ×). */
+export function dismissOperation() {
+  if (op && !ACTIVE.has(op.phase) && op.restart !== "busy") { op = null; publish(); }
+}
+
+/** Unrun changes of a failed operation, as data, for the panel to stage again (secrets excluded); taken once. */
+export function takeLeftover() {
+  if (!op || !op.leftover.length) return [];
+  const out = op.leftover;
+  op.leftover = [];
+  publish();
+  return out;
+}
+
+const mine = (o) => o === op;
+
+async function run(o) {
+  for (const step of o.steps) {
+    if (!mine(o)) return;
+    step.status = "running"; publish();
+    let res;
+    // A transport failure leaves the outcome unknown: the server may have taken the write (or made it a pending
+    // request). That is not a refusal — the step keeps its key, so trying again rejoins it (#1453 review).
+    try { res = await perform(step, o); }
+    catch (err) { res = { ok: false, ambiguous: true, body: { error: err && err.message ? err.message : "network" } }; }
+    finally {
+      if (step.connectionSecret) step.connectionSecret.secret = "";
+      if (step.request && step.request.sensitive) step.request.body = null;
+    }
+    if (!mine(o)) return;
+    step.pendingId = null;
+    // The wizard's commit says when ~/.agend/.env is readable by others.
+    if (res && res.ok && res.body && res.body.secret_mode_ok === false) toast(t("settings.wizardEnvPerms"), false);
+    if (!res || !res.ok) {
+      step.status = "failed";
+      step.ambiguous = !!(res && res.ambiguous);
+      step.error = (res && res.body && (res.body.error || res.body.result)) || "failed";
+      stop(o, step);
+      return;
+    }
+    step.status = "done"; publish();
+  }
+  if (!mine(o)) return;
+  o.phase = "posting"; publish();
+  const started = await postApply(o);
+  if (!mine(o)) return;
+  if (!started) return;
+  o.job = started; o.phase = "watching"; publish();
+  await watch(o, started.id);
+}
+
+/** The step's write; a connection's token rotation is verify → apply → its own short job. */
+async function perform(step, o) {
+  if (step.request) {
+    const { method, url, body } = step.request;
+    return confirmedWrite(url, { method, body, key: step.key, label: step.label,
+      onPending: (id) => { if (mine(o)) { step.pendingId = id; step.status = "waiting"; publish(); } } });
+  }
+  if (step.connectionSecret) return rotateConnectionSecret(step, o);
+  return { ok: false, body: { error: "unknown change" } };
+}
+
+async function rotateConnectionSecret(step, o) {
+  const { id } = step.connectionSecret;
+  const base = `/api/settings/connections/${encodeURIComponent(id)}/secret`;
+  const verified = await api(`${base}/verify`, { method: "POST", headers: { "Idempotency-Key": step.key },
+    body: JSON.stringify({ secret: step.connectionSecret.secret, idempotency_key: step.key }) });
+  step.connectionSecret.secret = "";                // the server holds it from here (by verification id)
+  if (!verified.ok) return verified;
+  const applied = await confirmedWrite(`${base}/apply`, { method: "POST", key: step.key, label: step.label,
+    body: { verification_id: verified.body && verified.body.verification_id, idempotency_key: step.key },
+    onPending: (pid) => { if (mine(o)) { step.pendingId = pid; step.status = "waiting"; publish(); } } });
+  if (!applied.ok && applied.status !== 409) return applied;
+  let result = applied.body || {};
+  for (let n = 0; result.job_id && result.result === "applying" && n < 60; n++) {
+    await sleep(250);
+    const status = await api(`${base}/apply/${encodeURIComponent(result.job_id)}`).catch(() => null);
+    if (status && status.ok) result = status.body || result;
+  }
+  const ok = result.result === "applied" || result.result === "restart_required";
+  return { ok, status: ok ? 200 : 409, body: ok ? result : { error: result.error || result.result || "apply failed" } };
+}
+
+function stop(o, failed) {
+  o.phase = "failed";
+  o.error = failed ? failed.error : o.error;
+  let after = false;
+  for (const step of o.steps) {
+    if (step === failed) after = true;
+    else if (after && step.status === "queued") step.status = "skipped";
+    if (step.connectionSecret) step.connectionSecret.secret = "";
+  }
+  // What did not land can be staged again, except a secret, which has to be entered again. A write whose outcome is
+  // unknown goes back with its key; one the server refused, or that never ran, gets a new key when it is applied.
+  o.leftover = o.steps.filter((s) => (s.status === "failed" || s.status === "skipped") && s.request && !s.request.sensitive)
+    .map(({ label, impact, request, stageKey, key, ambiguous }) => ({ label, impact, request, stageKey, ...(ambiguous ? { key } : {}) }));
+  publish();
+}
+
+async function postApply(o) {
+  for (let attempt = 0; ; attempt++) {
+    let res;
+    try {
+      res = await api("/api/settings/apply", { method: "POST", headers: { "Idempotency-Key": o.applyKey },
+        body: JSON.stringify({ idempotency_key: o.applyKey }) });
+    } catch {
+      // The answer was lost (a phone between networks): the same key rejoins the same job, never a second one.
+      if (!mine(o)) return null;
+      if (attempt < POST_RETRIES.length) { await sleep(POST_RETRIES[attempt]); if (!mine(o)) return null; continue; }
+      res = { ok: false, status: 0, body: { error: "network" } };
+    }
+    if (!mine(o)) return null;
+    if (res.status === 409) { o.phase = "failed"; o.error = "busy"; publish(); return null; }
+    if (!res.ok || !res.body || !res.body.id) { o.phase = "failed"; o.error = (res.body && res.body.error) || "failed"; publish(); return null; }
+    return res.body;
+  }
+}
+
+/** GET is the authority; a restart takes the server away under the request, which is the middle of it, not the end. */
+async function watch(o, id) {
+  const deadline = now() + WATCH_LIMIT_MS;
+  let current = o.job;
+  while (current && current.status === "running" && now() < deadline) {
+    await sleep(1000);
+    if (!mine(o)) return;
+    let res;
+    try { res = await api(`/api/settings/apply/${encodeURIComponent(id)}`); } catch { continue; }
+    if (!mine(o)) return;
+    // The job outlives the process that made it, so a 404 means it aged out of the store, not that it never ran.
+    if (res.status === 404) { o.lostJob = true; o.phase = "done"; publish(); return; }
+    if (!res.ok || !res.body || !res.body.id) continue;
+    current = res.body; o.job = current; publish();
+  }
+  if (!mine(o)) return;
+  o.phase = "done"; publish();
+  // Said once, wherever the person is now: a restart reminder and a partial result are errors, a clean apply is not.
+  const rows = (current && current.targets) || [];
+  const failed = rows.some((r) => r.status === "failed"), restart = rows.some((r) => r.status === "restart-required");
+  if (!o.lostJob) toast(t(failed ? "settings.applyPartial" : restart ? "settings.applyRestartNeeded" : "settings.changesApplied"), !(failed || restart));
+}
+
+/**
+ * A full AgEnD restart for a job that needs one: its own confirmation (the caller's), its own key, one at a time. The
+ * job's fleet row moves to "running" on the server; that job is watched again.
+ */
+export async function restartFleet(forJob) {
+  const o = op;
+  if (!o || !o.job || o.restart === "busy" || ACTIVE.has(o.phase)) return { ok: false };
+  // A confirmation given for one job never restarts for another (the operation was replaced meanwhile).
+  if (forJob && (forJob.opId !== o.id || forJob.jobId !== o.job.id)) return { ok: false, stale: true };
+  o.restart = "busy"; publish();
+  const key = newKey("restart");
+  let res;
+  try {
+    res = await api("/api/settings/restart-fleet", { method: "POST", headers: { "Idempotency-Key": key },
+      body: JSON.stringify({ job_id: o.job.id, confirm: "restart-agend", idempotency_key: key }) });
+  } catch { res = { ok: false, status: 0, body: null }; }
+  if (!mine(o)) return res;
+  if (!res.ok) { o.restart = "idle"; publish(); return res; }
+  toast(t("settings.restartFleetStarted"));          // when it is accepted; how it ends is said when it settles
+  const fresh = await api(`/api/settings/apply/${encodeURIComponent(o.job.id)}`).catch(() => null);
+  if (!mine(o)) return res;
+  o.job = fresh && fresh.ok && fresh.body && fresh.body.id ? fresh.body
+    : { ...o.job, status: "running", targets: o.job.targets.map((row) => (row.target === "fleet" ? { ...row, status: "running" } : row)) };
+  o.phase = "watching"; publish();
+  try { await watch(o, o.job.id); } finally { if (mine(o)) { o.restart = "idle"; publish(); } }
+  return res;
+}
+
+// Leaving while writes or the POST are still to come would lose them: the browser asks first. Once the job exists,
+// a reload re-attaches nothing but loses nothing either (the job runs on the server).
+if (typeof window !== "undefined") {
+  window.addEventListener("beforeunload", (e) => {
+    if (op && (op.phase === "writing" || op.phase === "posting")) { e.preventDefault(); e.returnValue = ""; }
+  });
+}
+
+/** For tests. */
+export function resetOperation() { op = null; publish(); }