@songsid/agend 2.1.4-beta.6 → 2.1.4-beta.60

package/dist/fleet-manager.d.ts

@@ -6,7 +6,7 @@ import { EventLog } from "./event-log.js";
 import { AdapterWorld } from "./adapter-world.js";
 import { CostGuard } from "./cost-guard.js";
 import { IpcClient } from "./channel/ipc-bridge.js";
-import type { ChannelAdapter } from "./channel/types.js";
+import type { AdapterHealthSnapshot, ChannelAdapter } from "./channel/types.js";
 import { type Logger } from "./logger.js";
 import { Scheduler } from "./scheduler/index.js";
 import type { FleetContext } from "./fleet-context.js";
@@ -20,6 +20,9 @@ import { type RawConfigPatch } from "./settings-api.js";
 import { type AgentEndpointContext } from "./agent-endpoint.js";
 import { ClassicChannelManager } from "./classic-channel-manager.js";
 import type { InstanceState } from "./backend/types.js";
+import { StormWindow } from "./storm-window.js";
+import { SpawnGate } from "./spawn-gate.js";
+import { BackendOutageTracker } from "./backend-outage.js";
 export declare function resolveReplyThreadId(argsThreadId: unknown, instanceConfig?: InstanceConfig): string | undefined;
 /**
  * Pure warm-cap victim selection (extracted for testability). Given the current
@@ -36,6 +39,25 @@ export declare function selectLruEvictions(warm: string[], cap: number, opts: {
     isIdle: (name: string) => boolean;
     lastInboundAt: (name: string) => number;
 }): string[];
+/**
+ * Answer shape for `list_models`. `scope` reports where the LIST came from —
+ * "instance" only when it was read through that instance's own backend config,
+ * "global" for the account/CLI catalog — so a caller can tell an authoritative
+ * per-instance list from a best-effort account-wide one.
+ */
+export interface ModelCatalog {
+    backend: string;
+    scope: "instance" | "global";
+    /** Set whenever an instance was asked about, even if the list is global. */
+    instance?: string;
+    current_model: string | null;
+    models: import("./backend/types.js").ModelOption[];
+    /** "cache" = startup probe cache, "live" = probed now, "fallback" = none available. */
+    source: "cache" | "live" | "fallback";
+    probed_at?: string;
+    /** Caveat the caller should read before trusting the list. */
+    note?: string;
+}
 export interface DeliveryOptions {
     /** Explicitly identify agent-to-agent delivery when metadata is unavailable. */
     isCrossInstance?: boolean;
@@ -50,6 +72,10 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     private static sighupHandlerInstalled;
     private children;
     readonly lifecycle: InstanceLifecycle;
+    readonly stormWindow: StormWindow;
+    readonly spawnGate: SpawnGate;
+    /** Fleet-level backend reachability memory (fed by pty_error / startup panes). */
+    readonly backendOutage: BackendOutageTracker;
     /** Live view of lifecycle.daemons — used throughout; not deprecated. */
     get daemons(): Map<string, import("./daemon.js").Daemon>;
     fleetConfig: FleetConfig | null;
@@ -83,6 +109,7 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     costGuard: CostGuard | null;
     private statuslineWatcher;
     private dailySummary;
+    private dailyTipScheduler;
     private webhookEmitter;
     private topicIcons;
     private lastActivity;
@@ -94,6 +121,13 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     private warmCapEvicting;
     /** Per-instance tail keeps cross-instance and scheduled deliveries FIFO. */
     private idleGatedDeliveryTails;
+    /**
+     * Per-instance cancellation epoch for deliveries which have not reached the
+     * daemon yet. A cancel advances the epoch; queued work captures the old value
+     * and becomes a no-op, while messages arriving after the click capture the new
+     * value and remain deliverable.
+     */
+    private deliveryEpochs;
     /** Non-user work must observe a fresh idle snapshot after the latest delivery. */
     private lastDeliveryAt;
     /** State-cache updates wake event-driven idle waiters without busy polling. */
@@ -106,10 +140,34 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     readonly replyDeduper: ReplyDeduper;
     /** instanceName → what it is doing right now, when the backend can tell us. */
     private instanceActivity;
+    /** instanceName → this turn's tool list (multi-line), for the bubble. */
+    private instanceProgress;
     /** instanceName → tail of deliveries waiting for its IPC to come back. */
     private ipcWaitTails;
     /** instanceName → restart currently executing; concurrent callers join it. */
     private restartsInFlight;
+    /**
+     * Delayed automatic retries for instances whose startup failed. Before this a
+     * failed start was logged once and the instance stayed `stopped` until an
+     * operator noticed (2026-09-03: 4 kiro instances, all victims of the same
+     * backend outage during a post-update herd). instanceName → pending retry.
+     */
+    private startupRetries;
+    /** Bumped by every explicit stop (incl. the stop half of a restart); fences the outage hand-off. */
+    private explicitStopGeneration;
+    /** instanceName → outage hand-off currently executing; a repeat joins it. */
+    private handOffsInFlight;
+    /** instanceName → explicit stop currently executing; the outage hand-off waits for it. */
+    private stopsInFlight;
+    /** Aggregation window for the "N instances failed to start" notice. */
+    private startupRetryNotices;
+    /** Backoff between automatic startup retries; the last step repeats while the backend is down. */
+    static readonly STARTUP_RETRY_BACKOFF_MS: number[];
+    /** Hard cap on automatic startup retries (3 backoff steps + up to 3 more during a backend outage). */
+    static readonly STARTUP_RETRY_MAX_ATTEMPTS = 6;
+    /** Re-check interval when a retry is due but the tmux storm window still blocks spawns. */
+    static readonly STARTUP_RETRY_STORM_DEFER_MS = 60000;
+    static readonly STARTUP_RETRY_NOTICE_AGGREGATE_MS = 1000;
     private lastInboundMsg;
     private topicArchiver;
     controlClient: TmuxControlClient | null;
@@ -140,12 +198,14 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     private updateProgressTimer;
     private updateProgressEditRunning;
     private lastUpdateProgressText;
+    private updateCompletionTipText;
     private eventLogPruneTimer;
     private logRotateTimer;
     /** Days of event/activity history to keep. */
     private static readonly EVENT_LOG_RETENTION_DAYS;
     private watchdogTimer;
     private startedAt;
+    private stormOpenNotifyTimer;
     private mirrorBuffer;
     private mirrorTimer;
     private sseClients;
@@ -153,6 +213,11 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     private viewToken;
     private healthServerListening;
     constructor(dataDir: string);
+    private spawnConcurrency;
+    /** Wire the one fleet-wide storm into notification and recovery surfaces. */
+    private bindStormWindowEvents;
+    private formatStormDelay;
+    stormSuppressed(kind: string): boolean;
     private handleSighup;
     private scheduleReconcile;
     /**
@@ -222,6 +287,7 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     private isModelAdmin;
     private handlePauseWakeSlash;
     private handleUpdateSlash;
+    private handleTipsSlash;
     /** Admin-only full conversation reset for fleet-topic and Classic instances. */
     private handleClearSlash;
     /** Get the adapter bound to an instance, falling back to primary adapter */
@@ -252,6 +318,14 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     bindInstanceAdapter(name: string, adapterId: string, fromInbound?: boolean): void;
     getInstanceStatus(name: string): "running" | "paused" | "stopped" | "crashed";
     getInstanceExecutionState(name: string): InstanceState | null;
+    /**
+     * Subscription providers currently relevant to this fleet. Stopped/crashed
+     * rows do not keep a usage card alive, while persisted paused instances do.
+     * Classic channels use their effective backend merge chain, not the raw row.
+     */
+    getActiveUsageProviderIds(): ReadonlySet<string>;
+    /** Effective backends with a running or persisted-paused fleet/Classic instance. */
+    getActiveBackendIds(): ReadonlySet<string>;
     isClassicInstance(name: string): boolean;
     private cacheInstanceExecutionState;
     private cancelIdleButtonRetirement;
@@ -268,7 +342,15 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
      */
     private enforceWarmCap;
     private waitForInstanceIdle;
+    /**
+     * Ask the daemon to capture the pane before answering, then wait for any state
+     * report produced after this request. The ordinary query is intentionally
+     * cache-only (idle gates call it frequently); this opt-in refresh is reserved
+     * for lifecycle decisions where a stale state would strand UI.
+     */
+    private refreshInstanceExecutionState;
     private deliverWithIdleGate;
+    private holdDeliveryForStorm;
     /**
      * Hand a payload to an instance's IPC, waiting out a *transient* disconnect.
      *
@@ -288,6 +370,8 @@ 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;
+    /** Whether this target already has an ordinary non-user delivery in its FIFO. */
+    hasPendingIdleGatedDelivery(instanceName: string): boolean;
     /** Single delivery facade: wake paused CLIs and serialize non-user work behind idle. */
     deliverToInstance(instanceName: string, payload: Record<string, unknown>, options?: DeliveryOptions): Promise<void>;
     /** Fleet admin is an explicit config allowlist entry, not merely an open/paired user. */
@@ -311,6 +395,65 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
      * TODO: per-instance startup timeout (existing issue, not introduced here)
      */
     private startInstancesWithConcurrency;
+    /**
+     * Start from an UNATTENDED path (fleet startup, full restart, config
+     * reconcile): nobody is watching the result, so a failure is logged and
+     * handed to the delayed automatic retry instead of leaving the instance
+     * `stopped` forever. Explicit operator/API starts call startInstance directly
+     * and keep their synchronous error. Returns whether the instance is up.
+     */
+    private startInstanceUnattended;
+    /**
+     * Schedule attempt `attempt` (0-based) of the automatic startup retry for an
+     * instance whose start just failed. Backoff 1 → 5 → 15 min; while the
+     * instance's backend is known to be unreachable the 15-min step repeats up to
+     * STARTUP_RETRY_MAX_ATTEMPTS, after which we give up with one notice. Each
+     * retry re-checks the world (still configured, not running, not paused, no
+     * tmux storm) and runs through the SpawnGate as "recovery" — so a herd of
+     * failed instances comes back at the gate's concurrency, never all at once.
+     */
+    scheduleStartupRetry(name: string, attempt: number): void;
+    /** Drop a pending automatic retry (an operator start/stop/restart supersedes it). */
+    cancelStartupRetry(name: string): void;
+    /** Pending automatic retry, if any (status display / tests). */
+    pendingStartupRetry(name: string): {
+        attempt: number;
+    } | null;
+    /**
+     * A daemon's crash-respawn hit the backend outage (startup_backend_unreachable):
+     * stop THAT daemon and schedule the delayed retry. Serialized against the
+     * operator paths: an in-flight restart is awaited first (it replaces the
+     * daemon itself), the stop is identity-checked so a fresh daemon registered
+     * meanwhile is never deleted, and an explicit stop/restart that began during
+     * the hand-off (generation bump) owns the outcome — no retry is scheduled
+     * behind an operator's back.
+     */
+    handOffToStartupRetry(name: string, daemon: unknown): Promise<void>;
+    private runStartupRetry;
+    /** Fleet-topic (fleet.yaml) or ClassicBot (classic channel) — both are retryable; anything else is gone. */
+    private isConfiguredInstance;
+    /**
+     * Kind-aware start for the automatic retry: fleet-topic instances come from
+     * fleet.yaml, ClassicBot instances exist only in the classic channel manager
+     * and must be rebuilt through startClassicInstance (a fleet.yaml lookup alone
+     * silently dropped them — the retry timer fired and nothing happened).
+     */
+    private startConfiguredInstance;
+    /**
+     * Unattended ClassicBot start (fleet startup batch, full-restart batch, the
+     * classicBot.yaml reconcile): same contract as startInstanceUnattended —
+     * failures are logged and handed to the delayed automatic retry, whose
+     * kind-aware startConfiguredInstance rebuilds the Classic instance. Returns
+     * whether the instance is up.
+     */
+    private startClassicInstanceUnattended;
+    private backendNameOf;
+    /**
+     * One fleet-level notice per burst, not one per instance: a post-update herd
+     * fails many instances within the same second. Two notices per incident at
+     * most — "N failed, retrying in X" and, if it comes to that, "gave up on N".
+     */
+    private queueStartupRetryNotice;
     private runnableStartupCount;
     private configuredStartupInstanceNames;
     private restartProgressTarget;
@@ -362,6 +505,7 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
         retryCount: number;
         lastError?: string;
     }>;
