alvin-bot 5.3.0 → 5.5.0

package/.env.example

@@ -41,3 +41,103 @@ WEB_PORT=3100
 
 # === Custom Chrome (for WhatsApp, if not auto-detected) ===
 # CHROME_PATH=/usr/bin/google-chrome
+
+# ===================================================================
+# OPTIONAL — Security & Auth
+# ===================================================================
+
+# Auth mode for new users trying to talk to the bot.
+#   allowlist  (default) — only ALLOWED_USERS can use the bot
+#   pairing              — new users get a 6-digit pairing code; owner approves
+#   open                 — anyone can chat (for public bots)
+# AUTH_MODE=allowlist
+
+# Session isolation (how context is scoped):
+#   per-user          (default) — each user gets their own session
+#   per-channel       — everyone in the same channel shares a session
+#   per-channel-peer  — per (channel, user) pair
+# SESSION_MODE=per-user
+
+# ===================================================================
+# OPTIONAL — Text-to-Speech (TTS)
+# ===================================================================
+
+# TTS backend: "edge" (free, default) or "elevenlabs" (paid, higher quality)
+# TTS_PROVIDER=edge
+
+# ElevenLabs — set all three to use ElevenLabs TTS
+# ELEVENLABS_API_KEY=
+# ELEVENLABS_VOICE_ID=iP95p4xoKVk53GoZ742B
+# ELEVENLABS_MODEL_ID=eleven_v3
+
+# ===================================================================
+# OPTIONAL — Webhooks
+# ===================================================================
+
+# Enable inbound webhook endpoint (POST /api/webhook) for external triggers
+# WEBHOOK_ENABLED=false
+# WEBHOOK_TOKEN=change-me-to-a-random-secret
+
+# ===================================================================
+# OPTIONAL — Sub-Agents & Compaction
+# ===================================================================
+
+# Maximum number of sub-agents that can run in parallel (default: 4)
+# MAX_SUBAGENTS=4
+
+# Sub-agent hard timeout in ms. -1 = unlimited (default: -1)
+# SUBAGENT_TIMEOUT=-1
+
+# Context compaction threshold in tokens (default: 80000)
+# COMPACTION_THRESHOLD=80000
+
+# ===================================================================
+# OPTIONAL — Browser Automation
+# ===================================================================
+
+# Connect to an existing Chrome DevTools Protocol endpoint instead of
+# launching a new browser instance.
+# CDP_URL=ws://localhost:9222
+
+# Port for the optional browser HTTP gateway (default: 3800)
+# BROWSE_SERVER_PORT=3800
+
+# ===================================================================
+# OPTIONAL — Data Directory
+# ===================================================================
+
+# Override where alvin-bot stores its data (default: ~/.alvin-bot)
+# ALVIN_DATA_DIR=/custom/path/to/data
+
+# Live steering — inject follow-up instructions mid-generation (default: on)
+# STEERING_ENABLED=true
+
+# ===================================================================
+# POWER / OWNER OPT-INS — unlock full capability
+#
+# These are safe-by-default for unconfigured installs. As the owner
+# you can opt in to the full power mode for each feature.
+# ===================================================================
+
+# Shell & Python execution security:
+#   allowlist  (default) — only a curated set of safe binaries (ls, cat, git,
+#               python3, node, etc.) can be executed by the bot
+#   full       — unrestricted shell/Python — full agent power mode; set this
+#                when you want the bot to run arbitrary commands on your machine
+#   deny       — block all exec/python tool calls (read-only agent)
+# EXEC_SECURITY=allowlist
+
+# Web UI host binding:
+#   127.0.0.1  (default) — loopback only, not reachable from LAN or internet
+#   0.0.0.0              — listen on all interfaces (expose to LAN/VPS/remote)
+# If you set WEB_HOST=0.0.0.0 (or any non-loopback address), also set
+# WEB_PASSWORD to protect the UI:
+# WEB_HOST=127.0.0.1
+# WEB_PASSWORD=your-strong-password
+
+# Allow the bot to fetch localhost / LAN / internal URLs (SSRF guard):
+#   unset or 0  (default) — private IPs and loopback are blocked to prevent
+#                SSRF attacks from untrusted prompt content
+#   1           — enable, so the bot can reach your local services, dev
+#                servers, and internal APIs (owner workflow on your own machine)
+# ALLOW_PRIVATE_FETCH=0

