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

package/dist/fleet-traffic.d.ts

@@ -0,0 +1,38 @@
+import type { FleetConfig } from "./types.js";
+import type { OutboxDelivery, OutboxState } from "./delivery-outbox.js";
+export type TrafficKind = "task" | "report" | "query" | "update" | "send" | "broadcast";
+export type TrafficState = "queued" | "delivering" | "delivered" | "consumed" | "failed" | "uncertain" | "cancelled";
+export interface TrafficItem {
+    id: string;
+    from: string;
+    to: string;
+    kind: TrafficKind;
+    state: TrafficState;
+    at: string;
+    op?: string;
+}
+/** Finished: the item stays a short while (it fades on the page), then leaves. */
+export declare const TRAFFIC_FINISHED: ReadonlySet<TrafficState>;
+/** How long a finished item stays in the snapshot, and how many items a snapshot holds at most. */
+export declare const TRAFFIC_RECENT_MS = 120000;
+export declare const TRAFFIC_SNAPSHOT_MAX = 200;
+export declare const trafficId: (deliveryId: string) => string;
+/** The item for a delivery row in `state` (default: the row's own), or null when it is not shown. */
+export declare function trafficItem(row: OutboxDelivery, fleet: Pick<FleetConfig, "defaults" | "instances"> | null | undefined, at: string, state?: OutboxState | "consumed"): TrafficItem | null;
+/**
+ * The traffic the fleet keeps in memory for a snapshot: each item's latest state, by id. Finished items are dropped
+ * TRAFFIC_RECENT_MS after they finished; at most TRAFFIC_SNAPSHOT_MAX are kept (the oldest go first).
+ */
+export declare class TrafficLog {
+    private readonly monotonic;
+    private readonly items;
+    constructor(monotonic?: () => number);
+    /** Record an item; returns it when it is news (a new id, or a new state for one), else null. */
+    note(item: TrafficItem): TrafficItem | null;
+    /**
+     * In flight now and recently finished: the pending rows' items first (the outbox is the truth for what is still
+     * moving), then the recent finished ones; newest last, at most TRAFFIC_SNAPSHOT_MAX.
+     */
+    snapshot(pending: readonly TrafficItem[]): TrafficItem[];
+    private prune;
+}

package/dist/fleet-traffic.js