+    private bindAdapterHealth;
     /**
      * Real, checkable fleet health for `/health` and the operator.
      *
@@ -390,6 +534,7 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
             total: number;
             connected: number;
             states: Record<string, string>;
+            details: Record<string, AdapterHealthSnapshot>;
         };
         startupComplete: boolean;
         /** See process-memory.ts: the fleet process and the whole service cgroup are
@@ -429,6 +574,11 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
      * message actually went out — a failed delivery keeps them queued.
      */
     private pendingReactionsMeta;
+    /**
+     * Why this adapter must ignore a bot/webhook message, or null to accept it.
+     * Pure: callers rely on being able to ask before claiming the dedup key.
+     */
+    private botMessageDropReason;
     private handleInboundMessage;
     /** Handle outbound tool calls from a daemon instance */
     /** Warn (but don't block) when rate limits are high. 30-min debounce per instance. */
@@ -445,6 +595,10 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     private handleDecisionCrud;
     /** Resolve display name for an instance, fallback to instance name. */
     resolveDisplayName(instanceName: string): string;
+    /** Persist identity to the instance's actual config store. Classic instances
+     * are registry rows in classicBot.yaml, not fleet.yaml instance entries. */
+    private setInstanceDisplayName;
+    private setInstanceDescription;
     private handleSetDisplayName;
     private handleSetDescription;
     handleScheduleCrudHttp(instance: string, op: string, args: Record<string, unknown>): Promise<unknown>;
