alvin-bot 5.1.8 → 5.3.0

package/CHANGELOG.md

@@ -2,6 +2,70 @@
 
 All notable changes to Alvin Bot are documented here.
 
+## [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
+
+You could always type `/cancel`, but it rarely felt like anything
+happened: the bot kept "thinking" for a while and the answer often
+still arrived. That's fixed. When you stop a task, the bot now bails
+out immediately instead of quietly trying its backup brains one after
+another in the background. Press stop — it stops.
+
+### A one-tap ⛔ Stop button on every running task
+
+No more remembering or typing a command mid-thought. While Alvin is
+working you'll see a ⛔ Stop button right there on the status message.
+One tap, the task ends, the button flips to "⛔ Gestoppt". Mistyped
+your request or changed your mind? It's one thumb away — and it works
+the same in Telegram, Slack, Discord and WhatsApp.
+
+### New `/stopall` — pull the plug on everything
+
+`/cancel` (and the button) stop the task you're watching but let
+already-running background helpers finish and report back later. When
+you want a hard reset — *"forget all of it"* — use the new `/stopall`:
+it stops the current task, terminates the background sub-agents it
+spawned, and clears anything queued behind it. Nothing comes back to
+surprise you afterwards.
+
+Under the hood this was a careful, well-tested hardening of the whole
+stop path — verified end-to-end on a clean second machine before
+shipping. No setup or config needed; it just works.
+
 ## [5.1.8] — 2026-05-17
 
 ### Interrupted jobs auto-resume after a controlled restart

package/dist/config.js

@@ -83,3 +83,11 @@ export const config = {
     // Exec Security
     execSecurity: (process.env.EXEC_SECURITY || "full"),
 };