@@ -0,0 +1,96 @@
+/**
+ * #1918: live cross-instance traffic for the org canvas — what the delivery outbox already records, as a small item the
+ * page can draw: who sends what kind of message to whom, and how far it got. No new probe: items are made where the
+ * outbox already changes a row (admission, its "state" events, a consumed mark), from the row the listener already has.
+ *
+ * - Only messages between instances: send_to_instance and what is built on it (delegate_task, report_result,
+ *   request_information) and broadcast. Fleet-generated notices (system, reply-obligation, outcome) are not traffic.
+ * - Never a delivery id or any text: an opaque id (a hash of the delivery id) and the two instance names. A broadcast's
+ *   items (one row per recipient) share an opaque `op`, so the page can draw them as one fan-out.
+ * - An instance whose cross_instance_visibility is "hidden" takes no part: a message to or from it is not shown.
+ */
+import { createHash } from "node:crypto";
+import { crossInstanceVisibility } from "./cross-instance-notice.js";
+/** The row kinds that are messages between instances (outbound-handlers: send_to_instance's family, broadcast). */
+const MESSAGE_KINDS = new Set(["fleet_inbound", "steer", "broadcast"]);
+const REQUEST_KINDS = { task: "task", report: "report", query: "query", update: "update" };
+const STATES = {
+    queued: "queued", retry_wait: "queued",
+    delivering: "delivering", submission_started: "delivering", reconciliation_pending: "delivering",
+    delivered: "delivered", consumed: "consumed",
+    failed: "failed", uncertain: "uncertain", cancelled: "cancelled",
+};
+/** Finished: the item stays a short while (it fades on the page), then leaves. */
+export const TRAFFIC_FINISHED = new Set(["delivered", "consumed", "failed", "uncertain", "cancelled"]);
+/** How long a finished item stays in the snapshot, and how many items a snapshot holds at most. */
+export const TRAFFIC_RECENT_MS = 120_000;
+export const TRAFFIC_SNAPSHOT_MAX = 200;
+export const trafficId = (deliveryId) => createHash("sha256").update(deliveryId).digest("hex").slice(0, 16);
+/** The item for a delivery row in `state` (default: the row's own), or null when it is not shown. */
+export function trafficItem(row, fleet, at, state) {
+    if (!MESSAGE_KINDS.has(row.kind))
+        return null;
+    const from = row.sourceInstance, to = row.targetInstance;
+    if (!from || !to || from === to)
+        return null;
+    if (crossInstanceVisibility(fleet, from) === "hidden" || crossInstanceVisibility(fleet, to) === "hidden")
+        return null;
+    const mapped = STATES[state ?? (row.reconciliationPending ? "reconciliation_pending" : row.state)];
+    if (!mapped)
+        return null;
+    const meta = row.payload?.meta;
+    const kind = row.kind === "broadcast" ? "broadcast"
+        : typeof meta?.request_kind === "string" && Object.prototype.hasOwnProperty.call(REQUEST_KINDS, meta.request_kind) ? REQUEST_KINDS[meta.request_kind] : "send";
+    return { id: trafficId(row.deliveryId), from, to, kind, state: mapped, at, ...(kind === "broadcast" ? { op: trafficId(`op:${row.operationId}`) } : {}) };
+}
+/**
+ * The traffic the fleet keeps in memory for a snapshot: each item's latest state, by id. Finished items are dropped
+ * TRAFFIC_RECENT_MS after they finished; at most TRAFFIC_SNAPSHOT_MAX are kept (the oldest go first).
+ */
+export class TrafficLog {
+    monotonic;
+    items = new Map();
+    constructor(monotonic = () => performance.now()) {
+        this.monotonic = monotonic;
+    }
+    /** Record an item; returns it when it is news (a new id, or a new state for one), else null. */
+    note(item) {
+        const prev = this.items.get(item.id);
+        if (prev && prev.item.state === item.state)
+            return null;
+        // A finished item never goes back to an earlier state (events can arrive out of order across listeners).
+        if (prev && TRAFFIC_FINISHED.has(prev.item.state) && !TRAFFIC_FINISHED.has(item.state))
+            return null;
+        if (prev && prev.item.state === "consumed")
+            return null;
+        this.items.delete(item.id);
+        this.items.set(item.id, { item, seenMs: this.monotonic() });
+        this.prune();
+        return item;
+    }
+    /**
+     * In flight now and recently finished: the pending rows' items first (the outbox is the truth for what is still
+     * moving), then the recent finished ones; newest last, at most TRAFFIC_SNAPSHOT_MAX.
+     */
+    snapshot(pending) {
+        this.prune();
+        const out = new Map();
+        for (const p of pending)
+            out.set(p.id, p);
+        for (const { item } of this.items.values())
+            if (TRAFFIC_FINISHED.has(item.state) && !out.has(item.id))
+                out.set(item.id, item);
+        const all = [...out.values()];
+        return all.slice(Math.max(0, all.length - TRAFFIC_SNAPSHOT_MAX));
+    }
+    prune() {
+        const now = this.monotonic();
+        for (const [id, e] of this.items) {
+            if (TRAFFIC_FINISHED.has(e.item.state) ? now - e.seenMs > TRAFFIC_RECENT_MS : now - e.seenMs > 24 * 3_600_000)
+                this.items.delete(id);
+        }
+        while (this.items.size > TRAFFIC_SNAPSHOT_MAX * 2)
+            this.items.delete(this.items.keys().next().value);
+    }
+}
+//# sourceMappingURL=fleet-traffic.js.map

package/dist/fleet-traffic.js.map

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

package/dist/general-knowledge/skills/credential-profiles/SKILL.md

@@ -177,18 +177,33 @@ Say "the default login", not "no subscription".
 `get_usage` returns one row per subscription: `Kiro (work)` and
 `Kiro (personal)` rather than a single `Kiro`. Read them out separately — they
 are two quotas, and adding them together would give a number that is true of