@@ -465,9 +619,13 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     private startTopicCleanupPoller;
     /**
      * Patch only values changed in the effective config into the original YAML
-     * document. Unknown keys, explicit overrides and comments remain untouched.
+     * document. Unknown keys and comments remain untouched; redundant
+     * non-identity instance leaves are canonicalized to inheritance afterward.
      */
     saveFleetConfig(explicitPatches?: RawConfigPatch[]): void;
+    /** One-time upgrade migration; invalid YAML is never rewritten. */
+    private slimFleetConfigAtStartup;
+    private writeFleetConfigBackup;
     private patchFleetDocument;
     removeInstance(name: string): Promise<void>;
     startStatuslineWatcher(name: string): void;
@@ -536,10 +694,30 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
      * The log line is written by the caller regardless: if every adapter is down,
      * the only notification path is the one that is broken.
      */
+    /**
+     * Surface ids that can never match into the operator's General topic.
+     *
+     * The load-time log is still silence for anyone not reading daemon.log, and a
+     * chat that never gets in with nothing said anywhere is exactly the failure
+     * this line of work exists to remove. notifyFleetError throttles by message
+     * text for 10 minutes and resolves its target from config, so the 30s reload
+     * poll cannot flood the topic and a down General does not swallow it.
+     */
+    private reportClassicUnrecoverableIds;
     notifyFleetError(text: string): void;
     private static readonly FLEET_ERROR_THROTTLE_MS;
     private fleetErrorNotices;
