npm - @adaptic/maestro - Versions diffs - 1.0.0 - Mend

@adaptic/maestro 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (854) hide show

package/scripts/outbound-dedup.sh ADDED Viewed

@@ -0,0 +1,476 @@
+#!/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
+SOPHIE_AI="/Users/sophie/sophie-ai"
+LOCK_BASE_DIR="$SOPHIE_AI/state/locks/outbound"
+LOCK_TTL_MINUTES=720  # 12 hours — email dedup needs long TTL to prevent cross-session duplicates
+AUDIT_DIR="$SOPHIE_AI/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 ADDED Viewed

@@ -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)