@cohortapp/agent-sdk 2.3.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 the agent'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,232 @@
+#!/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
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+AGENT_REPO_DIR="${AGENT_DIR:-$(cd "$SCRIPT_DIR/.." && pwd)}"
+
+LOCK_BASE_DIR="$AGENT_REPO_DIR/state/locks/slack-response"
+LEGACY_DIR="$AGENT_REPO_DIR/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
+    ;;
+
+  release)
+    # release <channel_id> <message_ts> [session_id]
+    # Releases an unconfirmed lock so a legitimate retry isn't blocked by a
+    # 24h TTL. Called by slack-send.sh's exit trap when a send fails or the
+    # script crashes after acquiring the lock but before confirming the send.
+    #
+    # Safety:
+    #   - Refuse to release if the lock has been confirmed (real send happened)
+    #   - If session_id is provided, only release locks owned by that session
+    #     (prevents a buggy caller from blowing away a sibling's in-flight lock)
+    #
+    # Lock metadata is stored in `meta` (acquire/confirm both write to it)
+    # using the format produced by the acquire/confirm sections above:
+    #   session: "<id>"
+    #   status: acquired   (or confirmed)
+    CHANNEL="${2:?Channel ID required}"
+    MSG_TS="${3:?Message TS required}"
+    SESSION_ID="${4:-unknown}"
+
+    LOCK_DIR="$LOCK_BASE_DIR/${CHANNEL}-${MSG_TS}"
+    META="$LOCK_DIR/meta"
+
+    if [ ! -d "$LOCK_DIR" ]; then
+      echo "NOT_HELD"
+      exit 0
+    fi
+
+    if [ -f "$META" ] && grep -qE "^status:[[:space:]]*confirmed" "$META" 2>/dev/null; then
+      echo "ALREADY_CONFIRMED"
+      exit 0
+    fi
+
+    if [ -f "$META" ] && [ "$SESSION_ID" != "unknown" ]; then
+      if ! grep -qE "^session:[[:space:]]*\"?${SESSION_ID}\"?[[:space:]]*$" "$META" 2>/dev/null; then
+        echo "NOT_OWNED"
+        exit 0
+      fi
+    fi
+
+    rm -rf "$LOCK_DIR"
+    echo "RELEASED"
+    ;;
+
+  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|release|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 "  release <channel> <msg_ts> [session_id]  — Release unconfirmed lock (send failed)"
+    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,287 @@
+#!/bin/bash
+# slack-send.sh — Send Slack message as the running agent via User OAuth Token (xoxp-)
+# Messages appear as the agent's own Slack user, NOT the bot app.
+# Usage: ./scripts/slack-send.sh <channel_id> <message> [--thread_ts <ts>]
+set -e
+
+# Resolve the agent repo dir so we can source env files regardless of cwd.
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+AGENT_REPO_DIR="${AGENT_DIR:-$(cd "$SCRIPT_DIR/.." && pwd)}"
+
+# Load identity vars (AGENT_FIRST_NAME, AGENT_FULL_NAME, AGENT_EMAIL, …) so
+# nothing in this script needs to hardcode the agent's name or paths.
+if [ -f "$AGENT_REPO_DIR/config/agent.env" ]; then
+  # shellcheck disable=SC1091
+  source "$AGENT_REPO_DIR/config/agent.env"
+fi
+
+# Load secrets from the agent's .env (must live alongside agent.env).
+if [ -f "$AGENT_REPO_DIR/.env" ]; then
+  # shellcheck disable=SC1091
+  source "$AGENT_REPO_DIR/.env"
+fi
+
+# 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 the running agent, not a generic bot app.
+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
+
+# Auto-detect --responding_to from the inbox if the caller didn't pass it.
+# Protects against operator-vs-daemon duplicate replies: when a human-prompted
+# session replies via this script, it should claim the dedup lock so the
+# daemon's session (which always passes --responding_to) finds the lock
+# already taken and skips its own send. Without auto-detect, two reply
+# sources race and the user gets duplicate substantive responses (observed
+# on 2026-05-12 when operator + daemon both replied to a CEO DM 3 min apart).
+#
+# Strategy: scan state/inbox/slack/ for the most recent unprocessed YAML
+# whose body references this channel; extract its raw_ref ts as RESPONDING_TO.
+# Operator can override by passing --responding_to explicitly, or skip auto-
+# detect with --responding_to "" (proactive send not tied to an inbox item).
+if [ -z "$RESPONDING_TO" ] && [[ "$CHANNEL" =~ ^[CD][A-Z0-9]+$ ]]; then
+  INBOX_DIR="$AGENT_REPO_DIR/state/inbox/slack"
+  if [ -d "$INBOX_DIR" ]; then
+    LATEST_INBOX=$(
+      ls -t "$INBOX_DIR"/*.yaml 2>/dev/null |
+        xargs -I{} grep -l "channel_id: \"$CHANNEL\"" {} 2>/dev/null |
+        head -1
+    )
+    if [ -n "$LATEST_INBOX" ]; then
+      AUTO_TS=$(grep "^raw_ref:" "$LATEST_INBOX" 2>/dev/null | sed -E 's/.*:([0-9]+\.[0-9]+)".*/\1/')
+      if [ -n "$AUTO_TS" ]; then
+        RESPONDING_TO="$AUTO_TS"
+        echo "[slack-send] auto-detected --responding_to=$RESPONDING_TO from $(basename "$LATEST_INBOX")" >&2
+      fi
+    fi
+  fi
+fi
+
+# Dedup check: if --responding_to is set, use atomic locking to prevent concurrent sends
+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.
+  # AGENT_SESSION_ID is the per-agent session identifier (used to be SOPHIE_SESSION_ID,
+  # RAVI_SESSION_ID, etc.); $$ is the fallback when running outside a daemon-spawned shell.
+  SESSION_ID="${AGENT_SESSION_ID:-${SOPHIE_SESSION_ID:-${RAVI_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"
+
+  # Lock-release safety net. If this script exits BEFORE confirming the
+  # lock (e.g. validation failed, Slack API errored, python script crashed
+  # during message conversion, caller killed us), we must release the lock
+  # so the next legitimate retry isn't blocked for 24 hours. The trap is
+  # cleared after the post-send confirm; if the confirm runs, we leave
+  # the lock in place (it's now a real send marker, not a placeholder).
+  cleanup_unconfirmed_lock() {
+    local exit_code=$?
+    if [ -n "$DEDUP_ACQUIRED" ] && [ -z "$DEDUP_CONFIRMED" ]; then
+      "$SCRIPT_DIR/slack-responded.sh" release "$CHANNEL" "$RESPONDING_TO" "$SESSION_ID" 2>/dev/null || true
+    fi
+    return "$exit_code"
+  }
+  trap cleanup_unconfirmed_lock EXIT
+fi
+
+# Show typing indicator before sending (non-blocking, fire-and-forget)
+# This makes the agent's presence feel human — the "X 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
+  echo "BLOCKED: outbound validator (validate_outbound.py) missing — refusing Slack send (fail closed)." >&2
+  exit 1
+fi
+if true; 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
+
+# ── Pre-send policy gate (shared send-gate chokepoint) ──────────────
+# Unified policy layer ABOVE validate_outbound.py (Layer 0): banned phrases,
+# AI-disclosure, information barriers, and the recipient allowlist, all enforced
+# in lib/comms/send-gate.mjs so every send path screens identically. Slack
+# channel/DM ids are internal by construction, so an FS fault fails OPEN here;
+# external recipients fail CLOSED (see the module header).
+SEND_GATE="$AGENT_REPO_DIR/lib/comms/send-gate.mjs"
+if [ ! -f "$SEND_GATE" ]; then
+  # Try the maestro package location if running from a consuming agent repo.
+  SEND_GATE="$AGENT_REPO_DIR/node_modules/@cohortapp/agent-sdk/lib/comms/send-gate.mjs"
+fi
+if [ -f "$SEND_GATE" ]; then
+  NODE_BIN="${MAESTRO_NODE_BIN:-/opt/homebrew/bin/node}"
+  command -v "$NODE_BIN" >/dev/null 2>&1 || NODE_BIN="node"
+  # Operational sends are replies by default (no proactive-disclosure duty);
+  # set MAESTRO_SEND_FIRST_CONTACT=true for a genuine first-contact send. The
+  # truthfulness invariant (never deny being an AI) applies regardless.
+  GATE_REASON=$(printf '%s' "$MESSAGE" | AGENT_DIR="$AGENT_REPO_DIR" "$NODE_BIN" "$SEND_GATE" \
+    --channel slack --recipient "$CHANNEL" --agent-root "$AGENT_REPO_DIR" \
+    --first-contact "${MAESTRO_SEND_FIRST_CONTACT:-false}" 2>&1) || GATE_EXIT=$?
+  GATE_EXIT=${GATE_EXIT:-0}
+  if [ "$GATE_EXIT" != "0" ]; then
+    echo "SEND_GATE_BLOCK: Slack message to $CHANNEL blocked by policy gate" >&2
+    echo "$GATE_REASON" >&2
+    exit 1
+  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)
+# and mark the trap as fulfilled so the exit-handler does NOT release the
+# now-legitimate confirmation marker. Any non-OK status leaves DEDUP_CONFIRMED
+# unset, so the EXIT trap releases the lock for legitimate retry.
+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
+  DEDUP_CONFIRMED="1"
+fi