@jtalk22/slack-mcp 4.1.0 → 4.2.0

package/README.md

@@ -4,7 +4,7 @@
 [![MCP Registry](https://img.shields.io/badge/MCP_Registry-listed-blue)](https://registry.modelcontextprotocol.io)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
 
-Give your AI agent full Slack access. No app registration, no admin approval, no OAuth. One command, 16 tools, works with any MCP client.
+Give your AI agent full Slack access — and structured workflow output the AI can actually use. No app registration, no admin approval, no OAuth. One command, 21 tools, works with any MCP client.
 
 ```bash
 npx -y @jtalk22/slack-mcp --setup
@@ -24,7 +24,7 @@ Slack's official MCP server requires a registered app, admin approval, and [does
 
 This server uses your browser's session tokens instead. If you can see it in Slack, your AI agent can see it too. No app install, no scopes, no admin.
 
-**Stealth Mode:** Session tokens leave zero footprint in your workspace admin panel. No bot user appears, no app install shows up, no audit trail. Your AI agent operates with the same invisibility as your browser tab.
+**Session-token transport:** No bot user appears in the workspace admin panel, no app install shows up, no audit trail entry is created. Your AI agent operates with the same workspace footprint as your browser tab — nothing more, nothing less.
 
 ![OAuth vs Chrome DB Decryption](docs/images/diagram-oauth-comparison.svg)
 
@@ -39,8 +39,28 @@ This server uses your browser's session tokens instead. If you can see it in Sla
 | Works with Gemini CLI | No | **Yes** |
 | Works with Codex CLI | No | **Yes** |
 | Setup time | ~30 min | **~2 min** |
-| Tools | Limited | **16** |
-| Visible to admins | Yes | **No — Stealth Mode** |
+| Tools | Limited | **21** |
+| Visible to admins | Yes | **No — session-token transport** |
+
+## Workflow Primitives (new in 4.2)
+
+Save a workflow profile that binds a `workflow_kind` to channels + priority people + retention + cadence. Stored locally at `~/.slack-mcp-workflows.json`. The hosted brain at [mcp.revasserlabs.com](https://mcp.revasserlabs.com) reads these profiles and returns **structured JSON per workflow_kind** — downstream automation (Linear, Notion, status dashboards) consumes the JSON directly.
+
+| `workflow_kind` | Returns (structured JSON) |
+|---|---|
+| `incident_room` | `{incident_summary, timeline, open_risks, owner_gaps, next_actions}` |
+| `exec_brief` | `{summary, decisions, risks, asks, action_items}` |
+| `support_inbox` | `{open_threads, ack_lag, owner_gaps, escalations, next_actions}` |
+| `product_launch_watch` | `{launch_signals, feedback_themes, blockers, metrics, next_actions}` |
+| `custom` | `{summary, highlights, open_questions, next_actions}` |
+
+Six prebuilt templates ship with the package:
+
+```bash
+npx -y @jtalk22/slack-mcp --apply-template oncall-handoff --channels C012345,C067890
+```
+
+Available templates: `oncall-handoff`, `support-triage`, `exec-monday`, `sprint-tracker`, `customer-feedback`, `incident-room`. The structural primitives (`slack_workflow_save`, `slack_workflows`) are free forever in OSS; the hosted brain is `$0` to start (no card) and `$9/mo` Pro for unlimited AI tools (scheduled morning catch-up DM rolling out Q2 2026).
 
 ## Quick Start per Client
 
@@ -129,11 +149,18 @@ Or via CLI: `codex mcp add slack -- npx -y @jtalk22/slack-mcp`
 | `slack_add_reaction` | Add an emoji reaction to a message | **destructive** |
 | `slack_remove_reaction` | Remove an emoji reaction from a message | **destructive** |
 | `slack_conversations_mark` | Mark a conversation as read | **destructive** |
+| `slack_workflow_save` | Save a workflow profile (channels, kind, retention, cadence) to `~/.slack-mcp-workflows.json` | local-write |
+| `slack_workflows` | List saved workflow profiles | read-only |
+| `slack_smart_search` | Semantic search across indexed channels — hosted brain | hosted-stub† |
+| `slack_catch_me_up` | AI-summarized digest of unreads + priority threads — hosted brain | hosted-stub† |
+| `slack_triage` | Prioritized action queue across channels — hosted brain | hosted-stub† |
 
-12 read-only, 4 write-path. All carry [MCP safety annotations](https://modelcontextprotocol.io/specification/2025-03-26/server/tools#annotations).
+21 tools total: 12 read-only Slack, 4 write-path Slack, 2 workflow profile primitives (1 local-write, 1 read-only), 3 hosted stubs. All carry [MCP safety annotations](https://modelcontextprotocol.io/specification/2025-03-26/server/tools#annotations).
 
 \* `slack_refresh_tokens` modifies local token file only.
 
+† Hosted stubs return a structured upgrade payload (`signup_url`, `free_tier_quota`, `pro_value_prop`) — no Slack write occurs from OSS. Activate the brain at [mcp.revasserlabs.com](https://mcp.revasserlabs.com) (free tier, no card).
+
 ## Install
 
 **Node.js 20+**
@@ -230,7 +257,15 @@ On macOS, tokens are auto-extracted from Chrome — `env` block is optional.
 <details>
 <summary><strong>Claude Web / Remote MCP</strong></summary>
 
-Hosted version with permanent OAuth tokens coming soon. See [mcp.revasserlabs.com](https://mcp.revasserlabs.com) for updates.
+Hosted tiers at [mcp.revasserlabs.com](https://mcp.revasserlabs.com):
+
+| Tier | Price | What it owns |
+|------|-------|-------------|
+| Self-host | Free (MIT) | Local stdio, all 21 tools (16 read/write Slack + 2 workflow profile primitives + 3 discoverable upgrade stubs to hosted brain) |
+| Hosted Free | $0 (no card) | Email signup, 1 workspace, 10 smart_search/mo + 3 catch_me_up/mo + 5 triage/day. All 5 workflow profile types. 7-day index retention. |
+| Pro | $9/mo | Unlimited AI tools, **scheduled morning catch-up DM** *(rolling out Q2 2026, 8am workspace tz)*, permanent OAuth, 90-day Vectorize, 2 workspaces |
+| Team | $49/mo flat | Pro + shared workflow profiles + audit log + 24h support + scheduled catch-up to channel + 5 workspaces |
+| Ops | from $199/mo (custom) | SLA, custom retention, SOC2 evidence path, multi-tenant isolation, 10+ workspaces, dedicated workflow tuning |
 
 </details>
 
@@ -270,6 +305,16 @@ Session tokens (`xoxc-` + `xoxd-`) from your browser. If you can see it in Slack
 
 Tokens expire. The server notices before you do — proactive health monitoring, automatic refresh on macOS, warnings when tokens age out. File writes are atomic (temp file → chmod → rename) to prevent corruption. Concurrent refresh attempts are mutex-locked.
 
+## What's New in 4.2.0
+
+- **Workflow primitives** — `slack_workflow_save` + `slack_workflows` bind a `workflow_kind` (`incident_room`, `exec_brief`, `support_inbox`, `product_launch_watch`, `custom`) to channels, priority people, retention, and cadence. The hosted brain returns structured JSON per kind — `incident_room` returns `{incident_summary, timeline, open_risks, owner_gaps, next_actions}`, `exec_brief` returns `{summary, decisions, risks, asks, action_items}`. Downstream automation (Linear, Notion, dashboards) consumes the JSON directly.
+- **Discoverable upgrade stubs** — `slack_smart_search`, `slack_catch_me_up`, `slack_triage` appear in OSS as upgrade payloads pointing at the hosted brain. Response shape is `{signup_url, free_tier_quota, pro_value_prop}` — no interruptions, the AI routes the user cleanly.
+- **Six prebuilt templates** — apply with `npx -y @jtalk22/slack-mcp --apply-template <name> --channels C012,C034`. Names: `oncall-handoff`, `support-triage`, `exec-monday`, `sprint-tracker`, `customer-feedback`, `incident-room`. Read them, fork them, edit them — they're JSON profiles.
+- **Setup wizard hosted bridge** — six in-wizard moments surface the hosted free tier (no card) where it matches the user's pain. Stays out of the way otherwise.
+- **Prior reliability fixes carried forward** — LevelDB token extraction, multi-profile enumeration, and explicit SIGTERM/SIGINT/SIGHUP/stdin shutdown handlers ship in 4.2.0 too.
+
+Full release notes on [GitHub releases/latest](https://github.com/jtalk22/slack-mcp-server/releases/latest).
+
 ## Hosted HTTP Mode
 
 For remote MCP endpoints (Cloudflare Worker, VPS, etc.):
@@ -326,4 +371,4 @@ Not affiliated with Slack Technologies, Inc. Uses browser session credentials
 
 ---
 
-Hosted version with semantic search, AI summaries, and permanent OAuth — coming soon at [mcp.revasserlabs.com](https://mcp.revasserlabs.com)
+Hosted version live at [mcp.revasserlabs.com](https://mcp.revasserlabs.com): Free tier (no card), $9/mo Pro, $49/mo Team flat, Ops from $199/mo. Hosted owns the AI brain (smart_search, catch_me_up, triage), the scheduled morning catch-up DM at 8am workspace time *(rolling out Q2 2026)*, permanent OAuth (no 2-week token rotation), 90-day Vectorize retention, and shared workflow profiles. The OSS package owns local stdio + all 16 read/write Slack tools + workflow profile primitives (slack_workflow_save, slack_workflows). The 3 paid stubs (slack_smart_search, slack_catch_me_up, slack_triage) appear in OSS as discoverable upgrade prompts.

package/docs/DEPLOYMENT-MODES.md

@@ -0,0 +1,56 @@
+# Deployment Modes
+
+Use this guide to choose the right operating mode before rollout.
+
+## Quick Chooser
+
+- Choose `stdio` for personal self-hosted use in Claude Desktop/Claude Code.
+- Choose local `web` for browser workflows and manual Slack browsing.
+- Choose hosted HTTP only when you need remote execution and can handle token operations.
+- Choose Smithery/Worker only when your consumers require registry-hosted MCP transport.
+- A managed **Hosted** version is live at [mcp.revasserlabs.com](https://mcp.revasserlabs.com) — Free tier (no card), Pro $9/mo, Team $49/mo flat, Ops from $199/mo. See [pricing](https://mcp.revasserlabs.com/pricing).
+
+## Mode Matrix
+
+| Mode | Start Command | Best For | Auth Material | Exposure | Notes |
+|------|---------------|----------|---------------|----------|-------|
+| Local MCP (`stdio`) | `npx -y @jtalk22/slack-mcp` | Individual daily usage in Claude | `SLACK_TOKEN` + `SLACK_COOKIE` via token file/env | Local process | Lowest ops burden. Free. 21 tools (16 read/write + 2 workflow profile primitives + 3 discoverable upgrade stubs to hosted). |
+| Local Web UI (`web`) | `npx -y @jtalk22/slack-mcp web` | Browser-first usage, manual search/send | Same as above + generated API key | `localhost` by default | Useful when MCP is not available |
+| Hosted MCP (`http`) | `node src/server-http.js` | Controlled hosted integration | Env-injected Slack token/cookie + HTTP bearer token | Remote endpoint | `/mcp` is bearer-protected by default; configure CORS allowlist |
+| Smithery/Worker | `wrangler deploy` + Smithery publish flow | Registry distribution for hosted consumers | Query/env token handoff | Remote endpoint | Keep worker version parity with npm release |
+
+## Team Deployment Guidance
+
+If you are deploying for more than one operator:
+
+1. Start with one maintainer on local `stdio`.
+2. Document token lifecycle and rotation ownership.
+3. Define support window and incident contact before enabling hosted mode.
+4. Validate `/health` and MCP initialize responses on every release.
+
+## Release Checklist by Mode
+
+### Local `stdio`
+
+1. `npx -y @jtalk22/slack-mcp --status`
+2. `npx -y @jtalk22/slack-mcp --help`
+3. Confirm tool list in Claude client.
+
+### Local `web`
+
+1. `npx -y @jtalk22/slack-mcp web`
+2. Verify API key generation at `~/.slack-mcp-api-key`.
+3. Verify `/health`, `/conversations`, and `/search` endpoints.
+
+### Hosted (`http` or Worker)
+
+1. Verify `version` parity across `package.json`, server metadata, and health responses.
+2. Verify HTTP auth behavior:
+   - missing `SLACK_MCP_HTTP_AUTH_TOKEN` returns `503`
+   - bad bearer token returns `401`
+   - valid bearer token succeeds
+3. Verify CORS behavior:
+   - denied by default
+   - allowed origins work when listed in `SLACK_MCP_HTTP_ALLOWED_ORIGINS`
+4. Confirm `slack_get_thread`, `slack_search_messages`, and `slack_users_info` behavior.
+5. Confirm token handling mode (ephemeral vs env persistence) is documented.

package/docs/TROUBLESHOOTING.md

@@ -31,7 +31,9 @@ If `--version` fails here, the issue is install/runtime path, not Slack credenti
 
 ## Hosted Version
 
-A hosted version with permanent OAuth tokens, semantic search, and AI summaries is coming soon at [mcp.revasserlabs.com](https://mcp.revasserlabs.com). The current release is self-hosted only.
+The hosted version is live at [mcp.revasserlabs.com](https://mcp.revasserlabs.com). Free tier (no card) ships 10 smart_search/mo + 3 catch_me_up/mo + 5 triage/day + all 5 workflow profile types. Pro at $9/mo unlocks unlimited AI tools, the scheduled morning catch-up DM at 8am workspace time *(rolling out Q2 2026)*, permanent OAuth (no 2-week token rotation), and 90-day Vectorize retention. Team at $49/mo flat covers 5 workspaces with shared workflow profiles and audit log. Ops engagement starts at $199/mo (custom) for 10+ workspace organizations with SLA, custom retention, SOC2 evidence, or multi-tenant isolation.
+
+The OSS package keeps the local-machine path. The hosted version adds the AI brain (smart_search, catch_me_up, triage) — these tools also appear in the OSS package as discoverable upgrade stubs that point at the hosted signup.
 
 ---
 

package/lib/handlers.js

@@ -16,6 +16,11 @@ import {
   getLastExtractionError
 } from "./token-store.js";
 import { slackAPI, resolveUser, formatTimestamp, sleep, checkTokenHealth, getUserCacheStats } from "./slack-client.js";
+import {
+  saveProfile as workflowSaveProfile,
+  listProfiles as workflowListProfiles,
+  ALLOWED_WORKFLOW_KINDS_LIST,
+} from "./workflow-store.js";
 
 // ============ Utilities ============
 
@@ -773,3 +778,90 @@ export async function handleUsersSearch(args) {
     users: allUsers.slice(0, limit)
   });
 }
+
+// ============ Workflow Profile Primitives (OSS) ============
+
+/**
+ * Save (or update) a workflow profile to ~/.slack-mcp-workflows.json
+ * Profile binds a workflow_kind to channels + priority_people + retention + cadence.
+ */
+export async function handleWorkflowSave(args) {
+  const safeArgs = args || {};
+  const result = workflowSaveProfile({
+    profile_name: safeArgs.profile_name,
+    workflow_kind: safeArgs.workflow_kind,
+    channels: safeArgs.channels,
+    priority_people: safeArgs.priority_people,
+    retention_mode: safeArgs.retention_mode,
+    summary_cadence: safeArgs.summary_cadence,
+  });
+  if (!result.ok) {
+    return asMcpJson({ error: "invalid_workflow_profile", errors: result.errors }, true);
+  }
+  return asMcpJson({
+    ok: true,
+    profile_name: result.profile_name,
+    profile: result.profile,
+    note: "Profile saved locally. Hosted free tier syncs profiles automatically when you connect your account; OSS-only mode keeps them on your machine.",
+  });
+}
+
+/**
+ * List saved workflow profiles, optionally filtered by workflow_kind.
+ */
+export async function handleWorkflows(args) {
+  const result = workflowListProfiles({ workflow_kind: args && args.workflow_kind });
+  if (!result.ok) {
+    return asMcpJson({ error: "invalid_workflow_filter", errors: result.errors }, true);
+  }
+  return asMcpJson({
+    ok: true,
+    count: result.profiles.length,
+    workflow_kinds: ALLOWED_WORKFLOW_KINDS_LIST,
+    profiles: result.profiles,
+  });
+}
+
+// ============ Hosted-Only AI Tool Stubs ============
+// These three tools appear in the OSS package's MCP tool list so users
+// discover them. The handlers return a structured upgrade message —
+// actual execution happens on the hosted worker (mcp.revasserlabs.com).
+
+const HOSTED_UPGRADE_PAYLOAD = {
+  error: "tool_requires_hosted",
+  message: "This tool needs hosted mode (Vectorize + Workers AI). Get free monthly credits at mcp.revasserlabs.com — no card required.",
+  signup_url: "https://mcp.revasserlabs.com/signup",
+  upgrade_url: "https://mcp.revasserlabs.com/pricing",
+  free_tier_quota: "10 smart_search + 3 catch_me_up per month, 5 triage per day",
+  pro_value_prop: "Pro $9/mo unlocks unlimited AI tools (scheduled morning catch-up DM at 8am workspace time rolling out Q2 2026).",
+};
+
+export async function handleSmartSearch(args) {
+  return asMcpJson(
+    {
+      ...HOSTED_UPGRADE_PAYLOAD,
+      requested: { tool: "slack_smart_search", args: args || {} },
+    },
+    true
+  );
+}
+
+export async function handleCatchMeUp(args) {
+  return asMcpJson(
+    {
+      ...HOSTED_UPGRADE_PAYLOAD,
+      requested: { tool: "slack_catch_me_up", args: args || {} },
+    },
+    true
+  );
+}
+
+export async function handleTriage(args) {
+  return asMcpJson(
+    {
+      ...HOSTED_UPGRADE_PAYLOAD,
+      requested: { tool: "slack_triage", args: args || {} },
+    },
+    true
+  );
+}

package/lib/public-metadata.js

@@ -18,5 +18,5 @@ export const PUBLIC_METADATA = Object.freeze({
   cloudSupportUrl: "https://mcp.revasserlabs.com/support",
   cloudStatusUrl: "https://mcp.revasserlabs.com/status",
   supportEmail: "support@revasserlabs.com",
-  selfHostedToolCount: 16,
+  selfHostedToolCount: 21,
 });

package/lib/public-pages.js

@@ -63,7 +63,7 @@ function shareLinks() {
 }
 
 function shareNote() {
-  return `<strong>Verify in 30 seconds:</strong> <code>--version</code>, <code>--doctor</code>, <code>--status</code>. Self-host gives ${PUBLIC_METADATA.selfHostedToolCount} tools with session-based auth. Works with any MCP client — Claude, ChatGPT, Cursor, Copilot, Gemini, Windsurf. Hosted version coming soon at <a href="${PUBLIC_METADATA.canonicalSiteUrl}">mcp.revasserlabs.com</a>.`;
+  return `<strong>Verify in 30 seconds:</strong> <code>--version</code>, <code>--doctor</code>, <code>--status</code>. Self-host gives ${PUBLIC_METADATA.selfHostedToolCount} tools with session-based auth. Works with any MCP client — Claude, ChatGPT, Cursor, Copilot, Gemini, Windsurf. Hosted free tier (no card) live at <a href="${PUBLIC_METADATA.canonicalSiteUrl}">mcp.revasserlabs.com</a> — Pro $9/mo unlocks unlimited AI tools (scheduled morning catch-up DM rolling out Q2 2026).`;
 }
 
 function demoLinks() {
@@ -75,7 +75,7 @@ function demoLinks() {
 }
 
 function demoNote() {
-  return `Self-host free for ${PUBLIC_METADATA.selfHostedToolCount} tools with session-based auth. Works with Claude, ChatGPT, Cursor, Copilot, Gemini, Windsurf, and any other MCP client. No OAuth app, no admin approval. Hosted version coming soon at <a href="${PUBLIC_METADATA.canonicalSiteUrl}" target="_blank" rel="noopener noreferrer">mcp.revasserlabs.com</a>.`;
+  return `Self-host free for ${PUBLIC_METADATA.selfHostedToolCount} tools with session-based auth. Works with Claude, ChatGPT, Cursor, Copilot, Gemini, Windsurf, and any other MCP client. No OAuth app, no admin approval. Hosted free tier (no card) live at <a href="${PUBLIC_METADATA.canonicalSiteUrl}" target="_blank" rel="noopener noreferrer">mcp.revasserlabs.com</a> — Pro $9/mo unlocks unlimited AI tools (scheduled morning catch-up DM rolling out Q2 2026).`;
 }
 
 function demoFooterLinks() {
@@ -113,8 +113,8 @@ function commonTokens() {
     SELF_HOSTED_TOOL_COUNT: String(PUBLIC_METADATA.selfHostedToolCount),
     CLOUD_MANAGED_TOOL_COUNT: "15",
     TEAM_AI_WORKFLOW_COUNT: "3",
-    CLOUD_SOLO_PRICE: "coming soon",
-    CLOUD_TEAM_PRICE: "coming soon",
+    CLOUD_SOLO_PRICE: "$9/mo",
+    CLOUD_TEAM_PRICE: "$49/mo",
     CLOUD_TURNKEY_LAUNCH_PRICE: "contact us",
     CLOUD_MANAGED_RELIABILITY_PRICE: "contact us",
     SUPPORT_EMAIL: PUBLIC_METADATA.supportEmail,

package/lib/slack-client.js

@@ -9,12 +9,19 @@
  * - Proactive token health checking
  */
 
-import { loadTokens, saveTokens, extractFromChrome } from "./token-store.js";
+import {
+  loadTokens,
+  saveTokens,
+  extractFromChrome,
+  getLastExtractionError,
+  saveAutoHealTelemetry,
+} from "./token-store.js";
 
 // ============ Configuration ============
 
 const TOKEN_WARNING_AGE = 10 * 24 * 60 * 60 * 1000;   // 10 days
 const TOKEN_CRITICAL_AGE = 13 * 24 * 60 * 60 * 1000;  // 13 days
+const STUCK_THRESHOLD_MS = 24 * 60 * 60 * 1000;       // Escalate to 'stuck' after 24h of repeated auto-heal failures
 const REFRESH_COOLDOWN = 60 * 60 * 1000;        // 1 hour between refresh attempts
 const USER_CACHE_MAX_SIZE = 500;
 const USER_CACHE_TTL = 60 * 60 * 1000;          // 1 hour
@@ -113,14 +120,21 @@ export async function checkTokenHealth(logger = console) {
     ? Math.round(tokenAge / (60 * 60 * 1000) * 10) / 10
     : null;
 
+  // Read auto-heal telemetry (only populated when source is "file")
+  let lastAutoHealAttempt = creds.lastAutoHealAttempt || null;
+  let lastAutoHealError = creds.lastAutoHealError || null;
+  let stuckSince = creds.stuckSince || null;
+
   // Attempt proactive refresh if token is getting old
   if (hasKnownAge && tokenAge > TOKEN_WARNING_AGE && Date.now() - lastRefreshAttempt > REFRESH_COOLDOWN) {
     lastRefreshAttempt = Date.now();
+    const attemptAt = new Date().toISOString();
     logger.error?.(`Token is ${ageHours}h old, attempting proactive refresh...`);
 
     const newTokens = extractFromChrome();
     if (newTokens) {
       saveTokens(newTokens.token, newTokens.cookie);
+      saveAutoHealTelemetry({ attemptAt, error: null });
       logger.error?.('Proactively refreshed tokens from Chrome');
       return {
         healthy: true,
@@ -129,35 +143,59 @@ export async function checkTokenHealth(logger = console) {
         age_known: true,
         age_state: 'fresh',
         source: 'chrome-auto',
+        last_auto_heal_attempt: attemptAt,
+        last_auto_heal_error: null,
+        stuck_since: null,
         message: 'Tokens refreshed successfully'
       };
     } else {
-      logger.error?.('Could not refresh from Chrome (is Slack tab open?)');
+      const extractionError = getLastExtractionError();
+      const errorCode = extractionError?.code || 'chrome_extraction_failed';
+      saveAutoHealTelemetry({ attemptAt, error: errorCode });
+      lastAutoHealAttempt = attemptAt;
+      if (lastAutoHealError !== errorCode) {
+        stuckSince = attemptAt;
+      }
+      lastAutoHealError = errorCode;
+      logger.error?.(`Could not refresh from Chrome: ${extractionError?.message || 'unknown error'}`);
     }
   }
 
+  const stuckSinceMs = stuckSince ? new Date(stuckSince).getTime() : Number.NaN;
+  const isStuck = Number.isFinite(stuckSinceMs)
+    && (Date.now() - stuckSinceMs) > STUCK_THRESHOLD_MS
+    && !!lastAutoHealError;
+
   return {
     healthy: !hasKnownAge || tokenAge < TOKEN_CRITICAL_AGE,
     age_hours: ageHours,
     age_known: hasKnownAge,
-    age_state: !hasKnownAge
-      ? 'unknown'
-      : tokenAge > TOKEN_CRITICAL_AGE
-        ? 'critical'
-        : tokenAge > TOKEN_WARNING_AGE
-          ? 'warning'
-          : 'healthy',
+    age_state: isStuck
+      ? 'stuck'
+      : !hasKnownAge
+        ? 'unknown'
+        : tokenAge > TOKEN_CRITICAL_AGE
+          ? 'critical'
+          : tokenAge > TOKEN_WARNING_AGE
+            ? 'warning'
+            : 'healthy',
     warning: hasKnownAge && tokenAge > TOKEN_WARNING_AGE,
     critical: hasKnownAge && tokenAge > TOKEN_CRITICAL_AGE,
+    stuck: isStuck,
     source: creds.source,
     updated_at: creds.updatedAt,
-    message: !hasKnownAge
-      ? 'Token age unknown (missing timestamp) - auth can still be valid'
-      : tokenAge > TOKEN_CRITICAL_AGE
-        ? 'Token may expire soon - open Slack in Chrome'
-        : tokenAge > TOKEN_WARNING_AGE
-          ? 'Token is getting old - will auto-refresh if Slack tab is open'
-          : 'Token is healthy'
+    last_auto_heal_attempt: lastAutoHealAttempt,
+    last_auto_heal_error: lastAutoHealError,
+    stuck_since: stuckSince,
+    message: isStuck
+      ? `Auto-heal has been failing since ${stuckSince} (last error: ${lastAutoHealError}). Open Chrome > View > Developer > Allow JavaScript from Apple Events, then run npm run tokens:auto.`
+      : !hasKnownAge
+        ? 'Token age unknown (missing timestamp) - auth can still be valid'
+        : tokenAge > TOKEN_CRITICAL_AGE
+          ? 'Token may expire soon - open Slack in Chrome'
+          : tokenAge > TOKEN_WARNING_AGE
+            ? 'Token is getting old - will auto-refresh if Slack tab is open'
+            : 'Token is healthy'
   };
 }
 
@@ -250,13 +288,28 @@ export async function slackAPI(method, params = {}, options = {}) {
     // Handle auth errors with auto-retry
     if ((data.error === "invalid_auth" || data.error === "token_expired") && retryOnAuthFail) {
       logger.error?.("Token expired, attempting Chrome auto-extraction...");
+      const attemptAt = new Date().toISOString();
       const chromeTokens = extractFromChrome();
       if (chromeTokens) {
         saveTokens(chromeTokens.token, chromeTokens.cookie);
+        saveAutoHealTelemetry({ attemptAt, error: null });
         // Retry the request
         return slackAPI(method, params, { ...options, retryOnAuthFail: false });
       }
-      throw new Error(`${data.error} - Tokens expired. Open Slack in Chrome and use slack_refresh_tokens.`);
+      const extractionError = getLastExtractionError() || {
+        code: 'chrome_extraction_failed',
+        message: 'Auto-heal attempted but no structured error surfaced.',
+        detail: null
+      };
+      saveAutoHealTelemetry({ attemptAt, error: extractionError.code });
+      const err = new Error(
+        `Slack auth failed (${data.error}) and auto-heal could not refresh tokens: ${extractionError.message}`
+      );
+      err.code = 'token_auth_failed';
+      err.slack_error = data.error;
+      err.extraction_error = extractionError;
+      err.next_action = 'Open http://localhost:3000 and click Refresh, OR run `npm run tokens:auto` with Slack open in Chrome, OR check Chrome > View > Developer > Allow JavaScript from Apple Events.';
+      throw err;
     }
     throw new Error(data.error || "Slack API error");
   }