@songsid/agend 2.1.12 → 2.2.0-alpha.1

package/dist/fleet-manager.d.ts

@@ -1,3 +1,5 @@
+import { SettingsExecution } from "./settings-transaction.js";
+import type { LoginCodeOwner } from "./web-login.js";
 import { type ProfileTicket } from "./runtime-cpu-profile.js";
 import type { CpuProfile } from "./cpu-profile.js";
 import { type FleetMemory } from "./process-memory.js";
@@ -49,6 +51,8 @@ export declare function applyTaskListCap<T extends {
     omitted: number;
     hint: string;
 } | T[];
+import { WebChatHistory } from "./web-chat-history.js";
+import { WebFileLedger } from "./web-upload.js";
 import { type RawConfigPatch } from "./settings-api.js";
 import { type AgentEndpointContext } from "./agent-endpoint.js";
 import { ClassicChannelManager } from "./classic-channel-manager.js";
@@ -57,6 +61,9 @@ import type { InstanceState, InteractionSnapshot } from "./backend/types.js";
 import { WakeCoordinator } from "./wake-coordinator.js";
 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 PreviewAvailability } from "./web-preview.js";
 import { type ConnectionMetadata, type ConnectionBinding, type BindingProbe, type SecretApplyJob, type ProviderSecretApplyJob } from "./connection-secrets.js";
 import { type ProviderSecretStatus } from "./provider-secret-registry.js";
 import { ApplyJobStore, type ApplyJob, type ApplyTargetKind, type SelfRestartResult } from "./apply-job.js";
@@ -119,6 +126,11 @@ export interface DeliveryOptions {
      * paused after its row was claimed is handed back instead of woken here.
      */
     noInlineWake?: boolean;
+    /**
+     * #1426: the caller's own fence, asked wherever the delivery epoch is — through the wake, the idle wait and up to the
+     * IPC hand-off itself. False drops the delivery unsent (a schedule retry past its deadline).
+     */
+    stillCurrent?: () => boolean;
 }
 export declare const LOGIN_CALLBACK_PREFIX = "login:";
 /**
@@ -271,6 +283,14 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     private instanceProgress;
     /** instanceName → tail of deliveries waiting for its IPC to come back. */
     private ipcWaitTails;
+    private webChannelEchoTails;
+    /**
+     * instanceName → the reservation whose echo callback is currently running.
+     * sendClassicWebEcho fences every per-entry copy against it: no new copy
+     * starts after the ordering budget is gone or the delivery epoch is revoked.
+     * Serialized per instance by the echo tail, so one slot is enough.
+     */
+    private webChannelEchoGuards;
     /** instanceName → restart currently executing; concurrent callers join it. */
     private restartsInFlight;
     /**
@@ -309,6 +329,20 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     private pendingModelSelects;
     /** nonce → pending button prompt (hang restart, interactive assist, clean-exit restart). */
     private pendingNonceButtons;
+    /** #1386 "Needs you": the list, its live chat messages and Acknowledge. Started with the fleet (finishStartup). */
+    private needsYou;
+    /** When the fleet first saw an instance crashed, for its "Needs you" age; cleared when it is not. */
+    private readonly needsCrashedAt;
+    /** Pause reason/time read from the marker, per paused instance; dropped on any attention change of it, and at most
+     *  NEEDS_PAUSE_TTL_MS old — so a recompute does not re-read the file every time (#1386 §4.3). */
+    private readonly needsPauseCache;
+    /**
+     * Clicks that came from the web dashboard (clickWebPrompt). Only that method adds to it, so nothing an
+     * adapter emits — whatever fields its payload carries — can claim a dashboard click's authority.
+     */
+    private readonly webPromptClicks;
+    /** The web clicks consumeNonceCallback actually claimed (the others were refused or lost a race). */
+    private readonly webPromptClaims;
     private failoverActive;
     /** instance → when a click with no live button entry last fired a cancel. */
     private staleCancelClickAt;
