@cohortapp/agent-sdk 2.3.0

package/scripts/sync-protocol.mjs

@@ -0,0 +1,217 @@
+#!/usr/bin/env node
+/**
+ * sync-protocol.mjs — THE way to evolve the shared Cohort wire contract.
+ *
+ * `lib/org/protocol.mjs` is the single CANONICAL source of the org-protocol wire
+ * contract (method names, scopes, mutating-method set, event families, board
+ * status vocabulary, error codes, and the `computeRowHash` hash-chain function).
+ * maestro (ESM .mjs / Node) and Cohort (TS / Next) must agree on it
+ * BYTE-FOR-BYTE. The cross-repo parity guard (`lib/org/protocol.checksum.test.mjs`
+ * here, plus the mirror test in Cohort) fails the moment the two drift.
+ *
+ * Workflow to change the protocol:
+ *   1. Edit `lib/org/protocol.mjs` (maestro — the canonical copy).
+ *   2. Run `node scripts/sync-protocol.mjs` (this script):
+ *        - recomputes the sha256 of `protocol.mjs`;
+ *        - copies it to `<cohort>/packages/protocol/index.mjs` (re-vendor);
+ *        - writes the new checksum to `<cohort>/packages/protocol/protocol.checksum`
+ *          AND to the maestro checksum reference (`lib/org/protocol.checksum`).
+ *        - prints the new checksum and the exact files to commit.
+ *   3. Commit BOTH repos.
+ *
+ * No checksum literal lives in any test file. Both parity guards READ the
+ * `protocol.checksum` reference at run time:
+ *   - maestro `lib/org/protocol.checksum.test.mjs` reads `lib/org/protocol.checksum`;
+ *   - Cohort `packages/protocol/protocol.test.ts` reads `packages/protocol/protocol.checksum`.
+ * That is the whole point — there is no frozen `EXPECTED`/`CANONICAL_CHECKSUM`
+ * constant for a re-vendor to leave stale; this script only has to keep the two
+ * `protocol.checksum` files (and the vendored `index.mjs`) in lock-step with
+ * `protocol.mjs`.
+ *
+ * Idempotent: re-running with an unchanged protocol re-writes the same bytes and
+ * the same checksum (no spurious diffs). Fail-soft on a missing Cohort checkout:
+ * it still updates + prints the maestro-side checksum so the local guard is never
+ * left stale, and it tells you which Cohort files to sync once the repo is present.
+ *
+ * Usage (the Cohort checkout path is REQUIRED — arg or COHORT_REPO env; there
+ * is deliberately no default: a silently-wrong hardcoded path is worse than a
+ * hard stop):
+ *   node scripts/sync-protocol.mjs <cohort-path>  # explicit checkout path
+ *   COHORT_REPO=/path/to/hq node scripts/sync-protocol.mjs
+ *   node scripts/sync-protocol.mjs <cohort-path> --dry-run  # compute + print only
+ *   node scripts/sync-protocol.mjs <cohort-path> --check    # exit non-zero on drift
+ *
+ * Node builtins only (maestro is "type":"module", near-zero-dep by design).
+ *
+ * @module scripts/sync-protocol
+ */
+"use strict";
+
+import { createHash } from "node:crypto";
+import {
+  readFileSync,
+  writeFileSync,
+  mkdirSync,
+  existsSync,
+} from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { applyBrandEnvCompat } from "../lib/env-compat.mjs";
+
+// Fleet back-compat FIRST: bridge NEOLITH_* ⇄ COHORT_* env names so a host
+// still exporting NEOLITH_REPO resolves the COHORT_REPO checkout path below.
+applyBrandEnvCompat();
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = resolve(HERE, "..");
+
+const PROTOCOL_PATH = join(REPO_ROOT, "lib", "org", "protocol.mjs");
+const MAESTRO_CHECKSUM_PATH = join(REPO_ROOT, "lib", "org", "protocol.checksum");
+
+/** sha256 over a file's exact bytes (byte-for-byte — no normalization). */
+function sha256File(path) {
+  return createHash("sha256").update(readFileSync(path)).digest("hex");
+}
+
+/** Parse argv: first non-flag positional is the Cohort path; collect flags. */
+function parseArgs(argv) {
+  const flags = new Set();
+  let cohortArg = null;
+  for (const a of argv) {
+    if (a.startsWith("--")) flags.add(a);
+    else if (cohortArg === null) cohortArg = a;
+  }
+  return { cohortArg, flags };
+}
+
+/**
+ * Resolve the Cohort checkout root from arg > env. Returns `{ root, source }`
+ * (source describes where the path came from for logging), or null when
+ * NEITHER is provided — the caller hard-stops rather than writing into a
+ * guessed path.
+ */
+function resolveCohortRoot(cohortArg) {
+  if (cohortArg) return { root: resolve(cohortArg), source: "arg" };
+  if (process.env.COHORT_REPO)
+    return { root: resolve(process.env.COHORT_REPO), source: "env COHORT_REPO" };
+  return null;
+}
+
+function main() {
+  const { cohortArg, flags } = parseArgs(process.argv.slice(2));
+  const dryRun = flags.has("--dry-run") || flags.has("--dry");
+  const checkOnly = flags.has("--check");
+
+  if (!existsSync(PROTOCOL_PATH)) {
+    console.error(`sync-protocol: canonical protocol missing at ${PROTOCOL_PATH}`);
+    process.exit(2);
+  }
+
+  if (!resolveCohortRoot(cohortArg)) {
+    console.error(
+      "sync-protocol: no Cohort checkout named — pass the path as the first argument " +
+        "(node scripts/sync-protocol.mjs /path/to/hq) or set COHORT_REPO. " +
+        "There is deliberately no default: a silently-wrong path would sync the protocol nowhere.",
+    );
+    process.exit(2);
+  }
+
+  const digest = sha256File(PROTOCOL_PATH);
+  console.log(`sync-protocol: canonical lib/org/protocol.mjs`);
+  console.log(`sync-protocol: sha256 = ${digest}`);
+  if (dryRun) console.log("sync-protocol: --dry-run — no files will be written.");
+  if (checkOnly) console.log("sync-protocol: --check — verifying sync, no files will be written.");
+
+  const committed = new Set();
+  let drift = false;
+
+  // ---- maestro side: checksum reference + frozen test constant ----
+  const curChecksum = existsSync(MAESTRO_CHECKSUM_PATH)
+    ? readFileSync(MAESTRO_CHECKSUM_PATH, "utf8").trim()
+    : null;
+  if (curChecksum !== digest) {
+    drift = true;
+    if (!dryRun && !checkOnly) {
+      writeFileSync(MAESTRO_CHECKSUM_PATH, digest + "\n");
+      console.log(`sync-protocol: wrote ${MAESTRO_CHECKSUM_PATH}`);
+    } else {
+      console.log(
+        `sync-protocol: OUT OF SYNC ${MAESTRO_CHECKSUM_PATH} (${curChecksum ?? "missing"} != ${digest})`,
+      );
+    }
+  } else {
+    console.log(`sync-protocol: up-to-date ${MAESTRO_CHECKSUM_PATH}`);
+  }
+  committed.add(MAESTRO_CHECKSUM_PATH);
+
+  // The maestro + Cohort parity guards READ their `protocol.checksum` at run
+  // time, so there is no frozen test constant to rewrite here — keeping the two
+  // checksum files in sync (below) is sufficient.
+
+  // ---- Cohort side: re-vendor @cohort/protocol + write its checksum ----
+  const { root: cohortRoot, source } = resolveCohortRoot(cohortArg);
+  const pkgDir = join(cohortRoot, "packages", "protocol");
+  const vendoredIndex = join(pkgDir, "index.mjs");
+  const cohortChecksum = join(pkgDir, "protocol.checksum");
+
+  if (!existsSync(cohortRoot)) {
+    console.warn(
+      `sync-protocol: WARNING — Cohort checkout not found at ${cohortRoot} (${source}).`,
+    );
+    console.warn(
+      "sync-protocol: skipped re-vendoring @cohort/protocol. Once the repo is present, re-run to sync:",
+    );
+    console.warn(`sync-protocol:   ${vendoredIndex}`);
+    console.warn(`sync-protocol:   ${cohortChecksum}`);
+  } else {
+    const protocolBytes = readFileSync(PROTOCOL_PATH);
+    const curVendored =
+      existsSync(vendoredIndex) ? readFileSync(vendoredIndex) : null;
+    const curCohortChecksum =
+      existsSync(cohortChecksum)
+        ? readFileSync(cohortChecksum, "utf8").trim()
+        : null;
+    const vendoredInSync =
+      curVendored !== null && Buffer.compare(curVendored, protocolBytes) === 0;
+    const cohortChecksumInSync = curCohortChecksum === digest;
+
+    if (!vendoredInSync || !cohortChecksumInSync) {
+      drift = true;
+      if (!dryRun && !checkOnly) {
+        mkdirSync(pkgDir, { recursive: true });
+        writeFileSync(vendoredIndex, protocolBytes);
+        writeFileSync(cohortChecksum, digest + "\n");
+        console.log(`sync-protocol: re-vendored ${vendoredIndex}`);
+        console.log(`sync-protocol: wrote ${cohortChecksum}`);
+      } else {
+        console.log(`sync-protocol: OUT OF SYNC ${vendoredIndex}`);
+        console.log(
+          `sync-protocol: OUT OF SYNC ${cohortChecksum} (${curCohortChecksum ?? "missing"} != ${digest})`,
+        );
+      }
+    } else {
+      console.log(`sync-protocol: up-to-date ${vendoredIndex}`);
+      console.log(`sync-protocol: up-to-date ${cohortChecksum}`);
+    }
+    committed.add(vendoredIndex);
+    committed.add(cohortChecksum);
+  }
+
+  // ---- summary ----
+  console.log("");
+  console.log(`sync-protocol: checksum = ${digest}`);
+  console.log("sync-protocol: files to commit (both repos):");
+  for (const f of committed) console.log(`  - ${f}`);
+
+  if (checkOnly) {
+    if (drift) {
+      console.error("sync-protocol: --check FAILED — protocol artifacts are out of sync. Run `node scripts/sync-protocol.mjs`.");
+      process.exit(1);
+    }
+    console.log("sync-protocol: --check OK — everything is in sync.");
+  }
+
+  process.exit(0);
+}
+
+main();