-neither. An agent with no profile appears under the plain `Kiro` row. Codex works
-the same way: `Codex (<profile>)` rows next to the plain `Codex`.
+neither. An agent with no profile appears under the plain `Kiro` row (shown only
+while some instance still uses the default login). Codex works the same way:
+`Codex (<profile>)` rows next to `Codex (default)`.
 
 Claude Code also has a row per profile: `Claude (work)`, `Claude (personal)`,
-next to the plain `Claude` for the default login. A profile reads quota from its
-own login; a profile that is configured but has never been signed in shows
-**Not logged in — run `/login claude-code <profile>` to sign in**.
+next to the plain `Claude` for the default login (again only while some instance
+uses it). A profile reads quota from its own login; a profile that is configured
+but has never been signed in shows **Not logged in — sign in with
+`/login claude-code <profile>`** (in chat, it adds the host command too).
+
+On the web dashboard's usage card (#2014) the title line says just the
+provider — "Claude", "Codex", "Kiro" — with the plan badge, and the profile
+name sits on its own line under it; the full `Claude (work)` is the tooltip.
+`get_usage` and the chat's `/usage` still call the row `Claude (work)`, so name
+the profile the way the user sees it on the screen they are looking at.
 
 A kiro profile that is configured but has never been logged in still gets a row,
 reading **Signed out — run `kiro-cli` to log in**. That is the reminder to go
 and log it in, so report it as such rather than as a missing subscription.
 
+## "Is the prompt cache costing us?"
+
+`get_cache_report({ window?, instance?, top? })` is the dashboard's **Fleet → cache** report.
+- **What a row has:** each instance's cache TTL as written and its 5m/1h write mix, the TTL it really behaves as (`effective_ttl`, with the gap-miss rate it is measured from), its expiry cost, and the keep-warm simulation and recommendation.
+- **When to look:** when someone asks why costs rose, whether to keep caches warm, or whether to set `backend_options.claude-code.prompt_cache_ttl: "1h"`. A row recommending `switch_to_1h` is the answer to the last one.
+- **What you can see:** as General you see every instance and the fleet summary.
+
 ## What to tell the user
 
 - Two agents with the same profile name share one login and one quota.

package/dist/general-knowledge/skills/multi-channel/SKILL.md

@@ -61,7 +61,7 @@ The `channel_id` field explicitly binds a general to an adapter. Without it, mat
 
 The dashboard's web chat is one more way in, not a `channels:` entry: its messages reach an instance as
 `[user:… via web, …]` and are answered with `reply` like any other. By default each is also copied to the
-instance's own topic (`web.echo_to_channel: false` turns that off; ClassicBot rooms only with `web_echo: true`).
+instance's own topic (`web.echo_to_channel: false` turns that off; a ClassicBot room follows it unless its own `web_echo` is set — `false` keeps that room off).
 
 ## Single → Multi Migration
 

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

@@ -1,7 +1,7 @@
 ---
 name: web-appearance
-description: How you look on the AgEnD web dashboard — check it, change your own theme, identity card and widgets, preview the result, share it as a mod
-roles: [worker]
+description: How you look on the AgEnD web dashboard — check it, change your own theme, identity card, identity colour and widgets, play Canvas Worker effects in your chat (and offer a Try), preview the result, share it as a mod; and, for General, changing Settings → Web appearance for the user
+roles: [general, worker]
 ---
 
 ## What it is