@@ -357,6 +391,12 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     private connectionBindingInFlight;
     private collabInstances;
     private healthServer;
+    /** #1306: the preview listener (health_port + 1 by default), and whether it is listening. */
+    private previewListener;
+    private previewListening;
+    /** The ports the preview listener was started for, and the inputs it was built from (a reload compares them). */
+    private previewPorts;
+    private previewInputs;
     private healthPortRetried;
     private updateCheckTimer;
     private updateProgressTimer;
@@ -387,12 +427,36 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     private mirrorBuffer;
     private mirrorTimer;
     private sseClients;
+    /** The web chat's recent messages: what `/ui/history` serves and what a reconnecting SSE stream is sent. */
+    readonly webChatHistory: WebChatHistory;
+    /** Uploaded files and the files the dashboard may fetch back (uploads, reply attachments). */
+    readonly webFiles: WebFileLedger;
     /**
      * Read from disk on every access rather than cached at startup: `agend
      * web-token rotate` runs in a separate process, and a cached copy would keep
      * authorizing revoked links and cookies until the fleet restarted.
      */
+    private settingsGeneration;
+    private settingsRuntimeRevision;
+    private settingsConfirmation;
+    private settingsControl;
+    private settingsJobSettlements;
+    private classicSettingsOwners;
+    private queueSettingsOperation;
+    private settingsGate;
+    private promptSettingsChange;
+    private handleSettingsChangeCallback;
+    startSettingsConfirmationControl(): Promise<void>;
     private get webToken();
+    /**
+     * Server-side web sessions (see web-session.ts). Created with the token, not per
+     * request: they are persisted, and a restart must find them again.
+     */
+    private webSessions;
+    /** Heartbeat of the dashboard's SSE stream; public so a test can shorten it. */
+    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;
     /**
      * 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
@@ -410,7 +474,6 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     /** Set when the file on disk and the in-memory config disagree on a
      * startup-only key at startup. See checkStartupSignatureConsistency(). */
     private fleetSignatureMismatch;
-    private viewToken;
     private healthServerListening;
     constructor(dataDir: string);
     private ensureDeliveryOutbox;
@@ -694,11 +757,51 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     private sendWhenConnected;
     /** Poll for the instance's IPC to come back, then send. Throws if it does not. */
     private sendAfterIpcReturns;
+    /**
+     * Reserve the display echo before IPC handoff: a fast reply cannot overtake
+     * it. The web request settles admission without awaiting the platform POST.
+     * Only accepted messages send an echo; failures release replies normally.
+     * Each reservation has a 5s total monotonic ordering budget (queue/admission
+     * included). Expiry drops unstarted copies and releases replies. An adapter
+     * request already in flight may land late, but cannot retain the ordering lane.
+     */
+    /**
+     * Post an owner web-chat echo to every ClassicBot channel entry opted in
+     * 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.
+     *
+     * 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
+     * primary adapter); when running under a reservation, an exhausted
+     * ordering budget or a revoked delivery epoch stops the loop, and each
+     * entry is re-resolved against current registration so a removed opt-in
+     * or a rebound adapter is never posted through a stale route. A copy
+     * already in flight may still land late — the contract permits that.
+     */
+    sendClassicWebEcho(instance: string, text: string): Promise<number>;
+    reserveWebChannelEcho(instanceName: string, sendEcho: () => Promise<unknown>): (accepted: boolean) => void;
     /** Whether this target already has an ordinary non-user delivery in its FIFO. */
     hasPendingIdleGatedDelivery(instanceName: string): boolean;
+    /** The running launch's own steer capability (#1405); undefined for a backend without one, or no running Daemon. */
+    instanceLaunchSupportsSteer(instanceName: string): boolean | undefined;
     /** Single delivery facade: wake paused CLIs and serialize non-user work behind idle. */
     deliverToInstance(instanceName: string, payload: Record<string, unknown>, options?: DeliveryOptions): Promise<boolean | void>;
