@cohortapp/agent-sdk 2.3.0

package/scripts/outbound-dedup.sh

@@ -0,0 +1,477 @@
+#!/bin/bash
+# outbound-dedup.sh — Generalized outbound message deduplication
+# Prevents duplicate sends across concurrent Claude Code sessions using atomic mkdir-based locking.
+#
+# Works for all outbound channels: slack, email, sms, whatsapp
+# Uses the same atomic mkdir pattern proven in slack-responded.sh
+#
+# Lock directory: state/locks/outbound/{channel}/{dedup-key}/
+#
+# Dedup key generation:
+#   email:    sha256(to + subject + first-100-chars-of-body)
+#   sms:      sha256(to + first-100-chars-of-body)
+#   whatsapp: sha256(to + first-100-chars-of-body)
+#   slack:    channel-ts (existing pattern, passthrough)
+#
+# Commands:
+#   acquire <channel> <dedup-key> [session_id]
+#     → stdout: CLAIMED (lock acquired, caller should send)
+#     → stdout: DEDUP_SKIP (another session claimed it, caller should skip)
+#     → stdout: ERROR (lock system failure — caller should send anyway, fail-open)
+#     → exit 0 always (fail-open: never block a send on lock errors)
+#
+#   confirm <channel> <dedup-key> [preview]
+#     → Records successful send in lock metadata
+#
+#   check <channel> <dedup-key>
+#     → stdout: CLAIMED (lock exists and is valid)
+#     → stdout: AVAILABLE (no valid lock)
+#     → exit 0 always
+#
+#   cleanup [max_age_minutes]
+#     → Removes locks older than max_age_minutes (default: 5)
+#
+#   generate-key <channel> <to> <subject> <body>
+#     → Generates and prints the dedup key for the given parameters
+#     → For email: sha256(to + subject + first-100-chars-of-body)
+#     → For sms/whatsapp: sha256(to + first-100-chars-of-body)
+#     → For slack: prints the subject parameter as-is (channel-ts passthrough)
+#
+# Design principles:
+#   - POSIX sh compatible (bash extensions avoided where possible)
+#   - Atomic operations (mkdir is atomic on all filesystems)
+#   - Fail-open on lock errors (better to send a duplicate than drop a message)
+#   - Full audit trail to logs/audit/
+set -e
+
+SCRIPT_DIR_INIT="$(cd "$(dirname "$0")" && pwd)"
+AGENT_REPO_DIR="${AGENT_DIR:-$(cd "$SCRIPT_DIR_INIT/.." && pwd)}"
+LOCK_BASE_DIR="$AGENT_REPO_DIR/state/locks/outbound"
+LOCK_TTL_MINUTES=720  # 12 hours — email dedup needs long TTL to prevent cross-session duplicates
+AUDIT_DIR="$AGENT_REPO_DIR/logs/audit"
+TIMESTAMP=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+
+# Ensure base directories exist
+mkdir -p "$LOCK_BASE_DIR"
+mkdir -p "$AUDIT_DIR"
+
+# --- Helper functions ---
+
+log_audit() {
+  local action="$1"
+  local channel="$2"
+  local dedup_key="$3"
+  local detail="$4"
+  local audit_file="$AUDIT_DIR/$(date +%Y-%m-%d)-actions.jsonl"
+  local safe_detail
+  safe_detail=$(printf '%s' "$detail" | head -c 200 | tr '"' "'" | tr '\n' ' ')
+  printf '{"timestamp":"%s","agent":"outbound-dedup","action":"%s","channel":"%s","dedup_key":"%s","detail":"%s","session":"%s"}\n' \
+    "$TIMESTAMP" "$action" "$channel" "$dedup_key" "$safe_detail" "${SOPHIE_SESSION_ID:-$$}" \
+    >> "$audit_file" 2>/dev/null || true
+}
+
+# Check if a lock directory is still valid (younger than TTL)
+lock_is_valid() {
+  local lock_path="$1"
+  if [ ! -d "$lock_path" ]; then
+    return 1
+  fi
+  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" ]
+}
+
+# Normalize an email subject for subject-level dedup.
+# Strips Re:/Fwd: prefixes, date/time components, leading/trailing whitespace, lowercases.
+# This ensures "Brief — Tue 7 April 2026, 14:00 GST" and "Brief — 7 April 2026" hash identically.
+normalize_subject() {
+  printf '%s' "$1" | \
+    sed -E 's/^(Re|Fwd|FW|RE|Fw): *//gi' | \
+    sed -E 's/^(Re|Fwd|FW|RE|Fw): *//gi' | \
+    tr '[:upper:]' '[:lower:]' | \
+    sed -E 's/(mon|tue|wed|thu|fri|sat|sun)(day|nesday|rsday|urday)?//gi' | \
+    sed -E 's/[0-9]{1,2}:[0-9]{2}(:[0-9]{2})?//g' | \
+    sed -E 's/ ?(gst|utc|est|pst|cst|mst|gmt|bst|cet|aest|aedt|ast|ict|jst|ist) ?//gi' | \
+    sed -E 's/,? *[0-9]{1,2} +(january|february|march|april|may|june|july|august|september|october|november|december) +[0-9]{4}//' | \
+    sed -E 's/,? *[0-9]{1,2} +(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec) +[0-9]{4}//' | \
+    sed -E 's/[0-9]{4}-[0-9]{2}-[0-9]{2}//g' | \
+    sed -E 's/,[ ,]*/ /g' | \
+    sed -E 's/ *— *— */— /g' | \
+    sed -E 's/— *$/—/' | \
+    sed -E 's/  +/ /g' | \
+    sed 's/^[[:space:]]*//' | \
+    sed 's/[[:space:]]*$//'
+}
+
+# Generate a SUBJECT+RECIPIENT dedup key (body-independent).
+# This catches semantically identical emails sent in different formats
+# (e.g., HTML vs PDF attachment vs Gmail draft).
+generate_subject_key() {
+  local to="$1"
+  local subject="$2"
+  local norm_to norm_subj
+  norm_to=$(printf '%s' "$to" | tr '[:upper:]' '[:lower:]' | sed 's/[[:space:]]//g')
+  norm_subj=$(normalize_subject "$subject")
+  printf 'subj|%s|%s' "$norm_to" "$norm_subj" | shasum -a 256 | cut -d' ' -f1
+}
+
+# Generate a dedup key from message parameters
+# Email: sha256(to + subject + first-100-chars-of-body)
+# SMS/WhatsApp: sha256(to + first-100-chars-of-body)
+# Slack: passthrough (use subject as the key directly — it's channel-ts)
+generate_dedup_key() {
+  local channel="$1"
+  local to="$2"
+  local subject="$3"
+  local body="$4"
+  local body_prefix
+  body_prefix=$(printf '%s' "$body" | head -c 100)
+
+  case "$channel" in
+    email)
+      printf '%s|%s|%s' "$to" "$subject" "$body_prefix" | shasum -a 256 | cut -d' ' -f1
+      ;;
+    sms|whatsapp)
+      printf '%s|%s' "$to" "$body_prefix" | shasum -a 256 | cut -d' ' -f1
+      ;;
+    slack)
+      # Slack uses channel-ts as key directly (passthrough)
+      printf '%s' "$subject"
+      ;;
+    *)
+      # Unknown channel: hash everything available
+      printf '%s|%s|%s|%s' "$channel" "$to" "$subject" "$body_prefix" | shasum -a 256 | cut -d' ' -f1
+      ;;
+  esac
+}
+
+# --- Main command dispatch ---
+
+ACTION="${1:-}"
+
+case "$ACTION" in
+  acquire)
+    # acquire <channel> <dedup-key> [session_id]
+    # Attempts to atomically acquire a send lock.
+    # Always exits 0 (fail-open). Outputs CLAIMED, DEDUP_SKIP, or ERROR.
+    CHANNEL="${2:-}"
+    DEDUP_KEY="${3:-}"
+    SESSION_ID="${4:-${SOPHIE_SESSION_ID:-$$}}"
+
+    if [ -z "$CHANNEL" ] || [ -z "$DEDUP_KEY" ]; then
+      echo "ERROR"
+      log_audit "acquire_error" "${CHANNEL:-unknown}" "${DEDUP_KEY:-unknown}" "Missing channel or dedup-key"
+      exit 0
+    fi
+
+    LOCK_DIR="$LOCK_BASE_DIR/$CHANNEL/$DEDUP_KEY"
+    CHANNEL_DIR="$LOCK_BASE_DIR/$CHANNEL"
+    mkdir -p "$CHANNEL_DIR"
+
+    # Check for existing valid lock
+    if lock_is_valid "$LOCK_DIR"; then
+      echo "DEDUP_SKIP"
+      log_audit "acquire_dedup_skip" "$CHANNEL" "$DEDUP_KEY" "Lock already held"
+      exit 0
+    fi
+
+    # If stale lock exists, remove it
+    if [ -d "$LOCK_DIR" ]; then
+      rm -rf "$LOCK_DIR" 2>/dev/null || true
+    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"
+dedup_key: "$DEDUP_KEY"
+status: acquired
+EOF
+      echo "CLAIMED"
+      log_audit "acquire_claimed" "$CHANNEL" "$DEDUP_KEY" "Lock acquired by session $SESSION_ID"
+      exit 0
+    else
+      # Another process beat us to it
+      echo "DEDUP_SKIP"
+      log_audit "acquire_dedup_skip" "$CHANNEL" "$DEDUP_KEY" "Race lost to another session"
+      exit 0
+    fi
+    ;;
+
+  acquire-email)
+    # acquire-email <to> <subject> <body> [session_id]
+    # TWO-LAYER dedup for email: subject+recipient THEN content-hash.
+    # This is the preferred entry point for all email sends.
+    # Returns: CLAIMED (send OK), DEDUP_SKIP (duplicate), ERROR (fail-open: send anyway)
+    TO="${2:-}"
+    SUBJECT="${3:-}"
+    BODY="${4:-}"
+    SESSION_ID="${5:-${SOPHIE_SESSION_ID:-$$}}"
+
+    if [ -z "$TO" ] || [ -z "$SUBJECT" ]; then
+      echo "ERROR"
+      log_audit "acquire_email_error" "email" "-" "Missing to or subject"
+      exit 0
+    fi
+
+    # --- Layer 1: Subject+recipient dedup (body-independent) ---
+    SUBJ_KEY=$(generate_subject_key "$TO" "$SUBJECT")
+    SUBJ_LOCK_DIR="$LOCK_BASE_DIR/email-subject/$SUBJ_KEY"
+    mkdir -p "$LOCK_BASE_DIR/email-subject"
+
+    if lock_is_valid "$SUBJ_LOCK_DIR"; then
+      echo "DEDUP_SKIP"
+      log_audit "acquire_email_subject_skip" "email-subject" "$SUBJ_KEY" "Subject+recipient duplicate: To:$TO Subj:$SUBJECT"
+      exit 0
+    fi
+
+    # Remove stale subject lock if exists
+    if [ -d "$SUBJ_LOCK_DIR" ]; then
+      rm -rf "$SUBJ_LOCK_DIR" 2>/dev/null || true
+    fi
+
+    # --- Layer 2: Content-hash dedup (existing behaviour) ---
+    CONTENT_KEY=$(generate_dedup_key "email" "$TO" "$SUBJECT" "$BODY")
+    CONTENT_LOCK_DIR="$LOCK_BASE_DIR/email/$CONTENT_KEY"
+    mkdir -p "$LOCK_BASE_DIR/email"
+
+    if lock_is_valid "$CONTENT_LOCK_DIR"; then
+      echo "DEDUP_SKIP"
+      log_audit "acquire_email_content_skip" "email" "$CONTENT_KEY" "Content-hash duplicate: To:$TO Subj:$SUBJECT"
+      exit 0
+    fi
+
+    # Remove stale content lock if exists
+    if [ -d "$CONTENT_LOCK_DIR" ]; then
+      rm -rf "$CONTENT_LOCK_DIR" 2>/dev/null || true
+    fi
+
+    # --- Acquire both locks atomically ---
+    SUBJ_ACQUIRED=""
+    CONTENT_ACQUIRED=""
+
+    if mkdir "$SUBJ_LOCK_DIR" 2>/dev/null; then
+      cat > "$SUBJ_LOCK_DIR/meta" << EOF
+acquired: "$TIMESTAMP"
+session: "$SESSION_ID"
+to: "$TO"
+subject: "$SUBJECT"
+type: subject-recipient
+status: acquired
+EOF
+      SUBJ_ACQUIRED="1"
+    else
+      # Another session claimed subject lock between check and mkdir
+      echo "DEDUP_SKIP"
+      log_audit "acquire_email_subject_race" "email-subject" "$SUBJ_KEY" "Race lost on subject lock: To:$TO Subj:$SUBJECT"
+      exit 0
+    fi
+
+    if mkdir "$CONTENT_LOCK_DIR" 2>/dev/null; then
+      cat > "$CONTENT_LOCK_DIR/meta" << EOF
+acquired: "$TIMESTAMP"
+session: "$SESSION_ID"
+to: "$TO"
+subject: "$SUBJECT"
+type: content-hash
+subject_key: "$SUBJ_KEY"
+status: acquired
+EOF
+      CONTENT_ACQUIRED="1"
+    fi
+    # Content lock failure is not fatal — subject lock is the primary guard
+
+    # Output both keys for confirm step (pipe-separated)
+    echo "CLAIMED"
+    log_audit "acquire_email_claimed" "email" "$CONTENT_KEY" "Both locks acquired. Subject key: $SUBJ_KEY. To:$TO Subj:$SUBJECT"
+    # Write combined key info for callers that need it
+    printf '%s|%s' "$SUBJ_KEY" "$CONTENT_KEY" > "$SUBJ_LOCK_DIR/content_key" 2>/dev/null || true
+    exit 0
+    ;;
+
+  confirm-email)
+    # confirm-email <to> <subject> [preview]
+    # Confirms both subject and content locks after a successful email send.
+    TO="${2:-}"
+    SUBJECT="${3:-}"
+    PREVIEW="${4:-}"
+
+    if [ -z "$TO" ] || [ -z "$SUBJECT" ]; then
+      exit 0
+    fi
+
+    SUBJ_KEY=$(generate_subject_key "$TO" "$SUBJECT")
+    SUBJ_LOCK_DIR="$LOCK_BASE_DIR/email-subject/$SUBJ_KEY"
+    SAFE_PREVIEW=$(printf '%s' "$PREVIEW" | head -c 200 | tr '"' "'")
+
+    if [ -d "$SUBJ_LOCK_DIR" ]; then
+      ORIG_ACQUIRED=$(grep 'acquired:' "$SUBJ_LOCK_DIR/meta" 2>/dev/null | head -1 | sed 's/^acquired: *//' | tr -d '"' || echo "$TIMESTAMP")
+      if [ -z "$ORIG_ACQUIRED" ]; then ORIG_ACQUIRED="$TIMESTAMP"; fi
+      cat > "$SUBJ_LOCK_DIR/meta" << EOF
+acquired: "$ORIG_ACQUIRED"
+confirmed: "$TIMESTAMP"
+to: "$TO"
+subject: "$SUBJECT"
+type: subject-recipient
+status: confirmed
+preview: "$SAFE_PREVIEW"
+EOF
+      log_audit "confirm_email_subject" "email-subject" "$SUBJ_KEY" "Subject lock confirmed: To:$TO Subj:$SUBJECT"
+    fi
+
+    # Also confirm content lock if it exists
+    CONTENT_KEY_FILE="$SUBJ_LOCK_DIR/content_key"
+    if [ -f "$CONTENT_KEY_FILE" ]; then
+      CONTENT_KEY=$(cut -d'|' -f2 "$CONTENT_KEY_FILE" 2>/dev/null || true)
+      if [ -n "$CONTENT_KEY" ]; then
+        CONTENT_LOCK_DIR="$LOCK_BASE_DIR/email/$CONTENT_KEY"
+        if [ -d "$CONTENT_LOCK_DIR" ]; then
+          ORIG_C=$(grep 'acquired:' "$CONTENT_LOCK_DIR/meta" 2>/dev/null | head -1 | sed 's/^acquired: *//' | tr -d '"' || echo "$TIMESTAMP")
+          if [ -z "$ORIG_C" ]; then ORIG_C="$TIMESTAMP"; fi
+          cat > "$CONTENT_LOCK_DIR/meta" << EOF
+acquired: "$ORIG_C"
+confirmed: "$TIMESTAMP"
+channel: "email"
+dedup_key: "$CONTENT_KEY"
+status: confirmed
+preview: "$SAFE_PREVIEW"
+EOF
+        fi
+      fi
+    fi
+
+    echo "CONFIRMED"
+    ;;
+
+  confirm)
+    # confirm <channel> <dedup-key> [preview]
+    # Called after a successful send to record what was sent.
+    CHANNEL="${2:-}"
+    DEDUP_KEY="${3:-}"
+    PREVIEW="${4:-}"
+
+    if [ -z "$CHANNEL" ] || [ -z "$DEDUP_KEY" ]; then
+      exit 0
+    fi
+
+    LOCK_DIR="$LOCK_BASE_DIR/$CHANNEL/$DEDUP_KEY"
+
+    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=$(printf '%s' "$PREVIEW" | head -c 200 | tr '"' "'")
+      cat > "$LOCK_DIR/meta" << EOF
+acquired: "$ORIG_ACQUIRED"
+confirmed: "$TIMESTAMP"
+channel: "$CHANNEL"
+dedup_key: "$DEDUP_KEY"
+status: confirmed
+preview: "$SAFE_PREVIEW"
+EOF
+      log_audit "confirm" "$CHANNEL" "$DEDUP_KEY" "Send confirmed: $SAFE_PREVIEW"
+    fi
+    echo "CONFIRMED"
+    ;;
+
+  check)
+    # check <channel> <dedup-key>
+    # Returns CLAIMED if a valid lock exists, AVAILABLE otherwise.
+    CHANNEL="${2:-}"
+    DEDUP_KEY="${3:-}"
+
+    if [ -z "$CHANNEL" ] || [ -z "$DEDUP_KEY" ]; then
+      echo "AVAILABLE"
+      exit 0
+    fi
+
+    LOCK_DIR="$LOCK_BASE_DIR/$CHANNEL/$DEDUP_KEY"
+
+    if lock_is_valid "$LOCK_DIR"; then
+      echo "CLAIMED"
+    else
+      echo "AVAILABLE"
+    fi
+    exit 0
+    ;;
+
+  cleanup)
+    # cleanup [max_age_minutes]
+    # Removes lock directories older than max_age_minutes (default: 5)
+    MAX_AGE="${2:-$LOCK_TTL_MINUTES}"
+    CLEANED=0
+
+    for channel_dir in "$LOCK_BASE_DIR"/*/; do
+      [ -d "$channel_dir" ] || continue
+      for lock_dir in "$channel_dir"*/; do
+        [ -d "$lock_dir" ] || continue
+        # Skip if it's just the channel directory itself
+        [ "$lock_dir" = "$channel_dir" ] && continue
+        # Check age
+        local_age=0
+        if [ "$(uname)" = "Darwin" ]; then
+          local_age=$(( ( $(date +%s) - $(stat -f %m "$lock_dir") ) / 60 ))
+        else
+          local_age=$(( ( $(date +%s) - $(stat -c %Y "$lock_dir") ) / 60 ))
+        fi
+        if [ "$local_age" -ge "$MAX_AGE" ]; then
+          rm -rf "$lock_dir" 2>/dev/null || true
+          CLEANED=$((CLEANED + 1))
+        fi
+      done
+    done
+    log_audit "cleanup" "all" "-" "Removed $CLEANED locks older than ${MAX_AGE}m"
+    echo "CLEANED: $CLEANED locks removed (older than ${MAX_AGE} minutes)"
+    ;;
+
+  generate-key)
+    # generate-key <channel> <to> <subject> <body>
+    # Outputs the dedup key for the given parameters
+    CHANNEL="${2:-}"
+    TO="${3:-}"
+    SUBJECT="${4:-}"
+    BODY="${5:-}"
+
+    if [ -z "$CHANNEL" ]; then
+      echo "ERROR: channel required" >&2
+      exit 1
+    fi
+
+    generate_dedup_key "$CHANNEL" "$TO" "$SUBJECT" "$BODY"
+    ;;
+
+  *)
+    echo "outbound-dedup.sh — Generalized outbound message deduplication"
+    echo ""
+    echo "Usage: outbound-dedup.sh <command> [args...]"
+    echo ""
+    echo "Commands:"
+    echo "  acquire <channel> <dedup-key> [session_id]"
+    echo "    Atomically claim a send lock. Outputs: CLAIMED | DEDUP_SKIP | ERROR"
+    echo "    Always exits 0 (fail-open)."
+    echo ""
+    echo "  confirm <channel> <dedup-key> [preview]"
+    echo "    Record that a send succeeded."
+    echo ""
+    echo "  check <channel> <dedup-key>"
+    echo "    Check if a lock is active. Outputs: CLAIMED | AVAILABLE"
+    echo ""
+    echo "  cleanup [max_age_minutes]"
+    echo "    Remove locks older than max_age_minutes (default: 5)."
+    echo ""
+    echo "  generate-key <channel> <to> <subject> <body>"
+    echo "    Generate a dedup key for the given message parameters."
+    echo ""
+    echo "Channels: slack, email, sms, whatsapp"
+    echo "Lock dir: state/locks/outbound/{channel}/{dedup-key}/"
+    exit 2
+    ;;
+esac