-    notifyInstanceTopic(instanceName: string, text: string, extraOpts?: import("./channel/types.js").SendOpts): void;
+    /**
+     * Post into an instance's topic. Returns whether a send was DISPATCHED — a
+     * target was resolved and sendText was called — so a caller that must not
+     * lose the message (notifyFleetError, which spends a throttle key) can tell
+     * that from silence. Existing callers ignore the result and are unaffected.
+     *
+     * Not a delivery guarantee: sendText is fire-and-forget, and a platform-side
+     * rejection surfaces only as a warn in its .catch. True delivery confirmation
+     * would have to make this async and change every caller.
+     */
+    notifyInstanceTopic(instanceName: string, text: string, extraOpts?: import("./channel/types.js").SendOpts): boolean;
     /**
      * Post decision buttons whose callback ids are `<prefix><nonce>:<action>`.
      * The entry is registered before the send and rolled back if the send
@@ -548,13 +726,12 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
      */
     private postNonceButtonPrompt;
     /**
-     * Claim a nonce-armed callback exactly once.
+     * Validate a nonce-armed callback and claim it exactly once.
      *
      * Returns:
      *  - null       — the callback is not for this prefix; try the next handler
      *  - "consumed" — for this prefix but stale/denied/malformed; stop dispatch
-     *  - the entry+action — the click is authorized and now claimed (removed
-     *    from the map before any await, so double clicks cannot act twice)
+     *  - the entry+action — the click is authorized and claimed before any await
      *
      * A stale click (expired nonce, or a pre-upgrade button whose payload no
      * longer parses) collapses the clicked message so the dead button stops
@@ -563,6 +740,19 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     private consumeNonceCallback;
     /** Collapse a consumed prompt's buttons into a final status line. */
     private retireNonceButtons;
