@rubytech/taskmaster 1.9.4 → 1.9.6

package/dist/gateway/public-chat-api.js

@@ -5,16 +5,18 @@
  *
  * Endpoints:
  *   POST /session        — create an anonymous session (returns sessionKey)
- *   POST /otp/request    — request a WhatsApp OTP code
+ *   POST /otp/request    — request an OTP code (phone via WhatsApp/SMS, or email via Resend)
  *   POST /otp/verify     — verify OTP and get a verified session (returns sessionKey)
  *   POST /chat           — send a message, receive the agent reply (sync or SSE stream)
  *   GET  /chat/history   — retrieve past messages for a session
  *   POST /chat/abort     — cancel an in-progress agent run
+ *   GET  /capabilities   — discover available auth methods and OTP channels
  *
  * Authentication mirrors the public chat widget: anonymous sessions use a
- * client-provided identity string; verified sessions use WhatsApp OTP.
- * The sessionKey returned from /session or /otp/verify is passed via the
- * X-Session-Key header on subsequent requests.
+ * client-provided identity string; verified sessions use OTP sent via phone
+ * (WhatsApp with SMS fallback) or email (Resend). The sessionKey returned
+ * from /session or /otp/verify is passed via the X-Session-Key header on
+ * subsequent requests.
  *
  * The chat endpoint uses `dispatchInboundMessage` — the same full pipeline
  * as the WebSocket `chat.send` handler — so filler messages, internal hooks,
@@ -34,10 +36,10 @@ import { createInternalHookEvent, triggerInternalHook } from "../hooks/internal-
 import { emitAgentEvent, onAgentEvent } from "../infra/agent-events.js";
 import { INTERNAL_MESSAGE_CHANNEL } from "../utils/message-channel.js";
 import { requestOtp, verifyOtp } from "./public-chat/otp.js";
-import { deliverOtp } from "./public-chat/deliver-otp.js";
+import { deliverOtp, detectOtpChannels } from "./public-chat/deliver-otp.js";
 import { buildPublicSessionKey, resolvePublicAgentId } from "./public-chat/session.js";
 import { loadSessionEntry, readSessionMessages } from "./session-utils.js";
-import { extractFileAttachments, sanitizeMediaForChat, stripEnvelopeFromMessages } from "./chat-sanitize.js";
+import { extractFileAttachments, sanitizeMediaForChat, stripEnvelopeFromMessages, } from "./chat-sanitize.js";
 import { resolveWorkspaceRoot } from "./media-http.js";
 import { readJsonBodyOrError, sendInvalidRequest, sendJson, sendMethodNotAllowed, setSseHeaders, writeDone, } from "./http-common.js";
 // ---------------------------------------------------------------------------