package/scripts/system-verify.sh

@@ -0,0 +1,184 @@
+#!/bin/bash
+# Agent System Verification — checks all components are operational
+# Usage: ./scripts/system-verify.sh
+#
+# Run this anytime to verify the full system is working.
+
+set -e
+AGENT_REPO_DIR="${AGENT_DIR:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}"
+cd "$AGENT_REPO_DIR"
+
+# Load identity (AGENT_LAUNCHD_PREFIX in particular) — the verification
+# checks read launchd labels with the agent-specific prefix.
+if [ -f "$AGENT_REPO_DIR/config/agent.env" ]; then
+  # shellcheck disable=SC1091
+  source "$AGENT_REPO_DIR/config/agent.env"
+fi
+LAUNCHD_PREFIX="${AGENT_LAUNCHD_PREFIX:-ai.maestro.agent}"
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m'
+
+pass=0
+warn=0
+fail=0
+
+check() {
+    if eval "$2" > /dev/null 2>&1; then
+        echo -e "  ${GREEN}✓${NC} $1"
+        ((pass++))
+    else
+        echo -e "  ${RED}✗${NC} $1"
+        ((fail++))
+    fi
+}
+
+warn_check() {
+    if eval "$2" > /dev/null 2>&1; then
+        echo -e "  ${GREEN}✓${NC} $1"
+        ((pass++))
+    else
+        echo -e "  ${YELLOW}⚠${NC} $1"
+        ((warn++))
+    fi
+}
+
+echo "╔══════════════════════════════════════════════╗"
+printf "║  %-44s║\n" "$(echo "${AGENT_FULL_NAME:-AGENT}" | tr '[:lower:]' '[:upper:]') SYSTEM VERIFICATION"
+echo "║  $(date '+%Y-%m-%d %H:%M %Z')                      ║"
+echo "╚══════════════════════════════════════════════╝"
+echo ""
+
+echo "=== DAEMONS ==="
+# Launchd labels start with AGENT_LAUNCHD_PREFIX (e.g. ai.maestro.ravi).
+# The legacy code searched for "robin-poller" etc.; we now derive the
+# agent-specific component from the prefix's last segment so the check
+# works for any agent.
+LAUNCHD_AGENT_SLUG="$(basename "$LAUNCHD_PREFIX" | tr -d ' ')"  # e.g. "ravi" from "ai.maestro.ravi"
+check "Poller daemon loaded" "launchctl list | grep -q ${LAUNCHD_AGENT_SLUG}-poller"
+check "Inbox processor loaded" "launchctl list | grep -q ${LAUNCHD_AGENT_SLUG}-inbox-processor"
+check "Meeting prep loaded" "launchctl list | grep -q ${LAUNCHD_AGENT_SLUG}-meeting-prep"
+check "Meeting capture loaded" "launchctl list | grep -q ${LAUNCHD_AGENT_SLUG}-meeting-action-capture"
+check "Midday sweep loaded" "launchctl list | grep -q ${LAUNCHD_AGENT_SLUG}-midday-sweep"
+check "Weekly hiring loaded" "launchctl list | grep -q ${LAUNCHD_AGENT_SLUG}-weekly-hiring"
+check "Weekly priorities loaded" "launchctl list | grep -q ${LAUNCHD_AGENT_SLUG}-weekly-priorities"
+check "Weekly eng health loaded" "launchctl list | grep -q ${LAUNCHD_AGENT_SLUG}-weekly-engineering-health"
+check "Weekly execution loaded" "launchctl list | grep -q ${LAUNCHD_AGENT_SLUG}-weekly-execution"
+check "Weekly strategic memo loaded" "launchctl list | grep -q ${LAUNCHD_AGENT_SLUG}-weekly-strategic-memo"
+check "Quarterly self-assessment loaded" "launchctl list | grep -q ${LAUNCHD_AGENT_SLUG}-quarterly"
+echo ""
+
+echo "=== REMOTE TRIGGERS ==="
+warn_check "Git pushed to origin" "test $(git rev-list --count origin/main..HEAD) -eq 0"
+echo "  Remote triggers read from GitHub — must be pushed to work"
+echo ""
+
+echo "=== POLLER ACTIVITY ==="
+TODAY=$(date -u +%Y-%m-%d)
+YESTERDAY=$(date -u -v-1d +%Y-%m-%d 2>/dev/null || date -u -d yesterday +%Y-%m-%d 2>/dev/null || echo "unknown")
+POLLER_LOG="logs/polling/${TODAY}-poller.jsonl"
+POLLER_LOG_YESTERDAY="logs/polling/${YESTERDAY}-poller.jsonl"
+if [ -f "$POLLER_LOG" ]; then
+    LAST_POLL=$(tail -1 "$POLLER_LOG" | python3 -c "import sys,json; print(json.loads(sys.stdin.read()).get('timestamp','unknown'))" 2>/dev/null || echo "unknown")
+    POLL_COUNT=$(wc -l < "$POLLER_LOG" | tr -d ' ')
+    echo -e "  ${GREEN}✓${NC} Poller active today: $POLL_COUNT polls, last at $LAST_POLL"
+    ((pass++))
+elif [ -f "$POLLER_LOG_YESTERDAY" ]; then
+    LAST_POLL=$(tail -1 "$POLLER_LOG_YESTERDAY" | python3 -c "import sys,json; print(json.loads(sys.stdin.read()).get('timestamp','unknown'))" 2>/dev/null || echo "unknown")
+    echo -e "  ${YELLOW}⚠${NC} No log today, yesterday's last poll: $LAST_POLL"
+    ((warn++))
+else
+    echo -e "  ${RED}✗${NC} No poller logs found"
+    ((fail++))
+fi
+echo ""
+
+echo "=== WORKFLOW EXECUTION ==="
+for workflow in inbox-processor meeting-prep meeting-action-capture; do
+    LOG="logs/workflows/${TODAY}-${workflow}.jsonl"
+    LOG_Y="logs/workflows/${YESTERDAY}-${workflow}.jsonl"
+    if [ -f "$LOG" ]; then
+        ENTRIES=$(wc -l < "$LOG" | tr -d ' ')
+        echo -e "  ${GREEN}✓${NC} $workflow: $ENTRIES log entries today"
+        ((pass++))
+    elif [ -f "$LOG_Y" ]; then
+        echo -e "  ${YELLOW}⚠${NC} $workflow: ran yesterday, not yet today"
+        ((warn++))
+    else
+        echo -e "  ${RED}✗${NC} $workflow: no recent logs"
+        ((fail++))
+    fi
+done
+echo ""
+
+echo "=== QUEUE HEALTH ==="
+TOTAL=0
+for q in state/queues/*.yaml; do
+    COUNT=$(grep -c "^  - id:" "$q" 2>/dev/null || echo 0)
+    TOTAL=$((TOTAL + COUNT))
+done
+echo "  Total items across all queues: $TOTAL"
+if [ "$TOTAL" -gt 0 ]; then
+    echo -e "  ${GREEN}✓${NC} Queues populated"
+    ((pass++))
+else
+    echo -e "  ${RED}✗${NC} All queues empty — backlog not loaded"
+    ((fail++))
+fi
+
+CRITICAL=$(grep -r "priority: critical" state/queues/ 2>/dev/null | wc -l | tr -d ' ')
+echo "  Critical items: $CRITICAL"
+echo ""
+
+echo "=== DASHBOARDS ==="
+for dash in executive-summary strategy-scorecard org-health leadership-accountability engineering-health relationship-pipeline capital-readiness risk-register system-health; do
+    check "Dashboard: $dash" "test -f state/dashboards/${dash}.yaml"
+done
+echo ""
+
+echo "=== STATE FILES ==="
+check "15+ queue files" "test $(ls state/queues/*.yaml | wc -l) -ge 15"
+check "5 user profiles" "test $(ls memory/profiles/users/*.yaml | wc -l) -ge 5"
+check "10 channel profiles" "test $(ls memory/profiles/channels/*.yaml | wc -l) -ge 10"
+check "Decision library" "test -f knowledge/decisions/index.yaml"
+check "Strategy state" "test -f knowledge/syntheses/strategy-state.yaml"
+check "Blocker playbooks" "test -f knowledge/sources/blocker-playbooks.yaml"
+check "SLA defaults" "test -f config/sla-defaults.yaml"
+check "Defence policy" "test -f policies/prompt-injection-defence.yaml"
+echo ""
+
+echo "=== HOOKS ==="
+check "Pre-send audit hook" "test -x scripts/hooks/pre-send-audit.sh"
+check "Post-action log hook" "test -x scripts/hooks/post-action-log.sh"
+check "Session-end log hook" "test -x scripts/hooks/session-end-log.sh"
+check "Hooks configured in settings" "grep -q 'pre-send-audit' .claude/settings.json"
+echo ""
+
+echo "=== TRIGGER PROMPTS ==="
+TRIGGER_COUNT=$(ls schedules/triggers/*.md | wc -l | tr -d ' ')
+check "12+ trigger prompts" "test $TRIGGER_COUNT -ge 12"
+echo "  Trigger prompts: $TRIGGER_COUNT"
+echo ""
+
+echo "=== CLAUDE.MD ==="
+CT_COUNT=$(grep -c "Control Tower" CLAUDE.md)
+check "12 control towers documented" "test $CT_COUNT -ge 12"
+check "Agent teams enabled" "grep -q 'AGENT_TEAMS' .claude/settings.json"
+echo ""
+
+echo "══════════════════════════════════════════════"
+echo -e "  ${GREEN}PASS: $pass${NC}  ${YELLOW}WARN: $warn${NC}  ${RED}FAIL: $fail${NC}"
+echo "══════════════════════════════════════════════"
+
+if [ "$fail" -gt 0 ]; then
+    echo -e "  ${RED}System has failures — investigate above${NC}"
+    exit 1
+elif [ "$warn" -gt 0 ]; then
+    echo -e "  ${YELLOW}System operational with warnings${NC}"
+    exit 0
+else
+    echo -e "  ${GREEN}System fully operational${NC}"
+    exit 0
+fi

package/scripts/test-email-thread-dedup.py

@@ -0,0 +1,239 @@
+#!/usr/bin/env python3
+"""Tests for email-thread-dedup.py — thread-level email deduplication.
+
+Run: python3 scripts/test-email-thread-dedup.py
+"""
+import json
+import os
+import sys
+import time
+
+# Add scripts dir to path
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from email_thread_dedup import (
+    _normalize_subject,
+    _normalize_recipient,
+    _thread_key,
+    check_thread_lock,
+    acquire_thread_lock,
+    confirm_thread_lock,
+    release_thread_lock,
+    clean_expired_locks,
+    LOCK_DIR,
+    TTL_SECONDS,
+    _lock_path,
+)
+
+PASS = 0
+FAIL = 0
+
+
+def assert_eq(label, actual, expected):
+    global PASS, FAIL
+    if actual == expected:
+        PASS += 1
+        print(f"  PASS: {label}")
+    else:
+        FAIL += 1
+        print(f"  FAIL: {label}")
+        print(f"    expected: {expected!r}")
+        print(f"    actual:   {actual!r}")
+
+
+def assert_true(label, value):
+    assert_eq(label, bool(value), True)
+
+
+def assert_false(label, value):
+    assert_eq(label, bool(value), False)
+
+
+# --- Test subject normalization ---
+
+print("\n=== Subject normalization ===")
+assert_eq("strips Re:", _normalize_subject("Re: Hello"), "Hello")
+assert_eq("strips RE:", _normalize_subject("RE: Hello"), "Hello")
+assert_eq("strips Fwd:", _normalize_subject("Fwd: Hello"), "Hello")
+assert_eq("strips FW:", _normalize_subject("FW: Hello"), "Hello")
+assert_eq("strips nested Re: Re:", _normalize_subject("Re: Re: Hello"), "Hello")
+assert_eq("strips mixed Re: Fwd:", _normalize_subject("Re: Fwd: Hello"), "Hello")
+assert_eq("normalizes whitespace", _normalize_subject("  Re:  Hello   World  "), "Hello World")
+assert_eq("preserves clean subject", _normalize_subject("Hello World"), "Hello World")
+
+# --- Test recipient normalization ---
+
+print("\n=== Recipient normalization ===")
+assert_eq("lowercases", _normalize_recipient("John@Example.COM"), "john@example.com")
+assert_eq("strips display name", _normalize_recipient("John Doe <john@example.com>"), "john@example.com")
+assert_eq("takes first of multiple", _normalize_recipient("john@a.com, jane@b.com"), "john@a.com")
+assert_eq("strips whitespace", _normalize_recipient("  john@example.com  "), "john@example.com")
+
+# --- Test thread key consistency ---
+
+print("\n=== Thread key consistency ===")
+key1 = _thread_key("john@example.com", "Re: Hello World")
+key2 = _thread_key("john@example.com", "Hello World")
+key3 = _thread_key("john@example.com", "RE: Fwd: Hello World")
+key4 = _thread_key("JOHN@EXAMPLE.COM", "Re: Hello World")
+key5 = _thread_key("john@example.com", "Different Subject")
+
+assert_eq("Re: stripped matches base", key1, key2)
+assert_eq("RE: Fwd: stripped matches base", key3, key2)
+assert_eq("case-insensitive recipient", key4, key1)
+assert_true("different subject = different key", key5 != key1)
+
+# --- Test lock lifecycle ---
+
+print("\n=== Lock lifecycle ===")
+
+# Use unique test subjects to avoid interference
+TEST_TO = "test-dedup@example.com"
+TEST_SUBJECT = f"Test Subject {time.time()}"
+
+# Clean start
+release_thread_lock(TEST_TO, TEST_SUBJECT)
+
+# 1. Check — should be available
+result = check_thread_lock(TEST_TO, TEST_SUBJECT)
+assert_false("initially unlocked", result["locked"])
+
+# 2. Acquire — should succeed
+acq = acquire_thread_lock(TEST_TO, TEST_SUBJECT, session_id="test-session-1", preview="Hello this is a test")
+assert_true("first acquire succeeds", acq["acquired"])
+assert_true("thread key returned", len(acq["thread_key"]) > 0)
+
+# 3. Check again — should now be locked
+result = check_thread_lock(TEST_TO, TEST_SUBJECT)
+assert_true("now locked", result["locked"])
+assert_eq("locked by correct session", result["lock_data"]["session_id"], "test-session-1")
+
+# 4. Second acquire — should be BLOCKED
+acq2 = acquire_thread_lock(TEST_TO, TEST_SUBJECT, session_id="test-session-2", preview="Different wording")
+assert_false("second acquire blocked", acq2["acquired"])
+assert_true("existing lock returned", acq2["existing_lock"] is not None)
+assert_eq("existing lock session", acq2["existing_lock"]["session_id"], "test-session-1")
+
+# 5. Confirm — should update status
+confirm_thread_lock(TEST_TO, TEST_SUBJECT, preview="Confirmed preview text")
+result = check_thread_lock(TEST_TO, TEST_SUBJECT)
+assert_true("still locked after confirm", result["locked"])
+assert_eq("status is confirmed", result["lock_data"]["status"], "confirmed")
+
+# 6. Release — should unlock
+release_thread_lock(TEST_TO, TEST_SUBJECT)
+result = check_thread_lock(TEST_TO, TEST_SUBJECT)
+assert_false("unlocked after release", result["locked"])
+
+# --- Test expired lock handling ---
+
+print("\n=== Expired lock handling ===")
+TEST_SUBJECT_EXP = f"Expired Subject {time.time()}"
+
+# Create a lock with a timestamp in the past (>24h ago)
+key = _thread_key(TEST_TO, TEST_SUBJECT_EXP)
+path = _lock_path(key)
+os.makedirs(LOCK_DIR, exist_ok=True)
+expired_data = {
+    "thread_key": key,
+    "timestamp": "2026-01-01T00:00:00Z",
+    "timestamp_epoch": time.time() - (TTL_SECONDS + 3600),  # 25 hours ago
+    "session_id": "old-session",
+    "subject_normalized": "Expired Subject",
+    "recipient_normalized": TEST_TO,
+    "preview": "old message",
+    "status": "confirmed",
+}
+with open(path, "w") as f:
+    json.dump(expired_data, f)
+
+# Check — expired lock should NOT block
+result = check_thread_lock(TEST_TO, TEST_SUBJECT_EXP)
+assert_false("expired lock does not block", result["locked"])
+
+# Acquire over expired lock — should succeed
+acq = acquire_thread_lock(TEST_TO, TEST_SUBJECT_EXP, session_id="new-session")
+assert_true("acquire over expired lock succeeds", acq["acquired"])
+
+# Clean up
+release_thread_lock(TEST_TO, TEST_SUBJECT_EXP)
+
+# --- Test Re:/Fwd: variant blocking ---
+
+print("\n=== Subject variant blocking ===")
+TEST_SUBJECT_VAR = f"Important Meeting Notes {time.time()}"
+release_thread_lock(TEST_TO, TEST_SUBJECT_VAR)  # clean start
+
+# Acquire with base subject
+acq = acquire_thread_lock(TEST_TO, TEST_SUBJECT_VAR, session_id="session-a")
+assert_true("acquire base subject", acq["acquired"])
+
+# Attempt with Re: variant — should be blocked (same thread)
+acq2 = acquire_thread_lock(TEST_TO, f"Re: {TEST_SUBJECT_VAR}", session_id="session-b")
+assert_false("Re: variant blocked", acq2["acquired"])
+
+# Attempt with RE: Fwd: variant — should also be blocked
+acq3 = acquire_thread_lock(TEST_TO, f"RE: Fwd: {TEST_SUBJECT_VAR}", session_id="session-c")
+assert_false("RE: Fwd: variant blocked", acq3["acquired"])
+
+# Clean up
+release_thread_lock(TEST_TO, TEST_SUBJECT_VAR)
+
+# --- Test clean_expired_locks ---
+
+print("\n=== Cleanup function ===")
+TEST_SUBJECT_CLN = f"Cleanup Test {time.time()}"
+
+# Create an expired lock
+key = _thread_key(TEST_TO, TEST_SUBJECT_CLN)
+path = _lock_path(key)
+expired_data = {
+    "thread_key": key,
+    "timestamp": "2026-01-01T00:00:00Z",
+    "timestamp_epoch": time.time() - (TTL_SECONDS + 3600),
+    "session_id": "cleanup-test",
+    "subject_normalized": "Cleanup Test",
+    "recipient_normalized": TEST_TO,
+    "status": "confirmed",
+}
+with open(path, "w") as f:
+    json.dump(expired_data, f)
+
+assert_true("expired lock file exists before clean", os.path.exists(path))
+removed = clean_expired_locks()
+assert_true("cleanup removed at least 1", removed >= 1)
+assert_false("expired lock file gone after clean", os.path.exists(path))
+
+# --- Test lock file contents ---
+
+print("\n=== Lock file contents ===")
+TEST_SUBJECT_META = f"Metadata Check {time.time()}"
+release_thread_lock(TEST_TO, TEST_SUBJECT_META)
+
+acquire_thread_lock(TEST_TO, TEST_SUBJECT_META, session_id="meta-session", preview="Hello, I wanted to follow up on our conversation")
+key = _thread_key(TEST_TO, TEST_SUBJECT_META)
+path = _lock_path(key)
+
+with open(path, "r") as f:
+    data = json.load(f)
+
+assert_eq("has thread_key", data.get("thread_key"), key)
+assert_true("has timestamp", "timestamp" in data)
+assert_true("has timestamp_epoch", "timestamp_epoch" in data)
+assert_eq("has session_id", data.get("session_id"), "meta-session")
+assert_true("has subject_normalized", "subject_normalized" in data)
+assert_true("has recipient_normalized", "recipient_normalized" in data)
+assert_true("has preview", len(data.get("preview", "")) > 0)
+assert_eq("status is acquired", data.get("status"), "acquired")
+
+release_thread_lock(TEST_TO, TEST_SUBJECT_META)
+
+# --- Summary ---
+
+print(f"\n{'='*50}")
+print(f"Results: {PASS} passed, {FAIL} failed, {PASS + FAIL} total")
+if FAIL > 0:
+    print("SOME TESTS FAILED")
+    sys.exit(1)
+else:
+    print("ALL TESTS PASSED")
+    sys.exit(0)