+    private tipsEnabled;
+    private readTipState;
+    private pickAvailableTip;
+    private tipText;
+    private formatTip;
+    /** Persistently enable advanced tips through the admin-only slash command. */
+    unlockAdvancedTips(userId: string): boolean;
+    /** Post one fresh nonce-armed tip in a known General channel. */
+    promptTip(generalName: string, adapter: ChannelAdapter, chatId: string, threadId?: string): Promise<"posted" | "empty" | "unavailable">;
+    private promptAdvancedTipUnlock;
+    private sendTipToGeneral;
+    private handleTipDismiss;
+    private handleTipUnlock;
     /** Post the destructive `/clear` confirmation in the invoking channel. */
     promptClearConfirmation(instanceName: string, channelId: string, adapter: ChannelAdapter, chatId: string, threadId?: string): Promise<string | null>;
     /** Consume `/clear` Confirm/Cancel exactly once; only Confirm reaches IPC. */
@@ -617,7 +807,7 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
      */
     private handleCancelClick;
     private hasCancelButton;
-    sendCancelButton(instanceName: string, correlationId?: string): Promise<void>;
+    sendCancelButton(instanceName: string, correlationId?: string, preserveProgress?: boolean): Promise<void>;
     /**
      * The cancel button's text for a given elapsed time.
      *
@@ -627,6 +817,13 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
      * and once the agent had replied once there was no sign it was still going.
      */
     static progressText(elapsedMs: number, activity?: string | null, minElapsedMs?: number): string;
+    /** Render elapsed time consistently in live and retained progress bubbles. */
+    private static formatProgressElapsed;
+    /** Final read-only form of a bubble that contains semantic tool history.
+     * Neutral wording is intentional: the same retirement primitive is used for
+     * normal completion, a mid-turn bubble replacement, and user cancellation,
+     * so claiming every retained checkpoint is "completed" would be false. */
+    private composeRetiredBubbleText;
     /**
      * Make a tool summary safe to paste into a channel message.
      *
@@ -644,6 +841,26 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
      * never used to decide anything — purely what the user is shown.
      */
     private cacheInstanceActivity;
+    /**
+     * Cache the turn's tool-progress list and push it into the instance's live
+     * bubble, coalesced so a burst of tool events cannot flood the Bot API
+     * (Telegram's flood limit is per-chat across ALL forum topics, so edits are
+     * rate-limited per bubble AND ride behind the daemon-side 3s coalescer).
+     */
+    private cacheInstanceProgress;
+    /** At most one progress-driven edit per bubble per TOOL_PROGRESS_EDIT_MIN_MS. */
+    private scheduleProgressEdit;
+    /**
+     * The ONE composer for the bubble text. Both writers — the elapsed-time
+     * ticker and the tool-progress push — go through here; two independent
+     * renderers editing the same message is how the progress list used to get
+     * wiped by the next elapsed tick (#528 trap 2).
+     */
+    private composeBubbleText;
+    /** Pure composition of header + tool list, exposed for tests. */
+    static bubbleText(elapsedMs: number, activity: string | undefined, minElapsedMs: number, progress: string | undefined): string;
+    /** Recompose and edit the bubble in place; skips when nothing changed. */
+    private refreshBubble;
     /**
      * Refresh the button's text in place while the instance keeps working.
      *
@@ -656,10 +873,14 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     private startProgressTicker;
     /**
      * After a reply: give the instance REPLY_RETIRE_GRACE_MS to resume working; if
-     * it has not, retire its button. Re-arming replaces the previous timer, so a
-     * burst of replies ends with exactly one pending check.
+     * it has not, retire its button. The daemon is asked for a fresh pane capture
+     * before deciding. Reading only the transition cache stranded the first
+     * post-restart bubble when its startup "working" report never got a matching
+     * idle edge. Re-arming replaces the previous timer, so a burst of replies ends
+     * with exactly one pending check.
      */
     private armReplyGrace;
