@songsid/agend 2.3.0-beta.6 → 2.3.0-beta.7

package/dist/fleet-manager.js

@@ -227,11 +227,15 @@ import { authorizeSession, decideWebGate, loadOrCreateWebToken, readWebToken } f
 import { bypassesWebGate, handleAuthRequest, serveSigninPage } from "./auth-api.js";
 import { isWebPageNavigation } from "./web-shell-routes.js";
 import { guestSessionPolicy, localSessionPolicy, tokenEpoch, WebSessionStore } from "./web-session.js";
-import { evaluateWebAuthority, webAuthorityPolicy } from "./authority/web-authority.js";
+import { authorityNow, evaluateWebAuthority, VERIFIED_SESSION_HOURS, webAuthorityPolicy } from "./authority/web-authority.js";
+import { AuthorityStateStore } from "./authority/authority-state.js";
+import { SessionAuthorizations } from "./authority/session-authorizations.js";
+import { SessionAuthorizationRequests } from "./web-session-authorization.js";
 import { GuestLoginCodes, WebLoginCodes, LOGIN_CODE_TTL_MS } from "./web-login.js";
 import { CodeRequestLimiter, ReturningDevices } from "./web-returning-device.js";
-import { allowedHostNames, applyWebSecurityHeaders, hostnameOf, isHostAllowed, WEB_HOST_REJECTED_MESSAGE } from "./web-host-guard.js";
+import { allowedHostNames, applyWebSecurityHeaders, hostnameOf, isHostAllowed, LOOPBACK_HOST_NAMES, WEB_HOST_REJECTED_MESSAGE } from "./web-host-guard.js";
 import { createPreviewListener, normalizeOrigin, previewAvailability, previewSettings } from "./web-preview.js";
+import { createEffectBootstrap } from "./web-effect-bootstrap.js";
 import { fleetLevelDifferences, fleetLevelSignature, appendedConnections } from "./fleet-level-config.js";
 import { checkSelfRestartAllowance, recordSelfRestartAttempt } from "./self-restart-limit.js";
 import { SecretStore } from "./secret-store.js";
@@ -779,6 +783,10 @@ export class FleetManager {
     collabInstances = new Set();
     // Health endpoint
     healthServer = null;
+    /** #2118: independent of HTML preview availability/port; fixed bootstrap only, no effect resources. */
+    effectBootstrap = createEffectBootstrap();
+    /** Fixed trusted document coherence, independent of the HTML preview listener; never a resource grant. */
+    get effectBoot() { return this.effectBootstrap.boot; }
     healthServerDrain = null;
     /** #1306: the preview listener (health_port + 1 by default), and whether it is listening. */
     previewListener = null;
@@ -1003,7 +1011,7 @@ export class FleetManager {
                 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.
+            // A nonmutating own/shared offer is not an appearance write. Only an explicit non-public admin-session click may start it.
             preview: async (instance, id) => {
                 const result = this.effectTrials.offer(instance, id);
                 if (!result.ok)
@@ -1011,11 +1019,12 @@ export class FleetManager {
                 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." };
+                return { id, status: "offered", expiresAt: result.offer.expiresAt, message: "A trial card is in your web chat. A signed-in admin outside the public link can start it; nothing was applied." };
             },
             profiles: id => this.effectProfiles.read(id),
             profileSummary: id => this.effectService.profileSummary(id),
             profileSummaries: ids => this.effectService.profileSummaries(ids),
+            playbackSummary: (name, id) => this.effectService.playbackSummary(name, id),
         }));
     }
     appearanceToolsService;
@@ -1023,7 +1032,12 @@ export class FleetManager {
     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 }; },