@@ -16,12 +16,46 @@ can shape how you look there — **only your own look, and only on the surfaces
 | Your chat | theme: colours, accent, bubbles, font, background picture, working label | `set_web_theme`, `set_web_theme_asset` |
 | 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` |
 | A file of your look | a mod: export yours, or propose one for a person | `export_web_mod`, `propose_web_mod` |
+| Effects in your chat | Canvas Worker animations, and Try cards a local admin may start | `upload_web_effect`, `apply_web_effect`, `preview_web_effect`, … (see Effects) |
 
 None of these tools takes a target: they always act on you. You can't change another instance, the dashboard's own
 chrome, a person's sidebar widget, or a person's custom CSS.
 
+## For the user: Settings → Web appearance (General, coordinators, full)
+
+If you are General (or a coordinator or full profile), you can change the user's **Settings → Web appearance** 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 and
+   effect slots are 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}), `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" }` |
+| `custom_css` | `save` (with `text`): goes **on trial** on their screens (it goes back by itself unless kept); `keep` (the trial), `revert` (the trial), `use` (with `version`: an earlier saved one, at once), `off` | `{ what: "custom_css", action: "save", text: "…" }`; ask how it looks, then `keep` only when they say so |
+| `mod` | an agent's proposal: `review` (instance → `stage`, `plan`, `plan_hash`), then `install` (stage, plan_hash, `include`: the parts, `target`: the agent); `cancel`, `dismiss`, `uninstall` (id) | review, show the user the plan, install only what they asked for — never custom CSS unasked. A person has one review open at a time: while theirs is open (`mod_review_open`) ask them to finish it; a mod they imported from a file is theirs to install (`mod_not_from_an_agent`) |
+| `effect` | `apply` (instance, id, params?) or `remove` (instance, id?) an effect on a chat | |
+| `effect_slot` | a person's `sidebar` / `header` / `page` / `box` / `cursor` effect (an id, or null) | |
+| `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: import a mod file, upload an effect folder, add a CSS asset or a card picture;
+- this browser's own switches: custom CSS off on this device, pausing effect playback;
+- download an export;
+- 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
@@ -109,6 +143,25 @@ theme stops naming is deleted.
 `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 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 → Web appearance; ring and bar 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
@@ -184,6 +237,8 @@ with the tools above, then `export_web_mod`.
   with `rate_limited` and `retry_after_s`. Only an accepted change counts; a refused or invalid one costs nothing.
 - Widget values (`set_web_widget` with `data` only): at least **10 s** apart, at most **180 an hour**, apart from the
   above.
+- Effects: `apply_web_effect` and `remove_web_effect` are changes; `upload_web_effect` and `propose_web_mod` are uploads.
+  At most 10 effects and 8 MiB of your own, at most two placed in your chat.
 - Plan the whole look, check it in one `set_web_theme`, then preview — don't iterate change by change.
 
 ## A good workflow
