@songsid/agend 2.2.0 → 2.3.0-beta.2

package/dist/fleet-manager.js

@@ -139,14 +139,31 @@ import { LogService } from "./log-service.js";
 import { WebChatHistory, WEB_CHAT_TEXT_MAX, isWebMessageId, newWebMessageId } from "./web-chat-history.js";
 import { WebChatDiskStore } from "./web-chat-store.js";
 import { SeenUsers, resolveMentions } from "./web-mentions.js";
-import { WebPrefsStore } from "./web-prefs.js";
+import { OPERATOR, WebPrefsStore } from "./web-prefs.js";
+import { agendVersion } from "./agent-whats-new.js";
+import { OwnerCssStore } from "./web-owner-css-store.js";
+import { ThemeStore } from "./web-theme-store.js";
+import { WebAppearance } from "./web-appearance.js";
+import { WebEffectLibrary } from "./web-effect-library.js";
+import { WebEffectTrials } from "./web-effect-trials.js";
+import { WebEffectService } from "./web-effect-service.js";
+import { WebEffectProfiles } from "./web-effect-profiles.js";
+import { WebEffectTools, WEB_EFFECT_TOOLS } from "./web-effect-tools.js";
+import { resolveEffectParams } from "./web-effect.js";
+import { cw1EffectChecker } from "./web-mod-bundle.js";
+import { effectiveAppearanceLimits } from "./web-appearance-limits.js";
 import { WEB_NAME_FALLBACK, safeWebName, validateWebName, webNameInUse, webPersonKey } from "./web-profile.js";
 import { ReplyButtonStore, parseReplyButtons, replyButtonClickText, replyButtonsFallbackText, REPLY_BUTTON_PREFIX } from "./reply-buttons.js";
 import { ReplyButtonsController } from "./reply-buttons-controller.js";
 import { parsePoll } from "./reply-polls.js";
 import { isUploadRequest, limitRequestReceive, publicAttachment, sweepOrphanedUploads, UPLOAD_REQUEST_TIMEOUT_MS, uploadLimits, WebFileLedger } from "./web-upload.js";
 import { REPLY_FILES_MAX_BYTES, snapshotReplyFile, sweepReplySnapshots, webFilesDir } from "./web-reply-files.js";
-import { handleViewRequest, isViewPath, profileIdentities, resolveInstanceIdentity } from "./view-api.js";
+import { cardPicture, handleViewRequest, humanCards, identityColors, isViewPath, profileIdentities, resolveInstanceIdentity } from "./view-api.js";
+import { autoIdentityColor } from "./web-identity-color.js";
+import { AppearanceTools } from "./web-appearance-tools.js";
+import { cardVersion, resolveCard } from "./web-card.js";
+import { ModStore } from "./web-mod-store.js";
+import { AgentMods } from "./web-mod-agent.js";
 import { downloadStickerImage } from "./channel/sticker-download.js";
 import { WebImageCache, imageMimeForFile, WEB_IMAGE_MAX_AGE_MS, WEB_IMAGE_MAX_BYTES, WEB_IMAGE_RETRY_MS } from "./web-images.js";
 import { accentColor, avatarFor, ownBotConnections } from "./instance-avatar.js";
@@ -192,7 +209,8 @@ import { NeedsYouHub } from "./needs-you-hub.js";
 import { WEB_CHAT_NOTICE, claimNotice, hasWebChat, releaseNotice, upgradeNoticesPath } from "./upgrade-notices.js";
 import { GENERAL_PAUSE_ERROR, isGeneralInstance } from "./general-instance.js";
 import { buildOrgChart } from "./web-org.js";
-import { CacheService, WINDOWS } from "./cache-service.js";
+import { GENERAL_POINTING_REFUSALS, SNOWFLAKE, hasPlaceRefs, placeRef, webRoute, webTextLinks, placeSuffix, renderPlaceRefs, stripPlaceRefs, topicUrl, worldPlaceOf } from "./topic-link.js";
+import { CacheService, cacheWindow } from "./cache-service.js";
 import { runWebCommand } from "./web-commands.js";
 import { CompactWatch, launchIdentity } from "./compact-watch.js";
 import { agyLegacyAgentsFile, danglingSymlink, migrateAgyAgentsFile } from "./backend/antigravity.js";
@@ -884,6 +902,183 @@ export class FleetManager {
                 return true;
         return false;
     }