+/**
+ * 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/commands.js

@@ -2,7 +2,7 @@ import { InlineKeyboard, InputFile } from "grammy";
 import fs from "fs";
 import path, { resolve } from "path";
 import os from "os";
-import { getSession, resetSession, markSessionDirty, getTelegramWorkspace, setTelegramWorkspace } from "../services/session.js";
+import { getSession, buildSessionKey, resetSession, markSessionDirty, getTelegramWorkspace, setTelegramWorkspace } from "../services/session.js";
 import { listWorkspaces, getWorkspace } from "../services/workspaces.js";
 import { getRegistry } from "../engine.js";
 import { reloadSoul } from "../services/personality.js";
@@ -32,6 +32,8 @@ import { getReleaseHighlights } from "../services/release-highlights.js";
 import { runCleanup, getCleanupPolicy } from "../services/disk-cleanup.js";
 import { getHealthStatus, isFailedOver } from "../services/heartbeat.js";
 import { t, LOCALE_NAMES, LOCALE_FLAGS } from "../i18n.js";
+import { requestStop, interruptQuery } from "../services/stop-controller.js";
+import { killSessionDetachedAgents, cancelPendingForSession } from "../services/async-agent-watcher.js";
 // Kick off auto-update loop on module load if the persistent flag is set.
 // Doing this as a module side-effect avoids touching the bot entry point.
 if (getAutoUpdate()) {
@@ -1896,18 +1898,66 @@ export function registerCommands(bot) {
         }
         await ctx.answerCallbackQuery();
     });
+    /** Build StopDeps for a session — wires the three stop side-effects. */
+    function buildStopDeps(session) {
+        return {
+            interruptQuery: () => interruptQuery(session),
+            killDetachedAgents: () => killSessionDetachedAgents(session),
+            clearPendingForSession: (k) => cancelPendingForSession(k),
+        };
+    }
     bot.command("cancel", async (ctx) => {
         const userId = ctx.from.id;
-        const session = getSession(userId);
+        // Use buildSessionKey so the resolved session is always the SAME object
+        // that message.ts created (and that registered pending agents under this key).
+        // In per-user mode this equals String(userId); in per-channel modes it
+        // incorporates chatId — matching the key used for the ⛔ button payload.
+        const sessionKey = buildSessionKey("telegram", ctx.chat.id, userId);
+        const session = getSession(sessionKey);
         const lang = session.language;
-        if (session.isProcessing && session.abortController) {
-            session.abortController.abort();
+        if (session.isProcessing) {
+            requestStop(session, "soft", buildStopDeps(session));
             await ctx.reply(t("bot.cancel.cancelling", lang));
         }
         else {
             await ctx.reply(t("bot.cancel.noRunning", lang));
         }
     });
+    // /stopall — hard stop: interrupt query + kill detached agents + clear queue + cancel pending.
+    bot.command("stopall", async (ctx) => {
+        const userId = ctx.from.id;
+        // Same canonical-key resolution as /cancel above — must match message.ts.
+        const sessionKey = buildSessionKey("telegram", ctx.chat.id, userId);
+        const session = getSession(sessionKey);
+        const lang = session.language;
+        if (session.isProcessing) {
+            requestStop(session, "hard", buildStopDeps(session));
+            await ctx.reply(t("bot.cancel.stoppedAll", lang));
+        }
+        else {
+            await ctx.reply(t("bot.cancel.noRunning", lang));
+        }
+    });
+    // stop: inline keyboard callback — soft stop triggered from the ⛔ button
+    // sent alongside the processing indicator in the message handler.
+    // Payload format: "stop:<sessionKey>" where sessionKey = String(userId) in
+    // default per-user mode (mirrors buildSessionKey used in message.ts).
+    bot.callbackQuery(/^stop:(.+)$/, async (ctx) => {
+        const sessionKey = ctx.match[1];
+        const session = getSession(sessionKey);
+        const lang = session.language;
+        if (session.isProcessing) {
+            requestStop(session, "soft", buildStopDeps(session));
+        }
+        try {
+            await ctx.answerCallbackQuery({ text: t("bot.cancel.stoppedToast", lang) });
+        }
+        catch { /* harmless grammy race */ }
+        try {
+            await ctx.editMessageReplyMarkup({});
+        }
+        catch { /* harmless grammy race — message may already be gone */ }
+    });
     // /restart — trigger a PM2-managed restart by exiting the process.
     // The PM2 supervisor picks up the exit and respawns with --update-env.
     bot.command("restart", async (ctx) => {

package/dist/handlers/message.js

@@ -1,4 +1,4 @@
-import { InputFile } from "grammy";
+import { InputFile, InlineKeyboard } from "grammy";
 import fs from "fs";
 import { getSession, addToHistory, trackProviderUsage, buildSessionKey, getTelegramWorkspace, markSessionDirty } from "../services/session.js";
 import { resolveWorkspaceOrDefault, getWorkspace } from "../services/workspaces.js";
@@ -19,6 +19,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 +121,29 @@ 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)
+        return "steer";
+    return "queue";
+}
 /** React to a message with an emoji. Silently fails if reactions aren't supported. */
 async function react(ctx, emoji) {
     try {
@@ -172,11 +197,22 @@ 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,
+            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 +230,23 @@ 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.
+            session._steerChannel.push(text);
+            await react(ctx, "📨");
+            if (!session._steerAckSentThisTurn) {
+                try {
+                    await ctx.reply(t("bot.steer.ack", session.language));
+                }
+                catch {
+                    /* harmless grammy race */
+                }
+                session._steerAckSentThisTurn = true;
+            }
+            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
@@ -229,6 +282,18 @@ export async function handleMessage(ctx) {
     // for the rest of this function (it's mutated from the bypass path in
     // another handler invocation, so the type stays `boolean | undefined`).
     delete session._bypassAbortFired;
+    // v5.1 — Send a lightweight control message with an inline ⛔ Stop button.
+    // Payload "stop:<sessionKey>" matches the callbackQuery handler in commands.ts.
+    // Cleaned up (deleted) in the finally block regardless of how the turn ends.
+    // One message only — do NOT send if the chat can't receive replies.
+    let stopMsgId = null;
+    try {
+        const stopMsg = await ctx.reply("⏳", {
+            reply_markup: new InlineKeyboard().text("⛔ Stop", `stop:${sessionKey}`),
+        });
+        stopMsgId = stopMsg.message_id;
+    }
+    catch { /* harmless — typing indicator remains, button is best-effort */ }
     const streamer = new TelegramStreamer(ctx.chat.id, ctx.api, ctx.message?.message_id);
     let finalText = "";
     let timedOut = false;
@@ -444,7 +509,22 @@ export async function handleMessage(ctx) {
                 userId,
                 sessionKey,
             } : undefined,
+            // 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
@@ -459,6 +539,11 @@ export async function handleMessage(ctx) {
         // This is the second half of the empty-stream-loop fix.
         let sessionResetInStream = false;
         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
+            // drains the current generator's remaining chunks immediately.
+            if (session._stopRequested)
+                break;
             // v4.12.1 — Update pending-sync-task state FIRST so the timer's
             // next reset picks up the new state. This ordering is load-bearing:
             // reversing it means the timer rearms with stale state. A sync
@@ -625,6 +710,14 @@ 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;
+        }
         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.
@@ -699,6 +792,24 @@ export async function handleMessage(ctx) {
         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) {
+            try {
+                await ctx.api.deleteMessage(ctx.chat.id, stopMsgId);
+            }
+            catch { /* harmless grammy race */ }
+        }
         // 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,13 @@ const strings = {
         es: "(externo, activo)",
         fr: "(externe, en cours)",
     },
+    // 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.",
+    },
     // /cancel
     "bot.cancel.cancelling": {
         en: "Cancelling request…",
@@ -344,6 +351,18 @@ const strings = {
         es: "No hay ninguna solicitud en curso.",
         fr: "Aucune requête en cours.",
     },
+    "bot.cancel.stoppedAll": {
+        en: "⛔ Stopped everything — running task, sub-agents and queue cancelled.",
+        de: "⛔ Alles gestoppt — laufende Aufgabe, Sub-Agents und Warteschlange abgebrochen.",
+        es: "⛔ Todo detenido — tarea en curso, sub-agentes y cola cancelados.",
+        fr: "⛔ Tout arrêté — tâche en cours, sous-agents et file annulés.",
+    },
+    "bot.cancel.stoppedToast": {
+        en: "⛔ Stopped",
+        de: "⛔ Gestoppt",
+        es: "⛔ Detenido",
+        fr: "⛔ Arrêté",
+    },
     // /model
     "bot.model.chooseHeader": {
         en: "🤖 *Choose model:*",

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,
@@ -206,10 +208,24 @@ export class ClaudeSDKProvider {
                     ...(fallbackModel ? { fallbackModel } : {}),
                 },
             });
+            // v5.1 — Expose the SDK query handle to the caller so requestStop()
+            // can interrupt it via q.interrupt() + transport.process.kill().
+            try {
+                options.onQueryHandle?.(q);
+            }
+            catch { /* non-fatal */ }
             let accumulatedText = "";
             let capturedSessionId = options.sessionId || "";
             let localToolUseCount = 0;
             for await (const message of q) {
+                // v5.1 — Bail immediately if the caller set abortSignal while iterating.
+                if (options.abortSignal?.aborted) {
+                    try {
+                        q.return?.();
+                    }
+                    catch { /* ignore */ }
+                    break;
+                }
                 // System init — capture session ID
                 if (message.type === "system" && "subtype" in message && message.subtype === "init") {
                     const sysMsg = message;

package/dist/providers/registry.js

@@ -123,6 +123,12 @@ export class ProviderRegistry {
         }
         const errors = [];
         for (const key of chain) {
+            // v5.1 PRIMARY FIX — bail before attempting any provider if the caller
+            // has already aborted. Without this guard, the outer fallback loop kept
+            // trying successive providers (e.g. Ollama) even after abort(), leaving
+            // the typing indicator on and wasting resources.
+            if (options.abortSignal?.aborted)
+                break;
             const provider = this.providers.get(key);
             if (!provider)
                 continue;
@@ -234,6 +240,12 @@ export class ProviderRegistry {
             // If we got here without done or error, something's off
             return;
         }
+        // v5.1 stop: clean user cancellation — the outer loop broke on an
+        // aborted signal with nothing attempted. Don't surface a misleading
+        // "no provider" error; end the generator quietly (the consumer's
+        // _stopRequested handling owns the user-facing acknowledgement).
+        if (options.abortSignal?.aborted)
+            return;
         // All providers failed — show specific errors
         const errorDetail = errors.map(e => `  ${e.key}: ${e.error}`).join("\n");
         yield {

package/dist/services/alvin-dispatch.js

@@ -99,6 +99,9 @@ export function dispatchDetachedAgent(input) {
     // 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.
+    // child.pid is captured here (before unref) so killSessionDetachedAgents
+    // can send SIGTERM to the process. child.pid may be undefined if the OS
+    // failed to assign a PID (extremely rare); registerPendingAgent tolerates it.
     registerPendingAgent({
         agentId,
         outputFile,
@@ -109,6 +112,7 @@ export function dispatchDetachedAgent(input) {
         toolUseId: null,
         sessionKey: input.sessionKey,
         platform: input.platform,
+        pid: child.pid,
     });
     // Increment the session's pendingBackgroundCount so the main handler
     // knows a background task is in flight (same signal path as SDK's

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

@@ -131,6 +131,7 @@ export function registerPendingAgent(input) {
         toolUseId: input.toolUseId,
         sessionKey: input.sessionKey,
         platform: input.platform,
+        pid: input.pid,
     };
     enforcePendingCap();
     pending.set(input.agentId, entry);
@@ -281,6 +282,66 @@ async function deliverAsFailure(entry, status, error) {
     decrementPendingCount(entry.sessionKey);
 }
 // ── Test helpers ──────────────────────────────────────────────────
+/**
+ * v5.1 — Kill detached sub-agent processes scoped to a session.
+ *
+ * Reads the canonical session key from `session.sessionKey` (stamped by
+ * getSession() / loadPersistedSessions() — always a real string, never null
+ * after the v5.1.x fix). Iterates watcher entries whose `sessionKey` matches
+ * and calls `killFn(entry.pid)` for entries that have a pid.
+ *
+ * The function accepts an injectable `killFn` for testability. The default
+ * implementation sends SIGTERM; callers in tests pass a spy.
+ *
+ * Never throws — all per-entry errors are swallowed.
+ */
+export function killSessionDetachedAgents(session, killFn = (p) => {
+    try {
+        process.kill(p, "SIGTERM");
+    }
+    catch { /* already gone */ }
+}) {
+    // Use session.sessionKey — the real canonical key stamped by getSession().
+    // Before v5.1.x this field did not exist on UserSession, causing a silent
+    // no-op; the fix in session.ts guarantees it is always a non-empty string.
+    const key = session.sessionKey ?? null;
+    if (key === null)
+        return;
+    for (const entry of pending.values()) {
+        if (entry.sessionKey !== key)
+            continue;
+        if (typeof entry.pid === "number") {
+            try {
+                killFn(entry.pid);
+            }
+            catch { /* best-effort */ }
+        }
+    }
+}
+/**
+ * v5.1 — Mark/remove all pending watcher entries for a session so the
+ * watcher does NOT deliver them after a hard stop.
+ *
+ * Mirrors the pattern used in pollOnce(): remove from the in-memory map
+ * and persist immediately. This is a remove-not-flag approach because
+ * there is no `cancelled` flag on PendingAsyncAgent and adding one would
+ * require touching all poll-cycle delivery paths.
+ *
+ * Scoped strictly to entries whose `sessionKey` matches — never global,
+ * never name-based. Never throws.
+ */
+export function cancelPendingForSession(sessionKey) {
+    let changed = false;
+    for (const [id, entry] of pending.entries()) {
+        if (entry.sessionKey === sessionKey) {
+            pending.delete(id);
+            changed = true;
+        }
+    }
+    if (changed) {
+        saveToDisk();
+    }
+}
 /** Test-only: drop in-memory state. Doesn't touch disk. */
 export function __resetForTest() {
     pending.clear();

package/dist/services/session-persistence.js

@@ -171,11 +171,19 @@ export function loadPersistedSessions() {
         // Build a UserSession from the persisted shape, filling defaults for any
         // fields added in newer schema versions.
         const restored = {
+            // v5.1.x — Canonical registry key stamped so stop-controller and watcher
+            // helpers can read session.sessionKey regardless of how the session was
+            // created (direct access or rehydrated from disk).
+            sessionKey: key,
             sessionId: persisted.sessionId ?? null,
             workingDir: persisted.workingDir ?? process.cwd(),
             workspaceName: persisted.workspaceName ?? null,
             isProcessing: false,
             abortController: null,
+            _stopRequested: null,
+            _qHandle: null,
+            _steerChannel: null,
+            _steerAckSentThisTurn: false,
             lastActivity: persisted.lastActivity ?? Date.now(),
             startedAt: persisted.startedAt ?? Date.now(),
             totalCost: persisted.totalCost ?? 0,

package/dist/services/session.js

@@ -74,11 +74,16 @@ export function getSession(key) {
     let session = sessions.get(k);
     if (!session) {
         session = {
+            sessionKey: k,
             sessionId: null,
             workingDir: config.defaultWorkingDir,
             workspaceName: null,
             isProcessing: false,
             abortController: null,
+            _stopRequested: null,
+            _qHandle: null,
+            _steerChannel: null,
+            _steerAckSentThisTurn: false,
             lastActivity: Date.now(),
             startedAt: Date.now(),
             totalCost: 0,
@@ -106,6 +111,15 @@ export function getSession(key) {
         // Touch lastActivity on every access so the cleanup interval
         // never kills a session that's still being interacted with.
         session.lastActivity = Date.now();
+        // Idempotent: stamp sessionKey on existing sessions that predate this field
+        // (e.g. sessions loaded from persistence before the field existed).
+        if (!session.sessionKey) {
+            session.sessionKey = k;
+        }
+        if (session._steerChannel === undefined)
+            session._steerChannel = null;
+        if (session._steerAckSentThisTurn === undefined)
+            session._steerAckSentThisTurn = false;
     }
     return session;
 }

package/dist/services/steer-channel.js

@@ -0,0 +1,41 @@
+const DEFAULT_CAP = 20;
+export class SteerChannel {
+    cap;
+    buf = [];
+    closed = false;
+    resolveNext = null;
+    constructor(cap = DEFAULT_CAP) {
+        this.cap = cap;
+    }
+    push(text) {
+        if (this.closed)
+            return;
+        if (this.buf.length >= this.cap) {
+            console.warn(`[steer-channel] cap ${this.cap} reached — dropping steer message`);
+            return;
+        }
+        this.buf.push({ type: "user", message: { role: "user", content: text }, parent_tool_use_id: null });
+        const r = this.resolveNext;
+        this.resolveNext = null;
+        r?.();
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        const r = this.resolveNext;
+        this.resolveNext = null;
+        r?.();
+    }
+    async *[Symbol.asyncIterator]() {
+        while (true) {
+            if (this.buf.length > 0) {
+                yield this.buf.shift();
+                continue;
+            }
+            if (this.closed)
+                return;
+            await new Promise((res) => { this.resolveNext = res; });
+        }
+    }
+}

package/dist/services/stop-controller.js

@@ -0,0 +1,52 @@
+/** Teeth: interrupt the running SDK query. SDK hides the pid, so we use
+ *  its own interrupt() control-message + transport process kill fallback.
+ *  Both best-effort; never throws. */
+export function interruptQuery(session) {
+    try {
+        session._qHandle?.interrupt?.();
+    }
+    catch { /* already finished */ }
+    try {
+        session._qHandle?.transport?.process?.kill?.();
+    }
+    catch { /* n/a */ }
+}
+/**
+ * Single shared stop primitive. Synchronous, idempotent, NEVER throws into
+ * the caller. soft = abort + interrupt running query + reset JS state.
+ * hard = soft + kill detached sub-agents + clear queue + cancel pending.
+ *
+ * Post Task-1: the SDK hides the subprocess PID, so the teeth are
+ * q.interrupt() (via deps.interruptQuery), NOT a process-group SIGKILL.
+ */
+export function requestStop(session, tier, deps) {
+    // 1. Signal abort (best-effort; already fast per Task-1 evidence).
+    try {
+        session.abortController?.abort();
+    }
+    catch { /* idempotent */ }
+    // 2. Teeth — interrupt the running SDK query.
+    try {
+        deps.interruptQuery();
+    }
+    catch { /* already finished / never throw */ }
+    // 3. Mark stop so consumer loop + provider + registry fallback bail.
+    session._stopRequested = tier;
+    // 4. Hard tier extras.
+    if (tier === "hard") {
+        try {
+            deps.killDetachedAgents();
+        }
+        catch { /* best-effort */ }
+        if (Array.isArray(session.messageQueue))
+            session.messageQueue.length = 0;
+        try {
+            deps.clearPendingForSession(session.sessionKey);
+        }
+        catch { /* best-effort */ }
+    }
+    // 5. Deterministic JS-state teardown.
+    session.isProcessing = false;
+    session.abortController = null;
+    session._qHandle = null;
+}

package/package.json

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