alvin-bot 5.2.0 → 5.4.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,79 @@
 
 All notable changes to Alvin Bot are documented here.
 
+## [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
+
+Until now, a message you sent while Alvin was busy had only two
+outcomes: it waited in line until the current task finished, or it
+threw the task away and started over. Now there's a third, much
+better one. Drop a quick *"btw, also check the other folder"* or
+*"actually, use the live data not the test data"* mid-task and Alvin
+takes it in **while keeping everything it has already done** — exactly
+like leaning over to a colleague who's already working and adding one
+more thing. No restart, no lost progress.
+
+### A quiet 📨 so you know it landed
+
+When your mid-task note is picked up, Alvin reacts with a 📨 on your
+message and, the first time per task, adds one short line so you know
+it was taken on board without derailing what it's doing. After that
+it's just the reaction — no chatter, no spam while it works.
+
+### Stop still always wins
+
+Steering never overrides stopping. The ⛔ Stop button, `/cancel` and
+`/stopall` behave exactly as before and always take precedence — a
+mid-task note can never bring back a task you've stopped. If you'd
+rather keep the old "queue it until done" behaviour, you can switch
+steering off with a single setting; it's on by default for everyone.
+
+Live steering works with the Claude engine; with other AI providers
+your message safely falls back to the previous queue behaviour, so
+nothing breaks. As always, this shipped only after a full end-to-end
+verification and a stress test on a clean separate machine.
+
 ## [5.2.0] — 2026-05-17
 
 ### Stop now actually means stop — instantly
@@ -396,8 +469,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
@@ -2299,7 +2372,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,6 +82,15 @@ 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.
+ * Re-reads process.env each call so tests can override without module reloads.
+ */
+export function isSteeringEnabled() {
+    const v = process.env.STEERING_ENABLED;
+    return v !== "false" && v !== "0";
+}

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";
@@ -19,6 +20,8 @@ import { isHarmlessTelegramError } from "../util/telegram-error-filter.js";
 import { handleToolResultChunk } from "./async-agent-chunk-handler.js";
 import { createStuckTimer } from "./stuck-timer.js";
 import { shouldBypassQueue, shouldBypassSdkResume, waitUntilProcessingFalse, } from "./background-bypass.js";
+import { SteerChannel } from "../services/steer-channel.js";
+import { isSteeringEnabled } from "../config.js";
 /**
  * Stuck-only timeout — NO absolute cap.
  *
@@ -119,6 +122,53 @@ const TOOL_ICONS = {
     WebFetch: "📡",
     Task: "🤖",
 };
+// ── v5.2 live steering — pure routing helper ─────────────────────────────────
+/**
+ * Decide how a mid-task message (arriving while `session.isProcessing`) should
+ * be handled. Evaluated in the `if (session.isProcessing)` guard before any
+ * side-effects, so the caller can branch cleanly.
+ *
+ * Decision priority:
+ *   1. "bypass"  — background-agent bypass path (pre-existing Cycle-1 logic)
+ *   2. "steer"   — push into live SteerChannel (claude-sdk + steering on + channel open)
+ *   3. "queue"   — normal queue behavior (all other cases)
+ *
+ * Defensive: if `isProcessing` is false the helper is being called incorrectly;
+ * it returns "queue" so the caller falls through to existing behavior.
+ */
+export function decideMidTaskRouting(args) {
+    if (!args.isProcessing)
+        return "queue";
+    if (args.shouldBypass)
+        return "bypass";
+    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 {
@@ -172,11 +222,23 @@ export async function handleMessage(ctx) {
         // the new message gets processed immediately. The background task
         // itself continues in its detached subprocess; the async-agent watcher
         // delivers the result via subagent-delivery.ts when ready.
-        if (shouldBypassQueue({
+        //
+        // v5.2 — decideMidTaskRouting unifies bypass / steer / queue in one place.
+        const _midTaskBypass = shouldBypassQueue({
             isProcessing: session.isProcessing,
             pendingBackgroundCount: session.pendingBackgroundCount,
             abortController: session.abortController,
-        })) {
+        });
+        const _midTaskProviderIsSdk = getRegistry().getActive().config.type === "claude-sdk";
+        const _midTaskRoute = decideMidTaskRouting({
+            isProcessing: true,
+            providerIsClaudeSdk: _midTaskProviderIsSdk,
+            steeringEnabled: isSteeringEnabled(),
+            hasSteerChannel: !!session._steerChannel,
+            hasLiveSdkQuery: !!session._qHandle, // C-H3: require a live SDK query handle
+            shouldBypass: _midTaskBypass,
+        });
+        if (_midTaskRoute === "bypass") {
             console.log(`[v4.12.3 bypass] aborting blocked query for ${sessionKey} — ` +
                 `${session.pendingBackgroundCount} background agent(s) pending`);
             // Mark the abort as a bypass so the old handler's error branch
@@ -194,6 +256,35 @@ export async function handleMessage(ctx) {
             await waitUntilProcessingFalse(session, 5000);
             // Fall through to start a fresh query below.
         }
+        else if (_midTaskRoute === "steer") {
+            // 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.
+            // 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.bufferFull", session.language));
+                }
+                catch {
+                    /* harmless grammy race */
+                }
+            }
+            return;
+        }
         else {
             // Normal queue behavior. v4.12.3 — emit a text reply in addition
             // to the reaction so the user actually sees that their message
@@ -221,6 +312,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
@@ -459,6 +557,19 @@ export async function handleMessage(ctx) {
             // v5.1 — Store the SDK query handle so requestStop() can interrupt it.
             onQueryHandle: (q) => { session._qHandle = q; },
         };
+        // v5.2 — btw live steering: seed SteerChannel at turn start so mid-task
+        // user messages can be pushed in while this query is running. Only for
+        // claude-sdk (the only provider that supports streaming-input prompts).
+        // The initial bridged prompt is pushed first so the channel sequence is:
+        //   [bridgedPrompt, <any mid-task messages>, <close on finally>]
+        // queryOpts.steerChannel is set so the provider uses the channel as the
+        // prompt source. queryOpts.prompt is kept as-is for non-SDK fallback paths
+        // (providers that don't support steerChannel ignore it and use prompt).
+        if (isSDK && isSteeringEnabled()) {
+            session._steerChannel = new SteerChannel();
+            session._steerChannel.push(bridgedPrompt);
+            queryOpts.steerChannel = session._steerChannel;
+        }
         // Stream response from provider (with fallback)
         let lastBroadcastLen = 0;
         // Captured during tool_use chunks; consumed by tool_result chunks so
@@ -472,6 +583,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
@@ -488,6 +606,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
@@ -644,6 +764,27 @@ export async function handleMessage(ctx) {
                     break;
             }
         }
+        // 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 */
+            }
+        }
         // 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.
@@ -724,11 +865,28 @@ 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;
+        // 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) {
+            session.isProcessing = false;
+            session.abortController = 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;
+            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;
+        }
         // 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) {

