alvin-bot 4.6.0 → 4.7.0

package/dist/services/subagent-stats.js

@@ -0,0 +1,123 @@
+/**
+ * Sub-Agent Stats (H3) — rolling 24h aggregation of per-agent run data.
+ *
+ * Append-only JSON ring buffer persisted to ~/.alvin-bot/subagent-stats.json.
+ * On load, entries older than 24h are pruned. On each append, entries older
+ * than 24h are pruned.
+ *
+ * Used by /subagents stats to show run totals per source (user, cron, implicit)
+ * over the last 24 hours. No SQLite dependency — when a real SQLite migration
+ * lands we can swap the backend without touching the consumer API.
+ */
+import os from "os";
+import fs from "fs";
+import { resolve, dirname } from "path";
+const DATA_DIR = process.env.ALVIN_DATA_DIR || resolve(os.homedir(), ".alvin-bot");
+const STATS_FILE = resolve(DATA_DIR, "subagent-stats.json");
+const WINDOW_MS = 24 * 60 * 60 * 1000; // 24 hours
+const MAX_ENTRIES = 5000; // hard cap to prevent unbounded growth on high-frequency bots
+let cache = null;
+function load() {
+    if (cache)
+        return cache;
+    try {
+        const raw = fs.readFileSync(STATS_FILE, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed)) {
+            cache = [];
+            return cache;
+        }
+        // Prune stale entries (> 24h old) on load
+        const cutoff = Date.now() - WINDOW_MS;
+        cache = parsed.filter((e) => typeof e === "object" &&
+            e !== null &&
+            typeof e.completedAt === "number" &&
+            e.completedAt >= cutoff);
+        return cache;
+    }
+    catch {
+        cache = [];
+        return cache;
+    }
+}
+function save(entries) {
+    try {
+        fs.mkdirSync(dirname(STATS_FILE), { recursive: true });
+        fs.writeFileSync(STATS_FILE, JSON.stringify(entries, null, 0), "utf-8");
+    }
+    catch (err) {
+        console.error("[subagent-stats] failed to write:", err);
+    }
+}
+/**
+ * Record a completed sub-agent run. Called from runSubAgent.finally() via
+ * a side-effect hook. Automatically prunes entries older than 24h and
+ * keeps the file bounded at MAX_ENTRIES.
+ */
+export function recordSubAgentRun(info, result) {
+    const entries = load();
+    const cutoff = Date.now() - WINDOW_MS;
+    // Prune in-place
+    const pruned = entries.filter((e) => e.completedAt >= cutoff);
+    const newEntry = {
+        completedAt: Date.now(),
+        name: info.name,
+        source: (info.source ?? "implicit"),
+        status: result.status,
+        durationMs: result.duration,
+        inputTokens: result.tokensUsed.input,
+        outputTokens: result.tokensUsed.output,
+    };
+    pruned.push(newEntry);
+    // Enforce hard cap — oldest entries drop first
+    const final = pruned.length > MAX_ENTRIES ? pruned.slice(-MAX_ENTRIES) : pruned;
+    cache = final;
+    save(final);
+}
+/**
+ * Compute a summary of the last 24h of sub-agent runs. Safe to call
+ * concurrently with recordSubAgentRun — both read from the same cache.
+ */
+export function getSubAgentStats() {
+    const entries = load();
+    const cutoff = Date.now() - WINDOW_MS;
+    const recent = entries.filter((e) => e.completedAt >= cutoff);
+    const empty = () => ({
+        runs: 0,
+        inputTokens: 0,
+        outputTokens: 0,
+        totalDurationMs: 0,
+    });
+    const bySource = {
+        user: empty(),
+        cron: empty(),
+        implicit: empty(),
+    };
+    const byStatus = {
+        completed: 0,
+        timeout: 0,
+        error: 0,
+        cancelled: 0,
+    };
+    const total = empty();
+    for (const e of recent) {
+        const bucket = bySource[e.source] ?? bySource.implicit;
+        bucket.runs += 1;
+        bucket.inputTokens += e.inputTokens;
+        bucket.outputTokens += e.outputTokens;
+        bucket.totalDurationMs += e.durationMs;
+        total.runs += 1;
+        total.inputTokens += e.inputTokens;
+        total.outputTokens += e.outputTokens;
+        total.totalDurationMs += e.durationMs;
+        byStatus[e.status] = (byStatus[e.status] ?? 0) + 1;
+    }
+    return { windowHours: 24, total, bySource, byStatus };
+}
+/**
+ * Reset the in-memory cache — for test isolation. Does NOT delete the
+ * file; use ALVIN_DATA_DIR in tests to point at a fresh temp dir.
+ */
+export function __resetStatsCacheForTest() {
+    cache = null;
+}

