alvin-bot 5.6.1 → 5.7.0

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 All notable changes to Alvin Bot are documented here.
 
+## [5.7.0] — 2026-05-19
+
+### Background-task results now arrive the instant the task finishes, and survive a restart
+
+Detached background-task results were delivered by a 15-second polling
+loop whose in-memory state could diverge across a bot restart, so a task
+that finished around a restart could keep its result undelivered with
+nothing shown in chat. Delivery is now pushed the moment the task's
+process exits — through an always-on local callback guarded by a
+per-boot token — and a startup reconciliation pass drains anything that
+completed while the bot was down. An atomic deliver-once marker
+guarantees the push, the polling backstop, and reconciliation never
+double-deliver, and a cancelled task can no longer be resurrected. The
+polling loop is kept only as a backstop for timeouts and stalled tasks.
+No configuration is required and nothing changes for existing setups.
+
+## [5.6.2] — 2026-05-19
+
+### Long background-task results now reliably arrive in chat
+
+A background task that produced a long final answer could finish
+successfully and yet never be delivered — you would see nothing and
+have to ask for the status by hand. Alvin now recognises a finished
+background task no matter how long its result is, so the answer always
+lands in your chat the moment the task completes.
+
 ## [5.6.1] — 2026-05-18
 
 ### Background-task results stay in the chat

package/README.md

@@ -2,9 +2,9 @@
 
 > Your personal AI agent — on Telegram, WhatsApp, Discord, Slack, Signal, Terminal, and Web.
 
-Open-source, self-hosted, multi-model. Lives where you chat, has full shell + filesystem access, remembers across sessions, and dispatches detached sub-agents for long-running work. Built on the Claude Agent SDK with a provider-agnostic engine that also drives OpenAI, Groq, Gemini, NVIDIA NIM, OpenRouter, and Ollama.
+Alvin Bot is an open-source, MIT-licensed, self-hosted autonomous AI agent that runs on your own machine and answers you on Telegram, Slack, Discord, WhatsApp, Signal, a terminal TUI, and a web dashboard. It is built on the official Claude Agent SDK and runs a provider-agnostic engine that also drives OpenAI, Groq, Google Gemini, NVIDIA NIM, OpenRouter, and Ollama, with automatic failover after two consecutive provider failures and a heartbeat health check every five minutes. Unlike most personal AI agents, it ships a zero-config indexed memory store: with no embedding API key it falls back to a built-in SQLite FTS5 keyword index, so recall works out of the box. It dispatches detached sub-agents as independent `claude -p` subprocesses that keep running and deliver their result even if the parent conversation is aborted. It is local-first and telemetry-free — prompts and responses are never logged off-machine, secrets live in a chmod-0600 `.env`, and shell execution is allowlisted by default.
 
-> **What's new — v4.22 (May 2026):** Pluggable memory backends — Gemini · OpenAI · Ollama · **FTS5 keyword fallback (zero-config)**. Users without an embedding API key now get a working indexed memory store out of the box. Smart inject mode trims ~25 k tokens per turn off long system prompts. [Full changelog →](CHANGELOG.md)
+> **What's new — v5.6.2 (May 2026):** Background-task and scheduled-job results now land cleanly in chat — a tight header (what ran, duration, tokens, success) plus the answer, with very long output attached as a single file instead of a wall of messages. Built on v5.5's instant, honest ⛔ Stop and calmer, evidence-based health monitoring. Earlier in the 5.x line: a zero-config FTS5 keyword memory index (indexed recall with **no embedding API key**), automatic multi-provider failover with a 5-minute heartbeat monitor, and detached sub-agents that survive a parent abort. [Full changelog →](CHANGELOG.md)
 
 ---
 
@@ -47,6 +47,34 @@ Open-source, self-hosted, multi-model. Lives where you chat, has full shell + fi
 
 ---
 