-    /** Fleet admin is an explicit config allowlist entry, not merely an open/paired user. */
+    /**
+     * The fleet-admin list of exactly this adapter (#754): its `access.allowed_users`, read from fleet.yaml. An adapter
+     * id that matches no configured channel and no running adapter has NO list — it is never answered with the primary
+     * channel's, as `getChannelConfig` would. No id at all means the primary adapter, a single-adapter fleet's only one.
+     */
+    private adminListOf;
+    /**
+     * The one fleet-admin gate (#754): is this user an admin of the adapter that OWNS what they are acting on — the
+     * target instance's or General's adapter, never merely the one the request arrived on. An empty list means nobody
+     * (`disabled`, so the reply can say admin commands are off); an unknown adapter means nobody either (`denied`).
+     * Fleet admin is an explicit config entry: a paired or open-mode user is not one.
+     */
+    adminGate(userId: string, ownerAdapterId?: string): "ok" | "disabled" | "denied";
+    /** Fleet admin is an explicit config allowlist entry, not merely an open/paired user. See adminGate. */
     isFleetAdmin(userId: string, adapterId?: string): boolean;
     /** Whether this adapter has any fleet admin at all (an empty allowlist means the admin commands are off). */
     hasFleetAdmins(adapterId?: string): boolean;
@@ -724,13 +827,16 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
      * this caller speak here at all) and then the COMMAND TABLE (src/command-table.ts — does this command apply
      * in this kind of channel, and which kind of admin does it need). The table can only narrow what the door
      * let through. A command nobody registered is answered, not left to time out.
+     *
+     * The door, the table and the start of the command run in one synchronous stretch (#1399 review): no await between
+     * the check and the act, so the channel's instance cannot be rebound to another bot in between.
      */
     private dispatchSlash;
     /**
-     * The door every Discord slash command goes through (src/slash-authz.ts has the rule and the reasoning).
-     * Answers the caller itself when it refuses, so a refused command costs one reply and does nothing else.
+     * The door every Discord slash command goes through (src/slash-authz.ts has the rule and the reasoning): the scope
+     * it lets the command into, or the reply that refuses it. Synchronous, so the dispatch acts on what it judged.
      */
-    private authorizeSlash;
+    private slashDoor;
     /** Phase 2: delivery_worker for a target (instance override → fleet default → wake_only). */
     deliveryWorkerMode(target: string): ReturnType<typeof resolveDeliveryWorkerMode>;
     /** Active instances mid-restart: they keep their warm slot through the stop → replacement gap. */
@@ -769,8 +875,11 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     /** Deliver an already-resolved hot snapshot without depending on IPC timing. */
     private applyHotConfigUpdate;
     private classicBehaviorUpdate;
+    /** Compensation retains this transaction's exact instance owner across its own transitions. */
+    captureClassicSettingsRestoration(instanceName: string, changedFields: string[], execution?: SettingsExecution): () => Promise<void>;
     /** Apply a Settings edit to a ClassicBot channel without waiting for the poller. */
-    restartClassicInstanceFromSettings(instanceName: string, changedFields?: string[]): Promise<void>;
+    restartClassicInstanceFromSettings(instanceName: string, changedFields?: string[], execution?: SettingsExecution): Promise<void>;
+    private restartClassicSettingsOwned;
     /** Reload classicBot.yaml once. Kept callable so the periodic production
      * path is covered without relying on fake timers around startAll(). */
     private reloadClassicConfigFromDisk;
@@ -782,7 +891,7 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
      */
     resumePaused?: boolean, 
     /** Phase 2a: the caller's transition, for a start made from inside a restart or wake. */
-    transition?: TransitionHandle): Promise<void>;
+    transition?: TransitionHandle, execution?: SettingsExecution): Promise<void>;
     /** Recreate a daemon for a marker-only paused instance after an explicit wake/delivery. */
     startPersistedPausedInstance(name: string, transition?: TransitionHandle): Promise<void>;
     /**
@@ -932,6 +1041,50 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     private loadEnvFile;
     /** Initialize auth before any adapter can answer /dashboard. */
     private initializeWebAuthTokens;