+    themeStoreInstance;
+    webAppearanceService;
+    /** #1629: every instance's theme, placements, assets and lock (web-themes.json). */
+    get themeStore() {
+        // r4.1 Q3 (b): the card's limits are read from fleet.yaml at each upload (a change applies without a restart).
+        return (this.themeStoreInstance ??= new ThemeStore(this.dataDir, { limits: () => effectiveAppearanceLimits(this.fleetConfig?.web?.appearance).limits, effectsDropped: ids => this.effectLibrary.collectUnreferenced(ids) }));
+    }
+    /** #1629: the theme tools, a person's reset and lock, and the one appearance rate limiter (shared with effects). */
+    get webAppearance() {
+        return (this.webAppearanceService ??= new WebAppearance(this.themeStore, () => this.fleetConfig?.web ?? null, () => { try {
+            this.emitSseEvent("status", this.getUiStatus());
+        }
+        catch { /* the next frame carries the rev */ } }));
+    }
+    effectLibraryInstance;
+    effectTrialsInstance;
+    /** Lazy, single-owner storage. Register every host reference source before any operation can collect. */
+    get effectLibrary() {
+        if (!this.effectLibraryInstance) {
+            const library = new WebEffectLibrary(this.dataDir);
+            // Providers are lazy; publish only after every registration succeeds.
+            library.registerReferenceSource("themes", () => {
+                if (!this.themeStore.readable())
+                    throw new Error("themes_unreadable");
+                return this.themeStore.placedEffects().flatMap(row => row.ids.map(id => ({ id, holder: `instance:${row.name}` })));
+            });
+            library.registerReferenceSource("prefs", () => this.webPrefs.ownerEffectReferences());
+            library.registerReferenceSource("mods", () => {
+                const mods = this.mods.list();
+                if (mods.unreadable)
+                    throw new Error("mods_unreadable");
+                return mods.mods.flatMap(mod => mod.effects.map(effect => ({ id: effect.id, holder: `mod:${mod.id}` })));
+            });
+            this.effectTrialsInstance = new WebEffectTrials({ library, known: name => this.isKnownInstance(name) });
+            this.effectLibraryInstance = library;
+        }
+        return this.effectLibraryInstance;
+    }
+    /** Volatile Try offers and session-bound runs share this library. */
+    get effectTrials() { if (!this.effectTrialsInstance)
+        void this.effectLibrary; return this.effectTrialsInstance; }
+    effectProfilesInstance;
+    get effectProfiles() { return (this.effectProfilesInstance ??= new WebEffectProfiles(this.dataDir)); }
+    effectServiceInstance;
+    get effectService() {
+        return (this.effectServiceInstance ??= new WebEffectService({ library: this.effectLibrary, themes: this.themeStore, profiles: this.effectProfiles, prefs: this.webPrefs, trials: this.effectTrials,
+            known: name => this.isKnownInstance(name), changed: () => { try {
+                this.emitSseEvent("status", this.getUiStatus());
+            }
+            catch { /* next status carries revision */ } } }));
+    }
+    effectToolsService;
+    /** Caller identity is supplied only by the owned IPC connection / verified agent endpoint token. */
+    get effectTools() {
+        return (this.effectToolsService ??= new WebEffectTools({
+            library: this.effectLibrary, limiter: this.webAppearance.limiter,
+            authorize: (name, buckets) => !this.isKnownInstance(name) ? { error: "unknown_instance" } : this.webAppearance.authorizeEffect(name, buckets),
+            placed: name => this.themeStore.get(name).placements.effects,
+            place: (name, effects) => {
+                const before = this.themeStore.get(name).placements.effects;
+                const explicit = new Set(effects.filter(e => typeof e !== "string").map(e => e.id));
+                const w = this.themeStore.setPlacements(name, { effects }, "agent", what => {
+                    // An unchanged human/private placement may be retained, never exposed or newly acquired by an agent.
+                    const r = explicit.has(what.id) ? this.effectLibrary.read(what.id, { kind: "agent", id: name })
+                        : this.effectLibrary.readReferenced(what.id, `instance:${name}`);
+                    if (!r.ok)
+                        return r.error;
+                    const params = explicit.has(what.id) ? what.params : before.find(e => e.id === what.id)?.params;
+                    return resolveEffectParams(r.entry.manifest, params ?? {}).ok ? null : "effect_params";
+                });
+                return w.ok ? { ok: true, rev: w.rev } : { ok: false, error: w.error };
+            },
+            changed: () => { try {
+                this.emitSseEvent("status", this.getUiStatus());
+            }
+            catch { /* later status carries placements */ } },
+            // A nonmutating own/shared offer is not an appearance write. Only an explicit local-admin click may start it.
+            preview: async (instance, id) => {
+                const result = this.effectTrials.offer(instance, id);
+                if (!result.ok)
+                    return { error: "not_found" };
+                const present = this.webChatHistory.list(instance).some(row => row.effectTrial?.offer === result.offer.offer);
+                if (!present && !this.publishEffectTrial(instance, result.offer))
+                    return { error: "trial_unavailable" };
+                return { id, status: "offered", expiresAt: result.offer.expiresAt, message: "A trial card is in your web chat. A signed-in local admin can start it; nothing was applied." };
+            },
+            profiles: id => this.effectProfiles.read(id),
+            profileSummary: id => this.effectService.profileSummary(id),
+            profileSummaries: ids => this.effectService.profileSummaries(ids),
+        }));
+    }
+    appearanceToolsService;
+    /** #1629 r4 §1: get_web_appearance / preview_web_appearance — the caller's own look, resolved as the page resolves it. */
+    get appearanceTools() {
+        return (this.appearanceToolsService ??= new AppearanceTools({
+            frame: (name) => (this.getUiStatus().instances.find(i => i.name === name) ?? { name }),
+            theme: (name) => { const r = this.themeStore.get(name); return { theme: r.theme, locked: r.locked, widgets: r.placements.widgets }; },
+            card: (name) => resolveCard(name, humanCards(this.dataDir).get(name), this.themeStore.get(name).theme.card),
+            // #1958: the host's identity-colour settings, as the page reads them (an unreadable prefs file: the defaults).
+            colorPrefs: () => { try {
+                const v = this.webPrefs.read(OPERATOR).values;
+                return { show: v["color.show"], off: v["color.off"] === true };
+            }
+            catch {
+                return {};
+            } },
+            cardPicture: (name, slot) => cardPicture(this, name, slot),
+            themeAsset: (name, id) => this.themeStore.asset(name, id),
+            profileAvatar: (name) => this.webImage("avatar", name),
+            botAvatar: (_name, key) => this.webImage("bot", key),
+            themeAnswer: (name) => this.webAppearance.getTheme(name),
+        }));
+    }
+    /** #1958: a profile, card or colour write (view-api.ts) landed: every open page gets a fresh status frame. */
+    identityChanged() {
+        try {
+            this.emitSseEvent("status", this.getUiStatus());
+        }
+        catch { /* the next frame carries it */ }
+    }
+    /** A fleet.yaml instance (own key) or a ClassicBot room, now (#1629: a person's reset/lock names one). */
+    isKnownInstance(name) {
+        return Object.hasOwn(this.fleetConfig?.instances ?? {}, name) || (this.classicChannels?.getAll() ?? []).some((ch) => ch.instanceName === name);
+    }
+    modStore;
+    /**
+     * #1629 r4-5 / B2: installed mods use the same validated library and scoped holder claims as direct uploads.
+     */
+    get mods() {
+        return (this.modStore ??= new ModStore(this.dataDir, {
+            themes: this.themeStore,
+            prefs: this.webPrefs,
+            ownerCss: this.ownerCss,
+            effects: this.effectLibrary,
+            context: () => ({ agendVersion: agendVersion(), limits: this.themeStore.limits(), effects: cw1EffectChecker() }),
+            isKnownInstance: (name) => this.isKnownInstance(name),
+            prefsIdentity: OPERATOR,
+        }));
+    }
+    agentModsService;
+    /** #1629 r4-5b: export_web_mod / propose_web_mod — the caller's own look as a file, and a proposal for a person. */
+    get agentMods() {
+        return (this.agentModsService ??= new AgentMods({
+            themes: this.themeStore, mods: this.mods, limiter: this.webAppearance.limiter,
+            webConfig: () => this.fleetConfig?.web ?? null,
+            // The mod store's own: a proposal is checked exactly as the person's import of it will be.
+            context: () => this.mods.checkContext(),
+            readOwnEffect: (instance, id) => { const r = this.effectLibrary.read(id, { kind: "agent", id: instance }); return r.ok ? { name: r.entry.manifest.name, files: r.entry.files } : null; },
+            notice: (instance, text) => { try {
+                this.emitSseEvent("message", { instance, sender: instance, role: "status", text, ts: new Date().toISOString() });
+            }
+            catch { /* the page reads it from Settings too */ } },
+            changed: () => { try {
+                this.emitSseEvent("status", this.getUiStatus());
+            }
+            catch { /* the next frame */ } },
+        }));
+    }
+    /**
+     * #1629 r4-5c: an effect as this person may carry it away in an export — their own claim, or one a person shared —
+     * read with their principal (Sol's ACL). Being able to view or run a placed effect never grants packaging someone
+     * else's private claim: the library's reference read is runtime access, not an export path. Null: not theirs.
+     */
+    modPlacedEffect(person, id) {
+        const r = this.effectLibrary.read(id, { kind: "human", id: person });
+        return r.ok ? { name: r.entry.manifest.name, files: r.entry.files } : null;
+    }
+    /** #1629 r4-5: an instance's card text as every viewer sees it (a person's fields over the agent's). */
+    modCardText(name) {
+        const card = resolveCard(name, humanCards(this.dataDir).get(name), this.themeStore.get(name).theme.card);
+        return { ...(card.tagline ? { tagline: card.tagline.text } : {}), ...(card.bio ? { bio: card.bio.text } : {}) };
+    }
+    ownerCssStore;
+    /** #1629 r4 §3: each person's own CSS; which version is in force is their `css.active` in the web preferences. */
+    get ownerCss() {
+        return (this.ownerCssStore ??= new OwnerCssStore(this.dataDir, this.webPrefs));
+    }
     get webPrefs() {
         // #1664: a favorite must be an instance of this fleet now — fleet.yaml's (own keys) or a ClassicBot room's.
         return (this.webPrefsStore ??= new WebPrefsStore(this.dataDir, {
@@ -3704,7 +3899,11 @@ export class FleetManager {
             // A command off for want of fleet admins names where they go (`{0}` in its disabled reply).
             if (decision.reply === spec.disabled)
                 args.push(this.adminListKey(adapterId));
-            await data.respond(t(key, ...args)).catch(() => { });
+            // #1990: a refusal that sends the person to General links to it — not in a ClassicBot room, whose readers need
+            // not be in the fleet's guild.
+            const toGeneral = GENERAL_POINTING_REFUSALS.has(key) && scope !== "classic" && scope !== "none";
+            const reply = toGeneral ? this.renderPlaces(adapterId, t(key, ...args) + placeSuffix({ kind: "general" }, "General")).text : t(key, ...args);
+            await data.respond(reply).catch(() => { });
             return;
         }
         if (data.command === "start") {
@@ -5302,7 +5501,8 @@ export class FleetManager {
         const owner = id ? this.dashboardOwner(msg.userId, id, msg.chatId, msg.threadId, msg.username) : null;
         if (!owner) {
             const adapter = id ? this.adapters.get(id) : undefined;
-            await adapter?.sendText(msg.chatId, t("dashboard.public_general"), { threadId: msg.threadId });
+            const out = this.renderPlaces(id, t("dashboard.public_general") + placeSuffix({ kind: "general" }, "General"), { threadId: msg.threadId });
+            await adapter?.sendText(msg.chatId, out.text, out.opts);
             return;
         }
         if (!await this.showDashboardMenu(owner)) {
@@ -6273,7 +6473,7 @@ export class FleetManager {
                 ...DEFAULT_SCHEDULER_CONFIG,
                 ...this.fleetConfig?.defaults.scheduler,
             };
-            this.scheduler = new Scheduler(join(this.dataDir, "scheduler.db"), (schedule, runId, retry) => this.handleScheduleTrigger(schedule, runId, retry), schedulerConfig, (name) => this.fleetConfig?.instances?.[name] != null || !!this.classicChannels?.getAll().some(ch => ch.instanceName === name), (schedule, retry, reason) => this.scheduleRetryDropped(schedule, retry, reason));
+            this.scheduler = new Scheduler(join(this.dataDir, "scheduler.db"), (schedule, runId, retry) => this.handleScheduleTrigger(schedule, runId, retry), schedulerConfig, (name) => this.fleetConfig?.instances?.[name] != null || !!this.classicChannels?.getAll().some(ch => ch.instanceName === name), (schedule, retry, reason) => this.scheduleRetryDropped(schedule, retry, reason), this.logger);
             this.scheduler.init();
             this.logger.info("Scheduler initialized");
             // Tips share the daily-report clock but remain an independent internal
@@ -7505,6 +7705,48 @@ export class FleetManager {
             this.adapterRestarting.delete(id);
         }
     }
+    /**
+     * #1990: how a reader in world `worldId`'s group reaches a place token's target — undefined (plain text) for another
+     * world's instance, an instance without a fleet topic (a ClassicBot room may be anywhere), or an id no link is built
+     * from. Discord: the channel mention; Telegram: the topic URL (General's topic included).
+     */
+    placeLink(worldId, target) {
+        const world = this.worlds.get(worldId ?? "");
+        if (!world)
+            return undefined;
+        let topic;
+        if (target.kind === "general") {
+            const notice = this.fleetNoticeTarget(world.id);
+            if (!notice || notice.chatId !== world.groupId || notice.opts.threadId === undefined)
+                return undefined;
+            topic = String(notice.opts.threadId);
+        }
+        else {
+            if (this.getInstanceAdapterId(target.name) !== world.id)
+                return undefined;
+            const topicId = this.fleetConfig?.instances[target.name]?.topic_id;
+            if (topicId == null)
+                return undefined;
+            topic = String(topicId);
+        }
+        if (world.type === "discord")
+            return SNOWFLAKE.test(topic) && SNOWFLAKE.test(world.groupId) ? { mention: `<#${topic}>` } : undefined;
+        const url = topicUrl(worldPlaceOf(world), topic, { general: target.kind === "general" });
+        return url ? { url } : undefined;
+    }
+    /** #1990: a message for world `worldId`'s group with its place tokens rendered (links as text or Telegram entities). */
+    renderPlaces(worldId, text, opts) {
+        if (!hasPlaceRefs(text))
+            return { text, opts };
+        const type = this.worlds.get(worldId ?? "")?.type;
+        const surface = type === "discord" ? "discord" : type === "telegram" ? "telegram" : "plain";
+        const out = renderPlaceRefs(text, surface, target => this.placeLink(worldId, target));
+        return { text: out.text, opts: out.textLinks.length ? { ...opts, textLinks: out.textLinks } : opts };
+    }
+    /** #1990: renderPlaces for the world that owns `instanceName`'s topic. */
+    renderPlacesFor(instanceName, text, opts) {
+        return this.renderPlaces(this.getInstanceAdapterId(instanceName), text, opts);
+    }
     /** Handle inbound message — transcribe voice if present, then route */
     findGeneralInstance(adapterId) {
         if (!this.fleetConfig)
@@ -9177,6 +9419,19 @@ export class FleetManager {
     }
     dispatchTypedIpc(name, msg) {
         const type = String(msg.type);
+        if (type.startsWith("fleet_") && WEB_EFFECT_TOOLS.has(type.slice(6))) {
+            const ipc = this.instanceIpcClients.get(name), fleetRequestId = msg.fleetRequestId;
+            if (!ipc || typeof fleetRequestId !== "string")
+                return;
+            void this.handleWebThemeHttp(name, type.slice(6), (msg.payload ?? {})).then(result => {
+                if (this.instanceIpcClients.get(name) === ipc)
+                    ipc.send({ type: "fleet_web_theme_response", fleetRequestId, result });
+            }, err => {
+                if (this.instanceIpcClients.get(name) === ipc)
+                    ipc.send({ type: "fleet_web_theme_response", fleetRequestId, error: err instanceof Error ? err.message : "Effect operation failed" });
+            }).catch(err => this.logger.debug({ err }, "Effect tool response could not be written"));
+            return;
+        }
         if (type.startsWith("fleet_schedule_")) {
             this.handleScheduleCrud(name, msg);
             return;
@@ -9202,6 +9457,36 @@ export class FleetManager {
             this.handlePersonaEmoji(name, msg);
             return;
         }
+        if (type === "fleet_get_web_theme" || type === "fleet_set_web_theme" || type === "fleet_set_web_theme_asset" || type === "fleet_reset_web_theme"
+            || type === "fleet_get_web_appearance" || type === "fleet_preview_web_appearance"
+            || type === "fleet_set_web_widget" || type === "fleet_remove_web_widget"
+            || type === "fleet_export_web_mod" || type === "fleet_propose_web_mod") {
+            this.handleWebTheme(name, msg);
+            return;
+        }
+    }
+    /**
+     * #1629: the caller's own web theme over IPC (the agent endpoint calls the same service). `name` is the instance this
+     * IPC connection belongs to — never anything the message says. A refusal is a result the agent reads (its `error`
+     * and what to do), not a transport error.
+     */
+    handleWebTheme(instanceName, msg) {
+        const fleetRequestId = msg.fleetRequestId;
+        const ipc = this.instanceIpcClients.get(instanceName);
+        if (!ipc)
+            return;
+        const tool = String(msg.type).replace(/^fleet_/, "");
+        try {
+            const args = (msg.payload ?? {});
+            const result = tool === "get_web_appearance" || tool === "preview_web_appearance"
+                ? this.appearanceTools.handle(instanceName, tool, args)
+                : tool === "export_web_mod" || tool === "propose_web_mod" ? this.agentMods.handle(instanceName, tool, args)
+                    : this.webAppearance.handleTool(instanceName, tool, args);
+            ipc.send({ type: "fleet_web_theme_response", fleetRequestId, result });
+        }
+        catch (err) {
+            ipc.send({ type: "fleet_web_theme_response", fleetRequestId, error: err.message });
+        }
     }
     /** `list_emojis` / `set_persona_emoji` / `preview_emojis` / `list_stickers` / `preview_stickers` over IPC; the agent endpoint calls the same methods. */
     handlePersonaEmoji(instanceName, msg) {
@@ -9606,6 +9891,19 @@ export class FleetManager {
     async handleSetPersonaEmojiHttp(instance, args) {
         return this.setPersonaEmoji(instance, args);
     }
+    /** #1629: `agend-agent theme …` — the same service as the tools; `instance` is the token's. */
+    async handleWebThemeHttp(instance, tool, args) {
+        if (WEB_EFFECT_TOOLS.has(tool)) {
+            if (!this.isKnownInstance(instance))
+                return { error: "unknown_instance" };
+            return this.effectTools.handle(instance, tool, args);
+        }
+        if (tool === "get_web_appearance" || tool === "preview_web_appearance")
+            return this.appearanceTools.handle(instance, tool, args);
+        if (tool === "export_web_mod" || tool === "propose_web_mod")
+            return this.agentMods.handle(instance, tool, args);
+        return this.webAppearance.handleTool(instance, tool, args);
+    }
     async handlePreviewEmojisHttp(instance, args) {
         return this.previewEmojis(instance, args);
     }
@@ -10308,6 +10606,17 @@ export class FleetManager {
         catch (err) {
             this.logger.warn({ err: err.message, name }, "Dropping a removed instance from web favorites failed");
         }
+        try {
+            this.themeStore.forget(name);
+            this.webAppearance.forget(name);
+            this.appearanceTools.forget(name);
+            this.effectToolsService?.forget(name);
+            this.mods.forgetInstance(name);
+            this.agentMods.forget(name);
+        }
+        catch (err) {
+            this.logger.warn({ err: err.message, name }, "Dropping a removed instance's web theme failed");
+        }
         // Clean up statusline watcher + instance directory
         this.statuslineWatcher.unwatch(name);
         // instanceDirToClean and effectiveBackend are captured before lifecycle.remove
@@ -10596,10 +10905,25 @@ export class FleetManager {
         const avatar = avatarFor({ name, displayName, profileVersion, bot: bot && connection ? { connection, version: bot.version } : null,
             personaEmoji: cfg?.status_emojis?.delivered });
         // The ring belongs to an own bot's face: only when that is what is shown (a shared bot's would ring everyone alike).
-        const accent = !profileVersion && bot && ownConnection && owner
+        // #1958: the own bot's colour is also the identity colour's role tier — whatever face is shown (never a shared bot's).
+        const roleColor = ownConnection && owner
             ? this.webAccent(ownConnection, owner, cfg ? (cfg.topic_id == null ? undefined : String(cfg.topic_id)) : this.classicChannels?.getChannelIdByInstance(name))
             : null;
-        return accent ? { avatar, accent } : { avatar };
+        const accent = !profileVersion && bot && ownConnection && owner ? roleColor : null;
+        // #1629 (first design §5, r2 (d)): the agent's theme may name its own picture and ring colour. Both come below a
+        // person's upload (never when there is one) and ride beside the theme-free face: a viewer who turned agents'
+        // themes off (fx.show), or a safe-mode load, shows `avatar` and `accent` as before.
+        let theme = { v: 1 };
+        try {
+            theme = this.themeStore.get(name).theme;
+        }
+        catch { /* unreadable themes: none */ }
+        const themeAvatar = !profileVersion && theme.avatar ? { kind: "image", src: `/ui/img/theme/${encodeURIComponent(name)}/${theme.avatar}` } : undefined;
+        const themeAccent = !profileVersion && theme.accent ? theme.accent : undefined;
+        return { avatar, ...(accent ? { accent } : {}), ...(themeAvatar ? { themeAvatar } : {}), ...(themeAccent ? { themeAccent } : {}),
+            // #1958: the agent's own identity colour (theme.identity.color, else its accent) and where it would show it.
+            ...(roleColor ? { roleColor } : {}), ...(theme.identity?.color ?? theme.accent ? { agentColor: theme.identity?.color ?? theme.accent } : {}),
+            ...(theme.identity?.show ? { agentShow: theme.identity.show } : {}) };
     }
     /**
      * GET /ui/img/bot|avatar/<key>: what is cached, never a fetch. Only a connection some instance or room speaks
@@ -11686,7 +12010,8 @@ export class FleetManager {
             // Discord, so every such fallback failed inside the catch handler.
             const target = this.fleetNoticeTarget();
             if (this.adapter && target) {
-                this.adapter.sendText(target.chatId, body, target.opts)
+                const out = this.renderPlaces(this.getPrimaryAdapterId(), body, target.opts);
+                this.adapter.sendText(target.chatId, out.text, out.opts)
                     .catch(err => this.logger.warn({ err }, "Failed to send fleet error notification"));
                 dispatched = true;
             }
@@ -11698,7 +12023,7 @@ export class FleetManager {
             // also suppressed the next ten minutes of identical ones. Leaving the key
             // unspent lets the next caller, once an adapter is up, actually get
             // through. The counter is not reset either: nothing was shown.
-            this.logger.warn({ text: body }, "Fleet error could not be delivered (no adapter or no target yet) — not consuming the throttle window");
+            this.logger.warn({ text: stripPlaceRefs(body) }, "Fleet error could not be delivered (no adapter or no target yet) — not consuming the throttle window");
             return false;
         }
         if (!throttled)
@@ -11736,24 +12061,28 @@ export class FleetManager {
         const groupId = channelCfg?.group_id;
         // Fleet topic instance
         const threadId = this.fleetConfig?.instances[instanceName]?.topic_id;
+        const worldId = this.getInstanceAdapterId(instanceName);
         if (threadId != null && groupId) {
-            adapter.sendText(String(groupId), text, { threadId: String(threadId), ...extraOpts })
+            const out = this.renderPlaces(worldId, text, { threadId: String(threadId), ...extraOpts });
+            adapter.sendText(String(groupId), out.text, out.opts)
                 .catch(e => this.logger.warn({ err: e, instanceName }, "Failed to send instance topic notification"));
             return true;
         }
         // Classic instance: find its channelId from the classic manager
         const classicChatId = this.classicChannels?.getChannelIdByInstance(instanceName);
         if (classicChatId) {
-            adapter.sendText(classicChatId, text, extraOpts)
+            // #1990: a ClassicBot room's readers need not be in the fleet's group, so its notices name places as plain text.
+            adapter.sendText(classicChatId, stripPlaceRefs(text), extraOpts)
                 .catch(e => this.logger.warn({ err: e, instanceName }, "Failed to send classic notification"));
             return true;
         }
         // Fallback: the instance has neither a topic nor a classic channel, so post
         // where fleet-wide notices go. Not the bare group id: on Discord that is a
         // guild, and the send fails inside the catch handler.
-        const target = this.fleetNoticeTarget(this.getInstanceAdapterId(instanceName));
+        const target = this.fleetNoticeTarget(worldId);
         if (target) {
-            adapter.sendText(target.chatId, text, { ...target.opts, ...extraOpts })
+            const out = this.renderPlaces(worldId, text, { ...target.opts, ...extraOpts });
+            adapter.sendText(target.chatId, out.text, out.opts)
                 .catch(e => this.logger.warn({ err: e, instanceName }, "Failed to send notification (no topic)"));
             return true;
         }
@@ -11824,12 +12153,14 @@ export class FleetManager {
         this.pendingNonceButtons.set(nonce, entry);
         try {
             const choices = opts.choices.map(c => ({ id: `${opts.prefix}${nonce}:${c.action}`, label: c.label }));
+            // #1990: place names link for the group the prompt is posted in; the dashboard's copy is plain (for now).
+            const posted = this.renderPlaces(opts.adapterId, opts.message, opts.threadId ? { threadId: opts.threadId } : undefined);
             const sent = opts.deliver ? await opts.deliver(choices) : await opts.adapter.notifyAlert(opts.chatId, {
                 type: opts.alertType,
                 instanceName: opts.instanceName,
-                message: opts.message,
+                message: posted.text,
                 choices,
-            }, opts.threadId ? { threadId: opts.threadId } : undefined);
+            }, posted.opts);
             // Bind the nonce to the provider's canonical delivery address, not the
             // logical routing input. Telegram, for example, represents General as
             // AgEnD topic "1" on input but omits message_thread_id on the wire and in
@@ -11847,8 +12178,15 @@ export class FleetManager {
             // Offered on the dashboard only once it is live on the platform (a failed post is disarmed above),
             // and only if nothing claimed or expired it meanwhile.
             if (WEB_MIRRORED_PROMPT_PREFIXES.has(opts.prefix) && this.pendingNonceButtons.get(nonce) === entry) {
+                // #1990: on the dashboard an instance's name opens its terminal View (where the prompt is answered by hand).
+                const web = renderPlaceRefs(opts.message, "web", target => {
+                    const route = target.kind === "instance" && Object.hasOwn(this.fleetConfig?.instances ?? {}, target.name) ? webRoute("view", target.name) : undefined;
+                    return route ? { url: route } : undefined;
+                });
+                const links = webTextLinks(web.textLinks, web.text);
                 entry.web = {
-                    text: opts.message,
+                    text: web.text,
+                    ...(links ? { links } : {}),
                     actions: opts.choices.map(c => ({ id: c.action, label: c.label })),
                     expiresAt: Date.now() + (opts.timeoutMs ?? NONCE_BUTTON_TIMEOUT_MS),
                 };
@@ -12100,7 +12438,7 @@ export class FleetManager {
             isClassic: name => classic.has(name),
             place: name => {
                 const world = this.worlds.get(this.getInstanceAdapterId(name) ?? "");
-                return world ? { type: world.type, ...(world.groupId ? { groupId: world.groupId } : {}) } : undefined;
+                return world ? worldPlaceOf(world) : undefined;
             },
             // fleet.yaml's topic only. A ClassicBot room has none here, so no link: its channel may sit in any allowed
             // guild, not necessarily its world's group.
@@ -12159,8 +12497,14 @@ export class FleetManager {
      * (cache-service.ts) — never a vendor call, never a synchronous transcript read.
      */
     cacheReport(window) {
-        const w = Object.prototype.hasOwnProperty.call(WINDOWS, window) ? window : "7d";
-        this.cacheService ??= new CacheService({
+        return this.cacheServiceFor().report(cacheWindow(window));
+    }
+    /** #2001: get_cache_report's — the same report, as last worked out (reused for a minute, until the next pass). */
+    cacheReportPublished(window) {
+        return this.cacheServiceFor().published(cacheWindow(window));
+    }
+    cacheServiceFor() {
+        return this.cacheService ??= new CacheService({
             instances: () => this.cacheInstances(),
             claudeProjectsDir: () => join(process.env.CLAUDE_CONFIG_DIR?.trim() || join(homedir(), ".claude"), "projects"),
             claudeKey: claudeProjectKey,
@@ -12169,7 +12513,6 @@ export class FleetManager {
             metaPath: join(this.dataDir, "cache-codex-rollouts.json"),
             log: (level, msg, extra) => this.logger[level](extra ?? {}, msg),
         });
-        return this.cacheService.report(w);
     }
     /** The web's Acknowledge (any item; a signed-in session is fleet-admin level). */
     acknowledgeNeedsItem(id, principal) {
@@ -12265,9 +12608,7 @@ export class FleetManager {
                 finishedAt: Date.parse(d.finishedAt) || 0,
             })),
             ownerOf,
-            worlds: () => [...this.worlds.values()].map((w) => ({
-                id: w.id, adapter: w.adapter, place: { type: w.type, ...(w.groupId ? { groupId: w.groupId } : {}) },
-            })),
+            worlds: () => [...this.worlds.values()].map((w) => ({ id: w.id, adapter: w.adapter, place: worldPlaceOf(w) })),
             noticeTarget: world => {
                 const target = this.fleetNoticeTarget(world);
                 return target ? { chatId: target.chatId, ...(target.opts.threadId !== undefined ? { threadId: String(target.opts.threadId) } : {}) } : null;
@@ -12919,12 +13260,12 @@ export class FleetManager {
      * the operator's. Keep the instance notice passive and put the action in the
      * same-world General topic where an administrator can make the choice. */
     async notifyNormalExit(instanceName) {
-        this.notifyInstanceTopic(instanceName, t("exit.instance_notice", instanceName));
+        this.notifyInstanceTopic(instanceName, t("exit.instance_notice", instanceName) + placeSuffix({ kind: "general" }, "General"));
         const web = this.webOnlyPromptPlace();
         if (web) {
             await this.postNonceButtonPrompt({
                 prefix: EXIT_RESTART_CALLBACK_PREFIX, alertType: "exit_restart", instanceName, ...web,
-                message: t("exit.general_notice", instanceName),
+                message: t("exit.general_notice", placeRef({ kind: "instance", name: instanceName }, instanceName)),
                 choices: [{ action: "restart", label: t("exit.restart") }, { action: "ignore", label: t("exit.ignore") }],
                 expiredText: t("exit.expired", instanceName),
             });
@@ -12953,7 +13294,7 @@ export class FleetManager {
             adapterId,
             chatId,
             threadId,
-            message: t("exit.general_notice", instanceName),
+            message: t("exit.general_notice", placeRef({ kind: "instance", name: instanceName }, instanceName)),
             choices: [
                 { action: "restart", label: t("exit.restart") },
                 { action: "ignore", label: t("exit.ignore") },
@@ -13000,7 +13341,7 @@ export class FleetManager {
      * contain usernames or secret-adjacent text and stays in daemon.log.
      */
     async notifyInteractivePrompt(instanceName, kind) {
-        this.notifyInstanceTopic(instanceName, t("interactive.instance_notice", instanceName));
+        this.notifyInstanceTopic(instanceName, t("interactive.instance_notice", instanceName) + placeSuffix({ kind: "general" }, "General"));
         // Multi-world fleets can have one General per bot/platform. Route the assist
         // request to the General bound to the same adapter as the blocked instance.
         const generalName = this.findGeneralInstance(this.getInstanceAdapterId(instanceName));
@@ -13011,7 +13352,7 @@ export class FleetManager {
         const label = this.interactivePromptLabel(kind);
         const prompt = {
             prefix: INTERACTIVE_ASSIST_CALLBACK_PREFIX, alertType: "interactive_prompt", instanceName,
-            message: t("interactive.general_notice", instanceName, label),
+            message: t("interactive.general_notice", placeRef({ kind: "instance", name: instanceName }, instanceName), label),
             choices: [{ action: "confirm", label: t("interactive.confirm") }, { action: "cancel", label: t("interactive.cancel") }],
             expiredText: t("interactive.expired", instanceName),
             extra: { generalName, promptKind: kind, assistFor: this.interactionWaitKey(instanceName) },
@@ -14610,6 +14951,14 @@ export class FleetManager {
         const room = this.classicChannels?.getAll().find(c => c.instanceName === name);
         return room ? `room:${room.channelId}:${room.adapterId ?? ""}` : null;
     }
+    /** The only Try-card publisher: no arbitrary SSE sender/role can manufacture this metadata. */
+    publishEffectTrial(instance, offer) {
+        const row = this.webChatHistory.recordEffectTrial(instance, offer, new Date().toISOString());
+        if (!row)
+            return false;
+        broadcastSseEvent(this.sseClients, "message", row, err => this.logger.debug({ err }, "SSE client write failed; evicting"), this.webChatHistory.cursorOf(row));
+        return true;
+    }
     /** Push an SSE event to all connected Web UI clients. */
     emitSseEvent(event, data) {
         // #1386: a prompt opened or closed, or an instance's state moved — "Needs you" may have changed.
@@ -14626,8 +14975,12 @@ export class FleetManager {
                 role: typeof m.role === "string" ? m.role : undefined,
                 buttons: m.buttons,
                 click: m.click,
+                links: m.links,
             });
             broadcastSseEvent(this.sseClients, event, recorded, onError, this.webChatHistory.cursorOf(recorded));
+            // #1629: live-only receipt after the recorded agent reply. Never persist/replay it or give it an SSE cursor.
+            if (recorded.role === "agent")
+                broadcastSseEvent(this.sseClients, "agent_reply_live", { v: 1, boot: recorded.boot, id: recorded.id, instance: recorded.instance }, onError);
             return;
         }
         // #1266: a reply's buttons ended — the history shows it too (a later load, the public link's poll).
@@ -17295,6 +17648,14 @@ Plus the operational skills (fleet-health, instance-lifecycle, scheduling, sessi
             catch (err) {
                 this.logger.warn({ err: err.message, instanceName: ch.instanceName }, "Dropping a removed room from web favorites failed");
             }
+            try {
+                this.themeStore.forget(ch.instanceName);
+                this.webAppearance.limiter.forget(ch.instanceName);
+                this.effectToolsService?.forget(ch.instanceName);
+            }
+            catch (err) {
+                this.logger.warn({ err: err.message, instanceName: ch.instanceName }, "Dropping a removed room's web theme failed");
+            }
         }
         this.instanceWorldBinding.delete(ch.instanceName);
         // #1716: say so in the reply when background work was ended with the stop.
@@ -20024,6 +20385,9 @@ Plus the operational skills (fleet-health, instance-lifecycle, scheduling, sessi
         // /api/profiles (resolveInstanceIdentity) — the sidebar groups, searches and labels with it on every page.
         const classicRooms = new Map((this.classicChannels?.getAll() ?? []).map(ch => [ch.instanceName, ch]));
         const profiles = profileIdentities(this.dataDir);
+        // #1629 r4 §1: the identity card's version per instance (the page reads the card when it moves).
+        const cards = humanCards(this.dataDir);
+        const colors = identityColors(this.dataDir);
         // #1630: decorative — whatever goes wrong deciding an avatar never costs the frame (every instance gets its first character).
         let bots = { own: new Map(), speaking: new Map() };
         try {
@@ -20083,6 +20447,21 @@ Plus the operational skills (fleet-health, instance-lifecycle, scheduling, sessi
                 display_name: identity.display_name || undefined,
                 avatar: image.avatar,
                 ...(image.accent ? { accent: image.accent } : {}),
+                // #1629: the agent's theme's picture and ring colour, for viewers who show agents' themes.
+                ...(image.themeAvatar ? { theme_avatar: image.themeAvatar } : {}),
+                ...(image.themeAccent ? { theme_accent: image.themeAccent } : {}),
+                ...(() => { try {
+                    const v = cardVersion(resolveCard(name, cards.get(name), this.themeStore.get(name).theme.card));
+                    return v ? { card_v: v } : {};
+                }
+                catch {
+                    return {};
+                } })(),
+                // #1958: the identity colour's tiers (the page resolves them: the agent's only while it shows agents' themes).
+                color: { ...(colors.get(name)?.color ? { person: colors.get(name).color } : {}), ...(image.agentColor ? { agent: image.agentColor } : {}),
+                    ...(image.roleColor ? { role: image.roleColor } : {}), auto: autoIdentityColor(name) },
+                // #1958 decision 2: where it shows — a person's choice for this instance, the agent's; else the viewer's host default.
+                color_show: { ...(colors.get(name)?.show ? { person: colors.get(name).show } : {}), ...(image.agentShow ? { agent: image.agentShow } : {}) },
                 description: identity.description || undefined,
                 role: identity.role || undefined,
                 tags: identity.tags,
@@ -20109,6 +20488,8 @@ Plus the operational skills (fleet-health, instance-lifecycle, scheduling, sessi
             connections: (this.fleetConfig?.channels ?? (this.fleetConfig?.channel ? [this.fleetConfig.channel] : [])).length,
             // #1665: the host preferences' revision — a page that has another re-reads /ui/prefs (no values in this frame).
             prefs_rev: this.webPrefs.rev(),
+            // #1629: the themes' revision — the page re-reads GET /ui/themes when it moves.
+            themes_rev: this.themeStore.rev(),
             // #1685: host memory pressure while it slows or holds new agents (the dashboard's indicator; macOS elevated is
             // shown here rather than in chat). null when normal, unknown or advisory.
             host_memory: this.hostMemoryIndicator(),