alvin-bot 4.12.0 → 4.12.2

package/dist/index.js

@@ -20,6 +20,57 @@ if (hasLegacyData()) {
 }
 // 3. Seed defaults for any files that don't exist yet (fresh install)
 seedDefaults();
+// 3a. v4.12.2 — Audit + repair permissions on sensitive files. On multi-user
+//     systems, files written pre-v4.12.2 may have 0o644 / 0o666 mode — i.e.
+//     readable by other users on the same machine. This routine chmod-repairs
+//     them to 0o600 (owner read/write only) at every startup. Idempotent for
+//     already-secure files; silent no-op for missing files.
+import { auditSensitiveFiles } from "./services/file-permissions.js";
+import { ENV_FILE as SEC_ENV, SESSIONS_STATE_FILE, MEMORY_FILE, CRON_FILE as SEC_CRON } from "./paths.js";
+import { readdirSync } from "fs";
+import { resolve as pathResolve } from "path";
+import { MEMORY_DIR as SEC_MEM_DIR, DATA_DIR as SEC_DATA_DIR } from "./paths.js";
+{
+    const sensitivePaths = [SEC_ENV, SESSIONS_STATE_FILE, MEMORY_FILE, SEC_CRON];
+    // Also audit every daily-log markdown file — they contain full conversation history
+    try {
+        if (readdirSync.length !== undefined) {
+            for (const entry of readdirSync(SEC_MEM_DIR)) {
+                if (entry.endsWith(".md") && !entry.startsWith(".")) {
+                    sensitivePaths.push(pathResolve(SEC_MEM_DIR, entry));
+                }
+            }
+        }
+    }
+    catch {
+        // memory dir missing — fine
+    }
+    // Also include async-agents state, delivery queue, and sudo credentials
+    const optionalPaths = [
+        pathResolve(SEC_DATA_DIR, "state", "async-agents.json"),
+        pathResolve(SEC_DATA_DIR, "delivery-queue.json"),
+        pathResolve(SEC_DATA_DIR, "data", ".sudo-enc"),
+        pathResolve(SEC_DATA_DIR, "data", ".sudo-key"),
+        pathResolve(SEC_DATA_DIR, "data", "access.json"),
+        pathResolve(SEC_DATA_DIR, "data", "approved-users.json"),
+    ];
+    sensitivePaths.push(...optionalPaths);
+    const auditResults = auditSensitiveFiles(sensitivePaths);
+    const repaired = auditResults.filter(r => r.status === "repaired");
+    if (repaired.length > 0) {
+        console.log(`🔒 file-permissions: repaired ${repaired.length} sensitive file(s) to 0o600`);
+        for (const r of repaired) {
+            console.log(`   ${r.path} (was 0o${r.previousMode})`);
+        }
+    }
+    const errors = auditResults.filter(r => r.status === "error");
+    if (errors.length > 0) {
+        console.warn(`⚠️  file-permissions: ${errors.length} file(s) could not be repaired:`);
+        for (const r of errors) {
+            console.warn(`   ${r.path}: ${r.error}`);
+        }
+    }
+}
 // 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
 //    launchd stops retrying. Runs BEFORE any expensive init so a broken
@@ -35,9 +86,30 @@ if (!hasTelegram) {
     console.warn("⚠️  BOT_TOKEN not set — Telegram disabled. WebUI + Cron still active.");
     console.warn("   Run 'alvin-bot setup' or set BOT_TOKEN in ~/.alvin-bot/.env");
 }