+    private initializeWebSessions;
+    /**
+     * A single-use login code for the dashboard, for a channel only the operator
+     * can read (`/dashboard`). Null while the panel is closed (no web.token).
+     */
+    issueDashboardLogin(): {
+        display: string;
+        expiresAt: number;
+        ttlMinutes: number;
+    } | null;
+    private tunnelPurposeLane;
+    private publicWebLink;
+    private getTunnelLane;
+    private publicOwnerCurrent;
+    /** Exact owning General. No primary-adapter or name fallback participates in authorization. */
+    private dashboardOwner;
+    private getPublicWebLink;
+    getPublicWebStatus(): {
+        state: string;
+        expiresAt?: number;
+        remainingSeconds?: number;
+    };
+    confirmPublicWebLogin(info: {
+        label: string;
+        handle: string;
+        owner: LoginCodeOwner;
+    }, current: () => boolean): Promise<void>;
+    /** Telegram's typed command enters through the same strict owner and nonce path as Discord. */
+    dashboardMenu(msg: InboundMessage): Promise<void>;
+    private sendLocalDashboard;
+    private showDashboardMenu;
+    private handleDashboardCallback;
+    /** `/dashboard revoke`: sign out every browser and withdraw any unused code. */
+    revokeWebSessions(): {
+        count: number;
+        durable: boolean;
+    };
+    /** 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;
+    }): void;
     getDashboardAccess(): {
         ready: boolean;
         token: string | null;
@@ -964,6 +1117,11 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
      * mirroring classic chat-log rotation (same 7-day retention).
      */
     private rotateInboxes;
+    /**
+     * Web uploads no message took before a restart (#1273): removed once older than the upload window. Younger ones
+     * are looked at again when the first comes due (an unref'd timer, so it never holds the process).
+     */
+    private sweepOrphanedWebUploads;
     /** Start the shared channel adapter(s) for topic mode */
     private startSharedAdapter;
     /** Exponential backoff retry for a single failed adapter (background, non-blocking). */
@@ -1019,6 +1177,7 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     };
     /** Start the primary adapter (backward-compatible, sets this.adapter) */
     private startSingleAdapter;
+    private startSingleAdapterOwned;
     /**
      * Register a Telegram connection's command menus; any other kind of channel has none to register. Started, not
      * awaited: a slow api.telegram.org must never hold up the adapter's login (each call has its own timeout). Never fatal.
@@ -1026,12 +1185,14 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     private registerTelegramCommandsFor;
     /** Start an additional (non-primary) adapter */
     private startAdditionalAdapter;
+    private startAdditionalAdapterOwned;
     /** Connect IPC to a single instance with all handlers */
     connectIpcToInstance(name: string): Promise<void>;
     private connectIpcToInstanceInternal;
     /** Attempt IPC reconnection with exponential backoff */
     private ipcReconnect;
     private runIpcReconnect;
+    private disposeSettingsAdapter;
     /** Restart a channel adapter after fatal error with infinite retry + 60s cap */
     private restartAdapter;
     /** Handle inbound message — transcribe voice if present, then route */
@@ -1126,8 +1287,10 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     /**
      * #1346: whether this copy may claim the shared dedup key for
      * command-like text. Fleet topics resolve an owning adapter and only its
-     * copy proceeds; anything else (classic targets, unknown routing, no
-     * identity) passes through to the existing handling.
+     * copy proceeds. Classic targets and unknown routing keep their existing
+     * handling. At the receiving Telegram world's own forum root, an explicit
+     * suffix requires a known matching username before dedup; present-thread
+     * copies retain their permissive handling when that identity is unknown.
      */
     private isOwnerCommandCopy;
     private resolveInboundTarget;
