@songsid/agend 2.2.1 → 2.3.0-beta.10

package/dist/fleet-manager.d.ts

@@ -6,10 +6,11 @@ import type { CpuProfile } from "./cpu-profile.js";
 import { type FleetMemory } from "./process-memory.js";
 import { MemoryPressure, type MemoryPressureSnapshot } from "./memory-pressure.js";
 import { ReplyDeduper } from "./reply-dedup.js";
-import type { FleetConfig, RawFleetConfig, InstanceConfig } from "./types.js";
+import type { FleetConfig, RawFleetConfig, InstanceConfig, WebVerifiedAuthorityConfig } from "./types.js";
 import { type DeliveryStatus, type GuildEmoji, type GuildEmojiGroup, type ResolvedStatusEmojis } from "./status-emojis.js";
 import { type RouteTarget } from "./fleet-context.js";
 import { EventLog } from "./event-log.js";
+import { BackendAvailabilityStore, type AvailabilityProbes, type BackendAvailability } from "./backend-availability.js";
 import { AdapterWorld } from "./adapter-world.js";
 import { CostGuard } from "./cost-guard.js";
 import { IpcClient } from "./channel/ipc-bridge.js";
@@ -57,11 +58,24 @@ import { type LogAnswer, type LogQuery } from "./log-service.js";
 import { WebChatHistory } from "./web-chat-history.js";
 import { SeenUsers, type MentionNames, type MentionQuery } from "./web-mentions.js";
 import { WebPrefsStore } from "./web-prefs.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 } from "./web-effect-tools.js";
 import { type WebAccount } from "./web-profile.js";
 import type { WebPerson as WebPersonView } from "./web-api.js";
 import { ReplyButtonsController } from "./reply-buttons-controller.js";
 import { WebFileLedger } from "./web-upload.js";
+import { AppearanceTools } from "./web-appearance-tools.js";
+import { ModStore } from "./web-mod-store.js";
+import { AgentMods } from "./web-mod-agent.js";
 import { type CachedImage } from "./web-images.js";
+import { WebSettingsTools } from "./web-settings-tools.js";
+import { type Delegation, type TrafficItem } from "./fleet-traffic.js";
 import { type RawConfigPatch } from "./settings-api.js";
 import { type AgentEndpointContext } from "./agent-endpoint.js";
 import { ClassicChannelManager } from "./classic-channel-manager.js";
@@ -73,8 +87,14 @@ import { TargetQueueWorker } from "./target-queue-worker.js";
 import { resolveDeliveryWorkerMode } from "./types.js";
 import { type WebNeedsItem } from "./needs-you-hub.js";
 import { type OrgChart } from "./web-org.js";
+import { type MemoryHog } from "./memory-hogs.js";
 import { type CacheReport } from "./cache-service.js";
 import { type WebCommandResult } from "./web-commands.js";
+import { type SessionRecord } from "./web-session.js";
+import { VERIFIED_SESSION_HOURS, type HumanAuthority, type WebAuthorityRefusal, type WebAuthorityResult, type WebPeer } from "./authority/web-authority.js";
+import { type AuthorityState } from "./authority/authority-state.js";
+import { type SessionAuthorization } from "./authority/session-authorizations.js";
+import { SessionAuthorizationRequests, type AuthorizationAskRefusal } from "./web-session-authorization.js";
 import { type ReturningDevice } from "./web-returning-device.js";
 import { type PreviewAvailability } from "./web-preview.js";
 import { type ConnectionMetadata, type ConnectionBinding, type BindingProbe, type SecretApplyJob, type ProviderSecretApplyJob } from "./connection-secrets.js";
@@ -101,12 +121,10 @@ export declare function selectLruEvictions(warm: string[], cap: number, opts: {
     lastInboundAt: (name: string) => number;
 }): string[];
 /**
- * Window-name shape this fleet recognises as an instance window: the
- * `-t<digits>` form every allocator emits, plus legacy `classic-` windows.
- * Startup cleanup reaps windows matching this that are no longer in
- * fleet.yaml. Keep in sync with `uniqueInstanceName` — every name it emits
- * must match here, or a deleted instance's CLI is left running (#1305 P2-3).
+ * #2163: whether `dir` is inside AgEnD's own workspaces (<AGEND_HOME>/workspaces/<name>/…), compared after resolving
+ * symlinks on both sides — including a missing folder's existing ancestors — so a link elsewhere is not inside, nor is a broken link.
  */
