@adaptic/maestro 1.0.0

package/scripts/slack-react.mjs

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+/**
+ * Slack Reaction Utility — Add emoji reactions to Slack messages.
+ *
+ * Used by Sophie's Claude Code sessions to react to messages.
+ * This is a thin wrapper around the Slack reactions.add API.
+ *
+ * Usage:
+ *   node scripts/slack-react.mjs <channel_id> <message_ts> <emoji_name>
+ *
+ * Examples:
+ *   node scripts/slack-react.mjs C0ARASMQE1W 1775472843.039059 eyes
+ *   node scripts/slack-react.mjs D099N1JGKRQ 1775472955.681459 white_check_mark
+ *
+ * Common emoji names:
+ *   eyes           — acknowledged / looking into it
+ *   white_check_mark — done / approved
+ *   thumbsup       — agreed / positive
+ *   thumbsdown     — disagreed / negative
+ *   hourglass_flowing_sand — working on it
+ *   heavy_check_mark — completed
+ *   warning        — flagged for attention
+ *   rocket         — shipped / deployed
+ *   brain          — thinking / reviewing
+ *
+ * Exit codes:
+ *   0 — success
+ *   1 — error (missing args, API failure)
+ */
+
+import { readFileSync, existsSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = join(__dirname, "..");
+
+// Load .env
+const envPath = join(ROOT, ".env");
+if (existsSync(envPath)) {
+  const envContent = readFileSync(envPath, "utf-8");
+  for (const line of envContent.split("\n")) {
+    const match = line.match(/^([A-Z_][A-Z0-9_]*)=(.*)$/);
+    if (match) {
+      let val = match[2].trim();
+      if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
+        val = val.slice(1, -1);
+      }
+      process.env[match[1]] = val;
+    }
+  }
+}
+
+const [channel, timestamp, emoji] = process.argv.slice(2);
+
+if (!channel || !timestamp || !emoji) {
+  console.error("Usage: node scripts/slack-react.mjs <channel_id> <message_ts> <emoji_name>");
+  process.exit(1);
+}
+
+const token = process.env.SLACK_BOT_TOKEN || process.env.SLACK_USER_TOKEN || process.env.SLACK_TOKEN;
+if (!token) {
+  console.error("Error: No Slack token found (SLACK_BOT_TOKEN, SLACK_USER_TOKEN, or SLACK_TOKEN)");
+  process.exit(1);
+}
+
+try {
+  const res = await fetch("https://slack.com/api/reactions.add", {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${token}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({ channel, timestamp, name: emoji }),
+  });
+  const body = await res.json();
+
+  if (body.ok) {
+    console.log(`Reacted with :${emoji}: on ${channel}/${timestamp}`);
+  } else if (body.error === "already_reacted") {
+    console.log(`Already reacted with :${emoji}: (no-op)`);
+  } else {
+    console.error(`Slack API error: ${body.error}`);
+    process.exit(1);
+  }
+} catch (err) {
+  console.error(`Error: ${err.message}`);
+  process.exit(1);
+}

package/scripts/slack-responded.sh