+## ⚖️ How Alvin Bot compares
+
+Alvin Bot sits in the same category as **Hermes Agent** (Nous Research) and **OpenClaw** — self-hosted, open-source personal AI agents that live on your machine and reach you on the chat apps you already use. They optimize for different things. This table is intended to be fair: where Hermes or OpenClaw is the better tool, it says so.
+
+| Dimension | **Alvin Bot** | **Hermes Agent** | **OpenClaw** |
+|---|---|---|---|
+| License / hosting | MIT · self-hosted · local-first · zero telemetry | MIT · self-hosted · 7 execution backends | Open-source · self-hosted · bring-your-own-key |
+| Model providers | Claude Agent SDK + OpenAI · Groq · Gemini · NVIDIA NIM · OpenRouter · Ollama, with **automatic failover after 2 provider failures + a 5-min heartbeat monitor** | 200+ models | Bring-your-own model / key |
+| Sub-agents | **Detached `claude -p` subprocesses that survive a parent abort**; `readonly`/`research` toolset presets | Isolated subagents for parallel workstreams | Not a primary focus |
+| Browser automation | **4-tier escalation**: WebFetch → stealth Playwright → persistent-profile CDP → agent-browser CLI | Built-in browse / vision tools | Via tools |
+| Platforms | Telegram · Slack · Discord · WhatsApp · Signal · terminal TUI · Web (7) | 20+ platforms from one gateway | 25–50+ platforms · native mobile apps · voice activation |
+| Memory | Layered L0–L3; SQLite embeddings with a **zero-config FTS5 keyword fallback (works with no API key)**; smart prompt-injection trims ~25 k tokens/turn | SQLite + full-text search · agent-curated · Honcho user profiling | Transparent plain Markdown/YAML files you can grep and git-track |
+| Extensibility | Hot-reload skills + 6 plugins · self-modifying skills · hooks · MCP client | 40+ built-in tools · **autonomous self-improving skill loop** | Skills as files · very large ecosystem |
+| MCP | MCP **client** (connect any MCP server) | MCP client **and `hermes mcp serve`** (acts as an MCP server for Claude Desktop / Cursor / VS Code) | Tool integrations |
+| Self-healing | **Startup preflight · dead-man's-switch heartbeat · crash forensic bundles · AI self-diagnosis · crash-loop brake · trend anomaly detection** | Stable in practice; self-improving | Frequent updates can break running instances |
+| Security defaults | Exec **allowlist + shell-metachar filter on by default** · DM pairing · timing-safe webhook auth · 0600 file perms enforced · `alvin-bot audit` CLI · honestly documented threat model | Standard | Standard |
+| Maturity / community | Small, focused, single-maintainer; modest public adoption | Large community, Nous Research team | Large community + team, Nvidia NemoClaw fork |
+
+### Use the right tool for the job
+
+- **Use Alvin Bot when** you want one resilient, self-healing agent on your own box that keeps working when a provider rate-limits or fails, gives you indexed memory **without buying an embedding API key**, ships safe-by-default execution sandboxing, and is built directly on the official Claude Agent SDK — and you mainly live in Telegram / Slack / Discord / WhatsApp / Signal.
+- **Use Hermes Agent when** you want a research-grade self-improving agent, need it to act as an **MCP server** for Claude Desktop / Cursor / VS Code, want 200+ model choice or many execution backends, and value a large community.
+- **Use OpenClaw when** you want the **widest messaging reach** (25–50+ channels) plus native mobile apps and voice activation, fully transparent plain-file memory you can git-track, and the largest ecosystem.
+
+A longer head-to-head with FAQ and decision guide: **[Alvin Bot vs Hermes vs OpenClaw](https://alvin.alev-b.com/vs/hermes-openclaw)**.
+
+---
+
 ## 🚀 Quick Start
 
 ```bash

package/dist/services/alvin-dispatch.js

@@ -35,6 +35,40 @@ import { SUBAGENTS_DIR } from "../paths.js";
 function generateAgentId() {
     return "alvin-" + crypto.randomBytes(12).toString("hex");
 }
+/**
+ * v5.7.0 — Best-effort push: tell the bot a detached sub-agent just
+ * exited so it can read the jsonl and deliver immediately instead of
+ * waiting for the next 15s poll tick. An in-process self-call to the
+ * always-on loopback route. Any failure (bot mid-restart, port race,
+ * network) is swallowed — startup reconciliation and the poll backstop
+ * are the safety nets. Never throws, always resolves.
+ */
+export async function postSubagentExit(agentId, exitCode) {
+    try {
+        const { getWebPort, getInternalToken } = await import("../web/server.js");
+        const port = getWebPort();
+        const token = getInternalToken();
+        const ac = new AbortController();
+        const timer = setTimeout(() => ac.abort(), 4000);
+        try {
+            await fetch(`http://127.0.0.1:${port}/internal/subagent-exit`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    Authorization: `Bearer ${token}`,
+                },
+                body: JSON.stringify({ agentId, exitCode }),
+                signal: ac.signal,
+            });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    catch {
+        /* best-effort — reconciliation/poll backstop cover any miss */
+    }
+}
 /**
  * Dispatch a detached sub-agent. Returns synchronously — the subprocess
  * runs in the background. Throws if spawn fails. On success:
@@ -96,6 +130,16 @@ export function dispatchDetachedAgent(input) {
     catch {
         /* ignore */
     }
+    // v5.7.0 — Push: deliver the result the instant the subprocess exits,
+    // instead of waiting for the next 15s poll tick. `exit` fires after
+    // the OS has reaped the process and flushed its inherited stdout FD,
+    // so the terminating result line is fully on disk before the handler
+    // reads it (race-safe). Best-effort: startup reconciliation + the poll
+    // backstop cover a missed push (bot restarted mid-run, port race).
+    // Attached before unref() so the listener is registered on the handle.
+    child.on("exit", (code) => {
+        void postSubagentExit(agentId, code);
+    });
     // Detach from parent Node's event loop so parent exit doesn't wait.
     child.unref();
     // Register with watcher so it polls the output file and delivers.

package/dist/services/async-agent-parser.js

@@ -68,6 +68,92 @@ export function parseAsyncLaunchedToolResult(raw) {
     return { agentId, outputFile };
 }
 const DEFAULT_TAIL_BYTES = 64 * 1024;
