@suzuke/agend 1.1.1 → 1.3.0

package/dist/fleet-manager.js

@@ -1,7 +1,6 @@
 import { existsSync, readFileSync, mkdirSync, writeFileSync, unlinkSync } from "node:fs";
-import { access } from "node:fs/promises";
 import { createServer } from "node:http";
-import { join, dirname, basename } from "node:path";
+import { join, dirname } from "node:path";
 import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
 import yaml from "js-yaml";
@@ -20,10 +19,16 @@ import { processAttachments } from "./channel/attachment-handler.js";
 import { routeToolCall } from "./channel/tool-router.js";
 import { Scheduler } from "./scheduler/index.js";
 import { DEFAULT_SCHEDULER_CONFIG } from "./scheduler/index.js";
-import { TopicCommands, sanitizeInstanceName } from "./topic-commands.js";
+import { TopicCommands } from "./topic-commands.js";
 import { DailySummary } from "./daily-summary.js";
 import { WebhookEmitter } from "./webhook-emitter.js";
 import { TmuxControlClient } from "./tmux-control.js";
+import { safeHandler } from "./safe-async.js";
+import { RoutingEngine } from "./routing-engine.js";
+import { InstanceLifecycle } from "./instance-lifecycle.js";
+import { TopicArchiver } from "./topic-archiver.js";
+import { StatuslineWatcher } from "./statusline-watcher.js";
+import { outboundHandlers } from "./outbound-handlers.js";
 const TMUX_SESSION = "agend";
 export function resolveReplyThreadId(argsThreadId, instanceConfig) {
     if (typeof argsThreadId === "string" && argsThreadId.length > 0) {
@@ -37,10 +42,13 @@ export function resolveReplyThreadId(argsThreadId, instanceConfig) {
 export class FleetManager {
     dataDir;
     children = new Map();
-    daemons = new Map();
+    lifecycle;
+    /** @deprecated Use lifecycle.daemons — kept for backward compat */
+    get daemons() { return this.lifecycle.daemons; }
     fleetConfig = null;
     adapter = null;
-    routingTable = new Map();
+    routing = new RoutingEngine();
+    get routingTable() { return this.routing.map; }
     instanceIpcClients = new Map();
     scheduler = null;
     configPath = "";
@@ -50,25 +58,52 @@ export class FleetManager {
     sessionRegistry = new Map();
     eventLog = null;
     costGuard = null;
-    statuslineWatchers = new Map();
-    instanceRateLimits = new Map();
+    statuslineWatcher;
     dailySummary = null;
     webhookEmitter = null;
     // Topic icon + auto-archive state
     topicIcons = {};
     lastActivity = new Map();
-    archivedTopics = new Set();
-    archiveTimer = null;
-    static ARCHIVE_IDLE_MS = 24 * 60 * 60 * 1000; // 24 hours
+    topicArchiver;
+    controlClient = null;
     // Model failover state
     failoverActive = new Map(); // instance → current failover model
-    controlClient = null;
     // Health endpoint
     healthServer = null;
     startedAt = 0;
     constructor(dataDir) {
         this.dataDir = dataDir;
+        this.lifecycle = new InstanceLifecycle(this);
         this.topicCommands = new TopicCommands(this);
+        this.topicArchiver = new TopicArchiver(this);
+        this.statuslineWatcher = new StatuslineWatcher(this);
+    }
+    // ── ArchiverContext bridge ────────────────────────────────────────────
+    lastActivityMs(name) {
+        return this.lastActivity.get(name) ?? 0;
+    }
+    // ── LifecycleContext bridge methods ──────────────────────────────────────
+    webhookEmit(event, name) {
+        this.webhookEmitter?.emit(event, name);
+    }
+    // ── SysInfo ────────────────────────────────────────────────────────────
+    getSysInfo() {
+        const mem = process.memoryUsage();
+        const toMB = (b) => Math.round(b / 1024 / 1024 * 10) / 10;
+        const instances = Object.keys(this.fleetConfig?.instances ?? {}).map(name => ({
+            name,
+            status: this.getInstanceStatus(name),
+            ipc: this.instanceIpcClients.has(name),
+            costCents: this.costGuard?.getDailyCostCents(name) ?? 0,
+            rateLimits: this.statuslineWatcher.getRateLimits(name) ?? null,
+        }));
+        return {
+            uptime_seconds: Math.floor((Date.now() - this.startedAt) / 1000),
+            memory_mb: { rss: toMB(mem.rss), heapUsed: toMB(mem.heapUsed), heapTotal: toMB(mem.heapTotal) },
+            instances,
+            fleet_cost_cents: this.costGuard?.getFleetTotalCents() ?? 0,
+            fleet_cost_limit_cents: this.costGuard?.getLimitCents() ?? 0,
+        };
     }
     /** Load fleet.yaml and build routing table */
     loadConfig(configPath) {
@@ -77,18 +112,10 @@ export class FleetManager {
     }
     /** Build topic routing table: { topicId -> RouteTarget } */
     buildRoutingTable() {
-        const table = new Map();
-        if (!this.fleetConfig)
-            return table;
-        for (const [name, inst] of Object.entries(this.fleetConfig.instances)) {
-            if (inst.topic_id != null) {
-                table.set(inst.topic_id, {
-                    kind: inst.general_topic ? "general" : "instance",
-                    name,
-                });
-            }
+        if (this.fleetConfig) {
+            this.routing.rebuild(this.fleetConfig);
         }
-        return table;
+        return this.routing.map;
     }
     getInstanceDir(name) {
         return join(this.dataDir, "instances", name);
@@ -107,65 +134,11 @@ export class FleetManager {
         }
     }
     async startInstance(name, config, topicMode) {
-        if (this.daemons.has(name)) {
-            this.logger.info({ name }, "Instance already running, skipping");
-            return;
-        }
-        if (!existsSync(config.working_directory)) {
-            this.logger.error({ name, working_directory: config.working_directory }, "Working directory does not exist — skipping instance");
-            return;
-        }
-        const instanceDir = this.getInstanceDir(name);
-        mkdirSync(instanceDir, { recursive: true });
-        const { Daemon } = await import("./daemon.js");
-        const { createBackend } = await import("./backend/factory.js");
-        const backendName = config.backend ?? this.fleetConfig?.defaults?.backend ?? "claude-code";
-        const backend = createBackend(backendName, instanceDir);
-        const daemon = new Daemon(name, config, instanceDir, topicMode, backend, this.controlClient ?? undefined);
-        await daemon.start();
-        this.daemons.set(name, daemon);
-        daemon.on("restart_complete", (data) => {
-            this.eventLog?.insert(name, "context_rotation", data);
-            this.logger.info({ name, ...data }, "Context restart completed");
-        });
-        const hangDetector = daemon.getHangDetector();
-        if (hangDetector) {
-            hangDetector.on("hang", () => {
-                this.eventLog?.insert(name, "hang_detected", {});
-                this.logger.warn({ name }, "Instance appears hung");
-                this.sendHangNotification(name);
-                this.webhookEmitter?.emit("hang", name);
-            });
-        }
-        daemon.on("crash_loop", () => {
-            this.eventLog?.insert(name, "crash_loop", {});
-            this.logger.error({ name }, "Instance in crash loop — respawn paused");
-            this.notifyInstanceTopic(name, `🔴 ${name} keeps crashing shortly after launch — respawn paused. Check rate limits or run \`agend fleet restart\`.`);
-            this.setTopicIcon(name, "red");
-        });
-        this.setTopicIcon(name, "green");
-        this.touchActivity(name);
+        return this.lifecycle.start(name, config, topicMode);
     }
     async stopInstance(name) {
-        this.setTopicIcon(name, "remove");
         this.failoverActive.delete(name);
-        const daemon = this.daemons.get(name);
-        if (daemon) {
-            await daemon.stop();
-            this.daemons.delete(name);
-        }
-        else {
-            const pidPath = join(this.getInstanceDir(name), "daemon.pid");
-            if (existsSync(pidPath)) {
-                const pid = parseInt(readFileSync(pidPath, "utf-8").trim(), 10);
-                try {
-                    process.kill(pid, "SIGTERM");
-                }
-                catch (e) {
-                    this.logger.debug({ err: e, pid }, "SIGTERM failed for stale process");
-                }
-            }
-        }
+        return this.lifecycle.stop(name);
     }
     /** Load .env file from data dir into process.env */
     loadEnvFile() {
@@ -226,16 +199,16 @@ export class FleetManager {
             this.webhookEmitter = new WebhookEmitter(webhookConfigs, this.logger);
             this.logger.info({ count: webhookConfigs.length }, "Webhook emitter initialized");
         }
-        this.costGuard.on("warn", (instance, totalCents, limitCents) => {
+        this.costGuard.on("warn", safeHandler((instance, totalCents, limitCents) => {
             this.notifyInstanceTopic(instance, `⚠️ ${instance} cost: ${formatCents(totalCents)} / ${formatCents(limitCents)} (${Math.round(totalCents / limitCents * 100)}%)`);
             this.webhookEmitter?.emit("cost_warning", instance, { cost_cents: totalCents, limit_cents: limitCents });
-        });
-        this.costGuard.on("limit", (instance, totalCents, limitCents) => {
+        }, this.logger, "costGuard.warn"));
+        this.costGuard.on("limit", safeHandler(async (instance, totalCents, limitCents) => {
             this.notifyInstanceTopic(instance, `🛑 ${instance} daily limit ${formatCents(limitCents)} reached — pausing instance.`);
             this.eventLog?.insert(instance, "instance_paused", { reason: "cost_limit", cost_cents: totalCents });
             this.webhookEmitter?.emit("cost_limit", instance, { cost_cents: totalCents, limit_cents: limitCents });
-            this.stopInstance(instance).catch(err => this.logger.error({ err, instance }, "Failed to pause instance on cost limit"));
-        });
+            await this.stopInstance(instance);
+        }, this.logger, "costGuard.limit"));
         const summaryConfig = {
             ...DEFAULT_DAILY_SUMMARY,
             ...fleet.defaults?.daily_summary ?? {},
@@ -309,12 +282,11 @@ export class FleetManager {
             await this.startSharedAdapter(fleet);
             // Auto-create topics AFTER adapter is ready (needs adapter.createTopic)
             await this.topicCommands.autoCreateTopics();
-            this.routingTable = this.buildRoutingTable();
-            const routeSummary = [...this.routingTable.entries()].map(([tid, target]) => `#${tid}→${target.name}`).join(", ");
+            const routeSummary = this.routing.rebuild(this.fleetConfig);
             this.logger.info(`Routes: ${routeSummary}`);
             // Resolve topic icon emoji IDs and start idle archive poller
             await this.resolveTopicIcons();
-            this.startArchivePoller();
+            this.topicArchiver.startPoller();
             await new Promise(r => setTimeout(r, 3000));
             await this.connectToInstances(fleet);
             for (const name of Object.keys(fleet.instances)) {
@@ -352,7 +324,7 @@ export class FleetManager {
         };
         process.once("SIGUSR1", onFullRestart);
     }
-    /** Start the shared Telegram adapter for topic mode */
+    /** Start the shared channel adapter for topic mode */
     async startSharedAdapter(fleet) {
         const channelConfig = fleet.channel;
         const botToken = process.env[channelConfig.bot_token_env];
@@ -371,10 +343,10 @@ export class FleetManager {
             accessManager,
             inboxDir,
         });
-        this.adapter.on("message", (msg) => {
-            this.handleInboundMessage(msg);
-        });
-        this.adapter.on("callback_query", async (data) => {
+        this.adapter.on("message", safeHandler(async (msg) => {
+            await this.handleInboundMessage(msg);
+        }, this.logger, "adapter.message"));
+        this.adapter.on("callback_query", safeHandler(async (data) => {
             if (data.callbackData.startsWith("hang:")) {
                 const parts = data.callbackData.split(":");
                 const action = parts[1];
@@ -395,28 +367,27 @@ export class FleetManager {
                 }
                 return;
             }
-        });
-        this.adapter.on("topic_closed", (data) => {
-            const tid = parseInt(data.threadId, 10);
+        }, this.logger, "adapter.callback_query"));
+        this.adapter.on("topic_closed", safeHandler(async (data) => {
             // Skip unbind if we archived this topic ourselves
-            if (this.archivedTopics.has(tid))
+            if (this.topicArchiver.isArchived(data.threadId))
                 return;
-            this.topicCommands.handleTopicDeleted(tid);
-        });
+            await this.topicCommands.handleTopicDeleted(data.threadId);
+        }, this.logger, "adapter.topic_closed"));
         await this.topicCommands.registerBotCommands();
         await this.adapter.start();
         if (fleet.channel?.group_id) {
             this.adapter.setChatId(String(fleet.channel.group_id));
         }
-        this.adapter.on("started", (username) => {
-            this.logger.info(`Telegram bot @${username} polling`);
-        });
-        this.adapter.on("polling_conflict", ({ attempt, delay }) => {
+        this.adapter.on("started", safeHandler((username) => {
+            this.logger.info(`Bot @${username} polling`);
+        }, this.logger, "adapter.started"));
+        this.adapter.on("polling_conflict", safeHandler(({ attempt, delay }) => {
             this.logger.warn(`409 Conflict (attempt ${attempt}), retry in ${delay / 1000}s`);
-        });
-        this.adapter.on("handler_error", (err) => {
-            this.logger.warn({ err: err instanceof Error ? err.message : String(err) }, "Telegram handler error");
-        });
+        }, this.logger, "adapter.polling_conflict"));
+        this.adapter.on("handler_error", safeHandler((err) => {
+            this.logger.warn({ err: err instanceof Error ? err.message : String(err) }, "Adapter handler error");
+        }, this.logger, "adapter.handler_error"));
         this.startTopicCleanupPoller();
         // Prune stale external sessions every 5 minutes
         this.sessionPruneTimer = setInterval(() => {
@@ -438,7 +409,7 @@ export class FleetManager {
         try {
             await ipc.connect();
             this.instanceIpcClients.set(name, ipc);
-            ipc.on("message", (msg) => {
+            ipc.on("message", safeHandler(async (msg) => {
                 if (msg.type === "mcp_ready") {
                     // Register external sessions (sessionName differs from instance name)
                     const sessionName = msg.sessionName;
@@ -463,7 +434,7 @@ export class FleetManager {
                         this.sessionRegistry.set(sender, name);
                         this.logger.info({ sessionName: sender, instanceName: name }, "Registered external session");
                     }
-                    this.handleOutboundFromInstance(name, msg).catch(err => this.logger.error({ err }, "handleOutboundFromInstance error"));
+                    await this.handleOutboundFromInstance(name, msg);
                 }
                 else if (msg.type === "fleet_tool_status") {
                     this.handleToolStatusFromInstance(name, msg);
@@ -472,13 +443,13 @@ export class FleetManager {
                     msg.type === "fleet_schedule_update" || msg.type === "fleet_schedule_delete") {
                     this.handleScheduleCrud(name, msg);
                 }
-            });
+            }, this.logger, `ipc.message[${name}]`));
             // Ask daemon for any sessions that registered before we connected
             // (fixes race condition where mcp_ready was broadcast before fleet manager connected)
             ipc.send({ type: "query_sessions" });
             this.logger.debug({ name }, "Connected to instance IPC");
-            if (!this.statuslineWatchers.has(name)) {
-                this.startStatuslineWatcher(name);
+            if (!this.statuslineWatcher.has(name)) {
+                this.statuslineWatcher.watch(name);
             }
         }
         catch (err) {
@@ -497,7 +468,7 @@ export class FleetManager {
         return undefined;
     }
     async handleInboundMessage(msg) {
-        const threadId = msg.threadId ? parseInt(msg.threadId, 10) : undefined;
+        const threadId = msg.threadId || undefined;
         if (threadId == null) {
             // General topic: check for /status command
             if (await this.topicCommands.handleGeneralCommand(msg))
@@ -534,15 +505,15 @@ export class FleetManager {
             }
             return;
         }
-        const target = this.routingTable.get(threadId);
+        const target = this.routing.resolve(threadId);
         if (!target) {
             this.topicCommands.handleUnboundTopic(msg);
             return;
         }
         const instanceName = target.name;
         // Reopen archived topic before routing
-        if (this.archivedTopics.has(threadId)) {
-            await this.reopenArchivedTopic(threadId, instanceName);
+        if (this.topicArchiver.isArchived(threadId)) {
+            await this.topicArchiver.reopen(threadId, instanceName);
         }
         this.touchActivity(instanceName);
         this.setTopicIcon(instanceName, "blue");
@@ -561,7 +532,7 @@ export class FleetManager {
         ipc.send({
             type: "fleet_inbound",
             content: text,
-            targetSession: instanceName, // Telegram messages → instance's own session
+            targetSession: instanceName, // Channel messages → instance's own session
             meta: {
                 chat_id: msg.chatId,
                 message_id: msg.messageId,
@@ -577,13 +548,13 @@ export class FleetManager {
     }
     /** Handle outbound tool calls from a daemon instance */
     replyIfRateLimited(instanceName, msg) {
-        const rl = this.instanceRateLimits.get(instanceName);
+        const rl = this.statuslineWatcher.getRateLimits(instanceName);
         if (!rl || rl.seven_day_pct < 100)
             return false;
         if (this.adapter && msg.chatId) {
             const threadId = msg.threadId ?? undefined;
             this.adapter.sendText(msg.chatId, `⏸ ${instanceName} has hit the weekly usage limit. Your message was not delivered. Limit resets automatically — check /status for details.`, { threadId })
-                .catch(e => this.logger.debug({ err: e }, "Failed to send rate limit notice"));
+                .catch(e => this.logger.warn({ err: e }, "Failed to send rate limit notice"));
         }
         this.logger.info({ instanceName }, "Blocked inbound message — weekly rate limit at 100%");
         return true;
@@ -618,389 +589,13 @@ export class FleetManager {
             }
             return;
         }
-        // Fleet-specific tools
-        switch (tool) {
-            case "send_to_instance": {
-                const targetName = args.instance_name;
-                const message = args.message;
-                if (!targetName) {
-                    respond(null, "send_to_instance: missing required argument 'instance_name'");
-                    break;
-                }
-                if (!message) {
-                    respond(null, "send_to_instance: missing required argument 'message'");
-                    break;
-                }
-                const senderLabel = senderSessionName ?? instanceName;
-                const isExternalSender = senderSessionName != null && senderSessionName !== instanceName;
-                // Resolve target: could be an instance name or an external session name
-                let targetIpc = this.instanceIpcClients.get(targetName);
-                let targetSession = targetName; // default: target is the instance itself
-                let targetInstanceName = targetName;
-                if (!targetIpc) {
-                    // Check if target is an external session
-                    const hostInstance = this.sessionRegistry.get(targetName);
-                    if (hostInstance) {
-                        targetIpc = this.instanceIpcClients.get(hostInstance);
-                        targetSession = targetName; // deliver to the external session
-                        targetInstanceName = hostInstance;
-                    }
-                }
-                if (!targetIpc) {
-                    // Check if instance exists in config but is stopped
-                    const existsInConfig = targetName in (this.fleetConfig?.instances ?? {});
-                    if (existsInConfig) {
-                        respond(null, `Instance '${targetName}' is stopped. Use start_instance('${targetName}') to start it first.`);
-                    }
-                    else {
-                        respond(null, `Instance or session not found: ${targetName}`);
-                    }
-                    break;
-                }
-                // Build structured metadata (Phase 2)
-                const correlationId = args.correlation_id || `cid-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
-                const meta = {
-                    chat_id: "",
-                    message_id: `xmsg-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
-                    user: `instance:${senderLabel}`,
-                    user_id: `instance:${senderLabel}`,
-                    ts: new Date().toISOString(),
-                    thread_id: "",
-                    from_instance: senderLabel,
-                    correlation_id: correlationId,
-                };
-                if (args.request_kind)
-                    meta.request_kind = args.request_kind;
-                if (args.requires_reply != null)
-                    meta.requires_reply = String(args.requires_reply);
-                if (args.task_summary)
-                    meta.task_summary = args.task_summary;
-                if (args.working_directory)
-                    meta.working_directory = args.working_directory;
-                if (args.branch)
-                    meta.branch = args.branch;
-                targetIpc.send({
-                    type: "fleet_inbound",
-                    targetSession,
-                    content: message,
-                    meta,
-                });
-                // Post to Telegram topics for visibility
-                const groupId = this.fleetConfig?.channel?.group_id;
-                if (groupId && this.adapter) {
-                    const senderTopicId = this.fleetConfig?.instances[instanceName]?.topic_id;
-                    const targetTopicId = this.fleetConfig?.instances[targetInstanceName]?.topic_id;
-                    // Post full message to topics — adapter handles 4096-char chunking
-                    // Only post to sender topic if sender is the instance itself (not external)
-                    if (senderTopicId && !isExternalSender) {
-                        this.adapter.sendText(String(groupId), `→ ${targetName}:\n${message}`, {
-                            threadId: String(senderTopicId),
-                        }).catch(e => this.logger.debug({ err: e }, "Failed to post cross-instance notification"));
-                    }
-                    // Only post to target topic if target is an instance (not external session)
-                    if (targetTopicId && !this.sessionRegistry.has(targetName)) {
-                        this.adapter.sendText(String(groupId), `← ${senderLabel}:\n${message}`, {
-                            threadId: String(targetTopicId),
-                        }).catch(e => this.logger.debug({ err: e }, "Failed to post cross-instance notification"));
-                    }
-                }
-                this.logger.info(`✉ ${senderLabel} → ${targetName}: ${(message ?? "").slice(0, 100)}`);
-                respond({ sent: true, target: targetName, correlation_id: correlationId });
-                break;
-            }
-            case "list_instances": {
-                const senderLabel = senderSessionName ?? instanceName;
-                const allInstances = Object.entries(this.fleetConfig?.instances ?? {})
-                    .filter(([name]) => name !== instanceName && name !== senderLabel)
-                    .map(([name, config]) => ({
-                    name,
-                    type: "instance",
-                    status: this.daemons.has(name) ? "running" : "stopped",
-                    working_directory: config.working_directory,
-                    topic_id: config.topic_id ?? null,
-                    description: config.description ?? null,
-                    tags: config.tags ?? [],
-                    last_activity: this.lastActivity.get(name) ? new Date(this.lastActivity.get(name)).toISOString() : null,
-                }));
-                // Include external sessions (excluding self)
-                const externalSessions = [...this.sessionRegistry.entries()]
-                    .filter(([sessName]) => sessName !== senderLabel)
-                    .map(([sessName, hostInstance]) => ({
-                    name: sessName, type: "session", host: hostInstance,
-                }));
-                respond({ instances: allInstances, external_sessions: externalSessions });
-                break;
-            }
-            // Phase 3: High-level collaboration tools (wrappers around send_to_instance)
-            case "request_information": {
-                const targetName = args.target_instance;
-                const question = args.question;
-                const context = args.context;
-                const body = context ? `${question}\n\nContext: ${context}` : question;
-                // Re-dispatch as send_to_instance with structured metadata
-                args.instance_name = targetName;
-                args.message = body;
-                args.request_kind = "query";
-                args.requires_reply = true;
-                args.task_summary = question.slice(0, 120);
-                // Recursively handle via the same switch (will hit send_to_instance case above)
-                return this.handleOutboundFromInstance(instanceName, { tool: "send_to_instance", args, requestId, fleetRequestId, senderSessionName });
-            }
-            case "delegate_task": {
-                const targetName = args.target_instance;
-                const task = args.task;
-                const criteria = args.success_criteria;
-                const context = args.context;
-                let body = task;
-                if (criteria)
-                    body += `\n\nSuccess criteria: ${criteria}`;
-                if (context)
-                    body += `\n\nContext: ${context}`;
-                args.instance_name = targetName;
-                args.message = body;
-                args.request_kind = "task";
-                args.requires_reply = true;
-                args.task_summary = task.slice(0, 120);
-                return this.handleOutboundFromInstance(instanceName, { tool: "send_to_instance", args, requestId, fleetRequestId, senderSessionName });
-            }
-            case "report_result": {
-                const targetName = args.target_instance;
-                const summary = args.summary;
-                const artifacts = args.artifacts;
-                if (!args.correlation_id) {
-                    this.logger.warn({ instanceName, targetName }, "report_result called without correlation_id — recipient cannot match this to an original request");
-                }
-                let body = summary;
-                if (artifacts)
-                    body += `\n\nArtifacts: ${artifacts}`;
-                args.instance_name = targetName;
-                args.message = body;
-                args.request_kind = "report";
-                args.requires_reply = false;
-                args.task_summary = summary.slice(0, 120);
-                return this.handleOutboundFromInstance(instanceName, { tool: "send_to_instance", args, requestId, fleetRequestId, senderSessionName });
-            }
-            // Phase 4: Capability discovery
-            case "describe_instance": {
-                const targetName = args.name;
-                const config = this.fleetConfig?.instances[targetName];
-                if (config) {
-                    respond({
-                        name: targetName,
-                        type: "instance",
-                        description: config.description ?? null,
-                        tags: config.tags ?? [],
-                        working_directory: config.working_directory,
-                        status: this.daemons.has(targetName) ? "running" : "stopped",
-                        topic_id: config.topic_id ?? null,
-                        model: config.model ?? null,
-                        last_activity: this.lastActivity.get(targetName) ? new Date(this.lastActivity.get(targetName)).toISOString() : null,
-                        worktree_source: config.worktree_source ?? null,
-                    });
-                    break;
-                }
-                // Check if it's a known external session
-                const hostInstance = this.sessionRegistry.get(targetName);
-                if (hostInstance) {
-                    respond({
-                        name: targetName,
-                        type: "session",
-                        host: hostInstance,
-                        status: "running",
-                    });
-                    break;
-                }
-                respond(null, `Instance or session '${targetName}' not found`);
-                break;
-            }
-            case "start_instance": {
-                const targetName = args.name;
-                // Already running?
-                if (this.daemons.has(targetName)) {
-                    respond({ success: true, status: "already_running" });
-                    break;
-                }
-                // Exists in config?
-                const targetConfig = this.fleetConfig?.instances[targetName];
-                if (!targetConfig) {
-                    respond(null, `Instance '${targetName}' not found in fleet config`);
-                    break;
-                }
-                try {
-                    await this.startInstance(targetName, targetConfig, true);
-                    await this.connectIpcToInstance(targetName);
-                    respond({ success: true, status: "started" });
-                }
-                catch (err) {
-                    respond(null, `Failed to start instance '${targetName}': ${err.message}`);
-                }
-                break;
-            }
-            case "create_instance": {
-                const directory = args.directory.replace(/^~/, process.env.HOME || "~");
-                const topicName = args.topic_name || basename(directory);
-                const description = args.description;
-                const branch = args.branch;
-                // Validate directory exists
-                try {
-                    await access(directory);
-                }
-                catch {
-                    respond(null, `Directory does not exist: ${directory}`);
-                    break;
-                }
-                // Check for duplicate early (before worktree creation) — only when no branch
-                if (!branch) {
-                    const expandHome = (p) => p.replace(/^~/, process.env.HOME || "~");
-                    const existingInstance = Object.entries(this.fleetConfig?.instances ?? {})
-                        .find(([_, config]) => expandHome(config.working_directory) === directory);
-                    if (existingInstance) {
-                        const [eName, eConfig] = existingInstance;
-                        respond({
-                            success: true,
-                            status: "already_exists",
-                            name: eName,
-                            topic_id: eConfig.topic_id,
-                            running: this.daemons.has(eName),
-                        });
-                        break;
-                    }
-                }
-                // If branch specified, create git worktree
-                let workDir = directory;
-                let worktreePath;
-                if (branch) {
-                    try {
-                        const { execFile: execFileCb } = await import("node:child_process");
-                        const { promisify } = await import("node:util");
-                        const execFileAsync = promisify(execFileCb);
-                        // Verify it's a git repo
-                        await execFileAsync("git", ["rev-parse", "--git-dir"], { cwd: directory });
-                        // Determine worktree path: sibling directory named repo-branch
-                        const repoName = basename(directory);
-                        const safeBranch = branch.replace(/\//g, "-");
-                        worktreePath = join(dirname(directory), `${repoName}-${safeBranch}`);
-                        // Check if branch exists
-                        let branchExists = false;
-                        try {
-                            await execFileAsync("git", ["rev-parse", "--verify", branch], { cwd: directory });
-                            branchExists = true;
-                        }
-                        catch { /* branch doesn't exist */ }
-                        if (branchExists) {
-                            await execFileAsync("git", ["worktree", "add", worktreePath, branch], { cwd: directory });
-                        }
-                        else {
-                            await execFileAsync("git", ["worktree", "add", worktreePath, "-b", branch], { cwd: directory });
-                        }
-                        this.logger.info({ worktreePath, branch, repo: directory }, "Created git worktree for instance");
-                        workDir = worktreePath;
-                    }
-                    catch (err) {
-                        respond(null, `Failed to create worktree: ${err.message}`);
-                        break;
-                    }
-                }
-                // Check worktree path for duplicates (branch case only — non-branch already checked above)
-                if (worktreePath) {
-                    const expandHome = (p) => p.replace(/^~/, process.env.HOME || "~");
-                    const existingInstance = Object.entries(this.fleetConfig?.instances ?? {})
-                        .find(([_, config]) => expandHome(config.working_directory) === workDir);
-                    if (existingInstance) {
-                        const [eName, eConfig] = existingInstance;
-                        respond({
-                            success: true,
-                            status: "already_exists",
-                            name: eName,
-                            topic_id: eConfig.topic_id,
-                            running: this.daemons.has(eName),
-                        });
-                        break;
-                    }
-                }
-                // Sequential steps with rollback
-                let createdTopicId;
-                let newInstanceName;
-                try {
-                    // Step a: Create Telegram topic
-                    createdTopicId = await this.createForumTopic(topicName);
-                    // Step b: Register in config
-                    // Use topicName for worktree instances to avoid long paths (Unix socket limit 104 bytes)
-                    const nameBase = worktreePath ? topicName : basename(workDir);
-                    newInstanceName = `${sanitizeInstanceName(nameBase)}-t${createdTopicId}`;
-                    const instanceConfig = {
-                        ...DEFAULT_INSTANCE_CONFIG,
-                        ...this.fleetConfig.defaults,
-                        working_directory: workDir,
-                        topic_id: createdTopicId,
-                        ...(description ? { description } : {}),
-                        ...(args.model ? { model: args.model } : {}),
-                        ...(args.backend ? { backend: args.backend } : {}),
-                        ...(worktreePath ? { worktree_source: directory } : {}),
-                    };
-                    this.fleetConfig.instances[newInstanceName] = instanceConfig;
-                    this.routingTable.set(createdTopicId, { kind: "instance", name: newInstanceName });
-                    this.saveFleetConfig();
-                    // Step c: Start instance
-                    await this.startInstance(newInstanceName, instanceConfig, true);
-                    await this.connectIpcToInstance(newInstanceName);
-                    respond({
-                        success: true,
-                        name: newInstanceName,
-                        topic_id: createdTopicId,
-                        ...(worktreePath ? { worktree_path: worktreePath, branch } : {}),
-                    });
-                }
-                catch (err) {
-                    // Rollback in reverse order
-                    if (newInstanceName && this.daemons.has(newInstanceName)) {
-                        await this.stopInstance(newInstanceName).catch(() => { });
-                    }
-                    if (newInstanceName && this.fleetConfig?.instances[newInstanceName]) {
-                        delete this.fleetConfig.instances[newInstanceName];
-                        if (createdTopicId)
-                            this.routingTable.delete(createdTopicId);
-                        this.saveFleetConfig();
-                    }
-                    if (createdTopicId) {
-                        await this.deleteForumTopic(createdTopicId);
-                    }
-                    // Rollback worktree
-                    if (worktreePath) {
-                        try {
-                            const { execFile: execFileCb } = await import("node:child_process");
-                            const { promisify } = await import("node:util");
-                            const execFileAsync = promisify(execFileCb);
-                            await execFileAsync("git", ["worktree", "remove", "--force", worktreePath], { cwd: directory });
-                        }
-                        catch { /* best-effort worktree cleanup */ }
-                    }
-                    respond(null, `Failed to create instance: ${err.message}`);
-                }
-                break;
-            }
-            case "delete_instance": {
-                const instanceName = args.name;
-                const deleteTopic = args.delete_topic ?? false;
-                const instanceConfig = this.fleetConfig?.instances[instanceName];
-                if (!instanceConfig) {
-                    respond(null, `Instance not found: ${instanceName}`);
-                    break;
-                }
-                if (instanceConfig.general_topic) {
-                    respond(null, "Cannot delete the General instance");
-                    break;
-                }
-                // Delete Telegram topic if requested (before removeInstance clears config)
-                if (deleteTopic && instanceConfig.topic_id) {
-                    await this.deleteForumTopic(instanceConfig.topic_id);
-                }
-                await this.removeInstance(instanceName);
-                respond({ success: true, name: instanceName, topic_deleted: deleteTopic });
-                break;
-            }
-            default:
-                respond(null, `Unknown tool: ${tool}`);
+        // Dispatch fleet-specific tools via handler map
+        const handler = outboundHandlers.get(tool);
+        if (handler) {
+            await handler(this, args, respond, { instanceName, requestId, fleetRequestId, senderSessionName });
+        }
+        else {
+            respond(null, `Unknown tool: ${tool}`);
         }
     }
     /** Handle tool status update from a daemon instance */
@@ -1021,14 +616,14 @@ export class FleetManager {
             this.adapter.sendText(chatId, text, { threadId }).then((sent) => {
                 const ipc = this.instanceIpcClients.get(instanceName);
                 ipc?.send({ type: "fleet_tool_status_ack", messageId: sent.messageId });
-            }).catch(e => this.logger.debug({ err: e }, "Failed to send tool status message"));
+            }).catch(e => this.logger.warn({ err: e }, "Failed to send tool status message"));
         }
     }
     // ===================== Scheduler =====================
     async handleScheduleTrigger(schedule) {
         const { target, reply_chat_id, reply_thread_id, message, label, id, source } = schedule;
         const RATE_LIMIT_DEFER_THRESHOLD = 85;
-        const rl = this.instanceRateLimits.get(target);
+        const rl = this.statuslineWatcher.getRateLimits(target);
         if (rl && rl.five_hour_pct > RATE_LIMIT_DEFER_THRESHOLD) {
             this.scheduler.recordRun(id, "deferred", `5hr rate limit at ${rl.five_hour_pct}%`);
             this.eventLog?.insert(target, "schedule_deferred", {
@@ -1141,18 +736,9 @@ export class FleetManager {
     }
     async deleteForumTopic(topicId) {
         try {
-            const groupId = this.fleetConfig?.channel?.group_id;
-            const botTokenEnv = this.fleetConfig?.channel?.bot_token_env;
-            if (!groupId || !botTokenEnv)
+            if (!this.adapter?.deleteTopic)
                 return;
-            const botToken = process.env[botTokenEnv];
-            if (!botToken)
-                return;
-            await fetch(`https://api.telegram.org/bot${botToken}/deleteForumTopic`, {
-                method: "POST",
-                headers: { "Content-Type": "application/json" },
-                body: JSON.stringify({ chat_id: groupId, message_thread_id: topicId }),
-            });
+            await this.adapter.deleteTopic(topicId);
         }
         catch (err) {
             this.logger.warn({ err, topicId }, "Failed to delete forum topic during rollback");
@@ -1165,7 +751,7 @@ export class FleetManager {
         this.topicCleanupTimer = setInterval(async () => {
             if (!this.fleetConfig?.channel?.group_id || !this.adapter?.topicExists)
                 return;
-            for (const [threadId, target] of this.routingTable) {
+            for (const [threadId, target] of this.routing.entries()) {
                 try {
                     if (!isProbeableRouteTarget(target)) {
                         continue;
@@ -1229,85 +815,18 @@ export class FleetManager {
         this.logger.info({ path: this.configPath }, "Saved fleet config");
     }
     async removeInstance(name) {
+        // Clean up schedules (scheduler is fleet-level, not lifecycle-level)
         const config = this.fleetConfig?.instances[name];
-        if (!config)
-            return;
-        // Never remove the General instance
-        if (config.general_topic) {
-            this.logger.warn({ name }, "Refusing to remove General instance");
-            return;
-        }
-        // Clean up schedules
-        if (this.scheduler && config.topic_id) {
+        if (this.scheduler && config?.topic_id) {
             const count = this.scheduler.deleteByInstanceOrThread(name, String(config.topic_id));
             if (count > 0) {
                 this.logger.info({ name, count }, "Cleaned up schedules for deleted instance");
             }
         }
-        // Stop daemon if running
-        if (this.daemons.has(name)) {
-            await this.stopInstance(name);
-        }
-        // Clean up git worktree if applicable
-        if (config.worktree_source && config.working_directory) {
-            const { existsSync } = await import("node:fs");
-            if (!existsSync(config.working_directory)) {
-                this.logger.info({ worktree: config.working_directory }, "Worktree directory already gone, skipping removal");
-            }
-            else {
-                try {
-                    const { execFile: execFileCb } = await import("node:child_process");
-                    const { promisify } = await import("node:util");
-                    const execFileAsync = promisify(execFileCb);
-                    await execFileAsync("git", ["worktree", "remove", "--force", config.working_directory], {
-                        cwd: config.worktree_source,
-                    });
-                    this.logger.info({ worktree: config.working_directory }, "Removed git worktree");
-                }
-                catch (err) {
-                    this.logger.warn({ err, worktree: config.working_directory }, "Failed to remove git worktree");
-                }
-            }
-        }
-        // Clean up IPC
-        const ipc = this.instanceIpcClients.get(name);
-        if (ipc) {
-            await ipc.close();
-            this.instanceIpcClients.delete(name);
-        }
-        // Remove from routing table
-        if (config.topic_id) {
-            this.routingTable.delete(config.topic_id);
-        }
-        // Remove from fleet config and save
-        delete this.fleetConfig.instances[name];
-        this.saveFleetConfig();
-        this.logger.info({ name }, "Instance removed");
+        return this.lifecycle.remove(name);
     }
     startStatuslineWatcher(name) {
-        const statusFile = join(this.getInstanceDir(name), "statusline.json");
-        const timer = setInterval(() => {
-            try {
-                const data = JSON.parse(readFileSync(statusFile, "utf-8"));
-                this.costGuard?.updateCost(name, data.cost?.total_cost_usd ?? 0);
-                const rl = data.rate_limits;
-                if (rl) {
-                    const prev = this.instanceRateLimits.get(name);
-                    const newSevenDay = rl.seven_day?.used_percentage ?? 0;
-                    if (prev?.seven_day_pct === 100 && newSevenDay < 100) {
-                        this.notifyInstanceTopic(name, `✅ ${name} weekly usage limit has reset — instance is available again.`);
-                        this.logger.info({ name }, "Weekly rate limit recovered");
-                    }
-                    this.instanceRateLimits.set(name, {
-                        five_hour_pct: rl.five_hour?.used_percentage ?? 0,
-                        seven_day_pct: newSevenDay,
-                    });
-                    this.checkModelFailover(name, rl.five_hour?.used_percentage ?? 0);
-                }
-            }
-            catch { /* file may not exist yet or be mid-write */ }
-        }, 10_000);
-        this.statuslineWatchers.set(name, timer);
+        this.statuslineWatcher.watch(name);
     }
     // ── Model failover ──────────────────────────────────────────────────────
     static FAILOVER_TRIGGER_PCT = 90;
@@ -1388,7 +907,7 @@ export class FleetManager {
             const stickers = await this.adapter.getTopicIconStickers();
             if (stickers.length === 0)
                 return;
-            // Telegram's getForumTopicIconStickers returns a fixed set.
+            // getForumTopicIconStickers returns a fixed set of available icons.
             // Try to match by emoji character, fall back to positional.
             const find = (targets) => stickers.find((s) => targets.some((t) => s.emoji.includes(t)));
             const green = find(["🟢", "✅", "💚"]);
@@ -1421,53 +940,9 @@ export class FleetManager {
         this.lastActivity.set(instanceName, Date.now());
     }
     /** Start periodic idle archive checker */
-    startArchivePoller() {
-        this.archiveTimer = setInterval(() => {
-            this.archiveIdleTopics().catch((err) => this.logger.debug({ err }, "Archive idle check failed"));
-        }, 30 * 60_000); // check every 30 minutes
-    }
-    /** Close topics that have been idle beyond threshold */
-    async archiveIdleTopics() {
-        if (!this.adapter?.closeForumTopic || !this.fleetConfig)
-            return;
-        const now = Date.now();
-        for (const [name, config] of Object.entries(this.fleetConfig.instances)) {
-            const topicId = config.topic_id;
-            if (topicId == null || config.general_topic)
-                continue;
-            if (this.archivedTopics.has(topicId))
-                continue;
-            const status = this.getInstanceStatus(name);
-            if (status !== "running")
-                continue; // only archive running-but-idle
-            const last = this.lastActivity.get(name) ?? 0;
-            if (last === 0)
-                continue; // never active → skip (just started)
-            if (now - last < FleetManager.ARCHIVE_IDLE_MS)
-                continue;
-            this.logger.info({ name, topicId, idleHours: Math.round((now - last) / 3600000) }, "Archiving idle topic");
-            this.archivedTopics.add(topicId);
-            this.setTopicIcon(name, "remove");
-            await this.adapter.closeForumTopic(topicId);
-        }
-    }
-    /** Reopen an archived topic and restore icon */
-    async reopenArchivedTopic(topicId, instanceName) {
-        if (!this.archivedTopics.has(topicId))
-            return;
-        this.archivedTopics.delete(topicId);
-        if (this.adapter?.reopenForumTopic) {
-            await this.adapter.reopenForumTopic(topicId);
-        }
-        this.setTopicIcon(instanceName, "green");
-        this.touchActivity(instanceName);
-        this.logger.info({ instanceName, topicId }, "Reopened archived topic");
-    }
+    // archiveIdleTopics / reopenArchivedTopic → delegated to TopicArchiver
     clearStatuslineWatchers() {
-        for (const [, timer] of this.statuslineWatchers)
-            clearInterval(timer);
-        this.statuslineWatchers.clear();
-        this.instanceRateLimits.clear();
+        this.statuslineWatcher.stopAll();
         this.failoverActive.clear();
     }
     async stopAll() {
@@ -1482,10 +957,7 @@ export class FleetManager {
             clearInterval(this.sessionPruneTimer);
             this.sessionPruneTimer = null;
         }
-        if (this.archiveTimer) {
-            clearInterval(this.archiveTimer);
-            this.archiveTimer = null;
-        }
+        this.topicArchiver.stop();
         this.scheduler?.shutdown();
         await Promise.allSettled([...this.daemons.entries()].map(async ([name, daemon]) => {
             try {
@@ -1661,7 +1133,7 @@ export class FleetManager {
             await this.startInstance(name, config, topicMode);
         }
         if (topicMode) {
-            this.routingTable = this.buildRoutingTable();
+            this.routing.rebuild(this.fleetConfig);
             await new Promise(r => setTimeout(r, 3000));
             await this.connectToInstances(fleet);
             for (const name of Object.keys(fleet.instances)) {
@@ -1677,7 +1149,7 @@ export class FleetManager {
             this.logger.info({ count: instances.length }, "Sending restart notification to instances");
             for (const [name, config] of instances) {
                 const threadId = config.topic_id != null ? String(config.topic_id) : undefined;
-                // Send to Telegram topic so the message appears in the chat
+                // Send to topic so the message appears in the instance's channel
                 if (threadId) {
                     this.adapter.sendText(String(groupId), "Fleet restart complete. Continue from where you left off.", { threadId })
                         .catch(e => this.logger.warn({ err: e, name, threadId }, "Failed to post per-instance restart notification"));