@@ -1158,10 +1321,21 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
      * their fleet is organised. Both stay theirs — this only makes sure they are
      * not discovered by an agent failing at three in the morning.
      */
+    /**
+     * #1366: the first time a fleet runs 2.2 or later, tell each chat platform's General — once — that its agents can
+     * now be talked to from a browser. Claimed in upgrade-notices.json before the send, released if the send fails.
+     * Platforms with nowhere to post fleet notices (no group, or a Discord fleet with no General channel) are skipped
+     * and not recorded, so they are told once they have one.
+     */
+    announceWebChatOnce(version: string): Promise<void>;
     private announceToolPermissionsChange;
     private checkToolPermission;
     private handleOutboundFromInstance;
     /** Side effects of a routed reply: cancel-button lifecycle, logs, SSE, chat log. */
+    /** No chat platform is configured at all: the web dashboard is the fleet's only surface. */
+    private isWebOnlyFleet;
+    /** On a fleet with no chat platform, the dashboard is where an instance-health prompt is posted (#1307 item 6). */
+    private webOnlyPromptPlace;
     private afterReplyRouted;
     private handleScheduleTrigger;
     /**
@@ -1195,6 +1369,12 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     private scheduleSourceAdapter;
     private notifySourceTopic;
     private notifyScheduleFailure;
+    /**
+     * #1426: a deferred occurrence's retry will not run — superseded by the next occurrence, deferred again, or its wait
+     * capped. Recorded as `deferred → skipped (…)`, and said in the schedule's own chat with its admins @mentioned:
+     * this is the case that used to be a silently lost day.
+     */
+    private scheduleRetryDropped;
     /**
      * The typed IPC messages, all through one door.
      *
@@ -1320,7 +1500,9 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     private slimFleetConfigAtStartup;
     private writeFleetConfigBackup;
     private patchFleetDocument;
-    removeInstance(name: string, authorization: ExplicitInstanceRemoval): Promise<void>;
+    getSettingsConfigPath(): string;
+    removeInstance(name: string, authorization: ExplicitInstanceRemoval, execution?: SettingsExecution): Promise<void>;
+    private removeInstanceOwned;
     startStatuslineWatcher(name: string): void;
     stopStatuslineWatcher(name: string): void;
     /**
@@ -1480,6 +1662,8 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
      */
     private savedAttachmentReactionFor;
     reactMessageStatus(instanceName: string, chatId: string, messageId: string, status: DeliveryStatus, threadId?: string, receivedAt?: number): void;
+    /** One delivery report for a web user's message: recorded with it, and sent to the pages when it moved. */
+    private reportWebDelivery;
     /**
      * Apply a terminal delivery verdict. On Telegram the built-in delivered is
      * 👀 and failed is 👎; Discord shows ✅/❌ — both configurable (#1005).
@@ -1660,6 +1844,60 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     private handleRetiredPromptButton;
     /** Routes a click to the handler that owns its prefix; false when none does. */
     private dispatchAdapterCallback;