+    private finishReplyGrace;
     /** Retire (delete) every cancel button belonging to an instance. */
     private retireInstanceButtons;
     /** Begin retiring one button (delete + bounded retry on failure). Idempotent:
@@ -684,7 +905,9 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     private sweepOrphanedCancelButtons;
     /** Re-attempt a failed button delete up to CANCEL_BTN_MAX_RETRIES times. */
     private scheduleButtonRetry;
-    /** Delete one button's message via its own adapter. Resolves on success,
+    /** Retire one cancel bubble via its own adapter. A bubble that accumulated
+     * tool progress is kept as a read-only history message; a plain bubble keeps
+     * the legacy delete/edit-to-checkmark behavior. Resolves on success and
      * rejects on failure so the caller can retry. */
     private deleteButtonMessage;
     /** Retire all cancel buttons for an instance — on reply or cancel. */
@@ -708,6 +931,123 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     private reactDone;
     /** Interrupt an instance's current generation (cancel button / /cancel). */
     cancelInstance(instanceName: string): boolean;
+    getDeliveryEpoch(instanceName: string): number;
+    private isDeliveryEpochCurrent;
+    /** Invalidate work queued before a user cancel and wake idle-gate waiters. */
+    private cancelPendingDeliveries;
+    private activeLogin;
+    /** Post the backend chooser for a bare `/login`. Caller enforces admin. */
+    promptLoginBackends(chat: {
+        adapter: ChannelAdapter;
+        adapterId: string;
+        chatId: string;
+        threadId?: string;
+    }): Promise<void>;
+    /**
+     * Ask the General topic to approve a ClassicBot access request.
+     *
+     * Two affirmative buttons rather than one, when the trigger identified a
+     * user. Allowing a group to talk and granting that person ClassicBot admin
+     * (start/stop/model on classic channels — NOT fleet admin, which reads
+     * fleet.yaml `channel.access.allowed_users`) have different blast radii, and
+     * bundling them would force anyone who wants only the cheap one to accept the
+     * expensive one or go edit YAML by hand.
+     *
+     * Built on postNonceButtonPrompt, so it inherits the canonical-address
+     * binding (#682) that makes these buttons answer in a Telegram General topic.
+     */
+    private promptClassicApproval;
+    /**
+     * Apply an approved ClassicBot access request.
+     *
+     * Writes through ClassicChannelManager's typed mutators rather than handing
+     * General a YAML edit: the id is stored via String() so a Discord snowflake
+     * cannot land as a YAML integer and lose precision, the existing save() path
+     * is reused, in-memory state is correct immediately (no waiting on the 30s
+     * reload poll), and a click cannot silently do nothing because General
+     * happened to be paused. General is still told the outcome.
+     */
+    private applyClassicApproval;
+    /** Consume a ClassicBot approval button. */
+    private handleClassicApproval;
+    /**
+   * Backend chooser for a bare `/install-cli`, mirroring promptLoginBackends so
+   * both commands feel the same. Built on postNonceButtonPrompt rather than the
+   * `/model` selection coordinator: that is the mechanism `/login` already uses,
+   * and the one whose canonical-address binding (#682) makes the buttons answer
+   * in a Telegram General topic.
+   *
+   * Unlike the login chooser this does NOT filter to backends the fleet already
+   * runs. Installing is how you get a backend you do not have yet, so filtering
+   * by configured backends would hide the only entry the admin came for.
+   *
+   * gemini-cli is omitted: it is deprecated (see backend/factory.ts). Typing
+   * `/install-cli gemini-cli` still works — this only stops recommending it.
+   */
+    promptInstallBackends(chat: {
+        adapter: ChannelAdapter;
+        adapterId: string;
+        chatId: string;
+        threadId?: string;
+    }): Promise<void>;
+    /** Backend chooser button → start that backend's install session. */
+    private handleInstallBackendSelect;
+    /**
+     * Start a login session for one backend. Caller enforces admin.
+     * Returns a status line to post, or null when a confirmation prompt was
+     * posted instead (auth still valid — see the pre-check below).
+     */
+    startLoginSession(backendArg: string, chat: {
+        adapter: ChannelAdapter;
+        adapterId: string;
+        chatId: string;
+        threadId?: string;
+    }, opts?: {
+        skipAuthCheck?: boolean;
+    }): Promise<string | null>;
+    /** Create the login window and session (pre-check already settled). */
+    private launchLoginSession;
+    /** `/login code <text>` — paste admin-supplied text into the login window. */
+    loginSubmitInput(text: string): Promise<string>;
+    /** `/login cancel` — abort the active session and remove its window. */
+    cancelLoginSession(): Promise<string>;
+    /**
+     * The URL (+ code) is a live credential: whoever completes it binds THEIR
+     * account to this fleet's CLI. Telegram gets an HTML spoiler (same treatment
+     * as the dashboard token); other adapters get plain text with the warning.
+     */
+    private sendLoginSecret;
+    /**
+     * After a successful login: wake the paused instances of that backend AND
+     * restart the running ones — a live CLI holds the old token in memory and
+     * only re-reads credentials on process start (a paused instance's CLI is
+     * already dead, so waking it respawns with the new token for free).
+     */
+    private recoverBackendInstances;
+    /** Backend chooser button → start that backend's login session. */
+    private handleLoginBackendSelect;
+    /** Re-login confirmation (auth pre-check said credentials still work). */
+    private handleLoginConfirm;
+    /** Kiro provider button → drive the CLI's arrow-key selector. */
+    private handleLoginMenuSelect;
+    private activeInstall;
+    /** Start a CLI install session. Caller enforces admin. */
+    startInstallSession(backendArg: string, chat: {
+        adapter: ChannelAdapter;
+        adapterId: string;
+        chatId: string;
+        threadId?: string;
+    }): Promise<string>;
+    /** `/install-cli cancel` — abort the active install and remove its window. */
+    cancelInstallSession(): Promise<string>;
+    /** `command -v` on a login shell, so PATH additions from rc files count. */
+    private verifyBinaryOnLoginShell;
+    /** "Sign in now?" button after a successful install. */
+    private handleInstallLoginConfirm;
+    /** Discord native `/login` slash — shared by every adapter dispatch block. */
+    private handleLoginSlash;
+    /** Discord native `/install-cli` slash — shared by every dispatch block. */
+    private handleInstallCliSlash;
     queueMirrorMessage(text: string): void;
     /** Push an SSE event to all connected Web UI clients. */
     emitSseEvent(event: string, data: unknown): void;