+export declare function insideManagedWorkspaces(dir: string, agendHome?: string): boolean;
 export declare function isOrphanInstanceWindowName(name: string): boolean;
 /** restartSingleInstance's options. `carry` (#1753): a credential-profile switch; its outcome is written into `result`. */
 export interface RestartOpts {
@@ -390,6 +408,8 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     /** At most one reconnect/backoff loop may exist per instance. */
     private ipcReconnectInFlight;
     private adapterRestarting;
+    /** #2175: this boot's progress message, whose completion may still be owed by its background retry. */
+    private startupProgress;
     private adapterState;
     /** Web Settings secret rotation is deliberately separate from reconnect
      * recovery: a rotation must build a fresh provider client with the new token,
@@ -427,10 +447,16 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     private connectionBindingInFlight;
     private collabInstances;
     private healthServer;
+    /** #2118: independent of HTML preview availability/port; fixed bootstrap only, no effect resources. */
+    private readonly effectBootstrap;
+    /** Fixed trusted document coherence, independent of the HTML preview listener; never a resource grant. */
+    get effectBoot(): string;
     private healthServerDrain;
     /** #1306: the preview listener (health_port + 1 by default), and whether it is listening. */
     private previewListener;
     private previewListening;
+    /** The preview listener could not open its port: "<port>: <error code>", for the page (#2061 follow-up); null otherwise. */
+    private previewListenError;
     /** The ports the preview listener was started for, and the inputs it was built from (a reload compares them). */
     private previewPorts;
     private previewInputs;
@@ -449,6 +475,9 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     /** Injectable only to keep the chat→CLI reload hand-off deterministic in tests. */
     private fullRestartLauncher;
     private eventLogPruneTimer;
+    /** #1920 §3.2: the background reads of guests' ClassicBot room membership (a minute's tick; reads only what is due). */
+    private guestRoomsTimer;
+    private guestRoomMembership;
     private outboxPruneTimer;
     private logRotateTimer;
     private discordPresenceTimer;
@@ -463,6 +492,17 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     private startedAt;
     private stormOpenNotifyTimer;
     private memoryLogAt;
+    /**
+     * #2015: while host memory is elevated or critical, the processes holding the most in the fleet's service and whose
+     * they are (an instance, the fleet, tmux), for the pressure log, /health and the dashboard — never chat (#1712).
+     * Rescanned at most once a minute (async, one at a time); cleared when pressure ends.
+     */
+    private memoryTop;
+    private memoryTopScan;
+    /** The scan (a seam for tests: they give it a fake /proc). */
+    private memoryHogScan;
+    /** The fleet's own tmux session exists (only then are its panes read: a fleet that never started has none). */
+    private tmuxSessionEnsured;
     private memoryDebugAt;
     private memoryLogLevel;
     /** #1685: the host_memory value the last status frame carried, so a change re-sends the frame. */
@@ -512,6 +552,63 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
      */
     private webNameReserved;
     private webNameTaken;
+    private themeStoreInstance?;
+    private webAppearanceService?;
+    /** #1629: every instance's theme, placements, assets and lock (web-themes.json). */
+    get themeStore(): ThemeStore;
+    /** #1629: the theme tools, a person's reset and lock, and the one appearance rate limiter (shared with effects). */
+    get webAppearance(): WebAppearance;
+    private effectLibraryInstance?;
+    private effectTrialsInstance?;
+    /** Lazy, single-owner storage. Register every host reference source before any operation can collect. */
+    get effectLibrary(): WebEffectLibrary;
+    /** Volatile Try offers and session-bound runs share this library. */
+    get effectTrials(): WebEffectTrials;
+    private effectProfilesInstance?;
+    get effectProfiles(): WebEffectProfiles;
+    private effectServiceInstance?;
+    get effectService(): WebEffectService;
+    private effectToolsService?;
+    /** Caller identity is supplied only by the owned IPC connection / verified agent endpoint token. */
+    get effectTools(): WebEffectTools;
+    private appearanceToolsService?;
+    /** #1629 r4 §1: get_web_appearance / preview_web_appearance — the caller's own look, resolved as the page resolves it. */
+    get appearanceTools(): AppearanceTools;
+    /** #1958: a profile, card or colour write (view-api.ts) landed: every open page gets a fresh status frame. */
+    identityChanged(): void;
+    /** A fleet.yaml instance (own key) or a ClassicBot room, now (#1629: a person's reset/lock names one). */
+    isKnownInstance(name: string): boolean;
+    private modStore?;
+    /**
+     * #1629 r4-5 / B2: installed mods use the same validated library and scoped holder claims as direct uploads.
+     */
+    get mods(): ModStore;
+    private 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(): AgentMods;
+    /**
+     * #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: string, id: string): {
+        name: string;
+        files: ReadonlyMap<string, Uint8Array>;
+    } | null;
+    /** #1629 r4-5: an instance's card text as every viewer sees it (a person's fields over the agent's). */
+    modCardText(name: string): {
+        tagline?: string;
+        bio?: string;
+    };
+    private ownerCssStore?;
+    /** #1629 r4 §3: each person's own CSS; which version is in force is their `css.active` in the web preferences. */
+    get ownerCss(): OwnerCssStore;
+    private webSettingsToolsService?;
+    /**
+     * #2056: Settings → Web appearance for a tool (General, a coordinator, full) — the page's own stores and checks, and the
+     * page's announcement after a change (web-settings-tools.ts).
+     */
+    get webSettings(): WebSettingsTools;
     get webPrefs(): WebPrefsStore;
     /**
      * Read from disk on every access rather than cached at startup: `agend
@@ -541,9 +638,26 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     sseHeartbeatMs: number;
     /** The dashboard's login codes. Memory only: a code that outlives the process is a code nobody can prove was not copied. */
     private webLoginCodes;
+    /**
+     * #1920 step 4: guests' codes, apart from the admins' — one per account, so no guest's `/web` withdraws another's or
+     * an admin's code (#2093 review), at most 32 at once. Local sign-in only for now (audience "local").
+     */
+    private webGuestLoginCodes;
+    /** #1920 step 4: when each account last got a guest code (monotonic) — one a minute, so `/web` is no DM flood. */
+    private readonly guestCodeAskedAt;
+    /** #2093 review: an account's guest /web in progress — one at a time, so two at once cannot both pass the minute. */
+    private readonly guestCodeInFlight;
+    /**
+     * #2093 review: revokes a guest /web in progress must see — every web session's (`/web revoke` from an admin) bumps
+     * the global count, an account's own bumps its entry — checked before the code is issued and while it is delivered.
+     */
+    private guestRevokes;
+    private readonly guestAccountRevokes;
     /** #1570: browsers that may ask the sign-in page for a fresh code, and how often they may. */
     private returningDevices;
     private readonly codeRequestLimiter;
+    /** #1920 step 4b: guests' device code requests, limited apart — guests never use up the admins' fleet-wide budget. */
+    private readonly guestCodeRequestLimiter;
     /**
      * Set while a Settings apply job is driving the reconcile. The reconcile
      * stays the single doer; it just says out loud what it is doing to whom, so
@@ -589,6 +703,25 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     /** #1266: the choice, delivered as an ordinary inbound message from whoever made it, and shown in the web chat. */
     private deliverReplyButtonChoice;
     private ensureDeliveryOutbox;
+    /** #1918: cross-instance traffic, as the org canvas draws it (fleet-traffic.ts). */
+    private readonly trafficLog;
+    private readonly delegations;
+    private trafficMemo;
+    /**
+     * One delivery row's traffic item, kept for the snapshot and sent to the open pages when it is news; and the
+     * delegation it opens or closes (a task and its report), sent as "delegation".
+     */
+    private publishTraffic;
+    /**
+     * GET /ui/traffic: what is in flight now (the outbox's pending rows) and what finished in the last two minutes, at
+     * most TRAFFIC_SNAPSHOT_MAX items. Worked out at most once every two seconds, so the public link's polling (or any
+     * number of pages) costs one indexed read per two seconds. Visibility is applied as of now.
+     */
+    trafficSnapshot(): {
+        now: string;
+        items: TrafficItem[];
+        delegations: Delegation[];
+    };
     /** Synchronous SQLite admission; the caller may acknowledge only after this returns. */
     admitDurableDelivery(input: {
         operationId: string;
@@ -642,6 +775,11 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     private hostMemoryIndicator;
     /** Separate cooldown: changing measurements must not create new text-throttle keys. */
     private reportMemoryPressure;
+    /**
+     * #2015: rescan the largest processes (at most once a minute, one at a time). The first result of an episode, and
+     * then at most every 10 minutes, is logged with the pressure; /health and the dashboard read the latest. Never chat.
+     */
+    private refreshMemoryTop;
     /** Wire the one fleet-wide storm into notification and recovery surfaces. */
     private bindStormWindowEvents;
     /** What the gate allows while any storm window is open (see SpawnGate.pump). */
@@ -931,7 +1069,8 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
      * for `instance` (#1320 part B). Per entry: the channel's own adapter, no
      * thread, mention suppression on. Returns the number of channels posted
      * to. Failures are per-entry warn-and-continue — a failed echo never fails
-     * the web send. Entries without `web_echo: true` are never touched.
+     * the web send. Only entries classicWebEchoOn admits are touched (#2054: unset follows web.echo_to_channel; an explicit
+     * `web_echo: false` never echoes).
      *
      * Every copy is fenced at start time: an entry whose explicit world is
      * gone is skipped (only legacy adapterId-less entries fall back to the
@@ -942,6 +1081,11 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
      * already in flight may still land late — the contract permits that.
      */
     /** `sender` (#1827): the web person's name, as the room log records them ("web-user" when none). */
+    /**
+     * #1920 §5.2: a web message's channel copy was sent — it is now what the channel saw. Kept so (and on disk), and sent
+     * to the guests' streams only: an admin's page already has it, and nothing about it changed for them.
+     */
+    webMessageInChannel(instance: string, messageId: string): void;
     sendClassicWebEcho(instance: string, text: string, sender?: string): Promise<number>;
     /**
      * #1666: a delivered web chat message starts the same cancel/progress lifecycle in the instance's topic as a platform
@@ -1297,6 +1441,20 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
         handle: string;
         owner: LoginCodeOwner;
     }, current: () => boolean): Promise<void>;
+    /**
+     * #1920 §5.5 (step 4b): a guest signing in through the public link — said in the General of the admin who opened it
+     * (who, how many agents), awaited as an admin's public sign-in is, while that link is the open one, its opener still
+     * current, and the account still an admitted guest. A failure refuses the sign-in.
+     */
+    confirmGuestPublicWebLogin(info: {
+        label: string;
+        handle: string;
+        account: {
+            adapterId: string;
+            userId: string;
+        };
+        exposureId: string;
+    }, current: () => boolean): Promise<void>;
     /** Telegram's typed command enters through the same strict owner and nonce path as Discord. */
     dashboardMenu(msg: InboundMessage): Promise<void>;
     /**
@@ -1334,6 +1492,77 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
         count: number;
         durable: boolean;
     };
+    /**
+     * #1920 phase 3: Settings → Web sign-ins → Guests — the switches, each connection's access mode and the agents named for
+     * an open one, and every guest account (signed in, with a returning device, or narrowed): who, its platform, what it
+     * reaches now, its sessions and devices, and its narrowing. Ids are the accounts' own (an admin's page).
+     */
+    guestOverview(): {
+        enabled: boolean;
+        chat: boolean;
+        instances: string[];
+        connections: Array<{
+            id: string;
+            type: string;
+            mode: "open" | "allowlist";
+            named: string[];
+        }>;
+        guests: Array<{
+            adapterId: string;
+            userId: string;
+            name: string;
+            platform: string;
+            scope: string[];
+            reach: string[];
+            sessions: number;
+            lastSeen: number | null;
+            devices: number;
+            narrow: string[] | null;
+        }>;
+    };
+    /** #1920 phase 3 (the app shell): a guest's chip — its web name, and its connection's platform (discord, telegram). */
+    guestBadge(owner: {
+        adapterId: string;
+        userId: string;
+    }): {
+        name: string;
+        platform: string;
+    };
+    /** #1920 step 4: whether a `/web` is a guest's — guest sign-in on, and not from a fleet admin (theirs runs as before). */
+    isGuestWebAsk(adapterId: string | undefined, userId: string): boolean;
+    /** #1920 step 4 (auth-api): a guest code's account may still sign in — guests on, and something in its scope now. */
+    guestSignInAllowed(account: {
+        adapterId: string;
+        userId: string;
+    }): boolean;
+    /**
+     * #1920 §5.4: a guest's own `/web revoke` — its sessions and its outstanding code; nobody else's (an admin's revokes
+     * everyone's, as before).
+     */
+    revokeGuestWebSessions(owner: {
+        adapterId: string;
+        userId: string;
+    }): {
+        count: number;
+        durable: boolean;
+    };
+    /**
+     * #1920 §2.3 (step 4): `/web` from someone who is not a fleet admin, while guest sign-in is on. `revoke` ends their
+     * own guest sessions. Otherwise a guest code (tier guest, bound to this account) goes privately — a DM, else the
+     * slash command's ephemeral answer (`replyPrivately`) — once a minute at most, and only when their scope (from what
+     * they may already use in chat, rooms read at sign-in) holds something. The code itself is never posted where asked.
+     * Callers ask isGuestWebAsk first (synchronously); false here too when it is not a guest's.
+     */
+    guestWebCommand(ask: {
+        adapterId: string;
+        userId: string;
+        username?: string;
+        arg: string;
+        replyHere: (text: string) => Promise<unknown>;
+        replyPrivately?: (text: string) => Promise<unknown>;
+    }): Promise<boolean>;
+    /** guestWebCommand's issuance, one per account at a time; a revoke made meanwhile (either kind) ends it unissued. */
+    private issueGuestCode;
     /** #1570 (auth-api): this browser becomes a returning device of the code's owner. The cookie value, or null. */
     rememberReturningDevice(owner: LoginCodeOwner, input: {
         surface: "local" | "gateway";
@@ -1359,12 +1588,31 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     } | {
         kind: "refused";
     }>;
+    /**
+     * #1920 step 4b: a guest's returning device asks for a code — a guest code for that account, by DM only, under the
+     * same rules as its /web (guests on, not an admin, something in scope now; one per account and the cap; one flow per
+     * account at a time; a revoke meanwhile ends it), its own limiter, and the guests' breaker. Asked through the public
+     * link: only while that exposure is the open one (its code then works through it alone), as an admin's device.
+     */
+    private requestGuestDeviceCode;
+    /** #1920 step 4b (auth-api): this browser becomes a guest's returning device. The cookie value, or null. */
+    rememberGuestDevice(account: {
+        adapterId: string;
+        userId: string;
+    }, input: {
+        surface: "local" | "gateway";
+        label: string;
+    }): string | null;
     /** Called by the sign-in endpoint: a login the operator did not make should be visible to them. */
     onWebLogin(info: {
         label: string;
         surface: "local" | "gateway";
         tier: string;
         handle: string;
+        owner?: {
+            adapterId: string;
+            userId: string;
+        };
     }): void;
     getDashboardAccess(): {
         ready: boolean;
@@ -1483,7 +1731,10 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
          *  reported separately because they differ by ~60x and only one of them can
          *  show a fleet-manager leak. */
         memory: FleetMemory;
-        hostMemory: MemoryPressureSnapshot;
+        hostMemory: MemoryPressureSnapshot & {
+            topProcesses?: MemoryHog[];
+            topProcessesAt?: string;
+        };
         problems: string[];
     };
     /** Start the primary adapter (backward-compatible, sets this.adapter) */
@@ -1506,6 +1757,22 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     private disposeSettingsAdapter;
     /** Restart a channel adapter after fatal error with infinite retry + 60s cap */
     private restartAdapter;
+    /**
+     * #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).
+     */
+    private placeLink;
+    /** #1990: a message for world `worldId`'s group with its place tokens rendered (links as text or Telegram entities). */
+    renderPlaces(worldId: string | undefined, text: string, opts?: import("./channel/types.js").SendOpts): {
+        text: string;
+        opts?: import("./channel/types.js").SendOpts;
+    };
+    /** #1990: renderPlaces for the world that owns `instanceName`'s topic. */
+    renderPlacesFor(instanceName: string, text: string, opts?: import("./channel/types.js").SendOpts): {
+        text: string;
+        opts?: import("./channel/types.js").SendOpts;
+    };
     /** Handle inbound message — transcribe voice if present, then route */
     private findGeneralInstance;
     /**
@@ -1619,6 +1886,11 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
      */
     private inboundNoticeAdapter;
     private handleInboundMessageCore;
+    /**
+     * A person's platform message as the web chat shows it — the user's own words, as a user (#1306), in the instance's
+     * history (#1565). #1920 §5.2: said in the instance's topic, General or room, so it is that channel's, by that account.
+     */
+    private emitPlatformInbound;
     /** Handle outbound tool calls from a daemon instance */
     /** Warn (but don't block) when rate limits are high. 30-min debounce per instance. */
     private rateLimitWarnedAt;
@@ -1661,6 +1933,14 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     /** On a fleet with no chat platform, the dashboard is where an instance-health prompt is posted (#1307 item 6). */
     private webOnlyPromptPlace;
     /** Resolves when the reply is in the web chat (#1770: after its files are copied); the caller need not wait. */
+    /**
+     * #1920 §5.2: whether a platform send landed in the instance's own place — its ClassicBot room, or its topic in its
+     * connection's group — so its channel's members saw it. Anything else (another chat, a DM, a context left from General,
+     * an answer without the chat it went to) is not the channel's.
+     */
+    private landedInOwnChannel;
+    /** #1920 §5.2 (#2085 review): a platform click's buttons are in the instance's own place — else not its channel's. */
+    private clickInOwnChannel;
     private afterReplyRouted;
     /**
      * #1770: a reply's files as the web chat shows them. Each is copied into the instance's web-files/ and served from
@@ -1724,6 +2004,12 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
      */
     private refuseTypedIpc;
     private dispatchTypedIpc;
+    /**
+     * #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.
+     */
+    private handleWebTheme;
     /** `list_emojis` / `set_persona_emoji` / `preview_emojis` / `list_stickers` / `preview_stickers` over IPC; the agent endpoint calls the same methods. */
     private handlePersonaEmoji;
     private handleScheduleCrud;
@@ -1759,6 +2045,8 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     handleListStickersHttp(instance: string, args: Record<string, unknown>): Promise<unknown>;
     handlePreviewStickersHttp(instance: string, args: Record<string, unknown>): Promise<unknown>;
     handleSetPersonaEmojiHttp(instance: string, args: Record<string, unknown>): Promise<unknown>;
+    /** #1629: `agend-agent theme …` — the same service as the tools; `instance` is the token's. */
+    handleWebThemeHttp(instance: string, tool: string, args: Record<string, unknown>): Promise<unknown>;
     handlePreviewEmojisHttp(instance: string, args: Record<string, unknown>): Promise<unknown>;
     handleSetDescriptionHttp(instance: string, description: string): Promise<unknown>;
     private summarizeToolCall;
@@ -1915,6 +2203,8 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     private guildEmojiCache;
     private guildEmojiFetches;
     private webImageCaches;
+    /** Server emoji whose picture fetch failure was already logged at warn (once each; bounded). */
+    private readonly webEmojiFailures;
     private webImageCache;
     /**
      * The bots instances and ClassicBot rooms speak through, by connections configured now (a connection removed from
@@ -2285,6 +2575,25 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
      * (cache-service.ts) — never a vendor call, never a synchronous transcript read.
      */
     cacheReport(window: string): Promise<CacheReport>;
+    /**
+     * #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).
+     */
+    private usageProfileOf;
+    /** #2122: the fleet's day boundary zone — defaults.scheduler.default_timezone, else this host's. */
+    usageZone(): string;
+    /**
+     * #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).
+     */
+    usageReport(params: {
+        range: import("./usage-report.js").UsageRange;
+        group: import("./usage-report.js").UsageGroup;
+        only?: string;
+    }): Promise<import("./usage-report.js").UsageReport>;
+    /** #2001: get_cache_report's — the same report, as last worked out (reused for a minute, until the next pass). */
+    cacheReportPublished(window: string): Promise<CacheReport>;
+    private cacheServiceFor;
     /** The web's Acknowledge (any item; a signed-in session is fleet-admin level). */
     acknowledgeNeedsItem(id: string, principal: string): {
         status: 200 | 400 | 404 | 409 | 500;
@@ -2309,6 +2618,7 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
             label: string;
         }>;
         expiresAt: number;
+        links?: import("./topic-link.js").TextLink[];
     }>;
     /**
      * A click on a prompt in the web dashboard (web track C4). It is the platform click, made by the
@@ -2334,6 +2644,8 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
         key: string;
         userId: string;
         name: string;
+        guest?: true;
+        authority?: HumanAuthority;
     }): Promise<{
         status: 200 | 400 | 403 | 409;
         error?: string;
@@ -2371,6 +2683,100 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     private readonly webBackendTokens;
     /** #1269: the web's /clear confirmations — one token per question, used once, for the instance as it was asked about. */
     private readonly webClearTokens;
+    /**
+     * #1939 S1: the design's §3 for one web request (authority/web-authority.ts), with this fleet's admins, policy and
+     * token; `instance` once the body has named it. Observe only: receipts record it, no agent acts on it yet.
+     */
+    webAuthority(input: {
+        session: SessionRecord | null;
+        gateway: boolean;
+        peer: WebPeer;
+        instance?: string;
+    }): WebAuthorityResult;
+    private sessionAuthorizations;
+    private sessionAuthorizationStore;
+    /**
+     * #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: SessionRecord, peer: WebPeer, gateway: boolean): {
+        ok: true;
+        authorization: SessionAuthorization;
+        durable: boolean;
+    } | {
+        ok: false;
+        refusal: WebAuthorityRefusal;
+    };
+    private authorityStateStore;
+    /**
+     * #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(): AuthorityState;
+    /**
+     * #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(): {
+        state: AuthorityState;
+        configured: WebVerifiedAuthorityConfig;
+        hours: typeof VERIFIED_SESSION_HOURS;
+        lanHosts: string[];
+        authorized: Array<{
+            handle: string;
+            label: string;
+            account: string;
+            authorizedAt: number;
+            until: number;
+        }>;
+    };
+    private authorizationRequests;
+    /**
+     * #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(): SessionAuthorizationRequests;
+    /** #1939 S2b: the web session asks to be authorized (the request judged by §3 first — as it will be again at the tap). */
+    requestSessionAuthorization(input: {
+        session: SessionRecord | null;
+        gateway: boolean;
+        peer: WebPeer;
+    }): Promise<{
+        ok: true;
+        expiresInMs: number;
+    } | {
+        ok: false;
+        refusal: AuthorizationAskRefusal;
+        retryAfterMs?: number;
+    }>;
+    /**
+     * #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).
+     */
+    private webAuthorityQualifies;
+    /** #1939 S2b: what the app shows for this browser — verified (until when), a card pending, or why not. */
+    webSessionAuthorization(input: {
+        session: SessionRecord | null;
+        gateway: boolean;
+        peer: WebPeer;
+    }): {
+        state: "verified";
+        until: number;
+    } | {
+        state: "pending";
+        expiresInMs: number;
+    } | {
+        state: "none";
+        reason: WebAuthorityRefusal;
+    };
+    /** #1939 §10: revoke every web authority given so far (receipts read as none), without signing anyone out. */
+    revokeWebAuthority(): {
+        epoch: number;
+        durable: boolean;
+    };
     /** #1269: an instance's chat command from the web chat (web-commands.ts); `publicLink`: a gateway request. */
     webCommand(input: {
         instance: string;
@@ -2380,6 +2786,7 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     }, opts: {
         publicLink: boolean;
         person?: Pick<WebPersonView, "userId" | "name">;
+        authority?: HumanAuthority;
     }): Promise<WebCommandResult>;
     /** Consume `/clear` Confirm/Cancel exactly once; only Confirm reaches IPC. */
     private handleClearConfirmation;
@@ -2744,6 +3151,8 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     private restoreWebChat;
     /** #1565: who an instance is, for its web chat file: its working directory, or its ClassicBot room; null if neither. */
     private webChatOwner;
+    /** The only Try-card publisher: no arbitrary SSE sender/role can manufacture this metadata. */
+    private publishEffectTrial;
     /** Push an SSE event to all connected Web UI clients. */
     emitSseEvent(event: string, data: unknown): void;
     listClaimedTasks(assignee: string): Array<{
@@ -2845,8 +3254,14 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     private pasteRawToClassicInstance;
     /** Resolve the backend name configured for an instance (fleet or classic). */
     private backendNameForInstance;
+    /**
+     * #2072: a catalog is the account's, so a credential profile has its own. Only claude-code's probe reads an account
+     * catalog through a profile's login (its `GET /v1/models` with the profile's token); other backends' probes read the
+     * process environment, so their catalog stays the backend's own.
+     */
+    private catalogProfile;
     private cliEnvPath;
-    /** Read the cached CLI env for a backend, or null if missing/stale/unparseable. */
+    /** Read the cached CLI env for a backend (a credential profile's own, when given), or null if missing/stale/unparseable. */
     private readCliEnv;
     /** Return cached CLI versions immediately. Refresh is started after /sysinfo is sent. */
     getBackendCliVersionSnapshot(): BackendCliVersionSnapshot;
@@ -2877,6 +3292,11 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     };
     /** Human-readable effective model, e.g. `auto (default)`. Used by /ctx. */
     modelDisplayForInstance(instanceName: string): string;
+    /**
+     * #2072: the model an instance runs is always among its choices — one its CLI's catalog does not list (an older
+     * name, a custom provider's, a typed one) is shown first, marked, so the menu never hides what is running.
+     */
+    private withCurrentModel;
     private modelChoiceLabel;
     /** Preserve the existing cache merge rules for worker probes. */
     private persistCliEnvProbeResult;
@@ -3050,8 +3470,31 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     private prospectiveCodexModel;
     /** #1811: whether a launch of `backend` here would pass a level: the same gate its builder applies. */
     private launchEffortGate;
-    /** Installed the way the launch finds a CLI (resolveBinary): on PATH or in a known install directory. */
-    private backendInstalledHere;
+    /**
+     * #2072: what this host can run, from the published availability snapshot (backend-availability.ts). Read only: a
+     * handler never starts a probe, not even in the background — launch, the timer, and /login install or sign-in do.
+     */
+    backendAvailabilityRows(): BackendAvailability[];
+    /**
+     * #2072 part 3: the models a Settings field offers for `backend` — the cached catalog (an instance's own credential
+     * profile's, when it is named and has one), claude's account catalog included. Read only: never a probe.
+     */
+    modelCatalogFor(backend: string, instance: string | null): import("./backend/types.js").ModelOption[];
+    /**
+     * #2072 (#2078 review): the snapshot as THIS instance would see it. Its sign-in on a backend is its own credential
+     * profile's when it has one there — the host's default login says nothing about it. A profile's login is a file check
+     * (credentialProfileLogin), no process.
+     */
+    backendAvailabilityFor(instanceName: string): BackendAvailability[];
+    /** The probes the snapshot runs (tests replace them: no CLI, no account, no network). */
+    availabilityProbes: AvailabilityProbes;
+    private availabilityStore;
+    private availabilityTimer;
+    get backendAvailability(): BackendAvailabilityStore;
+    /** A launch need not look the binary up again (a synchronous `which` on the loop) when the snapshot found it. */
+    private noteAvailabilityPaths;
+    /** Probe now and then every AVAILABILITY_STALE_MS; a pass that finds nothing changed starts no CLI. */
+    private startAvailabilityRefresh;
     /** The models `/model` would offer on a backend: the cached CLI env, else (live) a bounded probe. Never throws. */
     private backendModelOptions;
     /**
@@ -3096,6 +3539,7 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     private findClassicApprovalGeneral;
     /** Return a user-facing blocker without mutating ClassicBot state. */
     private validateClassicStart;
+    /** #2072: from the published snapshot (no `which` on the loop); not checked yet counts as installed (no false alarm). */
     private isBackendInstalled;
     private getMissingBackendWarning;
     /** Handle Discord's required static slash choice, warning before a likely startup failure. */
@@ -3391,6 +3835,56 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
      * Only the parsed host name is logged, never the raw header.
      */
     private noteRejectedHost;
+    /**
+     * #1920 §3: the instances a guest session may see — derived on every request from the account's chat access, never
+     * stored; nothing while `web.guests.enabled` is not true.
+     * - Its connection's fleet topics and General (what it may talk to in chat): when that connection's access lets the
+     *   account in (AccessManager.isAllowed — allowed_users or paired). An `open` connection lets everyone in, so it gives
+     *   only the instances an admin named for its guests (`web.guests.open_instances`; the user's decision: least
+     *   privilege, as an open group has no list of people).
+     * - A Telegram private ClassicBot room that is the account's own (its chat id is the user id).
+     * - A ClassicBot group or guild room on its connection: only while its membership is verified (§3.2 — a "member"
+     *   answer read in the background, at most 15 minutes old; unknown, failed or stale hides it).
+     * - Then an admin's narrowing (`web.guests.narrow`), which only takes away.
+     * A fleet admin is not a guest: an admin outside the connection's access gets nothing here (admins sign in as admins).
+     */
+    guestScope(owner: {
+        readonly adapterId: string;
+        readonly userId: string;
+    } | undefined): ReadonlySet<string>;
+    /**
+     * #1920 (#2104 review): what an account reaches before an admin's narrowing — its connection's topics (an open one's
+     * named agents), its own Telegram private room, its verified group rooms. Narrowing can only take from this set, so it
+     * is what Settings offers to narrow to. Empty while guest sign-in is off.
+     */
+    private guestReach;
+    /**
+     * #1920 §3.5: a guest session still admitted — current, with something in scope. A scope that became empty (guest
+     * sign-in off, the account removed from the connection's access, everything narrowed away) ends the session here,
+     * so the next request and the open stream find it gone.
+     */
+    private guestStillAdmitted;
+    /**
+     * The same, with a third answer (§3.2): "pending" — nothing in scope now, but a room's membership is not read yet
+     * (a restart, a room just created). The request is refused and the session kept; its read starts in the background.
+     */
+    private guestAdmission;
+    /** #1920 §3.2: the membership answers; the read goes to the room's own connection, never waits past its deadline. */
+    private guestRooms;
+    /** #1920 §3.2: read this guest's rooms that are due (GuestRoomMembership.refresh says when each mode reads). */
+    private refreshGuestRooms;
+    /** Every account with a live guest session, one after another (the guest caps bound them); one pass at a time. */
+    private refreshAllGuestRooms;
+    private guestRoomsPass;
+    /**
+     * #1920 §3.5: guest sign-in turned off ends every guest session — checked when the configuration is read or saved
+     * and when the sessions are opened, so turning it back on never revives one.
+     */
+    private enforceGuestSwitch;
+    /** #1920 §5.2: whether this instance is the account's own Telegram private ClassicBot room (its chat id is the user id). */
+    private guestOwnRoom;
+    /** A private room's chat id is its one user's id (a group's is negative, so never equal); Telegram only. */
+    private isOwnPrivateRoom;
     /** Shared handler dispatcher; gateway admission is enforced by its separate listener. */
     private dispatchWebHttp;
     private startHealthServer;
@@ -3412,6 +3906,7 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     previewForUi(hostHeader: string | undefined, secure: boolean): PreviewAvailability & {
         boot: string | null;
     };
+    private previewNotListening;
     /**
      * #1723: for one page of the public link (exposure `exposureId`, at `dashboardOrigin`): its own preview tunnel's
      * origin once up, "starting" until then, why it failed if it did — or a configured web.preview_origin, used instead.