@cohortapp/agent-sdk 2.3.0

package/scripts/daemon/session-lock.mjs

@@ -0,0 +1,721 @@
+#!/usr/bin/env node
+/**
+ * session-lock.mjs — File-based session locks and sent-message registry
+ *
+ * Replaces the in-memory recentlyProcessed Map in the agent daemon with
+ * persistent, atomic file locks that survive daemon restarts and prevent
+ * race conditions between concurrent polls.
+ *
+ * Also provides a sent-message registry to prevent duplicate sends even
+ * when locking fails (belt + suspenders).
+ */
+
+import {
+  writeFileSync,
+  readFileSync,
+  unlinkSync,
+  readdirSync,
+  appendFileSync,
+  mkdirSync,
+  existsSync,
+} from "fs";
+import { join } from "path";
+
+// Allow test override of state directory
+const AGENT_REPO_DIR = process.env.AGENT_DIR || join(new URL(".", import.meta.url).pathname, "../..");
+const SESSION_DIR = process.env.__TEST_SESSION_DIR || join(AGENT_REPO_DIR, "state", "sessions");
+const LOCKS_DIR = join(SESSION_DIR, "locks");
+const REGISTRY_PATH = join(SESSION_DIR, "sent-registry.jsonl");
+
+const STALE_LOCK_MS = 2 * 60 * 60 * 1000; // 2 hours — must exceed longest session timeout (Opus backlog = 12h, but 2h covers all inbox sessions and prevents re-dispatch of the same message across daemon restarts)
+const THREAD_LOCK_MS = 60 * 60 * 1000; // 60 min — stale fallback; normally released explicitly by dispatcher on session close
+const DM_CHANNEL_LOCK_MS = 60 * 60 * 1000; // 60 min — must match THREAD_LOCK_MS; 10 min was too short (Opus sessions take up to 45 min, and the lock expired mid-session causing triple-dispatch of CEO messages)
+const SENT_DEDUP_WINDOW_MS = 30 * 60 * 1000; // 30 min (was 10 min — still too short; CEO brief incident showed re-sends at 8-min intervals bypassing the window)
+const SENT_SUBSTANTIVE_WINDOW_MS = 2 * 60 * 1000; // 2 min for same-person substantive
+const HOLDING_DM_DEDUP_WINDOW_MS = 5 * 60 * 1000; // 5 min — max 1 holding note per DM channel per 5-min window
+const MAX_REGISTRY_ENTRIES = 500; // Keep registry file manageable
+
+// Ensure directories exist
+mkdirSync(LOCKS_DIR, { recursive: true });
+
+/**
+ * Sanitise an item ID for use as a filename.
+ * Replaces all non-alphanumeric characters with hyphens.
+ */
+export function sanitiseItemId(itemId) {
+  return itemId.replace(/[^a-zA-Z0-9]/g, "-");
+}
+
+/**
+ * Attempt to acquire a lock for an item.
+ * Uses exclusive file creation (wx flag) for atomicity.
+ *
+ * @param {string} itemId - Raw item ID (will be sanitised)
+ * @param {object} metadata - { sender, channel, sessionId? }
+ * @returns {{ acquired: boolean, existing?: object }}
+ */
+export function acquireLock(itemId, metadata = {}) {
+  const safeId = sanitiseItemId(itemId);
+  const lockPath = join(LOCKS_DIR, `${safeId}.lock`);
+
+  // Check for existing lock
+  if (existsSync(lockPath)) {
+    try {
+      const existing = JSON.parse(readFileSync(lockPath, "utf-8"));
+      const age = Date.now() - new Date(existing.acquiredAt).getTime();
+
+      // If lock is fresh (< STALE_LOCK_MS), reject
+      if (age < STALE_LOCK_MS) {
+        return { acquired: false, existing };
+      }
+      // Stale lock — fall through to overwrite
+    } catch {
+      // Corrupted lock file — overwrite
+    }
+  }
+
+  const lockData = {
+    sessionId: metadata.sessionId || `pending-${Date.now()}`,
+    itemId,
+    channel: metadata.channel || null,
+    sender: metadata.sender || null,
+    acquiredAt: new Date().toISOString(),
+    holdingSent: false,
+    substantiveSent: false,
+  };
+
+  try {
+    // Try exclusive create first (atomic)
+    writeFileSync(lockPath, JSON.stringify(lockData, null, 2), { flag: "wx" });
+    return { acquired: true };
+  } catch (err) {
+    if (err.code === "EEXIST") {
+      // Another process beat us — check if it's stale
+      try {
+        const existing = JSON.parse(readFileSync(lockPath, "utf-8"));
+        const age = Date.now() - new Date(existing.acquiredAt).getTime();
+        if (age >= STALE_LOCK_MS) {
+          // Stale — overwrite (non-atomic but acceptable for stale locks)
+          writeFileSync(lockPath, JSON.stringify(lockData, null, 2));
+          return { acquired: true };
+        }
+        return { acquired: false, existing };
+      } catch {
+        return { acquired: false };
+      }
+    }
+    throw err;
+  }
+}
+
+/**
+ * Release a lock for an item.
+ * @param {string} itemId - Raw item ID (will be sanitised)
+ */
+export function releaseLock(itemId) {
+  const safeId = sanitiseItemId(itemId);
+  const lockPath = join(LOCKS_DIR, `${safeId}.lock`);
+  try {
+    unlinkSync(lockPath);
+  } catch {
+    // Lock already released or never existed — fine
+  }
+}
+
+/**
+ * Read the lock data for an item without modifying it.
+ * @param {string} itemId - Raw item ID (will be sanitised)
+ * @returns {object|null} Lock data or null if no lock
+ */
+export function readLock(itemId) {
+  const safeId = sanitiseItemId(itemId);
+  const lockPath = join(LOCKS_DIR, `${safeId}.lock`);
+  try {
+    return JSON.parse(readFileSync(lockPath, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Update fields on an existing lock.
+ * @param {string} itemId - Raw item ID
+ * @param {object} updates - Fields to merge (e.g., { holdingSent: true })
+ */
+export function updateLock(itemId, updates) {
+  const safeId = sanitiseItemId(itemId);
+  const lockPath = join(LOCKS_DIR, `${safeId}.lock`);
+  try {
+    const existing = JSON.parse(readFileSync(lockPath, "utf-8"));
+    const updated = { ...existing, ...updates };
+    writeFileSync(lockPath, JSON.stringify(updated, null, 2));
+  } catch {
+    // Lock doesn't exist — no-op
+  }
+}
+
+/**
+ * Scan and remove stale locks (older than STALE_LOCK_MS).
+ * Call on daemon startup to clean up after crashes.
+ * @returns {number} Number of stale locks cleared
+ */
+export function scanStaleLocks() {
+  let cleared = 0;
+  try {
+    const files = readdirSync(LOCKS_DIR).filter((f) => f.endsWith(".lock"));
+    for (const file of files) {
+      const lockPath = join(LOCKS_DIR, file);
+      try {
+        const data = JSON.parse(readFileSync(lockPath, "utf-8"));
+        const age = Date.now() - new Date(data.acquiredAt).getTime();
+        if (age >= STALE_LOCK_MS) {
+          unlinkSync(lockPath);
+          cleared++;
+        }
+      } catch {
+        // Corrupted lock — remove it
+        try { unlinkSync(lockPath); cleared++; } catch {}
+      }
+    }
+  } catch {
+    // LOCKS_DIR doesn't exist yet — nothing to scan
+  }
+  return cleared;
+}
+
+/**
+ * Register that a message was sent.
+ * @param {string} channel - Slack channel ID or email address
+ * @param {string|null} threadTs - Thread timestamp (null for non-threaded)
+ * @param {string} type - "holding" | "quick_reply" | "substantive"
+ * @param {string} sessionId - Session that sent it
+ * @param {string} textPreview - First ~100 chars of the message
+ */
+export function registerSent(channel, threadTs, type, sessionId, textPreview) {
+  const entry = {
+    timestamp: new Date().toISOString(),
+    channel,
+    threadTs: threadTs || null,
+    type,
+    sessionId,
+    textPreview: (textPreview || "").substring(0, 100),
+  };
+  try {
+    appendFileSync(REGISTRY_PATH, JSON.stringify(entry) + "\n");
+  } catch {
+    // Registry dir might not exist yet in tests
+    mkdirSync(SESSION_DIR, { recursive: true });
+    appendFileSync(REGISTRY_PATH, JSON.stringify(entry) + "\n");
+  }
+}
+
+/**
+ * Check if a similar message was recently sent to the same channel/thread.
+ * @param {string} channel
+ * @param {string|null} threadTs
+ * @param {string} type - "holding" | "quick_reply" | "substantive"
+ * @returns {{ allowed: boolean, reason?: string }}
+ */
+export function checkRecentlySent(channel, threadTs, type) {
+  let entries = [];
+  try {
+    const raw = readFileSync(REGISTRY_PATH, "utf-8").trim();
+    if (!raw) return { allowed: true };
+    const lines = raw.split("\n").filter(Boolean);
+    // Only check recent entries (last MAX_REGISTRY_ENTRIES lines)
+    const recent = lines.slice(-MAX_REGISTRY_ENTRIES);
+    entries = recent.map((line) => {
+      try { return JSON.parse(line); } catch { return null; }
+    }).filter(Boolean);
+  } catch {
+    // No registry file yet — nothing sent
+    return { allowed: true };
+  }
+
+  const now = Date.now();
+  const isDmChannel = channel.startsWith("D");
+
+  // Rule 0a: DM holding-note dedup — max 1 holding note per DM channel per
+  // 5-minute window, regardless of thread. Prevents the CEO from receiving
+  // 3 holding notes when multiple sessions pick up the same request.
+  if (isDmChannel && type === "holding") {
+    const holdingMatch = entries.find((e) => {
+      const age = now - new Date(e.timestamp).getTime();
+      return e.channel === channel
+        && e.type === "holding"
+        && age < HOLDING_DM_DEDUP_WINDOW_MS;
+    });
+    if (holdingMatch) {
+      return { allowed: false, reason: `dm-holding-dedup: holding note already sent to this DM ${Math.round((now - new Date(holdingMatch.timestamp).getTime()) / 1000)}s ago (max 1 per ${HOLDING_DM_DEDUP_WINDOW_MS / 1000}s)` };
+    }
+  }
+
+  // Rule 0b: DM channel-level dedup — in DMs, user sees thread replies and
+  // main-feed messages in a single stream. A message sent to thread X and
+  // a message sent to the main DM feed are BOTH visible to the user, so
+  // treat the entire DM channel as one dedup group regardless of threadTs.
+  // This prevents the bug where a single message discovered via two paths
+  // (thread reply + DM channel message) each triggers independent sends.
+  if (isDmChannel) {
+    const dmMatch = entries.find((e) => {
+      const age = now - new Date(e.timestamp).getTime();
+      return e.channel === channel
+        && e.type === type
+        && age < SENT_DEDUP_WINDOW_MS;
+    });
+    if (dmMatch) {
+      return { allowed: false, reason: `dm-channel-dedup: ${type} already sent to this DM ${Math.round((now - new Date(dmMatch.timestamp).getTime()) / 1000)}s ago (thread ${dmMatch.threadTs || "main"})` };
+    }
+  }
+
+  // Rule 1: Same channel + thread + type within dedup window → BLOCK
+  const exactMatch = entries.find((e) => {
+    const age = now - new Date(e.timestamp).getTime();
+    return e.channel === channel
+      && e.threadTs === (threadTs || null)
+      && e.type === type
+      && age < SENT_DEDUP_WINDOW_MS;
+  });
+  if (exactMatch) {
+    return { allowed: false, reason: `duplicate: same channel+thread+type sent ${Math.round((now - new Date(exactMatch.timestamp).getTime()) / 1000)}s ago` };
+  }
+
+  // Rule 2: Same channel + thread (any type) within dedup window → BLOCK
+  // Prevents cascading responses when the same thread is re-ingested
+  // across multiple poll cycles with different message types.
+  if (threadTs) {
+    const threadMatch = entries.find((e) => {
+      const age = now - new Date(e.timestamp).getTime();
+      return e.channel === channel
+        && e.threadTs === threadTs
+        && age < SENT_DEDUP_WINDOW_MS;
+    });
+    if (threadMatch) {
+      return { allowed: false, reason: `thread cooldown: ${threadMatch.type} sent to same thread ${Math.round((now - new Date(threadMatch.timestamp).getTime()) / 1000)}s ago` };
+    }
+  }
+
+  // Rule 3: Same channel + substantive within 2 min (any thread) → BLOCK
+  if (type === "substantive") {
+    const rapidMatch = entries.find((e) => {
+      const age = now - new Date(e.timestamp).getTime();
+      return e.channel === channel
+        && e.type === "substantive"
+        && age < SENT_SUBSTANTIVE_WINDOW_MS;
+    });
+    if (rapidMatch) {
+      return { allowed: false, reason: `rapid: substantive message to same channel sent ${Math.round((now - new Date(rapidMatch.timestamp).getTime()) / 1000)}s ago` };
+    }
+  }
+
+  return { allowed: true };
+}
+
+/**
+ * Check if a session was already dispatched for the same thread recently.
+ * Prevents multiple sessions from responding to the same thread when
+ * several messages arrive in quick succession.
+ *
+ * For DM channel locks (threadTs = "dm-channel"), uses a shorter timeout
+ * (10 min) since DMs are individual messages, not persistent threads.
+ *
+ * @param {string} channel - Slack channel ID
+ * @param {string} threadTs - Thread parent timestamp, or "dm-channel" for non-threaded DMs
+ * @returns {{ allowed: boolean, reason?: string }}
+ */
+export function acquireThreadLock(channel, threadTs) {
+  if (!channel || !threadTs) return { allowed: true };
+
+  // DM CHANNEL NORMALIZATION: In DMs (channel starts with "D"), always use
+  // "dm-channel" as the lock key regardless of the actual threadTs. This
+  // ensures only ONE session handles a DM at a time — whether the message
+  // arrived as a thread reply or a main-feed message, the user sees both
+  // in the same conversation. Without this, the same message discovered
+  // via two paths (thread reply + DM channel) gets two separate locks.
+  if (channel.startsWith("D")) {
+    threadTs = "dm-channel";
+  }
+
+  // Use shorter lock for DM channels vs actual threads
+  const isDmLock = threadTs === "dm-channel";
+  const lockTimeout = isDmLock ? DM_CHANNEL_LOCK_MS : THREAD_LOCK_MS;
+  const lockLabel = isDmLock ? "DM channel" : "thread";
+
+  const safeKey = sanitiseItemId(`thread-${channel}-${threadTs}`);
+  const lockPath = join(LOCKS_DIR, `${safeKey}.lock`);
+
+  if (existsSync(lockPath)) {
+    try {
+      const existing = JSON.parse(readFileSync(lockPath, "utf-8"));
+      const age = Date.now() - new Date(existing.acquiredAt).getTime();
+      if (age < lockTimeout) {
+        return {
+          allowed: false,
+          reason: `${lockLabel} already dispatched ${Math.round(age / 1000)}s ago by ${existing.sessionId}`,
+        };
+      }
+      // Stale — fall through to overwrite
+    } catch {
+      // Corrupted — fall through to overwrite
+    }
+  }
+
+  const lockData = {
+    sessionId: `thread-${Date.now()}`,
+    channel,
+    threadTs,
+    acquiredAt: new Date().toISOString(),
+  };
+
+  try {
+    writeFileSync(lockPath, JSON.stringify(lockData, null, 2), { flag: "wx" });
+    return { allowed: true };
+  } catch (err) {
+    if (err.code === "EEXIST") {
+      try {
+        const existing = JSON.parse(readFileSync(lockPath, "utf-8"));
+        const age = Date.now() - new Date(existing.acquiredAt).getTime();
+        if (age >= lockTimeout) {
+          writeFileSync(lockPath, JSON.stringify(lockData, null, 2));
+          return { allowed: true };
+        }
+        return {
+          allowed: false,
+          reason: `${lockLabel} already dispatched ${Math.round(age / 1000)}s ago`,
+        };
+      } catch {
+        return { allowed: false, reason: "thread lock contention" };
+      }
+    }
+    throw err;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Request claiming — prevents multiple sessions from processing the same
+// inbound request (e.g., "email me the brief" picked up by inbox poller
+// AND backlog sweep, or by consecutive poll cycles).
+// ---------------------------------------------------------------------------
+
+const REQUEST_CLAIM_DIR = join(SESSION_DIR, "request-claims");
+const REQUEST_CLAIM_TTL_MS = 30 * 60 * 1000; // 30 min — request claim expires after 30 min
+
+// Ensure directory exists
+mkdirSync(REQUEST_CLAIM_DIR, { recursive: true });
+
+/**
+ * Generate a normalized claim key from request attributes.
+ * Normalizes subject/content to catch semantically-equivalent requests.
+ *
+ * @param {object} attrs - { recipient, subject, action_type }
+ *   recipient: email address or Slack channel
+ *   subject: email subject or brief description of request
+ *   action_type: "email_brief", "send_email", "respond", etc.
+ * @returns {string} Sanitized claim key
+ */
+export function requestClaimKey(attrs) {
+  const { recipient = "", subject = "", action_type = "" } = attrs;
+  // Normalize: lowercase, strip dates/times, strip Re:/Fwd:, collapse whitespace
+  const normRecipient = recipient.toLowerCase().trim();
+  const normSubject = subject.toLowerCase()
+    .replace(/^(re|fwd|fw):\s*/gi, "")
+    .replace(/\d{1,2}:\d{2}(:\d{2})?/g, "")         // strip times
+    .replace(/(mon|tue|wed|thu|fri|sat|sun)\w*/gi, "") // strip day names
+    .replace(/\d{1,2}\s+(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)\w*\s+\d{4}/gi, "") // strip dates
+    .replace(/\d{4}-\d{2}-\d{2}/g, "")                // strip ISO dates
+    .replace(/\s+/g, " ")
+    .trim();
+  const raw = `${action_type}|${normRecipient}|${normSubject}`;
+  return sanitiseItemId(`req-${raw}`).substring(0, 120);
+}
+
+/**
+ * Attempt to claim an inbound request so only one session processes it.
+ *
+ * @param {object} attrs - { recipient, subject, action_type }
+ * @param {string} sessionId - Session claiming the request
+ * @returns {{ claimed: boolean, reason?: string, existing?: object }}
+ */
+export function claimRequest(attrs, sessionId = "") {
+  const key = requestClaimKey(attrs);
+  const claimPath = join(REQUEST_CLAIM_DIR, `${key}.claim`);
+
+  if (!sessionId) sessionId = `claim-${Date.now()}`;
+
+  // Check for existing claim
+  if (existsSync(claimPath)) {
+    try {
+      const existing = JSON.parse(readFileSync(claimPath, "utf-8"));
+      const age = Date.now() - new Date(existing.claimedAt).getTime();
+      if (age < REQUEST_CLAIM_TTL_MS) {
+        return { claimed: false, reason: `request already claimed by ${existing.sessionId} ${Math.round(age / 1000)}s ago`, existing };
+      }
+      // Stale — fall through to overwrite
+    } catch {
+      // Corrupted — fall through
+    }
+  }
+
+  const claimData = {
+    sessionId,
+    attrs,
+    claimedAt: new Date().toISOString(),
+  };
+
+  try {
+    writeFileSync(claimPath, JSON.stringify(claimData, null, 2), { flag: "wx" });
+    return { claimed: true };
+  } catch (err) {
+    if (err.code === "EEXIST") {
+      try {
+        const existing = JSON.parse(readFileSync(claimPath, "utf-8"));
+        const age = Date.now() - new Date(existing.claimedAt).getTime();
+        if (age >= REQUEST_CLAIM_TTL_MS) {
+          writeFileSync(claimPath, JSON.stringify(claimData, null, 2));
+          return { claimed: true };
+        }
+        return { claimed: false, reason: `request claim race lost to ${existing.sessionId}`, existing };
+      } catch {
+        return { claimed: false, reason: "request claim contention" };
+      }
+    }
+    // Fail-open: if we can't write the claim, allow processing
+    return { claimed: true };
+  }
+}
+
+/**
+ * Release a request claim (e.g., after session completes or fails).
+ *
+ * @param {object} attrs - Same attrs used to claim
+ */
+export function releaseRequestClaim(attrs) {
+  const key = requestClaimKey(attrs);
+  const claimPath = join(REQUEST_CLAIM_DIR, `${key}.claim`);
+  try {
+    unlinkSync(claimPath);
+  } catch {
+    // Already released or never existed — fine
+  }
+}
+
+/**
+ * Release a thread lock after the session handling this thread completes.
+ * This allows new messages in the thread to be processed by subsequent polls.
+ *
+ * @param {string} channel - Slack channel ID
+ * @param {string} threadTs - Thread parent timestamp
+ */
+export function releaseThreadLock(channel, threadTs) {
+  if (!channel) return;
+  // Match normalization in acquireThreadLock — DMs always use "dm-channel"
+  // regardless of whether threadTs is set. This MUST happen before the
+  // empty-threadTs check, otherwise DM channel locks never get released
+  // and every DM after the first gets dropped for the full 60min TTL
+  // (observed in ravi-ai on 2026-05-12: CEO's follow-up DM 23min after
+  // the first was skipped with "thread_dedup: DM channel already
+  // dispatched 1200s ago").
+  if (channel.startsWith("D")) threadTs = "dm-channel";
+  if (!threadTs) return; // non-DM channel without a thread — no lock to release
+  const safeKey = sanitiseItemId(`thread-${channel}-${threadTs}`);
+  const lockPath = join(LOCKS_DIR, `${safeKey}.lock`);
+  try {
+    unlinkSync(lockPath);
+  } catch {
+    // Lock already released or never existed — fine
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Item claims — prevents multiple parallel backlog sessions from picking up
+// the same queue item simultaneously. Designed per:
+// outputs/research/2026-04-18-session-coordination-design.md
+// ---------------------------------------------------------------------------
+
+const ITEM_CLAIM_DIR = join(AGENT_REPO_DIR, "state", "locks", "item-claims");
+const DEFAULT_ITEM_CLAIM_TTL_MIN = 30; // Default TTL in minutes
+
+// Ensure directory exists
+mkdirSync(ITEM_CLAIM_DIR, { recursive: true });
+
+/**
+ * Check if a process is still running (macOS-compatible).
+ * Uses kill(pid, 0) — signal 0 checks existence without sending a signal.
+ *
+ * @param {number} pid - Process ID to check
+ * @returns {boolean} true if process is running
+ */
+function isProcessRunning(pid) {
+  try {
+    process.kill(pid, 0); // Signal 0 = existence check
+    return true;
+  } catch (err) {
+    return err.code === "EPERM"; // Process exists but we lack permission
+  }
+}
+
+/**
+ * Attempt to claim a queue item so only one session processes it.
+ * Uses exclusive file creation (wx flag) for POSIX-atomic acquisition.
+ *
+ * Fail-open design: claim system failures never block work. The worst case
+ * is duplicate work (the status quo), not blocked work.
+ *
+ * @param {string} itemId - Queue item ID (e.g. "ib-20260407-001b")
+ * @param {object} metadata - { session_id, agent_description, ttl_minutes, source, queue_file, pid }
+ * @returns {{ claimed: boolean, reason?: string, holder?: string }}
+ */
+export function claimItem(itemId, metadata = {}) {
+  const safeId = sanitiseItemId(itemId);
+  const claimPath = join(ITEM_CLAIM_DIR, `${safeId}.claim`);
+  const ttlMinutes = metadata.ttl_minutes || DEFAULT_ITEM_CLAIM_TTL_MIN;
+
+  // Check for existing claim
+  if (existsSync(claimPath)) {
+    try {
+      const existing = JSON.parse(readFileSync(claimPath, "utf-8"));
+      const ageMinutes = (Date.now() - new Date(existing.claimed_at).getTime()) / 60000;
+
+      if (ageMinutes < (existing.ttl_minutes || DEFAULT_ITEM_CLAIM_TTL_MIN)) {
+        // Claim is within TTL — check if the holding process is actually alive
+        if (existing.pid && isProcessRunning(existing.pid)) {
+          return { claimed: false, reason: "active_claim", holder: existing.session_id };
+        }
+        // Process is dead but claim not expired — override (orphaned claim)
+        console.log(`[session-lock] Overriding orphaned item claim for ${itemId}, pid ${existing.pid} is dead`);
+        // Fall through to write new claim
+      } else {
+        // TTL expired — override
+        console.log(`[session-lock] Overriding expired item claim for ${itemId}, age ${ageMinutes.toFixed(1)}m > ttl ${existing.ttl_minutes || DEFAULT_ITEM_CLAIM_TTL_MIN}m`);
+        // Fall through to write new claim
+      }
+    } catch {
+      // Corrupted claim file — treat as no existing claim (fail-open)
+    }
+  }
+
+  const claimData = {
+    session_id: metadata.session_id || `claim-${Date.now()}`,
+    claimed_at: new Date().toISOString(),
+    agent_description: metadata.agent_description || "",
+    ttl_minutes: ttlMinutes,
+    source: metadata.source || "backlog",
+    queue_file: metadata.queue_file || "",
+    pid: metadata.pid || process.pid,
+  };
+
+  try {
+    // Atomic exclusive create — identical pattern to acquireLock (line 90)
+    writeFileSync(claimPath, JSON.stringify(claimData, null, 2), { flag: "wx" });
+    return { claimed: true };
+  } catch (err) {
+    if (err.code === "EEXIST") {
+      // Race condition — another process won the claim
+      try {
+        const existing = JSON.parse(readFileSync(claimPath, "utf-8"));
+        const ageMinutes = (Date.now() - new Date(existing.claimed_at).getTime()) / 60000;
+        if (ageMinutes >= (existing.ttl_minutes || DEFAULT_ITEM_CLAIM_TTL_MIN)) {
+          // Stale — overwrite (non-atomic but acceptable)
+          writeFileSync(claimPath, JSON.stringify(claimData, null, 2));
+          return { claimed: true };
+        }
+        return { claimed: false, reason: "race_lost", holder: existing.session_id };
+      } catch {
+        return { claimed: false, reason: "race_lost" };
+      }
+    }
+    // Fail-open: if we can't write the claim for any other reason, allow processing
+    console.warn(`[session-lock] Item claim write failed for ${itemId} (fail-open): ${err.message}`);
+    return { claimed: true };
+  }
+}
+
+/**
+ * Release a claim for a queue item (on session completion or error).
+ *
+ * @param {string} itemId - Queue item ID
+ */
+export function releaseItemClaim(itemId) {
+  const safeId = sanitiseItemId(itemId);
+  const claimPath = join(ITEM_CLAIM_DIR, `${safeId}.claim`);
+  try {
+    unlinkSync(claimPath);
+  } catch {
+    // Claim already released, expired, or never existed — fine
+  }
+}
+
+/**
+ * Check if a queue item has an active (non-expired, live-process) claim.
+ * Used by sweepBacklog to skip items already being worked on.
+ *
+ * @param {string} itemId - Queue item ID
+ * @returns {boolean} true if there is an active claim on this item
+ */
+export function hasActiveClaim(itemId) {
+  const safeId = sanitiseItemId(itemId);
+  const claimPath = join(ITEM_CLAIM_DIR, `${safeId}.claim`);
+
+  try {
+    if (!existsSync(claimPath)) return false;
+
+    const claim = JSON.parse(readFileSync(claimPath, "utf-8"));
+    const ageMinutes = (Date.now() - new Date(claim.claimed_at).getTime()) / 60000;
+    const ttl = claim.ttl_minutes || DEFAULT_ITEM_CLAIM_TTL_MIN;
+
+    // Expired claim — not active
+    if (ageMinutes >= ttl) return false;
+
+    // If PID is recorded and process is dead — not active (orphaned)
+    if (claim.pid && !isProcessRunning(claim.pid)) return false;
+
+    return true;
+  } catch {
+    // Fail-open: if we can't read/parse the claim, treat as no claim
+    return false;
+  }
+}
+
+/**
+ * Sweep stale item claims. Called periodically from the daemon health interval.
+ *
+ * Two-tier cleanup:
+ *   - Past 2x TTL: unconditionally remove (well past expiry)
+ *   - Past 1x TTL but within 2x: remove only if PID is dead (orphaned)
+ *
+ * @returns {number} Number of stale claims removed
+ */
+export function sweepStaleItemClaims() {
+  let swept = 0;
+  try {
+    const files = readdirSync(ITEM_CLAIM_DIR).filter((f) => f.endsWith(".claim"));
+    for (const file of files) {
+      const claimPath = join(ITEM_CLAIM_DIR, file);
+      try {
+        const claim = JSON.parse(readFileSync(claimPath, "utf-8"));
+        const ageMinutes = (Date.now() - new Date(claim.claimed_at).getTime()) / 60000;
+        const ttl = claim.ttl_minutes || DEFAULT_ITEM_CLAIM_TTL_MIN;
+
+        if (ageMinutes > ttl * 2) {
+          // Well past TTL — remove unconditionally
+          unlinkSync(claimPath);
+          swept++;
+          console.log(`[session-lock] Swept stale item claim: ${claim.session_id}, age ${ageMinutes.toFixed(1)}m (2x TTL=${ttl * 2}m)`);
+        } else if (ageMinutes > ttl) {
+          // Past TTL but within 2x — check if PID is dead
+          if (claim.pid && !isProcessRunning(claim.pid)) {
+            unlinkSync(claimPath);
+            swept++;
+            console.log(`[session-lock] Swept orphaned item claim: ${claim.session_id}, pid ${claim.pid} dead`);
+          }
+        }
+      } catch {
+        // Corrupted claim file — remove it
+        try { unlinkSync(claimPath); swept++; } catch {}
+      }
+    }
+  } catch {
+    // ITEM_CLAIM_DIR doesn't exist or unreadable — nothing to sweep
+  }
+  return swept;
+}