package/CHANGELOG.md

@@ -2,6 +2,71 @@
 
 All notable changes to Alvin Bot are documented here.
 
+## [5.5.0] — 2026-05-18
+
+### The ⛔ Stop button now responds instantly — and honestly
+
+Stopping a task is now crisp and truthful. The moment a task finishes,
+the Stop button disappears, so you're never tapping a control for
+something that's already done. And the feedback always matches reality:
+if you tap Stop while Alvin is genuinely working, it stops and says so;
+if the task had already completed, Alvin tells you that plainly instead
+of implying it cut something short. If you hit Stop in that brief moment
+while an answer is being prepared, that answer is now held back — "I
+stopped it" means nothing more arrives. Anything Alvin had already
+shown you stays exactly as it was.
+
+### Fewer false alerts — smarter health monitoring
+
+Alvin's self-monitoring got a lot more trustworthy. A planned restart
+or an update is no longer mistaken for a problem, and the daily health
+summary only raises a flag when there's real evidence something is
+actually wrong — so the alerts you do get are ones worth reading.
+Routine background housekeeping no longer shows up as noise.
+
+As always, this shipped after a full multi-pass review and a
+fresh-install + stress verification on a clean separate machine.
+
+## [5.4.0] — 2026-05-18
+
+### Smoother background tasks — and Alvin always tells you the truth
+
+When you ask Alvin to go off and do something longer — research, a
+multi-step job — it now reliably hands control straight back to you so
+you can keep chatting while it works, then delivers the result as its
+own message. And if a task does need to run inline for a moment,
+Alvin says so honestly instead of implying you're free when you're
+not. Talking to Alvin now feels exactly like working with a colleague
+who's already on it: you're never left waiting or guessing.
+
+### Safer out of the box — with your full power one setting away
+
+Alvin now ships with sensible, safe defaults so a fresh install is
+solid for everyone, including people who just want to try it quickly.
+Nothing about Alvin's capabilities has been taken away: if you want
+the full, unrestricted superadmin experience it's a single documented
+setting — your machine, your rules, your call. The new `.env.example`
+spells out every option, including the "power" switches, in plain
+language. You stay completely in control.
+
+### Reliability & robustness across the board
+
+A broad pass to make Alvin steadier on long-running setups: no more
+duplicate messages under load, cleaner interplay between stopping,
+steering and background work, more accurate scheduling for custom
+cron expressions, and tighter handling of edge cases throughout.
+Verified end-to-end with a stress test on a clean separate machine.
+
+### A leaner, tidier install
+
+Roughly 20 MB lighter to install, a calmer first-run experience
+(optional features that aren't configured no longer look like
+errors), better behavior on Windows and for non-German voice notes,
+and a zero-config friendly default so a minimal setup just works.
+
+As always, this shipped only after a full multi-pass review and a
+fresh-install + stress verification on a clean second machine.
+
 ## [5.3.0] — 2026-05-18
 
 ### Talk to Alvin while it's working — no more interrupting yourself