+/**
+ * Upper bound for the window-independent final-line read (see
+ * readLastCompleteLine). Generous — ~128× the tail window — so any
+ * realistic final report is captured, but bounded so a pathological
+ * single line can't blow up memory. Beyond this we fall back to the
+ * windowed / staleness logic unchanged.
+ */
+const MAX_LAST_LINE_BYTES = 8 * 1024 * 1024;
+/**
+ * Read the LAST complete newline-delimited record of the file, regardless
+ * of how large it is, by scanning backward from EOF in chunks.
+ *
+ * Why this exists: for `claude -p --output-format stream-json` the
+ * terminating `{"type":"result",...}` event is ALWAYS the final line, but
+ * that line embeds the entire final report and is frequently larger than
+ * DEFAULT_TAIL_BYTES (e.g. an agent that writes a long status report
+ * after an auto-declined AskUserQuestion). The windowed tail read drops
+ * such a line as a truncated head fragment, so completion was missed and
+ * the agent sat "running" until the 12 h timeout — never auto-delivered.
+ * Reading the true final line makes completion detection independent of
+ * the tail-window size.
+ *
+ * Returns the final record WITHOUT its trailing newline, or null if the
+ * file is empty, the final line is not newline-terminated (still being
+ * written), or the line exceeds MAX_LAST_LINE_BYTES. In every null case
+ * the caller falls through to the existing windowed/staleness logic with
+ * no behavior change.
+ */
+async function readLastCompleteLine(path, size) {
+    if (size <= 0)
+        return null;
+    let fh;
+    try {
+        fh = await fs.open(path, "r");
+        const chunkSize = 64 * 1024;
+        let pos = size;
+        let collected = Buffer.alloc(0);
+        while (pos > 0) {
+            if (size - pos > MAX_LAST_LINE_BYTES)
+                return null;
+            const readLen = Math.min(chunkSize, pos);
+            pos -= readLen;
+            const buf = Buffer.alloc(readLen);
+            await fh.read(buf, 0, readLen, pos);
+            collected = Buffer.concat([buf, collected]);
+            // Strip exactly one trailing newline (the file terminator) so we
+            // search for the delimiter BEFORE the final record, not after it.
+            let end = collected.length;
+            if (end > 0 && collected[end - 1] === 0x0a) {
+                end--;
+                if (end > 0 && collected[end - 1] === 0x0d)
+                    end--;
+            }
+            else {
+                // No terminating newline → final line still being written.
+                return null;
+            }
+            if (end <= 0) {
+                // File is just a newline (or empty after trim) — nothing usable.
+                if (pos === 0)
+                    return null;
+                continue;
+            }
+            const nl = collected.lastIndexOf(0x0a, end - 1);
+            if (nl >= 0) {
+                return collected.toString("utf-8", nl + 1, end);
+            }
+            if (pos === 0) {
+                // Whole file is a single (newline-terminated) record.
+                return collected.toString("utf-8", 0, end);
+            }
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        try {
+            await fh?.close();
+        }
+        catch {
+            /* ignore */
+        }
+    }
+}
 /**
  * v4.12.4 — Default staleness window for partial-output delivery.
  *
@@ -148,12 +234,67 @@ export async function parseOutputFileStatus(path, opts = {}) {
     const usable = lines
         .slice(headIncomplete, lines.length - (trailIncomplete > 0 ? trailIncomplete : 0))
         .filter((l) => l.length > 0);
+    // Window-independent completion check (regression fix). The terminating
+    // `{"type":"result",...}` event for `claude -p --output-format
+    // stream-json` is ALWAYS the final line, but it embeds the whole final
+    // report and is routinely larger than maxTailBytes — the windowed tail
+    // below would drop it as a truncated head fragment, leaving the agent
+    // mis-classified "running" until the 12 h timeout (so a completed
+    // sub-agent is never auto-delivered and the user must ask "status?").
+    // Inspect the TRUE final complete line directly so detection no longer
+    // depends on the tail-window size. Falls through unchanged when the
+    // last line is not a result event (running / killed mid-write / etc.).
+    const finalLine = await readLastCompleteLine(path, stat.size);
+    if (finalLine) {
+        let parsedFinal = null;
+        try {
+            parsedFinal = JSON.parse(finalLine);
+        }
+        catch {
+            parsedFinal = null;
+        }
+        if (parsedFinal && parsedFinal.type === "result") {
+            let output = typeof parsedFinal.result === "string" ? parsedFinal.result : "";
+            if (!output) {
+                // Same aggregation fallback as the windowed FIRST PASS: when the
+                // result event carries no `result` text, stitch together the
+                // assistant text blocks visible in the tail.
+                const fragments = [];
+                for (const line of usable) {
+                    let p;
+                    try {
+                        p = JSON.parse(line);
+                    }
+                    catch {
+                        continue;
+                    }
+                    if (p.type === "assistant" && Array.isArray(p.message?.content)) {
+                        for (const c of p.message.content) {
+                            if (c?.type === "text" && typeof c.text === "string") {
+                                fragments.push(c.text);
+                            }
+                        }
+                    }
+                }
+                output = fragments.join("\n\n").trim();
+            }
+            const usage = parsedFinal.usage;
+            const tokensUsed = usage
+                ? {
+                    input: usage.input_tokens ?? 0,
+                    output: usage.output_tokens ?? 0,
+                }
+                : undefined;
+            return { state: "completed", output, tokensUsed };
+        }
+    }
     // v4.13 — FIRST PASS: look for a `{"type":"result"}` event anywhere in
     // the tail. This is the completion signal for `claude -p
     // --output-format stream-json` output (used by the v4.13 dispatch
     // mechanism). When present, the `result` field holds the authoritative
     // final text. If `result.result` is missing, aggregate from all
-    // assistant text blocks in the tail.
+    // assistant text blocks in the tail. (Retained as a defensive fallback
+    // for the rare case the result event is NOT the final line.)
     for (let i = usable.length - 1; i >= 0; i--) {
         let parsed;
         try {

package/dist/services/async-agent-watcher.js

@@ -23,9 +23,10 @@
  * for the JSONL format details.
  */
 import fs from "fs";
-import { dirname } from "path";
+import { dirname, resolve } from "path";
 import { parseOutputFileStatus } from "./async-agent-parser.js";
-import { ASYNC_AGENTS_STATE_FILE } from "../paths.js";
+import { claimDelivery, markDelivered, isDelivered, cleanupAgentFiles, } from "./subagent-dedup.js";
+import { ASYNC_AGENTS_STATE_FILE, SUBAGENTS_DIR } from "../paths.js";
 import { getAllSessions } from "./session.js";
 /**
  * B3 — Detect a permanent "target chat does not exist" delivery failure
@@ -191,12 +192,133 @@ function decrementPendingCount(sessionKey) {
 export function listPendingAgents() {
     return [...pending.values()];
 }
-/** Start the polling loop. Idempotent. Loads any persisted state from disk. */
+/**
+ * v5.7.0 push entry point — called by POST /internal/subagent-exit when
+ * a detached subprocess exits. Looks the agent up, classifies its jsonl,
+ * and delivers immediately (claim-gated, so push / the poll backstop /
+ * reconciliation never double-deliver). Returns a coarse status for the
+ * HTTP layer:
+ *
+ *  - "unknown"   → no matching pending entry (cancelled, already
+ *                  delivered, or never tracked). HTTP 404. No side effect.
+ *  - "delivered" → terminal jsonl found and delivered (or the claim was
+ *                  lost to another path — either way it is handled and
+ *                  the entry is dropped). HTTP 200.
+ *  - "pending"   → exit fired but the jsonl is not yet terminal (rare
+ *                  flush race). Left to the poll backstop. HTTP 202.
+ */
+export async function deliverByAgentId(agentId) {
+    const entry = pending.get(agentId);
+    if (!entry)
+        return "unknown";
+    const status = await parseOutputFileStatus(entry.outputFile);
+    if (status.state === "completed") {
+        // Invariant: the path that WINS the claim owns removal of the
+        // shared pending entry. A claim-loser must not mutate shared state
+        // — the winner (this push, the poll backstop, or reconcile) removes
+        // it. If a winner ever crashes mid-delivery the next poll tick
+        // self-heals: claimDelivery() is false there too, so it skips
+        // re-delivery but still drops the entry. Either way "delivered".
+        if (claimDelivery(agentId)) {
+            await deliverAsCompleted(entry, status.output, status.tokensUsed);
+            pending.delete(agentId);
+            saveToDisk();
+        }
+        return "delivered";
+    }
+    if (status.state === "failed") {
+        if (claimDelivery(agentId)) {
+            await deliverAsFailure(entry, "error", status.error);
+            pending.delete(agentId);
+            saveToDisk();
+        }
+        return "delivered";
+    }
+    // running / missing → not yet flushed; the 15s poll backstop will get it.
+    return "pending";
+}
+/**
+ * v5.7.0 — Startup reconciliation. Runs once inside startWatcher() after
+ * loadFromDisk(). Two passes:
+ *
+ *  Pass A — immediate terminal drain. For every entry already in the
+ *  pending map (full delivery metadata present, restored by
+ *  loadFromDisk), check its jsonl ONCE: if terminal, deliver immediately
+ *  at startup instead of waiting up to 15s for the first poll tick. This
+ *  is what removes the post-restart latency the BACKLOG observed and
+ *  works even if the poll loop were disabled. Claim-gated.
+ *
+ *  Pass B — disk hygiene, never delivers. Walk SUBAGENTS_DIR: skip
+ *  delivered/tombstoned agents, age-cap-clean ancient files, and leave
+ *  fresh orphans (jsonl with no persisted state entry → no delivery
+ *  target) untouched for a later age-cap. We never fabricate a target.
+ *
+ * Idempotent (re-runnable), dedup-guarded by the .delivered marker.
+ */
+async function reconcileOnStartup() {
+    // Pass A — drain pending entries with full metadata.
+    for (const entry of [...pending.values()]) {
+        try {
+            if (isDelivered(entry.agentId)) {
+                pending.delete(entry.agentId);
+                continue;
+            }
+            const status = await parseOutputFileStatus(entry.outputFile);
+            if (status.state === "completed" && claimDelivery(entry.agentId)) {
+                await deliverAsCompleted(entry, status.output, status.tokensUsed);
+                pending.delete(entry.agentId);
+            }
+            else if (status.state === "failed" && claimDelivery(entry.agentId)) {
+                await deliverAsFailure(entry, "error", status.error);
+                pending.delete(entry.agentId);
+            }
+        }
+        catch (err) {
+            console.error(`[async-watcher] reconcile passA ${entry.agentId}:`, err);
+        }
+    }
+    saveToDisk();
+    // Pass B — disk hygiene. Never delivers.
+    let files;
+    try {
+        files = fs.readdirSync(SUBAGENTS_DIR);
+    }
+    catch {
+        return; // no subagents dir yet — nothing to reconcile
+    }
+    const now = Date.now();
+    for (const f of files) {
+        if (!f.endsWith(".jsonl"))
+            continue;
+        const agentId = f.slice(0, -".jsonl".length);
+        if (isDelivered(agentId))
+            continue; // delivered or cancel-tombstone
+        if (pending.has(agentId))
+            continue; // Pass A / poll / push own it
+        const jsonlPath = resolve(SUBAGENTS_DIR, f);
+        try {
+            const st = fs.statSync(jsonlPath);
+            if (now - st.mtimeMs > MAX_AGENT_AGE_MS) {
+                cleanupAgentFiles(agentId); // ancient orphan → clean
+            }
+            // else: orphan within age, no persisted target → cannot deliver;
+            // leave it (age-cap cleans it on a later boot). No spam, no
+            // fabricated delivery target.
+        }
+        catch {
+            /* stat race — ignore */
+        }
+    }
+}
+/** Start the polling loop. Idempotent. Loads any persisted state from
+ *  disk, then runs startup reconciliation (immediate terminal drain +
+ *  disk hygiene) before the 15s poll backstop begins. */
 export function startWatcher() {
     if (started)
         return;
     started = true;
     loadFromDisk();
+    void reconcileOnStartup().catch((err) => console.error("[async-watcher] reconcile failed:", err));
     pollTimer = setInterval(() => {
         pollOnce().catch((err) => console.error("[async-watcher] poll cycle failed:", err));
     }, POLL_INTERVAL_MS);
@@ -235,21 +357,31 @@ export async function pollOnce() {
         entry.lastCheckedAt = now;
         // Timeout check first — if the agent is past its giveUpAt, give up
         // regardless of whether the file shows progress.
+        // v5.7.0 — every terminal delivery is claim-gated so push,
+        // this poll backstop, and startup reconciliation never
+        // double-deliver. A lost claim means another path already
+        // handled it: just drop the entry without re-delivering.
         if (now >= entry.giveUpAt) {
-            const outcome = await deliverAsFailure(entry, "timeout", "Agent ran longer than 12h — giving up");
-            abandonIfInvalidTarget(entry, outcome);
+            if (claimDelivery(entry.agentId)) {
+                const outcome = await deliverAsFailure(entry, "timeout", "Agent ran longer than 12h — giving up");
+                abandonIfInvalidTarget(entry, outcome);
+            }
             toRemove.push(entry.agentId);
             continue;
         }
         const status = await parseOutputFileStatus(entry.outputFile);
         if (status.state === "completed") {
-            const outcome = await deliverAsCompleted(entry, status.output, status.tokensUsed);
-            abandonIfInvalidTarget(entry, outcome);
+            if (claimDelivery(entry.agentId)) {
+                const outcome = await deliverAsCompleted(entry, status.output, status.tokensUsed);
+                abandonIfInvalidTarget(entry, outcome);
+            }
             toRemove.push(entry.agentId);
         }
         else if (status.state === "failed") {
-            const outcome = await deliverAsFailure(entry, "error", status.error);
-            abandonIfInvalidTarget(entry, outcome);
+            if (claimDelivery(entry.agentId)) {
+                const outcome = await deliverAsFailure(entry, "error", status.error);
+                abandonIfInvalidTarget(entry, outcome);
+            }
             toRemove.push(entry.agentId);
         }
         else if (status.state === "missing" &&
@@ -257,8 +389,10 @@ export async function pollOnce() {
             // v4.14.2 — Zombie guard: the subprocess never created its
             // output file within `missingFileFailureMs` (default 10 min).
             // Declare failed instead of polling until the 12h giveUpAt.
-            const outcome = await deliverAsFailure(entry, "error", `Dispatched subprocess never wrote its output file (${Math.round((now - entry.startedAt) / 60_000)}m after start). Likely crashed before initializing, or the file was removed externally.`);
-            abandonIfInvalidTarget(entry, outcome);
+            if (claimDelivery(entry.agentId)) {
+                const outcome = await deliverAsFailure(entry, "error", `Dispatched subprocess never wrote its output file (${Math.round((now - entry.startedAt) / 60_000)}m after start). Likely crashed before initializing, or the file was removed externally.`);
+                abandonIfInvalidTarget(entry, outcome);
+            }
             toRemove.push(entry.agentId);
         }
         // running / missing-but-young → keep polling next cycle
@@ -424,6 +558,12 @@ export function cancelPendingForSession(sessionKey) {
     let changed = false;
     for (const [id, entry] of pending.entries()) {
         if (entry.sessionKey === sessionKey) {
+            // v5.7.0 — tombstone before removal: a cancelled agent's
+            // subprocess may still exit later and POST, or its leftover jsonl
+            // may be rediscovered by reconciliation on a future boot. The
+            // .delivered marker makes "cancelled" authoritative and
+            // restart-proof so neither path can resurrect it.
+            markDelivered(entry.agentId);
             pending.delete(id);
             changed = true;
         }

package/dist/services/subagent-dedup.js

@@ -0,0 +1,86 @@
+/**
+ * Atomic deliver-once primitive for detached sub-agents (v5.7.0).
+ *
+ * The single source of truth for "has this agent's result already been
+ * delivered (or been cancel-tombstoned)?" — shared by all three delivery
+ * paths: the exit-push endpoint, the 15s poll backstop, and startup
+ * reconciliation. The marker is an empty `<agentId>.delivered` file in
+ * SUBAGENTS_DIR; `claimDelivery` creates it with O_EXCL ("wx") so exactly
+ * one caller wins the race. Crash-safe and restart-safe (it is on disk),
+ * which the in-memory pending map alone cannot be.
+ */
+import fs from "fs";
+import { resolve } from "path";
+import { SUBAGENTS_DIR } from "../paths.js";
+function markerPath(agentId) {
+    return resolve(SUBAGENTS_DIR, `${agentId}.delivered`);
+}
+function ensureDir() {
+    try {
+        fs.mkdirSync(SUBAGENTS_DIR, { recursive: true });
+    }
+    catch {
+        /* race-safe — a concurrent create is fine */
+    }
+}
+/**
+ * Attempt to claim delivery for `agentId`. Returns true exactly once
+ * (the caller that atomically created the marker) and false for every
+ * subsequent call. On an unexpected fs error other than EEXIST we return
+ * true: a rare double-delivery (a duplicate message) is strictly
+ * preferable to silently losing a result — the exact bug this whole
+ * feature exists to fix.
+ */
+export function claimDelivery(agentId) {
+    ensureDir();
+    try {
+        const fd = fs.openSync(markerPath(agentId), "wx");
+        fs.closeSync(fd);
+        return true;
+    }
+    catch (err) {
+        if (err.code === "EEXIST")
+            return false;
+        return true; // prefer a possible duplicate over a lost delivery
+    }
+}
+/**
+ * Write the marker if absent, ignore if already present. Used as a
+ * cancel tombstone (claim-without-deliver) so a cancelled agent can
+ * never be resurrected by push or reconciliation. Idempotent; never
+ * throws.
+ */
+export function markDelivered(agentId) {
+    ensureDir();
+    try {
+        const fd = fs.openSync(markerPath(agentId), "wx");
+        fs.closeSync(fd);
+    }
+    catch {
+        /* EEXIST or fs error — tombstone already effective / best-effort */
+    }
+}
+/** True if a delivered/tombstone marker exists for this agent. */
+export function isDelivered(agentId) {
+    try {
+        return fs.existsSync(markerPath(agentId));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Best-effort removal of every on-disk artifact for an aged-out agent
+ * (jsonl + err + delivered marker). Used by reconciliation's age-cap so
+ * ancient files don't accumulate. Never throws.
+ */
+export function cleanupAgentFiles(agentId) {
+    for (const ext of [".jsonl", ".err", ".delivered"]) {
+        try {
+            fs.unlinkSync(resolve(SUBAGENTS_DIR, `${agentId}${ext}`));
+        }
+        catch {
+            /* ignore — already gone or never existed */
+        }
+    }
+}

package/dist/web/server.js

@@ -12,6 +12,7 @@ import fs from "fs";
 import path from "path";
 import { resolve } from "path";
 import { execSync } from "child_process";
+import crypto from "crypto";
 import { WebSocketServer, WebSocket } from "ws";
 import { getRegistry } from "../engine.js";
 import { getSession, resetSession, getAllSessions } from "../services/session.js";
@@ -51,6 +52,18 @@ let bindRetryTimer = null;
  *  this and exits silently if set, so stop is truly terminal. */
 let stopRequested = false;
 const WEB_PASSWORD = process.env.WEB_PASSWORD || "";
+/**
+ * v5.7.0 — Per-boot random token guarding POST /internal/subagent-exit.
+ * Generated once at module load; never persisted, never logged. The
+ * detached-agent exit hook reads it in-process via getInternalToken().
+ * The route is loopback-bound by default; this token additionally
+ * defends the opt-in WEB_HOST=0.0.0.0 (LAN-exposed) case. 48 hex chars.
+ */
+const INTERNAL_TOKEN = crypto.randomBytes(24).toString("hex");
+/** In-process accessor for the per-boot internal-route token. */
+export function getInternalToken() {
+    return INTERNAL_TOKEN;
+}
 /** The actual port the Web UI is running on (may differ from WEB_PORT if busy). */
 let actualWebPort = WEB_PORT;
 // ── MIME Types ──────────────────────────────────────────
@@ -154,6 +167,56 @@ async function handleAPI(req, res, urlPath, body) {
         }
         return;
     }
+    // POST /internal/subagent-exit — detached sub-agent exit push (v5.7.0).
+    // Always available (NO WEBHOOK_ENABLED dependency, so it works for every
+    // install with zero config); loopback-bound by default; per-boot bearer
+    // token. Reads the agent's jsonl, classifies, delivers immediately
+    // (claim-gated). Idempotent — a repeat POST is a 404 no-op.
+    if (urlPath === "/internal/subagent-exit" && req.method === "POST") {
+        // The legitimate payload is ~80 bytes ({agentId, exitCode}). Reject
+        // anything absurd before the auth compare so an unauthenticated
+        // caller (only reachable at all under the opt-in WEB_HOST=0.0.0.0)
+        // cannot push large bodies through this always-on route. (A deeper
+        // streaming cap on the shared body accumulator — also used by
+        // /api/ and /v1/ — is a separate pre-existing hardening item.)
+        if (body.length > 8 * 1024) {
+            res.statusCode = 413;
+            res.end(JSON.stringify({ error: "Payload too large" }));
+            return;
+        }
+        if (!timingSafeBearerMatch(req.headers.authorization, INTERNAL_TOKEN)) {
+            res.statusCode = 401;
+            res.end(JSON.stringify({ error: "Unauthorized" }));
+            return;
+        }
+        let agentId;
+        try {
+            const payload = JSON.parse(body);
+            agentId = typeof payload.agentId === "string" ? payload.agentId : "";
+        }
+        catch {
+            res.statusCode = 400;
+            res.end(JSON.stringify({ error: "Invalid JSON body" }));
+            return;
+        }
+        if (!agentId) {
+            res.statusCode = 400;
+            res.end(JSON.stringify({ error: "Missing agentId" }));
+            return;
+        }
+        try {
+            const { deliverByAgentId } = await import("../services/async-agent-watcher.js");
+            const outcome = await deliverByAgentId(agentId);
+            res.statusCode = outcome === "unknown" ? 404 : outcome === "pending" ? 202 : 200;
+            res.end(JSON.stringify({ ok: outcome !== "unknown", outcome }));
+        }
+        catch (err) {
+            res.statusCode = 500;
+            res.end(JSON.stringify({ error: "delivery failed" }));
+            console.error("[internal/subagent-exit] delivery error:", err);
+        }
+        return;
+    }
     // Auth check for all other API routes
     if (!checkAuth(req)) {
         res.statusCode = 401;
@@ -1580,6 +1643,14 @@ function handleWebRequest(req, res) {
             handleAPI(req, res, urlPath, body);
             return;
         }
+        // v5.7.0 — internal bot-to-bot routes (detached sub-agent exit
+        // push). Dispatched through handleAPI, which bearer-auths it and
+        // returns before the cookie-auth gate. Kept off the /api/ prefix so
+        // it is never surfaced in the Web UI route surface.
+        if (urlPath.startsWith("/internal/")) {
+            handleAPI(req, res, urlPath, body);
+            return;
+        }
         // Auth page (if password set and not authenticated)
         if (WEB_PASSWORD && !checkAuth(req) && urlPath !== "/login.html") {
             res.writeHead(302, { Location: "/login.html" });

package/llms.txt

@@ -0,0 +1,38 @@
+# Alvin Bot
+
+> Alvin Bot is an open-source, MIT-licensed, self-hosted autonomous AI agent that runs on your own machine and answers you on Telegram, Slack, Discord, WhatsApp, Signal, a terminal TUI, and a web dashboard. It is built on the official Claude Agent SDK and runs a provider-agnostic engine that also drives OpenAI, Groq, Google Gemini, NVIDIA NIM, OpenRouter, and Ollama, with automatic failover after two consecutive provider failures and a heartbeat health check every five minutes. It is local-first and telemetry-free: prompts and responses are never logged off-machine, secrets live in a chmod-0600 .env, and shell execution is allowlisted by default.
+
+Alvin Bot is in the same category as Hermes Agent (Nous Research) and OpenClaw: a self-hosted personal AI agent with persistent memory, scheduled tasks, real shell/filesystem access, and multi-platform chat delivery. It differentiates on resilience (automatic provider failover + a self-preservation subsystem), zero-config memory (indexed recall with no embedding API key), detached sub-agents that survive a parent abort, and safe-by-default security.
+
+## Key capabilities
+
+- Multi-provider engine: Claude Agent SDK + OpenAI, Groq, Google Gemini, NVIDIA NIM, OpenRouter, Ollama, any OpenAI-compatible API; automatic failover after 2 provider failures, 5-minute heartbeat health check, reorderable fallback chain.
+- Detached sub-agents: `alvin_dispatch_agent` spawns independent `claude -p` subprocesses that keep running and deliver their result even if the parent conversation is aborted; `readonly`/`research` toolset presets restrict their privileges.
+- Zero-config layered memory: SQLite embeddings store with a built-in FTS5 keyword fallback so indexed recall works with no embedding API key; smart prompt-injection mode trims ~25k tokens/turn once the store is populated.
+- 4-tier browser automation: WebFetch → stealth Playwright → persistent-profile Chromium over CDP → opt-in agent-browser CLI; handles login-walled and bot-protected pages.
+- Self-preservation subsystem: startup preflight, dead-man's-switch heartbeat, crash forensic bundles, AI self-diagnosis, crash-loop brake, daily trend anomaly detection — detects and recovers from its own failures unattended.
+- Multi-platform: Telegram, Slack (one channel = one isolated workspace), Discord, WhatsApp (owner-approval gate), Signal, terminal TUI, full web dashboard.
+- Cron / scheduled AI tasks in natural language (e.g. "check my email every morning"); MCP client (connect any Model Context Protocol server); hot-reload skills + 6 built-in plugins; hooks; per-channel context-isolated workspaces with shared memory.
+- Security defaults: exec allowlist + shell-metachar filter on by default, DM pairing, timing-safe webhook auth, enforced 0600 file permissions, `alvin-bot audit` CLI, an honestly documented threat model (prompt injection is acknowledged as unsolved, not pretended away).
+- Distribution: npm global install, from-source, one-line installer, Docker, macOS Electron .dmg with system tray; macOS launchd integration keeps the Claude Max OAuth token working across restarts.
+
+## When to use Alvin Bot
+
+- Use Alvin Bot when you want one resilient, self-healing personal agent on your own machine that keeps working when a provider fails, gives you indexed memory without buying an embedding API key, ships safe-by-default execution sandboxing, and is built directly on the official Claude Agent SDK.
+- Use Hermes Agent when you want a research-grade self-improving learning loop, need the agent to act as an MCP server for Claude Desktop / Cursor / VS Code, want 200+ model choice or many execution backends, or value a large community.
+- Use OpenClaw when you want the widest messaging reach (25–50+ channels) plus native mobile apps and voice activation, fully transparent plain-file memory you can git-track, and the largest ecosystem.
+
+## Documentation
+
+- [README](https://github.com/alvbln/Alvin-Bot/blob/main/README.md): full feature list, quick start, architecture, provider matrix, configuration.
+- [Handbook](https://github.com/alvbln/Alvin-Bot/blob/main/docs/HANDBOOK.md): complete standalone reference — providers, sub-agents, cron, plugins, MCP, platforms.
+- [Changelog](https://github.com/alvbln/Alvin-Bot/blob/main/CHANGELOG.md): per-release notes; current version 5.6.1.
+- [Security threat model](https://github.com/alvbln/Alvin-Bot/blob/main/docs/security.md): honest threat model and hardening guide.
+- [Alvin Bot vs Hermes vs OpenClaw](https://alvin.alev-b.com/vs/hermes-openclaw): fair, named head-to-head comparison and decision guide.
+- [npm package](https://www.npmjs.com/package/alvin-bot): `npm install -g alvin-bot`.
+- [GitHub repository](https://github.com/alvbln/Alvin-Bot): source, issues, releases.
+
+## Optional
+
+- [Multi-session workspaces](https://github.com/alvbln/Alvin-Bot/blob/main/README.md#-multi-session-workspaces-v4120): parallel per-channel context-isolated sessions with globally shared memory.
+- [Slack setup](https://github.com/alvbln/Alvin-Bot/releases/latest): copy-paste Slack App manifest + step-by-step guide.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "alvin-bot",
-  "version": "5.6.1",
-  "description": "Alvin Bot — Your personal AI agent on Telegram, WhatsApp, Discord, Signal, and Web.",
+  "version": "5.7.0",
+  "description": "Alvin Bot — open-source, self-hosted autonomous AI agent on Telegram, Slack, Discord, WhatsApp, Signal, terminal & web. Built on the Claude Agent SDK with a multi-provider engine (OpenAI, Groq, Gemini, NVIDIA NIM, OpenRouter, Ollama) and automatic failover, detached sub-agents that survive a parent abort, zero-config indexed memory (no embedding key needed), 4-tier browser automation, cron tasks, MCP client and a self-preservation subsystem. Local-first, telemetry-free. An OpenClaw / Hermes Agent alternative.",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
@@ -143,6 +143,8 @@
     "ai",
     "claude",
     "agent",
+    "ai-agent",
+    "autonomous-agent",
     "llm",
     "multi-model",
     "gpt",
@@ -150,14 +152,26 @@
     "nvidia",
     "self-hosted",
     "autonomous",
+    "personal-assistant",
     "whatsapp",
     "discord",
     "signal",
+    "slack",
     "openai",
     "groq",
+    "ollama",
+    "openrouter",
     "chatbot",
     "assistant",
-    "electron"
+    "electron",
+    "sub-agents",
+    "mcp",
+    "mcp-client",
+    "claude-agent-sdk",
+    "cron",
+    "skills",
+    "openclaw-alternative",
+    "hermes-alternative"
   ],
   "author": "alvbln",
   "license": "MIT",