@@ -0,0 +1,185 @@
+#!/bin/bash
+# slack-responded.sh — Atomic response deduplication for Slack messages
+# Prevents duplicate responses from concurrent sessions using mkdir-based locking
+#
+# The key insight: `mkdir` is atomic on POSIX systems. Two concurrent processes
+# calling `mkdir` on the same path will have exactly one succeed and one fail.
+# This eliminates the race condition in the old check-then-write approach.
+#
+# Usage:
+#   ./scripts/slack-responded.sh acquire <channel_id> <message_ts> [session_id]
+#     → exits 0 if lock acquired (you should send), 1 if already locked (skip)
+#     → On success, creates lock dir + metadata file atomically
+#
+#   ./scripts/slack-responded.sh confirm <channel_id> <message_ts> [message_preview]
+#     → Called after successful send to record details in the lock
+#
+#   ./scripts/slack-responded.sh check <message_ts> [channel_id]
+#     → exits 0 if already handled, 1 if not (backward-compatible)
+#
+#   ./scripts/slack-responded.sh mark <message_ts>
+#     → marks message as handled (backward-compatible, legacy)
+#
+#   ./scripts/slack-responded.sh clean
+#     → purge entries older than 24h
+set -e
+
+LOCK_BASE_DIR="/Users/sophie/sophie-ai/state/locks/slack-response"
+LEGACY_DIR="/Users/sophie/sophie-ai/state/slack-responded"
+LOCK_TTL_MINUTES=1440  # 24 hours — thread-level dedup needs long TTL to prevent cross-session duplicates
+
+mkdir -p "$LOCK_BASE_DIR"
+mkdir -p "$LEGACY_DIR"
+
+ACTION="${1:-}"
+TIMESTAMP=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+
+# Helper: check if a lock path (directory or file) is still valid (< LOCK_TTL_MINUTES old)
+lock_is_valid() {
+  local lock_path="$1"
+  if [ ! -e "$lock_path" ]; then
+    return 1
+  fi
+  # Check age of lock path (works for both directories and files)
+  local lock_age
+  if [[ "$(uname)" == "Darwin" ]]; then
+    lock_age=$(( ( $(date +%s) - $(stat -f %m "$lock_path") ) / 60 ))
+  else
+    lock_age=$(( ( $(date +%s) - $(stat -c %Y "$lock_path") ) / 60 ))
+  fi
+  [ "$lock_age" -lt "$LOCK_TTL_MINUTES" ]
+}
+
+case "$ACTION" in
+  acquire)
+    # acquire <channel_id> <message_ts> [session_id]
+    # Attempts to atomically acquire a response lock.
+    # Returns 0 if lock acquired (caller should proceed to send).
+    # Returns 1 if lock already held (caller should skip sending).
+    CHANNEL="${2:?Channel ID required}"
+    MSG_TS="${3:?Message TS required}"
+    SESSION_ID="${4:-unknown}"
+
+    LOCK_DIR="$LOCK_BASE_DIR/${CHANNEL}-${MSG_TS}"
+
+    # Check for existing valid lock
+    if lock_is_valid "$LOCK_DIR"; then
+      echo "LOCKED: Response already claimed for $CHANNEL:$MSG_TS"
+      exit 1
+    fi
+
+    # If stale lock exists, remove it
+    if [ -d "$LOCK_DIR" ]; then
+      rm -rf "$LOCK_DIR"
+    fi
+
+    # Atomic lock acquisition via mkdir
+    # mkdir will fail if another process creates it between our check and this call
+    if mkdir "$LOCK_DIR" 2>/dev/null; then
+      # Lock acquired — write metadata
+      cat > "$LOCK_DIR/meta" << EOF
+acquired: "$TIMESTAMP"
+session: "$SESSION_ID"
+channel: "$CHANNEL"
+message_ts: "$MSG_TS"
+status: acquired
+EOF
+      # Also write legacy marker for backward compatibility
+      echo "$TIMESTAMP" > "$LEGACY_DIR/$MSG_TS"
+      echo "ACQUIRED"
+      exit 0
+    else
+      # Another process beat us to it
+      echo "LOCKED: Response already claimed for $CHANNEL:$MSG_TS (race lost)"
+      exit 1
+    fi
+    ;;
+
+  confirm)
+    # confirm <channel_id> <message_ts> [message_preview]
+    # Called after a successful send to record what was sent.
+    CHANNEL="${2:?Channel ID required}"
+    MSG_TS="${3:?Message TS required}"
+    PREVIEW="${4:-}"
+
+    LOCK_DIR="$LOCK_BASE_DIR/${CHANNEL}-${MSG_TS}"
+
+    if [ -d "$LOCK_DIR" ]; then
+      # Preserve the original acquisition timestamp
+      ORIG_ACQUIRED=$(grep 'acquired:' "$LOCK_DIR/meta" 2>/dev/null | head -1 | sed 's/^acquired: *//' | tr -d '"' || echo "$TIMESTAMP")
+      if [ -z "$ORIG_ACQUIRED" ]; then ORIG_ACQUIRED="$TIMESTAMP"; fi
+      SAFE_PREVIEW=$(echo "$PREVIEW" | head -c 200 | tr '"' "'")
+      cat > "$LOCK_DIR/meta" << EOF
+acquired: "$ORIG_ACQUIRED"
+confirmed: "$TIMESTAMP"
+channel: "$CHANNEL"
+message_ts: "$MSG_TS"
+status: confirmed
+preview: "$SAFE_PREVIEW"
+EOF
+    fi
+    # Update legacy marker
+    echo "$TIMESTAMP" > "$LEGACY_DIR/$MSG_TS"
+    echo "CONFIRMED"
+    ;;
+
+  check)
+    # check <message_ts> [channel_id]
+    # Backward-compatible check. Returns 0 if already handled, 1 if not.
+    MSG_TS="${2:?Message TS required}"
+    CHANNEL="${3:-}"
+
+    # If channel is provided, check the atomic lock first
+    if [ -n "$CHANNEL" ]; then
+      LOCK_DIR="$LOCK_BASE_DIR/${CHANNEL}-${MSG_TS}"
+      if lock_is_valid "$LOCK_DIR"; then
+        exit 0  # Already handled
+      fi
+    fi
+
+    # Also check any lock matching this message_ts (across all channels)
+    for lock in "$LOCK_BASE_DIR"/*-"${MSG_TS}"; do
+      if [ -d "$lock" ] && lock_is_valid "$lock"; then
+        exit 0  # Already handled
+      fi
+    done
+
+    # Fall back to legacy flat-file check
+    if [ -f "$LEGACY_DIR/$MSG_TS" ]; then
+      if lock_is_valid "$LEGACY_DIR/$MSG_TS"; then
+        exit 0  # Recently handled
+      fi
+      # Legacy file exists but is old — still treat as handled for backward compat
+      exit 0
+    fi
+
+    exit 1  # Not yet handled
+    ;;
+
+  mark)
+    # mark <message_ts> — backward-compatible mark
+    MSG_TS="${2:?Message TS required}"
+    echo "$TIMESTAMP" > "$LEGACY_DIR/$MSG_TS"
+    ;;
+
+  clean)
+    # Purge entries older than 24 hours
+    # Clean lock directories
+    find "$LOCK_BASE_DIR" -maxdepth 1 -type d -mmin +1440 -exec rm -rf {} + 2>/dev/null || true
+    # Clean legacy flat files
+    find "$LEGACY_DIR" -type f -mmin +1440 -delete 2>/dev/null || true
+    echo "Cleaned entries older than 24h"
+    ;;
+
+  *)
+    echo "Usage: slack-responded.sh {acquire|confirm|check|mark|clean} [args...]"
+    echo ""
+    echo "Commands:"
+    echo "  acquire <channel> <msg_ts> [session_id]  — Atomically claim a response lock"
+    echo "  confirm <channel> <msg_ts> [preview]      — Record successful send"
+    echo "  check <msg_ts> [channel]                   — Check if already handled"
+    echo "  mark <msg_ts>                              — Legacy: mark as handled"
+    echo "  clean                                       — Purge old entries"
+    exit 2
+    ;;
+esac

package/scripts/slack-send.sh

@@ -0,0 +1,190 @@
+#!/bin/bash
+# slack-send.sh — Send Slack message as Sophie via User OAuth Token (xoxp-)
+# Messages appear as Sophie's user account, NOT the bot app.
+# Usage: ./scripts/slack-send.sh <channel_id> <message> [--thread_ts <ts>]
+set -e
+
+source /Users/sophie/sophie-ai/.env
+
+# ENFORCEMENT: Must use User Token (xoxp-), never Bot Token (xoxb-)
+# Per CEO directive: all Slack sends must come from user scope so messages
+# appear as Sophie Nguyen, not the Adaptic COO bot.
+SLACK_SEND_TOKEN="${SLACK_USER_TOKEN}"
+if [ -z "$SLACK_SEND_TOKEN" ]; then
+  echo "ERROR: SLACK_USER_TOKEN not set in .env — cannot send as user scope" >&2
+  exit 1
+fi
+if [[ "$SLACK_SEND_TOKEN" == xoxb-* ]]; then
+  echo "ERROR: SLACK_SEND_TOKEN is a bot token (xoxb-). Must use user token (xoxp-)." >&2
+  exit 1
+fi
+
+CHANNEL="$1"
+MESSAGE="$2"
+THREAD_TS=""
+RESPONDING_TO=""
+SKIP_TYPING=""
+
+# Parse optional flags
+shift 2 2>/dev/null || true
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --thread_ts)
+      THREAD_TS="$2"
+      shift 2
+      ;;
+    --responding_to)
+      RESPONDING_TO="$2"
+      shift 2
+      ;;
+    --no-typing)
+      SKIP_TYPING="1"
+      shift
+      ;;
+    *)
+      shift
+      ;;
+  esac
+done
+
+# Allow env override to disable typing globally
+if [ "${SLACK_TYPING_ENABLED:-1}" = "0" ]; then
+  SKIP_TYPING="1"
+fi
+
+if [ -z "$CHANNEL" ] || [ -z "$MESSAGE" ]; then
+  echo "Usage: slack-send.sh <channel_id> <message> [--thread_ts <ts>] [--responding_to <ts>]"
+  exit 1
+fi
+
+# Dedup check: if --responding_to is set, use atomic locking to prevent concurrent sends
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+DEDUP_ACQUIRED=""
+if [ -n "$RESPONDING_TO" ]; then
+  # Atomic lock acquisition (mkdir-based, race-safe)
+  # This is the primary dedup mechanism. mkdir is atomic on POSIX — if two sessions
+  # race to respond to the same message, exactly one will succeed and the other will
+  # get LOCKED and skip. This eliminates the check-then-write race condition.
+  SESSION_ID="${SOPHIE_SESSION_ID:-$$}"
+  ACQUIRE_RESULT=$("$SCRIPT_DIR/slack-responded.sh" acquire "$CHANNEL" "$RESPONDING_TO" "$SESSION_ID" 2>/dev/null) || true
+  if [ "$ACQUIRE_RESULT" != "ACQUIRED" ]; then
+    echo "DEDUP_SKIP"
+    exit 0
+  fi
+  DEDUP_ACQUIRED="1"
+fi
+
+# Show typing indicator before sending (non-blocking, fire-and-forget)
+# This makes Sophie's presence feel human — the "Sophie is typing..." dots appear
+# before the message arrives. Requires rtm:stream scope on user token; degrades gracefully.
+TYPING_DURATION=2500
+MSG_LEN=${#MESSAGE}
+if [ "$MSG_LEN" -gt 500 ]; then
+  TYPING_DURATION=4000
+elif [ "$MSG_LEN" -gt 200 ]; then
+  TYPING_DURATION=3000
+elif [ "$MSG_LEN" -lt 50 ]; then
+  TYPING_DURATION=1500
+fi
+
+# Run typing indicator synchronously. The script connects via WebSocket, sends typing
+# events for TYPING_DURATION ms, then exits. If rtm:stream scope is missing, it exits
+# immediately with no delay — the message sends without the typing indicator.
+if [ -z "$SKIP_TYPING" ] && [ -f "$SCRIPT_DIR/slack-typing.mjs" ]; then
+  /opt/homebrew/bin/node "$SCRIPT_DIR/slack-typing.mjs" "$CHANNEL" "$TYPING_DURATION" 2>/dev/null || true
+fi
+
+# ── Pre-draft context enrichment (Phase 7) ─────────────────────
+# Look up recipient in entity index before sending. Advisory only — never blocks.
+# Logs context to logs/audit/{date}-pre-draft-lookups.jsonl for audit trail.
+if [ -f "$SCRIPT_DIR/pre_draft_lookup.py" ]; then
+  python3 "$SCRIPT_DIR/pre_draft_lookup.py" --recipient "$CHANNEL" --type slack --channel "$CHANNEL" 2>/dev/null >/dev/null || true
+fi
+
+# ── Pre-send factual validation ─────────────────────────────────
+# Checks relationship claims, AI disclosure, in-person scheduling, title accuracy
+# Blocks send if critical issues found. Fail-open on errors.
+if [ -f "$SCRIPT_DIR/validate-outbound.py" ]; then
+  VALIDATION_RESULT=$(echo "$MESSAGE" | python3 "$SCRIPT_DIR/validate-outbound.py" --type slack --recipient "$CHANNEL" --quiet 2>/dev/null) || VALIDATION_EXIT=$?
+  VALIDATION_EXIT=${VALIDATION_EXIT:-0}
+  if [ "$VALIDATION_EXIT" = "1" ]; then
+    BLOCKERS=$(echo "$VALIDATION_RESULT" | python3 -c "import json,sys; d=json.load(sys.stdin); print(d.get('metadata',{}).get('blockers',0))" 2>/dev/null) || BLOCKERS=0
+    if [ "$BLOCKERS" -gt 0 ]; then
+      echo "VALIDATION_BLOCK: $BLOCKERS issue(s) found in Slack message to $CHANNEL"
+      echo "$VALIDATION_RESULT" | python3 -c "
+import json,sys
+d=json.load(sys.stdin)
+for i in d.get('issues',[]):
+    if i.get('severity')=='block':
+        print(f\"  [{i['type']}] {i['description']}\")
+        if i.get('suggestion'): print(f\"    -> {i['suggestion']}\")
+" 2>/dev/null || true
+      echo "Fix the above issues before sending." >&2
+      exit 1
+    fi
+  fi
+fi
+
+# Convert markdown to Slack mrkdwn format before sending
+# Slack uses its own mrkdwn syntax which differs from standard markdown:
+#   Bold:          *text*     (not **text**)
+#   Italic:        _text_     (same as markdown)
+#   Strikethrough: ~text~     (not ~~text~~)
+#   Links:         <url|text> (not [text](url))
+#   Headings:      not supported — converted to *bold* text
+#   Images:        not supported — converted to <url|alt> links
+#   HR (---):      converted to Unicode line separator
+MESSAGE=$(python3 -c "
+import sys, re
+msg = sys.argv[1]
+# 1. Convert markdown images ![alt](url) to <url|alt> (strip the !)
+msg = re.sub(r'!\[([^\]]*)\]\(([^)]+)\)', r'<\2|\1>', msg)
+# 2. Convert ***bold italic*** to *_bold italic_* (must come before ** rule)
+msg = re.sub(r'\*\*\*(.+?)\*\*\*', r'*_\1_*', msg)
+# 3. Convert **bold** to *bold* (markdown bold to Slack bold)
+msg = re.sub(r'\*\*(.+?)\*\*', r'*\1*', msg)
+# 4. Convert __bold__ to *bold* (underscore bold variant)
+msg = re.sub(r'__(.+?)__', r'*\1*', msg)
+# 5. Convert ~~strikethrough~~ to ~strikethrough~ (Slack format)
+msg = re.sub(r'~~(.+?)~~', r'~\1~', msg)
+# 6. Convert [text](url) to <url|text> (markdown links to Slack links)
+msg = re.sub(r'(?<!!)\[([^\]]+)\]\(([^)]+)\)', r'<\2|\1>', msg)
+# 7. Convert headings to bold text (process longer prefixes first)
+msg = re.sub(r'^####\s+(.+)$', r'*\1*', msg, flags=re.MULTILINE)
+msg = re.sub(r'^###\s+(.+)$', r'*\1*', msg, flags=re.MULTILINE)
+msg = re.sub(r'^##\s+(.+)$', r'*\1*', msg, flags=re.MULTILINE)
+msg = re.sub(r'^#\s+(.+)$', r'*\1*', msg, flags=re.MULTILINE)
+# 8. Convert horizontal rules (---, ***, ___) to Unicode line
+msg = re.sub(r'^[-*_]{3,}\s*$', '───────────────────────────', msg, flags=re.MULTILINE)
+print(msg)
+" "$MESSAGE")
+
+# Escape message for JSON
+ESCAPED=$(python3 -c "import json,sys; print(json.dumps(sys.argv[1]))" "$MESSAGE")
+
+# Build JSON payload
+if [ -n "$THREAD_TS" ]; then
+  PAYLOAD="{\"channel\":\"$CHANNEL\",\"text\":$ESCAPED,\"thread_ts\":\"$THREAD_TS\"}"
+else
+  PAYLOAD="{\"channel\":\"$CHANNEL\",\"text\":$ESCAPED}"
+fi
+
+RESULT=$(curl -s -X POST "https://slack.com/api/chat.postMessage" \
+  -H "Authorization: Bearer $SLACK_SEND_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d "$PAYLOAD")
+
+STATUS=$(echo "$RESULT" | python3 -c "import json,sys; d=json.load(sys.stdin); print('OK' if d['ok'] else d.get('error','fail'))")
+echo "$STATUS"
+
+# If we get a token_revoked or invalid_auth error, surface it clearly
+if [ "$STATUS" = "invalid_auth" ] || [ "$STATUS" = "token_revoked" ] || [ "$STATUS" = "not_authed" ]; then
+  echo "ERROR: User token auth failed ($STATUS). Check SLACK_USER_TOKEN in .env" >&2
+  exit 1
+fi
+
+# Post-send: confirm the response lock with message details (audit trail)
+if [ "$STATUS" = "OK" ] && [ -n "$RESPONDING_TO" ] && [ -n "$DEDUP_ACQUIRED" ]; then
+  PREVIEW=$(echo "$MESSAGE" | head -c 200)
+  "$SCRIPT_DIR/slack-responded.sh" confirm "$CHANNEL" "$RESPONDING_TO" "$PREVIEW" 2>/dev/null || true
+fi

package/scripts/slack-typing.mjs

@@ -0,0 +1,196 @@
+#!/usr/bin/env /opt/homebrew/bin/node
+/**
+ * slack-typing.mjs — Send Slack typing indicator as Sophie
+ *
+ * Shows the "Sophie is typing..." indicator in a channel/DM before
+ * a message is sent, making Sophie's presence feel human and real.
+ *
+ * Approach: Connect to Slack RTM (WebSocket), send a `typing` event,
+ * hold the connection for the specified duration, then disconnect.
+ *
+ * Usage:
+ *   node scripts/slack-typing.mjs <channel_id> [duration_ms]
+ *   node scripts/slack-typing.mjs D0AQFT276KX 3000
+ *
+ * Requires: SLACK_USER_TOKEN with rtm:stream scope in .env
+ *
+ * If rtm:stream scope is missing, exits gracefully with code 0
+ * (typing is a nice-to-have, not a blocker for message delivery).
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(__dirname, "..");
+
+// Load env
+const envPath = path.join(ROOT, ".env");
+if (fs.existsSync(envPath)) {
+  const envContent = fs.readFileSync(envPath, "utf-8");
+  for (const line of envContent.split("\n")) {
+    const match = line.match(/^([A-Z_][A-Z0-9_]*)=(.+)$/);
+    if (match) process.env[match[1]] = match[2];
+  }
+}
+
+const SLACK_USER_TOKEN = process.env.SLACK_USER_TOKEN;
+const CHANNEL = process.argv[2];
+const DURATION_MS = parseInt(process.argv[3] || "2500", 10);
+const TYPING_INTERVAL_MS = 3000; // Slack typing indicator lasts ~3s, re-send to keep it alive
+
+if (!CHANNEL) {
+  console.error("Usage: slack-typing.mjs <channel_id> [duration_ms]");
+  process.exit(1);
+}
+
+if (!SLACK_USER_TOKEN) {
+  console.error(
+    "[slack-typing] No SLACK_USER_TOKEN — skipping typing indicator",
+  );
+  process.exit(0);
+}
+
+/**
+ * Get RTM WebSocket URL from Slack
+ */
+async function getRtmUrl() {
+  const resp = await fetch("https://slack.com/api/rtm.connect", {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${SLACK_USER_TOKEN}`,
+      "Content-Type": "application/json",
+    },
+  });
+  const data = await resp.json();
+
+  if (!data.ok) {
+    if (data.error === "missing_scope") {
+      console.error(
+        `[slack-typing] User token missing rtm:stream scope. ` +
+          `Add it at https://api.slack.com/apps → OAuth & Permissions → User Token Scopes → add rtm:stream, then reinstall.`,
+      );
+      return null;
+    }
+    console.error(`[slack-typing] rtm.connect failed: ${data.error}`);
+    return null;
+  }
+
+  return data.url;
+}
+
+/**
+ * Connect to RTM WebSocket and send typing events
+ */
+async function sendTypingIndicator(wssUrl, channel, durationMs) {
+  return new Promise((resolve) => {
+    const ws = new WebSocket(wssUrl);
+    let msgId = 1;
+    let typingTimer = null;
+    let cleanupTimer = null;
+
+    function sendTyping() {
+      if (ws.readyState === WebSocket.OPEN) {
+        ws.send(
+          JSON.stringify({
+            id: msgId++,
+            type: "typing",
+            channel: channel,
+          }),
+        );
+      }
+    }
+
+    function cleanup() {
+      if (typingTimer) clearInterval(typingTimer);
+      if (cleanupTimer) clearTimeout(cleanupTimer);
+      if (
+        ws.readyState === WebSocket.OPEN ||
+        ws.readyState === WebSocket.CONNECTING
+      ) {
+        ws.close();
+      }
+      resolve();
+    }
+
+    ws.addEventListener("open", () => {
+      // Send initial typing event immediately
+      sendTyping();
+
+      // If duration is longer than one typing interval, re-send to keep indicator alive
+      if (durationMs > TYPING_INTERVAL_MS) {
+        typingTimer = setInterval(sendTyping, TYPING_INTERVAL_MS);
+      }
+
+      // Close after duration
+      cleanupTimer = setTimeout(cleanup, durationMs);
+    });
+
+    ws.addEventListener("error", (err) => {
+      console.error(`[slack-typing] WebSocket error: ${err.message || err}`);
+      cleanup();
+    });
+
+    ws.addEventListener("close", () => {
+      if (typingTimer) clearInterval(typingTimer);
+      if (cleanupTimer) clearTimeout(cleanupTimer);
+      resolve();
+    });
+
+    // Safety timeout — never hang longer than 15 seconds
+    setTimeout(cleanup, 15000);
+  });
+}
+
+/**
+ * Cache RTM URL to avoid reconnecting for every message
+ * Cache file stores the URL and a timestamp; valid for 30 seconds
+ */
+const CACHE_FILE = path.join(ROOT, "state/.slack-rtm-cache.json");
+const CACHE_TTL_MS = 25000; // 25 seconds (RTM URLs expire after ~30s)
+
+async function getCachedOrFreshRtmUrl() {
+  // Check cache
+  try {
+    if (fs.existsSync(CACHE_FILE)) {
+      const cache = JSON.parse(fs.readFileSync(CACHE_FILE, "utf-8"));
+      if (Date.now() - cache.timestamp < CACHE_TTL_MS && cache.url) {
+        return cache.url;
+      }
+    }
+  } catch {
+    // Cache corrupted, fetch fresh
+  }
+
+  const url = await getRtmUrl();
+  if (url) {
+    try {
+      fs.writeFileSync(
+        CACHE_FILE,
+        JSON.stringify({ url, timestamp: Date.now() }),
+        "utf-8",
+      );
+    } catch {
+      // Non-critical
+    }
+  }
+  return url;
+}
+
+// Main
+async function main() {
+  const wssUrl = await getCachedOrFreshRtmUrl();
+  if (!wssUrl) {
+    // Graceful exit — typing is non-critical
+    process.exit(0);
+  }
+
+  await sendTypingIndicator(wssUrl, CHANNEL, DURATION_MS);
+  process.exit(0);
+}
+
+main().catch((err) => {
+  console.error(`[slack-typing] Unexpected error: ${err.message}`);
+  process.exit(0); // Non-critical — don't block message delivery
+});