package/dist/services/subagents.js

@@ -15,9 +15,11 @@ const DATA_DIR = process.env.ALVIN_DATA_DIR || resolve(os.homedir(), ".alvin-bot
 const CONFIG_FILE = resolve(DATA_DIR, "sub-agents.json");
 const ABSOLUTE_MAX_AGENTS = 16; // Hard cap no matter what
 const MAX_SUBAGENT_DEPTH = 2; // F2: hard cap on nested spawning
+const DEFAULT_QUEUE_CAP = 20; // D3: default bounded-queue size
+const ABSOLUTE_MAX_QUEUE = 200; // D3: absolute ceiling on queue length
 let configCache = null;
 function isValidVisibility(v) {
-    return v === "auto" || v === "banner" || v === "silent";
+    return v === "auto" || v === "banner" || v === "silent" || v === "live";
 }
 function loadSubAgentsConfig() {
     if (configCache)
@@ -28,6 +30,9 @@ function loadSubAgentsConfig() {
         configCache = {
             maxParallel: typeof parsed.maxParallel === "number" ? parsed.maxParallel : 0,
             visibility: isValidVisibility(parsed.visibility) ? parsed.visibility : "auto",
+            queueCap: typeof parsed.queueCap === "number"
+                ? Math.max(0, Math.min(Math.floor(parsed.queueCap), ABSOLUTE_MAX_QUEUE))
+                : DEFAULT_QUEUE_CAP,
         };
     }
     catch {
@@ -35,6 +40,7 @@ function loadSubAgentsConfig() {
         configCache = {
             maxParallel: Number(process.env.MAX_SUBAGENTS) || 0,
             visibility: "auto",
+            queueCap: DEFAULT_QUEUE_CAP,
         };
     }
     return configCache;
@@ -79,11 +85,23 @@ export function getVisibility() {
  */
 export function setVisibility(mode) {
     if (!isValidVisibility(mode)) {
-        throw new Error(`Invalid visibility mode "${mode}". Expected: auto | banner | silent.`);
+        throw new Error(`Invalid visibility mode "${mode}". Expected: auto | banner | silent | live.`);
     }
     const cfg = loadSubAgentsConfig();
     saveSubAgentsConfig({ ...cfg, visibility: mode });
 }
+/** D3: Current bounded-queue cap. 0 = queue disabled (reject on full pool). */
+export function getQueueCap() {
+    return loadSubAgentsConfig().queueCap;
+}
+/** D3: Set the queue cap. Clamped to [0, ABSOLUTE_MAX_QUEUE].
+ *  Returns the effective value after clamping. */
+export function setQueueCap(n) {
+    const clamped = Math.max(0, Math.min(Math.floor(n), ABSOLUTE_MAX_QUEUE));
+    const cfg = loadSubAgentsConfig();
+    saveSubAgentsConfig({ ...cfg, queueCap: clamped });
+    return clamped;
+}
 // ── State ───────────────────────────────────────────────
 const activeAgents = new Map();
 // ── Name resolver (B2) ──────────────────────────────────
@@ -167,6 +185,28 @@ export function findSubAgentByName(name, opts = {}) {
 async function runSubAgent(id, agentConfig, abort, resolvedName) {
     const startTime = Date.now();
     const entry = activeAgents.get(id);
+    // A4 live-stream state — set up if the effective visibility is "live"
+    // AND this is a user spawn with a parent chat. Cron and implicit spawns
+    // don't get live-streaming (cron because there's no interactive watcher,
+    // implicit because the parent Claude stream already shows everything).
+    let liveStream = null;
+    const effectiveVisibility = agentConfig.visibility ?? loadSubAgentsConfig().visibility;
+    if (effectiveVisibility === "live" &&
+        agentConfig.source === "user" &&
+        typeof agentConfig.parentChatId === "number") {
+        try {
+            const { createLiveStream } = await import("./subagent-delivery.js");
+            const stream = createLiveStream(agentConfig.parentChatId, resolvedName);
+            if (stream) {
+                await stream.start();
+                if (!stream.failed)
+                    liveStream = stream;
+            }
+        }
+        catch (err) {
+            console.error(`[subagent ${id}] live-stream init failed:`, err);
+        }
+    }
     try {
         const { getRegistry } = await import("../engine.js");
         const registry = getRegistry();
@@ -189,8 +229,13 @@ async function runSubAgent(id, agentConfig, abort, resolvedName) {
             effort: "high",
             abortSignal: abort.signal,
         })) {
-            if (chunk.type === "text")
+            if (chunk.type === "text") {
                 finalText = chunk.text || "";
+                // A4: push text updates into the throttled live-stream
+                if (liveStream && !liveStream.failed) {
+                    liveStream.update(finalText);
+                }
+            }
             if (chunk.type === "done") {
                 inputTokens = chunk.inputTokens || 0;
                 outputTokens = chunk.outputTokens || 0;
@@ -227,6 +272,20 @@ async function runSubAgent(id, agentConfig, abort, resolvedName) {
             };
             entry.info.status = "completed";
         }
+        // A4: finalize the live-stream if we had one. On success, mark the
+        // entry as delivered so spawnSubAgent.finally() skips the normal
+        // deliverSubAgentResult path — the live stream already posted the
+        // body, and finalize() already posted the banner.
+        if (liveStream && !liveStream.failed && entry.result) {
+            try {
+                await liveStream.finalize(entry.info, entry.result);
+                entry.delivered = true;
+            }
+            catch (err) {
+                console.error(`[subagent ${id}] live-stream finalize failed:`, err);
+                // Let the normal delivery path fire as a fallback.
+            }
+        }
     }
     catch (err) {
         const isAbort = err instanceof Error && err.message.includes("abort");
@@ -248,109 +307,179 @@ async function runSubAgent(id, agentConfig, abort, resolvedName) {
         entry.info.status = status;
     }
 }
-// ── Public API ──────────────────────────────────────────
+const pendingQueue = [];
+/** Priority order used when draining the queue — higher index = lower priority. */
+const SOURCE_PRIORITY = ["user", "cron", "implicit"];
+function sourceOf(cfg) {
+    return cfg.source ?? "implicit";
+}
+/** Count how many agents are currently running. */
+function runningCount() {
+    return [...activeAgents.values()].filter((a) => a.info.status === "running").length;
+}
+/**
+ * Pop the next queued spawn according to priority (user > cron > implicit)
+ * and within each priority in FIFO order. Returns null if the queue is empty.
+ */
+function popHighestPriorityQueued() {
+    for (const priority of SOURCE_PRIORITY) {
+        const idx = pendingQueue.findIndex((q) => sourceOf(q.agentConfig) === priority);
+        if (idx >= 0) {
+            const [entry] = pendingQueue.splice(idx, 1);
+            return entry;
+        }
+    }
+    return null;
+}
 /**
- * Spawn an isolated sub-agent that runs in the background.
- * Returns the agent ID immediately (does NOT await completion).
+ * Recalculate queuePosition for every entry still in the queue. Called
+ * after a pop or a cancel so /subagents list reflects the current state.
  */
+function reindexQueue() {
+    for (let i = 0; i < pendingQueue.length; i++) {
+        const q = pendingQueue[i];
+        const entry = activeAgents.get(q.id);
+        if (entry)
+            entry.info.queuePosition = i + 1;
+    }
+}
+/** Drain as many queued spawns as fit into the current free slots. */
+function drainQueue() {
+    const maxParallel = getMaxParallelAgents();
+    while (pendingQueue.length > 0 && runningCount() < maxParallel) {
+        const next = popHighestPriorityQueued();
+        if (!next)
+            break;
+        const entry = activeAgents.get(next.id);
+        if (!entry)
+            continue; // was cancelled while queued
+        reindexQueue();
+        // Transition to running
+        entry.info.status = "running";
+        entry.info.startedAt = Date.now();
+        entry.info.queuePosition = undefined;
+        startRun(next);
+    }
+}
+// ── Spawn pipeline ──────────────────────────────────────────
+function startRun(q) {
+    const { id, resolvedName, agentConfig, timeoutId } = q;
+    const entry = activeAgents.get(id);
+    if (!entry)
+        return;
+    // Run in background — don't await
+    runSubAgent(id, agentConfig, entry.abort, resolvedName)
+        .finally(() => {
+        if (timeoutId)
+            clearTimeout(timeoutId);
+        const currentEntry = activeAgents.get(id);
+        if (agentConfig.onComplete && currentEntry?.result) {
+            try {
+                agentConfig.onComplete(currentEntry.result);
+            }
+            catch (err) {
+                console.error(`[subagent ${id}] onComplete callback threw:`, err);
+            }
+        }
+        // I3: fire delivery router (non-blocking, errors logged). Guarded
+        // by the `delivered` flag.
+        if (currentEntry?.result && !currentEntry.delivered) {
+            currentEntry.delivered = true;
+            const resultSnapshot = currentEntry.result;
+            const infoSnapshot = currentEntry.info;
+            import("./subagent-delivery.js")
+                .then(({ deliverSubAgentResult }) => deliverSubAgentResult(infoSnapshot, resultSnapshot, {
+                visibility: agentConfig.visibility,
+            }))
+                .catch((err) => console.error(`[subagent ${id}] delivery failed:`, err));
+        }
+        // H3: record this run in the rolling 24h stats (non-blocking).
+        if (currentEntry?.result) {
+            const resultSnapshot = currentEntry.result;
+            const infoSnapshot = currentEntry.info;
+            import("./subagent-stats.js")
+                .then(({ recordSubAgentRun }) => recordSubAgentRun(infoSnapshot, resultSnapshot))
+                .catch((err) => console.error(`[subagent ${id}] stats recording failed:`, err));
+        }
+        // D3: drain the queue now that a slot has freed up
+        drainQueue();
+        // Auto-cleanup: remove completed agents after 30 minutes
+        setTimeout(() => {
+            const e = activeAgents.get(id);
+            if (e && e.info.status !== "running" && e.info.status !== "queued") {
+                activeAgents.delete(id);
+            }
+        }, 30 * 60 * 1000);
+    });
+}
 export function spawnSubAgent(agentConfig) {
     // F2: enforce depth cap before touching any state.
     const depth = agentConfig.depth ?? 0;
     if (depth > MAX_SUBAGENT_DEPTH) {
         return Promise.reject(new Error(`Sub-agent depth limit reached (${MAX_SUBAGENT_DEPTH}). Agents can only spawn ${MAX_SUBAGENT_DEPTH} level(s) of nested agents.`));
     }
-    // G1: toolset preset. Only "full" is supported in Stufe 1. The literal
-    // type blocks wrong values at compile time; the runtime check catches
-    // callers that bypass TypeScript (e.g. plugin code loaded at runtime).
+    // G1: toolset preset. Only "full" is supported. The literal type blocks
+    // wrong values at compile time; the runtime check catches callers that
+    // bypass TypeScript (e.g. plugin code loaded at runtime).
     const toolset = agentConfig.toolset ?? "full";
     if (toolset !== "full") {
         return Promise.reject(new Error(`Invalid toolset "${toolset}". Only "full" is supported in this version.`));
     }
-    // Check concurrency limit — now reads from the file-backed config so
-    // /sub-agents max <n> edits take effect immediately without a restart.
-    const running = [...activeAgents.values()].filter((a) => a.info.status === "running");
     const maxParallel = getMaxParallelAgents();
-    if (running.length >= maxParallel) {
-        // D4: priority-aware reject messages — give callers context about
-        // WHO is holding the slots so they know whether to wait, cancel,
-        // or give up.
-        const source = agentConfig.source ?? "implicit";
-        const userSlots = running.filter((a) => a.info.source === "user").length;
-        const bgSlots = running.length - userSlots;
+    const queueCap = getQueueCap();
+    const running = runningCount();
+    const queuedLen = pendingQueue.length;
+    // B2: resolve the requested name to a unique variant.
+    const resolved = resolveAgentName(agentConfig.name);
+    const resolvedName = resolved.name;
+    const id = crypto.randomUUID();
+    const timeout = agentConfig.timeout ?? config.subAgentTimeout;
+    const abort = new AbortController();
+    const timeoutId = setTimeout(() => abort.abort(), timeout);
+    const willRunImmediately = running < maxParallel;
+    const canQueue = !willRunImmediately && queueCap > 0 && queuedLen < queueCap;
+    if (!willRunImmediately && !canQueue) {
+        // No slot, no queue room → priority-aware reject
+        clearTimeout(timeoutId);
+        const source = sourceOf(agentConfig);
+        const runningAgents = [...activeAgents.values()].filter((a) => a.info.status === "running");
+        const userSlots = runningAgents.filter((a) => a.info.source === "user").length;
+        const bgSlots = runningAgents.length - userSlots;
         let message;
         if (source === "user") {
             if (bgSlots > 0) {
-                message = `Alle Slots belegt (${running.length}/${maxParallel}), davon ${bgSlots} cron/implicit im Hintergrund. /sub-agents list für Details oder /sub-agents cancel <name>.`;
+                message = `Alle Slots belegt (${running}/${maxParallel}), davon ${bgSlots} cron/implicit im Hintergrund. Queue voll (${queuedLen}/${queueCap}). /subagents list für Details oder /subagents cancel <name>.`;
             }
             else {
-                message = `Alle Slots belegt (${running.length}/${maxParallel}) mit eigenen user-Spawns. /sub-agents cancel <name> oder warten: /sub-agents list`;
+                message = `Alle Slots belegt (${running}/${maxParallel}) mit eigenen user-Spawns. Queue voll (${queuedLen}/${queueCap}). /subagents cancel <name> oder warten.`;
             }
         }
         else {
-            message = `Sub-agent limit reached (${maxParallel}). Wait for a running agent to finish or cancel one.`;
+            message = `Sub-agent limit reached (${maxParallel} running, ${queuedLen}/${queueCap} queued). Wait for a running agent to finish or cancel one.`;
         }
         return Promise.reject(new Error(message));
     }
-    // B2: resolve the requested name to a unique variant. On collision,
-    // append #N where N is the smallest free index ≥ 2.
-    const resolved = resolveAgentName(agentConfig.name);
-    const resolvedName = resolved.name;
-    const id = crypto.randomUUID();
-    const timeout = agentConfig.timeout ?? config.subAgentTimeout;
-    const abort = new AbortController();
-    // Set up timeout
-    const timeoutId = setTimeout(() => abort.abort(), timeout);
     const info = {
         id,
         name: resolvedName,
-        status: "running",
+        status: willRunImmediately ? "running" : "queued",
         startedAt: Date.now(),
         model: agentConfig.model,
         source: agentConfig.source,
         depth,
         parentChatId: agentConfig.parentChatId,
         nameIndex: resolved.index,
+        queuePosition: willRunImmediately ? undefined : queuedLen + 1,
     };
     activeAgents.set(id, { info, abort, delivered: false });
-    // Run in background — don't await
-    runSubAgent(id, agentConfig, abort, resolvedName)
-        .finally(() => {
-        clearTimeout(timeoutId);
-        // Call the onComplete callback if the caller provided one. This is
-        // how cron.ts turns the fire-and-forget spawnSubAgent() into a
-        // Promise that resolves when the work finishes. The callback runs
-        // inside a try/catch so a throwing callback can't break cleanup.
-        const entry = activeAgents.get(id);
-        if (agentConfig.onComplete && entry?.result) {
-            try {
-                agentConfig.onComplete(entry.result);
-            }
-            catch (err) {
-                console.error(`[subagent ${id}] onComplete callback threw:`, err);
-            }
-        }
-        // I3: fire delivery router (non-blocking, errors logged). Dynamic
-        // import keeps the module graph free of circular edges. Guarded by
-        // the `delivered` flag so cancelAllSubAgents (shutdown path) and
-        // this finally() can't both post the result.
-        if (entry?.result && !entry.delivered) {
-            entry.delivered = true;
-            const resultSnapshot = entry.result;
-            const infoSnapshot = entry.info;
-            import("./subagent-delivery.js")
-                .then(({ deliverSubAgentResult }) => deliverSubAgentResult(infoSnapshot, resultSnapshot, {
-                visibility: agentConfig.visibility,
-            }))
-                .catch((err) => console.error(`[subagent ${id}] delivery failed:`, err));
-        }
-        // Auto-cleanup: remove completed agents after 30 minutes
-        setTimeout(() => {
-            const e = activeAgents.get(id);
-            if (e && e.info.status !== "running") {
-                activeAgents.delete(id);
-            }
-        }, 30 * 60 * 1000);
-    });
+    const queuedSpawn = { id, resolvedName, agentConfig, depth, timeoutId };
+    if (willRunImmediately) {
+        startRun(queuedSpawn);
+    }
+    else {
+        pendingQueue.push(queuedSpawn);
+        reindexQueue();
+    }
     return Promise.resolve(id);
 }
 /**
@@ -365,7 +494,21 @@ export function listSubAgents() {
  */
 export function cancelSubAgent(id) {
     const entry = activeAgents.get(id);
-    if (!entry || entry.info.status !== "running")
+    if (!entry)
+        return false;
+    if (entry.info.status === "queued") {
+        // D3: remove from the pending queue, reindex, mark cancelled.
+        const idx = pendingQueue.findIndex((q) => q.id === id);
+        if (idx >= 0) {
+            const [removed] = pendingQueue.splice(idx, 1);
+            if (removed.timeoutId)
+                clearTimeout(removed.timeoutId);
+            reindexQueue();
+        }
+        entry.info.status = "cancelled";
+        return true;
+    }
+    if (entry.info.status !== "running")
         return false;
     entry.abort.abort();
     entry.info.status = "cancelled";
@@ -418,6 +561,16 @@ export async function cancelAllSubAgents(notify = true) {
     // delivered=true so runSubAgent.finally() can't fire a second
     // delivery on the next microtask, (4) queue the I3 delivery.
     const runningEntries = [];
+    // D3: clear the pending queue first so no entry starts during shutdown.
+    for (const q of pendingQueue.splice(0)) {
+        if (q.timeoutId)
+            clearTimeout(q.timeoutId);
+        const entry = activeAgents.get(q.id);
+        if (entry) {
+            entry.info.status = "cancelled";
+            entry.delivered = true; // no delivery for queued-never-ran agents
+        }
+    }
     for (const [id, entry] of activeAgents) {
         if (entry.info.status !== "running")
             continue;

package/docs/HANDBOOK.md

@@ -310,6 +310,7 @@ This allows the "scatter-gather" pattern (main → orchestrator → 10 workers)
 - `auto` (default) — source-based routing: implicit stays in the parent stream, user and cron get a banner+final delivery.
 - `banner` — always send a banner+final, even for implicit spawns.
 - `silent` — never send. The result is still stored in the activeAgents map for 30 minutes and pullable via `/subagents result <name>`.
+- **`live`** — stream incremental updates into a single Telegram message as the agent thinks. Only applies to `source: "user"` spawns with a `parentChatId`. The live message is plain text (so half-formed markdown during streaming can't break the edit), updates are throttled to 800 ms between edits, and a separate banner message is posted at the end so you get a completion notification. If the bot API doesn't support `editMessageText` or the live setup fails, we fall through to `banner` mode automatically.
 
 ### 7.6 Inheritance
 
@@ -320,7 +321,29 @@ Sub-agents inherit from the spawning context:
 - **Model and tools** — inherited via the provider registry.
 - **Conversation history** — **not inherited.** Sub-agents receive only their own prompt. This forces clean, self-describing spawn requests.
 
-### 7.7 Shutdown notifications
+### 7.7 Bounded priority queue
+
+When the running pool hits `maxParallel`, new spawn requests land in a bounded queue instead of being rejected immediately.
+
+- **Default cap:** 20 slots. Configure via `/subagents queue <n>` (clamped to 0–200).
+- **Disable:** `/subagents queue 0` — restores the old reject-on-full behavior.
+- **Priority order on drain:** `user > cron > implicit`. Within each priority class, FIFO.
+- **`/subagents list`** shows queued entries with a `#N` suffix indicating their position.
+- **Cancel a queued entry** with `/subagents cancel <name>` — it's removed from the queue without ever starting.
+
+Reject is only triggered when the pool **and** the queue are both full. The reject message is priority-aware and names who's holding the slots.
+
+### 7.8 Stats
+
+`/subagents stats` shows a summary of the last 24 hours of sub-agent runs:
+
+- Total runs + total tokens + total wall time
+- Runs per source (user / cron / implicit)
+- Runs per status (completed / cancelled / timeout / error)
+
+The backing data is an append-only JSON ring buffer at `~/.alvin-bot/subagent-stats.json`. Entries older than 24 hours are pruned automatically. A hard cap of 5000 entries protects against runaway growth on very busy bots.
+
+### 7.9 Shutdown notifications
 
 When you restart the bot (SIGTERM), any still-running sub-agents get a cancellation delivery before the process exits:
 
@@ -433,7 +456,14 @@ All commands are triggered from any platform that supports commands (Telegram, D
 | Command | Purpose |
 |---|---|
 | `/cron` | Manage scheduled jobs |
-| `/subagents` | Manage sub-agents |
+| `/subagents` | Show sub-agent status |
+| `/subagents max <n>` | Set max parallel (0 = auto) |
+| `/subagents queue <n>` | Set bounded-queue cap (0 = disabled) |
+| `/subagents visibility <auto\|banner\|silent\|live>` | Delivery mode |
+| `/subagents list` | List all (queued + running + recent) |
+| `/subagents cancel <name\|id>` | Cancel one |
+| `/subagents result <name\|id>` | Show a completed result |
+| `/subagents stats` | Last 24h run stats (by source + status) |
 | `/webui` | Open web UI URL |
 | `/setup` | Re-run the setup wizard flow from chat |
 | `/restart` | Restart the bot process |
@@ -776,6 +806,13 @@ Alvin Bot follows semver for the **data directory format**. Minor version bumps
 - Memory: no schema change.
 - `.env`: no new required variables. `MAX_SUBAGENTS` and `SUBAGENT_TIMEOUT` are optional.
 
+### 16.3 From 4.6.x to 4.7.0
+
+- Sub-agents: new fields in `sub-agents.json` (`queueCap`, defaults to 20). Old files auto-upgrade.
+- New file `~/.alvin-bot/subagent-stats.json` — auto-created when the first sub-agent finishes.
+- `start`/`stop` now auto-detect the LaunchAgent on macOS. No migration needed; if you previously installed the LaunchAgent in 4.6.0, `alvin-bot start` now correctly reloads it instead of spawning a parallel pm2 process.
+- No new required `.env` variables.
+
 ### 16.3 From git
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alvin-bot",
-  "version": "4.6.0",
+  "version": "4.7.0",
   "description": "Alvin Bot — Your personal AI agent on Telegram, WhatsApp, Discord, Signal, and Web.",
   "type": "module",
   "main": "dist/index.js",