package/scripts/outbound_dedup.py

@@ -0,0 +1,115 @@
+"""Outbound dedup helper for Python email/SMS send scripts.
+
+Calls outbound-dedup.sh to acquire/confirm locks before/after sending.
+Fail-open: if the dedup script is missing or errors, returns CLAIMED so the send proceeds.
+
+Usage:
+    from outbound_dedup import acquire_email_lock, confirm_email_lock
+
+    key, result = acquire_email_lock(to, subject, body)
+    if result == "DEDUP_SKIP":
+        print("DEDUP_SKIP")
+        sys.exit(0)
+
+    # ... send the email ...
+
+    confirm_email_lock(key, f"To:{to} Subj:{subject}")
+"""
+import os
+import subprocess
+
+SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
+DEDUP_SCRIPT = os.path.join(SCRIPT_DIR, "outbound-dedup.sh")
+
+
+def _run_dedup(*args):
+    """Run outbound-dedup.sh with the given arguments. Returns stdout string.
+
+    Fail-open: returns empty string on any error.
+    """
+    if not os.path.isfile(DEDUP_SCRIPT) or not os.access(DEDUP_SCRIPT, os.X_OK):
+        return ""
+    try:
+        result = subprocess.run(
+            [DEDUP_SCRIPT] + list(args),
+            capture_output=True, text=True, timeout=5,
+            env={**os.environ, "SOPHIE_SESSION_ID": os.environ.get("SOPHIE_SESSION_ID", str(os.getpid()))}
+        )
+        return result.stdout.strip()
+    except Exception:
+        return ""
+
+
+def generate_key(channel, to, subject="", body=""):
+    """Generate a dedup key for the given channel and message parameters."""
+    return _run_dedup("generate-key", channel, to, subject, body)
+
+
+def acquire_lock(channel, to, subject="", body=""):
+    """Acquire a dedup lock. Returns (dedup_key, result).
+
+    result is one of: "CLAIMED", "DEDUP_SKIP", "ERROR", ""
+    If DEDUP_SKIP, the caller should skip sending.
+    All other values mean the caller should proceed (fail-open).
+    """
+    key = generate_key(channel, to, subject, body)
+    if not key:
+        return ("", "CLAIMED")  # fail-open
+
+    session_id = os.environ.get("SOPHIE_SESSION_ID", str(os.getpid()))
+    result = _run_dedup("acquire", channel, key, session_id)
+
+    if result == "DEDUP_SKIP":
+        return (key, "DEDUP_SKIP")
+    elif result == "CLAIMED":
+        return (key, "CLAIMED")
+    else:
+        # ERROR or empty — fail-open
+        return (key, "CLAIMED")
+
+
+def confirm_lock(channel, dedup_key, preview=""):
+    """Confirm a successful send. Called after the message is sent."""
+    if not dedup_key:
+        return
+    _run_dedup("confirm", channel, dedup_key, preview)
+
+
+# Content-hash only email dedup
+# Subject+recipient layer removed per CEO directive ib-20260406-001.
+# LLM-based dedup is now handled in llm_email_dedup.py.
+def acquire_email_lock(to, subject, body):
+    """Acquire email dedup lock using content-hash only.
+
+    Returns (key, result) where key is the content-hash dedup key.
+    """
+    key = generate_key("email", to, subject, body)
+    if not key:
+        return ("", "CLAIMED")  # fail-open
+
+    session_id = os.environ.get("SOPHIE_SESSION_ID", str(os.getpid()))
+    result = _run_dedup("acquire", "email", key, session_id)
+
+    if result == "DEDUP_SKIP":
+        return (key, "DEDUP_SKIP")
+    elif result == "CLAIMED":
+        return (key, "CLAIMED")
+    else:
+        return (key, "CLAIMED")  # fail-open
+
+
+def confirm_email_lock(dedup_key_or_subject, preview="", to="", subject=""):
+    """Confirm email send. Uses content-hash lock confirm."""
+    if dedup_key_or_subject:
+        confirm_lock("email", dedup_key_or_subject, preview)
+
+
+# Convenience wrappers for SMS
+def acquire_sms_lock(to, body):
+    """Acquire SMS dedup lock. Returns (key, result)."""
+    return acquire_lock("sms", to, "", body)
+
+
+def confirm_sms_lock(dedup_key, preview=""):
+    """Confirm SMS send."""
+    confirm_lock("sms", dedup_key, preview)