@songsid/agend 2.3.2 → 2.3.3-beta.10

package/launcher/agend-install.cjs

@@ -24,6 +24,7 @@ var childProcess = require("child_process");
 
 var LOCK = ".agend-install.lock";
 var MARKER = "update-in-progress.json";
+var fleetServiceOwner = require("./fleet-service-owner.cjs");
 var ensurePrivateHome = require("./private-home.cjs").ensurePrivateHome;
 
 function defaultDeps() {
@@ -670,6 +671,8 @@ function main(argv, injected) {
   catch (error) { return fail("install", error.message); }
 
   log("  AgEnD installer v" + version + (upgrade ? " (upgrade)" : ""));
+  var ownerRefusal = fleetServiceOwner.updateRefusal(home, { env: deps.env, uid: deps.uid, run: deps.run });
+  if (ownerRefusal) return fail("install", ownerRefusal);
   var root = last(deps.run("npm", ["root", "-g"], { timeoutMs: 30000 }).stdout);
   var prefix = last(deps.run("npm", ["prefix", "-g"], { timeoutMs: 30000 }).stdout);
   if (!root || !prefix) {
@@ -688,6 +691,9 @@ function main(argv, injected) {
   try {
     claimed = claimMarker(home, deps, {});
     setStage(home, claimed, "downloading", { version: version }, deps);
+    // Recheck before any package repair/global install, including old update callers.
+    var ownerRecheck = fleetServiceOwner.updateRefusal(home, { env: deps.env, uid: deps.uid, run: deps.run });
+    if (ownerRecheck) return fail("install", ownerRecheck);
     var fixed = repair(root, prefix, deps);
     fixed.notes.forEach(function (n) { log("  ↺ " + n); });
     pruneStale(prefix, deps).forEach(function (n) { log("  ↺ " + n); });
@@ -785,7 +791,7 @@ function main(argv, injected) {
       var what = "the previous package (v" + preimage.version + ") and " + name + " were restored";
       if (back !== preimage.version) restored.push(bin + " reports " + (back || "nothing") + ", not v" + preimage.version);
       var outcome;
-      if (untouched) outcome = what + "; the previous service was never stopped and still runs (pid " + fleetBefore + ")";
+      if (untouched) outcome = what + "; " + fleetServiceOwner.message("survivor", { pid: fleetBefore }, fleetServiceOwner.locale(home));
       else if (fleetBefore > 0) {
         var started = startService(svc, home, deps);
         outcome = started.running ? what + "; the previous service is running (pid " + started.pid + ")"

package/launcher/fleet-service-owner.cjs

@@ -0,0 +1,150 @@
+"use strict";
+// Shared by the installed CLI and the TARGET release's installer (#2823).
+// Read-only classification: unknown ownership always refuses; this module never stops a process.
+var fs = require("fs"), path = require("path"), os = require("os"), cp = require("child_process");
+function defaults(options) {
+  var o = options || {}, env = o.env || process.env;
+  return Object.assign({
+    platform: process.platform, env: env, uid: process.getuid ? process.getuid() : -1,
+    read: function (p) { return fs.readFileSync(p, "utf8"); },
+    stat: function (p) { return fs.statSync(p); },
+    real: function (p) { return fs.realpathSync(p); },
+    link: function (p) { return fs.readlinkSync(p); },
+    lstat: function (p) { return fs.lstatSync(p); },
+    alive: function (pid) { try { process.kill(pid, 0); return true; } catch (e) { if (e.code === "ESRCH") return false; throw e; } },
+    run: function (cmd, args, opts) {
+      var r = cp.spawnSync(cmd, args, { encoding: "utf8", timeout: 5000, env: opts.env, stdio: ["ignore", "pipe", "pipe"] });
+      return { status: r.status, stdout: r.stdout || "" };
+    }
+  }, o);
+}
+function selectedService(options) {
+  var d = defaults(options);
+  if (d.platform !== "linux") return null;
+  var system = ["/etc/systemd/system/agend.service", "/usr/lib/systemd/system/agend.service", "/lib/systemd/system/agend.service"];
+  for (var i = 0; i < system.length; i++) if (present(system[i], d)) return { unit: "agend.service", user: false };
+  if (present(path.join(d.env.HOME || os.homedir(), ".config/systemd/user/com.agend.fleet.service"), d)) return { unit: "com.agend.fleet.service", user: true };
+  return null;
+}
+// existsSync also returns false for access errors and loops. Only ENOENT proves absence.
+function present(p, d) {
+  try { return d.lstat(p); } catch (e) { if (e.code === "ENOENT") return null; throw e; }
+}
+function record(p, d) {
+  var st = present(p, d);
+  if (!st) return null;
+  if (!st.isFile()) throw Error("not a regular record"); // includes dangling/self symlinks
+  return d.read(p); // disappearance after lstat is unknown, not proven absence
+}
+function processBirth(pid, d) {
+  var stat = d.read("/proc/" + pid + "/stat"), end = stat.lastIndexOf(")"), parts = stat.slice(end + 2).trim().split(/\s+/);
+  if (stat.indexOf(pid + " (") !== 0 || end < 0 || !/^\d+$/.test(parts[19] || "")) throw Error("unknown birth");
+  return { birth: parts[19], exited: parts[0] === "Z" || parts[0] === "X" };
+}
+function fingerprint(proof) { return JSON.stringify([proof.pid, proof.birth, proof.argv, proof.group]); }
+function fields(text) {
+  var out = Object.create(null);
+  text.split("\n").forEach(function (line) { var at = line.indexOf("="); if (at > 0) out[line.slice(0, at)] = line.slice(at + 1); });
+  return out;
+}
+// The process's systemd cgroup. Pure cgroup v2 lists one `0::` row; a hybrid host (WSL, older distros) lists both the
+// unified `0::` row and the v1 `N:name=systemd:` row, with the same path — the 0:: one is what systemd reports as the
+// unit's ControlGroup there too. A pure-v1 host has only the name=systemd row, or a bare `0::/` beside it (cgroup2
+// mounted but unused). Two rows of the same kind, or no usable path, stay unknown.
+function cgroup(text) {
+  var unified = null, named = null;
+  text.trim().split("\n").forEach(function (r) {
+    var m = /^(\d+):([^:]*):(.*)$/.exec(r);
+    if (!m) return;
+    if (m[1] === "0" && m[2] === "") { if (unified !== null) throw Error("unknown cgroup"); unified = m[3]; }
+    else if (m[2].split(",").indexOf("name=systemd") >= 0) { if (named !== null) throw Error("unknown cgroup"); named = m[3]; }
+  });
+  var p = unified !== null && unified !== "/" ? unified : named !== null ? named : unified;
+  if (!p || p[0] !== "/") throw Error("unknown cgroup");
+  return p;
+}
+function inside(p, group) { return !!group && group !== "/" && (p === group || p.indexOf(group + "/") === 0); }
+function processProof(pid, home, d) {
+  if (!d.alive(pid)) return null;
+  var proc = "/proc/" + pid, start = processBirth(pid, d);
+  if (start.exited) return null;
+  if (d.stat(proc).uid !== d.uid) throw Error("foreign uid");
+  var argv = d.read(proc + "/cmdline").split("\0").filter(Boolean);
+  // Concrete shipped CLI, not an arbitrary process with 'fleet start' in its title.
+  if (argv.length < 4 || argv.length > 5 || argv[2] !== "fleet" || argv[3] !== "start" || (argv.length === 5 && argv[4] !== "--direct")) throw Error("not a fleet command");
+  var entry = d.real(argv[1]);
+  if (path.basename(entry) !== "cli.js" || path.basename(path.dirname(entry)) !== "dist" || JSON.parse(d.read(path.join(path.dirname(entry), "../package.json"))).name !== "@songsid/agend") throw Error("not an AgEnD CLI");
+  // The kernel's exe link is already resolved. An update replaces the package dir that holds the private runtime,
+  // so the link then ends in " (deleted)" and realpath would throw on the old path.
+  if (!/^node(?:js)?$/.test(path.basename(d.link(proc + "/exe").replace(/ \(deleted\)$/, "")))) throw Error("not node");
+  var env = Object.create(null);
+  d.read(proc + "/environ").split("\0").forEach(function (v) { var at = v.indexOf("="); if (at > 0) env[v.slice(0, at)] = v.slice(at + 1); });
+  var declared = env.AGEND_HOME || (env.HOME ? path.join(env.HOME, ".agend") : null);
+  if (!declared || d.real(path.resolve(d.real(proc + "/cwd"), declared)) !== d.real(home)) throw Error("foreign or unreadable home");
+  var group = cgroup(d.read(proc + "/cgroup"));
+  var end = processBirth(pid, d);
+  if (start.birth !== end.birth || end.exited) throw Error("process changed during proof");
+  return { pid: pid, birth: start.birth, argv: argv, group: group };
+}
+function inspect(home, service, options) {
+  var d = defaults(options), raw, owner;
+  if (d.platform !== "linux" || !service) return { kind: "none" };
+  try {
+    var lock = path.join(home, "fleet.lock");
+    raw = record(lock, d);
+    if (raw === null) {
+      var pidText = record(path.join(home, "fleet.pid"), d);
+      if (pidText !== null) {
+        var recorded = Number(pidText.trim());
+        if (!Number.isSafeInteger(recorded) || recorded <= 1 || d.alive(recorded)) return { kind: "unknown" };
+      }
+      return { kind: "none" };
+    }
+    owner = JSON.parse(raw);
+    if (!owner || !Number.isSafeInteger(owner.pid) || owner.pid <= 1 || (owner.role !== undefined && owner.role !== "fleet") || typeof owner.nonce !== "string" || !owner.nonce) return { kind: "unknown" };
+    var proof = processProof(owner.pid, home, d);
+    if (!proof) return { kind: "none" };
+    var env = Object.assign({}, d.env);
+    if (service.user && !env.XDG_RUNTIME_DIR) env.XDG_RUNTIME_DIR = "/run/user/" + d.uid;
+    var r = d.run("systemctl", (service.user ? ["--user"] : []).concat(["show", service.unit, "--property=MainPID,ControlGroup,ActiveState,SubState,WorkingDirectory"]), { env: env, timeoutMs: 5000 });
+    if (r.status !== 0) return { kind: "unknown" };
+    // systemctl can block. Recheck the process and lock before trusting its ownership answer.
+    var after = processProof(owner.pid, home, d);
+    if (!after || fingerprint(after) !== fingerprint(proof) || record(lock, d) !== raw) return { kind: "unknown" };
+    var unit = fields(r.stdout), main = Number(unit.MainPID);
+    if (!/^\d+$/.test(unit.MainPID || "") || !unit.ActiveState || !unit.SubState || d.real(unit.WorkingDirectory) !== d.real(home)) return { kind: "unknown" };
+    // Require both the service MainPID and its cgroup to match.
+    if (main === owner.pid && inside(proof.group, unit.ControlGroup)) return { kind: "managed", pid: owner.pid, mainPid: main };
+    if (main !== 0 || !/^(?:inactive|failed)$/.test(unit.ActiveState)) return { kind: "unknown" };
+    return { kind: "outside", pid: owner.pid, unit: service.unit };
+  } catch (e) { return { kind: "unknown" }; }
+}
+var messages = {
+  en: {
+    update_outside: "Update not started: fleet PID {pid} is running outside {unit}. Run kill {pid} to request a normal stop, confirm that process has exited, then run agend start and retry agend update. No package or service definition was changed.",
+    update_unknown: "Update not started: fleet ownership could not be verified. Check fleet.lock and systemctl status to identify the fleet PID; only then stop that fleet with kill PID and confirm it has exited. Run agend start, then retry agend update. No package or service definition was changed.",
+    restart_outside: "Restart not started: fleet PID {pid} is running outside {unit}. Run kill {pid} to request a normal stop, confirm that process has exited, then run agend start. Nothing was signalled or started.",
+    restart_unknown: "Restart not started: fleet ownership could not be verified. Check fleet.lock and systemctl status to identify the fleet PID; only then stop that fleet with kill PID and confirm it has exited. Run agend start. Nothing was signalled or started.",
+    survivor: "the previously recorded fleet PID {pid} is still alive; this check does not establish which service owns it"
+  },
+  "zh-TW": {
+    update_outside: "尚未開始更新：Fleet（PID {pid}）正在 {unit} 之外執行。請執行 kill {pid} 要求正常停止，確認該程序已結束，再執行 agend start 並重試 agend update。套件與服務設定均未變更。",
+    update_unknown: "尚未開始更新：無法確認 Fleet 歸屬。請先檢查 fleet.lock 與 systemctl status，確認 Fleet 的 PID 後才執行 kill PID，並確認該程序已結束。再執行 agend start，然後重試 agend update。套件與服務設定均未變更。",
+    restart_outside: "尚未開始重新啟動：Fleet（PID {pid}）正在 {unit} 之外執行。請執行 kill {pid} 要求正常停止，確認該程序已結束，再執行 agend start。未傳送任何訊號，也未啟動任何程序。",
+    restart_unknown: "尚未開始重新啟動：無法確認 Fleet 歸屬。請先檢查 fleet.lock 與 systemctl status，確認 Fleet 的 PID 後才執行 kill PID，並確認該程序已結束。再執行 agend start。未傳送任何訊號，也未啟動任何程序。",
+    survivor: "先前記錄的 Fleet PID {pid} 仍存活；此檢查無法確認它由哪個服務管理"
+  }
+};
+function locale(home) {
+  try { var value = require("js-yaml").load(fs.readFileSync(path.join(home, "fleet.yaml"), "utf8")); if (value && value.defaults && messages[value.defaults.locale]) return value.defaults.locale; } catch (e) { /* zone fallback */ }
+  return new Date().getTimezoneOffset() === -480 ? "zh-TW" : "en";
+}
+function message(key, state, language) { return messages[language === "zh-TW" ? language : "en"][key].replace(/\{(pid|unit)\}/g, function (_, k) { return String(state[k]); }); }
+function refusal(action, home, service, options) {
+  var state;
+  try { state = inspect(home, service === undefined ? selectedService(options) : service, options); } catch (e) { state = { kind: "unknown" }; }
+  return state.kind === "outside" || state.kind === "unknown" ? message(action + "_" + state.kind, state, (options || {}).locale || locale(home)) : null;
+}
+function updateRefusal(home, options) { return refusal("update", home, undefined, options); }
+function restartRefusal(home, service, options) { return refusal("restart", home, service, options); }
+module.exports = { selectedService: selectedService, inspect: inspect, updateRefusal: updateRefusal, restartRefusal: restartRefusal, message: message, locale: locale };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@songsid/agend",
-  "version": "2.3.2",
+  "version": "2.3.3-beta.10",
   "description": "Multi-agent fleet daemon — run coding CLIs (Claude, Muse, Codex, OpenCode) from Discord or Telegram",
   "type": "module",
   "bin": {

package/dist/general-knowledge/skills/web-appearance/SKILL.canvas-worker-off.md

@@ -1,376 +0,0 @@
----
-name: web-appearance
-description: How you look on the AgEnD web dashboard — check it, change your own theme, identity card, identity colour and widgets, set an ambient effect (falling petals, click stars), and preview the result; and, for General, changing Settings → Look for the user
-roles: [general, worker, classic]
----
-
-## What it is
-
-People see you on the web dashboard: in the sidebar, at the top of your chat, on your Details page and in View. You
-can shape how you look there — **only your own look, and only on the surfaces that are yours**:
-
-| Surface | What you set | Tools |
-|---|---|---|
-| Your name and role line | display name, description | `set_display_name`, `set_description` |
-| Your status stamp | persona emoji | `set_persona_emoji` (see the `persona-emoji` skill) |
-| Your chat | theme: colours, accent, bubbles, font, background picture, working label | `set_web_theme`, `set_web_theme_asset` |
-| The whole page, while your chat is open | your theme's colours on the sidebar, the header, the usage rail (a phone: the drawer, the header, the tabs) — colours only | `set_web_theme` (`page`) |
-| Your face and ring | theme picture and accent | `set_web_theme`, `set_web_theme_asset` |
-| Your identity card | portrait, banner, tagline, bio | `set_web_theme` (`card.*`), `set_web_theme_asset` |
-| Your identity colour | the colour people find you by in the sidebar, and where it shows (name, bar, ring) | `set_web_theme` (`identity`) |
-| Your chat header strip and Details page | widgets: small panels of facts the dashboard draws | `set_web_widget`, `remove_web_widget` |
-| An ambient effect in your chat | falling petals, snow, rising lanterns, twinkles, stars where a person clicks — data only, drawn by the dashboard | `set_web_ambient`, `clear_web_ambient` |
-| Your character in Fleet → Org chart → Office | walk to a seat, a spot or a person, say a short line, hold a pose — for a few seconds (off until a person switches it on) | `office_view`, `office_set` |
-
-None of these tools takes a target: they always act on you. You can't change another instance, the dashboard's own
-chrome (beyond your colours on it while your chat is open), a person's sidebar widget, or a person's custom CSS.
-
-## For the user: Settings → Look (General, coordinators, full)
-
-If you are General (or a coordinator or full profile), you can change the user's **Settings → Look** for
-them, exactly as the page changes it: the same checks, the same refusals. Custom CSS keeps its safe rules: no remote
-URLs, assets only as `url("asset:<id>")`, at most 64 KiB. Other instances can't; they shape only their own look (the rest
-of this skill).
-
-1. **Read first:** `get_web_settings` returns a `summary` in plain words (tell the user from it), the values, and
-   `people`: the host operator and everyone who has signed in. Host settings are everyone's on this host. Custom CSS is one person's own: pass `person` as the entry whose id is the user's (`person:<adapter>:<their id>`),
-   else the host operator's are changed.
-2. **One change per call:** `set_web_settings({ person?, change })`, where `change.what` is one of:
-
-| `what` | Changes | Example |
-|---|---|---|
-| `host` | `themes_shown`, `card_size` (s/m/l), `card_sizes` ({instance: s/m/l}), `page_colours` ({instance: page/chat}), `colour_places` (name/bar/ring), `colours_off`, `sidebar_widget` ({spec, data}) — null puts one back to its default | `{ what: "host", set: { colour_places: ["name","ring"] } }` |
-| `agent_colour` | one agent's colour (`preset:<name>` or `#rrggbb`) and places; null resets each | `{ what: "agent_colour", instance: "atlas", colour: "preset:teal" }` |
-| `page_colours` | where one agent's theme colours go: `page` (the whole page), `chat` (only its chat) or `agent` (its own `page.on`) — as ⋯ → Page colours sets it | `{ what: "page_colours", instance: "atlas", choice: "chat" }` |
-| `banner_focus` | which part of one agent's cropped card banner stays in view: `focus` 0 (top) … 100 (bottom), 50 the centre; it wins over the agent's own `card.bannerFocus`; null follows the agent's again | `{ what: "banner_focus", instance: "atlas", focus: 20 }` |
-| `custom_css` | `save` (with `text`): goes **on trial**. It waits until they open the dashboard (up to 10 minutes; never opened, it goes back unseen), then goes back by itself 20 s after it is on their screen unless kept (#2198). `keep` (with `trial`: the id `save` returned — a different trial on now, say one they saved on their page since, is refused with `trial_mismatch`, never kept instead; or, kept after that 20 s ran out, it is put back in force as `use` of it), `revert` (the trial), `use` (with `version`: an earlier saved one, at once), `off` | `{ what: "custom_css", action: "save", text: "…" }`; tell them to open the dashboard and look, then `keep` (with that `trial`) only when they say so — a `keep` that comes too late (`not_on_trial`) means use `use` with the version from `get_web_settings` |
-| `ambient` | one agent's ambient effect, set for the user: `ambient` is the same spec as `set_web_ambient`'s (it replaces the one of its kind, and the agent can't change it after); `ambient: null` clears (`which`: `loop` or `click`, default both) | `{ what: "ambient", instance: "atlas", ambient: { preset: "fall", glyphs: ["🌸","❀","✿"] } }` |
-| `restore_defaults` | the host settings back to their defaults, and the person's custom CSS off | |
-
-3. **Say what changed** in the user's words (read again if unsure). A refusal says why: the same words the page would
-   show.
-
-**Only the person can do these, on the page:**
-- choose a file from their computer: add a CSS asset or a card picture;
-- this browser's own switches: custom CSS off on this device, pausing effect playback;
-- the card upload limits (fleet configuration; a raise waits for an admin's confirmation).
-
-## Look first
-
-- `get_web_appearance` — how you appear **now**, resolved exactly as the dashboard resolves it: your face and where it
-  comes from (`profile`, `theme`, `bot`, `emoji` or `initial`), your ring colour, your **identity colour**
-  (`identity_color`: the colour people find you by in the sidebar, its `source` — `person`, `agent` (your theme's
-  `identity.color`, else its `accent`), `role` (your own bot's Discord role) or `auto` — its `light` / `dark` values,
-  where it shows (`show`: `name`, `bar`, `ring`) and whose choice that is (`show_source`: `person`, `agent` or `host`),
-  and `off` when the host turned colours off), your card field by field
-  (each marked `human` or `agent`), your theme per light/dark mode after the defaults, whether a person locked it, and
-  your limits.
-- `preview_web_appearance` (`modes`: `["light"]`, `["dark"]` or both) — draws that as an SVG per mode into
-  `.agend/appearance/<mode>.svg` in your working directory, with the pictures it shows written beside it
-  (`avatar.png`, `portrait.png`, …), and returns both lists of paths. Read the SVGs for exact colours, geometry and
-  text, and the pictures as images. Only your own pictures are there.
-- `get_web_theme` — your stored theme, the token defaults it is drawn over, your uploaded pictures (`id`, `slot`), and
-  `limits` (changes left, each picture slot's size limits, your picture quota).
-
-## What wins over what
-
-- **A person's choices win.** A picture uploaded for you in View beats your theme picture. A person's card field (from
-  View's Edit profile) beats yours, field by field — leave it to them. A person can **Lock** your theme (every change
-  you try is refused with `locked`) or **Reset** it (your theme, card and pictures go; a lock stays).
-- A widget **a person placed** in one of your slots takes your values (`data`), but you can't replace or remove it
-  (`person_placed`).
-- **Each viewer decides what they see.** Anyone can turn agents' themes and widgets off for their own screens, and
-  `?safe=1` loads a page without them; they then see the default look, no widgets, and your face follows the usual order without your theme
-  picture — a picture a person uploaded for you, else your bot's avatar, your persona emoji or your first letter.
-  Don't rely on your theme to say something important.
-- The fleet can turn agent changes off entirely (`web.themes.agent_edit: false`): every change is refused with
-  `theme_editing_off`; what you stored stays.
-- A person can switch these tools off for you (`dashboard.appearance: false`; the person's web settings tools with
-  `dashboard.web_settings: false`): a call is refused saying so. Do not retry; tell them if you need it.
-
-## Change your theme
-
-`set_web_theme { set?, clear? }` — all or nothing; `set` merges into your current theme, `clear` removes dotted paths.
-Typed values only; anything else is refused with `{ errors: [{ path, problem }] }`:
-
-- `colors.light` / `colors.dark`: any of `bg`, `surface`, `text`, `text2`, `accent`, `userBubble`, `agentBubble` as
-  `#rrggbb` (or `#rgb`). **Contrast is checked per mode**: `text` at least 4.5:1 on `bg`, `surface` and both bubbles;
-  `text2` at least 4.5:1 on `bg` and `surface`; `accent` at least 3:1 on `bg` — a palette that fails is refused, naming
-  the pair.
-- `accent`: `#rrggbb` for both modes (a mode's own `accent` wins). Without `identity.color`, it is also your identity
-  colour.
-- `identity`: `{ color?, show? }`: your identity colour and where it shows.
-  - `color` is a preset (`red`, `orange`, `amber`, `lime`, `green`, `teal`, `cyan`, `blue`, `indigo`, `violet`, `pink`,
-    `slate`, each readable in light and dark) or `#rrggbb`.
-  - `show` is a list of `name`, `bar` and `ring` (`[]` for nowhere). Left out, the host's default applies (name, bar and ring).
-  - A person's choice for you in the dashboard always wins, field by field, and their Reset brings yours back.
-    `get_web_appearance` says which is in force.
-- `page` (#2196): `{ on?: true | false, sidebar?: { light?, dark? } }` — `on: true` puts your colours (bg, surface, text,
-  text2, accent; the sidebar's own colour per mode in `sidebar`, else your `bg`) on **the whole page while your chat,
-  View, Log or Details is open**: the sidebar, the header, the usage rail; on a phone the drawer, the header and the
-  tabs. Colours only: never fonts, pictures or layout, and **AgEnD's status colours** (the Needs you count, the state
-  dots, errors, the focus ring — `get_web_theme`'s `status_colors`) are never yours to change. With `on: true` the
-  contrast check adds: `text` and `text2` 4.5:1 and `accent` 3:1 on the sidebar, and every status colour 3:1 on the
-  sidebar and on `bg`. A person's choice for you (⋯ → **Page colours**: your choice, the whole page, only your chat)
-  wins; viewers with agents' themes off or `?safe=1` see the page's own look.
-- For a person's **custom CSS** (#2199): while an agent's Chat, View, Log or Details is open, `<body>` has
-  `data-agent="<instance name>"` (none elsewhere), set in the same render as the page — so a person's stylesheet can
-  follow the open agent: `body[data-agent="atlas"] { --bg-sidebar: … }`. It is the person's, not yours to set.
-- `bubble`: `{ radius: 0..24, border: "none" | "thin" | "accent" }`.
-- `font`: `"inter"`, `"system"` or `"mono"`.
-- `background`: `{ image: <asset id>, fit: "cover" | "contain", opacity: 0.05..1 }`.
-- `avatar`: an asset id — your face (below a person's upload).
-- `workingLabel`: 1..24 characters on one line, shown while you work instead of "is working…".
-- `card`: `{ portrait?, banner?, tagline?, bio?, bannerFocus? }` — see below.
-
-Example:
-
-```json
-{ "set": { "accent": "#7c3aed", "colors": { "dark": { "bg": "#14121f" } }, "bubble": { "radius": 12, "border": "accent" },
-  "font": "inter", "workingLabel": "Reviewing" } }
-```
-
-`reset_web_theme` puts your theme back to the default (it counts as a change).
-
-## Pictures
-
-`set_web_theme_asset { slot, file }` — `file` is a picture in **your working directory** (no symlinks; read on your side,
-never by path on the fleet). It returns `{ id }`; name that id in `set_web_theme`. Metadata such as GPS is removed, and
-the id is the hash of what is kept, so the same picture is the same id.
-
-| Slot | Types | Limits |
-|---|---|---|
-| `background` | png, jpeg, webp, gif | 512 KiB, 4096 px a side |
-| `avatar` | png, jpeg, webp, gif | 256 KiB, 4096 px a side |
-| `portrait` | png, jpeg, webp | set by the fleet (default 1024×1536, 1.5 MiB) |
-| `banner` | png, jpeg, webp | set by the fleet (default 1600×600, 768 KiB) |
-| `glyph` | png, webp, gif | 64 KiB, 128 px a side; at most 4 (for `set_web_ambient`'s `glyphs`) |
-
-A picture holds one slot: upload it again for another slot only if it is a different picture. `get_web_theme`'s
-`limits.asset_slots` has the limits in force and `limits.asset_quota` how many pictures you may keep. A picture your
-theme stops naming is deleted.
-
-## Your identity card
-
-`card.tagline` (one line, 1..60 characters), `card.bio` (1..280 characters, at most 3 line breaks), `card.portrait` and
-`card.banner` (asset ids uploaded for those slots). Text is shown as text — never markup or links. A person may set
-their own version of any field; theirs is shown instead of yours.
-
-The card goes **inside `set`**: `set_web_theme({ set: { card: { tagline, bio, portrait, banner } } })` (a top-level
-`card` argument is refused).
-
-**Your banner is cropped: never drawn wider than 5 : 1** (on a wider screen it is centred over a blurred copy) **nor
-narrower than 9 : 4** (which crops the sides). Make it **1600×600** (the default limit) and keep faces and text
-inside the **safe area: the middle 84% of the width × 53% of the height — 1350×320** — which every card shows on every
-screen and layout. `card.bannerFocus` (0 top … 100 bottom; default 50, the centre) moves that area up or down: put a face
-near the top at `bannerFocus: 0`. A person's focus (Edit profile, or General's `set_web_settings { what: "banner_focus" }`)
-wins over yours. `preview_web_appearance` draws the banner cropped at its focus, as the page does (an M card).
-
-**In your chat** the card is hidden until the person shows it (the card menu in the chat header: Show card, Show picture
-and bio). Shown, the banner sits right under the header and they can fold your portrait, tagline and bio away, keeping
-only the banner. Their choice,
-kept on their device; you cannot change it. So a banner that says who you are on its own reads well in your chat too.
-
-## Your identity colour
-
-The colour people find you by in the sidebar, drawn on your name, a bar at your row's left edge and/or the ring around
-your picture. Set yours with `set_web_theme({ set: { identity: { color, show } } })` (see Change your theme).
-
-- **Which colour shows**, first match wins: a **person's** pick for you (⋯ → Colour… or View's Edit profile, also from a
-  temporary public link) > **yours** (`identity.color`, else your theme's `accent`; only for a viewer who shows agents'
-  themes) > your own bot's Discord **role** colour > an **automatic** soft colour chosen from your name (two instances
-  may share one).
-- **Where it shows**: a person's choice for you > yours (`identity.show`; again only while themes are shown) > the
-  host's default (Settings → Look; name, bar and ring unless changed).
-- The host can **turn colours off** for everyone: nothing is drawn, and every pick, yours included, is kept for when
-  they come back.
-- `get_web_appearance`'s `identity_color` shows what is in force: `color`, `source` (`person`, `agent`, `role`, `auto`),
-  `light` / `dark`, `show`, `show_source` (`person`, `agent`, `host`) and `off`.
-
-## Widgets
-
-A widget is a small panel of facts the dashboard draws **with its own components**: you send what to show and the
-values, never HTML, script, links or CSS. It takes your theme's colours and always carries a `✦ <title>` chip. Nothing
-in it can be clicked or focused.
-
-`set_web_widget { slot, spec?, data? }`:
-
-- `slot`: `chat_header` (a strip under your chat header: at most **4** items, of `stat`, `progress`, `text`, `badge`)
-  or `details` (a card on your Details page: at most **8** items, any type). `sidebar` is a person's: `owner_slot`.
-- `spec` places or replaces the widget (a change):
-  `{ v: 1, title: 1..24 characters, items: [item, …] }`, where each item is `{ type, label?, key | bind, … }`:
-
-| Type | Shows | Value | Extra |
-|---|---|---|---|
-| `stat` | a label and a number or short word | number, or 1..24 characters | `unit` (1..8 characters) |
-| `progress` | a bar and its percentage | number, 0..`max` | `max` (default 100) |
-| `text` | one line | 1..120 characters | |
-| `list` | a short list | 1..6 lines of 1..60 characters | |
-| `badge` | a coloured word | 1..24 characters | `tone`, or `tones: { word: tone }` (`ok`, `warn`, `bad`, `info`, `muted`) |
-| `spark` | a sparkline and its last number | 2..48 numbers | |
-
-  `label` (1..24 characters) is required for `stat`, `progress` and `spark`. `key` (`a-z`, `0-9`, `_`) names a value
-  in your `data`. `bind` shows a value the page already has: `state` (`working`, `idle`, `needs`, `stopped`,
-  `crashed`) on `text` or `badge`, `context_pct` on `stat` or `progress`, `cost_usd` on `stat`. Exactly one of the
-  two. A missing value shows `—`.
-- `data` alone updates the placed widget's values: merged, `null` removes a key. Values must fit every item that shows
-  them; a key no item shows is refused. Data has **its own budget**, separate from theme changes: at least **10 s**
-  apart, at most **180 an hour**.
-- The spec is at most 2048 bytes and the data at most 4096.
-
-`remove_web_widget { slot? }` takes your widget out of one slot, or both (a change). `get_web_theme` and
-`get_web_appearance` list your widgets.
-
-```json
-{ "slot": "chat_header", "spec": { "v": 1, "title": "Build", "items": [
-    { "type": "progress", "label": "Tests", "key": "tests" },
-    { "type": "badge", "label": "State", "bind": "state", "tones": { "working": "info", "needs": "warn" } },
-    { "type": "text", "key": "step" } ] },
-  "data": { "tests": 40, "step": "Running unit tests" } }
-```
-
-Then, as you go: `set_web_widget { "slot": "chat_header", "data": { "tests": 75 } }`.
-
-## Ambient effects
-
-An ambient effect is **data only**: you choose a preset and its glyphs, the dashboard draws them. No code runs, so it
-needs no Try, no preview consent and no measurement — use it for petals, snow, lanterns, sparkles and stars on a click.
-
-`set_web_ambient { preset, glyphs, colors?, count?, duration?, size?, sway?, spread?, rotate?, opacity? }`:
-
-| `preset` | What it draws | `count` | `duration` (seconds, [min, max]) |
-|---|---|---|---|
-| `fall` | glyphs drifting down behind your chat, endlessly | 1..24 particles (default 12) | 4..30 (default [9, 19]) |
-| `rise` | the same, drifting up | 1..24 (12) | 4..30 ([9, 19]) |
-| `twinkle` | glyphs pulsing in place | 1..24 (12) | 1..10 ([2, 5]) |
-| `burst-on-click` | glyphs scattering from where a person clicks or taps in your chat | 4..16 per click (10) | 0.3..2 ([0.5, 0.9]) |
-
-- `glyphs`: 1..4, picked at random per particle — a string of 1..2 characters (an emoji, `✦`, `❀`), or `{ "asset": id }`,
-  a picture you uploaded with `set_web_theme_asset` to the `glyph` slot.
-- `colors`: 0..5 `#rrggbb` for text glyphs (default: your accent). `size`: [min, max] px, 10..40 (default [14, 22]).
-  `sway`: sideways drift for fall and rise, 0..80 px (40). `spread`: how far a burst scatters, [min, max] 20..120 px
-  ([34, 90]). `rotate`: 0..720 degrees over a run (300). `opacity`: [start, peak, end], each 0..1 ([0, 0.85, 0.15]).
-- Your chat holds **one looping ambient** (`fall`, `rise` or `twinkle`) **and one `burst-on-click`**: setting one
-  replaces only its own kind. `clear_web_ambient { which? }` clears `loop`, `click`, or both.
-- It is drawn **behind your messages** and never takes a click (a burst shows over them for a moment, then is gone).
-- Who sees it: everyone who shows agents' looks, the public link included. Not with "Show agents' themes, effects and
-  widgets" off, `?safe=1`, or on a device that chose to follow the system's reduced-motion setting while
-  the system asks for it. A hidden tab pauses it.
-- Like a theme: a change for the rate limit, refused while a person locked your look; one a person set is theirs
-  (`person_placed`). A person's Reset of your theme clears it. `get_web_appearance` shows it, and
-  `preview_web_appearance` draws the looping one, still, behind the bubbles.
-
-```json
-{ "preset": "fall", "glyphs": ["🌸", "❀", "✿"], "colors": ["#f4a7b9", "#ffd1dc"], "count": 12, "duration": [9, 19] }
-```
-
-Then stars on a click, alongside: `set_web_ambient { "preset": "burst-on-click", "glyphs": ["✦", "✧"] }`.
-
-## Your character in the Office view
-
-Fleet → Org chart → **Office** draws the fleet as an office, with a little character per agent placed by its state.
-When a person switches the **office** dashboard feature on for you (`office_access: true`; off until then — the tools
-are not in your list), you can direct your own character for a moment:
-
-- `office_view { office? }`: the stored offices you are in — each `{ id, name, skin, members: [{ name, display_name?,
-  state }], spots: { seats: [{ area, index, x, y }], waypoints: [{ id, x, y }], npcs: [{ id, label, x, y }], door } }` —
-  your current `act` (or null) and `cooldown_ms` (0: you may act now). `walks: false`: the office is drawn as desks (a
-  built-in style such as pixel or studio, or a pack without zones) — no spots; `say` and `pose` show, `go` is refused.
-- `office_set { office?, go?, say?, pose?, seconds?, clear? }`: `go` is exactly one of `seat` (`"area:index"`, as
-  office_view lists it), `waypoint` (an id) or `person` (a member of the same office); `say` a line of 1..40 characters
-  (a speech bubble); `pose` one of idle, working, needs, paused; `seconds` 5..120 (default 30). `clear: true`, alone,
-  ends your act. `office` is needed only when you are in more than one.
-- Each call replaces your act. It ends when its seconds are up or you begin new work (the turn you set it in, and being
-  idle after, keep it; working again after that, or after setting it while idle, ends it); it is not shown while you
-  need a person (needs, crashed, stuck), are paused or stopped, or are asleep at bedtime — real work always shows. At most **6 calls a minute** and **60 an hour**: a refusal says `cooldown_ms`.
-
-```json
-{ "go": { "person": "atlas" }, "say": "Review's ready", "seconds": 20 }
-```
-
-## Office skin packs (everyone's)
-
-The Office view draws offices in **skin packs**, which every viewer on the fleet sees. When a person switches the
-**office_packs** dashboard feature on for you (`office_pack_access: true`, its own switch — off until then, and the
-tools are not in your list), you can publish them yourself instead of asking a person to upload each fix by hand:
-
-- `office_pack_list {}` first: each pack's `id`, `name`, `files`, `bytes`, `version`, `previous` (a kept previous
-  version you can restore, or null) and the `offices` drawn in it; the stored offices and their style; the fleet's
-  `approval` (`"apply"`: at once; `"approve"`: a fleet admin's yes first — the default); your `pending` changes; the
-  `limits` and what is `left` of your hour.
-- `office_pack_check { dir }` runs the host's own checks and stores nothing: `{ result: "PACK OK", packs: [...] }` or the
-  first refusal. `dir` is a folder with its `manifest.json` and the PNGs at the paths the manifest names, in your working
-  directory or the fleet's shared folder (`~/.agend/shared`); a symlink is followed and must stay inside. Only those
-  files are read. Or `manifest` (the object) + `files` (`{ "<name it uses>": "<path>" }`); `packs: [...]` for several.
-- `office_pack_upload` (the same inputs) keeps it — an id the fleet keeps is **replaced** at once (no delete first; on
-  any failure the old one stays) and its previous version is kept. If a stored office's layout overrides would no
-  longer fit (a seat count changed, a seat left its area, an item is gone), check and upload refuse with the office
-  and the rule: fix the pack, or send `drop_invalid_overrides: true` to drop exactly those entries (the result names
-  them). With `"approve"` the answer is `{ pending }`: it waits for an admin's yes — say so; do not upload it again. A pending change that drops layout entries is applied
-  only if it still drops exactly the entries its notice named: if an office was edited meanwhile, the approval is
-  refused and you send the change again (#2695).
-- `office_pack_restore { id }` brings back the previous version (the replaced one becomes the previous);
-  `office_pack_delete { id, keep_previous? }`; `office_set_style { office, pack }` points a stored office at a pack or a
-  built-in style (pixel, studio, cozy).
-- Every change is logged with each picture's sha256 and told to the fleet's admins. At most **20 batches and 200 MiB an
-  hour**: one call is one batch (up to 16 packs), so send a whole set of fixes in one `packs: [...]`.
-- `office_pack_check` has its own allowance: at most **60 checks and 1 GiB (as sent) an hour**. Every check counts,
-  passed or refused, so fix what a refusal names before checking again. `office_pack_list` shows `check_left`.
-
-The skin-pack manifest format — every key, its ranges, a minimal example — and the limits are in the Office guide:
-[docs/office.md → Make a skin pack](https://github.com/songsid/AgEnD/blob/main/docs/office.md#make-a-skin-pack). Point people there too when they ask how the Office works.
-
-## Limits
-
-- At least **30 s** between changes, at most **10 changes an hour** — refused with `rate_limited` and
-  `retry_after_s`. Only an accepted change counts; a refused or invalid one costs nothing.
-- Picture uploads are not counted. Each picture slot's size limits, your picture quota and
-  each file's own caps still apply; using a picture in your theme is a change.
-- Widget values (`set_web_widget` with `data` only): at least **10 s** apart, at most **180 an hour**, apart from the
-  above.
-- `set_web_ambient` and `clear_web_ambient` are changes.
-- Plan the whole look, check it in one `set_web_theme`, then preview — don't iterate change by change.
-
-## A good workflow
-
-1. `get_web_appearance` and `get_web_theme`: see where you start, whether you are locked, what you have left.
-2. Upload the pictures you need (`set_web_theme_asset`), one per slot.
-3. One `set_web_theme` with everything; fix any `errors` it names.
-4. `preview_web_appearance` and Read the SVGs for both modes. Check contrast and that your card reads well.
-
-From a shell: `agend-agent theme get|set key=value…|set --json '<patch>'|clear <path>…|asset <slot> <file>|reset`,
-`agend-agent appearance`, `agend-agent appearance preview [light|dark]`, and
-`agend-agent widget set <slot> '<spec json>' ['<data json>']|data <slot> '<data json>'|remove [slot]`,
-`agend-agent ambient set '<spec json>'|clear [loop|click]`, `agend-agent office view [office]|set '<json>'`.
-
-## Files in your working directory
-
-Asset uploads must be inside your working directory. For an external project,
-use files there as before. For your own AgEnD-managed workspace under `~/.agend/workspaces/`, ordinary files there
-also work; no staging folder is required. This includes the standard `<your-instance-name>` folder (ClassicBot and
-instances without a project directory) and an exclusively configured folder with another name, such as instance
-`alpha` with `working_directory: ~/.agend/workspaces/alpha-home` in `fleet.yaml`. Its canonical configured path must
-not overlap another instance's configured or standard workspace, including persisted ClassicBot peers that are
-stopped or paused. The `workspaces/` root itself is not a workspace.
-
-General, adapter-specific General (such as `general-telegram`), and other configured working directories elsewhere
-inside the AgEnD state directory must stage inputs under **`web-assets/`**. For example, put a banner at
-`web-assets/banner.png`, relative to that working directory. Its root
-and backend configuration folders are not upload areas. Generated previews use the fixed
-`.agend/appearance/` directory and can be read back there.
-
-The daemon uses its launch identity and configuration; the CLI resolves `AGEND_INSTANCE_NAME` against `fleet.yaml`.
-These checks require a canonical, exclusively owned directory: the state root, shared or overlapping configured
-working directories, another instance's directory, and the host's state stores never qualify. No tool argument can
-select an identity or working directory. Missing or unreadable ownership evidence refuses in-state access.
-
-Inside all admitted in-state areas, `.env`, databases and their WAL/SHM/journal files, `instances/`,
-`credential-profiles/`, `inbox/`, `web-files/`, `web-chat.json`, `chat-logs/`, backend credential/session/config files,
-and hidden files or folders are refused. The only hidden-directory exception is the generated `.agend/`
-output directory above; their contents still undergo the sensitive-name checks. Hard-linked state files are also
-refused. Copy an intended asset into staging as a new regular file; do not link a private state file there.
-
-Paths are checked after resolving symlinks. A symlink named after General or a workspace, or in its managed parent
-path, cannot widen access; uploaded files themselves must not be symlinks. Containment still applies to relative and
-absolute paths and to each uploaded file. The CLI name and current directory are controlled by its shell:
-these local checks prevent accidental uploads, but do not isolate shells running as the same OS user.