@@ -728,8 +1068,45 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     private static GENERAL_INSTRUCTIONS;
     /** Ensure the general instance has its project instructions file + knowledge */
     private ensureGeneralInstructions;
-    /** Copy general-knowledge steering + skills to the general instance's workspace */
+    /** Resolve the workspace path a backend actually uses before publishing knowledge. */
+    private resolveKnowledgeWorkDir;
+    /**
+     * Where each backend natively loads on-demand skills from, relative to the
+     * workspace. Backends without a native skill mechanism (opencode, grok,
+     * antigravity, gemini-cli) are deliberately absent: dropping files a CLI
+     * never reads is clutter, not capability. Unknown directories are ignored
+     * by older CLI versions, so publishing is fail-open across upgrades.
+     */
+    private static SKILLS_DIR_SEGMENTS;
+    /** Copy general-knowledge steering + all role-eligible skills to General. */
     private syncGeneralKnowledge;
+    /** Publish only the bundled skills eligible for an instance role. */
+    private syncRoleSkills;
+    /**
+     * Steering (always-on rules like core-rules.md). Kiro loads a native
+     * steering directory; every other backend gets the content embedded into
+     * its instructions file (CLAUDE.md / AGENTS.md / …) inside a managed marker
+     * block — the previous behavior dropped bare .md files in the workspace
+     * root, which no CLI ever read. The block is replaced in place on every
+     * sync, so rule updates reach EXISTING workspaces; everything the user
+     * wrote outside the markers is preserved byte-for-byte.
+     */
+    private syncGeneralSteering;
+    private static STEERING_BLOCK_BEGIN;
+    private static STEERING_BLOCK_END;
+    /**
+     * Publish AgEnD's bundled skills into a CLI's native skills directory,
+     * owning ONLY what we published. A manifest records which skill names AgEnD
+     * wrote; a bundled rename/removal deletes the stale managed copy, while a
+     * skill the user created by hand is never listed and therefore never
+     * touched — even if a future bundle happens to reuse its name (the sync
+     * then skips it and logs, rather than overwrite the user's work). The sole
+     * migration exception is the pre-manifest Kiro General layout explicitly
+     * selected by adoptLegacyUnmanaged.
+     */
+    private syncManagedSkills;
+    /** Read AgEnD's roles extension from SKILL.md YAML frontmatter. */
+    private readManagedSkillRoles;
     /** Fetch forum topic icon stickers and pick emoji IDs for each state */
     private resolveTopicIcons;
     /** Set topic icon based on instance state */