-if (config.allowedUsers.length === 0 && hasTelegram) {
-    console.warn("⚠️  ALLOWED_USERS not set — nobody can message the Telegram bot yet.");
-    console.warn("   Send /start to @userinfobot on Telegram to find your ID.");
+// v4.12.2 — ALLOWED_USERS startup gate. Refuses to start when Telegram is
+// configured but no user allowlist is set, because that would leave the bot
+// open to any Telegram user with full shell/filesystem access via prompt
+// injection. See src/services/allowed-users-gate.ts for the pure decision
+// function + tests.
+{
+    const { checkAllowedUsersGate } = await import("./services/allowed-users-gate.js");
+    const gate = checkAllowedUsersGate({
+        hasTelegram,
+        allowedUsersCount: config.allowedUsers.length,
+        authMode: config.authMode,
+        insecureAcknowledged: process.env.ALVIN_INSECURE_ACKNOWLEDGED === "1",
+    });
+    if (!gate.allowed) {
+        console.error("");
+        console.error("❌ CRITICAL: Alvin Bot refusing to start.");
+        console.error("");
+        console.error("   " + gate.reason);
+        console.error("");
+        process.exit(1);
+    }
+    if (gate.warning) {
+        console.warn("⚠️  " + gate.warning);
+    }
 }
 // Check if the chosen provider has a corresponding API key.
 // Keys here MUST match the registry keys from src/providers/registry.ts

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

@@ -114,7 +114,10 @@ export class ClaudeSDKProvider {
                     allowDangerouslySkipPermissions: true,
                     env: cleanEnv,
                     settingSources: ["user", "project"],
-                    allowedTools: [
+                    // v4.12.2 — options.allowedTools can override the default full set.
+                    // Used by sub-agents with toolset="readonly"/"research" to restrict
+                    // what Claude can do. Default = full access.
+                    allowedTools: options.allowedTools ?? [
                         "Read", "Write", "Edit", "Bash", "Glob", "Grep",
                         "WebSearch", "WebFetch", "Task",
                     ],
@@ -161,6 +164,24 @@ export class ClaudeSDKProvider {
                             }
                             if ("name" in block) {
                                 localToolUseCount++;
+                                // v4.12.1 — Extract run_in_background from the raw input
+                                // object BEFORE the 500-char JSON truncation below. This is
+                                // load-bearing: for long prompts the serialized input can
+                                // exceed 500 chars, and naive post-truncation parsing would
+                                // lose the flag and misclassify sync tasks as async (→ false
+                                // 10-min abort on legitimate long-running sub-agents).
+                                // See src/handlers/stuck-timer.ts and message.ts for the
+                                // consumer side.
+                                let runInBackground;
+                                if ("input" in block &&
+                                    block.input &&
+                                    typeof block.input === "object") {
+                                    const input = block.input;
+                                    if (input.run_in_background === true)
+                                        runInBackground = true;
+                                    else if (input.run_in_background === false)
+                                        runInBackground = false;
+                                }
                                 // Serialise the tool input (parameters) so the message
                                 // handler can surface detail for specific tools — most
                                 // importantly the "Task" tool where `input.description`
@@ -176,10 +197,17 @@ export class ClaudeSDKProvider {
                                         // unserializable — skip
                                     }
                                 }
+                                // Tool-use blocks in the Anthropic API always have an `id`
+                                // at runtime, but the SDK's .d.ts shape doesn't guarantee it
+                                // — defensive cast. Used by the task-aware stuck timer to
+                                // correlate tool_use → tool_result for sync tracking.
+                                const toolUseId = block.id;
                                 yield {
                                     type: "tool_use",
                                     toolName: block.name,
                                     toolInput: toolInputStr,
+                                    toolUseId,
+                                    runInBackground,
                                     sessionId: capturedSessionId,
                                 };
                             }

package/dist/services/allowed-users-gate.js

@@ -0,0 +1,56 @@
+/**
+ * ALLOWED_USERS Startup Gate (v4.12.2)
+ *
+ * Pure decision function that runs at startup to decide whether Alvin should
+ * refuse to start because its Telegram bot is configured but has no user
+ * allowlist.
+ *
+ * Before v4.12.2, an empty ALLOWED_USERS with AUTH_MODE=allowlist would only
+ * emit a console.warn and the bot would start anyway. On production this
+ * left a "configured but unguarded" surface — any Telegram user who sends
+ * a DM would reach the bot and could exploit shell/filesystem access via
+ * prompt injection.
+ *
+ * The gate has two explicit escape hatches, both intentional:
+ *   1. AUTH_MODE=open — user explicitly wants a public bot (not recommended)
+ *   2. ALVIN_INSECURE_ACKNOWLEDGED=1 — explicit operator opt-out used for
+ *      test environments and scripted installs where the operator
+ *      acknowledges they know what they're doing.
+ *
+ * Pure: takes config values as args, returns a decision. The actual
+ * process.exit(1) lives in src/index.ts as a thin wrapper.
+ */
+export function checkAllowedUsersGate(input) {
+    // WebUI-only deployments don't have a BOT_TOKEN → nothing to gate
+    if (!input.hasTelegram) {
+        return { allowed: true };
+    }
+    // Telegram is enabled AND allowlist is populated → normal path
+    if (input.allowedUsersCount > 0) {
+        return { allowed: true };
+    }
+    // Telegram enabled but allowlist empty — check escape hatches
+    if (input.authMode === "open") {
+        return {
+            allowed: true,
+            warning: "AUTH_MODE=open explicitly set. Any Telegram user can message the bot. " +
+                "This is NOT recommended for machines with sensitive files or shell access.",
+        };
+    }
+    if (input.insecureAcknowledged) {
+        return {
+            allowed: true,
+            warning: "ALVIN_INSECURE_ACKNOWLEDGED=1 set. Bot starts with empty ALLOWED_USERS. " +
+                "The operator has explicitly opted out of the safety gate.",
+        };
+    }
+    // No escape hatch — refuse to start
+    return {
+        allowed: false,
+        reason: "ALLOWED_USERS is empty but BOT_TOKEN is set. " +
+            "Alvin Bot has full shell/filesystem access on this machine, so starting with " +
+            "an empty allowlist would leave the bot open to anyone who sends it a Telegram message. " +
+            "Fix: set ALLOWED_USERS=<your telegram user id> in ~/.alvin-bot/.env (get your ID from @userinfobot). " +
+            "Explicit opt-out: AUTH_MODE=open OR ALVIN_INSECURE_ACKNOWLEDGED=1.",
+    };
+}

package/dist/services/cron.js

@@ -124,6 +124,23 @@ async function executeJob(job) {
             }
             case "shell": {
                 const cmd = job.payload.command || "echo 'no command'";
+                // v4.12.2 — Cron shell jobs now go through exec-guard. Before
+                // v4.12.2 cron bypassed the allowlist, which was inconsistent
+                // with the rest of the bot's shell execution policy. With
+                // EXEC_SECURITY=allowlist (default) this rejects jobs with
+                // shell metacharacters or non-allowlisted binaries. Operators
+                // who legitimately need complex shell pipelines in cron set
+                // EXEC_SECURITY=full explicitly.
+                const { checkExecAllowed } = await import("./exec-guard.js");
+                const guard = checkExecAllowed(cmd);
+                if (!guard.allowed) {
+                    const msg = `Cron shell job blocked by exec-guard: ${guard.reason}`;
+                    console.warn(`[cron] ${job.name}: ${msg}`);
+                    if (notifyCallback) {
+                        await notifyCallback(job.target, `🛑 ${job.name}\n${msg}\n\nSet EXEC_SECURITY=full if this is intentional.`);
+                    }
+                    return { output: msg };
+                }
                 // Per-job timeout, default = no timeout (execSync treats timeout=0
                 // or "undefined" as infinite). Users opt in via /cron add … --timeout N.
                 const shellOpts = {

package/dist/services/exec-guard.js

@@ -30,12 +30,37 @@ function extractBinary(command) {
     // Strip path: /usr/bin/curl -> curl
     return first.split("/").pop() || first;
 }
+/**
+ * v4.12.2 — Reject shell metacharacters in allowlist mode.
+ *
+ * The pre-v4.12.2 allowlist check only inspected the first word of the
+ * command. That was trivially bypassable via:
+ *   - ";" chaining:       "echo safe; rm -rf /"
+ *   - "&&" / "||" chains:  "echo hi && cat /etc/passwd"
+ *   - pipe:                "cat /etc/passwd | head"
+ *   - substitution:        "echo $(whoami)" or "`whoami`"
+ *   - redirect:            "echo hi > /etc/passwd"
+ *   - backgrounding:       "... &"
+ *
+ * Strategy: in allowlist mode, any command containing any of these
+ * metachars is rejected outright. Users who need shell pipelines opt in
+ * explicitly via EXEC_SECURITY=full.
+ */
+const SHELL_METACHAR_PATTERN = /[;&|`$(){}<>]/;
 export function checkExecAllowed(command) {
     if (config.execSecurity === "full")
         return { allowed: true };
     if (config.execSecurity === "deny")
         return { allowed: false, reason: "Shell execution is disabled" };
-    // allowlist mode
+    // allowlist mode — v4.12.2 metachar guard
+    if (SHELL_METACHAR_PATTERN.test(command)) {
+        return {
+            allowed: false,
+            reason: `Command contains shell metacharacters (pipes, redirects, substitution, chaining). ` +
+                `Allowlist mode only permits simple binary invocations. ` +
+                `Set EXEC_SECURITY=full if you need shell pipelines.`,
+        };
+    }
     const binary = extractBinary(command);
     if (SAFE_BINS.includes(binary))
         return { allowed: true };

package/dist/services/fallback-order.js

@@ -10,6 +10,7 @@
  */
 import fs from "fs";
 import { FALLBACK_FILE, ENV_FILE, DATA_DIR } from "../paths.js";
+import { writeSecure } from "./file-permissions.js";
 // ── Public API ──────────────────────────────────────────────────────────────
 /**
  * Get the current fallback order.
@@ -143,7 +144,9 @@ function syncToEnv(primary, fallbacks) {
         else {
             env += `\nFALLBACK_PROVIDERS=${fallbackStr}`;
         }
-        fs.writeFileSync(ENV_FILE, env);
+        // v4.12.2 — writeSecure enforces 0o600 on .env so other users on the
+        // machine can't read tokens/API keys.
+        writeSecure(ENV_FILE, env);
     }
     catch (err) {
         console.error("Failed to sync fallback order to .env:", err);

package/dist/services/file-permissions.js

@@ -0,0 +1,93 @@
+/**
+ * File Permissions Hardening (v4.12.2)
+ *
+ * On multi-user dev servers, Alvin's sensitive files (.env, sessions.json,
+ * memory files, cron-jobs.json) were previously written with the default
+ * umask — typically 0o644 on Linux/macOS, meaning any other user on the
+ * same machine could read API keys, conversation history, cron job
+ * definitions, etc.
+ *
+ * This module provides:
+ *   - writeSecure(path, content) — atomic write with mode 0o600
+ *   - ensureSecureMode(path) — chmod-repair an existing file if it's too permissive
+ *   - auditSensitiveFiles(paths[]) — batch-audit a list of files and repair
+ *
+ * The handler strategy:
+ *   - NEW writes: use writeSecure() or pass `{ mode: 0o600 }` to writeFileSync
+ *   - STARTUP: call auditSensitiveFiles() once with the list of known-sensitive
+ *     files to chmod-repair anything that was written pre-v4.12.2
+ *
+ * Pure file-system operations — no grammy, no session, testable in isolation.
+ */
+import fs from "fs";
+/** Strict mode for all sensitive files: owner read/write only. */
+export const SECURE_MODE = 0o600;
+/**
+ * Atomically write a file with mode 0o600.
+ *
+ * Uses fs.writeFileSync's built-in `mode` option for initial creation, then
+ * an explicit fs.chmodSync to handle the case where the file already exists
+ * (in which case the mode arg to writeFileSync is ignored).
+ */
+export function writeSecure(path, content) {
+    fs.writeFileSync(path, content, { mode: SECURE_MODE });
+    // writeFileSync's mode is only applied on initial create. If the file
+    // already existed with a looser mode, we need to explicitly chmod it.
+    try {
+        fs.chmodSync(path, SECURE_MODE);
+    }
+    catch {
+        // Best effort — some filesystems (e.g. FAT) don't support chmod
+    }
+}
+/**
+ * Ensure a file is at most as permissive as SECURE_MODE (0o600). If it's
+ * already 0o600 or stricter (e.g. 0o400), leave it alone. If it's more
+ * permissive (e.g. 0o644, 0o666), repair it to 0o600.
+ *
+ * Returns a report of what happened — used by auditSensitiveFiles().
+ */
+export function ensureSecureMode(path) {
+    let stat;
+    try {
+        stat = fs.statSync(path);
+    }
+    catch (err) {
+        const e = err;
+        if (e.code === "ENOENT") {
+            return { path, status: "missing" };
+        }
+        return { path, status: "error", error: e.message };
+    }
+    const currentMode = stat.mode & 0o777;
+    // If the file is already at SECURE_MODE or stricter (fewer bits), leave it.
+    // We use bitwise AND: if (currentMode & ~SECURE_MODE) === 0 then all set bits
+    // are within SECURE_MODE's bits — i.e. the file is not MORE permissive.
+    if ((currentMode & ~SECURE_MODE) === 0) {
+        return { path, status: "already-secure" };
+    }
+    // File is more permissive than 0o600 — repair.
+    try {
+        fs.chmodSync(path, SECURE_MODE);
+        return {
+            path,
+            status: "repaired",
+            previousMode: currentMode.toString(8),
+        };
+    }
+    catch (err) {
+        return {
+            path,
+            status: "error",
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+/**
+ * Audit + repair a list of sensitive file paths. Returns a report per file.
+ * Called once at bot startup with the list of known-sensitive files so that
+ * any file written pre-v4.12.2 (with default 0o644/0o666 umask) gets repaired.
+ */
+export function auditSensitiveFiles(paths) {
+    return paths.map(p => ensureSecureMode(p));
+}

package/dist/services/personality.js

@@ -61,43 +61,68 @@ const SDK_ADDON = `When you run commands or edit files, briefly explain what you
  * See test/system-prompt-background-hint.test.ts and
  * docs/superpowers/plans/2026-04-13-async-subagents.md
  */
-const BACKGROUND_SUBAGENT_HINT = `## Background Sub-Agents (IMPORTANT)
+const BACKGROUND_SUBAGENT_HINT = `## ⚠️ CRITICAL: Background Sub-Agents (Telegram blocking rule)
 
-For long-running work, ALWAYS set \`run_in_background: true\` on your Agent
-tool call. This makes the tool return IMMEDIATELY with an \`agentId\` and
-\`outputFile\` path instead of blocking for the full duration. Your main
-turn ends quickly, the user's session unlocks, and they can keep chatting
-with me while the sub-agent works in parallel.
+**The rule**: For any Agent/Task tool call that will take more than
+~30 seconds, you MUST set \`run_in_background: true\`. Otherwise the
+Telegram user is COMPLETELY BLOCKED from messaging me until the task
+finishes — terrible UX for anything that ends up taking minutes or
+hours. This is the single most important rule for using the Agent tool.
 
-After launching a background agent, you MUST:
-1. Tell the user in one short sentence what you kicked off ("Starting SEO
-   audit for gethomes.io in the background — I'll send the report when
-   it's done").
-2. End your turn promptly. Do NOT wait around. Do NOT keep working on
-   that task. Wrap up within 1-2 short messages.
-3. When the agent finishes, its final report will arrive as a SEPARATE
-   message in this chat — the bot handles that delivery automatically.
-   You don't need to poll the outputFile proactively.
+**Why it matters**: During a synchronous Agent tool call the parent
+session has no way to know the sub-agent is still working. It appears
+hung. After a long silence the session can be aborted, destroying the
+work. Using \`run_in_background: true\` solves this: the tool returns
+an \`agentId\` + \`outputFile\` path IMMEDIATELY, your turn ends in
+seconds, the user can keep chatting with me, and the bot automatically
+delivers the sub-agent's final result as a separate message when ready.
 
-If the user asks "is it done yet?" before the bot delivers the result,
-you MAY read the agent's \`outputFile\` (from the tool result) using the
-Read tool to check progress.
+**Decision tree** (apply every time you consider the Agent/Task tool):
+
+  Does the task involve ANY of the following?
+    • Visiting more than 2 URLs
+    • Reading/analyzing more than 5 files
+    • A full-repo scan, audit, or refactor proposal
+    • A multi-section report or structured document
+    • Tasks you'd describe as "thorough", "comprehensive", or "deep"
+    • Shell commands that may take >30s (builds, installs, tests)
+    • Crawling, scraping, or fetching multiple resources
+    • Research across multiple sources or domains
+
+  YES → \`run_in_background: true\` (no exceptions)
+  NO  → foreground is fine (single quick sub-query under 30s)
 
-**DO use \`run_in_background: true\` for:**
-- Audits (SEO, security, code quality, performance)
-- Research tasks that visit more than 3 web pages
-- Multi-file codebase analyses, full-repo scans
+**Examples where you MUST use \`run_in_background: true\`:**
+- ANY audit (SEO, security, code quality, performance, accessibility, GEO)
+- Research visiting more than 1-2 web pages
+- Code reviews on more than a single file
+- Full-repo analyses, dependency scans, architecture proposals
 - Report generation with multiple sub-steps
-- Anything you estimate will take longer than 2 minutes
+- Build / install / test runs
+- Long data-processing jobs
+- Anything involving the word "analyze", "audit", "review", "scan", "research"
 
-**DON'T use run_in_background for:**
-- Simple questions the user is actively waiting on a quick answer
-- Single file reads
-- Quick web fetches for a specific fact
-- Short tool chains under ~30 seconds
+**Examples where foreground is fine:**
+- "Read this file and summarize it" (single file, <10s)
+- "What's 2+2?" (no sub-agent needed — answer yourself)
+- "Check if package.json has foo" (one quick tool call)
+
+**After launching a background agent, you MUST:**
+1. Tell the user in ONE short sentence what you kicked off.
+   Example: "Starting SEO audit for gethomes.io in the background —
+   I'll send the report when it's done."
+2. End your turn IMMEDIATELY. Do not continue working. Do not wait.
+3. The bot will deliver the result as a separate message when ready.
+   You don't need to poll the outputFile proactively.
+
+If the user asks "is it done yet?" before the bot delivers the result,
+you MAY read the agent's \`outputFile\` (from the original tool result)
+using the Read tool to peek at progress — but don't block on it.
 
-When in doubt: prefer background for audits/research, foreground for
-conversational answers.`;
+**Never** call the Agent/Task tool without \`run_in_background: true\`
+for anything you're not 100% sure completes in under 30 seconds. The
+cost of unnecessary background mode is zero. The cost of blocking the
+Telegram user for 20 minutes on a synchronous call is very high.`;
 /**
  * Self-Awareness Core — Dynamic introspection block.
  *

package/dist/services/session-persistence.js

@@ -21,6 +21,7 @@
 import fs from "fs";
 import { dirname } from "path";
 import { SESSIONS_STATE_FILE } from "../paths.js";
+import { SECURE_MODE } from "./file-permissions.js";
 import { getAllSessions, getTelegramWorkspacesMap, } from "./session.js";
 /** History entries to keep in the persisted snapshot (per session). */
 const MAX_PERSISTED_HISTORY = 50;
@@ -85,9 +86,20 @@ export async function flushSessions() {
             sessions: out,
             telegramWorkspaces: tgWorkspaces,
         };
-        // Atomic write: tmp + rename
+        // Atomic write: tmp + rename. v4.12.2 — mode 0o600 enforced so other
+        // users on the same machine can't read conversation history or tokens.
         const tmpFile = `${SESSIONS_STATE_FILE}.tmp`;
-        fs.writeFileSync(tmpFile, JSON.stringify(envelope, null, 2), "utf-8");
+        fs.writeFileSync(tmpFile, JSON.stringify(envelope, null, 2), {
+            encoding: "utf-8",
+            mode: SECURE_MODE,
+        });
+        // Belt-and-suspenders: chmod in case the tmp file already existed with
+        // looser permissions (writeFileSync's mode option is only applied on
+        // initial create).
+        try {
+            fs.chmodSync(tmpFile, SECURE_MODE);
+        }
+        catch { /* fs may not support */ }
         fs.renameSync(tmpFile, SESSIONS_STATE_FILE);
     }
     catch (err) {

package/dist/services/subagents.js

@@ -250,12 +250,30 @@ async function runSubAgent(id, agentConfig, abort, resolvedName) {
             ? agentConfig.workingDir || os.homedir()
             : os.homedir();
         const systemPrompt = `You are a sub-agent named "${resolvedName}". Complete the following task autonomously and report your results clearly when done. Working directory: ${effectiveCwd}`;
+        // v4.12.2 — Map the toolset preset to an explicit allowedTools list.
+        // The provider honors this override (see src/providers/claude-sdk-provider.ts
+        // line ~140). Passing undefined = full access (provider default).
+        const allowedToolsForToolset = (preset) => {
+            switch (preset) {
+                case "readonly":
+                    // Read, analyze, search — no writes, no shell, no network.
+                    return ["Read", "Glob", "Grep"];
+                case "research":
+                    // Same as readonly + web access for research tasks.
+                    return ["Read", "Glob", "Grep", "WebSearch", "WebFetch"];
+                case "full":
+                default:
+                    // undefined → provider uses its full default set.
+                    return undefined;
+            }
+        };
         for await (const chunk of registry.queryWithFallback({
             prompt: agentConfig.prompt,
             systemPrompt,
             workingDir: effectiveCwd,
             effort: "high",
             abortSignal: abort.signal,
+            allowedTools: allowedToolsForToolset(agentConfig.toolset ?? "full"),
         })) {
             if (chunk.type === "text") {
                 // Both SDK providers emit `text` as the accumulated string.
@@ -483,12 +501,12 @@ export function spawnSubAgent(agentConfig) {
     if (depth > MAX_SUBAGENT_DEPTH) {
         return Promise.reject(new Error(`Sub-agent depth limit reached (${MAX_SUBAGENT_DEPTH}). Agents can only spawn ${MAX_SUBAGENT_DEPTH} level(s) of nested agents.`));
     }
-    // G1: toolset preset. Only "full" is supported. The literal type blocks
-    // wrong values at compile time; the runtime check catches callers that
-    // bypass TypeScript (e.g. plugin code loaded at runtime).
+    // G1: toolset preset (v4.12.2 — extended with readonly + research).
+    // The literal type constrains at compile time; the runtime check catches
+    // callers that bypass TypeScript (e.g. plugin code loaded at runtime).
     const toolset = agentConfig.toolset ?? "full";
-    if (toolset !== "full") {
-        return Promise.reject(new Error(`Invalid toolset "${toolset}". Only "full" is supported in this version.`));
+    if (toolset !== "full" && toolset !== "readonly" && toolset !== "research") {
+        return Promise.reject(new Error(`Invalid toolset "${toolset}". Valid presets: full, readonly, research.`));
     }
     const maxParallel = getMaxParallelAgents();
     const queueCap = getQueueCap();

package/dist/services/timing-safe-bearer.js

@@ -0,0 +1,51 @@
+/**
+ * Timing-Safe Bearer Token Comparison (v4.12.2)
+ *
+ * Replaces naive `authHeader !== "Bearer " + token` comparison with
+ * crypto.timingSafeEqual so that token comparison time doesn't leak
+ * character-level information via side-channel.
+ *
+ * Real-world exploitability over network is low due to network jitter,
+ * but this is the right tool regardless — defense in depth.
+ *
+ * Behavior:
+ *   - Strict "Bearer <token>" format required (exactly one space)
+ *   - Empty expected token always rejects (prevents accidental auth bypass)
+ *   - Different-length tokens compared via timingSafeEqual on padded buffers
+ *     so timing doesn't leak whether the prefix matched
+ *   - Unicode-safe: Buffer.from uses UTF-8 encoding
+ */
+import { timingSafeEqual } from "crypto";
+export function timingSafeBearerMatch(authHeader, expectedToken) {
+    // Empty expected token → always reject. Prevents a misconfig where
+    // config.webhookToken is "" from accidentally allowing any "Bearer "
+    // or empty Authorization header.
+    if (!expectedToken || expectedToken.length === 0)
+        return false;
+    // Missing or non-string header
+    if (!authHeader || typeof authHeader !== "string")
+        return false;
+    // Strict format: "Bearer <token>" with exactly one space. Anything else
+    // (double space, leading whitespace, wrong prefix) is rejected. We do
+    // this via startsWith + exact-length check, not split, so attackers
+    // can't use whitespace variations to confuse the parser.
+    const prefix = "Bearer ";
+    if (!authHeader.startsWith(prefix))
+        return false;
+    const providedToken = authHeader.slice(prefix.length);
+    // timingSafeEqual requires equal-length buffers. If lengths differ,
+    // we return false — but we still touch both strings symbolically so
+    // the compare itself is constant-time relative to the shorter one.
+    // (A length leak through string.length check is acceptable; what we
+    // actually care about is that the character-by-character comparison
+    // doesn't leak.)
+    const expectedBuf = Buffer.from(expectedToken, "utf-8");
+    const providedBuf = Buffer.from(providedToken, "utf-8");
+    if (expectedBuf.length !== providedBuf.length) {
+        // Do a dummy comparison so total time is closer to constant.
+        // Not perfect but better than early-return alone.
+        timingSafeEqual(expectedBuf, expectedBuf);
+        return false;
+    }
+    return timingSafeEqual(expectedBuf, providedBuf);
+}

package/dist/web/doctor-api.js

@@ -12,6 +12,7 @@ import fs from "fs";
 import { resolve, dirname } from "path";
 import { execSync } from "child_process";
 import { BOT_ROOT, ENV_FILE, BACKUP_DIR, DATA_DIR, MEMORY_DIR, MEMORY_FILE, SOUL_FILE, SOUL_EXAMPLE, TOOLS_MD, TOOLS_JSON, CUSTOM_MODELS, CRON_FILE, MCP_CONFIG } from "../paths.js";
+import { writeSecure } from "../services/file-permissions.js";
 // Files to include in backups (absolute paths)
 const BACKUP_FILES = [
     { src: ENV_FILE, label: ".env" },
@@ -222,9 +223,14 @@ function autoRepair(action) {
                 const exampleFile = resolve(BOT_ROOT, ".env.example");
                 if (fs.existsSync(exampleFile)) {
                     fs.copyFileSync(exampleFile, ENV_FILE);
+                    // v4.12.2 — enforce 0o600 on fresh .env
+                    try {
+                        fs.chmodSync(ENV_FILE, 0o600);
+                    }
+                    catch { /* fs may not support */ }
                     return { ok: true, message: ".env created from .env.example" };
                 }
-                fs.writeFileSync(ENV_FILE, "BOT_TOKEN=\nALLOWED_USERS=\nPRIMARY_PROVIDER=claude-sdk\n");
+                writeSecure(ENV_FILE, "BOT_TOKEN=\nALLOWED_USERS=\nPRIMARY_PROVIDER=claude-sdk\n");
                 return { ok: true, message: "Default .env created (BOT_TOKEN still needs to be set)" };
             }
             case "create-docs": {
@@ -272,7 +278,7 @@ function autoRepair(action) {
                     const lines = fs.readFileSync(ENV_FILE, "utf-8").split("\n");
                     if (lineIdx >= 0 && lineIdx < lines.length) {
                         lines[lineIdx] = "# " + lines[lineIdx]; // Comment out broken line
-                        fs.writeFileSync(ENV_FILE, lines.join("\n"));
+                        writeSecure(ENV_FILE, lines.join("\n"));
                         return { ok: true, message: `Line ${lineIdx + 1} commented out` };
                     }
                 }