@@ -88,6 +90,10 @@ function getSessionKeyHeader(req) {
 function isValidPhone(phone) {
     return /^\+\d{7,15}$/.test(phone);
 }
+/** Basic email format check. */
+function isValidEmail(email) {
+    return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email) && email.length <= 254;
+}
 /** Strip spaces, dashes, and parentheses from a phone number. */
 function normalizePhone(raw) {
     return raw.replace(/[\s\-()]/g, "");
@@ -216,12 +222,38 @@ async function handleOtpRequest(req, res, accountId, cfg, maxBodyBytes) {
     if (body === undefined)
         return;
     const payload = (body && typeof body === "object" ? body : {});
-    const phone = typeof payload.phone === "string" ? normalizePhone(payload.phone.trim()) : "";
-    if (!phone || !isValidPhone(phone)) {
-        sendInvalidRequest(res, "invalid phone number — use E.164 format (e.g. +447123456789)");
-        return;
+    // Accept `identifier` (preferred) or `phone` (backward compat).
+    const rawIdentifier = typeof payload.identifier === "string"
+        ? payload.identifier.trim()
+        : typeof payload.phone === "string"
+            ? payload.phone.trim()
+            : "";
+    const isEmail = rawIdentifier.includes("@");
+    const verifyMethods = cfg.publicChat?.verifyMethods ?? ["phone"];
+    let identifier;
+    if (isEmail) {
+        if (!verifyMethods.includes("email")) {
+            sendForbidden(res, "email verification is not enabled for this account");
+            return;
+        }
+        identifier = rawIdentifier.toLowerCase();
+        if (!isValidEmail(identifier)) {
+            sendInvalidRequest(res, "invalid email address");
+            return;
+        }
+    }
+    else {
+        if (!verifyMethods.includes("phone")) {
+            sendForbidden(res, "phone verification is not enabled for this account");
+            return;
+        }
+        identifier = normalizePhone(rawIdentifier);
+        if (!identifier || !isValidPhone(identifier)) {
+            sendInvalidRequest(res, "invalid phone number — use E.164 format (e.g. +447123456789)");
+            return;
+        }
     }
-    const result = requestOtp(phone);
+    const result = requestOtp(identifier);
     if (!result.ok) {
         sendJson(res, 429, {
             error: { message: "rate limited — try again shortly", type: "rate_limited" },
@@ -234,13 +266,13 @@ async function handleOtpRequest(req, res, accountId, cfg, maxBodyBytes) {
     const agentId = resolvePublicAgentId(cfg, accountId);
     const whatsappAccountId = resolveAgentBoundAccountId(cfg, agentId, "whatsapp") ?? undefined;
     try {
-        await deliverOtp(phone, result.code, whatsappAccountId);
+        const delivery = await deliverOtp(identifier, result.code, whatsappAccountId);
+        sendJson(res, 200, { ok: true, channel: delivery.channel });
     }
-    catch {
-        sendUnavailable(res, "failed to send verification code — is WhatsApp connected?");
-        return;
+    catch (err) {
+        const message = err instanceof Error ? err.message : "failed to send verification code";
+        sendUnavailable(res, message);
     }
-    sendJson(res, 200, { ok: true });
 }
 // ---------------------------------------------------------------------------
 // Route: POST /otp/verify
@@ -258,21 +290,38 @@ async function handleOtpVerify(req, res, accountId, cfg, maxBodyBytes) {
     if (body === undefined)
         return;
     const payload = (body && typeof body === "object" ? body : {});
-    const phone = typeof payload.phone === "string" ? normalizePhone(payload.phone.trim()) : "";
+    // Accept `identifier` (preferred) or `phone` (backward compat).
+    const rawIdentifier = typeof payload.identifier === "string"
+        ? payload.identifier.trim()
+        : typeof payload.phone === "string"
+            ? payload.phone.trim()
+            : "";
     const code = typeof payload.code === "string" ? payload.code.trim() : "";
     const name = typeof payload.name === "string" ? payload.name.trim() : undefined;
-    if (!phone || !isValidPhone(phone)) {
-        sendInvalidRequest(res, "invalid phone number");
-        return;
+    const isEmail = rawIdentifier.includes("@");
+    let identifier;
+    if (isEmail) {
+        identifier = rawIdentifier.toLowerCase();
+        if (!isValidEmail(identifier)) {
+            sendInvalidRequest(res, "invalid email address");
+            return;
+        }
+    }
+    else {
+        identifier = normalizePhone(rawIdentifier);
+        if (!identifier || !isValidPhone(identifier)) {
+            sendInvalidRequest(res, "invalid phone number");
+            return;
+        }
     }
     if (!code) {
         sendInvalidRequest(res, "code is required");
         return;
     }
-    const result = verifyOtp(phone, code);
+    const result = verifyOtp(identifier, code);
     if (!result.ok) {
         const messages = {
-            not_found: "no pending verification for this number",
+            not_found: "no pending verification for this identifier",
             expired: "verification code expired",
             max_attempts: "too many attempts — request a new code",
             invalid: "incorrect code",
@@ -286,11 +335,13 @@ async function handleOtpVerify(req, res, accountId, cfg, maxBodyBytes) {
         return;
     }
     const agentId = resolvePublicAgentId(cfg, accountId);
-    const sessionKey = buildPublicSessionKey(agentId, phone);
+    const sessionKey = buildPublicSessionKey(agentId, identifier);
     sendJson(res, 200, {
         session_key: sessionKey,
         agent_id: agentId,
-        phone,
+        identifier,
+        // Backward-compat: include named field matching the identifier type.
+        ...(isEmail ? { email: identifier } : { phone: identifier }),
         ...(name ? { name } : {}),
     });
 }
@@ -692,6 +743,28 @@ async function handleChatAbort(req, res, maxBodyBytes) {
     sendJson(res, 200, { ok: true, run_id: runId ?? null });
 }
 // ---------------------------------------------------------------------------
+// Route: GET /capabilities
+// ---------------------------------------------------------------------------
+async function handleCapabilities(req, res, accountId, cfg) {
+    if (req.method !== "GET") {
+        sendMethodNotAllowed(res, "GET");
+        return;
+    }
+    const authMode = cfg.publicChat?.auth ?? "anonymous";
+    const verifyMethods = cfg.publicChat?.verifyMethods ?? ["phone"];
+    const agentId = resolvePublicAgentId(cfg, accountId);
+    const whatsappAccountId = resolveAgentBoundAccountId(cfg, agentId, "whatsapp") ?? undefined;
+    const channels = detectOtpChannels(whatsappAccountId);
+    sendJson(res, 200, {
+        auth: authMode,
+        verify_methods: verifyMethods,
+        otp: {
+            available: channels.length > 0,
+            channels,
+        },
+    });
+}
+// ---------------------------------------------------------------------------
 // Main handler
 // ---------------------------------------------------------------------------
 /**
@@ -741,6 +814,9 @@ export async function handlePublicChatApiRequest(req, res, opts) {
         case "otp/verify":
             await handleOtpVerify(req, res, accountId, cfg, maxBodyBytes);
             return true;
+        case "capabilities":
+            await handleCapabilities(req, res, accountId, cfg);
+            return true;
         case "chat":
             await handleChat(req, res, accountId, cfg, maxBodyBytes);
             return true;

package/dist/gateway/server-chat.js

@@ -47,12 +47,14 @@ export function createChatRunState() {
     const deltaSentAt = new Map();
     const abortedRuns = new Map();
     const finalHadContent = new Map();
+    const finalTexts = new Map();
     const clear = () => {
         registry.clear();
         buffers.clear();
         deltaSentAt.clear();
         abortedRuns.clear();
         finalHadContent.clear();
+        finalTexts.clear();
     };
     return {
         registry,
@@ -60,6 +62,7 @@ export function createChatRunState() {
         deltaSentAt,
         abortedRuns,
         finalHadContent,
+        finalTexts,
         clear,
     };
 }
@@ -97,6 +100,8 @@ export function createAgentEventHandler({ broadcast, nodeSendToSession, agentRun
         // Record whether the streaming buffer had content so the chat.send .then()
         // handler knows whether it needs to broadcast the dispatcher's final reply.
         chatRunState.finalHadContent.set(clientRunId, !!text);
+        if (text)
+            chatRunState.finalTexts.set(clientRunId, text);
         if (jobState === "done") {
             const payload = {
                 runId: clientRunId,

package/dist/gateway/server-methods/access.js

@@ -196,7 +196,17 @@ export const accessHandlers = {
      */
     "access.setAccountPin": async ({ params, respond }) => {
         try {
-            const workspace = params.workspace?.trim();
+            // Normalise workspace name to match sanitiseName() in workspaces.ts —
+            // the UI may pass the raw user-typed name (e.g. "Joe's Store") while
+            // the workspace was created with the sanitised slug ("joes-store").
+            const rawWorkspace = params.workspace?.trim();
+            const workspace = rawWorkspace
+                ? rawWorkspace
+                    .toLowerCase()
+                    .replace(/[^a-z0-9_-]/g, "-")
+                    .replace(/-+/g, "-")
+                    .replace(/^-|-$/g, "")
+                : "";
             const pin = params.pin?.trim();
             if (!workspace) {
                 respond(false, undefined, errorShape(ErrorCodes.INVALID_REQUEST, "workspace is required"));

package/dist/gateway/server-methods/apikeys.js

@@ -16,9 +16,7 @@ import { readConfigFileSnapshot, writeConfigFile } from "../../config/config.js"
 import { ErrorCodes, errorShape } from "../protocol/index.js";
 import { formatForLog } from "../ws-log.js";
 /** Providers whose API keys are stored as auth profiles (type: api_key). */
-const AUTH_PROFILE_PROVIDERS = new Set([
-    "anthropic", "openai", "google", "replicate", "hume",
-]);
+const AUTH_PROFILE_PROVIDERS = new Set(["anthropic", "openai", "google", "replicate", "hume"]);
 const PROVIDER_CATALOG = [
     { id: "anthropic", name: "Anthropic", category: "AI Model", primary: true },
     { id: "google", name: "Google", category: "Voice & Video", primary: true },
@@ -28,6 +26,7 @@ const PROVIDER_CATALOG = [
     { id: "hume", name: "Hume", category: "Voice" },
     { id: "brave", name: "Brave", category: "Web Search" },
     { id: "elevenlabs", name: "ElevenLabs", category: "Voice" },
+    { id: "resend", name: "Resend", category: "Email" },
 ];
 const VALID_PROVIDER_IDS = new Set(PROVIDER_CATALOG.map((p) => p.id));
 export const apikeysHandlers = {
@@ -38,7 +37,12 @@ export const apikeysHandlers = {
             const disabledMap = snapshot.config.apiKeysDisabled ?? {};
             const providers = PROVIDER_CATALOG.map((p) => {
                 const raw = storedKeys[p.id]?.trim();
-                return { ...p, hasKey: Boolean(raw), disabled: Boolean(disabledMap[p.id]), key: raw || undefined };
+                return {
+                    ...p,
+                    hasKey: Boolean(raw),
+                    disabled: Boolean(disabledMap[p.id]),
+                    key: raw || undefined,
+                };
             });
             respond(true, { providers });
         }

package/dist/gateway/server-methods/chat.js

@@ -18,6 +18,7 @@ import { loadSessionEntry, readSessionMessages, resolveSessionModelRef } from ".
 import { sanitizeMediaForChat, stripEnvelopeFromMessages } from "../chat-sanitize.js";
 import { resolveWorkspaceRoot } from "../media-http.js";
 import { formatForLog } from "../ws-log.js";
+import { fireSuggestion } from "../../suggestions/broadcast.js";
 function resolveTranscriptPath(params) {
     const { sessionId, storePath, sessionFile } = params;
     if (sessionFile)
@@ -701,6 +702,19 @@ export const chatHandlers = {
                         cfg,
                     }));
                 }
+                // Fire suggestion chips for the next user interaction
+                const streamedText = context.chatFinalTexts.get(clientRunId) ?? "";
+                context.chatFinalTexts.delete(clientRunId);
+                const lastAssistantReply = outboundText || streamedText;
+                if (lastAssistantReply) {
+                    fireSuggestion({
+                        sessionKey: p.sessionKey,
+                        broadcast: context.broadcast,
+                        cfg,
+                        lastUserMessage: p.message,
+                        lastAssistantReply,
+                    });
+                }
                 context.dedupe.set(`chat:${clientRunId}`, {
                     ts: Date.now(),
                     ok: true,

package/dist/gateway/server-methods/public-chat.js

@@ -3,6 +3,7 @@
  */
 import { loadConfig } from "../../config/config.js";
 import { resolveAgentBoundAccountId } from "../../routing/bindings.js";
+import { generateGreeting } from "../../suggestions/greeting.js";
 import { ErrorCodes, errorShape } from "../protocol/index.js";
 import { requestOtp, verifyOtp } from "../public-chat/otp.js";
 import { deliverOtp } from "../public-chat/deliver-otp.js";
@@ -15,6 +16,10 @@ function normalizePhone(raw) {
 function isValidPhone(phone) {
     return /^\+\d{7,15}$/.test(phone);
 }
+/** Basic email format check. */
+function isValidEmail(email) {
+    return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email) && email.length <= 254;
+}
 function validateAccountId(raw) {
     if (typeof raw !== "string")
         return null;
@@ -25,22 +30,48 @@ function validateAccountId(raw) {
 }
 export const publicChatHandlers = {
     /**
-     * Request an OTP code — sends a 6-digit code to the given phone via WhatsApp.
-     * Params: { phone: string }
+     * Request an OTP code — sends a 6-digit code via WhatsApp/SMS (phone) or
+     * Resend (email).
+     * Params: { identifier: string } or { phone: string } (backward compat)
      */
     "public.otp.request": async ({ params, respond, context }) => {
-        const phone = typeof params.phone === "string" ? normalizePhone(params.phone.trim()) : "";
+        const rawIdentifier = typeof params.identifier === "string"
+            ? params.identifier.trim()
+            : typeof params.phone === "string"
+                ? params.phone.trim()
+                : "";
         const accountId = validateAccountId(params.accountId);
-        if (!phone || !isValidPhone(phone)) {
-            respond(false, undefined, errorShape(ErrorCodes.INVALID_REQUEST, "invalid phone number"));
-            return;
-        }
         const cfg = loadConfig();
         if (!cfg.publicChat?.enabled) {
             respond(false, undefined, errorShape(ErrorCodes.INVALID_REQUEST, "public chat disabled"));
             return;
         }
-        const result = requestOtp(phone);
+        const isEmail = rawIdentifier.includes("@");
+        const verifyMethods = cfg.publicChat?.verifyMethods ?? ["phone"];
+        let identifier;
+        if (isEmail) {
+            if (!verifyMethods.includes("email")) {
+                respond(false, undefined, errorShape(ErrorCodes.INVALID_REQUEST, "email verification is not enabled"));
+                return;
+            }
+            identifier = rawIdentifier.toLowerCase();
+            if (!isValidEmail(identifier)) {
+                respond(false, undefined, errorShape(ErrorCodes.INVALID_REQUEST, "invalid email address"));
+                return;
+            }
+        }
+        else {
+            if (!verifyMethods.includes("phone")) {
+                respond(false, undefined, errorShape(ErrorCodes.INVALID_REQUEST, "phone verification is not enabled"));
+                return;
+            }
+            identifier = normalizePhone(rawIdentifier);
+            if (!identifier || !isValidPhone(identifier)) {
+                respond(false, undefined, errorShape(ErrorCodes.INVALID_REQUEST, "invalid phone number"));
+                return;
+            }
+        }
+        const result = requestOtp(identifier);
         if (!result.ok) {
             respond(false, { retryAfterMs: result.retryAfterMs }, errorShape(ErrorCodes.INVALID_REQUEST, "rate limited — try again shortly"));
             return;
@@ -52,27 +83,44 @@ export const publicChatHandlers = {
             ? (resolveAgentBoundAccountId(cfg, agentId, "whatsapp") ?? undefined)
             : undefined;
         try {
-            await deliverOtp(phone, result.code, whatsappAccountId);
+            const delivery = await deliverOtp(identifier, result.code, whatsappAccountId);
+            respond(true, { ok: true, channel: delivery.channel });
         }
         catch (err) {
-            context.logGateway.warn(`public-chat OTP delivery failed: ${String(err)}`);
-            respond(false, undefined, errorShape(ErrorCodes.UNAVAILABLE, "failed to send verification code"));
-            return;
+            const message = err instanceof Error ? err.message : "failed to send verification code";
+            context.logGateway.warn(`public-chat OTP delivery failed: ${message}`);
+            respond(false, undefined, errorShape(ErrorCodes.UNAVAILABLE, message));
         }
-        respond(true, { ok: true });
     },
     /**
      * Verify an OTP code and return the session key.
-     * Params: { phone: string, code: string, accountId: string, name?: string }
+     * Params: { identifier: string, code: string, accountId: string, name?: string }
+     *         (or { phone: string } for backward compat)
      */
     "public.otp.verify": async ({ params, respond }) => {
-        const phone = typeof params.phone === "string" ? normalizePhone(params.phone.trim()) : "";
+        const rawIdentifier = typeof params.identifier === "string"
+            ? params.identifier.trim()
+            : typeof params.phone === "string"
+                ? params.phone.trim()
+                : "";
         const code = typeof params.code === "string" ? params.code.trim() : "";
         const name = typeof params.name === "string" ? params.name.trim() : undefined;
         const accountId = validateAccountId(params.accountId);
-        if (!phone || !isValidPhone(phone)) {
-            respond(false, undefined, errorShape(ErrorCodes.INVALID_REQUEST, "invalid phone number"));
-            return;
+        const isEmail = rawIdentifier.includes("@");
+        let identifier;
+        if (isEmail) {
+            identifier = rawIdentifier.toLowerCase();
+            if (!isValidEmail(identifier)) {
+                respond(false, undefined, errorShape(ErrorCodes.INVALID_REQUEST, "invalid email address"));
+                return;
+            }
+        }
+        else {
+            identifier = normalizePhone(rawIdentifier);
+            if (!identifier || !isValidPhone(identifier)) {
+                respond(false, undefined, errorShape(ErrorCodes.INVALID_REQUEST, "invalid phone number"));
+                return;
+            }
         }
         if (!code) {
             respond(false, undefined, errorShape(ErrorCodes.INVALID_REQUEST, "code required"));
@@ -87,10 +135,10 @@ export const publicChatHandlers = {
             respond(false, undefined, errorShape(ErrorCodes.INVALID_REQUEST, "public chat disabled"));
             return;
         }
-        const result = verifyOtp(phone, code);
+        const result = verifyOtp(identifier, code);
         if (!result.ok) {
             const messages = {
-                not_found: "no pending verification for this number",
+                not_found: "no pending verification for this identifier",
                 expired: "verification code expired",
                 max_attempts: "too many attempts — request a new code",
                 invalid: "incorrect code",
@@ -99,12 +147,14 @@ export const publicChatHandlers = {
             return;
         }
         const agentId = resolvePublicAgentId(cfg, accountId);
-        const sessionKey = buildPublicSessionKey(agentId, phone);
+        const sessionKey = buildPublicSessionKey(agentId, identifier);
         respond(true, {
             ok: true,
             sessionKey,
             agentId,
-            phone,
+            identifier,
+            // Backward compat: include named field matching the identifier type.
+            ...(isEmail ? { email: identifier } : { phone: identifier }),
             name,
         });
     },
@@ -137,4 +187,26 @@ export const publicChatHandlers = {
             agentId,
         });
     },
+    /**
+     * Generate a proactive greeting using the agent's identity and persona.
+     * Params: { accountId: string }
+     * Returns: { ok: true, greeting: string }
+     */
+    "public.greeting.generate": async ({ params, respond }) => {
+        const accountId = validateAccountId(params.accountId);
+        if (!accountId) {
+            respond(false, undefined, errorShape(ErrorCodes.INVALID_REQUEST, "accountId required"));
+            return;
+        }
+        const cfg = loadConfig();
+        const agentId = resolvePublicAgentId(cfg, accountId);
+        try {
+            const result = await generateGreeting({ cfg, agentId });
+            respond(true, result);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : "greeting generation failed";
+            respond(false, undefined, errorShape(ErrorCodes.UNAVAILABLE, message));
+        }
+    },
 };

package/dist/gateway/server-methods/tailscale.js

@@ -108,36 +108,77 @@ export const tailscaleHandlers = {
      * `loggedIn` becomes true.
      */
     "tailscale.enable": async ({ respond, context }) => {
+        // Matches auth URLs across Tailscale versions:
+        // - https://login.tailscale.com/a/<code>
+        // - https://login.tailscale.com/authorize/<code>
+        // - any other login.tailscale.com path with an auth token
+        const authUrlPattern = /https:\/\/login\.tailscale\.com\/[a-z]+\/[A-Za-z0-9_-]+/;
+        const extractAuthUrl = (output) => output.match(authUrlPattern)?.[0];
+        const captureExecOutput = (err) => {
+            const errObj = err;
+            return {
+                stdout: typeof errObj.stdout === "string" ? errObj.stdout : "",
+                stderr: typeof errObj.stderr === "string" ? errObj.stderr : "",
+                message: typeof errObj.message === "string" ? errObj.message : "",
+            };
+        };
+        const needsSudo = (output) => {
+            const lower = output.toLowerCase();
+            return (lower.includes("access denied") ||
+                lower.includes("permission denied") ||
+                lower.includes("use 'sudo tailscale") ||
+                lower.includes("requires root"));
+        };
+        // Run `tailscale up` (with optional extra args) and capture output.
+        // If the command fails with a permission error, retries with `sudo -n`.
+        // `tailscale up` blocks until auth completes, so timeouts are expected —
+        // the auth URL appears in stdout/stderr before the timeout kills it.
+        const runTailscaleUp = async (binary, extraArgs = []) => {
+            const args = ["up", ...extraArgs];
+            const execOpts = { timeoutMs: 60_000, maxBuffer: 100_000 };
+            const result = await runExec(binary, args, execOpts).catch((err) => captureExecOutput(err));
+            const output = `${result.stdout}\n${result.stderr}`;
+            if (!needsSudo(output))
+                return output;
+            // Permission denied — retry with sudo -n (non-interactive)
+            context.logGateway.info(`tailscale.enable: permission denied, retrying with sudo: ${args.join(" ")}`);
+            const sudoResult = await runExec("sudo", ["-n", binary, ...args], execOpts).catch((err) => captureExecOutput(err));
+            return `${sudoResult.stdout}\n${sudoResult.stderr}`;
+        };
         try {
             const binary = await findTailscaleBinary();
             if (!binary) {
                 respond(false, undefined, errorShape(ErrorCodes.UNAVAILABLE, "Tailscale is not installed on this device"));
                 return;
             }
-            // Run `tailscale up` — on a headless device this prints:
-            // "To authenticate, visit:\n\n\thttps://login.tailscale.com/a/..."
-            // The command blocks until auth completes, so we run it with a
-            // timeout and parse the auth URL from the output. The URL appears
-            // within seconds; the timeout just kills the blocking wait.
-            const child = await runExec(binary, ["up"], {
-                timeoutMs: 60_000,
-                maxBuffer: 100_000,
-            }).catch((err) => {
-                // `tailscale up` exits non-zero while waiting for auth but still
-                // prints the URL to stdout/stderr before the timeout kills it.
-                const errObj = err;
-                return {
-                    stdout: typeof errObj.stdout === "string" ? errObj.stdout : "",
-                    stderr: typeof errObj.stderr === "string" ? errObj.stderr : "",
-                };
-            });
-            const combined = `${child.stdout}\n${child.stderr}`;
-            const urlMatch = combined.match(/https:\/\/login\.tailscale\.com\/a\/[A-Za-z0-9]+/);
-            if (urlMatch) {
-                respond(true, { authUrl: urlMatch[0] });
+            // ── Pre-check: is tailscaled reachable? ──
+            // On Linux (Pi), tailscaled runs as a systemd service. After a package
+            // upgrade it may need restarting. Detect this early with a clear message
+            // instead of falling through to a generic "no URL" error.
+            try {
+                await runExec(binary, ["status", "--json"], { timeoutMs: 5_000, maxBuffer: 100_000 });
+            }
+            catch (statusErr) {
+                const { stderr, message } = captureExecOutput(statusErr);
+                const detail = `${stderr}\n${message}`.toLowerCase();
+                if (detail.includes("connection refused") ||
+                    detail.includes("no such file or directory") ||
+                    detail.includes("connect:") ||
+                    detail.includes("is tailscaled running")) {
+                    respond(false, undefined, errorShape(ErrorCodes.UNAVAILABLE, "The Tailscale service (tailscaled) is not running. " +
+                        "Try restarting it: sudo systemctl restart tailscaled"));
+                    return;
+                }
+                // Other status errors (e.g. NeedsLogin) are fine — continue to `tailscale up`
+            }
+            // ── Attempt 1: `tailscale up` ──
+            const combined = await runTailscaleUp(binary);
+            const authUrl = extractAuthUrl(combined);
+            if (authUrl) {
+                respond(true, { authUrl });
                 return;
             }
-            // No auth URL found — maybe already logged in
+            // No auth URL found — check if already logged in
             try {
                 const status = await readTailscaleStatusJson();
                 if (status.BackendState === "Running") {
@@ -148,8 +189,26 @@ export const tailscaleHandlers = {
             catch {
                 // ignore
             }
-            context.logGateway.warn(`tailscale.enable: no auth URL found in output: ${combined.slice(0, 500)}`);
-            respond(false, undefined, errorShape(ErrorCodes.UNAVAILABLE, "Could not start Tailscale login — no authentication URL received"));
+            // ── Attempt 2: `tailscale up --force-reauth` ──
+            // After a software upgrade or expired auth, the node may be in a stale
+            // state where plain `tailscale up` doesn't produce a new auth URL.
+            // --force-reauth forces a fresh login flow that always emits a URL.
+            context.logGateway.info("tailscale.enable: no auth URL from initial attempt, retrying with --force-reauth");
+            const retryCombined = await runTailscaleUp(binary, ["--force-reauth"]);
+            const retryUrl = extractAuthUrl(retryCombined);
+            if (retryUrl) {
+                respond(true, { authUrl: retryUrl });
+                return;
+            }
+            // ── Still nothing — surface diagnostic info ──
+            const allOutput = `${combined}\n${retryCombined}`.trim();
+            context.logGateway.warn(`tailscale.enable: no auth URL found in output: ${allOutput.slice(0, 500)}`);
+            // Include a snippet of what Tailscale actually said, so the user can diagnose
+            const snippet = allOutput.replace(/\s+/g, " ").trim().slice(0, 200);
+            const detail = snippet
+                ? ` Tailscale output: ${snippet}`
+                : " No output received from Tailscale.";
+            respond(false, undefined, errorShape(ErrorCodes.UNAVAILABLE, `Could not start Tailscale login — no authentication URL received.${detail}`));
         }
         catch (err) {
             context.logGateway.warn(`tailscale.enable failed: ${err instanceof Error ? err.message : String(err)}`);