package/dist/i18n.js

@@ -331,6 +331,28 @@ 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.",
+        de: "📨 Mitgenommen — Alvin berücksichtigt das, ohne abzubrechen.",
+        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…",

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

package/dist/init-data-dir.js

@@ -9,6 +9,12 @@ import { DATA_DIR, MEMORY_DIR, USERS_DIR, RUNTIME_DIR, WHATSAPP_AUTH, BACKUP_DIR
 /**
  * Create the directory structure only (no file seeding).
  * Must run BEFORE migration so directories exist for copying.
+ *
+ * M5: DATA_DIR is created with mode 0700 (owner-only traverse) so that
+ * even before the per-file chmod audit runs, any file written by the bot
+ * is not accessible by other users on multi-user systems. On Windows,
+ * chmod is a no-op — we skip it silently to avoid alarming log output,
+ * mirroring how the file-permissions audit handles win32.
  */
 export function ensureDataDirs() {
     const dirs = [
@@ -27,6 +33,17 @@ export function ensureDataDirs() {
             fs.mkdirSync(dir, { recursive: true });
         }
     }
+    // M5: Ensure the DATA_DIR itself is 0700 (owner-only). New dirs are
+    // created without an explicit mode above (inherits umask), so we chmod
+    // after creation. Windows doesn't support POSIX modes — skip silently.
+    if (process.platform !== "win32") {
+        try {
+            fs.chmodSync(DATA_DIR, 0o700);
+        }
+        catch {
+            // Best-effort — some network filesystems may not support chmod
+        }
+    }
 }
 /**
  * Seed default files for a fresh install (only if they don't exist yet).

package/dist/middleware/auth.js

@@ -1,4 +1,5 @@
 import fs from "fs";
+import crypto from "crypto";
 import { InlineKeyboard } from "grammy";
 import { config } from "../config.js";
 import { APPROVED_USERS_FILE } from "../paths.js";
@@ -43,7 +44,7 @@ export function isApprovedUser(userId) {
 const MAX_PENDING = 3;
 const pendingPairings = new Map(); // code → pairing
 function generateCode() {
-    return String(Math.floor(100000 + Math.random() * 900000));
+    return String(crypto.randomInt(100000, 1000000));
 }
 function cleanExpired() {
     const now = Date.now();
@@ -211,5 +212,22 @@ export async function authMiddleware(ctx, next) {
         return;
     }
     // ── Callback queries (inline keyboards) ─────────
+    // Only allowedUsers may trigger admin action callbacks (approve/deny).
+    // Other callbacks (e.g. pairing-mode approved users) continue through.
+    if (userId && config.allowedUsers.includes(userId)) {
+        await next();
+        return;
+    }
+    // Unknown users: silently drop admin-action callbacks to prevent
+    // approval forgery / self-approval. Non-admin callbacks from pairing-
+    // approved users in "pairing" mode are also gated here intentionally;
+    // the approve flow is an admin-only action.
+    const callbackData = ctx.callbackQuery?.data || "";
+    const isAdminCallback = /^(pair|access|wa):(approve|deny|block):/.test(callbackData);
+    if (isAdminCallback) {
+        // Silently drop — no answer (grammy will time-out the spinner client-side)
+        return;
+    }
+    // Non-admin callbacks from unknown users: pass through (e.g. inline mode)
     await next();
 }

package/dist/providers/claude-sdk-provider.js

@@ -174,7 +174,9 @@ export class ClaudeSDKProvider {
             const primaryIsHaiku = (modelOverride ?? "").toLowerCase().includes("haiku");
             const fallbackModel = primaryIsHaiku ? undefined : "haiku";
             const q = query({
-                prompt,
+                prompt: options.steerChannel
+                    ? options.steerChannel
+                    : prompt,
                 options: {
                     cwd: options.workingDir || process.cwd(),
                     abortController: internalAbortController,