@@ -772,6 +1149,34 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     private probeCliEnvs;
     /** Best-effort model list for `/model`: cached CLI env first, else live probe. Never throws. */
     private getModelOptions;
+    /**
+     * Model catalog behind the `list_models` tool.
+     *
+     * The two scopes are not cosmetic. "global" is the account/CLI catalog served
+     * from the startup probe cache; "instance" is resolved through that instance's
+     * OWN backend config, and for a Codex instance on a custom provider that is a
+     * different catalog entirely — `listModels()` reads models_cache.json out of
+     * the instance's private CODEX_HOME. Answering such an instance with the
+     * account list would name models its CLI rejects, which is exactly the
+     * mistake this tool exists to prevent.
+     *
+     * `scope` always describes where the returned LIST came from, not what was
+     * asked for: an instance query that falls back to the account catalog reports
+     * scope "global" and says so in `note`, rather than implying instance-level
+     * accuracy it does not have.
+     *
+     * Never throws — a model listing is an aid, and failing it must not fail a turn.
+     */
+    listModelCatalog(opts?: {
+        backend?: string;
+        instanceName?: string;
+    }): Promise<ModelCatalog>;
+    /** The custom provider an instance overrides its backend with, if any. */
+    private customProviderFor;
+    /** Ask a backend for its catalog using ONE instance's real config. Never throws. */
+    private instanceScopedModels;
+    /** Account-wide catalog: probe cache first, live probe on miss. */
+    private globalModelCatalog;
     /** `/model` slash handler (admin only). No arg → DC menu; `/model <name>` → apply directly. */
     /** Label an effort choice, marking the one currently configured. */
     private effortChoiceLabel;
@@ -789,6 +1194,10 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
      * 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>;
+    /** Cached-or-live account catalog behind "/model → more models" (claude). */
+    private claudeApiModelOptions;
+    /** Replace a consumed "/model" menu with the full account catalog tier. */
+    private expandClaudeModelMenu;
     /** 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). */
@@ -876,7 +1285,8 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     /**
      * Hot-reload: re-read fleet.yaml and reconcile running instances.
      * Starts new, stops removed, restarts modified instances.
-     * Fleet-level config (access, cost_guard, etc.) requires /restart to take effect.
+     * Whitelisted runtime fields are pushed into live daemons; all other instance
+     * fields, plus cold fleet-level settings, retain restart semantics.
      */
     private reconcileInstances;
     restartInstances(): Promise<void>;