+            theme: (name) => {
+                const r = this.themeStore.get(name);
+                return { theme: r.theme, locked: r.locked, widgets: r.placements.widgets, ambient: r.placements.ambient,
+                    glyphAsset: (id) => this.themeStore.asset(name, id) };
+            },
+            effects: name => this.themeStore.readable() ? this.themeStore.get(name).placements.effects.map(p => ({ id: p.id, by: p.by, ...(p.params ? { params: p.params } : {}), playback: this.effectService.playbackSummary(name, p.id) })) : [],
             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 {
@@ -1121,6 +1135,8 @@ export class FleetManager {
             setBannerFocus: (name, focus) => { const w = setPersonBannerFocus(this.dataDir, name, focus); if (w.ok)
                 this.identityChanged(); return w; },
             placements: (name) => this.themeStore.get(name).placements.effects.map((e) => (typeof e === "string" ? { id: e } : e)),
+            ambient: (name) => Object.fromEntries(Object.entries(this.themeStore.get(name).placements.ambient).flatMap(([k, a]) => a ? [[k, { spec: a.spec, by: a.by }]] : [])),
+            setAmbient: (name, spec, which) => this.webAppearance.humanSetAmbient(name, spec, which),
             announce: () => { try {
                 this.emitSseEvent("status", this.getUiStatus());
             }
@@ -1745,10 +1761,18 @@ export class FleetManager {
     queryDurableDeliveryStatus(callerInstance, selector) {
         this.ensureDeliveryOutbox();
         const page = this.deliveryOutbox.queryStatusForInstance(callerInstance, selector);
+        // #1939 §10: a human receipt's authority as it reads now (switch, epoch, loopback_only).
+        const state = page.items.some(item => item.authority) ? this.webAuthorityState() : null;
+        const human = (item) => {
+            if (!item.authority || !state)
+                return item;
+            const authority = authorityNow(item.authority, state);
+            return { ...item, authority, ...(authority.downgraded ? { source_instance: "human:web:unknown" } : {}) };
+        };
         // #1641: a sender that sees only `queued` cannot tell "next in line" from "the target is stuck": say which.
         return {
             ...page,
-            items: page.items.map(item => (item.state === "queued" || item.state === "retry_wait")
+            items: page.items.map(human).map(item => (item.state === "queued" || item.state === "retry_wait")
                 ? { ...item, waiting_reason: this.deliveryWaitingReason(item.target_instance) }
                 : item),
         };
@@ -3832,24 +3856,31 @@ export class FleetManager {
     }
     /** Evidence-only admission. Bots/system/agent payloads have no trusted origin. */
     humanReceiptPayload(instanceName, payload, origin, originalBody) {
+        // #1939 S3: "via web (verified)" comes only from the receipt written here — never from a caller's meta.
+        const given = payload.meta;
+        if (given && "web_verified" in given) {
+            const { web_verified: _claimed, ...rest } = given;
+            payload = { ...payload, meta: rest };
+        }
         if (!origin || !this.deliveryOutbox)
             return payload;
         const row = this.deliveryOutbox.createHumanReceipt({ targetInstance: instanceName, originalBody,
             origin: { ...origin }, inputKind: String(payload.type), managerBootId: this.managerBootId });
         // #1939 §7: each ordinary verified web message, for the S1 beta to watch. No text, cookie or session id: the handle.
         const authority = origin.authority;
-        if (authority?.kind === "web-session" && authority.actor && authority.session) {
+        if (authority?.kind === "web-verified" && authority.actor && authority.session) {
             try {
                 this.eventLog?.insert(instanceName, "web_authority", { receipt_id: row.receipt_id, session: authority.session.handle,
                     peer: authority.session.peer, surface: "local", actor: `${authority.actor.adapter_id}:${authority.actor.user_id}`,
-                    input_kind: String(payload.type), outcome: "web-session", authority_epoch: authority.authority_epoch });
+                    input_kind: String(payload.type), outcome: "web-verified", authority_epoch: authority.authority_epoch });
             }
             catch (err) {
                 this.logger.warn({ err, instanceName }, "Could not record web authority");
             }
         }
+        const verified = origin.platform === "web" && authority?.kind === "web-verified";
         return { ...payload, meta: { ...(payload.meta ?? {}),
-                human_receipt_id: row.receipt_id, verification_id: row.message_id } };
+                human_receipt_id: row.receipt_id, verification_id: row.message_id, ...(verified ? { web_verified: "1" } : {}) } };
     }
     /** Bind at the actual IPC send, after all wake/reconnect waits. No human retry lane. */
     bindHumanReceiptPayload(instanceName, payload) {
@@ -6045,7 +6076,9 @@ export class FleetManager {
         // #1570: no browser may ask the sign-in page for a code any more.
         const devices = this.returningDevices.revokeAll();
         const sessions = this.webSessions.revokeAll();
-        const result = { count: sessions.count, durable: sessions.durable && devices.durable };
+        // #1939 §10: and every web authority given so far (its receipts read as none).
+        const authority = this.revokeWebAuthority();
+        const result = { count: sessions.count, durable: sessions.durable && devices.durable && authority.durable };
         if (result.durable)
             this.logger.info({ count: result.count, devices: devices.count }, "Web sessions revoked (all)");
         else
@@ -7078,6 +7111,13 @@ export class FleetManager {
         this.pruneEventLog();
         this.eventLogPruneTimer = setInterval(() => this.pruneEventLog(), 24 * 60 * 60_000);
         this.eventLogPruneTimer.unref?.();
+        // #2122 §5.5: usage is collected from the start, not from the first time someone opens a report — the same bounded
+        // background passes the cache report uses (16 MB a pass, then every 10 minutes).
+        {
+            const cache = this.cacheServiceFor();
+            cache.start();
+            void cache.kick();
+        }
         // #1920 §3.2: guests' ClassicBot room membership, read in the background — now, then each key ten minutes after
         // its answer (a minute after a failed read; the tick only finds what is due). A request only reads the answers.
         void this.refreshAllGuestRooms();
@@ -10008,6 +10048,7 @@ export class FleetManager {
         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_set_web_ambient" || type === "fleet_clear_web_ambient"
             || type === "fleet_export_web_mod" || type === "fleet_propose_web_mod") {
             this.handleWebTheme(name, msg);
             return;
@@ -12891,6 +12932,8 @@ export class FleetManager {
     }
     /** Routes a click to the handler that owns its prefix; false when none does. */
     async dispatchAdapterCallback(data, adapterId, adapter) {
+        if (await this.sessionAuthorizationRequests().handleCallback(data, adapterId))
+            return true; // #1939 S2b
         if (data.callbackData.startsWith(REPLY_BUTTON_PREFIX)) { // #1266
             const buttons = this.replyButtons();
             if (!buttons) {
@@ -13028,7 +13071,7 @@ export class FleetManager {
     cacheInstances() {
         const fleet = Object.entries(this.fleetConfig?.instances ?? {}).map(([name, cfg]) => ({
             name, backend: this.backendNameOf(name), workingDirectory: cfg.working_directory, ledgerPath: join(this.getInstanceDir(name), "cache-ledger.json"),
-            claudeConfigDir: this.claudeConfigDirOf(name),
+            claudeConfigDir: this.claudeConfigDirOf(name), profile: this.usageProfileOf(name, this.backendNameOf(name)),
         }));
         const taken = new Set(fleet.map(i => i.name));
         const classic = (this.classicChannels?.getAll() ?? []).filter(ch => !taken.has(ch.instanceName)).map(ch => ({
@@ -13037,6 +13080,7 @@ export class FleetManager {
             workingDirectory: join(getAgendHome(), "workspaces", ch.instanceName),
             ledgerPath: join(this.getInstanceDir(ch.instanceName), "cache-ledger.json"),
             claudeConfigDir: this.claudeConfigDirOf(ch.instanceName),
+            profile: this.usageProfileOf(ch.instanceName, this.classicChannels?.getBackendByInstance(ch.instanceName, this.fleetConfig?.defaults?.backend) ?? this.fleetConfig?.defaults?.backend ?? "claude-code"),
         }));
         return [...fleet, ...new Map(classic.map(c => [c.name, c])).values()];
     }
@@ -13048,6 +13092,45 @@ export class FleetManager {
     cacheReport(window) {
         return this.cacheServiceFor().report(cacheWindow(window));
     }
+    /**
+     * #2122 §5.1: the profile the usage read now is tagged with — the claude profile whose config dir is read ("default"
+     * without one); codex "unrecorded" (its rollouts don't say which login wrote them).
+     */
+    usageProfileOf(name, backend) {
+        if (backend === "claude-code")
+            return this.credentialProfileOf(name, "claude-code") ?? "default";
+        if (backend === "codex")
+            return "unrecorded";
+        return undefined;
+    }
+    /** #2122: the fleet's day boundary zone — defaults.scheduler.default_timezone, else this host's. */
+    usageZone() {
+        return this.fleetConfig?.defaults?.scheduler?.default_timezone?.trim() || Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC";
+    }
+    /**
+     * #2122: the usage report (usage-report.ts) — from the ledgers and rollups as they are now and the delivered-message
+     * counts; never a transcript read. `only`: just that instance (an ordinary agent's own row).
+     */
+    async usageReport(params) {
+        const { buildUsageReport } = await import("./usage-report.js");
+        const data = await this.cacheServiceFor().usageData();
+        const team = new Map();
+        for (const [t, cfg] of Object.entries(this.fleetConfig?.teams ?? {}))
+            for (const m of cfg?.members ?? [])
+                if (!team.has(m))
+                    team.set(m, t);
+        const now = Date.now();
+        this.ensureDeliveryOutbox?.();
+        // Every hour of the kept history: the report places each on a local date and keeps the range's own.
+        const messages = this.deliveryOutbox?.deliveredMessageHours(now - 401 * 86_400_000, now + 3_600_000) ?? [];
+        const keep = (name) => params.only === undefined || name === params.only;
+        return buildUsageReport({
+            now, zone: this.usageZone(), range: params.range, group: params.group, scanning: data.scanning,
+            instances: data.instances.filter(i => keep(i.inst.name)).map(i => ({ name: i.inst.name, backend: i.inst.backend, team: team.get(i.inst.name) ?? null,
+                status: i.status, ...(i.with ? { with: i.with } : {}), ledger: i.ledger, days: i.days })),
+            messages: messages.filter(m => keep(m.instance)),
+        });
+    }
     /** #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));
@@ -13059,7 +13142,9 @@ export class FleetManager {
             claudeKey: claudeProjectKey,
             codexSessionsDir: () => join(process.env.CODEX_HOME?.trim() || join(homedir(), ".codex"), "sessions"),
             listRollouts: root => sharedRolloutIndex(root).list(),
+            rolloutsUnreadable: root => sharedRolloutIndex(root).unreadable,
             metaPath: join(this.dataDir, "cache-codex-rollouts.json"),
+            zone: () => this.usageZone(),
             log: (level, msg, extra) => this.logger[level](extra ?? {}, msg),
         });
     }
@@ -13576,13 +13661,192 @@ export class FleetManager {
      * token; `instance` once the body has named it. Observe only: receipts record it, no agent acts on it yet.
      */
     webAuthority(input) {
+        const state = this.webAuthorityState();
         return evaluateWebAuthority({
             session: input.session, gateway: input.gateway, peer: input.peer,
             tokenEpoch: this.webToken ? tokenEpoch(this.webToken) : null,
             ...(input.instance !== undefined ? { target: { adapterId: this.getInstanceAdapterId(input.instance) } } : {}),
             isAdmin: (userId, adapterId) => this.adminGate(userId, adapterId) === "ok",
-            policy: webAuthorityPolicy(this.fleetConfig?.web), epoch: 0, now: Date.now(),
+            authorization: input.session ? this.sessionAuthorizationStore()?.get(input.session.handle) ?? null : null,
+            policy: { ...webAuthorityPolicy(this.fleetConfig?.web), enabled: state.enabled, loopbackOnly: state.loopbackOnly }, epoch: state.epoch, now: Date.now(),
+        });
+    }
+    sessionAuthorizations = null;
+    sessionAuthorizationStore() {
+        if (!this.dataDir)
+            return null;
+        this.sessionAuthorizations ??= new SessionAuthorizations(join(this.dataDir, "web-authorizations.json"), this.logger);
+        return this.sessionAuthorizations;
+    }
+    /**
+     * #1939 §0: record that a session's account has authorized it — called only once that account has confirmed on Discord
+     * or Telegram (S2b). The session must qualify now (§3, as a message from it would be judged); then every message,
+     * click, /steer and /btw from it is web-verified until max_session_hours after now, the session ends, or a revocation.
+     * Ones no longer worth keeping (their session gone, an old epoch, run out) are dropped on the way.
+     */
+    authorizeWebSession(session, peer, gateway) {
+        const store = this.sessionAuthorizationStore();
+        const state = this.webAuthorityState(), now = Date.now(), policy = webAuthorityPolicy(this.fleetConfig?.web);
+        if (!store || !session.owner)
+            return { ok: false, refusal: !store ? "disabled" : "no_account" };
+        const check = evaluateWebAuthority({
+            session, gateway, peer, tokenEpoch: this.webToken ? tokenEpoch(this.webToken) : null,
+            isAdmin: (userId, adapterId) => this.adminGate(userId, adapterId) === "ok",
+            authorization: { handle: session.handle, owner: session.owner, authorizedAt: now, until: now + policy.maxSessionMs, epoch: state.epoch },
+            policy: { ...policy, enabled: state.enabled, loopbackOnly: state.loopbackOnly }, epoch: state.epoch, now,
+        });
+        if (check.refusal)
+            return { ok: false, refusal: check.refusal };
+        const live = new Set(this.webSessions?.list(undefined, () => true).map(r => r.handle) ?? []);
+        store.prune(a => a.epoch === state.epoch && now <= Math.min(a.until, a.authorizedAt + policy.maxSessionMs) && live.has(a.handle));
+        return { ok: true, ...store.authorize(session.handle, session.owner, now, state.epoch, now + policy.maxSessionMs) };
+    }
+    authorityStateStore = null;
+    /**
+     * #1939 §10: the switch, "Only this computer can authorize" and the revocation epoch in force for the configuration as
+     * it is now (a change since last seen moves the epoch first; authority-state.ts). No data directory: off.
+     */
+    webAuthorityState() {
+        if (!this.dataDir)
+            return { enabled: false, loopbackOnly: true, epoch: 0 };
+        this.authorityStateStore ??= new AuthorityStateStore(join(this.dataDir, "web-authority.json"), this.logger, undefined, undefined, () => { this.ensureDeliveryOutbox?.(); return this.deliveryOutbox?.maxWebAuthorityEpoch() ?? 0; });
+        return this.authorityStateStore.current(this.fleetConfig?.web?.verified_authority);
+    }
+    /**
+     * #1939 S2a: Settings → Web → Web authority — the state in force (the switch counts as off while its state cannot be
+     * written), what fleet.yaml says, the hosts that make the dashboard reachable from elsewhere (the warning while
+     * loopback_only is off), and the sessions authorized now (§0): each one's device, account, and when it runs out.
+     */
+    webAuthorityOverview() {
+        const configured = this.fleetConfig?.web?.verified_authority ?? {};
+        const lanHosts = (this.fleetConfig?.web?.allowed_hosts ?? []).filter(h => { const name = hostnameOf(String(h)); return name !== null && !LOOPBACK_HOST_NAMES.includes(name); });
+        const state = this.webAuthorityState(), maxMs = webAuthorityPolicy(this.fleetConfig?.web).maxSessionMs, now = Date.now();
+        const sessions = new Map((this.webSessions?.list(undefined, () => true) ?? []).map(r => [r.handle, r]));
+        const authorized = state.enabled ? (this.sessionAuthorizationStore()?.list() ?? [])
+            .filter(a => a.epoch === state.epoch && sessions.has(a.handle) && now <= Math.min(a.until, a.authorizedAt + maxMs))
+            .map(a => ({ handle: a.handle, label: sessions.get(a.handle).label, account: `${a.owner.adapterId}:${a.owner.userId}`, authorizedAt: a.authorizedAt,
+            until: Math.min(a.until, a.authorizedAt + maxMs, sessions.get(a.handle).absoluteExpiry) })) : [];
+        return { state, configured, hours: VERIFIED_SESSION_HOURS, lanHosts, authorized };
+    }
+    authorizationRequests = null;
+    /**
+     * #1939 S2b (§0.1): "Authorize this browser" — the Confirm card in the account's DM. Confirm runs §3 again at the tap
+     * (authorizeWebSession on the session read again by its handle); Not me signs the session out.
+     */
+    sessionAuthorizationRequests() {
+        if (this.authorizationRequests)
+            return this.authorizationRequests;
+        const adapterOf = (adapterId) => this.adapters.get(adapterId) ?? this.worlds.get(adapterId)?.adapter;
+        // The host's clock, with its zone: the person may read the DM on a phone in another one.
+        const when = (ms) => new Date(ms).toLocaleString(undefined, { timeZoneName: "short" });
+        const where = (peer) => t(peer === "loopback" ? "web_auth.peer_loopback" : "web_auth.peer_lan");
+        return this.authorizationRequests = new SessionAuthorizationRequests({
+            now: () => performance.now(), wallNow: () => Date.now(),
+            maxSessionMs: () => webAuthorityPolicy(this.fleetConfig?.web).maxSessionMs,
+            sendDirect: async (owner, text, choices) => {
+                const adapter = adapterOf(owner.adapterId);
+                if (!adapter?.sendDirect)
+                    return null;
+                const sent = await adapter.sendDirect(owner.userId, text, { choices, allowedMentions: { parse: [] } });
+                return sent?.messageId ? { chatId: sent.chatId, messageId: sent.messageId } : null;
+            },
+            sendGeneralHint: async (owner, text) => {
+                const adapter = adapterOf(owner.adapterId), general = this.findGeneralInstance(owner.adapterId);
+                const topic = general ? this.fleetConfig?.instances[general]?.topic_id : undefined;
+                const group = general ? this.getGroupIdForInstance(general) : undefined;
+                if (adapter && group)
+                    await adapter.sendText(String(group), text, { ...(topic != null ? { threadId: String(topic) } : {}), allowedMentions: { parse: [] } });
+            },
+            editCard: async (owner, at, text, choices) => {
+                const adapter = adapterOf(owner.adapterId);
+                if (!adapter)
+                    return;
+                if (!choices.length && adapter.editMessageRemoveButtons) {
+                    await adapter.editMessageRemoveButtons(at.chatId, at.messageId, text);
+                    return;
+                }
+                await adapter.editMessage(at.chatId, at.messageId, text);
+                if (adapter.replaceMessageButtons)
+                    await adapter.replaceMessageButtons(at.chatId, at.messageId, choices);
+            },
+            authorize: (handle, peer) => {
+                const record = this.webSessions?.findByHandle(handle);
+                if (!record)
+                    return { ok: false, refusal: "session_gone" };
+                const r = this.authorizeWebSession(record, peer, false);
+                // What the card says: the end of the authorization, or the session's own end when that comes first.
+                return r.ok ? { ok: true, until: Math.min(r.authorization.until, record.absoluteExpiry) } : { ok: false, refusal: r.refusal };
+            },
+            signOut: (handle) => {
+                this.webSessions?.revokeByHandle(handle);
+                this.sessionAuthorizationStore()?.prune(a => a.handle !== handle);
+            },
+            event: (type, payload) => { try {
+                this.eventLog?.insert("web", type, payload);
+            }
+            catch { /* the event log is best effort */ } },
+            text: {
+                ask: (c) => t("web_auth.card_ask", c.label, where(c.peer), when(c.askedAt), when(c.until)),
+                confirmed: (c) => t("web_auth.card_confirmed", c.label, where(c.peer), when(c.until)),
+                denied: (c) => t("web_auth.card_denied", c.label),
+                expired: (c) => t("web_auth.card_expired", c.label),
+                refused: (c) => t("web_auth.card_refused", c.label, t(`web_auth.refusal_${c.refusal}`)),
+                revoked: (c) => t("web_auth.card_revoked", c.label),
+                ended: (c) => t("web_auth.card_ended", c.label),
+                generalHint: () => t("web_auth.general_hint"),
+                confirmLabel: () => t("web_auth.confirm"),
+                notMeLabel: () => t("web_auth.not_me"),
+                notYours: () => t("web_auth.not_yours"),
+            },
+            log: this.logger,
+        });
+    }
+    /** #1939 S2b: the web session asks to be authorized (the request judged by §3 first — as it will be again at the tap). */
+    async requestSessionAuthorization(input) {
+        const s = input.session;
+        const gate = this.webAuthorityQualifies(input);
+        if (gate)
+            return { ok: false, refusal: gate };
+        return this.sessionAuthorizationRequests().ask({ handle: s.handle, owner: s.owner, label: s.label, peer: input.peer, sessionEnd: s.absoluteExpiry });
+    }
+    /**
+     * #1939 §3 without the authorization: would this request's session qualify to be authorized? null: yes; otherwise the
+     * first check it fails (for the app to say why it can't be authorized here).
+     */
+    webAuthorityQualifies(input) {
+        const s = input.session, state = this.webAuthorityState(), now = Date.now(), policy = webAuthorityPolicy(this.fleetConfig?.web);
+        const r = evaluateWebAuthority({
+            session: s, gateway: input.gateway, peer: input.peer, tokenEpoch: this.webToken ? tokenEpoch(this.webToken) : null,
+            isAdmin: (userId, adapterId) => this.adminGate(userId, adapterId) === "ok",
+            authorization: s?.owner ? { handle: s.handle, owner: s.owner, authorizedAt: now, until: now + policy.maxSessionMs, epoch: state.epoch } : null,
+            policy: { ...policy, enabled: state.enabled, loopbackOnly: state.loopbackOnly }, epoch: state.epoch, now,
         });
+        return r.refusal;
+    }
+    /** #1939 S2b: what the app shows for this browser — verified (until when), a card pending, or why not. */
+    webSessionAuthorization(input) {
+        const s = input.session;
+        const verdict = this.webAuthority(input);
+        if (!verdict.refusal && verdict.authority.session) {
+            const a = this.sessionAuthorizationStore()?.get(s.handle);
+            const max = webAuthorityPolicy(this.fleetConfig?.web).maxSessionMs;
+            if (a)
+                return { state: "verified", until: Math.min(a.until, a.authorizedAt + max, s.absoluteExpiry) };
+        }
+        const pending = s ? this.sessionAuthorizationRequests().pending(s.handle) : null;
+        if (pending)
+            return { state: "pending", expiresInMs: pending.expiresInMs };
+        return { state: "none", reason: this.webAuthorityQualifies(input) ?? (verdict.refusal ?? "not_authorized") };
+    }
+    /** #1939 §10: revoke every web authority given so far (receipts read as none), without signing anyone out. */
+    revokeWebAuthority() {
+        this.webAuthorityState(); // any switch change first, then this revocation
+        const result = this.authorityStateStore?.revoke() ?? { epoch: 0, durable: false };
+        if (result.durable)
+            this.logger.info({ epoch: result.epoch }, "Web authority revoked");
+        else
+            this.logger.warn({ epoch: result.epoch }, "Web authority revoked in memory only — web authority stays off until its state can be written; a restart before then undoes this revocation");
+        return result;
     }
     /** #1269: an instance's chat command from the web chat (web-commands.ts); `publicLink`: a gateway request. */
     webCommand(input, opts) {
@@ -20711,6 +20975,8 @@ Plus the operational skills (fleet-health, instance-lifecycle, scheduling, sessi
                 return;
             }
             const requestPath = new URL(req.url ?? "/", `http://localhost:${port}`).pathname;
+            if (this.effectBootstrap.handle(req, res))
+                return;
             // Branding is public, after Host admission: automatic favicon requests
             // must not become noisy web-token 401s in the browser console.
             if (handleWebIconRequest(req, res, requestPath))
@@ -21338,6 +21604,8 @@ Plus the operational skills (fleet-health, instance-lifecycle, scheduling, sessi
                 catch {
                     return {};
                 } })(),
+                // #2118: only this Chat's placement content; guest projection drops global revisions.
+                effect_chat_v: createHash("sha256").update(JSON.stringify(this.themeStore.get(name).placements.effects)).digest("hex").slice(0, 32),
                 // #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) },