@@ -429,8 +494,8 @@ A maintainer's local Mac that had been running alvin-bot under PM2 *before* the
 ```bash
 pm2 delete polyseus                      # any other PM2 entries
 pm2 save --force                         # empty dump
-launchctl unload ~/Library/LaunchAgents/pm2.alvin_de.plist 2>/dev/null
-rm -f ~/Library/LaunchAgents/pm2.alvin_de.plist
+launchctl unload ~/Library/LaunchAgents/pm2.youruser.plist 2>/dev/null
+rm -f ~/Library/LaunchAgents/pm2.youruser.plist
 pm2 kill
 npm uninstall -g pm2
 rm -rf ~/.pm2
@@ -2332,7 +2397,7 @@ Example:
 🤖 Alvin Bot v4.8.3
    Node v25.9.0 · darwin/arm64
 
-📁 Data dir:  /Users/alvin_de/.alvin-bot
+📁 Data dir:  ~/.alvin-bot
    .env:      ✅ present
    Provider:  claude-sdk
 

package/README.md

@@ -62,6 +62,8 @@ That's it. The setup wizard validates everything:
 
 **Requires:** Node.js 18+ ([nodejs.org](https://nodejs.org)) · Telegram bot token ([@BotFather](https://t.me/BotFather)) · Your Telegram user ID ([@userinfobot](https://t.me/userinfobot))
 
+> **Native build note:** Alvin Bot uses `better-sqlite3` for indexed memory. Prebuilt binaries are included for common macOS and Linux environments so most installs need nothing extra. If your platform doesn't have a prebuilt binary and the optional native compilation is skipped, the bot still runs — semantic memory falls back gracefully to keyword search. A C++ toolchain (Xcode Command Line Tools on macOS, `build-essential` on Ubuntu) and Python 3 are only needed if you hit a build-from-source fallback.
+
 Free AI providers available — no credit card needed. **Privacy-first?** Pick the 🔒 **Offline — Gemma 4 E4B** option in setup for a fully local LLM via Ollama (macOS/Linux: automated install; Windows: manual).
 
 ### 🔐 A note on permission prompts

package/alvin-bot.config.example.json

@@ -6,7 +6,7 @@
     "streamThrottleMs": 1500
   },
   "ai": {
-    "primaryProvider": "claude-sdk",
+    "primaryProvider": "groq",
     "fallbackProviders": ["nvidia-kimi-k2.5", "nvidia-llama-3.3-70b"],
     "maxBudgetUsd": 5.0,
     "defaultEffort": "high"

package/dist/config.js

@@ -26,8 +26,10 @@ export const config = {
     // Agent
     defaultWorkingDir: process.env.WORKING_DIR || os.homedir(),
     maxBudgetUsd: Number(process.env.MAX_BUDGET_USD) || 5.0,
-    // Model provider (primary)
-    primaryProvider: process.env.PRIMARY_PROVIDER || "claude-sdk",
+    // Model provider (primary). Default is "groq" — works on a fresh install
+    // with only BOT_TOKEN + GROQ_API_KEY. Set PRIMARY_PROVIDER=claude-sdk to
+    // use the Claude SDK (requires `claude login` / Claude Max subscription).
+    primaryProvider: process.env.PRIMARY_PROVIDER || "groq",
     fallbackProviders: (process.env.FALLBACK_PROVIDERS || "")
         .split(",")
         .map(s => s.trim())
@@ -80,8 +82,9 @@ export const config = {
     // Browser
     cdpUrl: process.env.CDP_URL || "",
     browseServerPort: Number(process.env.BROWSE_SERVER_PORT) || 3800,
-    // Exec Security
-    execSecurity: (process.env.EXEC_SECURITY || "full"),
+    // Exec Security — default is "allowlist" (safe). Set EXEC_SECURITY=full to
+    // allow shell pipelines, metacharacters, and arbitrary binaries (opt-in).
+    execSecurity: (process.env.EXEC_SECURITY || "allowlist"),
 };
 /**
  * Feature flag: btw live-steering. Default ON — only "false" or "0" disables.

package/dist/handlers/commands.js

@@ -1946,11 +1946,19 @@ export function registerCommands(bot) {
         const sessionKey = ctx.match[1];
         const session = getSession(sessionKey);
         const lang = session.language;
-        if (session.isProcessing) {
+        // A1 — Capture isProcessing BEFORE requestStop (which sets it false)
+        // so we can show the right toast: "stopped" vs "already finished".
+        const wasProcessing = session.isProcessing;
+        if (wasProcessing) {
             requestStop(session, "soft", buildStopDeps(session));
         }
+        // A1 — Honest toast: if the turn had already finished when the button was
+        // tapped, don't claim "stopped" — tell the user it was already done.
+        const toastKey = wasProcessing
+            ? "bot.cancel.stoppedToast"
+            : "bot.cancel.alreadyDone";
         try {
-            await ctx.answerCallbackQuery({ text: t("bot.cancel.stoppedToast", lang) });
+            await ctx.answerCallbackQuery({ text: t(toastKey, lang) });
         }
         catch { /* harmless grammy race */ }
         try {

package/dist/handlers/document.js

@@ -74,7 +74,14 @@ export async function handleDocument(ctx) {
         // Download the file
         const file = await ctx.api.getFile(doc.file_id);
         const fileUrl = `https://api.telegram.org/file/bot${config.botToken}/${file.file_path}`;