+    /**
+     * A prompt the dashboard was offered is no longer open (answered on either surface, expired, or its
+     * instance stopped): every page drops its buttons, and shows `outcome` when there is one.
+     */
+    private webPromptGone;
+    /** The interaction wait an instance is in now, as a comparable key: which daemon/spawn owns it, and its episode. */
+    private interactionWaitKey;
+    /** An instance's interaction observation, pause or wake changed (relayed by the lifecycle): recompute now, not at the tick. */
+    onAttentionChanged(name: string): void;
+    /** The list for the web: every world's items, and those of instances with no world (#1386 §5.0). */
+    needsYouItems(): WebNeedsItem[];
+    /**
+     * #1389: the org chart's structure for the web — the instances the dashboard lists (getUiStatus's names), General,
+     * fleet.yaml's teams, each instance's description and thread link. Read on demand; the live state rides the stream.
+     */
+    orgChart(): OrgChart;
+    /** 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;
+        message: string;
+    };
+    private needsYouInstances;
+    private needsYouPrompts;
+    /**
+     * Shutdown: detach the hub first — nothing reaches it from here on, and the next startAll (finishStartup) builds a
+     * fresh one; the old one's late ACKs are fenced by its own stop (#1398 review) — then let it retire its live
+     * messages, bounded so a platform that does not answer cannot hold the shutdown.
+     */
+    private stopNeedsYou;
+    private startNeedsYou;
+    /** The prompts open on the dashboard right now (a page that loads after one was posted asks for them). */
+    listWebPrompts(): Array<{
+        instance: string;
+        nonce: string;
+        text: string;
+        actions: Array<{
+            id: string;
+            label: string;
+        }>;
+        expiresAt: number;
+    }>;
+    /**
+     * A click on a prompt in the web dashboard (web track C4). It is the platform click, made by the
+     * dashboard: the same handler, the same single claim (whoever answers first — here or on Telegram —
+     * wins), and the platform's buttons collapse to the outcome exactly as for a click there.
+     *
+     * The caller has passed the /ui gate (session, same origin, CSRF). Here: the prompt must be one offered
+     * on the dashboard, about the instance the page named, and the action one of its own buttons.
+     */
+    clickWebPrompt(instance: string, nonce: string, action: string): Promise<{
+        status: 200 | 400 | 403 | 409;
+        error?: string;
+        outcome?: string;
+    }>;
     private retireNonceButtons;
     private tipsEnabled;
     private readTipState;
@@ -1753,6 +1991,13 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
      * instance that has already started a new turn.
      */
     private handleCancelClick;
+    /** Where an instance's cancel button is posted — and so the only place a click on it can come from. */
+    private cancelButtonDestination;
+    /**
+     * A click came from this destination. A Discord click names the guild as its chat and the channel as its thread; a
+     * Telegram click names the chat and topic, with the General topic as thread 1 or none at all.
+     */
+    private clickAtDestination;
     private hasCancelButton;
     private beginCancelButtonPublication;
     /** Remember a clear/cancel/idle decision that arrived before notifyAlert
@@ -1877,6 +2122,8 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     cancelInstance(instanceName: string): boolean;
     getDeliveryEpoch(instanceName: string): number;
     private isDeliveryEpochCurrent;
+    /** The delivery epoch, and the caller's own fence when it gave one (DeliveryOptions.stillCurrent, #1426). */
+    private deliveryCurrent;
     /** Invalidate work queued before a user cancel and wake idle-gate waiters. */
     private cancelPendingDeliveries;
     /** Web-terminal login: the only sign-in path (the chat-relay mode was removed, #1139). */
@@ -1927,6 +2174,7 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
      * happened to be paused. General is still told the outcome.
      */
     private applyClassicApproval;
+    private notifyClassicRequester;
     /** Consume a ClassicBot approval button. */
     private handleClassicApproval;
     /**
@@ -2195,7 +2443,7 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     /** `/effort` — DC Select Menu, or apply directly when a level is given. */
     private handleEffortSlash;
     /** TG inline-keyboard effort menu. Returns null on success, else a fallback string. */
-    promptEffortMenu(instanceName: string, userId: string, channelId: string, adapter: ChannelAdapter, chatId: string, threadId?: string): Promise<string | null>;
+    promptEffortMenu(instanceName: string, userId: string, channelId: string, adapter: ChannelAdapter, chatId: string, threadId?: string, adapterId?: string): Promise<string | null>;
     /** Consume an `/effort` selection callback. Mirrors handleModelSelection. */
     private handleEffortSelection;
     private handleModelSlash;