@@ -198,6 +253,94 @@ From a shell: `agend-agent theme get|set key=value…|set --json '<patch>'|clear
 `agend-agent widget set <slot> '<spec json>' ['<data json>']|data <slot> '<data json>'|remove [slot]`, and
 `agend-agent mod export <name> <version> [title]|propose <file>`.
 
+## Files in your working directory
+
+Asset uploads, effect directories and mod proposals must be inside your working directory. This includes your own
+AgEnD-managed workspace (`~/.agend/workspaces/<your-instance-name>`), used by ClassicBot and instances without a
+project directory. `web-assets/` and `web-effects/` are convenient staging folders, not required names. Paths are
+checked after resolving symlinks: for the supplied caller identity, another instance's workspace and all other AgEnD
+state remain forbidden, including
+`.env`, databases, `instances/`, `credential-profiles/` and `inbox/`. Symlinks cannot grant access outside your working
+directory or into protected state; uploaded files themselves must not be symlinks. Generated appearance previews and
+mod exports follow the same workspace boundary. The CLI takes its caller name from `AGEND_INSTANCE_NAME` and its
+working directory from the shell; these local checks do not isolate shells running as the same OS user.
+
+## Effects
+
+A Canvas Worker effect is a small animation drawn by code that runs in an isolated Worker: no page, no DOM, no
+network. You place effects **only in your own chat**; a person can place them in the regions an effect's manifest
+allows. None of these tools takes a target.
+
+**The package** (CW1): a directory in your working directory with `effect.json` and `worker.js`, optionally
+`poster.png`, `cursor.png` and `assets/*.png|jpg|jpeg|webp|gif`. No HTML or CSS, at most 20 files and 16 assets. The
+smallest valid `effect.json`:
+
+```json
+{ "v": 1, "kind": "effect", "runtime": "canvas-worker-v1", "worker": "worker.js", "name": "spark", "title": "Spark", "regions": ["chat"], "layer": "behind", "wants": [] }
+```
+
+- Optional fields: `description`, `poster` (`"poster.png"`), `box`, `cursor` (its `hotspot` inside the image) and
+  `params`.
+  - `name`: 1..32 characters, starting with a-z or 0-9, then a-z, 0-9 and -.
+  - `title` (1..40) and `description` (up to 200): one line each, counted in characters as people see them.
+  - `regions`: 1–5 of `chat`, `sidebar`, `header`, `page`, `box`. **Include `chat` to place it in a chat**: applying
+    one without it is refused (`effect_region`), and so is a mod placing it. The other regions are ones a person may
+    choose it for.
+  - `layer`: `behind` (under the content) or `front` (over it).
+  - `wants`: up to 5 of `pointer`, `state`, `reply`, `mention`, `theme`. **`mention` is reserved and never fires in
+    2.3.0** (see Effect event availability).
+  - `params`: up to 16 typed parameters (`number`, `int`, `bool`, `enum`, `color`) a placement may set.
+- `worker.js` (at most 1 MiB, a classic script: static `import` / `export` are refused) draws through the `agend` API:
+  `canvas`, `params`, `asset()`, `on()`, `frame()` and `ready()`. Call `ready()` within 10 s, or it is stopped. Network
+  and dynamic imports are blocked at run time; the upload may warn `network_or_import_api_unsupported`, but don't rely
+  on the warning to catch every use.
+- Size: `effect.json` at most 64 KiB; the whole effect at most 8 MiB as uploaded and **1 MiB normalized**. Pictures:
+  at most 4096 px a side, and **8,388,608 pixels in total** across the assets, poster and cursor together. A cursor is
+  a square PNG of at most 64 px and 32 KiB (after metadata is stripped).
+
+**Reusable pointer example:** [`docs/examples/click-sparks`](https://github.com/songsid/AgEnD/blob/main/docs/examples/click-sparks.md) has a small two-file CW1 package: click for a burst, hold the primary button and move for a trail. Copy it into your working directory before uploading. Protected controls receive no pointer input; samples are coalesced (up to 60 Hz, 30 at reduced quality), so do not use it as a required click or drag control.
+
+**The tools:**
+
+- `upload_web_effect { dir }` → `{ id, warnings }`. It counts as an upload (3 an hour, shared with pictures and mods).
+  **Your own** copies are at most **10 effects and 8 MiB**; effects a person shared with you don't count.
+- `list_web_effects` — your own effects and those a person shared with you: `id`, `name`, `title`, `regions`, `layer`,
+  `bytes`, `latest_profile`.
+- `apply_web_effect { id, params? }` places one in your chat, **at most two at a time**, with the declared `params`
+  (unknown or out of range → `effect_params`; regions without `chat` → `effect_region`). `remove_web_effect { id? }`
+  takes one out, or all of them. Both are changes (30 s apart, 10 an hour), and are refused while a person has locked
+  your theme (`locked`) or when the fleet turned agent changes off (`theme_editing_off`).
+- `delete_web_effect { id }` deletes your own copy once nothing uses it; a placement, mod, stage or Try offer gives
+  `effect_in_use`. Another's copy is never removed.
+- `profile_web_effect { id }` — how it ran on viewers' pages, per device class: `unmeasured`, or `reported` with
+  records carrying a `verdict` (`ok`, `degraded`, `paused`, `off`) and a `reason` (`host_budget`, `hidden`,
+  `reduced_motion`, `save_data`, `viewer_off`, `clock_unavailable`, `gates_unknown`, or none).
+  `list_web_effects`' `latest_profile` has the latest one. These are best-effort reports of what happened, not live
+  notices. No measurement means unknown, never healthy.
+- `preview_web_effect { id }` offers a Try card in your chat (see Try below).
+- **Sharing is a person's act.** You can't share an effect. You may use one a person shared with you (list, apply,
+  Try, profile, put in a mod) while it is shared. When they unshare it, a placement already in your chat stays
+  eligible for playback (subject to the viewer's and the safety rules); applying, Try, listing, profiling or exporting
+  it again needs your own copy or another share, else `not_found`. A placement is never a grant to export it.
+
+**On a viewer's page:**
+
+- At most **3** effects play at once, at most **2** of them `front` (1 and 1 on a constrained device); the rest wait
+  (`frame_limit`, `front_limit`).
+- Nothing plays in safe mode, over a temporary public link, with reduced motion or save-data, on a hidden page, while
+  the viewer has effects off, or before they consent to previews. A `poster.png` may then show behind the chat (see
+  Static Chat fallback). A visible menu or dialog stops `front` effects; these stops lift by themselves.
+- **Safety pause** — it measures the page's responsiveness, not your Worker's CPU. The page's frame-rate floor is
+  90% of what it measured before the effect started, capped at 55 fps (50 on a constrained device), so a 30 Hz screen
+  has a 27 fps floor. Where the browser reports them, long tasks may take at most 50 ms a second (25 ms constrained);
+  unknown timing doesn't count as free. Overlapping 2-second windows are judged at most once a second after a warm-up,
+  and three bad judgements in a row pause the effect (`host_budget`).
+- Only a viewer's explicit **Resume** restarts a safety-paused effect, and it doesn't clear the history: three such
+  pauses within 24 hours turn the effect **off** for that viewer's browser and device class, across tabs and reloads,
+  and Resume then refuses. It doesn't come back by itself after 24 hours.
+- **Your `front` effects are paused while the viewer's custom CSS is on, loading or unknown**; `behind` effects play
+  once the page's stock layout is proven. A person's placement is exempt. Don't keep re-applying (see below).
+
 ## Owner-level effect selections
 
 The five owner keys `fx.sidebar`, `fx.header`, `fx.page`, `fx.box` and `fx.cursor` are a signed-in person's web
@@ -214,7 +357,7 @@ placed there. A reference is not a sharing or export grant. Do not keep retrying
 
 Owner selectors are available in Settings → Web appearance. With effects and preview consent enabled, personal
 page/header/sidebar/box choices play across supported stock pages in the same pool as local signed-in Chat.
-Appearance offers slot Pause/Resume and unavailable/Clear controls. The personal cursor uses a static PNG on the host shell after the same consent: no Worker/code read or frame slot. It preserves explicit pointer/text/resize cursors, falls back while dragging or on failure, and has status/Clear rather than Worker Pause/Resume. Before revealing paint, the host must prove stock content
+Web appearance offers slot Pause/Resume and unavailable/Clear controls. The personal cursor uses a static PNG on the host shell after the same consent: no Worker/code read or frame slot. It preserves explicit pointer/text/resize cursors, falls back while dragging or on failure, and has status/Clear rather than Worker Pause/Resume. Before revealing paint, the host must prove stock content
 ordering and trust paint coverage. Agent front effects must remain paused when custom CSS is active, loading or
 unknown; a person sees the reason and can open the causing setting. Human placements retain their exemption from
 that agent restriction, and behind effects still require proven ordering. Saving a placement alone is not proof of
@@ -229,8 +372,9 @@ deferred to #1940; do not keep reapplying an agent front while custom CSS is on,
 `preview_web_effect({id})` posts a volatile Try card in your own web chat, using your current own/shared read rights. It starts nothing and changes no appearance. The sample is physically clipped inside its own host panel or sheet. Only an explicit
 click by a signed-in **local admin** may start it; never an agent, public link, header token or automatic action.
 The host owns a visible Trial label and Stop control. Closing the panel/sheet, navigating, window blur, or another
-menu/dialog stops it. Custom CSS must be off (on/loading/unknown denies), and the same caps, profiler and safety
-stops apply. Ordinary foreground effects stay suppressed. A volatile offer lasts at most ten minutes; every read
+menu/dialog stops it. The explicit Try click consents to this sample only; no global HTML-preview opt-in is needed or changed.
+The host isolates the Trial controls and clipped stage in a closed Shadow DOM with fixed styles and reset typography.
+Custom CSS stays active elsewhere. The same caps, profiler and safety stops apply. Ordinary foreground effects stay suppressed. A volatile offer lasts at most ten minutes (offering the same effect again keeps that offer and its expiry; a different effect replaces it); every read
 rechecks the originating agent's current own/shared access, with the trial bound to the admin's session and epoch.
 There is no saved placement, claim, share, export or new saved profile record. Cards are memory-only and become inert when expired; a restart never restores them. Try uses manifest defaults and the existing app pool, not a second runtime. Do not treat an offer id or ordinary reply button
 as permission to run or fetch an effect, and do not keep retrying an unavailable Try.