-        const localPath = path.join(TEMP_DIR, `doc_${Date.now()}_${filename}`);
+        // H2: strip any path components from the attacker-controlled file_name
+        // to prevent writing outside TEMP_DIR (e.g. file_name="../../../x").
+        const safeFilename = path.basename(filename);
+        const localPath = path.join(TEMP_DIR, `doc_${Date.now()}_${safeFilename}`);
+        // Containment assertion: resolved path must stay inside TEMP_DIR.
+        if (!path.resolve(localPath).startsWith(path.resolve(TEMP_DIR))) {
+            throw new Error("File path containment violation");
+        }
         await downloadFile(fileUrl, localPath);
         const caption = ctx.message?.caption || "";
         const userInstruction = caption || `Analysiere diese Datei: ${filename}`;

package/dist/handlers/message.js

@@ -1,5 +1,6 @@
 import { InputFile, InlineKeyboard } from "grammy";
 import fs from "fs";
+import crypto from "crypto";
 import { getSession, addToHistory, trackProviderUsage, buildSessionKey, getTelegramWorkspace, markSessionDirty } from "../services/session.js";
 import { resolveWorkspaceOrDefault, getWorkspace } from "../services/workspaces.js";
 import { TelegramStreamer } from "../services/telegram.js";
@@ -121,6 +122,37 @@ const TOOL_ICONS = {
     WebFetch: "📡",
     Task: "🤖",
 };