@@ -2204,7 +2452,7 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
      * pendingModelSelects coordinator as the DC Select Menu path.
      * Returns null on success (menu shown), or a fallback string to send.
      */
-    promptModelMenu(instanceName: string, userId: string, channelId: string, adapter: ChannelAdapter, chatId: string, threadId?: string): Promise<string | null>;
+    promptModelMenu(instanceName: string, userId: string, channelId: string, adapter: ChannelAdapter, chatId: string, threadId?: string, adapterId?: string): Promise<string | null>;
     /** Cached-or-live account catalog behind "/model → more models" (claude). */
     private claudeApiModelOptions;
     /** Replace a consumed "/model" menu with the full account catalog tier. */
@@ -2221,6 +2469,14 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
      * menu, because a picker with no rows cannot even offer another refresh.
      */
     private refreshModelMenu;
+    /**
+     * A /model or /effort menu click may still act (#1396 review): the instance is still owned by the adapter the click
+     * came through (it may have been rebound since the menu opened) and the clicker is still that channel's admin. Asked
+     * when the click is claimed and again right before the change is applied.
+     */
+    private menuClickStillCurrent;
+    /** Current source-to-target mapping, including same-adapter topic moves. */
+    private commandChannelStillTargets;
     /** Consume a `/model` selection callback. Returns true for all model-select ids (incl. stale). */
     private handleModelSelection;
     /** Apply a model to an instance: runtime paste (claude-code) or persist + restart (others). */
@@ -2268,6 +2524,8 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
      * you @mention the bot; on Discord, @mention or `/chat`. The chat's platform is the adapter it came through.
      */
     private classicStartKey;
+    /** Approval is a system notification: General's agent need not be running. */
+    private findClassicApprovalGeneral;
     /** Return a user-facing blocker without mutating ClassicBot state. */
     private validateClassicStart;
     private isBackendInstalled;
@@ -2407,6 +2665,7 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
         verificationId: string;
         sessionBinding: string;
         idempotencyKey: string;
+        execution?: SettingsExecution;
     }): {
         job: ProviderSecretApplyJob;
         reused: boolean;
@@ -2450,6 +2709,7 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
         verificationId: string;
         sessionBinding: string;
         idempotencyKey: string;
+        execution?: SettingsExecution;
     }): {
         job: SecretApplyJob;
         reused: boolean;
@@ -2484,6 +2744,7 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
         verificationId: string;
         sessionBinding: string;
         idempotencyKey: string;
+        execution?: SettingsExecution;
     }): {
         job: SecretApplyJob;
         reused: boolean;
@@ -2539,7 +2800,27 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
      * Only the parsed host name is logged, never the raw header.
      */
     private noteRejectedHost;
+    /** Shared handler dispatcher; gateway admission is enforced by its separate listener. */
+    private dispatchWebHttp;
     private startHealthServer;
+    /**
+     * #1306: the preview listener, beside the web listener and closed with it. When it cannot listen (the port is
+     * taken, web.preview: false), cards show Source and Download only; nothing else changes.
+     */
+    private startPreviewListener;
+    /** What a reload may change hot: web.preview, and the dashboard names (the shim's allow-list and frame-ancestors). */
+    private previewInputsSignature;
+    /**
+     * After a config reload: web.preview true→false stops the listener at once (/ui then offers no origin, boot or
+     * frame-src), false→true starts it, and a change of dashboard names rebuilds it (a new boot id). preview_port and
+     * preview_origin are not adopted here: they are startup-only, and the reload reports "restart required".
+     */
+    private reconcilePreviewListener;
+    private stopPreviewListener;
+    /** For one /ui load: the preview origin it may frame, and the listener's boot id (see web-preview.ts). */
+    previewForUi(hostHeader: string | undefined, secure: boolean): PreviewAvailability & {
+        boot: string | null;
+    };
     getUiStatus(): unknown;
     private getUiStatusSync;
 }