+// ── A3 — stop-suppress-undelivered pure predicate ────────────────────────────
+/**
+ * Determine whether the final answer send should be suppressed because a stop
+ * was requested and no visible text has yet been delivered to the user.
+ *
+ * This closes the gap behind "I clicked Stop but it answered anyway": the
+ * Claude SDK delivers short answers atomically, so the for-await loop parks
+ * on IPC the whole time, and the complete answer arrives as one block. By the
+ * time the consumer bail fires at the top of the loop, the answer is computed
+ * and about to be sent. This guard is the only stoppable moment for atomic
+ * answers.
+ *
+ * HARD CONSTRAINT — no-retract invariant: if ANY visible text has already
+ * been streamed/committed to the user (visibleTextAlreadySent=true), the
+ * predicate returns false regardless of stop state. Partial output that
+ * already reached the user is NEVER retracted. The consumer bail in the
+ * for-await loop already handles mid-stream stops; this guard only acts on
+ * the final commit step.
+ *
+ * Truth table:
+ *   stopRequested=truthy  + visibleTextAlreadySent=false → true  (suppress)
+ *   stopRequested=truthy  + visibleTextAlreadySent=true  → false (no-retract)
+ *   stopRequested=falsy   + *                            → false (normal)
+ */
+export function shouldSuppressFinalSend(args) {
+    if (!args.stopRequested)
+        return false;
+    if (args.visibleTextAlreadySent)
+        return false;
+    return true;
+}
 // ── v5.2 live steering — pure routing helper ─────────────────────────────────
 /**
  * Decide how a mid-task message (arriving while `session.isProcessing`) should
@@ -140,10 +172,34 @@ export function decideMidTaskRouting(args) {
         return "queue";
     if (args.shouldBypass)
         return "bypass";
-    if (args.providerIsClaudeSdk && args.steeringEnabled && args.hasSteerChannel)
+    if (args.providerIsClaudeSdk && args.steeringEnabled && args.hasSteerChannel && args.hasLiveSdkQuery)
         return "steer";
     return "queue";
 }
+// ── Cycle-3 P0 — background honesty guard ────────────────────────────────────
+/**
+ * Detect when the bot falsely promised "running in the background — you can
+ * keep chatting" but actually ran a sync Task/Agent that blocked the session.
+ *
+ * Returns true when all of the following hold:
+ *   1. A Task/Agent chunk arrived WITHOUT `run_in_background: true` (i.e. the
+ *      stuck-timer entered sync mode — `taskChunkSeenWithoutRunInBackground`).
+ *   2. No real background detach happened this turn:
+ *      • `mcp__alvin__dispatch_agent` was NOT called (`dispatchAgentFired=false`)
+ *      • `pendingBackgroundCount` did NOT increase (`pendingBackgroundDelta=0`)
+ *
+ * Exported so it can be unit-tested without a grammy Context mock.
+ */
+export function detectUndetachedBackgroundClaim(args) {
+    if (!args.taskChunkSeenWithoutRunInBackground)
+        return false;
+    // Dead in production wiring (always false there — PATH A is detected via pendingBackgroundDelta); kept for explicit unit-test truth-table coverage.
+    if (args.dispatchAgentFired)
+        return false;
+    if (args.pendingBackgroundDelta > 0)
+        return false;
+    return true;
+}
 /** React to a message with an emoji. Silently fails if reactions aren't supported. */
 async function react(ctx, emoji) {
     try {
@@ -210,6 +266,7 @@ export async function handleMessage(ctx) {
             providerIsClaudeSdk: _midTaskProviderIsSdk,
             steeringEnabled: isSteeringEnabled(),
             hasSteerChannel: !!session._steerChannel,
+            hasLiveSdkQuery: !!session._qHandle, // C-H3: require a live SDK query handle
             shouldBypass: _midTaskBypass,
         });
         if (_midTaskRoute === "bypass") {
@@ -234,16 +291,28 @@ export async function handleMessage(ctx) {
             // v5.2 — btw live steering: push mid-task message into the open
             // SteerChannel so the running claude-sdk query picks it up as a
             // streaming-input user message. No abort, no queue.
-            session._steerChannel.push(text);
-            await react(ctx, "📨");
-            if (!session._steerAckSentThisTurn) {
+            // C-L2: push() returns boolean — only 📨/ack when accepted; reply bufferFull otherwise.
+            const steerAccepted = session._steerChannel.push(text);
+            if (steerAccepted) {
+                await react(ctx, "📨");
+                if (!session._steerAckSentThisTurn) {
+                    try {
+                        await ctx.reply(t("bot.steer.ack", session.language));
+                    }
+                    catch {
+                        /* harmless grammy race */
+                    }
+                    session._steerAckSentThisTurn = true;
+                }
+            }
+            else {
+                // Buffer full or channel closed — tell the user honestly
                 try {
-                    await ctx.reply(t("bot.steer.ack", session.language));
+                    await ctx.reply(t("bot.steer.bufferFull", session.language));
                 }
                 catch {
                     /* harmless grammy race */
                 }
-                session._steerAckSentThisTurn = true;
             }
             return;
         }
@@ -274,6 +343,13 @@ export async function handleMessage(ctx) {
     }
     session.isProcessing = true;
     session.abortController = new AbortController();
+    // C-H2 — Stamp a per-turn identity token so the finally block can detect
+    // whether a NEW turn has already started before it runs.  If requestStop
+    // fires mid-turn and allows a new message to start a fresh turn (with its
+    // own new abortController + _steerChannel), the old turn's finally sees the
+    // token mismatch and skips the clobber — preserving the new turn's state.
+    const _thisTurnId = crypto.randomUUID();
+    session._turnId = _thisTurnId;
     // v4.12.3 — Clear any stale bypass flag from a previous aborted turn.
     // The flag is set by the bypass path right before it calls abort(),
     // read by the OLD handler's error path, and cleared here by the NEW
@@ -538,6 +614,13 @@ export async function handleMessage(ctx) {
         // (the empty-stream capturedSessionId) and the next turn loops again.
         // This is the second half of the empty-stream-loop fix.
         let sessionResetInStream = false;
+        // Cycle-3 P0 — background honesty guard tracking.
+        // `syncTaskSeenWithoutRunInBackground`: lifted from the stuckTimer.enterSync
+        //   site below — true once a Task/Agent chunk arrives with no runInBackground.
+        // `pendingBackgroundCountAtTurnStart`: snapshot before the stream so we can
+        //   compute the delta at turn end (dispatch_agent increments this counter).
+        let syncTaskSeenWithoutRunInBackground = false;
+        const pendingBackgroundCountAtTurnStart = session.pendingBackgroundCount ?? 0;
         for await (const chunk of registry.queryWithFallback(queryOpts, workspace.provider)) {
             // v5.1 — Bail as soon as requestStop() marks the session. The registry's
             // outer loop already guards against new provider attempts; this guard
@@ -554,6 +637,8 @@ export async function handleMessage(ctx) {
                 chunk.toolUseId &&
                 chunk.runInBackground !== true) {
                 stuckTimer.enterSync(chunk.toolUseId);
+                // Cycle-3 P0 — lift the signal for honesty guard (same condition)
+                syncTaskSeenWithoutRunInBackground = true;
             }
             else if (chunk.type === "tool_result" && chunk.toolUseId) {
                 // Any tool_result may match a pending sync entry. Set.delete is
@@ -710,19 +795,66 @@ export async function handleMessage(ctx) {
                     break;
             }
         }
-        // v5.1 stop: user stopped this query — do NOT finalize partial output
-        // as a successful answer, no 👍, no history commit. The stop trigger
-        // (/cancel | /stopall | ⛔ button) already acknowledged to the user.
-        // The `finally` still runs (clears isProcessing/_qHandle/_stopRequested
-        // + typing indicator).
-        if (session._stopRequested) {
-            return;
+        // Cycle-3 P0 — background honesty guard.
+        // If the turn ran a sync Task/Agent (blocking) and no real detach happened
+        // (no dispatch_agent, no pendingBackgroundCount increase), append one
+        // truthful notice so the user is never left with a false async promise.
+        // This fires only on "normal" turn endings — bypass-abort and user-stop
+        // are handled below and don't need the notice (neither promises async).
+        if (!bypassAborted &&
+            !timedOut &&
+            !session._stopRequested &&
+            detectUndetachedBackgroundClaim({
+                taskChunkSeenWithoutRunInBackground: syncTaskSeenWithoutRunInBackground,
+                dispatchAgentFired: false, // used purely via pendingBackgroundDelta below
+                pendingBackgroundDelta: (session.pendingBackgroundCount ?? 0) - pendingBackgroundCountAtTurnStart,
+            })) {
+            try {
+                await ctx.reply(t("bot.background.syncNotice", session.language));
+            }
+            catch {
+                /* harmless — notice is best-effort */
+            }
         }
         if (bypassAborted) {
             // v4.12.3 — Bypass path took over; don't finalize, don't react 👍.
             // Just clean up and return. The finally block still fires.
             return;
         }
+        // A3 — Suppress-or-finalize gate for stopped turns.
+        //
+        // shouldSuppressFinalSend is the SINGLE gate controlling whether finalize runs:
+        //
+        //   stop + no visible text (suppress=true):
+        //     Skip finalize and all side-effects. Nothing reached the user — correct.
+        //     The stop trigger (/cancel | /stopall | ⛔) already acknowledged this.
+        //     The `finally` still runs (clears isProcessing/_qHandle/_stopRequested
+        //     + typing indicator).
+        //
+        //   stop + visible text already sent (suppress=false, _stopRequested truthy):
+        //     The no-retract invariant applies — partial output already shown must not
+        //     be left visually unfinished. Run streamer.finalize to flush the throttle
+        //     timer and drop the status line, then return BEFORE the completed-answer
+        //     side-effects (👍 / broadcastResponseDone / addToHistory). A stopped turn
+        //     is NOT a successfully completed turn.
+        //
+        //   no stop (suppress=false, _stopRequested falsy):
+        //     Normal path — fall through to finalize + all side-effects.
+        if (shouldSuppressFinalSend({
+            stopRequested: session._stopRequested,
+            visibleTextAlreadySent: streamer.hasSentText,
+        })) {
+            // Branch A: stop + no visible text → suppress entirely.
+            return;
+        }
+        if (session._stopRequested && streamer.hasSentText) {
+            // Branch B: stop + visible text already sent → finalize the partial cleanly
+            // (flushes throttle timer, clears status line) but do NOT emit the
+            // completed-answer signals or commit to history.
+            await streamer.finalize(finalText);
+            return;
+        }
+        // Branch C: normal (no stop) — fall through.
         await streamer.finalize(finalText);
         emit("message:sent", { userId, text: finalText, platform: "telegram" });
         // v4.5.0: tell observers the response is complete.
@@ -790,25 +922,36 @@ export async function handleMessage(ctx) {
     finally {
         stuckTimer.cancel();
         clearInterval(typingInterval);
-        session.isProcessing = false;
-        session.abortController = null;
-        // v5.1 — Clear stop-hardening state so the next turn starts clean.
-        session._qHandle = null;
-        session._stopRequested = null;
-        // v5.2 — Close and clear the SteerChannel; reset per-turn ack flag.
-        try {
-            session._steerChannel?.close();
-        }
-        catch { /* ignore */ }
-        session._steerChannel = null;
-        session._steerAckSentThisTurn = false;
-        // v5.1 — Remove the ⛔ Stop control message (sent at processing start).
-        // Best-effort: if it was already deleted or the bot lacks permission, ignore.
-        if (stopMsgId !== null) {
+        // C-H2 — Single-writer guard: only reset lifecycle fields if this turn's
+        // token still matches the session's current token.  If requestStop fired
+        // mid-turn and a NEW turn has already started (and stamped a new _turnId),
+        // then _turnId !== _thisTurnId and we SKIP the reset — the new turn owns
+        // these fields.  _qHandle and _stopRequested are included in the gate:
+        // requestStop already nulled _qHandle before returning (after interruptQuery),
+        // but if a new turn started and re-populated _qHandle via onQueryHandle we
+        // must NOT null it here — that would break Cycle-1 stop teeth for the new turn.
+        if (session._turnId === _thisTurnId) {
+            // A2 — Remove the ⛔ Stop control message as the FIRST action when the
+            // turn ends, so the stale button disappears before any post-turn work.
+            // Best-effort: if it was already deleted or the bot lacks permission, ignore.
+            if (stopMsgId !== null) {
+                try {
+                    await ctx.api.deleteMessage(ctx.chat.id, stopMsgId);
+                }
+                catch { /* harmless grammy race */ }
+            }
+            session.isProcessing = false;
+            session.abortController = null;
+            // v5.2 — Close and clear the SteerChannel; reset per-turn ack flag.
             try {
-                await ctx.api.deleteMessage(ctx.chat.id, stopMsgId);
+                session._steerChannel?.close();
             }
-            catch { /* harmless grammy race */ }
+            catch { /* ignore */ }
+            session._steerChannel = null;
+            session._steerAckSentThisTurn = false;
+            session._qHandle = null; // safe: token matches → no newer turn owns this
+            session._stopRequested = null; // safe: token matches → no newer turn has set this
+            session._turnId = null;
         }
         // Check for queued messages — they'll be prepended to the next real message
         // Queue stays in session and gets consumed on next handleMessage call

package/dist/i18n.js

@@ -331,6 +331,14 @@ const strings = {
         es: "(externo, activo)",
         fr: "(externe, en cours)",
     },
+    // background honesty notice — emitted when a sync Task blocked the turn
+    // (Cycle-3 P0 fix: don't falsely promise "you can keep chatting")
+    "bot.background.syncNotice": {
+        en: "ℹ️ That ran inline and took a while — I couldn't take new messages until it finished.",
+        de: "ℹ️ Das lief inline und hat eine Weile gedauert — ich konnte währenddessen keine neuen Nachrichten entgegennehmen.",
+        es: "ℹ️ Eso se ejecutó en línea y tardó un rato — no pude recibir nuevos mensajes hasta que terminó.",
+        fr: "ℹ️ Cela s'est exécuté en ligne et a pris un moment — je ne pouvais pas recevoir de nouveaux messages tant que ce n'était pas terminé.",
+    },
     // live steering ack (Task 4 — btw feature)
     "bot.steer.ack": {
         en: "📨 Noted — Alvin will factor that in without restarting.",
@@ -338,6 +346,13 @@ const strings = {
         es: "📨 Anotado — Alvin lo tendrá en cuenta sin reiniciar.",
         fr: "📨 Noté — Alvin en tiendra compte sans redémarrer.",
     },
+    // C-L2: steer buffer full — honest reply when the steer cap is reached
+    "bot.steer.bufferFull": {
+        en: "⚠️ Steer buffer full — this message wasn't queued. Alvin is still running; try again in a moment.",
+        de: "⚠️ Steer-Puffer voll — diese Nachricht wurde nicht übernommen. Alvin läuft noch; versuch es gleich nochmal.",
+        es: "⚠️ Búfer de dirección lleno — este mensaje no se añadió. Alvin sigue en marcha; inténtalo de nuevo en un momento.",
+        fr: "⚠️ Tampon de direction plein — ce message n'a pas été pris en compte. Alvin tourne toujours ; réessaie dans un instant.",
+    },
     // /cancel
     "bot.cancel.cancelling": {
         en: "Cancelling request…",
@@ -363,6 +378,12 @@ const strings = {
         es: "⛔ Detenido",
         fr: "⛔ Arrêté",
     },
+    "bot.cancel.alreadyDone": {
+        en: "Nothing running — that already finished.",
+        de: "Nichts läuft — das war schon fertig.",
+        es: "Nada en curso — eso ya terminó.",
+        fr: "Rien en cours — c'était déjà terminé.",
+    },
     // /model
     "bot.model.chooseHeader": {
         en: "🤖 *Choose model:*",

package/dist/index.js

@@ -81,6 +81,18 @@ import { MEMORY_DIR as SEC_MEM_DIR, DATA_DIR as SEC_DATA_DIR } from "./paths.js"
             console.warn(`   ${r.path}: ${r.error}`);
         }
     }
+    // M5: Ensure DATA_DIR itself is 0700 (owner-only traverse). ensureDataDirs()
+    // above handles new installs; this belt-and-suspenders catches the case where
+    // the dir was created by a pre-M5 version with 0755 and the bot is restarting.
+    if (process.platform !== "win32") {
+        try {
+            const { chmodSync } = await import("fs");
+            chmodSync(SEC_DATA_DIR, 0o700);
+        }
+        catch {
+            // Best-effort — network filesystems may not support chmod
+        }
+    }
 }
 // 4. Crash-loop brake check — if we've crashed N times in a short window,
 //    refuse to start, write an alert file, and unload our LaunchAgent so
@@ -175,7 +187,7 @@ import { loadSkills } from "./services/skills.js";
 import { loadHooks } from "./services/hooks.js";
 import { registerShutdownHandler } from "./services/restart.js";
 import { cancelAllSubAgents } from "./services/subagents.js";
-import { startWatchdog, stopWatchdog, checkCrashLoopBrake } from "./services/watchdog.js";
+import { startWatchdog, stopWatchdog, checkCrashLoopBrake, markExpectedRestart } from "./services/watchdog.js";
 import { getRegistry } from "./engine.js";
 import { scanAssets } from "./services/asset-index.js";
 // Scan asset directory and generate INDEX.json + INDEX.md
@@ -371,6 +383,12 @@ const shutdown = async () => {
         return;
     isShuttingDown = true;
     console.log("Graceful shutdown initiated...");
+    // Mark the imminent exit as an intentional restart so the next boot's
+    // decideBrakeAction does not count it as a crash. This covers launchctl
+    // unload/load (SIGTERM from launchd) in addition to /restart and /update
+    // which call markExpectedRestart() themselves before process.exit(0).
+    // Must run before stopWatchdog() (which just clears timers, not the beacon).
+    markExpectedRestart();
     // E2: shutdown-notification — await the async cancellation so running
     // agents can post a cancellation message to Telegram before the bot
     // stops. Capped at 5s internally so a hang can't block shutdown.